ParametricInstance#

class ParametricInstance#

__copy__() → ParametricInstance#

__deepcopy__(_memo: Any) → ParametricInstance#

add_constraint(constraint: Constraint) → AttachedConstraint#

Add a regular constraint to this parametric instance.

Picks an unused ConstraintID, drains the wrapper's metadata snapshot into this parametric instance's SoA store, and returns an AttachedConstraint bound to the new id. The input Constraint is not mutated; subsequent writes that should land on this parametric instance must go through the returned handle.

Raises ValueError if the constraint references an id that is neither a defined decision variable nor a defined parameter, or if it references an id currently used as a substitution-dependency key.

add_decision_variable(variable: DecisionVariable) → AttachedDecisionVariable#: Add a decision variable to this parametric instance. Returns an AttachedDecisionVariable bound to the variable's id — a write-through handle for further metadata mutation.

add_indicator_constraint(constraint: IndicatorConstraint) → AttachedIndicatorConstraint#

Add an indicator constraint to this parametric instance.

Picks an unused IndicatorConstraintID, drains the wrapper's metadata snapshot into this parametric instance's SoA store, and returns an AttachedIndicatorConstraint bound to the new id.

Raises ValueError if the constraint references an id that is neither a defined decision variable nor a defined parameter, or if it references an id currently used as a substitution-dependency key.

add_one_hot_constraint(constraint: OneHotConstraint) → AttachedOneHotConstraint#: Add a one-hot constraint to this parametric instance.

add_sos1_constraint(constraint: Sos1Constraint) → AttachedSos1Constraint#: Add a SOS1 constraint to this parametric instance.

add_user_annotation(key: str, value: str, annotation_namespace: str = 'org.ommx.user.') → None#

add_user_annotations(annotations: Mapping[str, str], annotation_namespace: str = 'org.ommx.user.') → None#

attached_decision_variable(variable_id: int) → AttachedDecisionVariable#: Look up the AttachedDecisionVariable for the given id — a write-through handle.

constraint_metadata_df(kind: Literal["regular", "indicator", "one_hot", "sos1"] = 'regular') → DataFrame#: Constraint metadata DataFrame (id-indexed). See ommx.v1.Instance.constraint_metadata_df() for column / kind= semantics.

constraint_parameters_df(kind: Literal["regular", "indicator", "one_hot", "sos1"] = 'regular') → DataFrame#: Constraint parameters DataFrame (long format).

constraint_provenance_df(kind: Literal["regular", "indicator", "one_hot", "sos1"] = 'regular') → DataFrame#: Constraint provenance DataFrame (long format).

constraint_removed_reasons_df(kind: Literal["regular", "indicator", "one_hot", "sos1"] = 'regular') → DataFrame#: Removed-constraint reasons DataFrame (long format).

constraints_df(kind: Literal["regular", "indicator", "one_hot", "sos1"] = 'regular', include: Optional[Sequence[str]] = None, removed: bool = False) → DataFrame#: DataFrame of constraints, dispatched on kind=. See ommx.v1.Instance.constraints_df() for column / kind= / include= / removed= semantics.

decision_variables_df(include: Optional[Sequence[str]] = None) → DataFrame#: DataFrame of decision variables

empty() → ParametricInstance#: Create trivial empty instance of minimization with zero objective, no constraints, and no decision variables and parameters.

from_bytes(bytes: bytes) → ParametricInstance#

from_components(sense: Sense, objective: ToFunction, decision_variables: Sequence[DecisionVariable], constraints: Mapping[int, Constraint], parameters: Sequence[Parameter], indicator_constraints: Optional[Mapping[int, IndicatorConstraint]] = None, one_hot_constraints: Optional[Mapping[int, OneHotConstraint]] = None, sos1_constraints: Optional[Mapping[int, Sos1Constraint]] = None, named_functions: Optional[Sequence[NamedFunction]] = None, description: Optional[InstanceDescription] = None) → ParametricInstance#

get_constraint_by_id(constraint_id: int) → Constraint#: Get a specific constraint by ID

get_decision_variable_by_id(variable_id: int) → DecisionVariable#: Get a specific decision variable by ID

get_named_function_by_id(named_function_id: int) → NamedFunction#: Get a specific named function by ID

get_parameter_by_id(parameter_id: int) → Parameter#: Get a specific parameter by ID

get_removed_constraint_by_id(constraint_id: int) → RemovedConstraint#: Get a specific removed constraint by ID

get_user_annotation(key: str, annotation_namespace: str = 'org.ommx.user.') → str#

