FORGE Backend (C++/CUDA)

The FORGE backend runs bundled C++/CUDA reconstruction binaries: forgeSense, forgePcSense, and forgeOscillateRecon. These are invoked as child processes — no persistent session.

---

How It Works

For each FORGE stage, FORGE Studio:

1. Resolves the binary path based on the selected compute variant (Metal / CUDA / CPU).
2. Builds a CLI command from the step's parameters.
3. Spawns the binary, capturing stderr as a JSONL event stream.
4. Reports progress, metrics, and image previews in real time.

---

Available Binaries

Binary	Description
forgeSense	SENSE/CS-SENSE reconstruction
forgePcSense	Phase-contrast SENSE
forgeOscillateRecon	OSCILLATE oscillating steady-state reconstruction

Binaries live at:

<forge-install>/bin/{cuda,metal,cpu}/<binary-name>

The default search paths are /usr/local/forge, /opt/forge, and ~/forge. Override in Settings → FORGE Engine.

---

Workflow Configuration

Set backend: forge on a stage, then configure the step with the desired binary as the module:

stages:
  - name: CS-SENSE Reconstruction
    type: reconstruction
    backend: forge
    steps:
      - id: cs_sense
        name: CS-SENSE
        module: forgeSense
        params:
          iterations:
            type: int
            label: Max iterations
            default: 40
          lambda:
            type: float
            label: Regularization (λ)
            default: 0.01
            scale: log
            precision: 4
          solver:
            type: enum
            label: Solver
            values: [CG, ADMM, FISTA, POGM]
            default: CG

---

Parameter Mapping

Step parameters are mapped to CLI flags. Integer, float, bool, and enum params become --param-name value flags. Array params are passed as space-separated values:

forgeSense --input /data/scan.dat --output /out/output.nii \
           --iterations 40 --lambda 0.01 --solver CG

Multi-step FORGE stages collapse all step parameters into a single binary invocation.

---

Output

FORGE binaries produce NIfTI output (.nii). The output path is set automatically by FORGE Studio to <stage-output-dir>/output.nii.

---

JSONL Progress Protocol

FORGE binaries report progress via stderr as newline-delimited JSON events:

{"type":"progress","action":"add","id":1,"label":"SENSE","max":40}
{"type":"progress","action":"tick","id":1,"current":1,"postfix":"err=0.123"}
{"type":"metrics","bar_id":1,"iter":1,"error_norm":0.123,"penalty":0.045}
{"type":"image_preview","iter":10,"bar_id":1,"slices":{...}}
{"type":"progress","action":"done","id":1}

These are parsed by jsonl-parser.ts and forwarded to the renderer as Redux actions.

---

Compute Variants

FORGE binaries are statically linked against the CUDA runtime (no system CUDA required). The correct variant is selected automatically:

Variant	Condition
metal	macOS with Apple Silicon
cuda	Linux with NVIDIA GPU detected via nvidia-smi
cpu	Fallback — always available

Override with Settings → Compute Backend → Select.

---

Verifying Installation

Go to Settings → FORGE Engine to verify binary availability. The panel shows:

• Installation source (bundled vs external).
• Per-variant (CUDA / Metal / CPU) availability.
• Binary version string.

If no FORGE binaries are found, reconstruction stages with backend: forge will fail at start with FORGE_ENGINE_MISSING.