Constraint packs and optimizer diagnostics

What a constraint pack is

A constraint pack (constraint_pack on the optimize request) is a structured bundle of limits beyond raw risk_settings. It is designed for:

• Auditability — stored on the portfolio document with numeric values that match what the server applied.
• Gradual rollout — some fields are informational on first-time optimization; others bind only in specific modes (e.g. rebalance).

v1 fields (conceptual):

• sector_caps — per-sector maximum portfolio weight, plus often a DEFAULT key interpreted as a per-name cap merged with max_position_size (via minimum of the two).
• vol_target_annual — expressed as a fraction (e.g. 0.12 for ~12% annualized vol). The service may rescale softmax temperature for CONFIDENCE_WEIGHTED and HYBRID_WEIGHTED strategies. This is not a full volatility-mandate optimizer with a covariance matrix—documentation in code describes it as a heuristic compared to a reference vol.
• max_portfolio_turnover_annual — cap on one-way annual turnover as a fraction of the portfolio. On initial optimize (no prior book), this may be diagnostic only; with prior_book_weights on rebalance, enforcement can blend the new book toward the prior so turnover fits the budget.
• covariance_model — reserved placeholder for future Σ integration; do not assume portfolio-wide risk model sizing from this field today.

Policy explanation

When a pack is compiled, DIONYSUS can attach a policy_explanation: short bullet strings describing which preset, quiz dimensions, and pack fields were used. This is for UX and compliance narratives—not a substitute for your firm’s own disclosures.

Optimizer diagnostics

optimizer_diagnostics on the response echoes what actually bound:

• Effective max_position_size after merging sector_caps.DEFAULT.
• Original vs effective softmax_temperature when a vol heuristic applied.
• binding_notes: human-readable lines such as “max_position_size binding: min(risk_settings, DEFAULT)” or sector-cap adjustments.

Use diagnostics when two runs differ and you need to see whether constraints, not markets, moved the result.

Practical tips

• If weights look too concentrated, check softmax temperature and vol target interactions—not only max position size.
• If sector labels on analysis documents are missing, named sector caps may not bite as you expect.

See also

• Rebalancing and turnover limits
• Portfolio optimization with DIONYSUS
• DIONYSUS position sizing, stops, and targets — how caps become dollars and shares
• DIONYSUS optimization troubleshooting — when diagnostics do not match intuition
• Optimization in the IRIS browser and API — BFF vs service URL
• Risk management fundamentals