PropagatorVariables

BoolEvaluateVariable

Represents a boolean evaluation variable, which is a special case of EvaluateVariable that is expected to evaluate to a boolean value. This class can be used for variables that are expected to represent conditions or constraints that must hold.

Attributes:

Name	Type	Description
name	str	Name of the variable.
expression	VariableValue	The VariableValue instance being evaluated.

active_literals property

active_literals: set[int]

Return signed literals that give the current value of the boolean evaluation variable.

Returns:

Type	Description
set[int]	set[int]: Set of signed literals.

decision_level property

decision_level: int

Return the decision level at which the value was set.

Returns:

Name	Type	Description
int	int	Decision level of the variable.

expressions property

expressions: set[VariableValue]

Return the set of VariableValue instances associated with this variable.

Returns:

Type	Description
set[VariableValue]	set[VariableValue]: Set containing the VariableValue of this boolean evaluation variable.

literals property

literals: set[int]

Return all literals associated with this boolean evaluation variable.

Returns:

Type	Description
set[int]	set[int]: Set of all literals (true, false, and bad) for this variable and the literal of the expression.

parents property

parents: list[VariableType]

Return parent variables.

Returns:

Type	Description
list[VariableType]	list[VariableType]: Empty list (bool evaluate variables have no parents).

__init__

__init__(name: str, expression_value: VariableValue, true_lit: int, false_lit: int, bad_lit: int) -> None

Initialize a BoolEvaluateVariable.

Parameters:

Name	Type	Description	Default
name	str	Name of the variable.	required
expression_value	VariableValue	Interned expression to evaluate, expected to yield a boolean value.	required
true_lit	int	Literal representing the true value of the variable.	required
false_lit	int	Literal representing the false value of the variable.	required
bad_lit	int	Literal representing a bad value of the variable.	required

evaluate

evaluate(ctl: PropagateControl) -> EvaluationResult

Evaluate the expression and return an EvaluationResult.

Parameters:

Name	Type	Description	Default
ctl	PropagateControl	PropagateControl	required

Returns:

Name	Type	Description
EvaluationResult	EvaluationResult	Result of the evaluation, indicating whether the value changed or if an inference should be made.

get_errors

get_errors() -> propagator_warning_t

Return warnings collected during evaluation.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings.

get_value

get_value() -> ValueStatus | bool | Bad

Return the current value of the boolean evaluation variable.

Returns:

Type	Description
ValueStatus | bool | Bad	ValueStatus | bool | expression.Bad: Current value, or NOT_SET.

has_domain

has_domain() -> bool

Return whether the variable has a domain.

Returns:

Name	Type	Description
bool	bool	Always True for BoolEvaluateVariable.

has_unassigned

has_unassigned() -> bool

Check whether the boolean evaluation variable is unassigned.

Returns:

Name	Type	Description
bool	bool	True if the value is NOT_SET.

infer

infer() -> set[int]

Infer the literal corresponding to the current value.

Returns:

Type	Description
set[int]	set[int]: A singleton set containing the signed literal if assigned; otherwise empty. Note that literal is flipped so that the nogood infers the correct value.

reset

reset(dl: int) -> bool

Reset based on the decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

Returns: bool: False since there is nothing to reset

vars

vars() -> set[Symbol]

Collect variables referenced by the boolean evaluation expression.

Returns:

Type	Description
set[Symbol]	set[clingo.Symbol]: Variables referenced by the expression.

DictVariable

A dict variable with a name and a set of key-value expressions.

This is supposed to mirror the multimap_declare/2 and multimap_assign/5 atom in the ASP encoding. multimap_declare is this class, while each multimap_assign adds a possible key-value pair to the dict.

Implements the VariableType protocol.

Attributes:

Name	Type	Description
name	str	Name of the dict variable.
var	Symbol	Clingo symbol for the variable.
expressions	set[VariableValue]	Dictionary mapping keys to SetVariableValue instances.
value	ValueStatus | Multimap[Symbol, Any]	Current value of the dict variable.
literal	int	Literal for the dict declaration.
assigned	bool | None	Truth value of the dict declaration.
decision_level	int	Decision level of the current value.
parents	list[VariableType]	Parent variables.
errors	propagator_warning_t	List of warnings or errors encountered during evaluation.
is_user_variable	bool	Whether this variable is defined by the user or is an internal variable

active_literals property

active_literals: set[int]

Return literals relevant for this variable's current state.

Includes literals from all key/value expressions and, if assigned, the dict declaration literal.

Returns:

Type	Description
set[int]	set[int]: Set of literals.

expressions property

expressions: set[VariableValue]

Return the set of VariableValue instances representing possible keys and their associated values.

Returns:

Type	Description
set[VariableValue]	set[VariableValue]: Set of possible key expressions.

literals property

literals: set[int]

