Struct ParametricInstance 

pub struct ParametricInstance {
    pub description: Option<Description>,
    pub annotations: HashMap<String, String>,
    /* private fields */
}

Optimization problem instance with parameters

Mathematical operations

ParametricInstance owns the same root operations as Instance and also owns the parameter-specialization operation. Parameter IDs share the VariableID namespace with decision variables, so only the enclosing parametric instance can interpret an expression reference as a decision variable or a parameter.

Self::with_parameters applies a parameter assignment to produce a concrete Instance. This is a root operation: it substitutes parameter values out of every expression-bearing component while preserving structural constraint families whose member IDs must already be real decision variables.

Invariants

• Self::decision_variables owns the DecisionVariableTable: row IDs, decision-variable modeling labels, and fixed values share one table owner.
• The decision-variable table rejects labels or fixed values for unknown variable IDs, and fixed values must satisfy the corresponding row’s kind/bound.
• Self::parameters owns the parameter ID universe and parameter modeling labels through ParameterTable. Parameter IDs intentionally use VariableID rather than a separate ParameterID, because algebraic expressions cannot distinguish decision-variable references from parameter references without the enclosing root.
• Self::decision_variables and Self::parameters together contain every ID that may appear in the objective, output objective, regular/indicator constraint bodies, named functions, and dependency RHS expressions.
• The IDs of Self::decision_variables and Self::parameters are disjoint sets. This shared-namespace invariant is host-level state and is validated by ParametricInstance::builder / protobuf parsing, not by ParameterTable alone.
• The keys of Self::constraints and Self::removed_constraints are disjoint sets.
• The keys of Self::decision_variable_dependency must be in Self::decision_variables, but must NOT be used in the active objective or active constraints. The RHS expressions of Self::decision_variable_dependency may reference IDs from Self::decision_variables or Self::parameters, and may not reference undefined IDs. Parameter IDs in RHS expressions are evaluated by Self::with_parameters.
• Self::output_objective has the same atomic sense/function/optimality semantics as Instance::output_objective. Its function may reference decision-variable or parameter IDs, including fixed, dependent, or otherwise inactive decision variables. Parameter references are specialized by Self::with_parameters before the pair is installed on the resulting Instance.
• Decision variables are classified into mutually exclusive roles:
  • used: Variable IDs appearing in the active objective or active constraints
  • fixed: Variable IDs present in Self::fixed_decision_variable_values and not used
  • dependent: Keys of decision_variable_dependency that are not used or fixed
• DecisionVariableUsage is the reverse-usage index for used decision variables only.
• Self::named_functions is keyed by the table-owned NamedFunctionID; named-function rows do not carry IDs.
• Self::named_functions may contain fixed or dependent decision-variable IDs (like removed_constraints) and may also reference parameter IDs. Every referenced ID must be registered in either Self::decision_variables or Self::parameters, but decision-variable IDs appearing only in named functions are NOT included in the “used” set calculation.
• Modeling-label and constraint-context sidecars are owned by their corresponding top-level table or collection; every label/context ID must refer to an existing decision variable, parameter, named function, or active/removed constraint in that owner. Parameter labels are owned by ParameterTable; parameter IDs are not valid variable-label IDs.
• Fixed decision-variable values are owned by DecisionVariableTable. The root ParametricInstance owns the host-level invariant that fixed IDs are disjoint from solver-used and dependent variables, and from parameter IDs via the shared namespace rule.

Special-constraint invariants

The same special-constraint invariants apply as on Instance, with one key difference: function bodies in indicator and regular constraints may reference parameter IDs (which are substituted via Self::with_parameters), but structural variable positions cannot — they must be real decision variables. Specifically:

• For every active or removed crate::IndicatorConstraint, the indicator_variable is registered in Self::decision_variables (not Self::parameters) and has Kind::Binary. The function body may reference any defined variable or parameter.
• For every active or removed crate::OneHotConstraint, every member of variables is registered in Self::decision_variables and has Kind::Binary.
• For every active or removed crate::Sos1Constraint, variables is non-empty and every member is registered in Self::decision_variables.
• The constraint id-disjointness invariants (active vs. removed, per kind) match Instance.

These invariants are enforced at every construction or mutation entry point: ParametricInstance::builder (which mirrors Instance::builder and accepts active maps for all three kinds, plus removed maps for regular and indicator constraints, validating each), and the post-construction setters Self::add_constraint / Self::add_indicator_constraint / Self::add_one_hot_constraint / Self::add_sos1_constraint.

Self::with_parameters partially evaluates parameter IDs out of every expression that could contain one when materializing a parametric instance into an Instance: the active objective, output objective, active and removed regular constraint bodies, active and removed indicator constraint function bodies, named functions, and decision_variable_dependency RHS expressions. OneHot/SOS1 collections (active and removed) pass through unchanged because their variable sets are required to be real decision variables at construction time. The resulting Instance satisfies its own (stricter) invariants — no parameter IDs survive anywhere.

