Python bindings

The fznso module, built with maturin from python/src/lib.rs.

Values are ordinary Python objects: a range or int_set for a domain, an int, a Decision, a list. See Using a solver.

Classes

Constraint

class Constraintsource

A reference to a constraint, returned by LayeredModel.add_constraint.

Decision

class Decisionsource

A reference to a decision variable, returned by LayeredModel.add_decision.

Discovered

class Discoveredsource

A solver library found on the search path, reported without loading it.

propertyname

The solver’s name, derived from the file name.

propertypath

The full path to the library.

propertyversion

The version parsed from the file name, or empty if it carries none. Compared component-wise, so 10 is newer than 9.

DynSolver

class DynSolversource

A solver instance created from a Library.

methodoption_get(name)

The current value of a named option.

methodoption_set(name, value)

Set a named option. Raises ValueError with the solver’s message on failure.

methodrun(model, on_solution = None, on_message = None, should_stop = None)

Run the solver over model, calling on_solution for each solution and on_message for each diagnostic. Returns the completion status, or raises RuntimeError if the solver reports an error.

model may be a LayeredModel built with the builder, or any object implementing the Model protocol.

should_stop, if given, is polled by the solver and ends the search when it returns a truthy value; the run then reports Status.Incomplete. Use it to cancel from a watchdog thread. It may be called from several solver threads at once, so keep it cheap and thread-safe.

methodstatistic(name)

The current value of a named solver-level statistic, or None if the solver does not report it.

FloatSet

class FloatSetsource

A float set, an ordered union of inclusive [min, max] ranges.

IntSet

class IntSetsource

An integer set, an ordered union of inclusive [min, max] ranges.

LayeredModel

class LayeredModelsource

A model to hand to a solver.

Decisions and constraints are added to the current layer. Layers can be pushed, popped and committed for incremental solving.

methodadd_constraint(ident, arguments, defines = None)

Add a constraint with the given identifier and arguments.

methodadd_decision(ty, domain = None, name = None, defined = False, in_solution = True)

Add a decision variable of the given type and domain, returning its handle.

methodmark_permanent()

Mark every current layer as permanent.

methodpop_layer()

Pop the top layer.

methodpush_layer()

Push a new, empty layer.

methodset_objective(ident, argument = None)

Set the objective. Pass no identifier for a satisfaction problem.

Library

class Librarysource

A loaded solver library.

methodcreate_solver()

Create a solver instance.

static methoddiscover()

List the solver libraries on the search path, without loading any.

Directories are visited in search_paths order and, within one directory, the highest version of a solver comes first. Nothing is opened, so the ABI version is not checked here; find skips solvers built for another ABI.

static methodfind(name, version = None)

Load a solver by name from the search path.

Without a version the newest is chosen, preferring earlier directories. A version selects by whole dotted components, so "6" matches 6.2.1 and "6.2" matches 6.2.1 but not 6.1.0.

Raises RuntimeError if no matching solver is installed, naming the directories that were searched.

static methodsearch_paths()

The directories searched for solver libraries, in search order.

Solvers live in a directory of their own rather than on the normal library path. The order is $FZNSO_SOLVER_PATH, then the per-user directory, then the system directories.

Model

class Modelsource

Base class for a model implemented in Python.

Subclass it and override the methods your model needs; the rest describe an empty model. Values are ordinary Python objects (a range or int_set for a domain, an int, a Decision, a list, and so on).

The model is read on demand while the solver runs, and the values and strings it returns are borrowed, not copied. The model must therefore keep them alive for the whole run: return objects it owns — for example stored on the instance — rather than freshly built temporaries.

By default a custom model is a single permanent layer. Override the layer_* methods to expose several layers for incremental solving, or use LayeredModel to build one directly.

methodconstraint_arguments(index)

The arguments of the constraint at index, as a list of values.

methodconstraint_count()

The number of constraints.

methodconstraint_defines(index)

The decision the constraint at index defines, if any.

methodconstraint_ident(index)

The identifier of the constraint at index.

methodconstraint_layer_end(layer)

One past the global index of the last constraint in layers 0..=layer. Defaults to every constraint living in a single layer.

methoddecision_count()

The number of decision variables.

methoddecision_defined(index)

Whether the decision at index is defined by a constraint.

methoddecision_domain(index)

The domain of the decision at index, or None for no explicit domain.

methoddecision_in_solution(index)

Whether a solution may be asked for the value of the decision at index. A model that does not say assumes every decision may be, which is the safe answer: a solver then assigns them all.

methoddecision_layer_end(layer)

One past the global index of the last decision in layers 0..=layer. Defaults to every decision living in a single layer.

methoddecision_name(index)

The name of the decision at index, if any.

methoddecision_type(index)

The type of the decision at index.

Unlike the other accessors this has no sensible default: a decision’s type is exactly what cannot be worked out from anything else it reports, so a model that declares decisions has to say what they are.

methodlayer_count()

The number of layers in the model. Defaults to a single layer.

methodlayer_permanent()

The number of permanently committed layers (the solver will not pop these). Defaults to all layers being permanent.

methodlayer_redundant()

The layer indices of permanent layers that are redundant. Defaults to none.

methodlayer_unchanged()

The number of trailing layers unchanged since the last run, for incremental reuse. Defaults to none.

methodobjective_argument()

The objective’s argument, or None.

methodobjective_ident()

The objective identifier, or "" for a satisfaction problem.

Solution

class Solutionsource

A solution reported to the on_solution callback.

Valid only during that callback; using it afterwards raises an error.

methodstatistic(name)

A named statistic for this solution.

methodvalue(decision)

The value assigned to a decision variable (a Decision or an index).

Status

class Statussource

The outcome of a run.

attributeComplete

The outcome of a run.

attributeIncomplete

The outcome of a run.

Type

class Typesource

A value type: a base type plus the qualifiers that apply to it.

Any type the interface can carry is expressible. Name the qualifiers you want as keyword arguments:

fznso.Type("int", decision=True)                # var int
fznso.Type("int", decision=True, set_of=True)   # var set of int
fznso.Type("bool", list_of=True)                # list of bool

The Rust and C++ bindings spell this as a builder, because neither has keyword arguments. Each qualifier is readable back under the name it was given, so a type can be taken apart and rebuilt.

propertybase

The base type: "bool", "int", "float" or "string".

propertydecision

Whether this type is a decision variable rather than a parameter.

propertylist_of

Whether this type is a list of its element type.

propertyopt

Whether this type also permits the absent value.

propertyset_of

Whether this type is over sets of its base type.

Functions

float_set

float_set(min, max)source

A float set covering the inclusive range [min, max].

int_set

int_set(min, max)source

An integer set covering the inclusive range [min, max].