Return the literal associated with this expression

Returns:

Type	Description
set[int]	set[int]: A singleton set containing the literal

__init__

__init__(name: str, var: Symbol, lit: int, is_user_variable: bool = False) -> None

Initialize a DictVariable.

Parameters:

Name	Type	Description	Default
name	str	Name of the dict variable.	required
var	Symbol	Clingo symbol identifying the variable.	required
lit	int	Literal for the dict declaration.	required
is_user_variable	bool	Whether this variable is defined by the user or is an internal variable.	False

add_value

add_value(key_value: VariableValue, value: VariableValue, condition_value: VariableValue | None = None) -> None

Add a key-value pair to the dict variable.

Parameters:

Name	Type	Description	Default
key_value	VariableValue	Interned expression for the key.	required
value	VariableValue	Interned expression for the value.	required
condition_value	VariableValue | None	Interned condition controlling membership of the pair.	None

discern_value

discern_value() -> ValueStatus | Multimap[Symbol, Any]

Returns a dictionary mapping keys to their assigned values. If any value is unassigned, returns None for that key.

Returns:

Type	Description
ValueStatus | Multimap[Symbol, Any]	ValueStatus | multimap.Multimap[clingo.Symbol, Any]: The discerned value of the dict variable, or NOT_SET if any key/value is unassigned.

evaluate

evaluate(ctl: PropagateControl) -> EvaluationResult

Evaluate all values in the dictionary and return (changed, conflict). For DictVariable, conflict should never occur.

Parameters:

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

Returns:

Name	Type	Description
EvaluationResult	EvaluationResult	The result of the evaluation, indicating whether the value changed, remained the same, or if there was a conflict.

get_errors

get_errors() -> propagator_warning_t

Get all errors from the dict variable and its key-value pairs. Bad value warnings are filtered out for non user variables.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings or errors.

get_literals

get_literals(active: bool) -> set[int]

Return the literals associated with the dict variable.

Parameters:

Name	Type	Description	Default
active	bool	Whether to return active (signed) literals that give this variable its value or all literals.	required

Returns:

Type	Description
set[int]	set[int]: Set of literals.

get_value

get_value() -> ValueStatus | Multimap[Symbol, Any]

Get the current value of the dict variable.

Returns:

Type	Description
ValueStatus | Multimap[Symbol, Any]	ValueStatus | multimap.Multimap[clingo.Symbol, Any]: Current dict value or NOT_SET.

has_domain

has_domain() -> bool

Check if the dict variable has a domain (any key-value pairs).

Returns:

Name	Type	Description
bool	bool	True if there are key-value pairs, False otherwise.

has_unassigned

has_unassigned() -> bool

Check whether any key/value expression is still unassigned.

Returns:

Name	Type	Description
bool	bool	True if any key/value expression is unassigned.

infer

infer() -> set[int]

Curently this return an empty set as it does not support any inferences. This is here for compatibility with the VariableType protocol.

Returns:

Type	Description
set[int]	set[int]: A set of inferred values, currently always empty.

reset

reset(dl: int) -> bool

Reset based on the decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

Returns: bool: True if the variable was reset, False otherwise.

vars

vars() -> set[Symbol]

Collect all variables referenced by this dict.

Returns:

Type	Description
set[Symbol]	set[clingo.Symbol]: Variables used in key/value expressions.

EvaluateVariable

Represents an evaluate atom defined by an operator and arguments of the operator.

Attributes:

Name	Type	Description
ref	constant	User-facing reference.
value	Any	The current value of the evaluation.
literal	int	The associated literal.
errors	propagator_warning_t	List of warnings or errors encountered during evaluation.

var property

var: Symbol

Return a symbolic representation of this evaluation variable.

Returns:

Type	Description
Symbol	clingo.Symbol: A symbolic representation of this variable.

__init__

__init__(ref: constant, expr: Expr, literal: int = -1) -> None

Initialize an EvaluateVariable.

Parameters:

Name	Type	Description	Default
ref	constant	User-facing reference.	required
expr	Expr	Expression to evaluate.	required
literal	int	Literal controlling whether this operation is active.	-1

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any]) -> bool

Evaluate the expression

Parameters:

Name	Type	Description	Default
evaluations	Evaluations	Current variable evaluations.	required
ctl	PropagateControl	PropagateControl for checking literal assignments and decision levels.	required
env	dict[Any, Any]	Environment for evaluation.	required

Returns:

Name	Type	Description
bool	bool	True if the value has changed, False otherwise.

get_errors

get_errors() -> propagator_warning_t

Return warnings collected while evaluating this operation.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings.

get_value

get_value() -> Any

Return the current value of the evaluation.

Returns:

Name	Type	Description
Any	Any	Current value.

Evaluations

Manages the current evaluations of variables.

Attributes:

