Step Config Format

FORGE Studio writes a JSON config file for each step before calling your module. The file is placed in the stage output directory and its path is passed as the sole argument to run().

---

Full Schema

{
  "job_id":       "abc-123-def",
  "step_id":      "espirit_calib",
  "stage_index":  0,
  "input_paths":  ["/data/meas_MID00107_FID16594.dat"],
  "output_dir":   "/output/stage_0_sensitivity_calibration",
  "input_format": "twix",

  "platform":          "VE11E",
  "channels":          32,
  "slices":            null,
  "shots":             null,
  "calibration_path":  null,
  "navigators_path":   null,

  "params": {
    "calibration_size": 24,
    "use_gpu": true,
    "solver": "CG"
  }
}

---

Required Fields

Field	Type	Description
job_id	string	Unique job identifier (UUID)
step_id	string	Step identifier from the workflow YAML
stage_index	integer	0-based stage position in the pipeline
input_paths	string[]	Absolute paths to input files. Stage 0 = the raw file the user selected. Subsequent stages = the output files of the previous stage.
output_dir	string	Directory where the module must write its output files. Created before the module is called.
input_format	string	Format of input_paths[0] — see table below
params	object	User-configured parameter values from the workflow definition

---

input_format Values

Detected from the file extension of input_paths[0]:

Value	Extension	Format
twix	.dat	Siemens TWIX raw data
ismrmrd	.h5, .hdf5, .mrd	ISMRMRD HDF5
mat	.mat	MATLAB MAT file
jld2	.jld2	Julia JLD2 file
npy	.npy	NumPy array
npz	.npz	NumPy compressed archive

---

Optional Acquisition Context Fields

These fields are populated from the file header when available. Always check for null before using.

Field	Type	Description
platform	string | null	Siemens platform revision (e.g. "VE11E", "XA61")
channels	integer | null	Number of active receive channels
slices	integer | null	Number of slices (where applicable)
shots	integer | null	Number of shots (where applicable)
calibration_path	string | null	Path to a calibration file if one was produced in a prior stage
navigators_path	string | null	Path to a navigators file if available

---

params Object

The params object contains all parameters declared in the workflow step definition, with user-overridden or default values applied. Parameter values are always one of:

Type	JSON type
int	number (integer)
float	number
bool	boolean
enum	string
string	string
int_array	number[]
float_array	number[]

Read params using the forge_param helper to safely handle missing keys and empty values:

Python:

n_iter = forge_param(config, "n_iter", default=100)

Julia:

n_iter = forge_param(config, "n_iter"; default=100)

MATLAB:

n_iter = forge_param(config, 'n_iter', 100);

Or access config["params"]["n_iter"] / config.params.n_iter directly if you are sure the key is present.

---

Stage Chaining Example

A three-stage pipeline where each stage consumes the previous stage's outputs:

Stage 0 (preprocessing, Python):

{
  "stage_index": 0,
  "input_paths": ["/data/scan.dat"],
  "input_format": "twix",
  "output_dir":  "/out/stage_0_sensitivity_calibration"
}

→ produces /out/stage_0_sensitivity_calibration/maps.npy

Stage 1 (reconstruction, FORGE):

{
  "stage_index": 1,
  "input_paths": ["/out/stage_0_sensitivity_calibration/maps.npy"],
  "input_format": "npy",
  "output_dir":  "/out/stage_1_cs_sense"
}

→ produces /out/stage_1_cs_sense/output.nii

Stage 2 (postprocessing, Julia):

{
  "stage_index": 2,
  "input_paths": ["/out/stage_1_cs_sense/output.nii"],
  "input_format": "ismrmrd",
  "output_dir":  "/out/stage_2_postprocessing"
}

---

Config File Location

The config file is written to:

<output_dir>/_step_config_<step_id>.json

It remains on disk after the stage completes, useful for debugging.