SynAPS

Deterministic-first scheduling engine for MO-FJSP-SDST-ARC production planning.

Language: EN | RU

SynAPS builds explainable, reproducible schedules: named solver configs, auditable metadata, independent feasibility checks, and a benchmark harness.

Reproducibility scope. CP-SAT runs in determinism="strict" by default: a fixed random_seed yields a byte-identical schedule regardless of host speed or CPU load. strict runs single-threaded (a deterministic search order) and stops on max_deterministic_time = 0.5 * time_limit_s — a machine-independent stopping point that is the sole binding limit; the wall clock is only a loose runaway safety (2× the budget). At the measured single-thread wall/deterministic ratio the run finishes within ~1.2× the wall budget, but under heavy CPU load the wall may exceed it — reproducibility is prioritised, and metadata["determinism_violated"] is set if the wall safety, not the deterministic stop, ended the search. (A multi-threaded or wall-bounded stop is inherently non-reproducible under variable load — the original D1/D3 collision; see docs/adr/0001-strict-determinism-single-thread.md.) The ~50% of the search budget traded away is the documented price of reproducibility. Opt into determinism="fast" for the faster multi-threaded non-reproducible portfolio. LBBD collects clusters in a deterministic order. Verified by tests/test_cpsat_determinism.py on a budget-binding instance.

Install

git clone https://github.com/KonkovDV/SynAPS.git
cd SynAPS
python -m pip install -e ".[dev]"

Requires Python ≥ 3.12. Optional Rust acceleration: see native/. HTTP BFF: see control-plane/.

Quick start

# Solve a tiny instance
python -m synaps solve benchmark/instances/tiny_3x3.json

# Compare solvers
python -m benchmark.run_benchmark benchmark/instances/tiny_3x3.json \
  --solvers GREED CPSAT-30 --compare

# List the public portfolio
python -m synaps list-solver-configs

JSON contracts live under schema/contracts/. Examples: schema/contracts/examples/.

Solver portfolio

25 named configs in synaps/solvers/registry.py, routed by synaps/solvers/router.py:

Family	Examples	Role
Constructive	GREED, BEAM-3	Fast feasible baselines
Exact / MIP	CPSAT-*, LBBD-*	Small–medium exact / decomposed
Metaheuristic	ALNS-*	Local search quality
Horizon	RHC-GREEDY, RHC-ALNS, RHC-ALNS-SEARCH-COVER, RHC-GREEDY-COVER	Large instances (10K–100K+ ops)

For full coverage on large instances, prefer RHC-GREEDY-COVER (reserved residual fill). RHC-ALNS is a refine/quality lane, not a completeness guarantee under short timeboxes. RHC-ALNS-SEARCH-COVER combines the search-active DOE geometry with a deterministic coverage-pace guard for 50K+ instances.

What is (and is not) claimed

Shipped: deterministic-first portfolio, stable solve/repair contracts, feasibility checker, CI (Python / TypeScript / Rust), lockfiles + SBOM, Scorecard workflows.

Not claimed: live-factory validation; full feasible 50K under historical ALNS/GREEDY study timeboxes without the coverage-complete path and adequate wall time.

Scale evidence protocol: benchmark/BENCHMARK_EVIDENCE_50K_2026_05_18.md. History: CHANGELOG.md.

Development

ruff check synaps tests benchmark
python -m mypy synaps --strict --no-error-summary
pytest tests/ -q -m "not slow"

cd control-plane && npm install && npm test

See CONTRIBUTING.md, SECURITY.md, RELEASE_POLICY.md.

Documentation

Path	Contents
docs/	Architecture, domains, research notes
benchmark/	Instances, study harness, evidence
control-plane/	Fastify BFF
technical/monitoring/	Grafana / Prometheus examples

Citation

Use CITATION.cff.

License

MIT