Repository navigation
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__)
PYThe last line printed is Status.OPTIMAL 17.01401660197175 17.01236204099385 True followed by the path of the gear package.
| 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.
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.
| 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. |
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.
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.
Problems that are rejected before the search raise a subclass of gr.GearError: ModelError, OptionError, ParseError, UnsupportedModelError, UnsupportedOperatorError, UnsupportedProblemError, LegacyArtifactError.