Name	Type	Description
evaluations	evaluations_type	Dictionary mapping variable symbols to their evaluated values.
false_assignments	list[Symbol]	List of variables that are assigned false.
existing_vars	dict[Symbol, int]	List of variables that exist in the current evaluation.

__init__

__init__() -> None

Initialize Evaluations with an empty dictionary.

add_var_to_evaluations

add_var_to_evaluations(variable: VariableType) -> None

Add a value-bearing variable's value to this evaluation context.

Parameters:

Name	Type	Description	Default
variable	VariableType	The variable to add.	required

init

init(variables: Iterable[VariableType]) -> None

Initialize the existing variables list based on the provided variables. This method should be called before any evaluations are updated to ensure that the existing variables are correctly tracked.

Parameters:

Name	Type	Description	Default
variables	Iterable[VariableType]	Iterable of variables to initialize from.	required

remove_var_from_evaluations

remove_var_from_evaluations(variable: VariableType) -> None

Remove a value-bearing variable's contribution from this context.

Parameters:

Name	Type	Description	Default
variable	VariableType	The variable to remove.	required

var_usable

var_usable(var: Symbol) -> bool

Check if a variable is usable in the current evaluation.

A variable is considered usable if it has an assigned value, is listed as a false assignment or does not exist.

Parameters:

Name	Type	Description	Default
var	Symbol	Variable symbol to check.	required

Returns:

Name	Type	Description
bool	bool	True if the variable is usable, False otherwise.

OptimizationHandler

Handles multiple optimization sums, each with a priority.

Attributes:

Name	Type	Description
sums	list[OptimizationSum]	List of OptimizationSum instances. Note that this is a list and not a dict. OptimizationSums are ordered by priority, with higher priority sums coming first.

active_literals property

active_literals: set[int]

Returns the empty set since the optimization sums do not have literals directly associated with them.

Returns:

Type	Description
set[int]	set[int]: Empty set.

expressions property

expressions: set[VariableValue]

Return the set of VariableValue instances representing all expressions in all optimization sums.

Returns:

Type	Description
set[VariableValue]	set[VariableValue]: Set of expressions in all optimization sums.

literals property

literals: set[int]

Returns the empty set since the optimization sums do not have literals directly associated with them.

Returns:

Type	Description
set[int]	set[int]: Empty set.

__init__

__init__() -> None

Initialize an OptimizationHandler.

add_value

add_value(var: Symbol, value: VariableValue, priority: int = 0) -> None

Add a value to the appropriate optimization sum by priority.

Parameters:

Name	Type	Description	Default
var	Symbol	Clingo symbol for the variable.	required
value	VariableValue	Interned expression to evaluate.	required
priority	int	Priority of the optimization sum.	0

evaluate

evaluate(ctl: PropagateControl) -> bool

Evaluate all optimization sums and return True if any value has changed.

Parameters:

Name	Type	Description	Default
ctl	PropagateControl	Clingo propagate control.	required

Returns:

Name	Type	Description
bool	bool	True if any value has changed, False otherwise.

get_errors

get_errors() -> propagator_warning_t

Get all errors from all optimization sums.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings or errors.

get_sum_count

get_sum_count() -> int

Get the number of optimization sums.

Returns:

Name	Type	Description
int	int	Number of optimization sums.

get_value

get_value() -> list[int | float]

Get the values of all optimization sums ordered by priority.

Returns:

Type	Description
list[int | float]	list[int | float]: List of current sum values.

has_unassigned

has_unassigned(position: int) -> bool

Check if the optimization sum at the given position has unassigned values.

Parameters:

Name	Type	Description	Default
position	int	Index of the optimization sum (sorted by priority).	required

Returns:

Name	Type	Description
bool	bool	True if there are unassigned values, False otherwise.

reset

reset(dl: int) -> None

Reset all optimization sums.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

vars

vars() -> set[Symbol]

Collect all variables used in all optimization sums.

Returns:

Type	Description
set[Symbol]	set[clingo.Symbol]: Set of variables in all optimization sums.

OptimizationSum

Represents a sum for optimization purposes, holding expressions and their priorities.

Attributes:

Name	Type	Description
expressions	set[VariableValue]	List of (clingo.Symbol, VariableValue) pairs. The symbol is the variable associated with the expresssion. The value of the expression is what is used in the sum.
value	int | float	The current sum value.
priority	int	Priority of the optimization sum.
decision_level	int	Decision level at which the value was set.

active_literals property

active_literals: set[int]

Get all literals associated with the optimization sum that gave it its current value.

Returns:

Type	Description
set[int]	set[int]: Set of literals.

expressions property

expressions: set[VariableValue]

Return the set of VariableValue instances representing the expressions in the optimization sum.

Returns:

Type	Description
set[VariableValue]	set[VariableValue]: Set of expressions in the optimization sum.

literals property

