XCSP3 (cpmpy.tools.xcsp3)

Set of utilities for working with XCSP3-formatted CP models.

List of functions

read_xcsp3

Reads in an XCSP3 instance (.xml or .xml.lzma) and returns its matching CPMpy model.

List of helper functions

_parse_xcsp3	Parses an XCSP3 instance file (.xml) and returns a ParserXCSP3 instance.
_load_xcsp3	Takes in a ParserXCSP3 instance and loads its captured model as a CPMpy model.

List of submodules

globals

Additional global constraints which are not (yet) part of the standard CPMpy collection.

class cpmpy.tools.xcsp3.XCSP3Dataset(root: str = '.', year: int = 2024, track: str = 'CSP', transform: Callable | None = None, target_transform: Callable | None = None, download: bool = False, **kwargs: Any)

XCSP3 Dataset in a PyTorch compatible format.

• Origin: https://xcsp.org/instances/

• Reference: Audemard, G., Boussemart, F., Lecoutre, C., Piette, C., Tabary, S. XCSP3: An Integrated Format for Benchmarking Combinatorial Constrained Problems. arXiv:2009.00514, 2020.

Parameters:

• root (str) – Root directory containing the XCSP3 instances (if ‘download’, instances will be downloaded to this location)

• year (int) – Competition year (2022, 2023 or 2024)

• track (str, optional) – Filter instances by track type (e.g., “COP”, “CSP”, “MiniCOP”)

• transform (callable, optional) – Optional transform to be applied on the instance data (the file path of each problem instance)

• target_transform (callable, optional) – Optional transform to be applied on the metadata (the metadata dictionary of each problem instance)

• download (bool) – If True, downloads the dataset from the internet and puts it in root directory

METADATA_EXTENSION: ClassVar[str] = '.meta.json'

categories() → Dict[str, Any]

Labels to distinguish instances into categories matching to those of the dataset. E.g.

• year

• track

citation: ClassVar[List[str]] = ['Audemard, G., Boussemart, F., Lecoutre, C., Piette, C., Tabary, S. XCSP3: An Integrated Format for Benchmarking Combinatorial Constrained Problems. arXiv:2009.00514, 2020.']

collect_instance_metadata(file: Path) → Dict[str, Any]

Extract instance type (CSP/COP) from XCSP3 XML root element.

classmethod dataset_metadata() → Dict[str, Any]

Return dataset-level metadata as a dictionary.

Returns:

The dataset-level metadata.

Return type:

dict

description: ClassVar[str] = 'XCSP3 competition benchmark instances for constraint satisfaction and optimization.'

download()

Download the dataset.

homepage: ClassVar[str] = 'https://xcsp.org/instances/'

instance_metadata(instance: PathLike) → Dict[str, Any]

Return the metadata for a given instance file.

Parameters:

file (os.PathLike) – Path to the instance file.

Returns:

The metadata for the instance.

Return type:

dict

name: ClassVar[str] = 'xcsp3'

classmethod open(instance: PathLike) → TextIOBase

How an instance file from the dataset should be opened. Especially usefull when files come compressed and won’t work with Python standard library’s ‘open’, e.g. ‘.xz’, ‘.lzma’.

Parameters:

instance (os.PathLike) – File path to the instance file.

Returns:

The opened file handle.

Return type:

io.TextIOBase

parse(instance: PathLike) → Any

Parse an instance file into intermediate data structures.

Override this for datasets whose files contain problem data but not an explicit model. Typical outputs are structures like tables, arrays, and dictionaries that can then be passed to a separate model-construction function.

Default behavior is read(instance), i.e. return raw text content.

Parameters:

instance (os.PathLike) – File path to the instance file.

Returns:

The parsed intermediate data structure(s).

read(instance: PathLike) → str

Read raw file contents from an instance file. Handles optional decompression automatically via dataset.open().

Parameters:

instance (os.PathLike) – File path to the instance file.

Returns:

The raw file contents.

Return type:

str

cpmpy.tools.xcsp3.decompress_lzma(path: PathLike) → StringIO

Decompresses a .lzma file.

Parameters:

path – Location of .lzma file

Returns:

Memory-mapped decompressed file

cpmpy.tools.xcsp3.read_xcsp3(path: PathLike) → Model

