6

Base

01_Base.jl implements the most basal symbols used in PortfolioOptimisers.jl.

Base abstract types

PortfolioOptimisers.jl is designed in a deliberately structured and hierarchical way. This enables us to create self-contained, independent, composable processes. These abstract types form the basis of this hierarchy.

PortfolioOptimisers.AbstractEstimator Type

julia

abstract type AbstractEstimator end

Abstract supertype for all estimator types in PortfolioOptimisers.jl.

All custom estimators (e.g., for moments, risk, or priors) should subtype AbstractEstimator.

This enables a consistent interface for estimation routines throughout the package.

Estimators consume data to estimate parameters or models. Some estimators may utilise different algorithms. These can range from simple implementation details that don't change the result much but may have different characteristics, to entirely different methodologies or algorithms yielding different results. Results are often encapsulated in result types, this simplifies dispatch and usage.

Related

PortfolioOptimisers.AbstractAlgorithm Type

julia

abstract type AbstractAlgorithm end

Abstract supertype for all algorithm types in PortfolioOptimisers.jl.

All algorithms (e.g., solvers, metaheuristics) should subtype AbstractAlgorithm.

This allows for flexible extension and dispatch of routines.

Algorithms are often used by estimators to perform specific tasks. These can be in the form of simple implementation details or entirely different procedures.

Related

PortfolioOptimisers.AbstractResult Type

julia

abstract type AbstractResult end

Abstract supertype for all result types returned by optimizers in PortfolioOptimisers.jl.

All result objects (e.g., optimization outputs, solution summaries) should subtype AbstractResult.

This ensures a unified interface for accessing results across different estimators and algorithms.

Result types encapsulate the outcomes of estimators. This makes dispatch and usage more straightforward, especially when the results encapsulate a variety of information.

Related

Pretty printing

PortfolioOptimisers.jl's types tend to contain quite a lot of information, these functions enable pretty printing so they are easier to interpret.

PortfolioOptimisers.@define_pretty_show Macro

julia

@define_pretty_show(T)

Macro to define a custom pretty-printing Base.show method for types in PortfolioOptimisers.jl.

This macro generates a show method that displays the type name and all fields in a readable, aligned format. For fields that are themselves custom types or collections, the macro recursively applies pretty-printing for nested structures. Handles compact and multiline IO contexts gracefully.

Arguments

T: The type for which to define the pretty-printing method.

Returns

Defines a Base.show(io::IO, obj::T) method for the given type.

Details

Prints the type name and all fields with aligned labels.
Recursively pretty-prints nested custom types and collections.
Handles compact and multiline IO contexts.
Displays matrix/vector fields with their size and type.
Skips fields that are not present or are nothing.

Related

PortfolioOptimisers.has_pretty_show_method Function

julia

has_pretty_show_method(::Any)

Default method indicating whether a type has a custom pretty-printing show method.

Overloading this method to return true indicates that type already has a custom pretty-printing method.

Arguments

::Any: Any type.

Returns

flag::Bool: false by default, indicating no custom pretty-printing method.

Related

@define_pretty_show

Error types

Many of the types defined in PortfolioOptimisers.jl make use of extensive data validation to ensure values meet various criteria. This simplifies the implementation of methods, and improves performance and by delegating as many checks as possible to variable instantiation. In cases where validation cannot be performed at variable instantiation, they are performed as soon as possible within functions.

PortfolioOptimisers.jl aims to catch potential data validation issues as soon as possible and in an informative manner, in order to do so it makes use of a few custom error types.

PortfolioOptimisers.PortfolioOptimisersError Type

julia

abstract type PortfolioOptimisersError <: Exception end

Abstract supertype for all custom exception types in PortfolioOptimisers.jl.

All error types specific to PortfolioOptimisers.jl should subtype PortfolioOptimisersError. This enables consistent error handling and dispatch throughout the package.

Related Types

PortfolioOptimisers.IsNothingError Type

julia

struct IsNothingError{T1} <: PortfolioOptimisersError
    msg::T1
end

Exception type thrown when an argument or value is unexpectedly nothing.

Fields

msg: Error message describing the condition that triggered the exception.

Constructors

julia

IsNothingError(msg)

Arguments correspond to the fields above.

Examples

julia