literals: set[int]

Get all literals associated with the optimization sum.

Returns:

Type	Description
set[int]	set[int]: Set of literals.

__init__

__init__(priority: int = 0) -> None

Initialize an OptimizationSum.

Parameters:

Name	Type	Description	Default
priority	int	Priority of the optimization sum.	0

add_value

add_value(var: Symbol, value: VariableValue) -> None

Add a value to the optimization sum.

Parameters:

Name	Type	Description	Default
var	Symbol	Clingo symbol for the variable.	required
value	VariableValue	Interned expression to evaluate.	required

discern_value

discern_value() -> int | float

Compute the sum of all assigned values in the optimization sum.

Returns:

Type	Description
int | float	int | float: The sum of all assigned values.

evaluate

evaluate(ctl: PropagateControl) -> bool

Evaluate the optimization sum and return True if the value has changed.

Parameters:

Name	Type	Description	Default
ctl	PropagateControl	Clingo propagate control.	required

Returns:

Name	Type	Description
bool	bool	True if the value has changed, False otherwise.

get_errors

get_errors() -> propagator_warning_t

Get all errors from the evaluation of the optimization sum.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings or errors.

get_literals

get_literals(active: bool) -> set[int]

Get all literals associated with the optimization sum.

Parameters:

Name	Type	Description	Default
active	bool	Whether to return active (signed) literals that give this variable its value or all literals.	required

Returns:

Type	Description
set[int]	set[int]: Set of literals.

get_value

get_value() -> int | float

Get the current value of the optimization sum.

Returns:

Type	Description
int | float	int | float: The sum value.

has_unassigned

has_unassigned() -> bool

Check if any value in the optimization sum is unassigned.

Returns:

Name	Type	Description
bool	bool	True if any value is unassigned, False otherwise.

reset

reset(dl: int) -> None

Reset the optimization sum if the decision level is greater than or equal to dl.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

vars

vars() -> set[Symbol]

Collect all variables used in the optimization sum.

Returns:

Type	Description
set[Symbol]	set[clingo.Symbol]: Set of variables in the optimization sum.

SetVariable

A set variable with a name and a set of value expressions.

This is supposed to mirror the set_declare/2 and set_assign/3 atom in the ASP encoding. set_declare is this class, while each set_assign adds a possible value to the set.

Implements the VariableType protocol.

Attributes:

Name	Type	Description
name	str	Name of the set variable.
var	Symbol	Clingo symbol for the variable.
expressions	set[VariableValue]	SetVariableValue instance holding possible values.
value	ValueStatus | frozenset[Any]	Current value of the set variable.
literal	int	Literal for the set declaration.
assigned	bool | None	Truth value of the set declaration.
decision_level	int	Decision level of the set declaration.
parents	list[VariableType]	Parent variables.
errors	propagator_warning_t	List of warnings or errors encountered during evaluation.
is_user_variable	bool	Whether this variable is defined by the user or is an internal variable

active_literals property

active_literals: set[int]

Return literals relevant for this variable's current state.

Includes literals from all element assignments and, if assigned, the set declaration literal.

Returns:

Type	Description
set[int]	set[int]: Set of literals.

expressions property

expressions: set[VariableValue]

Return the set of VariableValue instances representing possible set elements.

Returns:

Type	Description
set[VariableValue]	set[VariableValue]: Set of possible element expressions.

literals property

literals: set[int]

Return the literal associated with this expression

Returns:

Type	Description
set[int]	set[int]: A singleton set containing the literal

__init__

__init__(name: str, var: Symbol, lit: int, is_user_variable: bool = False) -> None

Initialize a SetVariable.

Parameters:

Name	Type	Description	Default
name	str	Name of the set variable.	required
var	Symbol	Clingo symbol identifying the variable.	required
lit	int	Literal for the set declaration.	required
is_user_variable	bool	Whether this variable is defined by the user or is an internal variable.	False

add_value

add_value(value: VariableValue, condition_value: VariableValue | None) -> None

Add a potential value expression with its associated condition to the set.

Parameters:

Name	Type	Description	Default
value	VariableValue	Interned expression for one possible set element.	required
condition_value	VariableValue | None	Interned expression representing the condition under which the value is added to the set. If None, the value is always added.	required

evaluate

evaluate(ctl: PropagateControl) -> EvaluationResult

Evaluate the expression and return an EvaluationResult.

Parameters:

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

Returns:

Name	Type	Description
EvaluationResult	EvaluationResult	The result of the evaluation, indicating whether the value changed, remained the same, or if there was a conflict.

get_errors

get_errors() -> propagator_warning_t

Return warnings/errors collected during evaluation. Bad value warnings are filtered out for non user variables

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	Warnings and errors for this set and its elements.

get_literals

get_literals(active: bool) -> set[int]

Return the literals associated with the set variable.

