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

Annotation

class Annotationsource

An annotation: an identifier and the argument values that go with it.

Annotations carry advice a solver may act on or ignore — a search strategy, an output hint. Attach them to a decision, a constraint or the objective with the annotations argument of the LayeredModel builder, or return them from a custom Model.

fznso.Annotation("output_var")
fznso.Annotation("int_search", [[x, y], "first_fail", "indomain_min"])

propertyarguments

The annotation’s arguments.

propertyident

The annotation identifier, e.g. "output_var".

Constraint

class Constraintsource

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

ConstraintType

class ConstraintTypesource

A constraint solvers from this library implement natively.

propertyargument_types

The type of each argument, in order. A solver may declare a narrower type than the registry does, so check these too.

propertyident

The registry identifier, e.g. "int_lin_le".

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, annotations = None)

Add a constraint with the given identifier and arguments.

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

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

methodmark_permanent()

Mark every current layer as permanent.

methodmark_redundant(layer)

Mark a permanent layer as redundant, letting the solver discard it.

Raises IndexError if the layer is not permanent: only a layer that can never be retracted can be declared vacuous.

methodpop_layer()

Pop the top layer.

methodpush_layer()

Push a new, empty layer.

methodset_objective(ident, argument = None, annotations = None)

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

methodset_unchanged(count)

Declare how many leading layers are unchanged since the last run, so the solver can keep the state it built for them.

This is 0 until you say otherwise, which is always correct but re-reads the whole model every run. Reporting a layer as unchanged when it is not is the one way to get a wrong answer.

methodtruncate(n)

Pop every layer from n upward, keeping layers 0..n.

Raises IndexError if that would pop a permanent layer.

Library

class Librarysource

A loaded solver library.

propertypath

The file this library was loaded from, as given to the constructor or chosen by find.

methodconstraint_types()

The constraints solvers from this library implement natively.

Do not post a constraint that is not in this list, and check the argument types too — a solver may accept one only in a narrower form than the registry declares.

methodcreate_solver()

Create a solver instance.

methoddecision_types()

The decision-variable types solvers from this library can create.

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.

methodobjectives()

The objective strategies solvers from this library implement.

methodoptions()

The options solvers from this library accept, with types and defaults.

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.

methodstatistics()

The statistics solvers from this library report, and where each can be read from.

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_annotations(index)

The Annotations on the constraint at index. Defaults to none.

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_annotations(index)

The Annotations on the decision at index. Defaults to none.

Like the other accessors this borrows: return a list the model owns, not one built for the call.

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

The Annotations on the objective. Defaults to none.

methodobjective_argument()

The objective’s argument, or None.

methodobjective_ident()

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

Objective

class Objectivesource

An objective strategy solvers from this library implement.

propertyargument_type

The type of the objective’s argument.

propertyident

The registry identifier, e.g. "int_minimize".

Option

class Optionsource

An option solvers from this library accept.

propertyargument_type

The type of value the option takes.

attributedefault

The value the option has before anything sets it.

propertyident

The identifier passed to option_set and option_get.

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

Statistic

class Statisticsource

A statistic solvers from this library report.

propertyident

The identifier passed to Solution.statistic or DynSolver.statistic.

propertysolution

Whether it can be read from a solution.

propertysolver

Whether it can be read from the solver instance.

propertyvalue_type

The type of the value reported.

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