julia> throw(IsNothingError("Input data must not be nothing"))
ERROR: IsNothingError: Input data must not be nothing
Stacktrace:
 [1] top-level scope
   @ none:1

Related

PortfolioOptimisers.IsEmptyError Type

julia

struct IsEmptyError{T1} <: PortfolioOptimisersError
    msg::T1
end

Exception type thrown when an argument or value is unexpectedly empty.

Fields

msg: Error message describing the condition that triggered the exception.

Constructors

julia

IsEmptyError(msg)

Arguments correspond to the fields above.

Examples

julia

julia> throw(IsEmptyError("Input array must not be empty"))
ERROR: IsEmptyError: Input array must not be empty
Stacktrace:
 [1] top-level scope
   @ none:1

Related

PortfolioOptimisers.IsNonFiniteError Type

julia

struct IsNonFiniteError{T1} <: PortfolioOptimisersError
    msg::T1
end

Exception type thrown when an argument or value is unexpectedly non-finite (e.g., contains NaN or Inf).

Fields

msg: Error message describing the condition that triggered the exception.

Constructors

julia

IsNonFiniteError(msg)

Arguments correspond to the fields above.

Examples

julia

julia> throw(IsNonFiniteError("Input array contains non-finite values"))
ERROR: IsNonFiniteError: Input array contains non-finite values
Stacktrace:
 [1] top-level scope
   @ none:1

Related

Utility types

Custom types are the bread and butter of PorfolioOptimisers.jl, the following types non-specific and used throughout the library.

PortfolioOptimisers.VecScalar Type

julia

struct VecScalar{T1, T2} <: AbstractResult
    v::T1
    s::T2
end

Represents a composite result containing a vector and a scalar in PortfolioOptimisers.jl.

Encapsulates a vector and a scalar value, commonly used for storing results that combine both types of data (e.g., weighted statistics, risk measures).

Fields

v: Vector value.
s: Scalar value.

Constructors

julia

VecScalar(; v::VecNum, s::Number)

Keyword arguments correspond to the fields above.

Validation

v: !isempty(v) and all(isfinite, v).
s: isfinite(s).

Examples

julia

julia> VecScalar([1.0, 2.0, 3.0], 4.2)
VecScalar
  v ┼ Vector{Float64}: [1.0, 2.0, 3.0]
  s ┴ Float64: 4.2

Related

Base type aliases

PortfolioOptimisers.jl heavily relies on Julia's dispatch and type system to ensure data validity. Many custom types and functions/methods can accept different data types. These can be represented as type unions, many of which are used throughout the library. The following type aliases centralise these union definitions, as well as improving correctness and maintainability.

PortfolioOptimisers.Option Type

julia

const Option{T} = Union{Nothing, T}

Alias for an optional value of type T, which may be nothing.

Related Types

EstValType

PortfolioOptimisers.VecNum Type

julia

const VecNum = Union{<:AbstractVector{<:Union{<:Number, <:AbstractJuMPScalar}}}

Alias for an abstract vector of numeric types or JuMP scalar types.

Related Types

PortfolioOptimisers.VecInt Type

julia

const VecInt = Union{<:AbstractVector{<:Integer}}

Alias for an abstract vector of integer types.

Related Types

PortfolioOptimisers.MatNum Type

julia

const MatNum = Union{<:AbstractMatrix{<:Union{<:Number, <:AbstractJuMPScalar}}}

Alias for an abstract matrix of numeric types or JuMP scalar types.

Related Types

PortfolioOptimisers.ArrNum Type

julia

const ArrNum = Union{<:AbstractArray{<:Union{<:Number, <:AbstractJuMPScalar}}}

Alias for an abstract array of numeric types or JuMP scalar types.

Related Types

PortfolioOptimisers.Num_VecNum Type

julia

const Num_VecNum = Union{<:Number, <:VecNum}

Alias for a union of a numeric type or an abstract vector of numeric types.

Related Types

PortfolioOptimisers.Num_ArrNum Type

julia

const Num_ArrNum = Union{<:Number, <:ArrNum}

Alias for a union of a numeric type or an abstract array of numeric types.

Related Types

PortfolioOptimisers.PairStrNum Type

julia

const PairStrNum = Pair{<:AbstractString, <:Number}

Alias for a pair consisting of an abstract string and a numeric type.

Related Types

PortfolioOptimisers.DictStrNum Type

julia

