Engines and determinism

Which engine to pick, why results repeat, and how to discover what a deployment serves.

Engines

• heuristic (default) — the guillotine multi-strategy packer. Highest yield, every layout saw-cuttable, always a full cutPlan.
• balanced — a MaxRects free-nesting packer. Much faster on large jobs (measured ~25× at 2,000 parts) for a small yield cost, and its layouts are often not guillotine (guillotineValid: false, cutPlan: null). It does not model tolerance, minimizeCost, grainGroup, maxCutStages or minimizeRotations — set one and a warning tells you it was ignored.
• max — the asynchronous tier. On 2D it is a tree search that reaches the proven optimum on far more jobs at the cost of seconds-to-a-minute per solve. Still deterministic and guillotine-valid. It does not return a plan directly — see Async jobs below.

  It models ONE stock format at full sheet size with unlimited supply and a fixed 3-stage guillotine pattern, so a second stock row, trim, respectStock, material, grainGroup or a non-empty matchedSets is refused with 400 before a call is reserved; tolerance, minimizeCost, maxCutStages, minimizeRotations, firstCut and effort go through but are ignored with a warning, and a max result reports no offcuts.

  Send those jobs to heuristic. On true-shape nesting (POST /v1/optimize/nest) max runs the lbf pass first and then searches, within options.timeBudgetMs (60 s by default, 10–180), for a layout with fewer sheets — never more; its nests carry deterministic: false.

  There it accepts several sheet sizes per material and respectStock, and keeps its result only when it ranks better than lbf’s (by price with minimizeCost, otherwise by sheet area); a polygon sheet or exclusion zones are served by lbf inside the job, with a warning.

Determinism & versioning

Every response carries engineVersion. The algorithms are deterministic (the one exception, the time-limited nesting max search, reports deterministic: false), so improving one changes output for the same input — which is a breaking change if you cache. Pin behaviour by sending engine explicitly and watching engineVersion; the path version /v1/ only changes if the response shape changes.

Each engine versions independently, so a change to one never moves the other's version.

GET /v1/health

{
  "status": "healthy",
  "service": "cutoptim-engine",
  "contractVersion": "1",
  "engineVersion": "1.0.0+10e0c941",
  "engines": ["heuristic", "balanced"],
  "modes": ["2d", "1d", "wood", "nest"],
  "nestEngines": ["lbf", "max"],
  "maxEngines": ["max"],
  "uptimeSec": 16
}

No key, no quota, no database. It deliberately touches nothing stateful, so an outage in the key store cannot make the service look dead to an orchestrator. engines lists the ids this deployment accepts in engine, and engineVersion is the default engine’s version.

Is an engine down? The status page shows the live state of the website, the Engine API, the nesting engine and the async max engine: Service status ↗