optical_module

class MCXAdapter(global_settings: Settings)

Bases: OpticalAdapterBase

This class implements a bridge to the mcx framework to integrate mcx into SIMPA. This adapter only allows for computation of fluence, for computations of diffuse reflectance, take a look at simpa.ReflectanceMcxAdapter

Note

MCX is a GPU-enabled Monte-Carlo model simulation of photon transport in tissue: Fang, Qianqian, and David A. Boas. “Monte Carlo simulation of photon migration in 3D turbid media accelerated by graphics processing units.” Optics express 17.22 (2009): 20178-20190.

initializes MCX-specific configuration and clean-up instances

Parameters:

global_settings – global settings used during simulations

forward_model(absorption_cm: ndarray, scattering_cm: ndarray, anisotropy: ndarray, illumination_geometry: IlluminationGeometryBase) → Dict

runs the MCX simulations. Binary file containing scattering and absorption volumes is temporarily created as input for MCX. A JSON serializable file containing the configuration required by MCx is also generated. The set of flags parsed to MCX is built based on the Tags declared in self.component_settings, the results from MCX are used to populate an instance of Dict and returned.

Parameters:

• absorption_cm – array containing the absorption of the tissue in cm units

• scattering_cm – array containing the scattering of the tissue in cm units

• anisotropy – array containing the anisotropy of the volume defined by absorption_cm and scattering_cm

• illumination_geometry – and instance of IlluminationGeometryBase defining the illumination geometry

Returns:

Dict containing the results of optical simulations, the keys in this dictionary-like object depend on the Tags defined in self.component_settings

generate_mcx_bin_input(absorption_cm: ndarray, scattering_cm: ndarray, anisotropy: ndarray, assumed_anisotropy: ndarray) → None

generates binary file containing volume scattering and absorption as input for MCX

Parameters:

• absorption_cm – Absorption in units of per centimeter

• scattering_cm – Scattering in units of per centimeter

• anisotropy – Dimensionless scattering anisotropy

• assumed_anisotropy –

Returns:

None

generate_mcx_json_input(settings_dict: Dict) → None

generates JSON serializable file with settings needed by MCX to run simulations.

Parameters:

settings_dict – dictionary to be saved as .json

Returns:

None

get_command() → List

generates list of commands to be parse to MCX in a subprocess

Returns:

list of MCX commands

get_mcx_settings(illumination_geometry: IlluminationGeometryBase, assumed_anisotropy: ndarray, **kwargs) → Dict

generates MCX-specific settings for simulations based on Tags in self.global_settings and self.component_settings . Among others, it defines the volume type, dimensions and path to binary file.

Parameters:

• illumination_geometry – and instance of IlluminationGeometryBase defining the illumination geometry

• assumed_anisotropy –

• kwargs – dummy, used for class inheritance

Returns:

dictionary with settings to be used by MCX

static post_process_volumes(**kwargs) → Tuple

post-processes volumes after MCX simulations. Dummy function implemented for compatibility with inherited classes

Parameters:

kwargs – dictionary containing at least the key volumes to be transformed

Returns:

pre_process_volumes(**kwargs) → Tuple

pre-process volumes before running simulations with MCX. The volumes are transformed to mm units

Parameters:

kwargs – dictionary containing at least the keys scattering_cm, absorption_cm, anisotropy and assumed_anisotropy

Returns:

Tuple of volumes after transformation

read_mcx_output(**kwargs) → Dict

reads the temporary output generated with MCX

Parameters:

kwargs – dummy, used for class inheritance compatibility

Returns:

Dict instance containing the MCX output

remove_mcx_output() → None

deletes temporary MCX output files from the file system

Returns:

None

static run_mcx(cmd: List) → None

runs subprocess calling MCX with the flags built with self.get_command. Rises a RuntimeError if the code exit of the subprocess is not 0.

Parameters:

cmd – list defining command to parse to subprocess.run

Returns:

None

static volumes_to_mm(**kwargs) → Tuple

transforms volumes into mm units

Parameters:

kwargs – dictionary containing at least the keys scattering_cm, absorption_cm, anisotropy and assumed_anisotropy

Returns:

Tuple of volumes after transformation

class MCXReflectanceAdapter(global_settings: Settings)

Bases: MCXAdapter

This class implements a bridge to the mcx framework to integrate mcx into SIMPA. This class targets specifically diffuse reflectance simulations. Specifically, it implements the capability to run diffuse reflectance simulations.

Warning

This MCX adapter requires a version of MCX containing the commit 56eca8ae7e9abde309053759d6d6273ac4795fc5, which was published in the Nightly build on 2024-03-10.

Note

MCX is a GPU-enabled Monte-Carlo model simulation of photon transport in tissue: Fang, Qianqian, and David A. Boas. “Monte Carlo simulation of photon migration in 3D turbid media accelerated by graphics processing units.” Optics express 17.22 (2009): 20178-20190.

initializes MCX-specific configuration and clean-up instances

Parameters:

global_settings – global settings used during simulations

static extract_reflectance_from_fluence(fluence: ndarray) → Tuple

