CLI reference¶

The reference below is generated directly from tokamunch.cli.build_parser(), so it stays aligned with the actual command-line interface.

IDS mapping CLI

usage: munchi [-h] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
              [--log-file FILE]
              [--log-file-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
              {paths,map,init-config,init-mapping,convert,check,update-mapping,diff,update,completions} ...

Positional Arguments¶

command: Possible choices: paths, map, init-config, init-mapping, convert, check, update-mapping, diff, update, completions

Named Arguments¶

--log-level

Possible choices: DEBUG, INFO, WARNING, ERROR, CRITICAL

Logging verbosity; overrides log_level in config (default: WARNING)

--log-file

Write log output to FILE in addition to (or instead of) the console

--log-file-level

Possible choices: DEBUG, INFO, WARNING, ERROR, CRITICAL

Verbosity for the file log sink (default: DEBUG)

Default: 'DEBUG'

Sub-commands¶

paths¶

Expand and print concrete IDS runtime paths

munchi paths [-h] [--config CONFIG] [--device DEVICE] [--shot SHOT]
             [--leaves-only] [--set KEY=VALUE] --ids IDS [--match MATCH]
             [--schema-map] [--output FILE] [--force]

Named Arguments¶

--config

munchi config file

Default: 'munchi.toml'

--device

Override device from config

--shot

Override shot from config

--leaves-only

Only include leaf paths

Default: False

--set

Override a config value at runtime, e.g. –set run.concurrency.mode=thread –set run.concurrency.workers=4. Can be repeated.

--ids

IDS name to expand, e.g. ‘magnetics’

--match

Glob-style filter applied to expanded concrete runtime paths, e.g. ‘magnetics/flux_loop*’

--schema-map

Show each schema path ((:) notation) alongside the concrete path(s) it expands to. Console: ‘schema -> concrete’ lines. JSON: {schema_path: [concrete_path, …]}.

Default: False

--output

Write output to a JSON file instead of printing to the console

--force

Overwrite output file if it already exists

Default: False

Path syntax:

Concrete runtime path:: magnetics/flux_loop[0]/position[0]/r
Non-concrete IDS/schema path:: magnetics/flux_loop(:)/position(:)/r
Mapping-template path:: magnetics/flux_loop[#]/position[#]/r

Notes:

‘map –path’ expects one concrete path.
‘map –ids magnetics’ expands all concrete paths for that IDS.
‘–match’ filters expanded concrete paths, e.g. ‘magnetics/flux_loop*’.
‘–mapping’ restricts paths to those present in a mapping JSON file.

map¶

Map one concrete path or all concrete paths of an IDS

munchi map [-h] [--config CONFIG] [--device DEVICE] [--shot SHOT]
           [--leaves-only] [--set KEY=VALUE] (--ids IDS | --path PATH |
           --paths PATH_OR_FILE [PATH_OR_FILE ...]) [--match MATCH] [--force]
           [--verbose-errors] [--output OUTPUT] [--mapping FILE]
           [--concurrency-mode {serial,thread,process}] [--workers N]
           [--binary-arrays] [--on-imas-error {fallback-json,raise}]
           [--dry-run] [--limit N] [--profile-stats] [--profile FILE]
           [--verbose] [--shots N [N ...] | --shot-range START [END ...]]
           [--checkpoint FILE]

Named Arguments¶

--config

munchi config file

Default: 'munchi.toml'

--device

Override device from config

--shot

Override shot from config

--leaves-only

Only include leaf paths

Default: False

--set

Override a config value at runtime, e.g. –set run.concurrency.mode=thread –set run.concurrency.workers=4. Can be repeated.

--ids

IDS name to expand into concrete runtime paths, e.g. ‘magnetics’

--path

Single concrete runtime path, e.g. ‘magnetics/flux_loop[0]/position[0]/r’

--paths

One or more concrete runtime paths, or a single path to a text file containing newline-delimited paths (lines starting with ‘#’ are ignored)

--match

Glob-style filter applied to expanded concrete runtime paths, e.g. ‘magnetics/flux_loop*’

--force

Overwrite output file if it already exists

Default: False

--verbose-errors

Show suppressed ‘missing mapping’ errors as well

Default: False

--output

Output destination. Default: terminal text. Use .json for JSON, .h5 for HDF5, .nc for NetCDF (imas-python required for .h5/.nc).

--mapping

Path to a mapping JSON file. Only IDS paths whose template form appears as a key in the file will be mapped.

--concurrency-mode

Possible choices: serial, thread, process

Override concurrency mode from config

--workers

Override number of parallel workers from config

--binary-arrays

Encode numpy arrays as base64 binary objects in JSON output (overrides run.binary_arrays in config; default: false)

Default: False

--on-imas-error

Possible choices: fallback-json, raise

Action when an IDS fails to write to an IMAS file. ‘fallback-json’ (default) logs the error and writes failed IDS records to a companion _fallback.json file; ‘raise’ stops the run immediately.

--dry-run

Expand paths only — do not call the mapper. Useful for checking how many paths will be mapped and how long path expansion takes.

Default: False

--limit

Map at most N paths (after expansion and filtering). Useful for quick tests.

--profile-stats

Print a profiling report after the run: phase timings (expansion / mapping / output), per-call stats for mapper.map() and get_array_length(), and bottleneck hints.

Default: False

--profile

Write a cProfile stats file to FILE for detailed line-level profiling. Inspect with: python -m pstats FILE or snakeviz FILE

--verbose

Show expanded output for each mapped value (dtype, shape, min/max, first elements). Errors show full traceback.

Default: False

--shots

Map these specific shot numbers. –output is required and may contain {shot} as a template.

--shot-range

Map shots in range START..END (inclusive), with optional STEP. Provide 2 or 3 integers: START END [STEP]. –output is required and may contain {shot} as a template.

--checkpoint

Checkpoint file path. If the file exists, completed paths are skipped and mapping resumes from where it left off. The checkpoint is deleted on successful completion.

Path syntax:

Concrete runtime path:: magnetics/flux_loop[0]/position[0]/r
Non-concrete IDS/schema path:: magnetics/flux_loop(:)/position(:)/r
Mapping-template path:: magnetics/flux_loop[#]/position[#]/r

Notes:

‘map –path’ expects one concrete path.
‘map –ids magnetics’ expands all concrete paths for that IDS.
‘–match’ filters expanded concrete paths, e.g. ‘magnetics/flux_loop*’.
‘–mapping’ restricts paths to those present in a mapping JSON file.

init-config¶

Create a skeleton munchi config file

munchi init-config [-h] [--output OUTPUT] [--force]

Named Arguments¶

--output

Output config path

Default: 'munchi.toml'

--force

Overwrite output file if it already exists

Default: False

init-mapping¶

Create a blank JSON mapping template from IDS schema paths

munchi init-mapping [-h] --ids IDS [--output OUTPUT] [--leaves-only] [--force]

Named Arguments¶

--ids

IDS name, e.g. ‘magnetics’

--output

Output mapping JSON path

Default: 'mapping.json'

--leaves-only

Only include leaf schema paths

Default: False

--force

Overwrite output file if it already exists

Default: False

Path syntax:

Concrete runtime path:: magnetics/flux_loop[0]/position[0]/r
Non-concrete IDS/schema path:: magnetics/flux_loop(:)/position(:)/r
Mapping-template path:: magnetics/flux_loop[#]/position[#]/r

Notes:

‘map –path’ expects one concrete path.
‘map –ids magnetics’ expands all concrete paths for that IDS.
‘–match’ filters expanded concrete paths, e.g. ‘magnetics/flux_loop*’.
‘–mapping’ restricts paths to those present in a mapping JSON file.

convert¶

Convert between munchi JSON output and imas-python IMAS files.

Supported formats: .json .h5 .nc

Primary use case — load a non-compliant JSON into IDS objects in Python:: records = read_json_records(Path(‘results.json’)) ids_objects = records_to_ids_objects(records) ids_objects[‘equilibrium’].time_slice[0].time = 0.5 # add missing fields with imas.DBEntry(…) as db: db.put(ids_objects[‘equilibrium’])

munchi convert [-h] --input FILE --output FILE [--ids IDS [IDS ...]]
               [--binary-arrays] [--on-imas-error {fallback-json,raise}]
               [--force]

Named Arguments¶

--input

Input file (.json, .h5, or .nc)

--output

Output file (.json, .h5, or .nc)

--ids

IDS name(s) to read when the input is an IMAS file (e.g. –ids magnetics equilibrium). Not needed for JSON input.

--binary-arrays

Encode numpy arrays as base64 binary objects in JSON output

Default: False

--on-imas-error

Possible choices: fallback-json, raise

Action when an IDS fails to write: ‘fallback-json’ (default) writes failed records to a _fallback.json companion file; ‘raise’ stops immediately.

--force

Overwrite output file if it already exists

Default: False

check¶

Validate config/mapper setup and optionally an IDS schema

munchi check [-h] [--config CONFIG] [--device DEVICE] [--shot SHOT]
             [--leaves-only] [--set KEY=VALUE] [--ids IDS]

Named Arguments¶

--config

munchi config file

Default: 'munchi.toml'

--device

Override device from config

--shot

Override shot from config

--leaves-only

Only include leaf paths

Default: False

--set

Override a config value at runtime, e.g. –set run.concurrency.mode=thread –set run.concurrency.workers=4. Can be repeated.

--ids

Optional IDS name to validate and inspect

Path syntax:

Concrete runtime path:: magnetics/flux_loop[0]/position[0]/r
Non-concrete IDS/schema path:: magnetics/flux_loop(:)/position(:)/r
Mapping-template path:: magnetics/flux_loop[#]/position[#]/r

Notes:

‘map –path’ expects one concrete path.
‘map –ids magnetics’ expands all concrete paths for that IDS.
‘–match’ filters expanded concrete paths, e.g. ‘magnetics/flux_loop*’.
‘–mapping’ restricts paths to those present in a mapping JSON file.

update-mapping¶

Add new stub entries to an existing mapping JSON file

munchi update-mapping [-h] --ids IDS --mapping FILE [--output FILE]
                      [--leaves-only] [--force]

Named Arguments¶

--ids

IDS name, e.g. ‘magnetics’

--mapping

Existing mapping JSON file to update

--output

Output file (default: print JSON to stdout)

--leaves-only

Only add stubs for leaf schema paths

Default: False

--force

Overwrite output file if it already exists

Default: False

diff¶

Compare two mapping result files

munchi diff [-h] [--ids IDS [IDS ...]] [--show-unchanged] FILE_A FILE_B

Positional Arguments¶

FILE_A: First file (.json, .h5, or .nc)
FILE_B: Second file (.json, .h5, or .nc)

Named Arguments¶

--ids

IDS name(s) to read when the input is an IMAS file

--show-unchanged

Also print unchanged paths

Default: False

update¶

Map missing paths and merge with existing results

munchi update [-h] [--config CONFIG] [--device DEVICE] [--shot SHOT]
              [--leaves-only] [--set KEY=VALUE] --input FILE --output FILE
              [--ids IDS] [--mapping FILE] [--force] [--verbose-errors]

Named Arguments¶

--config

munchi config file

Default: 'munchi.toml'

--device

Override device from config

--shot

Override shot from config

--leaves-only

Only include leaf paths

Default: False

--set

Override a config value at runtime, e.g. –set run.concurrency.mode=thread –set run.concurrency.workers=4. Can be repeated.

--input

Existing result file (.json, .h5, or .nc)

--output

Output file (.json, .h5, or .nc)

--ids

IDS name to map (required for IMAS input; optional for JSON)

--mapping

Restrict paths to those present in this mapping JSON file

--force

Overwrite output file if it already exists

Default: False

--verbose-errors

Show suppressed ‘missing mapping’ errors as well

Default: False

completions¶

Generate shell completion scripts

munchi completions [-h] {bash,zsh,fish}

Positional Arguments¶

shell

Possible choices: bash, zsh, fish

Target shell

Path syntax:

Concrete runtime path:: magnetics/flux_loop[0]/position[0]/r
Non-concrete IDS/schema path:: magnetics/flux_loop(:)/position(:)/r
Mapping-template path:: magnetics/flux_loop[#]/position[#]/r

Notes:

’map –path’ expects one concrete path.
’map –ids magnetics’ expands all concrete paths for that IDS.
’–match’ filters expanded concrete paths, e.g. ‘magnetics/flux_loop*’.
’–mapping’ restricts paths to those present in a mapping JSON file.