pyRadPlan.dose.engines package#

Module contents#

Dose calculation engines and algorithms.

class DoseEngineBase(pln=None)[source]#

Bases: ABC

Abstract Interface for all dose engines.

All dose engines should inherit from this class.

Parameters:: pln (Union[Plan, dict]) – The Plan object to assign properties from.

short_name#

The short name of the dose engine.

Type:: str

name#

The name of the dose engine.

Type:: str

possible_radiation_modes#

The possible radiation modes for the dose engine.

Type:: list[str]

is_dose_engine#

Helper class variable telling you that this is a dose engine

Type:: bool = True

select_voxels_in_scenarios#

Whether to select voxels in scenarios.

Type:: bool

mult_scen#

The scenario model.

Type:: Union[str, ScenarioModel]

bio_model#

The biological model.

Type:: Union[str, dict]

dose_grid#

The dose grid to use (struct with at least doseGrid.resolution.x/y/z set).

Type:: Union[Grid,dict]

Methods

`assign_properties_from_pln`(pln[, ...])	Assign properties from a Plan object to the Dose Engine.
`calc_dose_forward`(ct, cst, stf, w)	Perform a forward dose calculation.
`calc_dose_influence`(ct, cst, stf)	Calculate the set of dose/quantity influence matrices.
`is_available`(pln, machine)
`resize_cst_to_grid`(cst, ct_with_new_grid)	Resize the CST to the dose cube resolution.
`select_voxels_from_cst`(cst, dose_grid, ...)	Get mask of the voxels (on dose grid).
`set_overlap_priorities`(cst[, resample])	Apply overlap priorities and, if enabled, resample the CST to the dose grid.

load_machine

assign_properties_from_pln(pln, warn_when_property_changed=False)[source]#

Assign properties from a Plan object to the Dose Engine.

This includes the Scenario Model and the Biological Model, and any other properties that can be stored in the prop_dose_calc dictionary within the Plan object. This function will check if a property exists for the dose engine and, if yes, set it.

Parameters:

pln (Plan) – The Plan object to assign properties from.
warn_when_property_changed (bool) – Whether to warn when properties are changed.

bio_model: str | dict#

calc_dose_forward(ct, cst, stf, w)[source]#

Perform a forward dose calculation.

Compute a dose cube by directly applying a set of weights during dose calculation.

Parameters:

ct (CT) – The CT scan data.
cst (StructureSet) – The structure set containing volumes of interest (VOIs).
stf (SteeringInformation) – The steering information containing beam configurations.
w (ndarray) – The weights to apply during dose calculation.

Returns:

The dose information

Return type:

dict

Notes

pyRadPlan handles the forward dose calculation by setting a switch in the dose engine (_calc_dose_direct) to True. This facilitates reusing of algorithms in both forward and influence matrix calculations.

calc_dose_influence(ct, cst, stf)[source]#

Calculate the set of dose/quantity influence matrices.

These are the matrices that map a fluence vector to a dose/quantity distribution.

Parameters:

ct (CT) – The CT scan data.
cst (StructureSet) – The structure set containing volumes of interest (VOIs).
stf (SteeringInformation) – The steering information containing beam configurations.

Returns:

The dose influence matrix collection

Return type:

Dij

Notes

pyRadPlan handles the forward dose calculation by setting a switch in the dose engine (_calc_dose_direct) to True. This facilitates reusing of algorithms in both forward and influence matrix calculations.

dose_grid: Grid | dict#

static is_available(pln, machine)[source]#

is_dose_engine: ClassVar[bool] = True#

static load_machine(radiation_mode, machine_name)[source]#

mult_scen: str | ScenarioModel#

name: ClassVar[str]#

possible_radiation_modes: ClassVar[list[str]] = NotImplemented#

resize_cst_to_grid(cst, ct_with_new_grid)[source]#

Resize the CST to the dose cube resolution.

Return type:: StructureSet

select_voxels_from_cst(cst, dose_grid, selection_mode)[source]#

Get mask of the voxels (on dose grid).

Gets the mask from the cst structures specified by selection_mode.

select_voxels_in_scenarios: bool#

set_overlap_priorities(cst, resample=True)[source]#

Apply overlap priorities and, if enabled, resample the CST to the dose grid.

Return type:: StructureSet

short_name: ClassVar[str]#

class ParticleFredMCEngine(pln=None)[source]#

Bases: MonteCarloEngineAbstract

Attributes:

save_input
save_output
use_output

