From ffd0187fbb993ff100f5e029fa29aae6250fe6e4 Mon Sep 17 00:00:00 2001 From: AJ Isaacs Date: Thu, 24 Sep 2026 12:32:42 -0400 Subject: [PATCH] docs(template): add BENCH-RULES.md for engine-building runs Rules for the runs were being made up mid-run (git for rollback, access to the real-part drawing archive), so each model started under a different rule set. BENCH-RULES.md writes them down in one place, stamped into every new engine, so all models work under the same rules: workspace limits and no searching for other engines, git init plus commit-per-working-state, the archive as read-only with nothing customer-identifying kept in the (publishable) engine folder, tests may only be added to, and what the final report must cover. Co-Authored-By: Claude Opus 5.5 --- README.md | 3 +- _Template/BENCH-RULES.md | 60 ++++++++++++++++++++++++++++++++++++++++ _Template/README.md | 3 ++ 3 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 _Template/BENCH-RULES.md diff --git a/README.md b/README.md index d19b692..0e0707d 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,8 @@ Each engine's README covers its algorithm and benchmark results. ``` This copies `_Template/` to `OpenNest.Engine.Nova/`: an `INestingEngine` stub, a README -spelling out what counts as an independent engine, and starter acceptance tests checked by +spelling out what counts as an independent engine, `BENCH-RULES.md` (how a model's run +works: workspace limits, git, the real-part archive, reporting), and starter acceptance tests checked by the benchmark's own `NestValidator` (they fail until `Solve()` is implemented). To work inside an OpenNest checkout instead, stamp it into an `Engines/` folder there and diff --git a/_Template/BENCH-RULES.md b/_Template/BENCH-RULES.md new file mode 100644 index 0000000..4b30461 --- /dev/null +++ b/_Template/BENCH-RULES.md @@ -0,0 +1,60 @@ +# Bench rules + +These rules apply to every model building or optimizing an OpenNest engine, so results can be +compared fairly. `README.md` in this folder covers what counts as an independent engine; this +file covers how the run itself works. + +## Your workspace + +- You are working in a copy of OpenNest. Your engine is `Engines/OpenNest.Engine.__NAME__/`. +- Work only inside this copy. Do not search the rest of the filesystem, other checkouts of + OpenNest, the network, or any git remote for other nesting engines or earlier versions of + this project. Using another engine's code or results in any form is disqualifying. +- Do not edit `OpenNest.Core`, `OpenNest.Engine`, `OpenNest.Benchmark` or anything else outside + your engine folder, except for throwaway tools under `tools/` and scratch work under + `bench-local/` (see below). If shared code has a bug that blocks you, work around it in your + engine and describe the bug in your report. + +## Version control + +- At the start, if this copy is not already a git repository, run `git init` in the copy's root + and commit everything as `Initial bench copy` before changing anything. +- Commit every time the engine reaches a working state (it builds and the tests pass), with a + message that says what changed and why, plus any benchmark numbers you measured. +- When an experiment makes things worse, go back to the last good commit rather than + patching forward. Do not rewrite or squash history; the commit log is part of the record + of your run. +- Do not add a git remote or push anywhere. + +## Real parts + +- Real production drawings are available read-only at `/mnt/rogers/PEP Drawings/Archive`. + Use them to build realistic benchmark jobs. +- Never modify, move or delete anything in the archive. +- Do not copy DXF files into your engine folder, and do not commit archive paths, file names or + part numbers inside your engine folder. The engine folder may be published; these drawings + are customer property. Keep manifests, results and notes that reference the archive under + `bench-local/` in the copy's root instead. +- Final scoring also uses jobs you will not see. Tune for real parts in general, not for the + specific drawings you tested with. + +## Tests and scoring + +- Keep the starter tests in `tests/` and keep them passing. Add tests; do not weaken, + skip or delete existing ones. If you believe an existing test is wrong, leave it and explain + why in your report. +- Engines are scored by `OpenNest.Benchmark`. Every layout goes through `NestValidator`; an + invalid layout places nothing and pays the unplaced-part penalty, so validity comes before + utilization. +- Benchmark with `--parallel 1` whenever you report timing. + +## Your report + +When you finish, update `README.md` in your engine folder to replace the template text with: + +- the algorithm and why you chose it, +- what you tried that did not work, +- benchmark results (synthetic jobs only in the README; real-part results go in + `bench-local/`), +- any shared-code bugs or improvements you found, with measured numbers, so they can be + upstreamed. diff --git a/_Template/README.md b/_Template/README.md index 74d22cc..7188d85 100644 --- a/_Template/README.md +++ b/_Template/README.md @@ -11,6 +11,9 @@ several of them and keep the best result. The decisions that make it an engine must be yours: which sheet(s) to use, which parts go where and in what order, which pattern/strategy to apply to which region, and when to stop. +**Read `BENCH-RULES.md` before starting.** It covers your workspace, version control, the +real-part drawing archive, tests and your final report. + ## Allowed building blocks Reuse is encouraged. These are tools you drive, composed by your own decision logic: