JuMP model setup: private API
PortfolioOptimisers.process_model — Function
process_model(model::JuMP.Model, retcode::OptimisationSuccess)
process_model(model::JuMP.Model, retcode::OptimisationFailure)Read the portfolio weights of a solved JuMP model into a JuMPOptimisationSolution.
After a success the weights are the solved w divided by the solved k. A ratio objective solves for $k \boldsymbol{w}$, so the division gives weights on the scale of the budget. When k solves to zero the weights are the solved w unchanged. After a failure the weights are a vector of NaN, one for each weight, in the value type of the model.
Arguments
model::JuMP.Model: The optimised JuMP model.retcode: The return code,OptimisationSuccessorOptimisationFailure, that selects the method.
Returns
sol::JuMPOptimisationSolution: The solution that holds the weights.
Related
PortfolioOptimisers.optimise_JuMP_model! — Function
optimise_JuMP_model!(model::JuMP.Model, slv::Slv_VecSlv) -> JuMPResultSolve model with each solver of slv in turn, until one gives a solution that its check_sol accepts.
The loop guards three stages: JuMP.set_optimizer, JuMP.optimize! and JuMP.assert_is_solved_and_feasible. It does not guard set_solver_attributes. So an attribute that the solver refuses raises out of this function, the loop records no trial, and it tries no later solver. A misspelled attribute is an error of the configuration, not a failure of the solver, and the caller must see it.
Give each solver of a vector its own name. The name is the key of trials, and every solver has the default name "". Under one key, a later failure overwrites an earlier one. Two solvers that both fail at JuMP.set_optimizer leave one entry under the default names, and two entries under distinct names.
Algorithm
- For each solver of
slv, in order:- Attach the solver to
modelwithJuMP.set_optimizer. When that raises, record the error under:set_optimizerintrials[solver.name], and go to the next solver. - Set the attributes of the solver from its
settingswithset_solver_attributes. - Solve with
JuMP.optimize!. When that raises, record the error under:optimize!, and go to the next solver. - Check the solution with
JuMP.assert_is_solved_and_feasibleunder thecheck_solkeywords of the solver. When the check passes, setsuccesstotrueand stop the loop. Otherwise record the error under:assert_is_solved_and_feasible, the termination status of the solver under:termination_status, and thesettingsof the solver under:settings.
- Attach the solver to
- Build the
JuMPResultfromtrialsandsuccess. Its constructor warns whensuccessisfalse.
Arguments
model: The JuMP model to solve. After a success, it holds the solution of the solver that succeeded.slv: OneSolver, or a vector of them in the order to try.
Returns
res::JuMPResult: The failures of the solvers, and whether one solver succeeded.
Related
optimise_JuMP_model!(
model::Model,
opt::JuMPOptimisationEstimator
) -> Tuple{Union{OptimisationFailure{Dict{Union{AbstractString, Symbol}, AbstractDict{Symbol}}}, OptimisationSuccess{Dict{Union{AbstractString, Symbol}, AbstractDict{Symbol}}}}, JuMPOptimisationSolution{<:AbstractArray{var"#s166", N}} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}
optimise_JuMP_model!(
model::Model,
opt::JuMPOptimisationEstimator,
datatype::DataType
) -> Tuple{Union{OptimisationFailure{Dict{Union{AbstractString, Symbol}, AbstractDict{Symbol}}}, OptimisationSuccess{Dict{Union{AbstractString, Symbol}, AbstractDict{Symbol}}}}, JuMPOptimisationSolution{<:AbstractArray{var"#s166", N}} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}
Solve the JuMP model with each solver of opt.opt.slv in turn, until one gives an acceptable solution.
A solution is acceptable when JuMP reports it solved and feasible under the check_sol keywords of the solver, every weight is finite, and at least one weight is not zero. The fallback of the optimiser is not tried here.
Algorithm
- For each solver of
opt.opt.slv, in order:- Attach the solver to
model. When that raises, record the error under the name of the solver and go to the next solver. - Set the attributes of the solver from its
settings. - Solve. When that raises, record the error and go to the next solver.
- Check the solution with
JuMP.assert_is_solved_and_feasible, and read the weights. When every weight is finite and one weight is not zero, stop the loop. - Otherwise record the settings, the error of the check if there is one, the termination status and the solution summary under the name of the solver.
- Attach the solver to
- When a solver stopped the loop, the return code is an
OptimisationSuccess. Otherwise it is anOptimisationFailure. A warning fromfailed_solve_msggives one line for each failed stage of each solver, and states in words a status that makes the problem infeasible or unbounded. It points toresfor the full data. - Read the weights with
process_model.
Returns
(retcode, sol): The return code and theJuMPOptimisationSolution. Theresfield of the return code is aDictfrom the name of each solver that failed to what went wrong. The solver that succeeds adds no entry, so theresof a success on the first solver is empty.
Related
PortfolioOptimisers.set_initial_w! — Function
set_initial_w!(w::VecNum, wi::VecNum)
set_initial_w!(w::VecNum, ::Option{<:VecVecNum})Set the start values of the weight variables of the JuMP model.
The method for two vectors sets the start value of each weight variable to the matching entry of wi. nothing sets no start value. A vector of weight vectors, the anchors of a NearOptimalCentering sweep, sets no start value either. Any other type or arity is a MethodError.
Arguments
w::VecNum: Vector of JuMP weight variables.wi: Vector of start values,nothing, or a vector of weight vectors.
Validation
length(wi) == length(w). Otherwise aDimensionMismatchnames both lengths.
Returns
nothing.
Related
PortfolioOptimisers.set_w! — Function
set_w!(model::JuMP.Model, X::MatNum, wi::Option{<:VecNum_VecVecNum})Register the portfolio weight variables in the JuMP model, and set their start values from wi.
A vector wi sets one start value for each weight through set_initial_w!. A vector of weight vectors, which a NearOptimalCentering sweep passes as its anchors, and nothing set no start value.
JuMP formulation
Variables
w: $\boldsymbol{w}$, created free, with one entry for each column ofX.
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
Arguments
model::JuMP.Model: JuMP optimisation model.X::MatNum: Asset returns matrix, $T \times N$. The function reads only its number of columns.wi: Start values of the weights, ornothing.
Returns
nothing.
Related
PortfolioOptimisers.set_portfolio_returns! — Function
set_portfolio_returns!(model::JuMP.Model, X::MatNum; prefix::Symbol = Symbol(""))Register the portfolio return series $\mathbf{X} \boldsymbol{w}$ in the JuMP model, and return it.
A second call returns the registered series and builds nothing.
JuMP formulation
Variables
w: $\boldsymbol{w}$, read underprefixwithget_w.
Expressions
Xunderprefix: $\mathbf{X} \boldsymbol{w}$, a $T \times 1$ vector.
Where:
- $\mathbf{X}$: Returns matrix $T \times N$.
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
Arguments
model::JuMP.Model: JuMP optimisation model.X::MatNum: Asset returns matrix.prefix::Symbol: Model State namespace of the build. The empty default gives the bare key.
Returns
- The portfolio return series.
Related
PortfolioOptimisers.set_net_portfolio_returns! — Function
set_net_portfolio_returns!(model::JuMP.Model, X::MatNum; prefix::Symbol = Symbol(""))Register the portfolio return series net of fees in the JuMP model, and return it.
The model's :fees expression holds the per period terms l, s, tn and lq. They are rates for each period, so each observation pays them. The model's :one_time_fees expression holds the one-off terms fl, fs and flq, which the holding period pays one time, and :fee_fa names the clock they fall on. A nothing or FirstObservationFees clock takes them from the first observation alone, and an AmortisedFees clock spreads them evenly over the observation count of the fit. charge_fees states the same rule for values, and charge_one_time_fees applies it here. A second call returns the registered series and builds nothing. :fees and :one_time_fees are shared entries, so a nested build reads them under the bare key.
Algorithm
- When the series is registered under
prefix, return it. - Build the portfolio return series with
set_portfolio_returns!, givingXe. - When the model holds neither
:feesnor:one_time_fees, registerXeas the net series and return it. - Subtract
:fees, or zero when the model holds none, from each entry ofXe, givingnet. - When the model holds
:one_time_feesandnetis not empty, charge them on the clock:fee_fawithcharge_one_time_fees, over the countget_T. - Register
netand return it.
JuMP formulation
Expressions
net_Xunderprefix: $\hat{r}_t = \boldsymbol{x}_t^\intercal \boldsymbol{w} - f_r - c_t f_o$.
Where:
- $\boldsymbol{x}_t$: Asset returns for observation $t$, the $t$-th row of the returns matrix.
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $f_r$: Per period fee, the model's
:feesexpression. Each observation of the net return series pays it in full. It is zero when the model holds none. - $f_o$: One-off fee, the model's
:one_time_feesexpression. The holding period pays it one time. It is zero when the model holds none. - $c_t$: Charge fraction of observation $t$, the part of $f_o$ that the observation pays. Under a
nothingorFirstObservationFeesclock $c_1 = 1$ and $c_t = 0$ for $t > 1$. Under anAmortisedFeesclock $c_t = 1 / T$. - $T$: Number of observations.
Arguments
model::JuMP.Model: JuMP optimisation model.X::MatNum: Asset returns matrix.prefix::Symbol: Model State namespace of the build. The empty default gives the bare key.
Returns
- The net portfolio return series.
Related
PortfolioOptimisers.set_asset_returns_plus_one! — Function
set_asset_returns_plus_one!(model::JuMP.Model, X::MatNum; prefix::Symbol = Symbol(""))Register the gross asset returns $\mathbf{X} + 1$ in the JuMP model, and return them.
The value is the constant matrix X .+ 1, not a JuMP expression. The distributionally robust conditional value at risk measures the transport cost of its Wasserstein ambiguity ball against it. The gain side of that measure passes -X under a prefix of its own. A second call returns the registered matrix and builds nothing.
JuMP formulation
Expressions
Xap1underprefix: $\mathbf{X} + 1$, entry by entry.
Where:
- $\mathbf{X}$: Returns matrix $T \times N$.
Arguments
model::JuMP.Model: JuMP optimisation model.X::MatNum: Asset returns matrix.prefix::Symbol: Model State namespace of the build. The empty default gives the bare key.
Returns
- The gross asset returns matrix.
Related
PortfolioOptimisers.set_portfolio_drawdowns_plus_one! — Function
set_portfolio_drawdowns_plus_one!(model::JuMP.Model, X::MatNum; prefix::Symbol = Symbol(""))Register the drawdowns of each asset plus one in the JuMP model, and return them.
absolute_drawdown_arr takes the drawdown of each column of X on the cumulative sum of its returns, with the running peak seeded at zero. The value is a constant matrix, not a JuMP expression. The distributionally robust conditional drawdown at risk measures the transport cost of its Wasserstein ambiguity ball against it. A second call returns the registered matrix and builds nothing.
Mathematical definition
\[\begin{align} c_{t,i} &= \sum_{s=1}^{t} x_{s,i}\,, \\ D_{t,i} &= 1 + c_{t,i} - \max\left(0,\, \max_{s \leq t} c_{s,i}\right)\,. \end{align}\]
Where:
- $x_{s,i}$: The return of asset $i$ at observation $s$, an entry of
X. - $c_{t,i}$: The cumulative sum of the returns of asset $i$ up to observation $t$.
- $D_{t,i}$: The drawdown of asset $i$ at observation $t$, plus one. It is at most one.
JuMP formulation
Expressions
ddap1underprefix: the matrix of $D_{t,i}$, $T \times N$.
Where:
- $T$: Number of observations.
- $N$: Number of assets.
Arguments
model::JuMP.Model: JuMP optimisation model.X::MatNum: Asset returns matrix, $T \times N$.prefix::Symbol: Model State namespace of the build. The empty default gives the bare key.
Returns
- The matrix of asset drawdowns plus one.
Related