Reads in an XCSP3 instance (.xml or .xml.lzma) and returns its matching CPMpy model.

Parameters:

path – location of the XCSP3 instance to read (expects a .xml or .xml.lzma file).

Returns:

The XCSP3 instance loaded as a CPMpy model.

Analyze (cpmpy.tools.xcsp3.analyze)

Dataset

The XCSP3 tools can work directly with benchmark instances from the XCSP3 competitions. The XCSP3Dataset class provides a PyTorch-style interface for downloading a competition year and track, iterating over the instance files, and accessing per-instance metadata.

Globals (cpmpy.tools.xcsp3.globals)

Additional global constraints which are not (yet) part of the standard CPMpy collection.

This file contains all the missing global constraints in order to support XCSP3-core, which is a restricted scope of the complete XCSP3 specification (as used for the competitions).

Currently, version 3.2 is supported.

List of classes

AllDifferentLists	Ensures none of the lists given are exactly the same.
AllDifferentListsExceptN	Ensures none of the lists given are exactly the same.
SubCircuit	The sequence of variables form a subcircuit, where x[i] = j means that j is the successor of i.
SubCircuitWithStart	The sequence of variables form a subcircuit, where x[i] = j means that j is the successor of i.
SafeOnlyInverse	Inverse (aka channeling / assignment) constraint.
InverseOne	Inverse (aka channeling / assignment) constraint but with only one array. Equivalent to Inverse(x,x) arr[i] == j <==> arr[j] == i.
Channel	Channeling constraint. Channeling integer representation of a variable into a representation with boolean indicators for all 0<=i<len(arr) : arr[i] = 1 <=> value = i exists 0<=i<len(arr) s.t. arr[i] = 1.
NonReifiedTable	The values of the variables in 'array' correspond to a row in 'table'.
RowSelectingShortTable	Extension of the Table constraint where the table matrix may contain wildcards (STAR), meaning there are no restrictions for the corresponding variable in that tuple.
NegativeShortTable	The values of the variables in 'array' do not correspond to any row in 'table'
MDD	MDD-constraint: an MDD (Multi-valued Decision Diagram) is an acyclic layerd graph starting from a single node and ending in one.
Regular	Regular-constraint (or Automaton-constraint) Takes as input a sequence of variables and a automaton representation using a transition table.
NotInDomain	The "NotInDomain" constraint, defining non-interval domains for an expression
NoOverlap2d	2D-version of the NoOverlap constraint.
IfThenElseNum	Function returning x if b is True and otherwise y
DynamicCumulative	Global cumulative constraint.

List of Solver-native classes

OrtNoOverlap2D	OR-Tools native NoOverlap2D global constraint.
OrtSubcircuit	OR-Tools native SubCircuit global constraint.
OrtSubcircuitWithStart	OR-Tools native SubCircuitWithStart global constraint.
ChocoSubcircuit	Choco's native SubCircuit global constraint.
MinizincSubcircuit	Minizinc's native SubCircuit global constraint.
MinizincSubcircuitWithStart	Minizinc's native SubCircuitWithStart global constraint.

class cpmpy.tools.xcsp3.globals.AllDifferentLists(lists)

Ensures none of the lists given are exactly the same. Called ‘lex_alldifferent’ in the global constraint catalog: https://sofdem.github.io/gccat/gccat/Clex_alldifferent.html#uid24923

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Returns the decomposition

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.AllDifferentListsExceptN(lists, n)

Ensures none of the lists given are exactly the same. Excluding the tuples given in N Called ‘lex_alldifferent’ in the global constraint catalog: https://sofdem.github.io/gccat/gccat/Clex_alldifferent.html#uid24923

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Returns the decomposition

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.Channel(arr, v)

Channeling constraint. Channeling integer representation of a variable into a representation with boolean indicators

for all 0<=i<len(arr) : arr[i] = 1 <=> value = i exists 0<=i<len(arr) s.t. arr[i] = 1

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Returns a decomposition into (a conjunction of) smaller constraints.

The decomposition might create auxiliary variables, it can also use other global constraints as long as it does not create a circular dependency.

To ensure equivalence of decomposition, we split into constraints determining the value of the global constraint, and defining-constraints. Defining constraints (totally) define new auxiliary variables needed for the decomposition, and can always be enforced at top-level.