Methods

`assign_properties_from_pln`(pln[, ...])	Assign properties from a Plan object to the Dose Engine.
`calc_dose_forward`(ct, cst, stf, w)	Perform a forward dose calculation.
`calc_dose_influence`(ct, cst, stf)	Calculate the set of dose/quantity influence matrices.
`read_sparse_dij_bin`(f_name)	Dispatch method to read a sparse dij binary file based on the dij format version.
`resize_cst_to_grid`(cst, ct_with_new_grid)	Resize the CST to the dose cube resolution.
`select_voxels_from_cst`(cst, dose_grid, ...)	Get mask of the voxels (on dose grid).
`set_overlap_priorities`(cst[, resample])	Apply overlap priorities and, if enabled, resample the CST to the dose grid.

is_available
load_machine

HU_table_file: str#

available_source_models = ['gaussian', 'emittance', 'sigmaSqrModel']#

available_versions = ['3.70.0', '3.76.0']#

calc_bio_dose: bool#

calc_let: bool#

external_calculation: str | bool#

fred_cmd: str#

fred_dir: Path#

fred_version: str#

static is_available(pln, machine)[source]#

name: ClassVar[str] = 'FRED'#

possible_radiation_modes: ClassVar[list[str]] = ['protons', 'helium', 'carbon', 'oxygen16']#

print_output: bool#

read_sparse_dij_bin(f_name)[source]#

Dispatch method to read a sparse dij binary file based on the dij format version.

Parameters:: (str) (f_name)
Return type:: csc_array
Returns:: sparse.csc_array: Sparse matrix containing the dij data.

room_material: str#

property save_input: PathLike | bool#

property save_output: PathLike | bool#

scaling_factor: int#

scorers: list[str]#

short_name: ClassVar[str] = 'FRED'#

source_model: str#

use_gpu: bool#

property use_output: Any#

class ParticleHongPencilBeamEngine(pln)[source]#

Bases: ParticlePencilBeamEngineAbstract

Methods

`assign_properties_from_pln`(pln[, ...])	Assign properties from a Plan object to the Dose Engine.
`calc_dose_forward`(ct, cst, stf, w)	Perform a forward dose calculation.
`calc_dose_influence`(ct, cst, stf)	Calculate the set of dose/quantity influence matrices.
`calc_geo_dists`(rot_coords_bev, ...)	Calculate geometric distances for dose calculation.
`resize_cst_to_grid`(cst, ct_with_new_grid)	Resize the CST to the dose cube resolution.
`round2`(a, b)	Round a number stably for energy selection (helper function).
`select_voxels_from_cst`(cst, dose_grid, ...)	Get mask of the voxels (on dose grid).
`set_overlap_priorities`(cst[, resample])	Apply overlap priorities and, if enabled, resample the CST to the dose grid.

is_available
load_machine

static is_available(pln, machine)[source]#

name: ClassVar[str] = 'Hong Particle Pencil-Beam'#

possible_radiation_modes: ClassVar[list[str]] = ['protons', 'helium', 'carbon', 'VHEE']#

short_name: ClassVar[str] = 'HongPB'#

class ParticleTOPASMCEngine(pln=None)[source]#

Bases: MonteCarloEngineAbstract

Methods

`assign_properties_from_pln`(pln[, ...])	Assign properties from a Plan object to the Dose Engine.
`calc_dose_forward`(ct, cst, stf, w)	Perform a forward dose calculation.
`calc_dose_influence`(ct, cst, stf)	Calculate the set of dose/quantity influence matrices.
`resize_cst_to_grid`(cst, ct_with_new_grid)	Resize the CST to the dose cube resolution.
`select_voxels_from_cst`(cst, dose_grid, ...)	Get mask of the voxels (on dose grid).
`set_overlap_priorities`(cst[, resample])	Apply overlap priorities and, if enabled, resample the CST to the dose grid.

helper_write_beam_params
helper_write_scanning
is_available
load_machine

available_source_models = ['biGaussian']#

base_topas_folder = MultiplexedPath('/home/docs/checkouts/readthedocs.org/user_builds/pyradplan/envs/latest/lib/python3.13/site-packages/pyRadPlan/data/TOPAS')#

calc_bio_dose: bool#

external_calculation: str | bool#

static helper_write_beam_params(beams_topas, beam_ix, param_name, layer_key, unit='', value_prefix='dv', transform=None)[source]#