get_user_annotations(annotation_namespace: str = 'org.ommx.user.') → dict[str, str]#

named_functions_df(include: Optional[Sequence[str]] = None) → DataFrame#: DataFrame of named functions

parameters_df(include: Optional[Sequence[str]] = None) → DataFrame#: DataFrame of parameters

substitute(assignments: Mapping[int, ToFunction]) → None#

Substitute decision variables with function expressions (in-place).

Replaces each given decision variable with the provided function in the objective and all active constraints. Replacement functions may still reference parameters; those parameter references remain in this parametric instance and are evaluated later by with_parameters(). Assignment targets must be existing decision variable IDs. Replacement expressions may only reference existing decision variable or parameter IDs; parameter IDs cannot be assignment targets.

Args:

assignments: A dict mapping decision variable IDs to the function expressions that should replace them.

Important: This method performs an algebraic rewrite. It does not automatically translate the substituted variable's bound or kind into constraints on the replacement expression. If the substitution must preserve the optimization problem, the caller must provide a domain-preserving encoding or add the required linking and bound constraints explicitly.

Raises ValueError on cyclic or recursive assignments, undefined IDs, when a parameter ID is used as an assignment target, or when substituting a variable that is a member of an indicator, one-hot, or SOS1 constraint.

to_bytes() → bytes#

variable_metadata_df() → DataFrame#: Decision-variable metadata DataFrame (id-indexed).

variable_parameters_df() → DataFrame#: Decision-variable parameters DataFrame (long format).

with_parameters(parameters: Mapping[int, float]) → Instance#

Substitute parameters to yield an instance.

Parameters can be provided as a dict mapping parameter IDs to their values.

property annotations: dict[str, str]#

Returns a copy of the annotations dictionary.

Mutating the returned dict will not update the object. Use add_user_annotation() or assign to annotations to modify annotations.

property authors: list[str]#

property constraints: dict[int, AttachedConstraint]#

Read-only property.

Dict of all active constraints in the instance keyed by their IDs.

Each value is an AttachedConstraint: a write-through handle whose getters read from this parametric instance's SoA store and whose metadata setters write back through to it. Use detach() to materialize a Constraint snapshot if you need an independent copy.

property created: Optional[datetime]#

property dataset: Optional[str]#

property decision_variable_ids: set[int]#: Read-only property.

property decision_variables: list[AttachedDecisionVariable]#

Read-only property.

List of all decision variables in the parametric instance sorted by their IDs.

Returns a list of AttachedDecisionVariable write-through handles. See decision_variables for the same shape on Instance.

property description: Optional[InstanceDescription]#: Read-only property.

property indicator_constraints: dict[int, AttachedIndicatorConstraint]#

Read-only property.

Dict of all active indicator constraints in the parametric instance keyed by their IDs.

Each value is an AttachedIndicatorConstraint: a write-through handle whose getters read from this parametric instance's SoA store and whose metadata setters write back through to it.

property license: Optional[str]#

property named_functions: list[NamedFunction]#: Read-only property.

property num_constraints: Optional[int]#

property num_variables: Optional[int]#

property objective: Function #: Read-only property.

property one_hot_constraints: dict[int, AttachedOneHotConstraint]#

Read-only property.

Dict of all active one-hot constraints in the parametric instance keyed by their IDs. Each value is an AttachedOneHotConstraint.

property parameter_ids: set[int]#: Read-only property.

property parameters: list[Parameter]#: Read-only property.

property removed_constraints: dict[int, RemovedConstraint]#: Read-only property.

property removed_indicator_constraints: dict[int, RemovedIndicatorConstraint]#

Read-only property.

Dict of all removed indicator constraints in the parametric instance keyed by their IDs.

property removed_one_hot_constraints: dict[int, RemovedOneHotConstraint]#

Read-only property.

Dict of all removed one-hot constraints in the parametric instance keyed by their IDs. The removed map can become non-empty when an Instance whose one-hot constraints have been converted (via convert_all_one_hots_to_constraints) is round-tripped back to a ParametricInstance via From<Instance>.

property removed_sos1_constraints: dict[int, RemovedSos1Constraint]#

Read-only property.

Dict of all removed SOS1 constraints in the parametric instance keyed by their IDs. See removed_one_hot_constraints() for the round-trip rationale.

property sense: Sense#: Read-only property.

property sos1_constraints: dict[int, AttachedSos1Constraint]#

Read-only property.

Dict of all active SOS1 constraints in the parametric instance keyed by their IDs. Each value is an AttachedSos1Constraint.

property title: Optional[str]#