:py:mod:`pytomography.utils.simind_mc`
======================================

.. py:module:: pytomography.utils.simind_mc


Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   pytomography.utils.simind_mc.save_attenuation_map
   pytomography.utils.simind_mc.save_source_map
   pytomography.utils.simind_mc.get_simind_params_from_metadata
   pytomography.utils.simind_mc.get_simind_isotope_detector_params
   pytomography.utils.simind_mc.get_energy_window_params_dicom
   pytomography.utils.simind_mc.get_energy_window_params_simind
   pytomography.utils.simind_mc.create_simind_command
   pytomography.utils.simind_mc.add_together
   pytomography.utils.simind_mc.run_scatter_simulation



Attributes
~~~~~~~~~~

.. autoapisummary::

   pytomography.utils.simind_mc.ENERGY_RESOLUTION_MODELS


.. py:data:: ENERGY_RESOLUTION_MODELS
   :value: ['siemens']

   

.. py:function:: save_attenuation_map(attenuation_map, dx, temp_path)

   Save attenuation map as binary file to temporary directory for subsequent use by Monte Carlo scatter simulation.

   :param attenuation_map: Attenuation map to save
   :type attenuation_map: torch.Tensor
   :param dx: Spacing of attenuation map in cm
   :type dx: float
   :param temp_path: Temporary folder to save to
   :type temp_path: str


.. py:function:: save_source_map(source_map, temp_path, scaling, vmax = 1000000.0)

   Save source map as binary file to temporary directory for subsequent use by Monte Carlo scatter simulation.

   :param source_map: Source map to save
   :type source_map: torch.Tensor
   :param temp_path: Temporary folder to save to
   :type temp_path: str
   :param vmax: Maximum value of source map, prevents divergence at early iterations. Defaults to 1e6.
   :type vmax: float, optional


.. py:function:: get_simind_params_from_metadata(object_meta, proj_meta)

   Obtain dictionary of SIMIND parameters from object and projection metadata

   :param object_meta: SPECT object metadata used in reconstruction
   :type object_meta: ObjectMeta
   :param proj_meta: SPECT projection metadata used in reconstruction
   :type proj_meta: SPECTProjMeta

   :returns: Dictionary of SIMIND parameters obtainable from object and projection metadata
   :rtype: dict


.. py:function:: get_simind_isotope_detector_params(isotope_name, collimator_type, cover_thickness, backscatter_thickness, crystal_thickness, energy_resolution_140keV = 0, advanced_energy_resolution_model = None, advanced_collimator_modeling = False, random_collimator_movement = False)

   Obtain SIMIND parameter dictionary from isotope and detector parameters

   :param isotope_name: Name of isotope used for Monte Carlo scatter simulation
   :type isotope_name: str
   :param collimator_type: Collimator type used for Monte Carlo scatter simulation.
   :type collimator_type: str
   :param cover_thickness: Cover thickness used for simulation. Currently assumes aluminum is used.
   :type cover_thickness: float
   :param backscatter_thickness: Equivalent backscatter thickness used for simulation. Currently assumes pyrex is used.
   :type backscatter_thickness: float
   :param energy_resolution_140keV: Energy resolution in percent of the detector at 140keV. Currently uses the relationship that resolution is proportional to sqrt(E) for E in keV.
   :type energy_resolution_140keV: float
   :param advanced_collimator_modeling: Whether or not to use advanced collimator modeling that can be used to model septal penetration and scatter. Defaults to False.
   :type advanced_collimator_modeling: bool, optional
   :param random_collimator_movement: Whether or not to include random collimator movement (e.g. holes are not fixed in place). Defaults to False.
   :type random_collimator_movement: bool, optional

   :returns: Dictionary of SIMIND parameters obtainable from isotope and detector parameters
   :rtype: dict


.. py:function:: get_energy_window_params_dicom(file_NM, idxs = None)

   Obtain energy window parameters from a DICOM file: this includes a list of strings which, when written to a file, correspond to a typical "scattwin.win" file used by SIMIND.

   :param file_NM: DICOM projection file name
   :type file_NM: str
   :param idxs: Indices corresponding to the energy windows to extract. More than one index is provided in cases where multi-photopeak reconstruction is used and scatter needs to be obtained at all windows.
   :type idxs: Sequence[int]

   :returns: Lines of the "scattwin.win" file corresponding to the energy windows specified by the indices.
   :rtype: Sequence[str]


.. py:function:: get_energy_window_params_simind(headerfiles)

   Obtain energy window parameters from a list of SIMIND header files: this includes a list of strings which, when written to a file, correspond to a typical "scattwin.win" file used by SIMIND.

   :param headerfiles: SIMIND header files
   :type headerfiles: Sequence[str]

   :returns: Lines of the "scattwin.win" file corresponding to the energy windows specified by the header files.
   :rtype: Sequence[str]


.. py:function:: create_simind_command(index_dict, parallel_idx)

   Creates the terminal command to run SIMIND with the specified parameters

   :param index_dict: Dictionary of SIMIND parameters
   :type index_dict: dict
   :param parallel_idx: Random seed used for simulation, used to differentiate between parallel simulations
   :type parallel_idx: int

   :returns: Terminal command to run SIMIND with the specified parameters
   :rtype: str


.. py:function:: add_together(n_parallel, n_windows, temp_path)

   Adds together all the parallel SIMIND simulations to obtain the final scatter and total projections

   :param n_parallel: Number of parallel simulations
   :type n_parallel: int
   :param n_windows: Number of energy windows used in the simulation
   :type n_windows: int
   :param temp_path: Temporary directory where files were saved
   :type temp_path: str


.. py:function:: run_scatter_simulation(source_map, attenuation_map_140keV, object_meta, proj_meta, energy_window_params, simind_index_dict, n_events, n_parallel = 1, return_total = False)

   Runs a Monte Carlo scatter simulation using SIMIND

   :param source_map: Source map used in the simulation
   :type source_map: torch.Tensor
   :param attenuation_map_140keV: Attenuation map at 140keV used in the simulation
   :type attenuation_map_140keV: torch.Tensor
   :param object_meta: SPECT ObjectMeta used in reconstruction
   :type object_meta: ObjectMeta
   :param proj_meta: SPECT projection metadata used in reconstruction
   :type proj_meta: SPECTProjMeta
   :param energy_window_params: List of strings which constitute a typical "scattwin.win" file used by SIMIND
   :type energy_window_params: list
   :param primary_window_idxs: Indices from the energy_window_params list corresponding to indices used as photopeak in reconstruction. For single photopeak reconstruction, this will be a list of length 1, while for multi-photopeak reconstruction, this will be a list of length > 1.
   :type primary_window_idxs: Sequence[int]
   :param simind_index_dict: Dictionary of SIMIND parameters
   :type simind_index_dict: dict
   :param n_events: Number of events to simulate per projection angle
   :type n_events: int
   :param n_parallel: Number of simulations to perform in parallel, should not exceed number of CPU cores. Defaults to 1.
   :type n_parallel: int, optional
   :param return_total: Whether or not to also return the total projections. Defaults to False.
   :type return_total: bool, optional

   :returns: Simulated projections
   :rtype: torch.Tensor