Command-line programs

Every program prints its options with --help and its version with --version (-v). Options can be given in long or short form. Unless a section says otherwise, the programs read an ISMRMRD HDF5 file (see Input data format) and write NIfTI images (see Output files).

Program	What it does
forgeSense	SENSE reconstruction with field correction
forgePcSense	SENSE with shot-by-shot phase correction
forgePcSenseTimeSeg	forgePcSense with time-segmented field correction
oscillateRecon	Low-rank joint reconstruction of all repetitions
gridCoilImages	Gridded coil images, no iterative solve
GenSyntheticISMRMRD	Writes a synthetic test dataset
forgeSenseMPI, forgePcSenseMPI, forgePcSenseMPI_TS	MPI versions
forgeview	Terminal progress monitor

Options shared by the reconstruction programs

These options behave the same way in forgeSense, forgePcSense, forgePcSenseTimeSeg, oscillateRecon, gridCoilImages and the MPI programs.

Option	Default	Meaning
-i, --inputData	required	ISMRMRD HDF5 input file
-o, --outputImage	required	Output directory. It must already exist, except for gridCoilImages, which creates it.
-x, --Nx; -y, --Ny; -z, --Nz	from the header	Image matrix size. Without them, the size comes from the encoded matrix in the ISMRMRD header.
-d, --device	0	GPU index in CUDA builds. Metal always uses the default GPU and warns if you pass anything other than 0. CPU builds ignore it.
--log-level	info	trace, debug, info, warn or error
--no-tui		Write JSON lines on stderr and never start forgeview
--jsonl-output	stderr	Send JSON lines to stderr, stdout or a file path. Anything other than stderr implies --no-tui.
--no-jsonl		Plain log text and text progress bars instead of JSON lines. Implies --no-tui and overrides --jsonl-output.
--voxel-size x,y,z	from the header	Voxel size in mm along x (read), y (phase) and z, written to the NIfTI header
--no-orient		Write NIfTI files with no orientation
-h, --help		Print the options and exit
-v, --version		Print the version and exit

The iterative programs (all but gridCoilImages) also share these:

Option	Default	Meaning
-n, --CGIterations	10	Conjugate gradient iterations
-B, --Beta	0	Weight of the quadratic roughness penalty
-D, --Dims2Penalize	3	Penalize differences in 2 (x, y) or 3 (x, y, z) dimensions

Output modes describes what the progress options do, and Monitor a reconstruction shows how to use them.

forgeSense

SENSE reconstruction of single-shot or multi-shot data, with off-resonance correction from the field map. One image is reconstructed for every slice, repetition, average, echo and cardiac phase in the file.

Input arrays: SENSEMap and FieldMap.

Option	Default	Meaning
-F, --FourierTransform	required	Forward model: NUFFT (gridding with time-segmented field correction), DFT (exact field-corrected DFT, much slower) or DFTGrads (DFT that also models field-map gradients)
-t, --TimeSegments	from the readout	Time segments for NUFFT. Without it, the program uses one segment per 2 ms of readout with hanning, or per 3 ms with minmax or histo. 1 turns field correction off.
-I, --TimeSegmentationInterp	hanning	Time-segment interpolator for NUFFT: hanning, minmax or histo
-s, --NShots	1	Number of shots, passed to the time-segmentation operator

forgeSense -i data.h5 -o recon/ -F NUFFT -t 6 -I minmax -n 20 -B 0.001

forgePcSense

SENSE with a separate phase map for every shot, for multi-shot acquisitions with shot-to-shot phase errors such as multi-shot diffusion or MRE. Each shot uses a field-corrected DFT, so there is no -F or -t.

Input arrays: SENSEMap, FieldMap and PhaseMaps.

The number of shots comes from the header (the kspace_encoding_step_1 limit). -s is accepted but not used.

forgePcSense -i data.h5 -o recon/ -n 10 -B 0.001

forgePcSenseTimeSeg

forgePcSense with time-segmented NUFFT field correction in place of the DFT. It is much faster for long readouts.

Input arrays: SENSEMap, FieldMap and PhaseMaps.