The decomposition is not allowed to introduce explicit not operators. Instead, use cpmpy.transformations.negation.recurse_negation to push down the negation if you want to negate an expression.

Tip: avoid creating auxiliary variables and use nested expressions instead! (especially, don’t create Booleans but use (iv == v) expressions instead, better for common subexpression elimination!)

Returns:

A tuple containing the constraints representing the constraint value and the defining constraints

Return type:

tuple[list[Expression], list[Expression]]

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.ChocoSubcircuit(arguments)

Choco’s native SubCircuit global constraint.

A subcircuit is a Hamiltonian path between a subset of the nodes of a graph. When a node i is not part of the circuit, it should self-loop with an arc i -> i.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

callSolver(CPMpy_solver, Native_solver)

Call the directname() function of the native solver, with stored arguments replacing CPMpy variables with solver variables as needed.

SolverInterfaces will call this function when this constraint is added.

Parameters:

• CPMpy_solver – a CPM_solver object, that has a solver_vars() function

• Native_solver – the python interface to some specific solver

Returns:

the response of the solver when calling the function

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value() → int | None

class cpmpy.tools.xcsp3.globals.DynamicCumulative(start, duration, end, demand, capacity)

Global cumulative constraint. Used for resource aware scheduling. Ensures that the capacity of the resource is never exceeded. When decomposed, dynamically switches between time-resource and task-resource decompositions depending on size of domains. Equivalent to NoOverlap when demand and capacity are equal to 1. Supports both varying demand across tasks or equal demand for all jobs.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Decomposition from: Schutt, Andreas, et al. “Why cumulative decomposition is not as bad as it sounds.” International Conference on Principles and Practice of Constraint Programming. Springer, Berlin, Heidelberg, 2009.

Heuristically switches between time-resource and task-resource decomposition depending on the relative size of the time horizon and the number of tasks.

If

n = number of tasks t = size of time horizon

then

time-resource decomposition scales with n*t task-resource decomposition scales with 3n(n-1)

thus

switch when t > 3*n

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.IfThenElseNum(b, x, y)

Function returning x if b is True and otherwise y

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose() → tuple[Expression, list[Expression]]

Returns a decomposition into smaller constraints as a tuple of (numerical expression, list of constraints defining auxiliary variables)

The first one will replace the GlobalFunction expression in-place, the second one will be added to the list of top-level constraints.

The decomposition is not allowed to introduce explicit not operators. Instead, use cpmpy.transformations.negation.recurse_negation to push down the negation if you want to negate an expression.

The decomposition might create auxiliary variables and use other global constraints as long as it does not create a circular dependency.

Returns:

A tuple containing the numerical expression and a list of constraints defining auxiliary variables

Return type:

tuple[Expression, list[Expression]]

decompose_comparison(cmp_op, cpm_rhs)

DEPRECATED: returns a list of constraints representing the decomposed comparison of the global function (and any auxiliary variables introduced).

Parameters:

• cmp_op (str) – Comparison operator

• cmp_rhs (Expression) – Right-hand side expression for the comparison

Returns:

A tuple containing two lists: constraints representing the comparison, and constraints defining auxiliary variables

Return type:

tuple[list[Expression], list[Expression]]

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds()

Returns the bounds of the global function

Returns:

A tuple of (lower bound, upper bound)

Return type:

tuple[int, int]

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns:

False, global functions are numeric

Return type:

bool

is_total() → bool

Returns whether it is a total function. If true, its value is defined for all arguments

TODO: I do not find anywhere where we set it dynamically to False? TODO: REMOVE??

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.InverseOne(arr)

Inverse (aka channeling / assignment) constraint but with only one array. Equivalent to Inverse(x,x)

arr[i] == j <==> arr[j] == i

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Returns a decomposition into (a conjunction of) smaller constraints.

The decomposition might create auxiliary variables, it can also use other global constraints as long as it does not create a circular dependency.

To ensure equivalence of decomposition, we split into constraints determining the value of the global constraint, and defining-constraints. Defining constraints (totally) define new auxiliary variables needed for the decomposition, and can always be enforced at top-level.

