forward

tit.source.forward

Rebuild MNE-compatible EEG forward solutions from SimNIBS head models.

For a subject with an existing m2m_<id> head model, :func:prepare_forward produces the three files an MNE source-reconstruction needs:

• sub-<id>_net-<net>-fwd.fif -- the forward solution (gain matrix)
• sub-<id>_net-<net>-src.fif -- the cortical source space
• sub-<id>_net-<net>-morph.h5 -- a SourceMorph onto fsaverage

plus the point-electrode leadfield (*_leadfield.hdf5) and the head<->MRI transform (*-trans.fif) they are derived from. All outputs land under derivatives/SimNIBS/sub-<id>/forward/ -- a namespace distinct from the optimizer's leadfields/ (which uses modeled electrodes for stimulation dose; the EEG forward uses point electrodes per the SimNIBS EEG convention).

The expensive FEM leadfield is computed at most once per (subject, net, net CSV, head mesh): sub-<id>_net-<net>-provenance.json records the sha256 of the net CSV and head mesh (and the fsaverage spacing of the assembled files), and a re-run reuses the leadfield / MNE files only when they match exactly.

Runs under simnibs_python (imports both mne and simnibs)::

simnibs_python -m tit.source forward_config.json

See Also

tit.source.config.ForwardConfig : Parameter object. tit.source.fsaverage.project_fields_to_fsaverage : The companion field-mapping pipeline that puts simulation fields on the same fsaverage grid.

prepare_forward

prepare_forward(subject_id: str, cfg: ForwardConfig, *, output_dir: str | Path | None = None, info: Info | None = None, trans: Transform | None = None) -> tuple[Path, Path, Path]

Rebuild one subject's forward, source-space, and fsaverage morph files.

Parameters

subject_id : str Subject identifier without the sub- prefix (e.g. "101"). cfg : ForwardConfig EEG net, fsaverage spacing, FEM worker count, and overwrite flag. output_dir : str or pathlib.Path or None Destination directory. Defaults to pm.forward(subject_id) (derivatives/SimNIBS/sub-<id>/forward/). info : mne.Info or None A recording's Info whose dig carries the LPA, Nasion and RPA cardinal points. The head<->MRI transform is coregistered from them, so the forward is in the recording's head frame. Default: the net's own template fiducials. trans : mne.transforms.Transform or None An explicit head->MRI transform (MNE head -> MRI frames); used as is, never re-estimated. Pass info or trans, not both.

Returns

tuple of pathlib.Path (fwd_path, src_path, morph_path).

Source code in tit/source/forward.py

