Diffing and incremental mapping

munchi diff

Compare two mapping result files (JSON or IMAS HDF5/NetCDF) and print a human-readable summary of which paths were added, removed, or changed:

munchi diff baseline.json updated.json

Output format:

--- baseline.json
+++ updated.json

+ magnetics/flux_loop[2]/field           1.23e-03
- magnetics/b_field_pol_probe[0]/field   4.56e-04
~ magnetics/flux_loop[0]/field           7.8e-04 → 7.9e-04

Summary: 1 added, 1 removed, 1 changed, 42 unchanged

Symbols:

  • + path is new in the second file

  • - path was removed from the first file

  • ~ path exists in both files but its value changed

  • (space) path is identical — hidden by default

Unchanged paths are hidden by default. To show them:

munchi diff baseline.json updated.json --show-unchanged

Restrict the comparison to specific IDS names:

munchi diff a.json b.json --ids magnetics equilibrium

munchi update — incremental mapping

Map only the paths that are missing from an existing result file, then merge with the existing data and write a new file. This avoids re-running the mapper on paths that are already present:

# First pass — map what you have now.
munchi map --ids magnetics --output results.json

# Later — schema or mapping file changed; fill in the gaps.
munchi update --input results.json --output results-full.json \
    --ids magnetics

Options:

  • --mapping FILE restrict the missing-path search to keys in a mapping file (same semantics as munchi map --mapping)

  • --config FILE path to munchi.toml

  • --device NAME override the device name from config

  • --set KEY=VALUE ad-hoc config overrides (repeatable)

Typical workflow

# 1. Generate stubs for all leaf paths.
munchi init-mapping --ids magnetics --leaves-only --output magnetics.json

# 2. Annotate and implement paths in magnetics.json.

# 3. Map using the file as a filter.
munchi map --ids magnetics --mapping magnetics.json --output results.json

# 4. Compare with a previous run.
munchi diff results-prev.json results.json

# 5. Schema updated — add stubs for new paths without losing existing data.
munchi update-mapping --ids magnetics --mapping magnetics.json \
    --output magnetics-v2.json

# 6. Incrementally fill in the new paths.
munchi update --input results.json --output results-v2.json \
    --ids magnetics --mapping magnetics-v2.json

Library usage

from tokamunch.diff import diff_records, diff_files, render_diff, DiffEntry
from tokamunch.mapping import MappingRecord

records_a = [MappingRecord(ids_path="a/b", value=1.0)]
records_b = [MappingRecord(ids_path="a/b", value=2.0)]

entries: list[DiffEntry] = diff_records(records_a, records_b)
print(render_diff(entries, "before", "after"))

# Compare files directly (JSON or IMAS).
entries = diff_files("baseline.json", "updated.json", ids_names=["magnetics"])