The decomposition is not allowed to introduce explicit not operators. Instead, use cpmpy.transformations.negation.recurse_negation to push down the negation if you want to negate an expression.

Tip: avoid creating auxiliary variables and use nested expressions instead! (especially, don’t create Booleans but use (iv == v) expressions instead, better for common subexpression elimination!)

Returns:

A tuple containing the constraints representing the constraint value and the defining constraints

Return type:

tuple[list[Expression], list[Expression]]

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.MDD(array, transitions)

MDD-constraint: an MDD (Multi-valued Decision Diagram) is an acyclic layerd graph starting from a single node and ending in one. Each edge layer corresponds to a variables and each path corresponds to a solution The values of the variables in ‘array’ correspond to a path in the mdd formed by the transitions in ‘transitions’. Root node is the first node used as a start in the first transition (i.e. transitions[0][0])

Parameters:

• array – an array of CPMpy expressions (integer variable, global functions,…)

• transitions – an array of tuples (nodeID, int, nodeID) where nodeID is some unique identifiers for the nodes (int or str are fine)

Example

The following transitions depict a 3 layer MDD, starting at ‘r’ and ending in ‘t’ (“r”, 0, “n1”), (“r”, 1, “n2”), (“r”, 2, “n3”), (“n1”, 2, “n4”), (“n2”, 2, “n4”), (“n3”, 0, “n5”), (“n4”, 0, “t”), (“n5”, 1, “t”) Its graphical representation is:

      r
  0/ |1  \2     X
n1   n2   n3
2| /2    /O     Y
 n4     n5
  0\   /1       Z
     t

It has 3 paths, corresponding to 3 solution for (X,Y,Z): (0,2,0), (1,2,0) and (2,0,1)

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Returns a decomposition into (a conjunction of) smaller constraints.

The decomposition might create auxiliary variables, it can also use other global constraints as long as it does not create a circular dependency.

To ensure equivalence of decomposition, we split into constraints determining the value of the global constraint, and defining-constraints. Defining constraints (totally) define new auxiliary variables needed for the decomposition, and can always be enforced at top-level.

The decomposition is not allowed to introduce explicit not operators. Instead, use cpmpy.transformations.negation.recurse_negation to push down the negation if you want to negate an expression.

Tip: avoid creating auxiliary variables and use nested expressions instead! (especially, don’t create Booleans but use (iv == v) expressions instead, better for common subexpression elimination!)

Returns:

A tuple containing the constraints representing the constraint value and the defining constraints

Return type:

tuple[list[Expression], list[Expression]]

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.MinizincSubcircuit(arguments)

Minizinc’s native SubCircuit global constraint.

A subcircuit is a Hamiltonian path between a subset of the nodes of a graph. When a node i is not part of the circuit, it should self-loop with an arc i -> i.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

callSolver(CPMpy_solver, Native_solver)

Call the directname() function of the native solver, with stored arguments replacing CPMpy variables with solver variables as needed.

SolverInterfaces will call this function when this constraint is added.

Parameters:

• CPMpy_solver – a CPM_solver object, that has a solver_vars() function

• Native_solver – the python interface to some specific solver

Returns:

the response of the solver when calling the function

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value() → int | None

class cpmpy.tools.xcsp3.globals.MinizincSubcircuitWithStart(arguments)

Minizinc’s native SubCircuitWithStart global constraint.

This global is the same as SubCircuit, only can a additional start_index be provided which is ensure to be part of the subcircuit.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

callSolver(CPMpy_solver, Native_solver)

Call the directname() function of the native solver, with stored arguments replacing CPMpy variables with solver variables as needed.

SolverInterfaces will call this function when this constraint is added.

Parameters:

• CPMpy_solver – a CPM_solver object, that has a solver_vars() function

• Native_solver – the python interface to some specific solver

Returns:

the response of the solver when calling the function

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value() → int | None

class cpmpy.tools.xcsp3.globals.NegativeShortTable(array: Sequence[Expression] | ndarray, table: Sequence[Sequence[int | Literal['*']] | ndarray] | ndarray)

The values of the variables in ‘array’ do not correspond to any row in ‘table’

property args: tuple[Sequence[Expression] | ndarray, ndarray]

READ-ONLY, the well-tuped arguments of this global constraint

decompose()