Parameters:

Name	Type	Description	Default
active	bool	Whether to return active (signed) literals that give this variable its value or all literals.	required

Returns:

Type	Description
set[int]	set[int]: Set of literals.

get_value

get_value() -> ValueStatus | frozenset[Any]

See SetVariableValue.get_value

Returns:

Type	Description
ValueStatus | frozenset[Any]	ValueStatus | frozenset[Any]: The current value of the set variable

has_domain

has_domain() -> bool

Check whether the set has a domain.

Returns:

Name	Type	Description
bool	bool	True if at least one value can be assigned.

has_unassigned

has_unassigned() -> bool

Check whether any element expression is still unassigned.

Returns:

Name	Type	Description
bool	bool	True if at least one element is unassigned.

infer

infer() -> set[int]

Curently this returns an empty set as it does not support any inferences. This is here for compatibility with the VariableType protocol.

reset

reset(dl: int) -> bool

Reset based on decision level.

Returns:

Name	Type	Description
bool	bool	True if the variable was reset, False otherwise.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

vars

vars() -> set[Symbol]

Collect all variables referenced by this set.

Returns:

Type	Description
set[Symbol]	set[clingo.Symbol]: Variables used in element expressions.

SetVariableValue

Represents a set of possible values for a set variable.

Attributes:

Name	Type	Description
values		Set of VariableValue instances representing possible values.

active_literals property

active_literals: set[int]

Return signed literals implied by currently evaluated set elements.

Returns:

Type	Description
set[int]	set[int]: Set of signed literals.

expressions property

expressions: set[VariableValue]

Return all value expressions in the set variable.

Returns:

Type	Description
set[VariableValue]	set[VariableValue]: Set of value expressions.

literals property

literals: set[int]

Return the literal associated with this expression

Returns:

Type	Description
set[int]	set[int]: A singleton set containing the literal

__init__

__init__() -> None

Initialize a SetVariableValue.

add_value

add_value(value: VariableValue, condition_value: VariableValue | None = None) -> None

Add a candidate value to the set.

Parameters:

Name	Type	Description	Default
value	VariableValue	Interned expression for a set element.	required

get_errors

get_errors() -> propagator_warning_t

Return warnings collected while evaluating set elements.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings.

get_literals

get_literals(active: bool) -> set[int]

Return the literals associated with the set elements.

Parameters:

Name	Type	Description	Default
active	bool	Whether to return active (signed) literals that give this variable its value or all literals.	required

Returns:

Type	Description
set[int]	set[int]: Set of literals.

get_value

get_value() -> ValueStatus | frozenset[Any]

If there is an unassigned value, return ValueStatus.NOT_SET. Otherwise return the set of assigned values.

Returns:

Type	Description
ValueStatus | frozenset[Any]	ValueStatus | frozenset[Any]: ValueStatus.NOT_SET if any element is unassigned, otherwise a frozenset of assigned values.

has_domain

has_domain() -> bool

Return whether at least one value expression is present.

Returns:

Name	Type	Description
bool	bool	True if any value expression exists.

has_unassigned

has_unassigned() -> bool

Check whether any element value is still unassigned.

Returns:

Name	Type	Description
bool	bool	True if any element is NOT_SET.

reset

reset(dl: int) -> None

Reset all element values based on decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

vars

vars() -> set[Symbol]

Collect variables referenced by all set element expressions.

Returns:

Type	Description
set[Symbol]	set[clingo.Symbol]: Referenced variables.

SharedValue

Represents a shared value that is used by other parts of the constraint handler.

var property

var: Symbol

Return a symbolic representation of this evaluation variable.

Returns:

Type	Description
Symbol	clingo.Symbol: A symbolic representation of this variable.

__init__

__init__(expr: Expr, literal: int = -1) -> None

Initialize a SharedValue.

Parameters:

Name	Type	Description	Default
expr	Expr	The expression associated with this shared value.	required
literal	int	Literal controlling whether this operation is active.	-1

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any]) -> bool

Evaluate the expression

Parameters:

Name	Type	Description	Default
evaluations	Evaluations	Current variable evaluations.	required
ctl	PropagateControl	PropagateControl for checking literal assignments and decision levels.	required
env	dict[Any, Any]	Environment for evaluation.	required

Returns:

Name	Type	Description
bool	bool	True if the value has changed, False otherwise.

get_errors

get_errors() -> propagator_warning_t

Return warnings collected while evaluating this operation.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings.

get_value

get_value() -> Any

Return the current value of the evaluation.

Returns:

Name	Type	Description
Any	Any	Current value.

Variable

A variable with a name and a value expression.

Class to hold the expressions assigned to a variable (via variable_define, variable_declare, etc). It also evaluates them and discerns the appropriate value for the variable, while keeping track of the decision level and errors.

Implements the VariableType protocol.