Fields

description: Option<Description>

annotations: HashMap<String, String>

User-defined or third-party extension annotations.

OMMX-reserved metadata is represented by explicit fields such as Self::description.

Implementations

impl ParametricInstance

pub fn with_parameters(self, parameters: Parameters) -> Result<Instance>

Materialize every parameter into an Instance.

Postconditions

Materialization removes parameter IDs from both active and output objectives. An existing output objective remains explicit even if specialization makes it structurally equal to the active objective.

use ommx::{
    linear, v1::{Parameters, State}, ATol, Constraint, ConstraintID,
    DecisionVariable, Evaluate, Function, Instance, Sense, VariableID,
};
use std::collections::{BTreeMap, HashMap};

let variable = VariableID::from(1);
let source = Instance::builder()
    .sense(Sense::Minimize)
    .objective(Function::from(linear!(1)))
    .decision_variables(BTreeMap::from([(variable, DecisionVariable::binary())]))
    .constraints(BTreeMap::from([(
        ConstraintID::from(1),
        Constraint::equal_to_zero(Function::from(linear!(1))),
    )]))
    .build()
    .unwrap();
let parametric = source.uniform_penalty_method().unwrap();
let penalty = *parametric.parameters().keys().next().unwrap();
let mut parameters = Parameters::default();
parameters.entries.insert(penalty.into_inner(), 2.0);
let instance = parametric.with_parameters(parameters).unwrap();

assert!(instance.objective().required_ids().contains(&variable));
assert!(!instance.objective().required_ids().contains(&penalty));
assert_eq!(instance.output_objective().unwrap().sense(), Sense::Minimize);
assert!(!instance.output_objective().unwrap().preserves_optimality());
let solution = instance
    .evaluate(&State::from(HashMap::from([(1, 0.0)])), ATol::default())
    .unwrap();
assert_eq!(*solution.objective(), 0.0);

impl ParametricInstance

pub fn format_summary(&self) -> String

Format a compact, context-aware summary of this parametric instance.

This is intended for user-facing print(instance) / Display output. It resolves decision-variable and parameter labels through the parametric instance while keeping large expressions bounded.

pub fn format_function(&self, function: &Function) -> Result<String>

Format a function using this parametric instance’s decision-variable and parameter modeling labels.

This validates that every ID referenced by function belongs to exactly one of the decision-variable table or parameter table before applying any output budget.

pub fn format_function_with( &self, function: &Function, opts: FunctionFormatOptions, ) -> Result<FormattedFunction>

Format a function using this parametric instance’s decision-variable and parameter modeling labels and explicit output limits.

An ID that resolves as both a decision variable and a parameter, or as neither, is rejected before any term or character truncation is applied.

impl ParametricInstance

pub fn new( sense: Sense, objective: Function, decision_variables: BTreeMap<VariableID, DecisionVariable>, parameters: ParameterTable, constraints: BTreeMap<ConstraintID, Constraint>, ) -> Result<Self>

impl ParametricInstance

pub fn builder() -> ParametricInstanceBuilder

Creates a new ParametricInstanceBuilder.

impl ParametricInstance

pub fn to_v1_bytes(&self) -> Result<Vec<u8>>

Serialize this parametric instance using the v1 wire format.

Errors

ommx.v1.ParametricInstance cannot represent the presence of a ParametricInstance::output_objective, even when it currently matches the active objective.

use ommx::{linear, DecisionVariable, Function, Instance, ParametricInstance, Sense, VariableID};
use std::collections::BTreeMap;

let mut source = Instance::builder()
    .sense(Sense::Maximize)
    .objective(Function::from(linear!(1)))
    .decision_variables(BTreeMap::from([(
        VariableID::from(1),
        DecisionVariable::binary(),
    )]))
    .constraints(BTreeMap::new())
    .build()
    .unwrap();
assert!(source.convert_active_objective(Sense::Minimize));
assert!(source.convert_active_objective(Sense::Maximize));
let instance = ParametricInstance::from(source);
assert_eq!(instance.output_objective().unwrap().function(), instance.objective());

assert!(instance.to_v1_bytes().is_err());

pub fn to_v2_bytes(&self) -> Vec<u8>

Serialize this parametric instance using the v2 wire format.

Postconditions

v2 serialization round-trips the parametric output objective.

use ommx::{linear, DecisionVariable, Function, Instance, ParametricInstance, Sense, VariableID};
use std::collections::BTreeMap;