def prepare_forward(
    subject_id: str,
    cfg: ForwardConfig,
    *,
    output_dir: str | Path | None = None,
    info: mne.Info | None = None,
    trans: mne.transforms.Transform | None = None,
) -> tuple[Path, Path, Path]:
    """Rebuild one subject's forward, source-space, and fsaverage morph files.

    Parameters
    ----------
    subject_id : str
        Subject identifier without the ``sub-`` prefix (e.g. ``"101"``).
    cfg : ForwardConfig
        EEG net, fsaverage spacing, FEM worker count, and overwrite flag.
    output_dir : str or pathlib.Path or None
        Destination directory.  Defaults to ``pm.forward(subject_id)``
        (``derivatives/SimNIBS/sub-<id>/forward/``).
    info : mne.Info or None
        A recording's Info whose ``dig`` carries the LPA, Nasion and RPA
        cardinal points.  The head<->MRI transform is coregistered from them,
        so the forward is in the recording's head frame.  Default: the net's
        own template fiducials.
    trans : mne.transforms.Transform or None
        An explicit head->MRI transform (MNE head -> MRI frames); used as is,
        never re-estimated.  Pass ``info`` or ``trans``, not both.

    Returns
    -------
    tuple of pathlib.Path
        ``(fwd_path, src_path, morph_path)``.
    """
    _check_recording_geometry(info, trans)
    pm = get_path_manager()
    m2m_dir = Path(pm.m2m(subject_id))
    if not m2m_dir.is_dir():
        raise FileNotFoundError(f"m2m directory not found: {m2m_dir}")

    _check_forward_dependencies()

    forward_dir = (
        Path(output_dir) if output_dir is not None else Path(pm.forward(subject_id))
    )
    forward_dir.mkdir(parents=True, exist_ok=True)

    stem = f"sub-{subject_id}_net-{cfg.eeg_net}"
    expected = (
        forward_dir / f"{stem}-fwd.fif",
        forward_dir / f"{stem}-src.fif",
        forward_dir / f"{stem}-morph.h5",
    )
    electrodes, fiducials = _read_simnibs_montage(m2m_dir, cfg.eeg_net)

    # Cached files are reused only if built from these exact inputs: a net CSV
    # rewritten in place (the v3.1.1 cap re-apply) or a new head mesh rebuilds.
    eeg_csv = m2m_dir / "eeg_positions" / f"{cfg.eeg_net}.csv"
    provenance_path = forward_dir / f"{stem}-provenance.json"
    inputs = {
        "net_csv_sha256": sha256_file(eeg_csv),
        "head_mesh_sha256": sha256_file(m2m_dir / f"{subject_id}.msh"),
    }
    recorded = {} if cfg.overwrite else _read_provenance(provenance_path)
    same_inputs = all(recorded.get(k) == v for k, v in inputs.items())
    # Cached outputs may hold another recording's geometry, so a supplied
    # ``info``/``trans`` always rebuilds (the FEM leadfield is still reused).
    default_frame = info is None and trans is None
    if (
        same_inputs
        and default_frame
        and recorded.get("fsaverage_spacing") == cfg.fsaverage_spacing
        and _forward_outputs_valid(*expected)
    ):
        logger.info("Forward outputs already present for %s; skipping.", subject_id)
        return expected

    # SimNIBS names the leadfield <head mesh stem>_leadfield_<net>.hdf5.
    leadfield_hdf5 = forward_dir / f"{subject_id}_leadfield_{cfg.eeg_net}.hdf5"
    if same_inputs and _exists_real(leadfield_hdf5):
        logger.info("Reusing cached leadfield: %s", leadfield_hdf5.name)
    else:
        provenance_path.unlink(missing_ok=True)
        leadfield_hdf5.unlink(missing_ok=True)  # never append to a stale HDF5
        leadfield_hdf5 = _compute_leadfield(m2m_dir, forward_dir, eeg_csv, cfg.cpus)
        _write_provenance(provenance_path, inputs)

    # The Info is built *after* the leadfield, in the leadfield's channel order:
    # SimNIBS's assembly asserts `info["ch_names"] == forward["ch_names"]` element by
    # element, and the leadfield does not use the net CSV's order (below).
    electrodes = _in_leadfield_order(electrodes, leadfield_hdf5)
    montage_info, trans = _build_montage_info(
        electrodes, fiducials, info=info, trans=trans
    )

    info_path = forward_dir / f"{stem}-info.fif"
    trans_path = forward_dir / f"{stem}-trans.fif"
    mne.io.RawArray(
        np.zeros((len(montage_info.ch_names), 1)), montage_info, verbose=False
    ).save(str(info_path), overwrite=True, verbose=False)
    mne.write_trans(str(trans_path), trans, overwrite=True)

    # Not SimNIBS's own ``prepare_eeg_forward`` console script: that wrapper runs
    # ``python -E``, so no compatibility shim can reach it, and its MNE/cortech
    # bridge dies *after* the FEM leadfield above has been paid for. The worker
    # calls the same ``simnibs.eeg.forward.make_forward`` with the shims applied --
    # still a child process, so the ~0.9 GB gain matrix is reclaimed on exit.
    # See tit/source/_simnibs_compat.py.
    _run(
        [
            sys.executable,
            "-m",
            "tit.source._prepare_forward",
            str(m2m_dir),
            str(leadfield_hdf5),
            str(info_path),
            str(trans_path),
            "--fsaverage",
            str(cfg.fsaverage_spacing),
        ],
        f"MNE forward assembly for sub-{subject_id}",
        cwd=forward_dir,
    )
    outputs = _rename_generated_outputs(forward_dir, stem, leadfield_hdf5.stem)
    provenance = dict(inputs)
    if default_frame:  # a recording-frame forward is never reused as the default
        provenance["fsaverage_spacing"] = cfg.fsaverage_spacing
    _write_provenance(provenance_path, provenance)
    return outputs