nc-gcode-interpreter 0.2.9__tar.gz → 0.3.0__tar.gz

{nc_gcode_interpreter-0.2.9 → nc_gcode_interpreter-0.3.0}/.github/workflows/build-and-release.yml

@@ -80,7 +80,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter
+          args: --release --out dist -i python3.12 -i python3.13 -i python3.14 -i python3.14t -i python3.15 -i python3.15t
           sccache: 'true'
           manylinux: auto
       - name: Upload wheels
@@ -156,8 +156,8 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          # Named interpreters: --find-interpreter also picks up the image's PyPy,
-          # which pyo3-ffi 0.29.0 fails to compile for.
+          # Every wheel job names its interpreters (the set 0.2.8 shipped per platform):
+          # --find-interpreter picks up whatever the image has, e.g. PyPy, which fails.
           args: --release --out dist -i python3.12 -i python3.13 -i python3.14 -i python3.14t
           sccache: 'true'
           manylinux: auto
@@ -216,7 +216,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter
+          args: --release --out dist -i python3.12 -i python3.13 -i python3.14
           sccache: 'true'
       - name: Upload wheels
         uses: actions/upload-artifact@v4
@@ -256,7 +256,7 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter
+          args: --release --out dist -i python3.12 -i python3.13 -i python3.14 -i python3.15
           sccache: 'true'
       - name: Upload wheels
         uses: actions/upload-artifact@v4
@@ -305,7 +305,7 @@ jobs:
       contents: write
       attestations: write
     steps:
-      # Do NOT use `merge-multiple: true`. With `--find-interpreter`, every
+      # Do NOT use `merge-multiple: true`. With a shared interpreter list, every
       # build matrix leg (py3.12 AND py3.13) produces cp312/cp313/cp314 wheels
       # with identical filenames but non-identical bytes (sccache makes builds
       # nondeterministic). Merging them into one directory makes

{nc_gcode_interpreter-0.2.9 → nc_gcode_interpreter-0.3.0}/CHANGELOG.md

@@ -4,6 +4,288 @@ Notable changes to **nc-gcode-interpreter**. The format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); versions are git tags,
 released to PyPI.
 
