Struct Model 

pub struct Model {
    pub name: SmolStr,
    /* private fields */
}

The optimization model. Owns the expression arena, variable/parameter registries, constraints, and (optional) objective.

Model uses interior mutability so the builder API can take &self references.

Registries use RefCells. The expression arena uses synchronized interior mutability and isolated worker forks while large indexed families are prepared in parallel.

Fields

name: SmolStr

Implementations

impl Model

pub fn display_expr(&self, e: Expr<'_>) -> ExprDisplay<'_>

Display adapter for an expression handle, resolving variable names against this model.

pub fn display_expr_id(&self, id: ExprId) -> ExprDisplay<'_>

Display adapter for a raw ExprId (as stored in constraints and the objective).

pub fn display_constraint(&self, id: ConstraintId) -> ConstraintDisplay<'_>

Display adapter for one algebraic constraint.

pub fn display_objective(&self) -> ObjectiveDisplay<'_>

Display adapter for the objective (minimize <expr>/maximize <expr>/ feasibility/(no objective)).

pub fn display_soc(&self, id: SocConstraintId) -> SocDisplay<'_>

Display adapter for one second-order cone constraint.

pub fn display_sos(&self, id: impl Into<SosConstraintId>) -> SosDisplay<'_>

pub fn display_indicator( &self, id: impl Into<IndicatorConstraintId>, ) -> IndicatorDisplay<'_>

impl Model

pub fn new(name: impl Into<SmolStr>) -> Self

pub const fn id(&self) -> ModelId

Stable identity carried by this model’s expression handles and results.

pub fn variable_id(&self, name: &str) -> Option<VarId>

pub fn variable_handle(&self, id: VarId) -> Expr<'_>

Create a model-bound expression handle for an existing variable ID.

This is useful after an ID-preserving model transformation, since source and transformed models have distinct identities, so the source expression handle is not accepted by the transformed model or its solver result.

Panics

Panics if id is not registered on this model.

pub fn variables(&self) -> Ref<'_, Vec<Variable>>

pub fn arena(&self) -> ExprArenaSnapshot<'_>

Return an immutable copy-on-write snapshot of the expression arena.

The snapshot is cheap to create, but it is not live. Subsequent model mutations (including parameter rebinding) are not visible through a snapshot that is already held.

pub fn num_variables(&self) -> usize

pub fn describe_eval_error(&self, err: &EvalError) -> String

Render an EvalError using this model’s registered variable/parameter name instead of the bare numeric id it carries. Use it when surfacing an evaluation failure to a user.

pub fn fix(&self, e: Expr<'_>, value: f64) -> Result<(), ModelMismatchError>

Fix a single-variable expression to value. Convenience over Self::fix_var for handles from the variable! macro or crate::IndexedVar indexing.

Panics

Panics if e is not a bare variable handle from this model lineage, or on anything Self::fix_var rejects.

Errors

Returns ModelMismatchError if e belongs to another model.

pub fn fix_var(&self, id: VarId, value: f64)

Fix variable id to value by setting lb = ub = value.

VarId is a raw numeric index and carries no model provenance. Prefer Self::fix when an expression handle is available.

Panics

Panics if value is not a feasible fixing for the variable (non-finite, fractional on an integer domain, outside its bounds, or inside a semicontinuity gap), or if its bounds are embedded in a previously reformulated SOS or indicator row.

pub fn set_initial( &self, e: Expr<'_>, value: f64, ) -> Result<(), ModelMismatchError>

Set the initial (warm-start) value of a single-variable expression. The macro API has no bound-style syntax for warm starts, so this is the supported way to seed variable!-declared variables.

Panics

Panics if e is not a bare variable handle from this model lineage.

Errors

Returns ModelMismatchError if e belongs to another model.

pub fn unfix_var(&self, id: VarId, lb: f64, ub: f64)

Restore bounds on variable id. Pass f64::NEG_INFINITY / f64::INFINITY to restore an unbounded direction.

Panics

Panics if the variable belongs to an SOS or indicator constraint that has already been reformulated, because its bounds are embedded in rows.

pub fn set_param_idx<K, Q: Into<IndexKey>>( &self, params: &IndexedParam<'_, K>, key: Q, value: f64, ) -> Result<(), ModelMismatchError>

Re-bind the parameter at key of an indexed family to value. Takes effect on the next solve.

Panics

Panics if key is not present in the family.

Errors

Returns ModelMismatchError if params belongs to another model.

pub fn param_value_idx<K, Q: Into<IndexKey>>( &self, params: &IndexedParam<'_, K>, key: Q, ) -> Result<Option<f64>, ModelMismatchError>

Current value bound to the parameter at key of an indexed family. Returns Ok(None) if the key is absent and ModelMismatchError if the family belongs to another model.

Errors

Returns ModelMismatchError if params belongs to another model.

pub fn set_param( &self, p: Expr<'_>, value: f64, ) -> Result<(), ModelMismatchError>

Re-bind the parameter referenced by handle p to value.

Panics

Panics if p is not a bare parameter handle from this model lineage (one returned by the param! macro).

Errors

Returns ModelMismatchError if p belongs to another model.

pub fn set_param_id(&self, id: ParamId, value: f64)

Re-bind parameter id to value. Takes effect on the next solve.

The value is stored only in the expression arena (its single source of truth); extraction and evaluation read it from there. ParamId is a raw numeric index and carries no model provenance; prefer Self::set_param when an expression handle is available.

pub fn param_value(&self, id: ParamId) -> f64

Current value bound to parameter id.

Panics

Panics if id does not belong to a parameter registered on this model.

pub fn param_value_of( &self, p: Expr<'_>, ) -> Result<Option<f64>, ModelMismatchError>

Current value of the parameter referenced by handle p. Returns Ok(None) if p is not a bare parameter handle and ModelMismatchError if it belongs to another model.

Errors

Returns ModelMismatchError if p belongs to another model.

pub fn parameter_id(&self, name: &str) -> Option<ParamId>

pub fn parameters(&self) -> Ref<'_, Vec<Parameter>>

pub fn num_parameters(&self) -> usize

pub fn add_constraints<'a, I>(&'a self, items: I)

where I: IntoIterator<Item = (SmolStr, ConstraintExpr<'a>)>,

Bulk-register constraints. Each entry is (name, ConstraintExpr). Useful with .par_iter().map(...).collect() style construction.

pub fn constraints(&self) -> ModelConstraints<'_>

Unified view of every algebraic, explicit SOC, SOS, and indicator constraint declared on this model.

pub fn num_constraints(&self) -> usize

Total number of algebraic, SOC, SOS, and indicator constraints.

pub fn constraint_id(&self, name: &str) -> Option<ConstraintId>

pub fn constraint_handle(&self, name: &str) -> Option<ConstraintHandle>

Return a model-bound handle for a named algebraic constraint.

pub fn constraint_handle_from_id( &self, id: ConstraintId, ) -> Option<ConstraintHandle>

Bind a raw algebraic constraint ID to this model.

pub fn add_soc_constraint<'a>( &'a self, name: impl Into<SmolStr>, terms: impl IntoIterator<Item = Expr<'a>>, bound: Expr<'a>, ) -> SocConstraintHandle

Register the explicit second-order cone constraint ||terms||_2 <= bound.

Every member of terms and the bound must be affine; the bound is additionally constrained to be nonnegative by the cone itself, so backends emit a bound >= 0 side condition where needed.

Panics

Panics if a SOC constraint with the same name is already registered, if terms is empty, if any term or the bound is not affine, or if the count exceeds u32::MAX.

pub fn soc_constraints(&self) -> Ref<'_, Vec<SocConstraint>>

Typed explicit-SOC registry for specialized backend passes.

Use Self::constraints when inspecting constraints generically. This accessor exists so performance-sensitive translators can keep a homogeneous borrow scoped to one conic pass.

pub fn num_soc_constraints(&self) -> usize

pub fn soc_constraint_id(&self, name: &str) -> Option<SocConstraintId>

pub fn soc_constraint_handle(&self, name: &str) -> Option<SocConstraintHandle>

Return a model-bound handle for a named explicit SOC constraint.

pub fn soc_constraint_handle_from_id( &self, id: SocConstraintId, ) -> Option<SocConstraintHandle>

Bind a raw explicit-SOC constraint ID to this model.

pub fn has_cones(&self) -> bool

Whether the model carries any explicit second-order cone constraints.

pub fn add_sos_constraint<'a>( &'a self, name: impl Into<SmolStr>, sos_type: SosType, members: impl IntoIterator<Item = (Expr<'a>, f64)>, ) -> SosConstraintHandle<'a>

Register an explicit SOS1 or SOS2 constraint. Members must be bare variables belonging to this model and have finite, unique weights.

Panics

Panics when a member belongs to another model, is not a bare variable, or the name, members, variables, or weights violate SOS invariants.

pub fn add_sos_constraint_auto_weights<'a>( &'a self, name: impl Into<SmolStr>, sos_type: SosType, variables: impl IntoIterator<Item = Expr<'a>>, ) -> SosConstraintHandle<'a>

Register an SOS1 or SOS2 constraint with consecutive positional weights 1, 2, ... inferred from the member order.

This is a convenience for models where the ordering is already represented by the iterator order. Use Self::add_sos_constraint when the weights are meaningful values that should be preserved.

Panics

Panics under the same conditions as Self::add_sos_constraint, or when the iterator contains more than u32::MAX members.

pub fn sos_constraints(&self) -> Ref<'_, Vec<SosConstraint>>

pub fn num_sos_constraints(&self) -> usize

pub fn sos_constraint_id(&self, name: &str) -> Option<SosConstraintId>

pub fn has_sos_constraints(&self) -> bool

pub fn has_active_sos_constraints(&self) -> bool

Whether at least one SOS constraint still requires native backend handling. Reformulation retains source SOS entries but marks them inactive so their stable IDs and provenance are preserved.

pub fn add_indicator_constraint<'a>( &'a self, name: impl Into<SmolStr>, trigger: Expr<'a>, active_value: bool, consequent: ConstraintExpr<'a>, ) -> IndicatorConstraintHandle<'a>

Register trigger == active_value => consequent.

pub fn indicator_constraints(&self) -> Ref<'_, Vec<IndicatorConstraint>>

pub fn num_indicator_constraints(&self) -> usize

pub fn indicator_constraint_id( &self, name: &str, ) -> Option<IndicatorConstraintId>

pub fn has_indicator_constraints(&self) -> bool

pub fn has_active_indicator_constraints(&self) -> bool

pub fn is_feasibility(&self) -> bool

Whether feasibility was declared explicitly via objective!(m, Feasibility), as opposed to a model that simply has no objective set.

pub fn ensure_objective_declared(&self) -> Result<()>

Ensure the model has a solve direction declared: either an objective (Min/Max) or an explicit feasibility problem.

Errors

Returns Error::NoObjective if neither an objective nor objective!(m, Feasibility) was declared.

pub fn objective(&self) -> Ref<'_, Option<Objective>>

pub fn try_objective(&self) -> Result<Objective>

Try to get a cloned copy of the objective.

Errors

Returns Error::NoObjective if no objective is set on this model.

pub fn kind(&self) -> ModelKind

Infer the ModelKind from current variables and expressions. Result is cached and invalidated whenever variables, constraints, or the objective change.

The decision ladder, top-down (any integer variable picks the MI* column):

1. any nonlinear expression (objective or constraint) -> NLP
2. any quadratic constraint not recognized by the structural SOC predicate -> QCP
3. cones present (explicit or detected) -> SOCP
4. quadratic objective -> QP
5. otherwise -> LP

impl Model

pub fn to_reformulated_indicator_constraint_model( &self, id: IndicatorConstraintId, options: IndicatorReformulationOptions, ) -> Result<ReformulatedModel, ReformulationError>

Clone the model and replace one indicator while preserving its source ID.

Errors

Returns a reformulation error if the ID, body, bounds, or options are invalid.

pub fn reformulate_indicator_constraint( &self, id: IndicatorConstraintId, options: IndicatorReformulationOptions, ) -> Result<Option<IndicatorReformulationArtifacts>, ReformulationError>

Replace one indicator in place after validating its complete reformulation. Returns None if the source indicator is already inactive.

Errors

Returns an error before mutation if the selected indicator is invalid.

pub fn to_reformulated_indicator_model( &self, options: IndicatorReformulationOptions, ) -> Result<ReformulatedModel, ReformulationError>

Clone the model and replace every active indicator in ID order.

Errors

Returns an error without producing a partial clone if any indicator is invalid.

pub fn reformulate_indicators( &self, options: IndicatorReformulationOptions, ) -> Result<Vec<IndicatorReformulationArtifacts>, ReformulationError>

Replace every active indicator after validating the complete model plan.

Errors

Returns an error without mutating the model if any indicator is invalid.

pub fn indicator_reformulations( &self, ) -> Ref<'_, [IndicatorReformulationArtifacts]>

Complete indicator reformulation history retained by this model.

impl Model

pub fn to_reformulated_sos_constraint_model( &self, id: SosConstraintId, options: SosReformulationOptions, ) -> Result<ReformulatedModel, ReformulationError>

Clone this model and replace one active SOS constraint with an MILP formulation. An already-inactive constraint is copied unchanged. The source model remains mutable and unchanged.

Errors

Returns ReformulationError for an unknown ID, invalid fallback Big-M, or an unbounded member side without a fallback.

pub fn reformulate_sos_constraint( &self, id: SosConstraintId, options: SosReformulationOptions, ) -> Result<Option<SosReformulationArtifacts>, ReformulationError>

Replace one active SOS constraint on this model without cloning it. Existing variable and parameter expression handles remain valid because registries are only appended and all existing IDs are preserved.

Returns Ok(None) when the source SOS is already inactive. Bounds of all source members become immutable after reformulation because their current values are embedded in the generated Big-M rows.

Errors

Returns ReformulationError before modifying the model when the ID, fallback Big-M, or required member bounds are invalid.

pub fn to_reformulated_sos_model( &self, options: SosReformulationOptions, ) -> Result<ReformulatedModel, ReformulationError>

Clone this model and replace every active SOS constraint with an MILP formulation, in stable SosConstraintId order. The source model remains mutable and unchanged.

Errors

Returns ReformulationError when the fallback Big-M is invalid or an active member has an unbounded side without a fallback. No partial transformed model is returned.

pub fn reformulate_sos( &self, options: SosReformulationOptions, ) -> Result<Vec<SosReformulationArtifacts>, ReformulationError>

Replace every active SOS constraint on this model without cloning it. This is the memory-efficient alternative to Self::to_reformulated_sos_model when the original native-SOS form is no longer needed.

Errors

Returns ReformulationError before modifying the model when the fallback Big-M or any required member bound is invalid.

Reformulation history remains available through Self::sos_reformulations after the returned artifacts are dropped.

pub fn sos_reformulations(&self) -> Ref<'_, [SosReformulationArtifacts]>

Complete SOS reformulation history accumulated by this model.

The returned guard dereferences to a slice of artifacts. This is useful after an in-place reformulation when the Vec returned by Self::reformulate_sos is no longer available.

Trait Implementations

impl AsRef<Model> for ReformulatedModel

fn as_ref(&self) -> &Model

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for Model

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Model

Pretty-print the whole model as readable algebra:

Model 'diet' (LP)
minimize 3 x + 4 y
s.t.
  c1: x + 2 y <= 14
  c2: 3 x - y >= 0
vars
  x >= 0
  y >= 0

Sections (s.t., vars, params) are omitted when empty. The objective line is omitted when no objective was declared.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.