MATLAB Backend

MATLAB modules are called via a persistent forge_dispatcher.m session. The forge_* helper functions are available once forge_session_init has been called (done automatically by forge_read_config).

---

Module Structure

Every MATLAB module must be a function that accepts a config path and returns a cell array of output paths:

function output_paths = my_module(config_path)
    % MY_MODULE  Brief description
    config     = forge_read_config(config_path);
    output_dir = config.output_dir;
    % ... your code ...
    output_paths = {out_path};
end

The function name must match the filename (standard MATLAB convention).

---

Minimal Example

function output_paths = minimal_module(config_path)
%MINIMAL_MODULE  Simplest compliant FORGE Studio module.

  config     = forge_read_config(config_path);
  output_dir = config.output_dir;

  forge_log('info', 'minimal_module: starting');

  result   = zeros(64, 64, 32, 'single');
  out_path = fullfile(output_dir, 'result.mat');
  save(out_path, 'result', '-v7.3');

  forge_log('info', 'minimal_module: done, wrote %s', 'result.mat');
  output_paths = {out_path};
end

---

Iterative Reconstruction Example

function output_paths = iterative_recon(config_path)
%ITERATIVE_RECON  Iterative reconstruction with live monitoring.

  config     = forge_read_config(config_path);
  output_dir = config.output_dir;
  input_path = config.input_paths{1};

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

  forge_log('info', 'starting: n_iter=%d step_size=%.4f', n_iter, step_size);

  x = zeros(64, 64, 32, 'single');
  for i = 1:n_iter
    % --- your reconstruction update here ---
    error_norm = 1.0 / i;
    penalty    = 0.5 / i;

    forge_progress('iter', i, n_iter, 'Iterating', ...
                   sprintf('err=%.3g', error_norm));
    forge_convergence('iter', i, error_norm, penalty);
  end
  forge_progress_done('iter');

  out_path = fullfile(output_dir, 'recon.mat');
  save(out_path, 'x', '-v7.3');
  forge_log('info', 'done');
  output_paths = {out_path};
end

---

API Reference

forge_read_config(config_path)

Loads the step config JSON and returns a struct. Automatically initialises the session.

config = forge_read_config(config_path);

config.job_id        % char — job identifier
config.step_id       % char — step identifier
config.stage_index   % double — 0-based stage number
config.input_paths   % cell array of char — input files
config.output_dir    % char — directory to write outputs
config.input_format  % char — 'twix' | 'ismrmrd' | 'mat' | 'jld2' | 'npy'
config.params        % struct — user parameter values
config.channels      % double (optional)

---

forge_param(config, name, default)

Reads a named parameter from config.params. Returns default if absent or empty.

n_iter    = forge_param(config, 'n_iter', 100);
use_gpu   = forge_param(config, 'use_gpu', true);
solver    = forge_param(config, 'solver', 'CG');

---

forge_log(level, message, ...)

Emits a log event using fprintf-style formatting.

forge_log('info',  'Starting calibration');
forge_log('warn',  'Low SNR: %d channels', n_channels);
forge_log('error', 'Convergence failed at iter %d', i);

Levels: 'debug', 'info', 'warn', 'error'.

---

forge_progress(bar_id, current, max_val, label, postfix)

Reports progress.

forge_progress('recon', i, n_iter, 'Reconstructing', sprintf('err=%.3g', err));

postfix is optional — pass '' to omit.

---

forge_progress_done(bar_id)

Marks a progress bar complete.

forge_progress_done('recon');

---

forge_convergence(bar_id, iter, error_norm, penalty)

Emits metrics for the convergence chart. Additional named metrics are not supported in the MATLAB backend (use Python or Julia for **kwargs equivalent).

forge_convergence('recon', i, error_norm, penalty);

---

forge_is_session()

Returns true inside a FORGE Studio managed session.

if forge_is_session()
    forge_log('info', 'running in FORGE Studio');
else
    fprintf('standalone mode\n');
end

---

Helper Location

All forge_*.m files are in resources/matlab/ within the app bundle. The dispatcher adds this directory to the MATLAB path automatically via addpath.

---

Config Access

Config fields are accessed as struct fields (not map keys):

% Correct:
output_dir = config.output_dir;
input_file = config.input_paths{1};

% Params:
lambda = config.params.lambda;
% or equivalently:
lambda = forge_param(config, 'lambda', 0.01);

---

Testing Your Module

Use the forge-session dev tool →:

node scripts/forge-session.mjs --matlab /Applications/MATLAB_R2024a.app/bin/matlab --repl
matlab> run minimal_module

Or call it directly from the MATLAB command window:

addpath('/path/to/forge-studio/resources/matlab')
output_paths = minimal_module('/tmp/test_config.json')