Returns a decomposition into (a conjunction of) smaller constraints.

The decomposition might create auxiliary variables, it can also use other global constraints as long as it does not create a circular dependency.

To ensure equivalence of decomposition, we split into constraints determining the value of the global constraint, and defining-constraints. Defining constraints (totally) define new auxiliary variables needed for the decomposition, and can always be enforced at top-level.

The decomposition is not allowed to introduce explicit not operators. Instead, use cpmpy.transformations.negation.recurse_negation to push down the negation if you want to negate an expression.

Tip: avoid creating auxiliary variables and use nested expressions instead! (especially, don’t create Booleans but use (iv == v) expressions instead, better for common subexpression elimination!)

Returns:

A tuple containing the constraints representing the constraint value and the defining constraints

Return type:

tuple[list[Expression], list[Expression]]

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.NoOverlap2d(start_x, dur_x, end_x, start_y, dur_y, end_y)

2D-version of the NoOverlap constraint. Ensures a set of rectangles is placed on a grid such that they do not overlap.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Returns a decomposition into (a conjunction of) smaller constraints.

The decomposition might create auxiliary variables, it can also use other global constraints as long as it does not create a circular dependency.

To ensure equivalence of decomposition, we split into constraints determining the value of the global constraint, and defining-constraints. Defining constraints (totally) define new auxiliary variables needed for the decomposition, and can always be enforced at top-level.

The decomposition is not allowed to introduce explicit not operators. Instead, use cpmpy.transformations.negation.recurse_negation to push down the negation if you want to negate an expression.

Tip: avoid creating auxiliary variables and use nested expressions instead! (especially, don’t create Booleans but use (iv == v) expressions instead, better for common subexpression elimination!)

Returns:

A tuple containing the constraints representing the constraint value and the defining constraints

Return type:

tuple[list[Expression], list[Expression]]

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.NonReifiedTable(array: Sequence[Expression] | ndarray, table: Sequence[Sequence[int] | ndarray] | ndarray)

The values of the variables in ‘array’ correspond to a row in ‘table’. This global represents the non-reified version, meaning that it does not support occuring reified when decomposing. Look at globalconstraints.Table <cpmpy.expressions.globalconstraints.Table for a formulation that does support reification.

property args: tuple[Sequence[Expression] | ndarray, ndarray]

READ-ONLY, the well-tuped arguments of this global constraint

decompose()

This explicit implication-only decomposition is only valid in a non-reified setting.

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.NotInDomain(expr, arr)

The “NotInDomain” constraint, defining non-interval domains for an expression

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

This decomp only works in positive context

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.OrtNoOverlap2D(arguments)

OR-Tools native NoOverlap2D global constraint.

Ensures that all provided rectangles are positioned within a plane whilst not overlapping. The rectangles have their sides aligned with the perpendicular x- and y-axis.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

callSolver(CPMpy_solver, Native_solver)

Call the directname() function of the native solver, with stored arguments replacing CPMpy variables with solver variables as needed.

SolverInterfaces will call this function when this constraint is added.

Parameters:

• CPMpy_solver – a CPM_solver object, that has a solver_vars() function

• Native_solver – the python interface to some specific solver

Returns:

the response of the solver when calling the function

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value() → int | None

class cpmpy.tools.xcsp3.globals.OrtSubcircuit(arguments)

OR-Tools native SubCircuit global constraint.

A subcircuit is a Hamiltonian path between a subset of the nodes of a graph. When a node i is not part of the circuit, it should self-loop with an arc i -> i.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

callSolver(CPMpy_solver, Native_solver)

Call the directname() function of the native solver, with stored arguments replacing CPMpy variables with solver variables as needed.

SolverInterfaces will call this function when this constraint is added.

Parameters:

• CPMpy_solver – a CPM_solver object, that has a solver_vars() function

• Native_solver – the python interface to some specific solver

Returns:

the response of the solver when calling the function

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value() → int | None

class cpmpy.tools.xcsp3.globals.OrtSubcircuitWithStart(arguments, start_index: int = 0)

OR-Tools native SubCircuitWithStart global constraint.

This global is the same as SubCircuit, only can a additional start_index be provided which is ensure to be part of the subcircuit.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

callSolver(CPMpy_solver, Native_solver)