Attributes:

Name	Type	Description
name	str	Name of the variable.
var	Symbol	Clingo symbol for the variable.
expressions	set[VariableValue]	Set of possible values (VariableValue).
value	Any	Current value of the variable.
parents	list[VariableType]	Parent variables.
decision_level	int	Decision level at which the value was set.
domain_literals	set[int]	Literals defining the domain.
errors	propagator_warning_t	List of warnings or errors encountered during evaluation.
is_user_variable	bool	Whether this variable is defined by the user or is an internal variable

active_literals property

active_literals: set[int]

Return signed literals implied by all candidate values.

Returns:

Type	Description
set[int]	set[int]: Set of signed literals.

literals property

literals: set[int]

Return the literal associated with this expression

Returns:

Type	Description
set[int]	set[int]: A singleton set containing the literal

__init__

__init__(name: str, var: Symbol, is_user_variable: bool = False) -> None

Initialize a Variable.

Parameters:

Name	Type	Description	Default
name	str	Name for the variable.	required
var	Symbol	Clingo symbol representing this variable.	required
is_user_variable	bool	Whether this variable is defined by the user or is an internal variable.	False

add_value

add_value(value: VariableValue, domain_lit: int) -> None

Add a possible value expression for this variable.

Parameters:

Name	Type	Description	Default
value	VariableValue	Interned expression representing a candidate value.	required
domain_lit	int	Literal indicating the truth value of the domain/declaration context.	required

evaluate

evaluate(ctl: PropagateControl) -> EvaluationResult

Evaluate the expression and return an EvaluationResult. Args: ctl: PropagateControl object for interacting with the solver.

Returns:

Name	Type	Description
EvaluationResult	EvaluationResult	Result of the evaluation.

get_errors

get_errors() -> propagator_warning_t

Return warnings collected while evaluating candidate values. Bad value warnings are filtered out for non user variables.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings.

get_literals

get_literals(active: bool) -> set[int]

Return the literal associated with this expression

Parameters:

Name	Type	Description	Default
active	bool	Whether to return active (signed) literals that give this variable its value or all literals.	required

Returns:

Type	Description
set[int]	set[int]: A singleton set containing the literal

get_value

get_value() -> Any

Return the current value.

Returns:

Name	Type	Description
Any	Any	Current value, or a ValueStatus.

get_values

get_values() -> list[Any]

Return all concrete values assigned to this variable.

Returns:

Type	Description
list[Any]	list[Any]: Values excluding NOT_SET and ASSIGNMENT_IS_FALSE.

has_domain

has_domain() -> bool

Return whether at least one value expression is available.

Returns:

Name	Type	Description
bool	bool	True if any candidate expression exists.

has_unassigned

has_unassigned() -> bool

Check whether any candidate value is still unassigned.

Returns:

Name	Type	Description
bool	bool	True if any candidate value is NOT_SET.

infer

infer() -> set[int]

Currently this returns an empty set as it does not support any inferences. This is here for compatibility with the VariableType protocol.

Returns:

Type	Description
set[int]	set[int]: Empty set (no inferences).

reset

reset(dl: int) -> bool

Reset based on decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

Returns:

Name	Type	Description
bool	bool	True if the variable was reset, False otherwise.

vars

vars() -> set[Symbol]

Collect variables referenced by all candidate value expressions.

Returns:

Type	Description
set[Symbol]	set[clingo.Symbol]: Referenced variables.

VariableManager

Manages variables in the propagator. This includes storing variables, retrieving them by name and type, and resetting them based on decision levels.

Attributes:

Name	Type	Description
variables	dict[Symbol, dict[VariableTypeNames, VariableType]]	Dictionary mapping variable names to VariableType instances.

add_expr_owner

add_expr_owner(value: VariableValue, variable: VariableType) -> None

Associate an interned value with its owning variable.

Parameters:

Name	Type	Description	Default
value	VariableValue	Interned expression value.	required
variable	VariableType	Owning variable.	required

add_literal_expr

add_literal_expr(literal: int, value: VariableValue) -> None

Associate a value with the positive form of a solver literal.

Parameters:

Name	Type	Description	Default
literal	int	Solver literal.	required
value	VariableValue	Expression value to associate with the literal.	required

add_literal_var

add_literal_var(literal: int, variable: VariableType) -> None

Associate a variable with the positive form of a solver literal.

Parameters:

Name	Type	Description	Default
literal	int	Solver literal.	required
variable	VariableType	Variable to associate with the literal.	required

add_user_variable_name

add_user_variable_name(name: Symbol) -> None

Add a variable name to the set of user variable names.

Parameters:

Name	Type	Description	Default
name	Symbol	The variable name to add.	required

add_var_expr

add_var_expr(var: Symbol, expr: VariableValue) -> None

Record that an expression value depends on a variable symbol.

