nc-gcode-interpreter 0.2.7__tar.gz → 0.2.8__tar.gz

nc_gcode_interpreter-0.2.8/.github/workflows/benchmark.yml

@@ -0,0 +1,41 @@
+name: Benchmark
+on:
+  workflow_dispatch:
+    inputs:
+      lines:
+        description: Space-separated synthetic line counts
+        default: '100000 400000'
+        required: true
+      samples:
+        description: Warm samples per case
+        default: '5'
+        required: true
+permissions:
+  contents: read
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+      - name: Run correctness gates
+        run: cargo test --features bench-experiments
+      - name: Differential benchmark smoke test
+        run: python scripts/benchmark.py --lines 1000 --shapes flat --edits coordinate parameter insert delete --threads 1 --blocks 64 --samples 1 --verify-digest --output benchmark-smoke.json
+      - name: Record baseline and experiments
+        env:
+          BENCH_LINES: ${{ inputs.lines }}
+          BENCH_SAMPLES: ${{ inputs.samples }}
+        run: python scripts/benchmark.py --lines $BENCH_LINES --samples "$BENCH_SAMPLES" --output benchmark-results.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: benchmark-results
+          path: |
+            benchmark-results.json
+            benchmark-smoke.json

{nc_gcode_interpreter-0.2.7 → nc_gcode_interpreter-0.2.8}/.github/workflows/build-and-release.yml

@@ -54,7 +54,7 @@ jobs:
       - name: Check Rust formatting
         run: cargo fmt --check
       - name: Run Rust unit and integration tests
-        run: cargo test
+        run: cargo test --features bench-experiments
 
   linux-x64:
     needs: [lint]

{nc_gcode_interpreter-0.2.7 → nc_gcode_interpreter-0.2.8}/CHANGELOG.md

@@ -4,6 +4,169 @@ Notable changes to **nc-gcode-interpreter**. The format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); versions are git tags,
 released to PyPI.
 
