Python API reference

This page documents the supported public Python API for JijZept Solver.

solve(instance, *, options=None, time_limit=_UNSET, gap_limit=_UNSET, num_threads=_UNSET, presolve=_UNSET, verbosity=_UNSET, display_frequency=_UNSET, initial_state=None, structure=None)

Solve an OMMX optimization problem instance.

This function supports Ctrl+C interruption when running on the Python main thread. When interrupted, it returns the best solution found so far (feasible or infeasible, if any) with a warning, or raises KeyboardInterrupt if there is nothing to return. When called from a non-main thread (e.g. a server worker thread), the solver runs without SIGINT integration: it cannot be interrupted this way and runs until a limit is reached.

Option precedence, lowest to highest: solver defaults, the structure preset, options, then the convenience arguments below. See SolveOptions for every available option.

Parameters:

instance (Any) – The OMMX Instance to solve.
options (jijzept_solver.core.SolveOptions | None) – SolveOptions with detailed solver settings (default None = solver defaults, or the structure preset when structure is set).
time_limit (float | None) – Time limit in seconds. Passing None explicitly selects “no time limit” (overriding options); omitted = no opinion (default: no time limit).
gap_limit (float) – Relative optimality gap tolerance, e.g. 0.01 for 1% (default 0.0001). None is not accepted.
num_threads (int | None) – Number of solver threads. Passing None explicitly selects automatic (overriding options); omitted = no opinion (default: automatic).
presolve (bool) – Enable presolve (default True; False when a TSP structure is set). None is not accepted.
verbosity (int) – Verbosity level: 0 = quiet, 1 = normal, 2 = verbose (default 1). None is not accepted.
display_frequency (int) – Display progress every N nodes, 0 = disabled (default 10). None is not accepted.
initial_state (Any) –
Optional initial solution as ommx.v1.State (default None).
- Missing variables: filled with solver defaults (0 if in bounds, lower otherwise; lower.ceil() for integers).
- Extra variables (not in the instance): silently ignored.
- Out-of-bounds values: clamped.
* Recommendation: use a solution generated in the same environment * Presolve behavior (especially dual reductions) can vary across platforms (CPU architecture, OS, native library build). An initial_state created on one environment (e.g., a development machine) may not work effectively when used on another environment (e.g., a production machine), due to differences in presolve decisions between environments. To avoid this, when using initial_state, prefer using a solution generated by JijZept Solver in the same environment.
structure (jijzept_solver.core.Structure | None) – Structure describing problem structure (default None). Also applies the structure’s recommended option preset; values set in options or passed explicitly override the preset.

Returns:

The OMMX Solution. When no feasible solution was found within the limits, the best infeasible solution the solver encountered (smallest total constraint violation) is returned with solution.feasible == False. Always check solution.feasible before using the values.

Raises:

KeyboardInterrupt – If interrupted by Ctrl+C before any solution (feasible or infeasible) was found. Ctrl+C interruption is available only when solve() runs on the Python main thread.
NoSolutionError – If the solver found no solution at all to return for the termination status. A subclass of RuntimeError; the termination status name is available as the status attribute (e.g. "Infeasible", "TimeLimit").
RuntimeError – If an internal error occurs during solving.
ValueError – If the input instance or an option value is invalid.

Return type:

Any

class SolveOptions

Options for solve().

Every constructor argument defaults to None, meaning “not set”: the solver default is used, or the structure preset value when a structure is passed to solve(). Instances are immutable; derive modified copies with with_overrides.

Seven options default to “no limit” / “automatic”: time_limit, node_limit, solution_limit, num_threads, min_efficacy, max_cuts_per_round, and orthogonality_threshold. For these, passing None to with_overrides explicitly selects that behavior, overriding any value from a lower layer such as an options file.

property time_limit: float | None

Return type:: float | None

property node_limit: int | None

Return type:: int | None

property solution_limit: int | None

Return type:: int | None

property gap_limit: float

Return type:: float

property abs_gap_limit: float

Return type:: float

property verbosity: int

Return type:: int

property display_frequency: int

Return type:: int

property num_threads: int | None

Return type:: int | None

property branching: str

Return type:: str

property min_reliable: int