let mut source = Instance::builder()
    .sense(Sense::Maximize)
    .objective(Function::from(linear!(1)))
    .decision_variables(BTreeMap::from([(
        VariableID::from(1),
        DecisionVariable::binary(),
    )]))
    .constraints(BTreeMap::new())
    .build()
    .unwrap();
assert!(source.convert_active_objective(Sense::Minimize));
let instance = ParametricInstance::from(source);

let restored = ParametricInstance::from_v2_bytes(&instance.to_v2_bytes()).unwrap();
assert_eq!(restored.output_objective().unwrap().sense(), Sense::Maximize);
assert_eq!(restored, instance);

pub fn from_v1_bytes(bytes: &[u8]) -> Result<Self>

pub fn from_v2_bytes(bytes: &[u8]) -> Result<Self>

impl ParametricInstance

pub fn add_constraint( &mut self, constraint: Constraint, context: ConstraintContext, ) -> Result<ConstraintID>

Insert a new constraint with its context, picking an unused id.

Mirrors Instance::add_constraint for parametric instances. Returns the newly assigned ConstraintID. The context is drained into the per-constraint ConstraintContextStore; pass ConstraintContext::default for an unannotated constraint.

All IDs referenced by the constraint must already be present in either decision_variables or parameters, and must not be substitution- dependency keys.

pub fn add_indicator_constraint( &mut self, constraint: IndicatorConstraint, context: ConstraintContext, ) -> Result<IndicatorConstraintID>

Insert a new indicator constraint with its context, picking an unused id.

Mirrors Instance::add_indicator_constraint for parametric instances. The function body may reference either decision variables or parameters, but the indicator variable itself must be a binary decision variable — substitution cannot replace a structural variable position, and the indicator semantics require Kind::Binary.

pub fn add_one_hot_constraint( &mut self, constraint: OneHotConstraint, context: ConstraintContext, ) -> Result<OneHotConstraintID>

Insert a new one-hot constraint with its context, picking an unused id.

The one-hot set must be non-empty. All variables in the set are structural and must be binary decision variables (parameter ids and non-binary kinds are rejected). Dependency keys are also rejected.

pub fn add_sos1_constraint( &mut self, constraint: Sos1Constraint, context: ConstraintContext, ) -> Result<Sos1ConstraintID>

Insert a new SOS1 constraint with its context, picking an unused id.

All variables in the SOS1 set are structural and must be decision variables (parameter ids are rejected). The set must be non-empty. Dependency keys are also rejected. Unlike one-hot, SOS1 does not require Kind::Binary.

pub fn add_decision_variable( &mut self, id: VariableID, variable: DecisionVariable, label: DecisionVariableLabel, ) -> Result<VariableID>

Insert a decision variable with its modeling label.

The table key must not collide with any existing decision variable, parameter, or substitution-dependency key.

Errors

Returns an error whose chain contains crate::DecisionVariableError::DuplicateID when id is already owned by a decision variable, or crate::ParameterIDCollision when it is already owned by a parameter.

impl ParametricInstance

pub fn sense(&self) -> &Sense

pub fn objective(&self) -> &Function

pub fn parameters(&self) -> &ParameterTable

pub fn decision_variable_dependency(&self) -> &AcyclicAssignments

impl ParametricInstance

pub fn output_objective(&self) -> Option<&OutputObjective>

Return the preserved objective semantics used after specialization.

None means the active Self::sense and Self::objective define the output semantics directly.

pub fn decision_variable_table(&self) -> &DecisionVariableTable

Access the decision-variable definition table.

pub fn decision_variables(&self) -> &BTreeMap<VariableID, DecisionVariable>

Access decision-variable rows keyed by table-owned IDs.

pub fn variable_labels(&self) -> &VariableLabelStore

Access the per-variable modeling-label store.

pub fn set_variable_label( &mut self, id: VariableID, label: ModelingLabel, ) -> Result<()>

Replace the modeling label for a decision variable owned by this parametric instance.

pub fn fixed_decision_variable_values(&self) -> &BTreeMap<VariableID, f64>

Access table-owned fixed decision-variable values.

pub fn fixed_decision_variable_value(&self, id: VariableID) -> Option<f64>

Return the fixed value for one decision variable, if it is fixed.

pub fn named_function_table(&self) -> &NamedFunctionTable<NamedFunction>

Access named-function rows plus their modeling labels.

pub fn named_functions(&self) -> &BTreeMap<NamedFunctionID, NamedFunction>

Access named-function row payloads keyed by table-owned IDs.

pub fn named_function_labels(&self) -> &NamedFunctionLabelStore

Access the per-named-function modeling-label store.

pub fn set_named_function_label( &mut self, id: NamedFunctionID, label: ModelingLabel, ) -> Result<()>

Replace the modeling label for a named function owned by this parametric instance.

pub fn constraints(&self) -> &BTreeMap<ConstraintID, Constraint>