+## [v0.3.0] - 2026-11-11
+
+This release changes the API and the output. To upgrade:
+
+- Replace `initial_state` with `definitions` (definition files),
+  `variables` (values) and `start` (machine state); see the first entry
+  under Changed.
+- Program a feed before the first path motion, or pass it in `start` (key
+  `"feed"`): a missing feed is now the `feed_not_programmed` error, as on
+  the control (alarm 10860).
+- The G-group columns are `pl.Enum`, and polars 1.32 or newer is required.
+  `cast(pl.String)` restores the old dtype.
+- New loud errors for constructs that used to be misread: two calls in one
+  block, `G4` with axis words, `FGROUP`/`FGREF` on non-axes, reading
+  `FGREF`, and others listed below.
+
+### Added
+
+- Subprogram execution (#48). `nc_to_dataframe` and `nc_to_batches` take
+  `subprograms`, a mapping of subprogram name to source text. A call whose
+  name is in the mapping runs that text; any other call stays a
+  `non_returning_function_call` cell as before. Supported: a `PROC` header
+  with by-value parameters (numbers and strings, with defaults), `VAR`
+  parameters and `VAR` array parameters, local `DEF` variables (invisible to
+  callees, gone on return), return on `M17` or `RET`, and nested calls up to
+  16 levels. Rows produced inside a call keep the main-program line of the
+  call in `line_no` and carry two new columns: `subprogram`, the call path
+  (`OUTER/INNER`), and `subprogram_line`, the line inside that subprogram's
+  text. The interpreter does not read files; the caller supplies the texts.
+- `m_function_subprograms`, a mapping of M function number to subprogram
+  name: the subprogram runs at the end of every block that programs that M
+  function, as a control does for a tool-change cycle on `M6`. It does not
+  apply inside the replacement subprogram itself.
+- External variables. `external_variables` takes a provider object with
+  `names`, `read(name, indices)` and `write(name, indices, value)`. Every
+  read or write of a listed name (`$A_IN`, `$A_DBB`, `$AA_IM`, or any other
+  variable name) goes to the provider and is not stored by the interpreter,
+  so a program can branch and wait on machine state the interpreter does not
+  model. Indices arrive as ints, or as the axis name where an axis is the
+  index. With `nc_to_batches` the rows produced so far are yielded before the
+  provider is asked, and the provider is called on the consuming thread, so
+  a simulator can play those rows first. An exception raised by the provider
+  ends the run and propagates unchanged.
+- Rust API: `interpreter::nc_to_table_with` and
+  `interpreter::nc_to_batch_stream_with` take a `subprogram::Extensions`
+  value with the same extensions; the provider is the
+  `subprogram::ExternalVariables` trait.
+- `required_subprograms`: a call of a listed name that is not among
+  `subprograms` is an error that names the call path, where it would
+  otherwise stay an opaque cell.
+- `stop_on_setal`: a `SETAL` call ends the run with an error that carries the
+  call as written and the call path.
+- String comparison with `==` and `<>` in conditions and expressions
+  (`IF (KIND == "MILL")`). Other operators on strings, and a string compared
+  with a number, are errors. A served external variable compared with a
+  string is read from the provider as text (`read` returns a `str`).
+- A frame value assigned to a served external variable
+  (`$P_UIFR[7] = CTRANS(X, 10) : CROT(Z, 90)`) reaches the provider's `write`
+  as `[("CTRANS", ("X", 10.0)), ("CROT", ("Z", 90.0))]`. Assigned to any
+  other variable it is an error.
+- Machine axis names (`AX1`) and frame components (`TR`, `FI`, `RT`, `SC`,
+  `MI`) are passed to the provider as index names.
+- `transformation` column: the last `TRAORI`, `TRANSMIT`, `TRACYL`, `TRAANG`,
+  `TRACON` or `TRAFOOF` call as written, forward-filled like a modal G group.
+  The call also stays in `non_returning_function_call`.
+- Definition files parse: the `DEF` attributes for range, preprocessing stop,
+  access rights, unit and limits (`DEF CHAN APW 4 REAL LLI 0 ULI 10 NAME`),
+  the `CHAR` type, and attribute-only `REDEF` lines are accepted and not
+  interpreted.
+- Array assignment as a statement: `NAME[n] = SET(v, ...)` and
+  `NAME[n] = REP(v[, count])` write consecutive elements starting at the
+  indexed one, last index fastest. Before, only the `DEF` initializer form
+  was interpreted and the statement form was an internal error.
+- A subprogram whose `PROC` header has the `SAVE` attribute gives the caller
+  back its modal G functions on return: each G group the subprogram changed
+  gets the caller's value on the row after the body's rows. A group the
+  program never set before the call cannot be restored and gives a warning.
+- Loud errors for constructs the subprogram mechanism does not model: a
+  `FOR` counter, a `PROC` parameter or a local `DEF` with the name of an
+  external variable, a string assigned to an external variable, a `PROC` parameter with the name of an axis or
+  address, `SET`/`REP` statements that write past the declared array, and
+  two `subprograms` entries whose names differ only in case.
+- Program repetitions: `L6 P2` and `L6 P=2` call `L6` twice (manual
+  4.2.3.3). A supplied subprogram runs that many times, with its arguments
+  passed once; without a supplied body the call keeps its name and the
+  count goes to a new `call_repetitions` column. A count outside 1 to 9999
+  is an error. Before, `L6 P2` was recorded as a call named `P2` and
+  `L6 P=2` set a user variable `P` (part of #105).
+- `PCALL NAME(...)` calls `NAME` (manual 4.2.3.8). A path before the name
+  (`PCALL/_N_WKS_DIR/_N_X_WPD/NAME`) is not interpreted and gives a
+  warning; the call goes to `NAME`. Before, `PCALL` was dropped silently.
+
+- `FGROUP(<axes>)` and `FGREF[<axis>]=<radius>` are modal state (manual
+  3.7.1). A forward-filled, dictionary-encoded `FGROUP` column holds the axes
+  the path feed refers to, comma-separated as programmed; `FGROUP()` writes
+  `""` for the machine-data default, which the interpreter does not know.
+  Each programmed axis gets a forward-filled `FGREF[<axis>]` float column;
+  null means the control default. Both columns appear only when the program
+  uses them, after the axis columns. Before, `FGROUP` was stored as a
+  subprogram call in `non_returning_function_call` and `FGREF[<axis>]` needed
+  an `axis_index_map` entry and became the variable `FGREF[<index>]`; it now
+  resolves by axis name and is no longer a variable. An argument that is not
+  a configured channel axis (including N, F, S, D and T) is an
+  `unexpected_axis` error. Reading `FGREF[<axis>]` is an
+  `unsupported_statement` error, and so is a user array named `FGREF` (#107).
+
+### Changed
+
+- **Breaking:** `initial_state` is removed from `nc_to_dataframe`,
+  `nc_to_batches`, `nc_to_rows`, the Rust interpreter functions and the CLIs
+  (`-i/--initial_state`, `--initial-state`). It ran a string of NC text before
+  the program and discarded its rows, which mixed three jobs. Three inputs
+  replace it, applied in this order before the main program:
+  - `definitions`: a list of definition files (GUD/MGUD/UGUD `.DEF`), each
+    read on its own. A file may hold DEF and REDEF statements, assignments to
+    variables and comments; the `%_N_..._DEF` header and `$PATH=` line are
+    skipped. M17, M30 or M2 ends that file and reading goes on with the next,
+    so several files no longer need their end codes stripped. `CHANDATA(1)`
+    is accepted and ignored; another channel number is an error. `TRAFOOF`
+    on a block of its own sets the start transformation to off, in the first
+    row and the returned state, unless `start["transformation"]` gives
+    another, so a restore program (CHANDATA(1), TRAFOOF, SET array
+    assignments, M30) reads unchanged. The program stops M0 and M1 are
+    ignored. A subprogram call stays an error naming the call. Assigning
+    to a name the files have not declared is an error, unless it is an R
+    parameter or `allow_undefined_variables` is set. Motion, G codes or
+    anything else is an error naming the file (`NcError.definition_file`,
+    its index in the list) and the line within it. Migration: pass the DEF
+    files as a list instead of concatenating them into `initial_state`.
+  - `variables`: a dict of values (`float`, `int`, `bool`, `str`) written
+    straight into the variable tables and checked against the declared type
+    (2.5 into an INT, or a string into a REAL or an R parameter, is an
+    error). Names must be
+    defined unless they are R parameters, system variables or
+    `allow_undefined_variables` is set. Migration: replace generated
+    `NAME=VALUE` lines with `variables={"NAME": value}`; strings now work.
+  - `start`: the machine state at program start, in the shape of the
+    returned state dict (`axes`, `translation`, `rotation`, `symbol_table`,
+    `string_table`, plus the new `g_groups`, `feed`, `tool`,
+    `transformation`, `fgroup` and `fgref`), so a returned state can be
+    passed back. `fgroup` is the FGROUP column value and `fgref` maps a
+    channel axis to its FGREF reference radius. Modal G groups
+    are checked against the G group table, and they, `feed`, `tool` (the `T`
+    column), `transformation`, `fgroup` and `fgref` fill the first output row, so those columns
+    no longer start as null. Axis positions and the frame only seed the internal state.
+    A name in both `variables` and `start` is an error. Migration: replace
+    axis words and frame instructions in `initial_state` with
+    `start={"axes": {...}, "translation": {...}}`, and modal G codes and F
+    with `start={"g_groups": {...}, "feed": ...}`.
+  The returned state gains `g_groups` (modal G group column to code, as of
+  the last row), `feed`, `tool`, `transformation`, `fgroup` and `fgref`. The CLIs take `--definitions FILE` (repeatable),
+  `--variables FILE.json` and `--start FILE.json`. The Rust functions take
+  `Option<&start::StartInputs>` where they took `Option<&str>`.
+
+- **Breaking:** a block that traverses a path (G1, G2, G3, CIP, splines and
+  the other path motions) while no feed is programmed is an error
+  (`NcError.kind == "feed_not_programmed"`), as alarm 10860 is on the
+  control. G0, the G4 dwell, G74/G75 and the thread commands need no F;
+  G63 tapping does. A change of feed unit deletes F and FZ (Axes and
+  spindles manual 7.2.1, 7.2.2): inverse time (G93), traversing time
+  (G931), per minute (G94, G961, G971, G942) and per revolution (G95, G96,
+  G97, G952, G973); G962 and G972 keep the unit that was active. A change
+  within one unit (G95 to G96) keeps F. When the previous feed type is
+  unknown (never programmed, not in `start["g_groups"]`) nothing is
+  deleted. A feed seeded from `start` is start state, not an F of the first
+  block, so a feed type change there deletes it too. `FZ=` (feed per tooth)
+  counts as a feed under a revolutional feed type and `FB=` (non-modal feed,
+  7.4.10) for its own block; both are now output columns (`FZ`
+  forward-filled, `FB` not), where they used to become variables. G4 with
+  axis words in the same block is an error (G4 stands alone, manual
+  3.14.7). G93 recommends but does not
+  require F in every block, so that is not checked. The control's default
+  feed SD42110 `$SC_DEFAULT_FEED` (0 unless set) is evaluated at program
+  start: pass it as `start["feed"]`. The check is off when F is not a
+  configured axis. FGROUP only selects the axes F refers to, so a block
+  moving only synchronized or rotary axes needs F the same way, and FGROUP
+  and FGREF neither move nor delete F. Tree walker, VM and line fast path
+  raise the same error.
+  Migration: program F before the first path motion or pass
+  `start={"feed": ...}`. The examples `simple`, `trans_ic`, `r_param`,
+  `axis_index_assignment`, `multiple_m_codes` and `function_calls` gained
+  `F1000` on their first path motion, and their expected CSVs gained the
+  `F` column (no other column changed).
+
+- **Breaking:** every G-group column (`gg01_motion`, `gg02_wait`, ...) in the
+  output of `nc_to_batches`, `nc_to_dataframe` and `sanitize_dataframe` is
+  now a `pl.Enum` instead of `String`. Its categories are that group's
+  commands in manual order, the same in every batch and every run, so batches
+  and runs concatenate without a cast and a value outside the group cannot
+  occur. Rust hands the codes over as an Arrow dictionary that polars imports
+  as `Enum` directly, with no cast. The new `G_GROUP_DTYPES` maps each G-group column name to its
+  `pl.Enum`, for matching schemas and empty frames. `T`, `comment`,
+  `non_returning_function_call` and other free-text columns stay `String`,
+  and `nc_to_rows` still yields `str`. On a 1M-row program the G-group cells
+  take 1 byte each instead of a 16-byte string view, and filtering or
+  grouping on them is about 1.4 to 2 times faster, at unchanged
+  interpretation time. Consequences
+  for code that reads these columns:
+  - `.str` methods raise `InvalidOperationError`, and joining against a
+    `String` column raises `SchemaError`.
+  - `fill_null("")` silently leaves the nulls in place, because `""` is not a
+    category.
+  - `is_in` with a value outside the group raises; `==` with such a literal
+    returns no matches.
+  - Sorting follows manual order (`G0`, `G1`, `G2`, ...), not alphabetical
+    order.
+  - A strict `pl.concat` with frames from an older version, or
+    `assert_frame_equal` against `String` frames, fails on the dtype.
+  - Migration: `df.with_columns(pl.col(c).cast(pl.String) for c in
+    G_GROUP_DTYPES if c in df.columns)` restores the old dtype.
+
+- **Breaking:** the minimum polars version is now 1.32 (was 1.9). The Enum
+  handoff relies on the Arrow field metadata polars reads from 1.32 on.
+
+- A program that calls `TRAORI`, `TRANSMIT`, `TRACYL`, `TRAANG`, `TRACON` or
+  `TRAFOOF` gets the new `transformation` column, also when it uses none of
+  the new arguments.
+- Two subprogram calls in one block (`FOO BAR`) are an error. Before, the
+  second silently replaced the first. Keyword G commands such as `SOFT`
+  next to a call are unaffected. A repeat count before the name (`P3 FOO`,
+  `P=3 FOO`) is an error as well (part of #105).
+- `PROC`, `EXTERN` and `RET` are reserved words and no longer read as
+  subprogram calls. A `PROC` header and an `EXTERN` declaration produce no
+  output; `RET` ends the program at the top level like `M17`. Before,
+  `PROC FOO SAVE` was recorded as a call named `SAVE` and `RET` as a call
+  while interpretation continued (part of #105). A main program whose `PROC`
+  header declares parameters is an error.
+- A program without control structures keeps the line fast path when an
+  extension is used. Only its lines with a call, an M function mapped to a
+  subprogram, or a word that names a served variable go through the
+  grammar, which dispatches them. Before, any extension sent the whole
+  program through the grammar path, about seven times slower per line.
+- `DEF REAL A[n]` declares the elements `A[0]` to `A[n-1]`. Before, it also
+  created `A[n]`, so an out-of-range access went unnoticed.
+- `REDEF` and `PCALL` are reserved words.
+- A supplied subprogram is checked and parsed on its first call, and later
+  calls in the same run reuse the parse tree. Before, every call parsed the
+  text again, which was about two thirds of the time of a call of a 20-line
+  body. Adds the `self_cell` dependency, which holds the tree next to the
+  text it borrows from.
+- `nc_to_dataframe` with `external_variables` no longer sends the rows
+  produced so far as a separate batch before each provider call, since its
+  caller reads no row before the run ends. A program that reads the provider
+  on every motion row built one batch per row. `nc_to_batches` and the Rust
+  API keep handing the rows over first; Rust callers can opt out with
+  `Extensions::defer_rows`.
+
+## [v0.2.10] - 2026-11-10
+
+### Changed
+
+- `nc_to_batches` and `nc_to_dataframe` do less work per output row. The
+  G-group columns are held as per-batch dictionary codes and written straight
+  to the Arrow string array, instead of one `String` per row per column that
+  the consumer thread then freed; the batch builder finds a cell's column
+  without hashing its name; the streaming driver reuses its decode buffers.
+  Python output is unchanged (same columns, `String` dtype, values and
+  `variable_events`). With `flatten_tolerance`, line numbers and variables on,
+  a 7.2M-row, 442 MiB linear program takes 3.3 s instead of 8.3 s and a
+  22M-row, 1.1 GB program 10.5 s instead of 24 s, at the same peak memory
+  (#89).
+
+- `flatten_tolerance` costs almost nothing on rows that are not curves: the
+  flattener tracked positions with an allocation and a lookup per configured
+  axis for every row, about 2 s on the 7.2M-row program above, now about
+  0.15 s. B-spline flattening reuses one working buffer per curve; a
+  5.4M-row, 380 MB spline program takes 8 s instead of 16 s (#89).
+
+- Rust API: `Column` has a new `Dict(DictColumn)` variant, used for the
+  G-group columns (`values` plus one `u32` code per row,
+  `DictColumn::NULL` for a null cell). Code that matches `Column`
+  exhaustively needs one more arm; `DictColumn::iter` yields the cells as
+  `Option<&str>` (#89).
+
+### Fixed
+
+- A numeric tool selection (`T2`, `T=3`, `T=R1`) now reaches the output table.
+  It is written to the same string `T` column as `T="name"`, as the number's
+  text (`"2"`), on the row of the block that programs it. Before, only named
+  tools appeared and a numeric one was dropped without a warning. The value is
+  still stored as the variable `T` in the final state, as before (#101).
+
 ## [v0.2.9] - 2026-11-01
 
 ### Changed

{nc_gcode_interpreter-0.2.9 → nc_gcode_interpreter-0.3.0}/Cargo.lock

@@ -506,7 +506,7 @@ checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
 
 [[package]]
 name = "nc-gcode-interpreter"
-version = "0.2.9"
+version = "0.3.0"
 dependencies = [
  "arrow-array",
  "arrow-data",
@@ -518,6 +518,8 @@ dependencies = [
  "pyo3",
  "rayon",
  "rustc-hash",
+ "self_cell",
+ "serde_json",
  "thiserror",
 ]
 
@@ -745,6 +747,21 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
 
+[[package]]
+name = "self_cell"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ab42ca02749e120097e328d91d415325bdf43b1c72c4c8badf37375fe40a813"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+]
+
 [[package]]
 name = "serde_core"
 version = "1.0.228"
@@ -765,6 +782,19 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
 [[package]]
 name = "sha2"
 version = "0.10.9"
@@ -1023,3 +1053,9 @@ dependencies = [
  "quote",
  "syn",
 ]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

{nc_gcode_interpreter-0.2.9 → nc_gcode_interpreter-0.3.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nc-gcode-interpreter"
-version = "0.2.9"
+version = "0.3.0"
 edition = "2021"
 readme = "README.md"
 
@@ -20,6 +20,7 @@ thiserror = "2.0.18"
 clap = { version = "4.6", features = ["derive"] }
 rayon = "1.10"
 rustc-hash = "2.1"
+serde_json = "1"
 
 # NOTE: keep every dependency version inline (`crate = { version = "..." }`),
 # NOT as a `[dependencies.crate]` block with a standalone `version = "..."`
@@ -44,6 +45,7 @@ pyo3 = { version = "0.29", optional = true }
 arrow-array = { version = "59", optional = true, default-features = false, features = ["ffi"] }
 arrow-schema = { version = "59", optional = true, default-features = false }
 arrow-data = { version = "59", optional = true, default-features = false }
+self_cell = "1"
 
 [features]
 default = []
@@ -54,3 +56,7 @@ python = ["pyo3", "arrow-array", "arrow-schema", "arrow-data"]
 name = "workloads"
 harness = false
 required-features = ["bench-experiments"]
+
+[[bench]]
+name = "extensions"
+harness = false

{nc_gcode_interpreter-0.2.9 → nc_gcode_interpreter-0.3.0}/Development.md

@@ -78,7 +78,7 @@ evaluated for its extra build time across the wheel matrix.
 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 {}
+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 --definitions examples/defaults.def --start examples/defaults_start.json "$1" || echo "Failed to process $1" >&2' sh {}
 ```
 
 ## python test

{nc_gcode_interpreter-0.2.9 → nc_gcode_interpreter-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nc-gcode-interpreter
-Version: 0.2.9
+Version: 0.3.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: 3.12
@@ -9,7 +9,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: maturin>=1.7.4
-Requires-Dist: polars>=1.9.0
+Requires-Dist: polars>=1.32.0
 Requires-Dist: jupyter>=1.1.1 ; extra == 'dev'
 Requires-Dist: pytest>=8.3.3 ; extra == 'test'
 Requires-Dist: mypy ; extra == 'test'

{nc_gcode_interpreter-0.2.9 → nc_gcode_interpreter-0.3.0}/README.md

@@ -20,6 +20,7 @@ The **NC-GCode-Interpreter** offers a streamlined and efficient solution for int
 - **Array Operations**: Manages arrays and allows operations on them.
 - **Incremental Changes**: Facilitates incremental changes in axes positions like `X=IC(2)`.
 - **Spline Programming**: `ASPLINE`, `BSPLINE` and `CSPLINE` blocks with their start/end conditions (`BAUTO`/`BNAT`/`BTAN`, `EAUTO`/`ENAT`/`ETAN`) and the spline block addresses `PW` (point weight), `SD` (spline degree) and `PL` (parameter interval length). Block addresses appear as output columns; unlike axes they receive no `TRANS` offset and are not forward-filled, since e.g. a point weight only applies to the point it is programmed with.
+- **Feed group**: `FGROUP(<axes>)` and `FGREF[<axis>]=<radius>` are modal state, not calls or variables. The `FGROUP` column holds the axes the path feed `F` refers to, comma-separated as programmed (`"RA1,RA2,RA3"`); `FGROUP()` gives `""`, the machine-data default, as does a null before the first `FGROUP`. Each `FGREF[<axis>]` column holds the reference radius of that axis; null means the control default (360 mm / 2π for a rotary axis). Both are forward-filled, appear only when the program uses them, and need no `axis_index_map` entry. The interpreter computes no timing from them.
 
 ### Additional Functionality
 
@@ -28,7 +29,8 @@ The **NC-GCode-Interpreter** offers a streamlined and efficient solution for int
 - **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).
 - **Custom Axes**: Allows users to define additional axes beyond the standard `X`, `Y`, `Z`.
-- **Initial State Configuration**: Enables the use of an initial state MPF file to set default values for multiple runs.
+- **Definitions, variables and start state**: `definitions` takes the definition files a control loads (GUD/MGUD/UGUD `.DEF`: DEF and REDEF statements, assignments, comments; M17/M30/M2 ends a file), `variables` takes variable values checked against their declared type, and `start` takes the machine state at program start in the shape of the returned `state` dict (axes, frame, variables, modal G groups, feed, tool, transformation, FGROUP and FGREF radii). The G groups, feed, tool, transformation, FGROUP and FGREF fill the first output row; seeded G groups have the same `pl.Enum` dtype as the rest of the column. They are applied in that order, before the main program. In a definition file `CHANDATA(1)` is ignored, another channel is an error, `TRAFOOF` sets the start transformation to off (a later `start["transformation"]` wins), M0 and M1 are ignored, a subprogram call is an error, and assigning to an undeclared name is an error unless it is an R parameter or `allow_undefined_variables` is set.
+- **Feed check**: a path motion (G1, G2, G3, CIP, splines) with no feed programmed is an error, as alarm 10860 is on the control; a change of feed unit (inverse time, per minute, per revolution) deletes F; `FZ=` counts as a feed under a revolutional feed type and `FB=` for its own block. FGROUP does not change this: a block moving only axes outside the FGROUP, or only rotary axes, needs F too. Pass the control's default feed (SD42110 `$SC_DEFAULT_FEED`) as `start["feed"]`. The check is off when F is not a configured axis. On the CLI: `--definitions FILE` (repeatable), `--variables FILE.json` and `--start FILE.json`.
 - **CLI Options**: Numerous command-line options to customize the processing, such as axis overriding, loop limits, and more.
 
 ## Example Usage
@@ -66,7 +68,9 @@ Arguments:
 Options:
   -a, --axes <AXIS>                    Override default axis identifiers (comma-separated, e.g., "X,Y,Z")
   -e, --extra-axes <EXTRA_AXIS>        Add extra axis identifiers (comma-separated, e.g., "RA1,RA2")
-  -i, --initial_state <INITIAL_STATE>  Optional initial state file to e.g. define global variables or set axis positions
+      --definitions <FILE>             Definition file (GUD/MGUD .DEF) to read before the program; repeat for several, read in order
+      --variables <FILE>               JSON object of variable values applied after the definitions, e.g. {"COUNT": 3}
+      --start <FILE>                   JSON object with the machine state at program start (the shape of the returned state)
   -l, --iteration_limit <LIMIT>        Maximum number of iterations for loops [default: 10000]
   -f, --disable-forward-fill           Disable forward-filling of null values in axes columns
   -h, --help                           Print help
@@ -113,7 +117,7 @@ shape: (14, 7)
 ┌───────┬───────┬──────┬────────┬───────────┬─────────────┬─────────────────────────────────┐
 │ X     ┆ Y     ┆ Z    ┆ F      ┆ M         ┆ gg01_motion ┆ comment                         │
 │ ---   ┆ ---   ┆ ---  ┆ ---    ┆ ---       ┆ ---         ┆ ---                             │
-│ f64   ┆ f64   ┆ f64  ┆ f64    ┆ list[str] ┆ str         ┆ str                             │
+│ f64   ┆ f64   ┆ f64  ┆ f64    ┆ list[str] ┆ enum        ┆ str                             │
 ╞═══════╪═══════╪══════╪════════╪═══════════╪═════════════╪═════════════════════════════════╡
 │ null  ┆ null  ┆ null ┆ null   ┆ null      ┆ null        ┆ ;size of the square             │
 │ null  ┆ null  ┆ null ┆ null   ┆ null      ┆ null        ┆ ;size of the square             │
@@ -131,6 +135,17 @@ shape: (14, 7)
 
 The Python bindings also return the state of the program after execution, which can be used for inspection.
 
+#### Column dtypes
+
+Axis and other value columns are `Float64`, `N` is `Int64` and `M` is `List(String)`. Each G-group column (`gg01_motion`, `gg06_plane_select`, ...) is a `pl.Enum` whose categories are that group's commands in manual order; `G_GROUP_DTYPES` maps every G-group column name to its dtype, for building matching schemas or empty frames. Every batch and every run has the same Enum per column, so frames concatenate without a cast. The Python package requires polars 1.32 or newer. `T`, `comment`, `non_returning_function_call` and other free-text columns stay `String`. `nc_to_rows` yields plain `str` values.
+
+Things that differ from a `String` column:
+
+- `pl.col("gg01_motion") == "G1"` and `is_in(["G0", "G1"])` work; `is_in` with a value outside the group raises.
+- `.str` methods and joins against a `String` column raise; cast first with `.cast(pl.String)`.
+- `fill_null("")` leaves the nulls in place, because `""` is not a category. Cast to `String` first.
+- Sorting follows manual order (`G0`, `G1`, `G2`, ...), not alphabetical order.
+
 #### Streaming
 
 For long programs (or when you want results before the whole file is interpreted), `nc_to_rows` yields rows lazily while the interpreter runs on a background thread. Each row carries the 1-based source line it came from — loops and jumps repeat line numbers, which is exactly what a visualizer needs to map trace rows back to the program:
@@ -178,7 +193,7 @@ Measure a local program with
 --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.
+**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 (for example a live-edit re-interpret in an editor) rely on it for latest-wins cancellation.
 
 Additionally, conversion from a Polars DataFrame back to an MPF (NC) program is also supported:
 
@@ -202,7 +217,9 @@ Arguments:
 Options:
   -a, --axes <AXIS>                    Override default axis identifiers (comma-separated, e.g., "X,Y,Z")
   -e, --extra-axes <EXTRA_AXIS>        Add extra axis identifiers (comma-separated, e.g., "RA1,RA2")
-  -i, --initial_state <INITIAL_STATE>  Optional initial_state file to initialize state
+      --definitions <FILE>             Definition file (GUD/MGUD .DEF) to read before the program; repeat for several, read in order
+      --variables <FILE>               JSON object of variable values applied after the definitions, e.g. {"COUNT": 3}
+      --start <FILE>                   JSON object with the machine state at program start (the shape of the returned state)
   -l, --iteration_limit <LIMIT>             Maximum number of iterations for loops [default: 10000]
   -f, --disable-forward-fill           Disable forward-filling of null values in axes columns
   -h, --help                           Print help