Parameters:

Name	Type	Description	Default
var	Symbol	Variable symbol used by the expression.	required
expr	VariableValue	Expression value using the variable.	required

add_variable

add_variable(name: Symbol, variable: VariableType) -> None

Add a variable to the manager. We assume that this is called only once for a given VariableType

Parameters:

Name	Type	Description	Default
name	Symbol	The name of the variable to add.	required
variable	VariableType	The VariableType instance to add.	required

compute_ranks

compute_ranks() -> None

Assign ranks to variables based on the ranks of their dependencies, then to interned expressions based on the variables they use.

Variables whose dependencies can never be satisfied get rank -1, as do expressions that use an unknown variable.

delete_literal_var

delete_literal_var(literal: int, variable: VariableType) -> bool

Remove a literal-variable association, returning whether it existed.

Parameters:

Name	Type	Description	Default
literal	int	Solver literal.	required
variable	VariableType	Variable to disassociate from the literal.	required

Returns: bool: True if the association existed and was removed, False otherwise.

delete_variable

delete_variable(name: Symbol) -> None

Delete a variable by name.

Parameters:

Name	Type	Description	Default
name	Symbol	The name of the variable to delete.	required

Raises: KeyError: If the variable with the specified name does not exist.

delete_variable_type

delete_variable_type(name: Symbol, variable: VariableType) -> None

Delete one registered variable object.

Remove the symbol entry when it no longer contains any variable types.

get_all_expressions

get_all_expressions() -> list[VariableValue]

Return a snapshot of all interned expression values. Returns: list[VariableValue]: All interned expression values.

get_dependencies

get_dependencies(name: Symbol) -> set[Symbol]

Get the dependencies of a variable by name.

Parameters:

Name	Type	Description	Default
name	Symbol	The name of the variable to retrieve dependencies for.	required

Returns: set[clingo.Symbol]: A set of variable names that are dependencies of the specified variable.

get_expr_owners

get_expr_owners(expr: VariableValue) -> list[VariableType]

Get the variables owning an expression value, or an empty list.

Parameters:

Name	Type	Description	Default
expr	VariableValue	Expression value.	required

Returns: list[VariableType]: Owning variables.

get_expr_rank

get_expr_rank(expr: VariableValue) -> int

Get the rank of an expression value.

Parameters:

Name	Type	Description	Default
expr	VariableValue	Expression value.	required

Raises: KeyError: If ranks were not computed for the expression.

get_literal_exprs

get_literal_exprs(literal: int) -> set[VariableValue]

Get values associated with a solver literal, regardless of sign.

Parameters:

Name	Type	Description	Default
literal	int	Solver literal.	required

Returns: set[VariableValue]: Associated expression values.

get_literal_vars

get_literal_vars(literal: int) -> list[VariableType]

Get variables associated with a solver literal, regardless of sign.

Parameters:

Name	Type	Description	Default
literal	int	Solver literal.	required

Returns: list[VariableType]: Associated variables.

get_var_exprs

get_var_exprs(var: Symbol) -> set[VariableValue]

Get the expression values that depend on a variable symbol.

Parameters:

Name	Type	Description	Default
var	Symbol	Variable symbol.	required

Returns: set[VariableValue]: Dependent expression values.

get_var_rank

get_var_rank(var: Symbol) -> int

Get the rank of a variable symbol.

Parameters:

Name	Type	Description	Default
var	Symbol	Variable symbol.	required

Raises: KeyError: If ranks were not computed for the variable.

get_variable

get_variable(name: Symbol, var_type: VariableTypeNames) -> VariableType

Get a variable by name and type.

Parameters:

Name	Type	Description	Default
name	Symbol	The name of the variable to retrieve.	required
var_type	VariableTypeNames	The type of the variable to retrieve.	required

Returns: The VariableType instance if found. Raises: KeyError: If the variable with the specified name and type does not exist.

get_variable_value

get_variable_value(expr: Expr, literal: int) -> VariableValue

Intern a value and index it by its solver literal.

Parameters:

Name	Type	Description	Default
expr	Expr	Expression object.	required
literal	int	Solver literal.	required

Returns: VariableValue: Interned expression value.

get_variables

get_variables() -> Iterable[VariableType]

Get all variables managed by this VariableManager. Returns: Iterable[VariableType]: An iterable of all VariableType instances.

get_variables_by_type

get_variables_by_type(var_type: VariableTypeNames) -> Iterable[VariableType]

Get all variables of a specific type.

Parameters:

Name	Type	Description	Default
var_type	VariableTypeNames	The type of variables to retrieve.	required

Returns: Iterable[VariableType]: An iterable of VariableType instances of the specified type.

has_var_type

has_var_type(name: Symbol, var_type: VariableTypeNames) -> bool

Check if a variable of a specific type exists for a given name.

Parameters:

