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.

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, expr: Expr, literal: int, true_lit: int, false_lit: int, bad_lit: int)

Initialize a BoolEvaluateVariable.

Parameters:

Name	Type	Description	Default
name	str	Name of the variable.	required
expr	Expr	Expression to evaluate, expected to yield a boolean value.	required
literal	int	Literal controlling whether this variable is active.	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

add_self_to_evaluations

add_self_to_evaluations(e: Evaluations) -> None

This variable is not added to the evaluation dictionary

Parameters:

Name	Type	Description	Default
e	Evaluations	Evaluations object to update.	required

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any], expr_lits: set[int] | None = None) -> EvaluationResult

Evaluate the expression and return an EvaluationResult.

Parameters:

Name	Type	Description	Default
evaluations	Evaluations	Current variable evaluations.	required
ctl	PropagateControl	PropagateControl	required
env	dict[Any, Any]	Environment for evaluation.	required

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) -> None

Reset based on the decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

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/4 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)

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_self_to_evaluations

add_self_to_evaluations(e: Evaluations) -> None

Add this variable's value into the given Evaluations object.

Parameters:

Name	Type	Description	Default
e	Evaluations	Evaluations object to update.	required

add_value

add_value(key: Expr, expr: Expr, lit: int) -> None

Add a key-value pair to the dict variable.

Parameters:

Name	Type	Description	Default
key	Expr	Expression for the key.	required
expr	Expr	Expression for the value.	required
lit	int	Literal for assignment.	required

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.

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any], expr_lits: set[int] | None = None) -> EvaluationResult

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

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.

reset

reset(dl: int) -> None

Reset based on the decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

simple_evaluate

simple_evaluate(valuations: dict[Symbol, Any], env: dict[Any, Any]) -> set[Multimap[Symbol, Any]]

Evaluate the dict variable with the given valuations and environment, without any checks for decision levels or literal assignments. This function does not change the internal state of the variable.

Returns:

Type	Description
set[Multimap[Symbol, Any]]	set[multimap.Multimap[clingo.Symbol, Any]]: Possible values for the dict variable.

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.

EnsureVariable

Represents an 'ensure' atom, which ensures a certain expression holds. Implements the VariableType protocol.

Attributes:

Name	Type	Description
name	str	Name of the ensure atom.
expression	VariableValue	The VariableValue instance being ensured.
value	ValueStatus | bool	Current value of the expression.
decision_level	int	Decision level at which the value was set.

active_literals property

active_literals: set[int]

Return signed literals that give the current value of the ensure variable.

Returns:

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

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 ensure variable.

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

parents property

parents: list[VariableType]

Return parent variables.

Returns:

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

__init__

__init__(name: str, expr: Expr, literal: int)

Initialize an EnsureVariable.

Parameters:

Name	Type	Description	Default
name	str	Name of the ensure atom.	required
expr	Expr	Expression that must hold.	required
literal	int	Literal controlling whether the ensure atom is active.	required

add_self_to_evaluations

add_self_to_evaluations(e: Evaluations) -> None

Does nothing, as ensure variables are not added to the evaluation dictionary. This is here for compatibility with the VariableType protocol.

Parameters:

Name	Type	Description	Default
e	Evaluations	Evaluations object to update.	required

asses_dependencies_values

asses_dependencies_values(valuations: dict[Symbol, Any], env: dict[Any, Any]) -> dict[Symbol, set[Any]]

Just here to comply with VariableType protocol. Ensure variables already do this part in the propagator itself.

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any], expr_lits: set[int] | None = None) -> EvaluationResult

Evaluate the expression and return a tuple (changed, conflict). changed is True if the value has changed. conflict is True if there is a conflict.

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

Return the current value of the ensure variable.

Returns:

Type	Description
ValueStatus | bool	ValueStatus | bool: 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 ensure variables.

has_unassigned

has_unassigned() -> bool

Check whether the ensure variable is unassigned.

Returns:

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

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.

reset

reset(dl: int) -> None

Reset based on the decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

set_possible_values

set_possible_values(possible_values: set[Any], ctl: PropagateInit) -> None

Just here to comply with VariableType protocol.

simple_evaluate

simple_evaluate(evaluations: dict[Symbol, Any], env: dict[Any, Any]) -> bool

Evaluate the ensure variable without considering decision levels or literals. This is used for preprocessing to determine which values result in either True or Bad.

Parameters:

Name	Type	Description	Default
valuations		Current variable evaluations.	required
env	dict[Any, Any]	Environment dictionary for evaluation context.	required

Returns: dict[clingo.Symbol, set[Any]]: A dictionary mapping the variable's symbolic representation to a set of values that result in either True or Bad.

vars

vars() -> set[Symbol]

Collect variables referenced by the ensure expression.

Returns:

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

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)

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__()

Initialize Evaluations with an empty dictionary.

init

init(variables: Iterable[VariableType])

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

update_evaluations

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

Build a plain Python dictionary from a collection of variables.

The resulting dictionary maps each variable symbol to its evaluated value. Variables that are assigned false are listed under the FALSE_ASSIGNMENTS key.

Parameters:

Name	Type	Description	Default
variables	Iterable[VariableType]	Iterable of variables to export. Variables must implement the add_self_to_evaluations method!	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__()

Initialize an OptimizationHandler.

add_value

add_value(var: Symbol, expr: Expr, lit: int, 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
expr	Expr	Expression to evaluate.	required
lit	int	Associated literal.	required
priority	int	Priority of the optimization sum.	0

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any], expr_lits: set[int] | None = None) -> bool

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

Parameters:

Name	Type	Description	Default
evaluations	Evaluations	Current variable evaluations.	required
ctl	PropagateControl	Clingo propagate control.	required
env	dict[Any, Any]	Evaluation environment.	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)

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, expr: Expr, lit: int) -> None

Add a value to the optimization sum.

Parameters:

Name	Type	Description	Default
var	Symbol	Clingo symbol for the variable.	required
expr	Expr	Expression to evaluate.	required
lit	int	Associated literal.	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(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any]) -> bool

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

Parameters:

Name	Type	Description	Default
evaluations	Evaluations	Current variable evaluations.	required
ctl	PropagateControl	Clingo propagate control.	required
env	dict[Any, Any]	Evaluation environment.	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)

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)

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_self_to_evaluations

add_self_to_evaluations(e: Evaluations) -> None

Add this variable's value into an output dictionary.

Parameters:

Name	Type	Description	Default
e	Evaluations	Evaluations object to update.	required

add_value

add_value(arg: Expr, lit: int) -> None

Add a potential value expression to the set.

Parameters:

Name	Type	Description	Default
arg	Expr	Expression representing one possible set element.	required
lit	int	Literal for the corresponding set_assign/3 atom.	required

asses_dependencies_values

asses_dependencies_values(valuations: dict[Symbol, Any], env: dict[Any, Any]) -> dict[Symbol, set[Any]]

This function is supposed to be used after pruning values with ensures. It looks at the possible values for this variable, then checks which values for the dependencies generate those values. It returns those values

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any], expr_lits: set[int] | None = None) -> EvaluationResult

Evaluate the expression and return an EvaluationResult.

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]

If there is an unassigned value, return None. Otherwise return the set of assigned values without the None values.

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 return an empty set as it does not support any inferences. This is here for compatibility with the VariableType protocol.

reset

reset(dl: int) -> None

Reset based on decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

simple_evaluate

simple_evaluate(valuations: dict[Symbol, Any], env: dict[Any, Any]) -> set[frozenset[Any]]

Evaluate the set variable with the given valuations and environment, without any checks for decision levels or literal assignments. This function does not change the internal state of the variable.

Returns:

Type	Description
set[frozenset[Any]]	set[frozenset[Any]]: Possible values for the set variable.

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.

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(arg: Expr, lit: int) -> None

Add a candidate value to the set.

Parameters:

Name	Type	Description	Default
arg	Expr	Expression for a set element.	required
lit	int	Literal guarding the element.	required

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any], expr_lits: set[int] | None = None) -> bool

Evaluate the expression and return True if the value has changed.

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 None. Otherwise return the set of assigned values without the None 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

TODO

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)

Initialize an EvaluateVariable.

Parameters:

Name	Type	Description	Default
op		Operator to apply.	required
args		Operands for the operator.	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).
lit2expr	dict[int, VariableValue]	Mapping from literal to the corresponding 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)

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_self_to_evaluations

add_self_to_evaluations(e: Evaluations) -> None

Add this variable's value to the evaluation dictionary.

Parameters:

Name	Type	Description	Default
e	Evaluations	Evaluations object to update.	required

add_value

add_value(expr: Expr, value_lit: int, domain_lit: int) -> None

Add a possible value expression for this variable.

Parameters:

Name	Type	Description	Default
expr	Expr	Expression representing a candidate value.	required
value_lit	int	Literal for the value assignment.	required
domain_lit	int	Literal indicating the truth value of the domain/declaration context.	required

add_value_to_expression

add_value_to_expression(expr: VariableValue, val: Any) -> None

Add a value to the list of possible values for a given expression.

Parameters:

Name	Type	Description	Default
expr	VariableValue	The VariableValue expression to which the value should be added.	required
val	Any	The value to add.	required

asses_dependencies_values

asses_dependencies_values(valuations: dict[Symbol, set[Any]], env: dict[Any, Any]) -> dict[Symbol, set[Any]]

This function is supposed to be used after pruning values with ensures. It looks at the possible values for this variable, then checks which values for the dependencies generate those values. It returns the values for the dependencies that can generate the possible values for this variable.

evaluate

evaluate(evaluations: Evaluations, ctl: PropagateControl, env: dict[Any, Any], expr_lits: set[int] | None = None) -> EvaluationResult

Evaluate the expression and return an EvaluationResult.

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)

Return the literal associated with this expression

Parameters:

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

Returns:

Type	Description
	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) -> None

Reset based on decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

set_possible_values

set_possible_values(possible_values: set[Any], ctl: PropagateInit) -> None

Set the possible values for this variable based on the given set of possible values. This function will add nogoods to the propagator to ensure that only the specified values can be assigned to this variable. I.e. Expression that can't produce any value in the list have their literals set to false.

Parameters:

Name	Type	Description	Default
possible_values	set[Any]	Set of possible values for this variable.	required
ctl	PropagateInit	PropagateInit object to add nogoods.	required

simple_evaluate

simple_evaluate(valuations: dict[Symbol, set[Any]], env: dict[Any, Any]) -> set[Any]

evaluate the variable with the given evaluations and environment, without any checks for decision levels or literal assignments. This function does not change the internal state of the variable.

Returns:

Type	Description
set[Any]	set[Any]: Possible values.

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_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_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
variable	VariableType	The VariableType instance to add.	required

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.

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_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_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.

reset

reset(dl: int) -> None

Reset variables based on the decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold for resetting variables.	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)

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)

Reset based on decision level.

Parameters:

Name	Type	Description	Default
dl	int	Decision level threshold.	required

vars

vars() -> frozenset[Symbol]

Collect variables referenced by the underlying expression.

Returns:

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