base

tit.sim.base ¶

Base simulation class with shared logic for TI and mTI simulations.

BaseSimulation factors out the identical code shared by TISimulation and mTISimulation:

__init__ -- config, montage, logger, path manager, m2m_dir
_apply_tissue_conductivities -- SimulationConfig.tissue_conductivities overrides
run -- template method (setup dirs, viz, build session, post-process)
_init_session -- common SESSION setup (subpath, tensor, eeg_cap, flags)
_add_electrode_pair -- electrode creation on a TDCS list
_cropped_carriers / _write_volume_mesh / _write_central_surface -- the field outputs (:mod:tit.calc over all channel fields, any even count)

Subclasses implement the following abstract interface:

_simulation_mode -- property returning SimulationMode.TI or .MTI
_montage_type_label -- property returning "TI" or "mTI"
_montage_imgs_key -- property returning dirs key for montage images
_build_session -- mode-specific (TI or mTI) session construction
_post_process -- field computation and file organization

BaseSimulation ¶

BaseSimulation(config: SimulationConfig, montage: Montage, logger)

Bases: ABC

Abstract base class for TI/mTI simulations.

Provides the template-method run pipeline that subclasses customise by implementing _build_session and _post_process.

Parameters¶

config : SimulationConfig Fully specified simulation configuration. montage : Montage The electrode montage to simulate. logger : logging.Logger Logger instance for status and diagnostic messages.

Attributes¶

config : SimulationConfig Simulation configuration supplied at construction. montage : Montage Electrode montage supplied at construction. logger : logging.Logger Logger instance used throughout the pipeline. pm : tit.paths.PathManager Singleton path manager for BIDS path resolution. m2m_dir : str Absolute path to the subject's m2m_<subject> directory.

run ¶

run(simulation_dir: str, *, overwrite: bool = False) -> dict

Execute the full simulation pipeline for one montage.

This template method orchestrates directory setup, montage visualisation, SimNIBS FEM execution, and subclass-specific post-processing.

Parameters¶

simulation_dir : str Root simulations directory for the subject. overwrite : bool Replace an earlier result of this montage. The earlier run's derived outputs are removed first (see :func:tit.sim.utils.clear_previous_outputs), so the folder holds exactly what the new config.json says.

Returns¶

dict Result dictionary with keys montage_name, montage_type, status, and output_mesh.

Raises¶

FileExistsError If overwrite is False and the montage folder already holds a result mesh. Nothing is written, config.json included.

See Also¶

run_simulation : Calls run for each montage in a config.

Source code in tit/sim/base.py

def run(self, simulation_dir: str, *, overwrite: bool = False) -> dict:
    """Execute the full simulation pipeline for one montage.

    This template method orchestrates directory setup, montage
    visualisation, SimNIBS FEM execution, and subclass-specific
    post-processing.

    Parameters
    ----------
    simulation_dir : str
        Root simulations directory for the subject.
    overwrite : bool
        Replace an earlier result of this montage.  The earlier run's
        derived outputs are removed first (see
        :func:`tit.sim.utils.clear_previous_outputs`), so the folder holds
        exactly what the new ``config.json`` says.

    Returns
    -------
    dict
        Result dictionary with keys ``montage_name``, ``montage_type``,
        ``status``, and ``output_mesh``.

    Raises
    ------
    FileExistsError
        If *overwrite* is ``False`` and the montage folder already holds a
        result mesh.  Nothing is written, ``config.json`` included.

    See Also
    --------
    run_simulation : Calls ``run`` for each montage in a config.
    """
    montage_dir = self.pm.simulation(
        self.config.subject_id,
        self.montage.name,
    )
    # SimNIBS's own guard looks for its session record in pathfem, which
    # _organize_files moves into documentation/, so after a completed run it
    # never fires: the result mesh is the toolbox's own marker of a result.
    if overwrite:
        clear_previous_outputs(montage_dir)
    else:
        refuse_existing_result(montage_dir, self.montage.name)
    dirs = setup_montage_directories(
        montage_dir, self._simulation_mode, niftis=self.config.map_to_vol
    )
    create_simulation_config_file(
        self.config, self.montage, dirs["documentation"], self.logger
    )

    viz_pairs = None if self.montage.is_xyz else self.montage.electrode_pairs

    run_montage_visualization(
        montage_name=self.montage.name,
        simulation_mode=self._simulation_mode,
        eeg_net=self.montage.eeg_net,
        output_dir=dirs[self._montage_imgs_key],
        logger=self.logger,
        electrode_pairs=viz_pairs,
    )

    self.logger.info("SimNIBS simulation: Started")
    session = self._build_session(dirs["hf_dir"])
    self._session = session  # its conductivity settings feed hf_power_density
    if overwrite:
        # run_simnibs does not expose this supported SESSION option. Keep the
        # native existence guard for ordinary runs; never delete marker files.
        session.run(allow_multiple_runs=True)
    else:
        run_simnibs(session)
    self.logger.info("SimNIBS simulation: \u2713 Complete")

    output_mesh = self._post_process(dirs)
    self._write_report()
    self.logger.info(f"\u2713 {self.montage.name} complete")

    return {
        "montage_name": self.montage.name,
        "montage_type": self._montage_type_label,
        "status": "completed",
        "output_mesh": output_mesh,
        "output_dir": montage_dir,
    }