Name	Type	Description	Default
name	Symbol	The name of the variable to check.	required
var_type	VariableTypeNames	The type of the variable to check.	required

Returns: bool: True if the variable of the specified type exists, False otherwise.

is_user_variable

is_user_variable(name: Symbol) -> bool

Check if a variable name is a user variable.

Parameters:

Name	Type	Description	Default
name	Symbol	The variable name to check.	required

Returns: bool: True if the variable name is a user variable, False otherwise.

items

items() -> Iterable[tuple[Symbol, dict[VariableTypeNames, VariableType]]]

Get all variable items as (name, variable_dict) pairs.

Returns:

Type	Description
Iterable[tuple[Symbol, dict[VariableTypeNames, VariableType]]]	Iterable[tuple[clingo.Symbol, dict[VariableTypeNames, VariableType]]]: An iterable of (name, variable_dict) pairs.

keys

keys() -> Iterable[Symbol]

Get all variable names.

Returns:

Type	Description
Iterable[Symbol]	Iterable[clingo.Symbol]: An iterable of variable names.

remove

remove(variable: Symbol) -> None

Remove a variable by name.

Parameters:

Name	Type	Description	Default
variable	Symbol	The name of the variable to remove.	required

Raises: KeyError: If the variable with the specified name does not exist.

remove_expr_owner

remove_expr_owner(expr: VariableValue, variable: VariableType) -> None

Remove a variable from the owners of an expression value, if present.

Parameters:

Name	Type	Description	Default
expr	VariableValue	Expression value.	required
variable	VariableType	Owner to remove.	required

values

values() -> Iterable[dict[VariableTypeNames, VariableType]]

Get all variable dictionaries.

Returns:

Type	Description
Iterable[dict[VariableTypeNames, VariableType]]	Iterable[dict[VariableTypeNames, VariableType]]: An iterable of variable dictionaries.

VariableType

Bases: Protocol

Protocol for variable types used in the propagator. Defines the required interface for variables.

VariableValue

Represents a single expression appearing in an assignment atom.

Attributes:

Name	Type	Description
expr	Expr	The expression to evaluate.
value	Any	The current value of the expression.
literal	int	The associated literal.
assigned	bool | None	Whether the literal is assigned.
decision_level	int	The decision level at which the value was set.
errors	propagator_warning_t	List of warnings or errors encountered during evaluation.

active_literals property

active_literals: set[int]

Return the literal that represents the current value.

Returns:

Type	Description
set[int]	set[int]: A singleton set containing the signed literal if assigned; otherwise empty.

literals property

literals: set[int]

Return the literal associated with this expression

Returns:

Type	Description
set[int]	set[int]: A singleton set containing the literal

__init__

__init__(expr: Expr, lit: int) -> None

Initialize a VariableValue.

Parameters:

Name	Type	Description	Default
expr	Expr	Expression associated with the variable.	required
lit	int	The literal controlling whether this expression is evaluated.	required

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any]) -> bool

Evaluate the expression

Parameters:

Name	Type	Description	Default
evaluations	Evaluations	Current variable evaluations.	required
ctl	PropagateControl	PropagateControl for checking literal assignments and decision levels.	required
env	dict[Any, Any]	Environment for evaluation.	required

Returns:

Name	Type	Description
bool	bool	True if the value has changed, False otherwise.

get_errors

get_errors() -> propagator_warning_t

Return warnings collected while evaluating this value.

Returns:

Name	Type	Description
propagator_warning_t	propagator_warning_t	List of warnings.

reset

reset(dl: int) -> bool

Reset based on decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

Returns:

Name	Type	Description
bool	bool	True if the value was reset; False otherwise.

vars

vars() -> frozenset[Symbol]

Collect variables referenced by the underlying expression.

Returns:

Type	Description
frozenset[Symbol]	frozenset[clingo.Symbol]: Variables referenced by self.expr.

VariableValueRegistry

Intern VariableValue instances.

delete

delete(value: VariableValue) -> bool

Remove the given instance, returning whether it was registered.

Parameters:

Name	Type	Description	Default
value	VariableValue	The VariableValue instance to remove.	required

Returns:

Name	Type	Description
bool	bool	True if the instance was registered and removed; False otherwise.

get_all

get_all() -> list[VariableValue]

Return a snapshot of all interned values.

Returns:

Type	Description
list[VariableValue]	list[VariableValue]: A list of all interned VariableValue instances.

is_evaluation_possible

is_evaluation_possible(var: VariableType | VariableValue) -> bool

Check whether evaluation is possible for this variable by checking the count of evaluated expressions against the total expressions count.

Parameters:

Name	Type	Description	Default
var	VariableType | VariableValue	The variable or variable value to check for evaluation possibility.	required

Returns:

Name	Type	Description
bool	bool	True if evaluation is possible, False otherwise.