API Reference

Module providing the Solver class to launch and monitor solver executions on XCSP3 instances.

It supports: - Managing solver options (time limit, seeds, solution limits, etc.) - Capturing solver outputs (objective values, assignments) - Enforcing timeouts - Building JSON or human-readable results - Displaying execution summaries with wall-clock and CPU times

class xcsp.solver.solver.CheckStatus(value)

Bases: Enum

An enumeration.

INVALID = 'INVALID'

NO_CHECK = 'NO CHECK'

VALID = 'VALID'

class xcsp.solver.solver.ResultStatusEnum(value)

Bases: Enum

Enum representing standard solver statuses such as SATISFIABLE, UNSATISFIABLE, UNKNOWN, and OPTIMUM FOUND.

ERROR = 'ERROR'

MEMOUT = 'MEMOUT'

OPTIMUM = 'OPTIMUM FOUND'

SATISFIABLE = 'SATISFIABLE'

TIMEOUT = 'TIMEOUT'

UNKNOWN = 'UNKNOWN'

UNSATISFIABLE = 'UNSATISFIABLE'

class xcsp.solver.solver.Solver(name, id_solver, version, command_line, options, alias=None)

Bases: object

Class representing a solver execution context for an XCSP3 model. Allows setting solver options, running the solver, and capturing results.

add_complementary_options(options)

Manually set additional command-line options for the solver.

This method replaces any previously set complementary options with the new list provided.

Parameters:

options (list of str) – A list of additional command-line arguments to be passed to the solver.

property alias

Return a list of aliases for the solver.

all_solutions(activate: bool)

Enable or disable collecting all solutions found by the solver.

Parameters:

activate (bool) – True to collect all solutions.

static available_solvers() → Dict[str, Solver]

Retrieve all available solvers installed in the system.

Returns:

Mapping of name@version to Solver instances.

Return type:

dict

property cmd

Return the base command line of the solver.

static create_from_cli(args)

Create and configure a Solver instance based on parsed CLI arguments.

Parameters:

args (dict) – CLI arguments parsed with argparse or similar.

Returns:

Configured Solver instance.

Return type:

Solver

property id

Return the solver ID.

static lookup(name: str) → Solver

Retrieve a Solver instance by name and optional version.

Parameters:

name (str) – Name or name@version of the solver.

Returns:

The corresponding solver instance.

Return type:

Solver

Raises:

ValueError – If the solver is not found.

property name

Return the name of the solver.

objective_value()

set_collect_intermediate_solutions(activate: bool)

Enable or disable collecting intermediate assignments during search.

Parameters:

activate (bool) – True to collect intermediate solutions.

set_delay(delay: int)

set_error(error)

Set where to redirect standard error output (stderr).

Parameters:

error (str or Path) – Either “stderr” or a file path.

set_is_timeout(is_timeout: bool)

Set whether the solver run was interrupted by a timeout.

Parameters:

is_timeout (bool) – True if the run was interrupted by a timeout.

set_json_output(activate)

Enable or disable JSON output mode instead of live printing.

Parameters:

activate (bool) – True to generate JSON output.

set_limit_number_of_solutions(limit: int | None)

Set the maximum number of solutions to retrieve.

Parameters:

limit (int | None) – Maximum number of solutions, or None for unlimited.

set_output(output)

Set where to redirect standard output (stdout).

Parameters:

output (str or Path) – Either “stdout” or a file path.

set_prefix(prefix)

Set a prefix to prepend to each line of solver output.

Parameters:

prefix (str) – Prefix string.

set_seed(seed: int | None)

Set the random seed for the solver.

Parameters:

seed (int | None) – Random seed value.

set_time_limit(time_limit: int | None)

Set the time limit (timeout) for the solver.

Parameters:

time_limit (int | None) – Time limit in seconds, or None for unlimited.

solve(instance_path, keep_solver_output=False, check=False, delay=5)

Launch and monitor the solver on the given instance.

Captures intermediate objectives and solutions, enforces a timeout, and returns parsed results.

Parameters:

• instance_path (str | Path) – Path to the XCSP3 instance file.

• keep_solver_output (bool) – If True, solver stdout is printed live.

• check (bool) – If True, checks the final solution using a solution checker.

Returns:

A dictionary summarizing the solver run including solutions, bounds, times.

Return type:

dict

status() → ResultStatusEnum

property version

Return the solver version.