PortfolioOptimisers.jl julia-source-code.instructions.md

Julia Source Code Guidelines for PortfolioOptimisers.jl

Estimator, Algorithm, and Result Roles

These three abstract hierarchies form the backbone of the library. Understanding their distinct roles is critical for correct design.

• Estimators (<: AbstractEstimator):

  • User-facing. Compose algorithms and/or other estimators as fields.
  • Are the entry points for computation — all high-level API functions accept estimators.
  • May consume data (e.g., a returns matrix) and produce results or transformed data.
  • Example: Covariance, EmpiricalPrior, Denoise.

• Algorithms (<: AbstractAlgorithm):

  • Internal dispatch mechanism. Never called directly from user-facing APIs.
  • Modify or specialise the behaviour of an estimator they are stored in.
  • Must not contain data — only parameters that tune an algorithm's behaviour.
  • Example: FullMoment, SemiMoment, SpectralDenoise, Newton.

• Results (<: AbstractResult):

  • Returned by functions that consume estimators when the output is complex enough to warrant its own type (e.g., contains multiple arrays, metadata).
  • Can themselves be passed as inputs to further computations — functions must dispatch on both estimator and result types where this makes sense.
  • Example: LowOrderPrior, ClustersResult, OptimisationResult.

Type Definitions

• Abstract types:

  • Always prefix with Abstract (e.g., AbstractCovarianceEstimator).
  • Include comprehensive docstrings explaining their role in the type hierarchy.
  • List related types in the # Related section.
  • When subtypes must implement specific methods, document this in an # Interfaces section (see the docstring guide).

• Struct types:

  • Use @concrete from ConcreteStructs.jl — it auto-generates type parameters so struct MyType{T1, T2} boilerplate is not needed.
  • Use DocStringExtensions.TYPEDEF in the docstring header for struct types.
  • All fields must be documented using inline "$(field_dict[:key])" strings and reflected in the # Fields section via $(DocStringExtensions.FIELDS).
  • Call @define_pretty_show(TypeName) immediately after any new struct that should display nicely in the REPL (all estimators, algorithms, and results).
  • Every source file must end with an export statement listing all public symbols defined in that file.