Call the directname() function of the native solver, with stored arguments replacing CPMpy variables with solver variables as needed.

SolverInterfaces will call this function when this constraint is added.

Parameters:

• CPMpy_solver – a CPM_solver object, that has a solver_vars() function

• Native_solver – the python interface to some specific solver

Returns:

the response of the solver when calling the function

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value() → int | None

class cpmpy.tools.xcsp3.globals.Regular(array, transitions, start, accepting)

Regular-constraint (or Automaton-constraint) Takes as input a sequence of variables and a automaton representation using a transition table. The constraint is satisfied if the sequence of variables corresponds to an accepting path in the automaton.

The automaton is defined by a list of transitions, a starting node and a list of accepting nodes. The transitions are represented as a list of tuples, where each tuple is of the form (id1, value, id2). An id is an integer or string representing a state in the automaton, and value is an integer representing the value of the variable in the sequence. The starting node is an integer or string representing the starting state of the automaton. The accepting nodes are a list of integers or strings representing the accepting states of the automaton.

Example

an automaton that accepts the language 0*10* (exactly 1 variable taking value 1) is defined as:

cp.Regular(array = cp.intvar(0,1, shape=4),
        transitions = [("A",0,"A"), ("A",1,"B"), ("B",0,"C"), ("C",0,"C")],
        start = "A",
        accepting = ["C"])

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Returns a decomposition into (a conjunction of) smaller constraints.

The decomposition might create auxiliary variables, it can also use other global constraints as long as it does not create a circular dependency.

To ensure equivalence of decomposition, we split into constraints determining the value of the global constraint, and defining-constraints. Defining constraints (totally) define new auxiliary variables needed for the decomposition, and can always be enforced at top-level.

The decomposition is not allowed to introduce explicit not operators. Instead, use cpmpy.transformations.negation.recurse_negation to push down the negation if you want to negate an expression.

Tip: avoid creating auxiliary variables and use nested expressions instead! (especially, don’t create Booleans but use (iv == v) expressions instead, better for common subexpression elimination!)

Returns:

A tuple containing the constraints representing the constraint value and the defining constraints

Return type:

tuple[list[Expression], list[Expression]]

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.RowSelectingShortTable(array: Sequence[Expression] | ndarray, table: Sequence[Sequence[int | Literal['*']] | ndarray] | ndarray)

Extension of the Table constraint where the table matrix may contain wildcards (STAR), meaning there are no restrictions for the corresponding variable in that tuple. Bit less validation then for globalconstraints.ShortTable; decomposition differs (row-selecting formulation).

property args: tuple[Sequence[Expression] | ndarray, ndarray]

READ-ONLY, the well-tuped arguments of this global constraint

decompose()

Alternative decomposition, similar to element from Gleb’s paper: “Improved Linearization of Constraint Programming Models”

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.SafeOnlyInverse(fwd, rev)

Inverse (aka channeling / assignment) constraint. ‘fwd’ and ‘rev’ represent inverse functions; that is,

The symmetric version (where len(fwd) == len(rev)) is defined as:

fwd[i] == x <==> rev[x] == i

The asymmetric version (where len(fwd) < len(rev)) is defined as:

fwd[i] == x => rev[x] == i

