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

dataset	PyTorch-style Dataset for XCSP3 competition instances.
globals	Additional global constraints which are not (yet) part of the standard CPMpy collection.

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 (cpmpy.tools.xcsp3.dataset)

PyTorch-style Dataset for XCSP3 competition instances.

Simply create a dataset instance (configured for the targeted competition year/track) and start iterating over its contents:

from cpmpy.tools.xcsp3 import XCSP3Dataset, read_xcsp3

for filename, metadata in XCSP3Dataset(year=2024, track="COP", download=True): # auto download dataset and iterate over its instances
    # Do whatever you want here, e.g. reading to a CPMpy model and solving it:
    model = read_xcsp3(filename)
    model.solve()
    print(model.status())

The metadata contains usefull information about the current problem instance.

Since the dataset is PyTorch compatible, it can be used with a DataLoader:

from cpmpy.tools.xcsp3 import XCSP3Dataset, read_xcsp3

# Initialize the dataset
dataset = XCSP3Dataset(year=2024, track="COP", download=True)

from torch.utils.data import DataLoader

# Wrap dataset in a DataLoader
data_loader = DataLoader(dataset, batch_size=10, shuffle=False)

# Iterate over the dataset
for batch in data_loader:
    # Your code here

class cpmpy.tools.xcsp3.dataset.XCSP3Dataset(root: str = '.', year: int = 2023, track: str = None, transform=None, target_transform=None, download: bool = False)

XCSP3 Dataset in a PyTorch compatible format.

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

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

decompose()

Returns the decomposition

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

decompose()

Returns the decomposition

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

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.

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[Sequence[Expression], Sequence[Expression]]

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

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={})

get_bounds()

has_subexpr()

Does it contains 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)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt, override_print=True, full_print=False)

update_args(args)

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

value()

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

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

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

value()

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

Function returning x if b is True and otherwise y

property args

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 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={})

get_bounds()

Returns the bounds of the global function

Returns:

A tuple of (lower bound, upper bound)

Return type:

tuple[int, int]

has_subexpr()

Does it contains 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)

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, override_print=True, full_print=False)

update_args(args)

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

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

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.

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[Sequence[Expression], Sequence[Expression]]

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

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.

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[Sequence[Expression], Sequence[Expression]]

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

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={})

get_bounds()

has_subexpr()

Does it contains 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)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt, override_print=True, full_print=False)

update_args(args)

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

value()

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

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={})

get_bounds()

has_subexpr()

Does it contains 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)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt, override_print=True, full_print=False)

update_args(args)

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

value()

class cpmpy.tools.xcsp3.globals.NegativeShortTable(array, table)

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

property args

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.

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[Sequence[Expression], Sequence[Expression]]

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

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.

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[Sequence[Expression], Sequence[Expression]]

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

value()

class cpmpy.tools.xcsp3.globals.NonReifiedTable(array, table)

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

decompose()

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

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

value()

property vars

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

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

property args

decompose()

This decomp only works in positive context

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

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={})

get_bounds()

has_subexpr()

Does it contains 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)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt, override_print=True, full_print=False)

update_args(args)

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

value()

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

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={})

get_bounds()

has_subexpr()

Does it contains 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)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt, override_print=True, full_print=False)

update_args(args)

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

value()

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

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={})

get_bounds()

has_subexpr()

Does it contains 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)

is_bool() → bool

is it a Boolean (return type) Operator?

set_description(txt, override_print=True, full_print=False)

update_args(args)

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

value()

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

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.

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[Sequence[Expression], Sequence[Expression]]

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

value()

class cpmpy.tools.xcsp3.globals.RowSelectingShortTable(array, table)

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. This global skips typechecks on the table and has a different decomposition than the standard globalconstraints.ShortTable.

property args

decompose()

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

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

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.

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[Sequence[Expression], Sequence[Expression]]

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

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

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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

decompose()

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

deepcopy(memodict={})

get_bounds()

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

has_subexpr()

Does it contains 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)

is_bool() → bool

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

Returns:

True, global constraints are Boolean

Return type:

bool

negate()

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, override_print=True, full_print=False)

update_args(args)

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

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)