static helper_write_scanning(beams_topas, beam_ix, field_name, value_getter, unit='', value_prefix='dv')[source]#

input_filenames = {'beam_biGaussian': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pyradplan/envs/latest/lib/python3.13/site-packages/pyRadPlan/data/TOPAS/input/beam_setup/TOPAS_beam_setup_biGaussian.txt.in'), 'matConv_Schneider_loadFromFile': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pyradplan/envs/latest/lib/python3.13/site-packages/pyRadPlan/data/TOPAS/input/material_converter/TOPAS_SchneiderConverter.txt.in'), 'scorer_LET': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pyradplan/envs/latest/lib/python3.13/site-packages/pyRadPlan/data/TOPAS/input/scorer/TOPAS_subscorer_LET.txt.in'), 'scorer_doseToMedium': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pyradplan/envs/latest/lib/python3.13/site-packages/pyRadPlan/data/TOPAS/input/scorer/TOPAS_scorer_doseToMedium.txt.in'), 'scorer_doseToWater': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/pyradplan/envs/latest/lib/python3.13/site-packages/pyRadPlan/data/TOPAS/input/scorer/TOPAS_scorer_doseToWater.txt.in')}#

static is_available(pln, machine)[source]#

material_converter = {'load_from_file': False, 'mode': 'RSP'}#

name: ClassVar[str] = 'TOPAS'#

num_runs: int#

num_threads: int#

physics_modules: list[str]#

possible_radiation_modes: ClassVar[list[str]] = ['electron', 'protons', 'helium', 'carbon', 'oxygen']#

radiation_mode: str#

room_material: str#

rsp_material: str#

scaling_factor: float#

scorer = {'LET': False, 'dose_to_medium': True, 'dose_to_water': False, 'output_type': 'binary'}#

short_name: ClassVar[str] = 'TOPAS'#

source_model: str#

class PhotonPencilBeamSVDEngine(pln)[source]#

Bases: PencilBeamEngineAbstract

Implementation of a pencil beam dose calculation engine for photons.

The implementation is based on the Singular-value decomposition (SVD) method by Bortfeld, Schlegel & Rhein (1993).

Parameters:: pln (PhotonPlan) – A photon plan object.

use_custom_primary_photon_fluence#

Use custom primary photon fluence.

Type:: bool

kernel_cutoff#

Kernel cutoff.

Type:: float

random_seed#

Random seed.

Type:: int

int_conv_resolution#

Intensity convolution resolution.

Type:: float

enable_dij_sampling#

Enable Dij sampling.

Type:: bool

dij_sampling#

Dij sampling configuration.

Type:: DijSamplingConfig

Methods

`assign_properties_from_pln`(pln[, ...])	Assign properties from a Plan object to the Dose Engine.
`calc_dose_forward`(ct, cst, stf, w)	Perform a forward dose calculation.
`calc_dose_influence`(ct, cst, stf)	Calculate the set of dose/quantity influence matrices.
`calc_geo_dists`(rot_coords_bev, ...)	Calculate geometric distances for dose calculation.
`is_available`(pln, machine)
`resize_cst_to_grid`(cst, ct_with_new_grid)	Resize the CST to the dose cube resolution.
`select_voxels_from_cst`(cst, dose_grid, ...)	Get mask of the voxels (on dose grid).
`set_overlap_priorities`(cst[, resample])	Apply overlap priorities and, if enabled, resample the CST to the dose grid.

load_machine

dij_sampling: DijSamplingConfig#

enable_dij_sampling: bool = True#

int_conv_resolution: float = 0.5#

kernel_cutoff: float#

name: ClassVar[str] = 'SVD Pencil Beam'#

possible_radiation_modes: ClassVar[list[str]] = ['photons']#

random_seed: int#

short_name: ClassVar[str] = 'SVDPB'#

use_custom_primary_photon_fluence: bool#

get_available_engines(pln)[source]#

Get a list of available engines based on the plan.

Parameters:: pln (Union[Plan, dict[str]]) – A Plan object.
Returns:: A dictionary containing the available engines.
Return type:: dict[str, Type[DoseEngineBase]]

get_engine(pln)[source]#

Get the appropriate engine based on the plan.

Parameters:: pln (Union[Plan, dict]) – A Plan object.
Returns:: A Dose Engine object.
Return type:: DoseEngineBase

register_engine(engine_cls)[source]#

Register a new engine.

Parameters:: engine_cls (Type[DoseEngineBase]) – A Dose Engine class.
Return type:: None