Physics¶
Define DoseFrame
and Physics
classes for treatment
planning.
-
class
physics.
DoseFrame
(voxels=None, beams=None, data=None, voxel_labels=None, beam_labels=None, voxel_weights=None, beam_weights=None, frame_name=None)[source]¶ Describe a reference frame (voxels x beams) for dosing physics.
A
DoseFrame
provides a description of the mathematical basis of the dosing physics, which usually consists of a matrix in \(\mathbf{R}^{\mbox{voxels} \times \mbox{beams}}\), mapping the space of beam intensities, \(\mathbf{R}^\mbox{beams}\) to the space of doses delivered to each voxel, \(\mathbf{R}^\mbox{voxels}\).For a given plan, we may require conversions between several related representations of the dose matrix. For instance, the beams may in fact be beamlets that can be coalesced into apertures, or—in order to accelerate the treatment plan optimization—may be clustered or sampled. Similarly, voxels may be clustered or sampled. For voxels, there is also a geometric frame, with
X
*Y
*Z
voxels, where the tuple (X
,Y
,Z
) gives the dimensions of a regularly discretized grid, the so-called dose grid used in Monte Carlo simulations or ray tracing calculations. Since many of the voxels in this rectangular volume necessarily lie outside of the patient volume, there is only some number of voxelsm
<X
*Y
*Z
that are actually relevant to treatment planning.Accordingly, each
DoseFrame
is intended to capture one such configuration of beams and voxels, with corresponding data on labels and/or weights attached to the configuration. Voxel labels allow each voxel to be mapped to an anatomical or clinical structure used in planning. The concept of beam labels is defined to allow beams to be gathered in logical groups (e.g. beamlets in fluence maps, or apertures in arcs) that may be constrained jointly or treated as a unit in some other way in an optimization context. Voxel and beam weights are defined for accounting purposes: if aDoseFrame
represents a set of clustered voxels or beams, the associated weights give the number of unitary voxels or beams in each cluster, so that optimization objective terms can be weighted appropriately.-
beam_labels
¶ Vector of labels mapping beams to beam groups.
Setter will also use dimension of input vector to set beam dimensions (
DoseFrame.beams
) if not already assigned at call time.Raises: ValueError
– If provided vector dimensions inconsistent with known frame dimensions.
-
beam_weights
¶ Vector of weights assigned to each (meta-)beam.
Setter will also use dimension of input vector to set voxel dimensions (
DoseFrame.beams
) if not already assigned at call time.Raises: ValueError
– If provided vector dimensions inconsistent with known frame dimensions.
-
beams
¶ Number of beams in dose frame.
If
DoseFrame.beam_weights
has not been assigned at call time, the setter will initialize it to the 1 vector.Raises: ValueError
– IfDoseFrame.beams
already determined. Beam dimension is a write-once property.
-
dose_matrix
¶ Dose matrix.
Setter will also use dimensions of input matrix to set any dimensions (
DoseFrame.voxels
orDoseFrame.beams
) that are not already assigned at call time.Raises: TypeError
– If input to setter is not a sparse or dense matrix type recognized byconrad
.ValueError
– If provided matrix dimensions inconsistent with known frame dimensions.
-
static
indices_by_label
(label_vector, label, vector_name)[source]¶ Retrieve indices of vector entries corresponding to a given value.
Parameters: - label_vector – Vector of values to search for entries corresponding
- label – Value to find.
- vector_name (
str
) – Name of vector, for use in exception messages.
Returns: Vector of indices at which the entries of
label_vector
are equal tolabel
.Return type: ndarray
Raises: ValueError
– Iflabel_vector
isNone
.KeyError
– Iflabel
not found inlabel_vector
.
-
plannable
¶ True if both dose matrix and voxel label data loaded.
This can be achieved by having a contiguous matrix and a vector of voxel labels indicating the identity of each row of the matrix, or a dictionary of submatrices that map label keys to submatrix values.
-
shape
¶ Frame dimensions, \(\{\mathbf{R}^\mbox{voxels} \times \mathbf{R}^\mbox{beams}\}\).
-
voxel_labels
¶ Vector of labels mapping voxels to structures.
Setter will also use dimension of input vector to set voxel dimensions (
DoseFrame.voxels
) if not already assigned at call time.Raises: ValueError
– If provided vector dimensions inconsistent with known frame dimensions.
-
voxel_weights
¶ Vector of weights assigned to each (meta-)voxel.
Setter will also use dimension of input vector to set voxel dimensions (
DoseFrame.voxels
) if not already assigned at call time.Raises: ValueError
– If provided vector dimensions inconsistent with known frame dimensions.
-
voxels
¶ Number of voxels in dose frame.
If
DoseFrame.voxel_weights
has not been assigned at call time, the setter will initialize it to the 1 vector.Raises: ValueError
– IfDoseFrame.voxels
already determined. Voxel dimension is a write-once property.
-
-
class
physics.
Physics
(voxels=None, beams=None, dose_matrix=None, dose_grid=None, voxel_labels=None, **options)[source]¶ Class managing all dose-related information for treatment planning.
A
Physics
instance includes one or moreDoseFrames
, each with attached data including voxel dimensions, beam dimensions, a voxel-to-structure mapping, and a dose influence matrix. The class also provides an interface for adding and switching between frames, and extracting data from the active frame.A
Physics
instance optionally has an associatedVoxelGrid
that represents the dose grid used for dose matrix calculation, and that provides the necessary geometric information for reconstructing and rendering the 3-D dose distribution (or 2-D slices thereof).-
add_dose_frame
(key, **frame_args)[source]¶ Add new
DoseFrame
representation of a dosing configuration.Parameters: Returns: None
Raises: ValueError
– Ifkey
corresponds to an existing key in thePhysics
object’s dictionary of dose frames.
-
beams
¶ Number of beams in current
Physics.frame
.
-
data_loaded
¶ True
if a client has seen data from the current dose frame.
-
dose_grid
¶ Three-dimensional grid.
-
dose_matrix
¶ Dose influence matrix for current
Physics.frame
.
-
dose_matrix_by_label
(voxel_label=None, beam_label=None)[source]¶ Submatrix of dose matrix, filtered by voxel and beam labels.
Parameters: - voxel_label (optional) – Label for which to build/retrieve
submatrix of current
Physics.dose_matrix
based on row indices for whichvoxel_label
matches the entries ofPhysics.voxel_labels
. All rows returned if no label provided. - beam_label (optional) – Label for which to build/retrieve
submatrix of current
Physics.dose_matrix
based on column indices for whichbeam_label
matches the entries ofPhysics.frame.beam_labels
. All columns returned if no label provided.
Returns: Submatrix of dose matrix attached to current
Physics.frame
, based on row indices for whichPhysics.frame.voxel_labels
matches the queriedvoxel_label
, and column indices for whichPhysics.frame.beam_labels
matches the queriedbeam_label
.- voxel_label (optional) – Label for which to build/retrieve
submatrix of current
-
plannable
¶ True if current frame has both dose matrix and voxel label data
-
voxel_labels
¶ Vector mapping voxels to structures in current
Physics.frame
.
-
voxels
¶ Number of voxels in current
Physics.frame
.
-