Return type:: int

property max_sb_candidates: int

Return type:: int

property node_selector: str

Return type:: str

property presolve: bool

Return type:: bool

property presolve_mode: str

Return type:: str

property presolve_dual_reductions: str

Return type:: str

property presolve_threads: int

Return type:: int

property presolve_seed: int

Return type:: int

property no_rounding: bool

Return type:: bool

property no_shifting: bool

Return type:: bool

property enable_int_shifting: bool

Return type:: bool

property enable_random_rounding: bool

Return type:: bool

property enable_zi_rounding: bool

Return type:: bool

property enable_fractional_diving: bool

Return type:: bool

property enable_feasibility_pump: bool

Return type:: bool

property no_rins: bool

Return type:: bool

property no_rens: bool

Return type:: bool

property no_warm_start: bool

Return type:: bool

property no_lp: bool

Return type:: bool

property lp_presolve: bool

Return type:: bool

property enable_alns: bool

Return type:: bool

property alns_max_iter: int

Return type:: int

property alns_time_limit: float

Return type:: float

property alns_patience: int

Return type:: int

property no_root_tightening: bool

Return type:: bool

property no_root_rc_fixing: bool

Return type:: bool

property no_root_sb_init: bool

Return type:: bool

property root_max_tightening_rounds: int

Return type:: int

property root_min_bound_improvement: float

Return type:: float

property root_sb_candidates: int

Return type:: int

property root_max_separation_rounds: int

Return type:: int

property root_min_cut_efficacy: float

Return type:: float

property root_max_cuts_per_round: int

Return type:: int

property root_max_cut_similarity: float

Return type:: float

property root_min_dual_improvement: float

Return type:: float

property root_max_idle_rounds: int

Return type:: int

property cut_selector: str

Return type:: str

property min_efficacy: float | None

Return type:: float | None

property max_cuts_per_round: int | None

Return type:: int | None

property orthogonality_threshold: float | None

Return type:: float | None

property no_miqp_initial_heuristic: bool

Return type:: bool

property miqp_initial_heuristic_num_iters: int

Return type:: int

property miqp_initial_heuristic_time_limit_msec_per_iter: int

Return type:: int

with_overrides(**kwargs)

Return a copy with the given options set on top of this object.

Keyword names and values match the constructor arguments. Passing None explicitly selects the unlimited/automatic behavior for time_limit, node_limit, solution_limit, num_threads, min_efficacy, max_cuts_per_round, orthogonality_threshold; None is rejected for every other option.

Parameters:: kwargs (Any)
Return type:: SolveOptions

to_dict(changed_only=False)

Return the options as a dict.

With changed_only=True only explicitly set options are included; otherwise every option appears with its effective value (the set value or the solver default). An explicit None (unlimited/automatic, set via with_overrides) is omitted from the changed_only dict, exactly as in a file written by to_file: it selects the same behavior as the default.

Parameters:: changed_only (bool)
Return type:: Any

to_file(path)

Write the explicitly set options (only those) to a TOML file.

Parameters:: path (str | os.PathLike | pathlib.Path)
Return type:: None

static from_file(path)

Load options from a TOML file.

Parameters:: path (str | os.PathLike | pathlib.Path)
Return type:: SolveOptions

static write_template(path)

Write a template TOML file listing every option with its default value.

Parameters:: path (str | os.PathLike | pathlib.Path)
Return type:: None

class Structure

Structure of the optimization problem.

Used to automatically select solver strategies and register structural handlers.

static tsp(var_name)

Create a TSP structure (Python factory method).

Parameters:: var_name (str)
Return type:: Structure

static general(fixed_bases)

Create a General structure (Python factory method).

Parameters:: fixed_bases (Sequence[str])
Return type:: Structure

class Tsp

The problem is a Travelling Salesman Problem.

property var_name: str

Name prefix for edge variables in OMMX metadata. Used to build the edge->VarId mapping from OMMX variable subscripts.

Return type:: str

class General

General MIP structure using inference propagation graph. Enables graph-based cooperative worker (GraphHeuristicsWorker).

property fixed_bases: list[str]

Variable base names used as fixed roots in the inference graph.

Return type:: list[str]