Active constraints.

pub fn removed_constraints( &self, ) -> &BTreeMap<ConstraintID, (Constraint, RemovedReason)>

Removed constraints.

pub fn constraint_collection(&self) -> &ConstraintCollection<Constraint>

The full constraint collection (active + removed).

pub fn constraint_context(&self) -> &ConstraintContextStore<ConstraintID>

Access the per-constraint context store.

pub fn set_constraint_context( &mut self, id: ConstraintID, context: ConstraintContext, ) -> Result<()>

Replace the context for a regular constraint owned by this parametric instance.

pub fn indicator_constraints( &self, ) -> &BTreeMap<IndicatorConstraintID, IndicatorConstraint>

Active indicator constraints.

pub fn removed_indicator_constraints( &self, ) -> &BTreeMap<IndicatorConstraintID, (IndicatorConstraint, RemovedReason)>

Removed indicator constraints.

pub fn indicator_constraint_collection( &self, ) -> &ConstraintCollection<IndicatorConstraint>

The full indicator constraint collection.

pub fn indicator_constraint_context( &self, ) -> &ConstraintContextStore<IndicatorConstraintID>

Access the per-indicator-constraint context store.

pub fn set_indicator_constraint_context( &mut self, id: IndicatorConstraintID, context: ConstraintContext, ) -> Result<()>

Replace the context for an indicator constraint owned by this parametric instance.

pub fn one_hot_constraints( &self, ) -> &BTreeMap<OneHotConstraintID, OneHotConstraint>

Active one-hot constraints.

pub fn removed_one_hot_constraints( &self, ) -> &BTreeMap<OneHotConstraintID, (OneHotConstraint, RemovedReason)>

Removed one-hot constraints.

pub fn one_hot_constraint_collection( &self, ) -> &ConstraintCollection<OneHotConstraint>

The full one-hot constraint collection.

pub fn one_hot_constraint_context( &self, ) -> &ConstraintContextStore<OneHotConstraintID>

Access the per-one-hot-constraint context store.

pub fn set_one_hot_constraint_context( &mut self, id: OneHotConstraintID, context: ConstraintContext, ) -> Result<()>

Replace the context for a one-hot constraint owned by this parametric instance.

pub fn sos1_constraints(&self) -> &BTreeMap<Sos1ConstraintID, Sos1Constraint>

Active SOS1 constraints.

pub fn removed_sos1_constraints( &self, ) -> &BTreeMap<Sos1ConstraintID, (Sos1Constraint, RemovedReason)>

Removed SOS1 constraints.

pub fn sos1_constraint_collection( &self, ) -> &ConstraintCollection<Sos1Constraint>

The full SOS1 constraint collection.

pub fn sos1_constraint_context( &self, ) -> &ConstraintContextStore<Sos1ConstraintID>

Access the per-SOS1-constraint context store.

pub fn set_sos1_constraint_context( &mut self, id: Sos1ConstraintID, context: ConstraintContext, ) -> Result<()>

Replace the context for an SOS1 constraint owned by this parametric instance.

Trait Implementations

impl Clone for ParametricInstance

fn clone(&self) -> ParametricInstance

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ParametricInstance

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

Formats the value using the given formatter.

impl Default for ParametricInstance

fn default() -> ParametricInstance

Returns the “default value” for a type.

impl Display for ParametricInstance

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

Formats the value using the given formatter.

impl FlatAnnotations for ParametricInstance

fn flat_annotations(&self) -> HashMap<String, String>

fn merge_annotations(&mut self, annotations: &HashMap<String, String>)

fn replace_annotations(&mut self, annotations: HashMap<String, String>)

impl From<Instance> for ParametricInstance

fn from(_: Instance) -> Self

Converts to this type from the input type.

impl From<ParametricInstance> for ParametricInstance

fn from(value: ParametricInstance) -> Self

Converts to this type from the input type.

impl PartialEq for ParametricInstance

fn eq(&self, other: &ParametricInstance) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ParametricInstance

impl Substitute for ParametricInstance

type Output = ParametricInstance

fn substitute_acyclic( self, acyclic: &AcyclicAssignments, ) -> Result<Self::Output, SubstitutionError>

Performs substitution using pre-validated acyclic assignments.

fn substitute_one( self, assigned: VariableID, f: &Function, ) -> Result<Self::Output, SubstitutionError>

Substitutes a single variable with a function.

fn substitute( self, assignments: impl IntoIterator<Item = (VariableID, Function)>, ) -> Result<Self::Output, SubstitutionError>

Performs substitution with cycle detection and validation.

impl TryFrom<ParametricInstance> for ParametricInstance

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from(value: ParametricInstance) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<ParametricInstance> for ParametricInstance

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: ParametricInstance) -> Result<Self>

Performs the conversion.