extracts diffuse reflectance from volumes. MCX stores diffuse reflectance as negative values in the fluence volume. The position where the reflectance is stored is also returned. If there are no negative values in the fluence, None is returned instead of reflectance and reflectance position. Negative values in fluence are set to 0 after extraction of the reflectance.

Parameters:

fluence – array containing fluence as generated by MCX

Returns:

tuple of reflectance, reflectance position and transformed fluence

forward_model(absorption_cm: ndarray, scattering_cm: ndarray, anisotropy: ndarray, illumination_geometry: IlluminationGeometryBase) → Dict

runs the MCX simulations. Binary file containing scattering and absorption volumes is temporarily created as input for MCX. A JSON serializable file containing the configuration required by MCx is also generated. The set of flags parsed to MCX is built based on the Tags declared in self.component_settings, the results from MCX are used to populate an instance of Settings and returned.

Parameters:

• absorption_cm – array containing the absorption of the tissue in cm units

• scattering_cm – array containing the scattering of the tissue in cm units

• anisotropy – array containing the anisotropy of the volume defined by absorption_cm and scattering_cm

• illumination_geometry – and instance of IlluminationGeometryBase defining the illumination geometry

• probe_position_mm – position of a probe in mm units. This is parsed to illumination_geometry.get_mcx_illuminator_definition

Returns:

Settings containing the results of optical simulations, the keys in this dictionary-like object depend on the Tags defined in self.component_settings

get_command() → List

generates list of commands to be parse to MCX in a subprocess

Returns:

list of MCX commands

post_process_volumes(**kwargs)

post-processes volumes after MCX simulations. Dummy function implemented for compatibility with inherited classes. Removes layer padded by self.pre_process_volumes if it was added and transforms np.nan -> 0.

Parameters:

kwargs – dictionary containing at least the key volumes to be transformed

Returns:

pre_process_volumes(**kwargs) → Tuple

pre-process volumes before running simulations with MCX. The volumes are transformed to mm units and pads a 0-values layer along the z-axis in order to save diffuse reflectance values. All 0-valued voxels are then transformed to np.nan. This last transformation 0->np.nan is a requirement form MCX.

Parameters:

kwargs – dictionary containing at least the keys scattering_cm, absorption_cm, anisotropy and assumed_anisotropy

Returns:

Tuple of volumes after transformation

read_mcx_output(**kwargs) → Dict

reads the temporary output generated with MCX

Parameters:

kwargs – dummy, used for class inheritance compatibility

Returns:

Settings instance containing the MCX output

run_forward_model(_device, device: Union[IlluminationGeometryBase, PhotoacousticDevice], absorption: ndarray, scattering: ndarray, anisotropy: ndarray) → Dict

runs self.forward_model as many times as defined by device and aggregates the results.

Parameters:

• _device – device illumination geometry

• device – class defining illumination

• absorption – Absorption volume

• scattering – Scattering volume

• anisotropy – Dimensionless scattering anisotropy

Returns:

class OpticalAdapterBase(global_settings: Settings)

Bases: SimulationModuleBase

Use this class as a base for implementations of optical forward models. This class has the attributes self.temporary_output_files which stores file paths that are temporarily created as input to the optical simulator, e.g. MCX. The class attributes nx, ny & nz represent the volume dimensions

Parameters:

global_settings (Settings) – The SIMPA settings dictionary

abstract forward_model(absorption_cm: ndarray, scattering_cm: ndarray, anisotropy: ndarray, illumination_geometry: IlluminationGeometryBase)

A deriving class needs to implement this method according to its model.

Parameters:

• absorption_cm – Absorption in units of per centimeter

• scattering_cm – Scattering in units of per centimeter

• anisotropy – Dimensionless scattering anisotropy

• illumination_geometry – A device that represents a detection geometry

Returns:

Fluence in units of J/cm^2

load_component_settings() → Settings

Implements abstract method to serve optical settings as component settings

Returns:

Settings: optical component settings

run(device: Union[IlluminationGeometryBase, PhotoacousticDevice]) → None

runs optical simulations. Volumes are first loaded from HDF5 file and parsed to self.forward_model, the output is aggregated in case multiple illuminations are defined by device and stored in the same HDF5 file.

Parameters:

device – Illumination or Photoacoustic device that defines the illumination geometry

Returns:

None

run_forward_model(_device, device: Union[IlluminationGeometryBase, PhotoacousticDevice], absorption: ndarray, scattering: ndarray, anisotropy: ndarray) → Dict

runs self.forward_model as many times as defined by device and aggregates the results.

Parameters:

• _device – device illumination geometry

• device – class defining illumination

• absorption – Absorption volume

• scattering – Scattering volume

• anisotropy – Dimensionless scattering anisotropy

Returns:

class OpticalTestAdapter(global_settings: Settings)

Bases: OpticalAdapterBase

This Adapter was created for testing purposes and only

Parameters:

global_settings (Settings) – The SIMPA settings dictionary

forward_model(absorption_cm, scattering_cm, anisotropy, illumination_geometry)

A deriving class needs to implement this method according to its model.

Parameters:

• absorption_cm – Absorption in units of per centimeter

• scattering_cm – Scattering in units of per centimeter

• anisotropy – Dimensionless scattering anisotropy

• illumination_geometry – A device that represents a detection geometry

Returns:

Fluence in units of J/cm^2