const DictStrNum = AbstractDict{<:AbstractString, <:Number}

Alias for an abstract dictionary with string keys and numeric values.

Related Types

PortfolioOptimisers.MultiEstValType Type

julia

const MultiEstValType = Union{<:DictStrNum, <:AbstractVector{<:PairStrNum}}

Alias for a union of a dictionary with string keys and numeric values, or a vector of string-number pairs.

Related Types

PortfolioOptimisers.EstValType Type

julia

const EstValType = Union{<:Num_VecNum, <:PairStrNum, <:MultiEstValType}

Alias for a union of numeric, vector of numeric, string-number pair, or multi-estimator value types.

Related Types

PortfolioOptimisers.Str_Expr Type

julia

const Str_Expr = Union{<:AbstractString, Expr}

Alias for a union of abstract string or Julia expression.

Related Types

PortfolioOptimisers.VecStr_Expr Type

julia

const VecStr_Expr = AbstractVector{<:Str_Expr}

Alias for an abstract vector of strings or Julia expressions.

Related Types

PortfolioOptimisers.EqnType Type

julia

const EqnType = Union{<:AbstractString, Expr, <:VecStr_Expr}

Alias for a union of string, Julia expression, or vector of strings/expressions.

Related Types

PortfolioOptimisers.VecVecNum Type

julia

const VecVecNum = AbstractVector{<:VecNum}

Alias for an abstract vector of numeric vectors.

Related Types

PortfolioOptimisers.VecVecInt Type

julia

const VecVecInt = AbstractVector{<:VecInt}

Alias for an abstract vector of integer vectors.

Related Types

VecInt

PortfolioOptimisers.VecMatNum Type

julia

const VecMatNum = AbstractVector{<:MatNum}

Alias for an abstract vector of numeric matrices.

Related Types

PortfolioOptimisers.VecStr Type

julia

const VecStr = Union{<:AbstractVector{<:AbstractString}}

Alias for an abstract vector of strings.

Related Types

PortfolioOptimisers.VecPair Type

julia

const VecPair = AbstractVector{<:Pair}

Alias for an abstract vector of pairs.

Related Types

PairStrNum

PortfolioOptimisers.VecJuMPScalar Type

julia

const VecJuMPScalar = Union{<:AbstractVector{<:AbstractJuMPScalar}}

Alias for an abstract vector of JuMP scalar types.

Related Types

VecNum

PortfolioOptimisers.MatNum_VecMatNum Type

julia

const MatNum_VecMatNum = Union{<:MatNum, <:VecMatNum}

Alias for a union of a numeric matrix or a vector of numeric matrices.

Related Types

PortfolioOptimisers.Int_VecInt Type

julia

const Int_VecInt = Union{<:Integer, <:VecInt}

Alias for a union of an integer or a vector of integers.

Related Types

VecInt

PortfolioOptimisers.VecNum_VecVecNum Type

julia

const VecNum_VecVecNum = Union{<:VecNum, <:VecVecNum}

Alias for a union of a numeric vector or a vector of numeric vectors.

Related Types

PortfolioOptimisers.VecDate Type

julia

const VecDate = AbstractVector{<:Dates.AbstractTime}

Alias for an abstract vector of date or time types.

Related Types

PortfolioOptimisers.Dict_Vec Type

julia

const Dict_Vec = Union{<:AbstractDict, <:AbstractVector}

Alias for a union of an abstract dictionary or an abstract vector.

Related Types

PortfolioOptimisers.Sym_Str Type

julia

const Sym_Str = Union{Symbol, <:AbstractString}

Alias for a union of a symbol or an abstract string.

Related Types

VecStr

PortfolioOptimisers.Str_Vec Type

julia

const Str_Vec = Union{<:AbstractString, <:AbstractVector}

Alias for a union of an abstract string or an abstract vector.

Related Types

PortfolioOptimisers.Num_VecNum_VecScalar Type

julia

const Num_VecNum_VecScalar = Union{<:Num_VecNum, <:VecScalar}

Alias for a union of a numeric type, a vector of numeric types, or a VecScalar result.

Related Types

PortfolioOptimisers.Num_ArrNum_VecScalar Type

julia

const Num_ArrNum_VecScalar = Union{<:Num_ArrNum, <:VecScalar}

Alias for a union of a numeric type, an array of numeric types, or a VecScalar result.

Related Types