The included decomposition only covers the “safe” variant, meaning that the expressions in fwd are assumed to have a domain within [0, len(rev)[. To also handle the “unsafe” variant, have a look at globalconstraints.Inverse.

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Returns a decomposition into (a conjunction of) smaller constraints.

The decomposition might create auxiliary variables, it can also use other global constraints as long as it does not create a circular dependency.

To ensure equivalence of decomposition, we split into constraints determining the value of the global constraint, and defining-constraints. Defining constraints (totally) define new auxiliary variables needed for the decomposition, and can always be enforced at top-level.

The decomposition is not allowed to introduce explicit not operators. Instead, use cpmpy.transformations.negation.recurse_negation to push down the negation if you want to negate an expression.

Tip: avoid creating auxiliary variables and use nested expressions instead! (especially, don’t create Booleans but use (iv == v) expressions instead, better for common subexpression elimination!)

Returns:

A tuple containing the constraints representing the constraint value and the defining constraints

Return type:

tuple[list[Expression], list[Expression]]

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.SubCircuit(*args)

The sequence of variables form a subcircuit, where x[i] = j means that j is the successor of i. Contrary to Circuit, there is no requirement on all nodes needing to be part of the circuit. Nodes which aren’t part of the subcircuit, should self loop i.e. x[i] = i. The subcircuit can be empty (all stops self-loop). A length 1 subcircuit is treated as an empty subcircuit. Global Constraint Catalog: https://sofdem.github.io/gccat/gccat/Cproper_circuit.html

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Decomposition for SubCircuit A mix of the above Circuit decomposition, with elements from the Minizinc implementation for the support of optional visits: https://github.com/MiniZinc/minizinc-old/blob/master/lib/minizinc/std/subcircuit.mzn

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

class cpmpy.tools.xcsp3.globals.SubCircuitWithStart(*args, start_index: int = 0)

The sequence of variables form a subcircuit, where x[i] = j means that j is the successor of i. Contrary to Circuit, there is no requirement on all nodes needing to be part of the circuit. Nodes which aren’t part of the subcircuit, should self loop i.e. x[i] = i. The size of the subcircuit should be strictly greater than 1, so not all stops can self loop (as otherwise the start_index will never get visited). start_index will be treated as the start of the subcircuit. The only impact of start_index is that it will be guaranteed to be inside the subcircuit. Global Constraint Catalog: https://sofdem.github.io/gccat/gccat/Cproper_circuit.html

property args: tuple[Any, ...]

READ-ONLY access to the expression’s arguments. Use update_args() to update the arguments.

Subclasses can override this property to return a more precisely typed tuple.

decompose()

Decomposition for SubCircuitWithStart. SubCircuitWithStart simply gets decomposed into SubCircuit and a constraint enforcing the start_index to be part of the subcircuit.

decompose_positive() → tuple[list[Expression], list[Expression]]

Positive decomposition of the global constraint, only valid when the constraint is posted toplevel or occurs in a positive nested context. Defaults to the standard decomposition, but subclasses can implement a better version.

deepcopy(memodict={})

DEPRECATED: use copy.deepcopy() instead

Will be removed in stable version.

get_bounds() → tuple[int, int]

Returns the bounds of a Boolean global constraint. Numerical global constraints should reimplement this.

has_subexpr() → bool

Does it contain nested Expressions (anything other than a _NumVarImpl or a constant)? Is of importance when deciding whether certain transformations are needed along particular paths of the expression tree. Results are cached for future calls and reset when the expression changes (in-place argument update).

implies(other: Expression | bool | bool, simplify: bool = False) → Expression

Implication constraint: self -> other.

Python does not offer relevant syntax for implication, call this method instead. For double reification (<->), use equivalence self == other.

Parameters:

• other (BoolExprLike) – the right-hand-side of the implication

• simplify (bool) – if True, simplify by eliminating True/False constants (might remove expressions & their variables from user-view)

Returns:

the implication constraint or a BoolVal if simplified

Return type:

Expression

Simplification rules:

• self -> True :: BoolVal(True)

• self -> False :: ~self (Boolean inversion)

is_bool() → bool

Returns whether the global constraint is a Boolean (return type) Operator.

Returns:

True, global constraints are Boolean

Return type:

bool

negate() → Expression

Returns the negation of this global constraint. Defaults to ~self, but subclasses can implement a better version, > Fages, François, and Sylvain Soliman. Reifying global constraints. Diss. INRIA, 2012.

set_description(txt: str, override_print: bool = True, full_print: bool = False) → None

update_args(args: Iterable[Any], has_subexpr: bool | None = None) → None

Allows in-place update of the expression’s arguments. Resets all cached computations which depend on the expression tree.

• args (Iterable[Any]): new arguments

• has_subexpr (Optional[bool]): provide this if you know the answer already, to avoid computing it

value()

cpmpy.tools.xcsp3.globals.is_transition(arg)

test if the argument is a transition, i.e. a 3-elements-tuple specifying a starting state, a transition value and an ending node

Solution (cpmpy.tools.xcsp3.xcsp3_solution)

CLI (cpmpy.tools.xcsp3.xcsp3_cpmpy)

Benchmark (cpmpy.tools.xcsp3.benchmark)