Skip to content

Python API

Lemutisme edited this page Nov 7, 2026 · 1 revision

Python API

The package gear (in complete_verifier/gear/) compiles a problem and solves it. PYTHONPATH must contain solver/ and solver/complete_verifier/.

Run from the repository root after the export line of Installation:

export PYTHONPATH=$PWD/solver:$PWD/solver/complete_verifier PYTHONNOUSERSITE=1; ./env/bin/python - <<'PY' 2>&1 | tail -n 8
from pathlib import Path
import gear as gr
c = gr.compile(gr.read_legacy('hs071', root=Path('benchmarks').resolve(), family='gams_world'))
r = gr.solve(c, gr.Options(preset='gear-f0', device='cuda', time_limit=180))
print(r.status, r.primal_bound, r.dual_bound, r.replay.ok, gr.__file__)
PY

The last line printed is Status.OPTIMAL 17.01401660197175 17.01236204099385 True followed by the path of the gear package.

Functions

Call Purpose
gr.read_legacy(name, root=..., family=...) Read one benchmark instance of Dataset (family is "gams_world" or "minlplib_linear").
gr.compile(source, ...) Check and freeze a problem; returns a Compiled. Sources: a benchmark instance, or a torch.nn.Module (see Your Own Problem).
gr.solve(source_or_compiled, options=None, **option_fields) Solve and return a Result.
gr.Solver(options) Holds the options; .solve(src), .solve_many(srcs) (sequential), .on_incumbent(fn) and .on_bound(fn) callbacks.

Callbacks run between batches of the search. An exception raised in a callback ends the solve with termination INTERRUPTED.

A compiled problem is immutable and can be solved repeatedly with different options.

Options

gr.Options is a frozen dataclass. A field left unset takes the value of the preset.

Field Meaning Default
preset "gear-f0" (the configuration of the paper) or a path to a preset file "gear-f0"
time_limit Seconds 180
timing "solve": the limit covers compile, setup and search. "legacy": the limit starts where the command-line runner starts it. "solve"
gap gr.Gap(abs=..., rel=...): the search stops when P - D <= abs or (P - D) / max(1, abs(P), abs(D)) <= rel preset
feas_tol Absolute feasibility tolerance of the returned point 1e-6
device "cpu" or "cuda", "cuda:k" "cuda"
dtype Only "float64" "float64"
batch gr.Batch(domains=int or "auto", gpu_domain_mb=int) preset
seed Random seed 100
advanced Dictionary of dotted configuration keys, validated against the schema; see Configuration {}
log File that receives the solver transcript; None prints to standard output None
verbosity Output level 1

Options.resolved() returns the full effective configuration.

Presets

Preset Content
gear-f0 Default. The same configuration as exp_configs/NLP_solver/f3.yaml of the command line. It uses an LP solver on the CPU and IPOPT in parts of the search.
ref505 The configuration exp_configs/NLP_solver/int3p_final.yaml of an earlier configuration, kept for comparison. A result obtained with it carries the anomaly historical_preset:ref505:a67_off.

The result object

gr.Result is a frozen dataclass.

Field Meaning
status gr.Status: OPTIMAL (gap closed), INFEASIBLE (proved), FEASIBLE (a point, no closed gap), NO_SOLUTION, ERROR
termination gr.Termination: GAP_CLOSED, PROVED_INFEASIBLE, TIME_LIMIT, MEMORY_LIMIT, DOMAIN_ERROR, INTERRUPTED, INTERNAL_ERROR
sense gr.MIN or gr.MAX
primal_bound P, in the sense of the model
dual_bound D, in the sense of the model
gap_abs, gap_rel P - D and (P - D) / max(1, abs(P), abs(D))
x The returned point, a dictionary from variable name to value, or None
replay The returned point re-evaluated on the original problem: ok, feas_tol, max_row_violation, max_bound_violation, worst_row, objective
stats Seconds per phase, number of visited domains, peak GPU memory in MB
provenance What produced the result (below)
anomalies Tuple of strings; empty for a normal solve
solved Property: status is OPTIMAL or INFEASIBLE
to_json() A JSON-serializable dictionary of all fields

replay.ok is true when the point satisfies every constraint and variable bound of the original problem to feas_tol. This is the strict check of Quick Start.

Provenance

result.provenance records how the result was obtained: the source (path, file hashes), compiled_hash, the preset and its preset_sha256, options_hash, timing, the device, the code commit, and the CPU solvers the solve used. Two results with equal provenance used the same problem, options and code.

Errors

Problems that are rejected before the search raise a subclass of gr.GearError: ModelError, OptionError, ParseError, UnsupportedModelError, UnsupportedOperatorError, UnsupportedProblemError, LegacyArtifactError.

Clone this wiki locally