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)

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 voxels m < 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 a DoseFrame 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_lookup_by_label(label)

Get indices of beam labeled label in this DoseFrame.

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 – If DoseFrame.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 or DoseFrame.beams) that are not already assigned at call time.

Raises:

• TypeError – If input to setter is not a sparse or dense matrix type recognized by conrad.
• ValueError – If provided matrix dimensions inconsistent with known frame dimensions.

static indices_by_label(label_vector, label, vector_name)

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 to label.

Return type:

ndarray

Raises:

• ValueError – If label_vector is None.
• KeyError – If label not found in label_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_lookup_by_label(label)

Get indices of voxels labeled label in this DoseFrame.

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 – If DoseFrame.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)

Class managing all dose-related information for treatment planning.

A Physics instance includes one or more DoseFrames, 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 associated VoxelGrid 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)

Add new DoseFrame representation of a dosing configuration.

Parameters:

• key – A new DoseFrame will be added to the Physics object’s dictionary with the key key.
• **frame_args – Keyword arguments passed to DoseFrame initializer.

Returns:

None

Raises:

ValueError – If key corresponds to an existing key in the Physics object’s dictionary of dose frames.

available_frames

List of keys to dose frames already attached to Physics.

beam_weights_by_label(label)

Subvector of beam weights, filtered by label.

beams

Number of beams in current Physics.frame.

change_dose_frame(key)

Switch between dose frames already attached to Physics.

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)

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 which voxel_label matches the entries of Physics.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 which beam_label matches the entries of Physics.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 which Physics.frame.voxel_labels matches the queried voxel_label, and column indices for which Physics.frame.beam_labels matches the queried beam_label.

frame

Handle to DoseFrame representing current dosing configuration.

mark_data_as_loaded()

Allow clients to mark dose frame data as seen.

plannable

True if current frame has both dose matrix and voxel label data

unique_frames

List of unique dose frames attached to Physics.

voxel_labels

Vector mapping voxels to structures in current Physics.frame.

voxel_weights_by_label(label)

Subvector of voxel weights, filtered by label.

voxels

Number of voxels in current Physics.frame.