Option	Default	Meaning
-t, --TimeSegments	from the readout	As for forgeSense
-I, --TimeSegmentationInterp	hanning	As for forgeSense
-s, --NShots		Accepted but not used. The number of shots comes from the header.

forgePcSenseTimeSeg -i data.h5 -o recon/ -t 6 -I minmax -n 10 -B 0.001

oscillateRecon

Low-rank reconstruction of all repetitions together. The images of the repetitions are modelled as a few spatial images combined with a temporal basis read from the file, and each repetition has its own pcSenseTimeSeg operator. Low-rank reconstruction explains the model.

Input arrays: SENSEMap, FieldMap, PhaseMaps and v, the NRep × NRep temporal basis.

Option	Default	Meaning
-L, --Rank	1	Number of temporal basis vectors to use, from 1 to the number of repetitions
-t, --TimeSegments	required	Time segments for field correction
-I, --TimeSegmentationInterp	required	hanning, minmax or histo
-s, --NShots	1	Accepted but not used

Here -L is the rank, not the number of time segments.

One image is written for each slice, average, echo and cardiac phase, with all repetitions as frames of a 4-D file: img_Slice0_Avg0_Echo0_Phase0_mag.nii.

oscillateRecon -i data.h5 -o recon/ -L 12 -t 6 -I minmax -n 20 -B 0.01

gridCoilImages

Grids each coil's data with density compensation, with no iterative solve. Use it to inspect raw data or as the first step in estimating coil sensitivity maps.

The input needs only the k-space data and trajectories, no SENSEMap or FieldMap. The in-plane matrix must be square.

Option	Default	Meaning
--dcf-iterations	2	Pipe-Menon density compensation iterations. 0 turns density compensation off.

It has no -n, -B or -D. -x and -y must be equal.

For each repetition, average, echo and cardiac phase it writes:

• img_Rep0_Avg0_Echo0_Phase0_mag.nii and ..._phs.nii: the coil images, one frame per coil (4-D, or 5-D when the file has several slices).
• imSOS_Rep0_Avg0_Echo0_Phase0.nii: their root sum of squares.

gridCoilImages -i scan_cal.h5 -o coils/ --dcf-iterations 25

GenSyntheticISMRMRD

Writes a synthetic radial dataset: a Shepp-Logan phantom with coil sensitivities, a field map and, for more than one shot, shot phase maps.

Option	Default	Meaning
-o, --output	required	Output file
-x, -y, -z	64, 64, 1	Image size
-c, --coils	4	Number of coils
-k, --spokes	128	Radial spokes
-r, --readout	128	Samples per spoke
-f, --fieldmap-hz	0	Peak off-resonance in Hz. The data are simulated with this field map, and it is written in rad/s.
-s, --shots	1	Shots. More than 1 writes one acquisition per shot and adds PhaseMaps for pcSENSE. Must divide -k.
-T, --readout-time	0.01	Length of each readout in seconds: one spoke, or one shot with -s
--snr	0	Add noise at this SNR in dB. 0 adds none.

MPI programs

Built when MPISupport=ON and CMake finds MPI. Each takes the options of its single-process program, with these differences.

Program	Based on	Differences
forgeSenseMPI	forgeSense	-I and -t are required
forgePcSenseMPI	forgePcSense
forgePcSenseMPI_TS	forgePcSenseTimeSeg

All three add:

Option	Default	Meaning
-d, --device	auto	auto gives rank r GPU r mod (number of GPUs) in CUDA builds. A number puts every rank on that GPU. No effect in CPU and Metal builds.
--mpi-log-all		Log from every rank. By default only rank 0 logs to the terminal and the others log to forge.log only.

Run a reconstruction with MPI explains how each program splits the work.

forgeview

Reads JSON lines on standard input and draws a full-screen monitor. The reconstruction programs start it for you; see Monitor a reconstruction. Press q or Esc to quit.

forgeSense [options] --no-tui 2>&1 | forgeview

Exit codes

Code	Meaning
0	Success
1	Unexpected runtime error
2	Invalid options or input, such as a file with more than one encoding space
3	GPU initialization or device selection failed
130	Cancelled with Ctrl-C (SIGINT). The program stops before the next image and does not write the one it was working on.