+## [v0.2.8] - 2026-10-15
+
+### Added
+
+- `MATCH` and `MINDEX` string search functions (manual 4.1.4.6), next to
+  `INDEX`/`RINDEX`: `MATCH` returns the 0-based position of a substring,
+  `MINDEX` that of the first character found in a character list; both return
+  `-1` when nothing matches (#64).
+
+- The `<<` operator is accepted in function-argument position, including the
+  prefix form with no left operand, which is the implicit conversion to STRING
+  (manual 4.1.4.1). Real programs write `MATCH(<machine data>, <<NAME)` in an
+  IF condition; that line used to be a parse error (#64).
+
+- Programmable frame rotations `ROT` and `AROT`, with `X.. Y.. Z..` angles or
+  the planar form `RPL=`, on top of the existing `TRANS`/`ATRANS` offsets
+  (#68). The geometry axes X, Y, Z are output as machine coordinates under a
+  rotation matrix plus translation (machine = R * local + t); every other axis
+  keeps its plain offset, so programmed A/B/C orientations are never rotated.
+  The semantics follow the Sinumerik frame chapters (NC programming manual
+  3.12.2.1 and 3.12.2.4, Basic Functions manual 4.5.2.3 and 4.5.2.4): `ROT`
+  and `TRANS` are both absolute and each deletes the whole programmable frame,
+  so a `TRANS` after `AROT` drops the rotation and a `ROT` after `TRANS` drops
+  the offset; `AROT` chains onto the current frame; several angles in one
+  block are RPY angles executed Z, then Y', then X'' (MD10600
+  FRAME_ANGLE_INPUT_MODE = 1, the default; the Euler ZX'Z'' mode is out of
+  scope); `RPL` turns about the normal of the active G17/G18/G19 plane;
+  `ATRANS` after a rotation offsets in the rotated system. `IC()` increments
+  stay in local coordinates. G2/G3 arcs (I/J/K and CR forms, TURN) are
+  supported while the rotation keeps the arc plane equal to the machine plane
+  (RPL, or a rotation about the plane normal): the centre offsets are rotated
+  with the frame and the flattener works unchanged. An arc under a rotation
+  that tilts the plane, `RPL=` mixed with axis angles, angles on non-geometry
+  axes, and the still unmodeled `ROTS`/`AROTS`/`CROTS`, `SCALE`/`ASCALE` and
+  `MIRROR`/`AMIRROR` all raise with line context. The final state dict gains a
+  `rotation` entry (row-major 3x3 list); `translation` keeps its meaning. The
+  fast path and the streaming/batch APIs mirror the whole-file interpreter.
+
+### Changed
+
+- Jump-free programs of 64 MiB or more on the fast path no longer keep every
+  decoded line in memory. A parallel preflight scan validates the whole
+  program first (a parse error anywhere, also after `M30`, is still reported
+  before any row is emitted), then execution decodes and parses one line at a
+  time, so parse storage is bounded by the longest line instead of the program
+  length. Peak RSS of `nc_to_batches` on a 1.28M-line (112 MB) field program
+  drops from about 1.3 GiB to 0.4 GiB, and on a 22M-line (1.1 GB) one from
+  5.4 GiB to 2.4 GiB; the second decode costs up to about 20 percent of
+  interpretation time. Below 64 MiB the indexed path stays: its retained state
+  is at most about 0.7 GiB there, and the second decode would cost the most
+  relative time. `NC_STREAM_MIN_BYTES` sets the threshold in bytes (0 streams
+  every jump-free program). Programs with a jump keep the indexed path at any
+  size (#73).
+
+- The fast path builds its jump-target index (one `N:` key per block number,
+  one `LABEL:` key per label) only when a grammar-bound line mentions GOTO.
+  Trivial lines can never carry a jump, so a program without one skips the
+  allocation entirely; a GOTO inside a comment merely builds an unused index.
+  About 40 % less time on a 400k-line straight-line program (#73).
+
+- A frame instruction no longer moves the interpreted position. `TRANS`,
+  `ATRANS`, `ROT` and `AROT` hold the machine position of every positioned
+  axis and re-derive its local (workpiece) coordinate under the new frame, as
+  a control does when a frame becomes active (Basic Functions manual 4.5.11:
+  `$AA_IM` is the machine setpoint, `$AA_IW` the workpiece one). So a block
+  after the frame change that programs only some axes moves the others only
+  through the rotation, `$AA_IM` agrees with the output rows, `$AA_IW` reports
+  the re-derived value, and an `IC()` increment after a `TRANS` moves from the
+  current position (NC programming manual 3.1.1.5) instead of jumping by the
+  offset; `examples/trans2.csv` changes accordingly. A geometry axis that a
+  rotation couples to a positioned axis before any block positioned it is
+  taken at machine 0 (with a warning) from then on, so it can be read with
+  `$AA_IM` and appears in the rows.
+
+- `scripts/compare_benchmarks.py` refuses to compare reports recorded on
+  different inputs or, when both were recorded with `--verify-digest`, with
+  differing row counts or output/state digests in any matched case (#76).
+
+- A control-structure keyword must stand alone in its block (#84). The
+  grammar accepted statements on the same line and ran them as part of the
+  body: `WHILE R1<3 X1` (likewise after `LOOP`, `REPEAT`, `FOR ... TO ...` and
+  `ELSE`) ran `X1` as the first body block of every pass, and a mid-line
+  `X1 ELSE X2` ended the true branch. The NC programming manual (4.1.7) shows
+  every structure keyword in a block of its own and does not say a control
+  accepts more, so these forms are now parse errors that name the text to
+  move. A comment after the keyword and a block number before it are still
+  allowed. A closer after other content (`X1 ENDIF`) is reported at the closer
+  instead of as "IF is never closed". A jump label on a structure line
+  (`LB: WHILE R1<3`, `LB: ENDIF`) is rejected too, as a real control does with
+  alarm 12630; a conditional jump (`LB: IF R1<3 GOTOB LB`) is no structure and
+  keeps its label.
+
+### Fixed
+
+- Flattened `BSPLINE` samples now carry the line number of the control-point
+  block they belong to, instead of all carrying the last control point's line.
+  `ASPLINE`/`CSPLINE` and G2/G3 already attributed their samples per segment,
+  so a simulator that highlights the executing line from `line_no` stuck on
+  one line for a B-spline and walked through the control-point lines for
+  every other curve. The curve is now split at the Greville abscissae of the
+  clamped knot vector: a sample belongs to the first control point whose
+  Greville abscissa is at or beyond the sample's parameter, the last control
+  point taking the remainder. Between its Greville abscissae a control point
+  is the one with the most influence on the curve, and for degree 1 the rule
+  reduces to the polyline segment ending at each programmed point. The
+  sampled geometry is unchanged (same coordinates, order and count), only the
+  `line_no` distribution changes: the auxiliary cells of a control-point
+  block (feed, M codes, comments) now ride on its first sample, and a block
+  that owns samples no longer emits an aux-only placeholder row. Only the
+  curve end stays a programmed position; every other sample keeps
+  `flattened = 1`. The checked-in `examples/flattening/flatten_demo_flattened.csv`
+  is regenerated accordingly (#62).
+
+- Two statements glued onto one line with no separator (`... = SET(...)DEF INT
+  ...`, a copy-paste defect seen in a real program) are still rejected, but
+  the error now names the trailing text and points at the column where the
+  second statement starts, instead of "expected the end of the program". The
+  INDEX-based single-character write from the same report has worked since
+  v0.2.6 and is now pinned by a test (#58).
+
+- Reading an array element or indexed system variable that was never assigned
+  reported "Invalid array index ... used as an array index"; the message now
+  says the element is undefined and how to supply it. It still names the
+  variable and the line, so an unknown string-typed machine data in a string
+  argument is a loud error rather than a silent empty string (#64).
+
+- A quoted string passed to a numeric function (`SIN("abc")`) was silently
+  dropped from the argument list and surfaced as an arity error; it is now a
+  type error naming the string.
+
+- Nested function calls parse in linear time: each function argument, and
+  each assignment right-hand side, is parsed once instead of once per grammar
+  alternative, so a deeply nested `SIN(SIN(...))` is instant (#78).
+
+- The line fast path no longer declines whole programs because a few hundred
+  grammar-bound lines (procedure calls such as `SUPPORT_PIN_TRIGGER(2.5)`,
+  `MATERIAL_UPDATE`, `R1=R1+1`, `STOPRE`) are spread through a large file
+  (#69). Grammar-bound lines used to be parsed one at a time, each padded with
+  one newline per preceding line so that pest reported whole-file positions;
+  the padding cost O(line index) bytes per line, and a budget guard sent any
+  program over it to the whole-file parse. The grammar-bound lines are now
+  parsed in one pest run over a sparse copy of the program (only those lines
+  keep their text, every other line is empty), which gives the same whole-file
+  positions at O(input) bytes. The budget guard, the padded buffers and the
+  grammar-line ratio guard are gone: a program that is entirely grammar-bound
+  now costs the same as the whole-file parse (measured equal at 100k and 400k
+  lines), so every structure-free program takes the line path and the
+  whole-file parse is only used for programs with IF/WHILE/FOR/LOOP/REPEAT
+  blocks. On a 112 MB, 1.28M-line CAM
+  program with about 12,000 such lines the Python batch API went from 24.3 s
+  and 3.0 GiB peak RSS (whole-file parse) to 2.2 s and 1.3 GiB.
+
+- The line fast path no longer gives three line shapes a different meaning
+  than the grammar does (#83). `N10X5` (a block number glued to the next word)
+  was read as block 10 plus `X5`, where the grammar reads one call named
+  `N10X5` and warns about the glued word; `TRANS=5` (a frame keyword before
+  `=`) was stored as a variable, where the grammar rejects the line; and
+  `X=5 AND Y1` (likewise `OR`, `XOR`, `B_AND`, `B_OR`, `B_XOR` after a
+  constant) became `X=5`, a call `AND` and `Y1`, where the grammar evaluates
+  `5 AND Y1`. The decoder now hands these lines to the grammar, so the result
+  no longer depends on which path a program takes. A seeded random-line test
+  compares every line the decoder claims against the grammar.
+
 ## [v0.2.7] - 2026-09-08
 
 ### Changed

{nc_gcode_interpreter-0.2.7 → nc_gcode_interpreter-0.2.8}/Cargo.lock

@@ -506,7 +506,7 @@ checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
 
 [[package]]
 name = "nc-gcode-interpreter"
-version = "0.2.7"
+version = "0.2.8"
 dependencies = [
  "arrow-array",
  "arrow-data",

{nc_gcode_interpreter-0.2.7 → nc_gcode_interpreter-0.2.8}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nc-gcode-interpreter"
-version = "0.2.7"
+version = "0.2.8"
 edition = "2021"
 readme = "README.md"
 
@@ -47,4 +47,10 @@ arrow-data = { version = "59", optional = true, default-features = false }
 
 [features]
 default = []
+bench-experiments = []
 python = ["pyo3", "arrow-array", "arrow-schema", "arrow-data"]
+
+[[bench]]
+name = "workloads"
+harness = false
+required-features = ["bench-experiments"]

nc_gcode_interpreter-0.2.8/Development.md

@@ -0,0 +1,146 @@
+# Development
+
+
+Use Cargo to build and run the CLi tool:
+
+```
+cargo run -- --help
+```
+
+
+To compile the python module:
+
+```bash
+maturin develop
+```
+
+## Setup python environment
+
+```bash
+uv venv -p 3.12
+uv synv --all-extras
+```
+
+
+
+## Release
+
+```bash
+cargo build --release
+maturin develop --release --uv
+```
+
+### Versioning
+
+`Cargo.toml` holds the placeholder version `0.0.0-dev`; the release workflow
+rewrites it from the git tag before building the wheels, so the released
+version always comes from the tag and never from a committed number.
+
+Local builds get a version too. `build_backend/nc_build_backend.py` is an
+in-tree PEP 517 backend that wraps maturin: when it sees the placeholder and
+finds a git checkout with tags, it stamps
+`git describe --tags --long --dirty` onto the `Cargo.toml` version as
+`0.2.6-dev.3+g<sha>` (maturin normalises that to the PEP 440
+`0.2.6.dev3+<sha>`), builds, then restores `Cargo.toml` and `Cargo.lock`. So an
+editable `uv sync` reports the commit it was built from rather than
+`0.0.0.dev0` - which is what lets a downstream consumer notice it is running a
+local edit of the interpreter rather than a release.
+
+Any non-placeholder version in `Cargo.toml` is left alone, so the CI release
+path is unaffected. Without git (an unpacked sdist, say) the placeholder
+stands.
+
+A plain `cargo build` doesn't go through that shim, so `build.rs` derives the
+same version independently and exposes it as `NC_GCODE_INTERPRETER_VERSION`,
+which is what the CLI's `--version` reports. It applies the same rules: an
+already-stamped `Cargo.toml` version wins, and without git the placeholder
+stands. The CLI therefore shows cargo's semver spelling
+(`0.2.6-dev.1+ge5f2306`), not maturin's PEP 440 normalisation of it.
+
+### Release profile
+
+`[profile.release]` currently sets no `strip`/`lto` overrides. `strip = true` was
+tried and dropped (`e1ff63a`): cargo runs the *host* `strip` binary even on a
+cross-compiled artifact, so stripping the cross-built macOS x86_64 dylib with
+the arm64 host `strip` produced a wheel PyPI rejected as "not a zipfile" -
+stripping was reverted to unblock the release. It was a secondary size win
+(mostly orthogonal to the polars removal that motivated it) and can be
+revisited via maturin's cross-aware `--strip` flag instead of a Cargo
+profile setting.
+
+`lto` remains an untried, plausible speed knob (doesn't invoke an external
+tool, so it isn't blocked by the cross-compile issue above) - just not yet
+evaluated for its extra build time across the wheel matrix.
+
+
+## Super simple test
+
+There are a bunch of csv files in the examples directory. To test the tool on all of them (use git to check changes)
+
+```bash
+rm **/*.csv && cargo build --release && find examples -name "*.mpf" -type f -print0 | xargs -0 -I {} sh -c './target/release/nc-gcode-interpreter --axis-index-map E:4 --initial_state=examples/defaults.mpf "$1" || echo "Failed to process $1" >&2' sh {}
+```
+
+## python test
+    
+```bash
+maturin develop --release --uv && pytest
+```
+
+## Benchmark harness and parsing experiments
+
+The `bench-experiments` cargo feature compiles research-only strategies
+(`src/line_driver/experiments.rs`), a benchmark executable (`benches/`) and
+differential tests (`tests/performance_contract.rs`). Normal library and Python
+builds do not include any of it. The strategies are a laboratory for #71, #72,
+#73 and #74, not a session or incremental API.
+
+```bash
+cargo test --features bench-experiments
+python3 scripts/benchmark.py --lines 10000 100000 400000 --samples 5 --output tmp/baseline.json
+python3 scripts/compare_benchmarks.py tmp/baseline.json tmp/candidate.json
+```
+
+`scripts/benchmark.py` (Python 3.11 or newer, macOS or Linux) runs each case in
+its own release-build process and records cold and warm samples, time to the
+first batch, per-process peak RSS, build settings, the source and binary
+SHA-256 and the git revision. Sample zero is cold. `prepare_ms + run_ms` is the
+interpreter turnaround. The timings exclude Python, Arrow and viewer work, so
+they say nothing about edit-to-visible latency (#72). Do not run other builds
+concurrently when comparing. Results are not committed; keep them under `tmp/`.
+
+| Mode | What it measures | Boundary |
+| --- | --- | --- |
+| `fresh` | The public batch API, 1 or 4 Rayon threads; `--reference` adds the whole-file grammar and the VM | Full interpretation every time |
+| `grammar-cache` | Keeping a pest tree for unchanged reruns | Every edit reparses; O(file) AST |
+| `decoded-cache` | Immutable decoded blocks, patched by line range | Trivial label-free lines only; output is re-executed |
+| `bounded` | Validate eligibility, then decode and execute one line at a time | Two decode passes; trivial label-free lines only |
+| `fused` | Decode and execute immediately with a reusable word arena | Same language; a later unsupported line fails after output started |
+
+Edit cases (`--edits coordinate parameter insert delete translation`) prepare
+two revised sources before timing; `decoded-cache` undoes the previous patch
+and applies the next one inside `prepare_ms`. `--input <file>` benchmarks a
+local program with `--edits none`; `--verify-digest` additionally checks that
+every strategy produces the same rows and final state (hashing adds time, so
+do not compare those timings with plain runs). `--cancel` drops the consumer
+after the first batch. The manually dispatched Benchmark workflow runs the
+correctness gate and uploads the JSON; it asserts no wall-clock numbers.
+
+Findings so far (Apple M1 Pro, release builds, median of five warm samples,
+single thread, 400k-line synthetic straight-line program):
+
+| Strategy | Time | Peak RSS |
+| --- | ---: | ---: |
+| Public batch API | 672 ms | 560 MiB |
+| Cached decoded blocks (64 lines) | 260 ms | 272 MiB |
+| Fused decode and execute | 357 ms | 87 MiB |
+
+Parsing reuse removes about a quarter of the warm-edit time; execution and
+output dominate the rest, so output chunks or checkpoints (#47, #74) are
+needed to go further. Keeping the whole pest tree was slower than the fast
+path on ordinary CAM input and cost 3.7 s to rebuild after a TRANS edit. Four
+Rayon threads did not consistently beat one. Thin LTO changed the flat cases by
+1 to 9 %. Fused decoding handled synthetic 7M and 22M-line programs in 6.3 s
+and 21 s at 1.0 and 3.1 GiB; the input copy and the State line index still
+scale with the source. The sparse grammar buffer that came out of this work is
+now the production fast path (#69).

{nc_gcode_interpreter-0.2.7 → nc_gcode_interpreter-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nc-gcode-interpreter
-Version: 0.2.7
+Version: 0.2.8
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: 3.12

{nc_gcode_interpreter-0.2.7 → nc_gcode_interpreter-0.2.8}/README.md

@@ -11,7 +11,7 @@ The **NC-GCode-Interpreter** offers a streamlined and efficient solution for int
 ### Supported G-code Features
 
 - **G Group Commands**: Recognizes G-code groups and modal G-code commands.
-- **Global Transformations**: Supports commands like `TRANS` and `ATRANS` for adjusting coordinates globally.
+- **Programmable frames**: `TRANS`/`ATRANS` work offsets and `ROT`/`AROT` rotations (`X.. Y.. Z..` RPY angles or `RPL=` in the active plane) for the geometry axes X, Y, Z; output coordinates are machine coordinates with the frame applied, and the final state reports the `translation` and `rotation`.
 - **Looping Constructs**: Handles loops using `WHILE`, `FOR`, `REPEAT ... UNTIL` and `LOOP ... ENDLOOP` statements.
 - **Variable Handling**: Supports definition and manipulation of local variables.
 - **Conditional Logic**: Implements conditional execution with `IF`, `ELSE`, and `ENDIF`.
@@ -23,7 +23,7 @@ The **NC-GCode-Interpreter** offers a streamlined and efficient solution for int
 
 ### Additional Functionality
 
-- **Streaming interpretation**: `nc_to_rows(program)` yields `(line_no, row)` tuples lazily while the interpreter runs on a background thread — constant memory, early exit by dropping the iterator (breaking out of a `for` loop over an anonymous iterator does this; a stored iterator keeps the run alive until it is deleted or garbage-collected), and source-line numbers for mapping trace rows back to the program. With `include_variables=True` it yields `(line_no, row, variables)` instead, exposing every variable assignment (`R1=R1+1`, `DEF`, FOR counters) as it happens — including blocks that only assign variables, which are invisible in the batch DataFrame.
+- **Streaming interpretation**: `nc_to_rows(program)` yields `(line_no, row)` tuples lazily while the interpreter runs on a background thread — bounded output buffering, early exit by dropping the iterator (breaking out of a `for` loop over an anonymous iterator does this; a stored iterator keeps the run alive until it is deleted or garbage-collected), and source-line numbers for mapping trace rows back to the program. With `include_variables=True` it yields `(line_no, row, variables)` instead, exposing every variable assignment (`R1=R1+1`, `DEF`, FOR counters) as it happens — including blocks that only assign variables, which are invisible in the batch DataFrame.
 
 - **Curve flattening**: pass `flatten_tolerance` (Python) or `--flatten-tolerance` (CLI) to convert curved motions — `G2`/`G3` arcs (`I`/`J`/`K` centre offsets or `CR=` radius form, `G17`/`G18`/`G19` planes, helical third axis with `TURN=` multi-turn support, full circles) and `ASPLINE`/`BSPLINE`/`CSPLINE` splines (including `PW` weights and `SD` degree) — into runs of plain `G1` rows in the same table format. `CIP`/`CT`/`POLY`/thread/involute blocks pass through unchanged with a warning; spline start/end conditions (`BAUTO`/`BNAT`/... ) are approximated by natural (CSPLINE) / Akima (ASPLINE) boundaries — see the `flatten` module docs for the full list of checked approximations. The single tolerance is the maximum deviation between the emitted polyline and the true curve, in path units: arcs use the exact sagitta bound, splines adaptive subdivision. The interpolation addresses (`I`/`J`/`K`/`CR`/`PW`/`SD`/`PL`) are consumed and do not appear in the output; sampled rows keep the source block's line number, and its other cells (`F`, `M`, comments, ...) ride on the first sample so modal behavior is preserved. Generated samples carry a `flattened = 1` marker column (never forward-filled); programmed positions stay null there, so filtering on null recovers the original toolpath points.
 - **Toolpath visualization** (optional): with the `viz` extra (`pip install 'nc-gcode-interpreter[viz]'`), `nc_gcode_interpreter.viz.view_toolpath(df)` renders an interpreted toolpath in [threejs-viewer](https://pypi.org/project/threejs-viewer/) as an extruded bead tube with a draw-range animation replaying the program at feed-rate-proportional speed. Combined with `flatten_tolerance`, programmed points render orange and flattener-generated samples blue. The extra also installs the `nc-view` command: `nc-view part.mpf` interprets, flattens (default tolerance 0.1, `--no-flatten` to skip) and opens the animated toolpath in the browser; `--speed` sets the time-lapse factor (default 60 = one machine-minute per second).
@@ -161,6 +161,22 @@ for line_no, row, variables in nc_to_rows(program, include_variables=True):
 
 Rows are typed and forward-filled like the batch DataFrame (disable with `forward_fill=False`); errors raise from `next()` at the offending row; after exhaustion the iterator's `state` attribute holds the final interpreter state. See `python/example/streaming.py` for a runnable version.
 
+**Memory.** Programs of 64 MiB or more without multi-line control blocks or
+jumps are validated in a parallel preflight scan and then executed one line at a
+time, so parse storage is bounded by the longest line instead of the program
+length. The input text, its diagnostic copy and line-offset index, variable
+state and any output the caller retains still grow with the program, so use
+`nc_to_batches` with a bounded consumer for large files. Smaller programs and
+programs with jumps keep the indexed fast path; `NC_STREAM_MIN_BYTES` sets the
+threshold in bytes (0 streams every jump-free program). Control blocks and
+`NC_STAGE1=0` still use the whole-file parser. On a 1.28M-line (112 MB) field
+program the peak RSS of `nc_to_batches` drops from about 1.3 GiB to 0.4 GiB,
+and the second decode during execution costs up to about 20 percent of
+interpretation time. Measure a local program with
+`python scripts/benchmark.py --input <file> --modes fresh --edits none
+--threads 4 --samples 1 --batch-size 4096 --allow-undefined --axis-index-e 4
+--axis-index-elx 5 --output tmp/memory.json`.
+
 **Cancellation.** Dropping the iterator is the supported way to cancel a `nc_to_rows`/`nc_to_batches` run — leaving a `for` loop early or `del`-ing it drops it immediately; relying on garbage collection works too but only whenever the runtime happens to collect it, so it is not prompt on all interpreters: the background interpreter thread's next attempt to send a row hits a closed channel and returns internally via `ParsingError::StreamClosed`, so the thread unwinds promptly instead of running the rest of the program to completion. No explicit `.close()`/`.cancel()` call is needed or provided — drop is the whole contract, and downstreams (e.g. ribweaver's `/sim` live-edit reinterpret) rely on it for latest-wins cancellation.
 
 Additionally, conversion from a Polars DataFrame back to an MPF (NC) program is also supported:

nc_gcode_interpreter-0.2.8/benches/fixtures.rs

@@ -0,0 +1,50 @@
+use std::fmt::Write;
+
+pub fn program(shape: &str, lines: usize) -> String {
+    assert!(lines >= 8);
+    let mut text = String::with_capacity(lines * 90);
+    text.push_str(if shape == "frames" {
+        "TRANS X10\n"
+    } else {
+        "MULTIPLIER=1\n"
+    });
+    text.push_str("G1 X0 Y0 Z0 E0 F1200\n");
+    for i in 2..lines - 1 {
+        match shape {
+            "calls" if i % 1000 == 0 => text.push_str("SUPPORT_PIN_TRIGGER(2.5)\n"),
+            "grammar" => text.push_str("X=SIN(30) Y=COS(60)\n"),
+            "structured" if i == 2 => text.push_str("IF 1==1\n"),
+            "structured" if i == lines - 2 => text.push_str("ENDIF\n"),
+            _ => writeln!(
+                text,
+                "N{i} G1 X{}.125 Y{}.25 Z1 E=IC({}) ELX=100 F1200",
+                i % 1000,
+                i % 300,
+                if shape == "frames" { "0.025" } else { "MULTIPLIER*0.025" }
+            )
+            .unwrap(),
+        }
+    }
+    text.push_str("M30\n");
+    text
+}
+
+/// All edits are against the original revision, allowing alternating edit/undo.
+pub fn edit(source: &str, kind: &str, alternate: bool) -> (String, std::ops::Range<usize>, String) {
+    let mut lines: Vec<_> = source.lines().collect();
+    let mid = lines.len() / 2;
+    let (range, replacement) = match kind {
+        "none" => (0..0, String::new()),
+        "coordinate" => (
+            mid..mid + 1,
+            format!("G1 X{} Y2 E=IC(0.025)", if alternate { 7 } else { 8 }),
+        ),
+        "parameter" => (0..1, format!("MULTIPLIER={}", if alternate { 2 } else { 3 })),
+        "translation" => (0..1, format!("TRANS X{}", if alternate { 20 } else { 30 })),
+        "insert" => (mid..mid, "; inserted comment\nG1 X3".into()),
+        "delete" => (mid..mid + 1, String::new()),
+        _ => panic!("unknown edit {kind}"),
+    };
+    lines.splice(range.clone(), replacement.lines());
+    (format!("{}\n", lines.join("\n")), range, replacement)
+}