optimization_modes

Configuration and lifecycle for propagator-side optimization.

OptimizationModeHandler

Own optimization state, objective sums, and pruning decisions.

Attributes:

Name	Type	Description
sums		OptimizationHandler holding the optimization sums and related state
best_value	list[int | float]	Holds the best objective value found so far
strength		OptimizationStrength indicating the current pruning strength
stage_literals	dict[int, int]	dict[int, int] mapping optimization stages to their corresponding literals
optimal_models_wanted		int specifying the number of optimal models requested
optimal_models_found		int counting the number of optimal models found so far

enabled property

enabled: bool

Check if optimization is enabled based on the presence of optimization sums.

Returns:

Name	Type	Description
bool	bool	True if there are optimization sums, False otherwise.

activate_equal_stage

activate_equal_stage(assignment: Assignment, changed_literal: int | None = None) -> bool

Switch to lenient pruning when optimization stage two becomes active. "equal" stage refers to the fact that we do not prune new solution that have the best known value.

Parameters:

Name	Type	Description	Default
assignment	Assignment	The current Clingo assignment.	required
changed_literal	int | None	The literal that changed in the current propagation step, if any.	None

Returns:

Name	Type	Description
bool	bool	True if the pruning strength was switched to lenient, False otherwise.

add_helper_atoms

add_helper_atoms(init: PropagateInit, add_watch: Callable[[int], None]) -> None

Register stage literals used by optimization pruning.

Parameters:

Name	Type	Description	Default
init	PropagateInit	The Clingo propagate initialization object.	required
add_watch	Callable[[int], None]	A callable to register literals for watching.	required

add_value

add_value(variable: Symbol, value: VariableValue, priority: int) -> None

Add a value to the optimization sums with the specified priority.

Parameters:

Name	Type	Description	Default
variable	Symbol	The Clingo symbol representing the variable.	required
value	VariableValue	The value associated with the variable.	required
priority	int	The priority of the value in the optimization sums.	required

configure

configure(ctl: Control) -> Warning | None

Add optimization support and configure the requested optimal-model count.

Parameters:

Name	Type	Description	Default
ctl	Control	Clingo control object.	required

Returns:

Type	Description
Warning | None	warning.Warning | None: A warning if the configuration is not compatible, None otherwise.

evaluate_optimization_sums

evaluate_optimization_sums(ctl: PropagateControl) -> list[int] | None

Evaluate objective bounds and return extra literals for a pruning nogood.

Parameters:

Name	Type	Description	Default
ctl	PropagateControl	The Clingo propagate control object.	required

Returns:

Type	Description
list[int] | None	list[int] | None: A list of literals for the pruning nogood, or None if no pruning is needed.

get_errors

get_errors() -> propagator_warning_t

Get the current optimization errors.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	The current optimization errors.

get_optimization_sums

get_optimization_sums(ctl: PropagateInit, get_variable_value: Callable[[Expr, int], VariableValue], add_watch: Callable[[int], None]) -> None

Load optimization sum declarations from ASP facts.

Parameters:

Name	Type	Description	Default
ctl	PropagateInit	Clingo propagation initializer.	required
get_variable_value	Callable[[Expr, int], VariableValue]	Callback to intern an expression value.	required
add_watch	Callable[[int], None]	Callback to register literals for watching.	required

initialize_best_value

initialize_best_value() -> None

Initialize the best value for the optimization sums.

This sets the best value to the lowest possible values based on the number of optimization sums.

record_model

record_model(model: Model) -> bool

Count optimal models and report when the requested count is reached.

Parameters:

Name	Type	Description	Default
model	Model	The Clingo model to be recorded.	required

Returns:

Name	Type	Description
bool	bool	True if the requested number of optimal models has been reached, False otherwise.

reset

reset() -> None

Reset per-solve optimization state, preserving configuration.

This includes resetting the optimization sums, best value, pruning strength, stage literals, and the count of optimal models found.

reset_sums

reset_sums(decision_level: int) -> None

Reset the optimization sums for the given decision level.

Parameters:

Name	Type	Description	Default
decision_level	int	The current decision level in the solver.	required

update_best_value

update_best_value() -> tuple[list[int | float], list[int | float]] | None

Update the incumbent if the current objective vector is better.

Returns:

Type	Description
tuple[list[int | float], list[int | float]] | None	tuple[list[int | float], list[int | float]] | None: A tuple containing the previous and new best values if updated, or None if no update occurred.