mspt.scanning package

Submodules

mspt.scanning.deliverySimulation_Static_Dynamic module

mspt.scanning.deliverySimulation_Static_Dynamic.beamletSimul(rhomw, Smw, Xr, Yr, Zr, dmax, z_dd, dd, sig0, xrshift, yrshift, sad, ssd0, Deff, indicesRay, x0y0z0_IECF, IECFSpacing, rotMatrixInv, typeFloat)[source]

Calls the C extension: beamletSimulation_PythonExt and returns its result.

The goal of this function is to simulate a beamlet and get the dose deposited by this beamlet.

Parameters:
  • rhomw – 3D numpy array density ratio to water (i.e. density matrix since water density = 1.0 g.cm-3)
  • Smw – 3D numpy array of the relative stopping power ratio to water
  • Xr – 3D matrix representing x coordinates in the IEC Gantry coordinate system (cm).
  • Yr – 3D matrix representing y coordinates in the IEC Gantry coordinate system (cm).
  • Zr – 3D matrix representing z coordinates in the IEC Gantry coordinate system (cm).
  • dmax – Bragg Peak depth (cm).
  • z_dd – “depth” coordinates for the depth dose curve (cm).
  • dd – “dose” coordinates for the depth dose curve. (Gy.cm ^2 )
  • sig0 – beam size (along x and y IEC gantry axis) at patient entrance (cm): [sig0X,sig0Y]
  • xrshift – x beam shift (from isocenter) used to define target position. Provided in the IEC gantry coordinate system.(cm)
  • yrshift – y beam shift (from isocenter) used to define target position. Provided in the IEC gantry coordinate system.(cm)
  • sad – source-axis distance: distance between the source and the isocenter.(cm)
  • ssd0 – source to patient surface distance (cm)
  • Deff – 3D matrix representing the radiological depth.(cm)
  • indicesRay – list of indices (frame,row, column) of the voxels encountered by the ray from the source to the target spot (xrshift,yrshift) located in the isocenter plane. They are sorted by increasing distance from the source.
  • x0y0z0_IECF – beam target point in the IEC fixed coordinate system.
  • spacingIECF – voxel spacing in the IEC fixed coord system
  • rotMatrixInv – 3x3 array (rotation matrix) to convert coordinates from IECG to IECF
  • typeFloat – the type of numpy float to be used: ‘float32’ or ‘float64’
Returns:

The resulting 3D dose distribution in a numpy array.
class mspt.scanning.deliverySimulation_Static_Dynamic.simulatorDelivery(patient, ddCurvesData, configData, motion=None, monitor=None)[source]

Bases: object

Class simulatorDelivery is the core of the simulation. This where the delivery is actually simulated.

Parameters:
  • patient – Patient object (in patient.patient) containing all the 3D arrays for the CT, density, ...
  • ddCurvesData – DDcurve object (in physics.ddCurveManager) used to store all the depth-dose curves.
  • configData –

    dictionary (globalVariables) storing the data configuring the simulator. Mandatory keys:

    • ‘mainPath’ : corresponds to the path where any simulation will be saved.
    • ‘nameSimulation’ : corresponds to the path where the current simulation will be saved.
    • ‘typeFloat’ : The type of numpy float to be used: ‘float32’ or ‘float64’
    • ‘protPerMU’ : Number of protons per MU to use.
    • ‘MeV’: Constant to convert 1MeV to Joules: 1MeV = 1.602e-13J
    • ‘displayScanPathUpdates’ : Display the evolution of the current scanning path of the current energy layer. Scanning Paths are stored in 3D numpy array ( see dicomReader.scanningPath for more information) where each frame is an energy layer. Therefore, if True the frame corresponding the current energy layer will be displayed to show the remaining beam positions.
    • ‘skipSaveBeamlets’: False to save an image of the dose distribution of each beamlet simulated, True otherwise.
    • ‘saveBeamletsCPKL’: True to save the dose distribution of each beamlet (a 3D numpy array) in a cPickle structure.
    • ‘staticDelivery’ : True if the patient is not moving, or False otherwise
    • ‘motionDuringBeam’ (if ‘staticDelivery’ is False): True to allow the patient to move while the beam is irradiating, False otherwise.
    • ‘motion3D’ (if ‘staticDelivery’ is False): True if the patient motion is in 3D.
    • ‘evaluateDiffStatDyna’ (if ‘staticDelivery’ is False) : True to evaluate the difference for each beam position between the static delivery and the dynamic delivery (i.e., moving patient). False otherwise.
    • ‘storeInterDoseDens’ (if ‘staticDelivery’ is False) : True to store the density image of the moving patient and the dose distribution of the beam when the patient is moving while being irradiated by a pencil beam. False otherwise.
    • ‘listSaveCompDoseAlong’ (if ‘staticDelivery’ is False): list of the axis along which the user wants to save the density and dose images of the moving patient. Possible values are ‘x’ (i.e. the images are stored along the column axis of the dicom image), ‘y’ (i.e. the images are stored along the rows axis of the dicom image), ‘z’ (i.e. the images are stored along the frame axis of the dicom image). Examlpes: listSaveCompDoseAlong = [] , or listSaveCompDoseAlong = [‘x’] or listSaveCompDoseAlong = [‘x’,’z’] ...
    • ‘timeEnergyChange’ (if ‘staticDelivery’ is False) : Time to change the energy of the beam in s.
    • ‘lateralScanningSpeed’ (if ‘staticDelivery’ is False): Beam lateral scanning speed in cm/s.
    • ‘spotSettlingTime’ (if ‘staticDelivery’ is False): Beam vertical scanning speed in cm/s.
    • ‘speedGantryRotation’ (if ‘staticDelivery’ is False): Gantry rotational speed in degrees/min.
    • ‘beamIntensity’ (if ‘staticDelivery’ is False): Number of protons per seconds being delivered.
    • ‘unitTimeForDelivery’ (if ‘staticDelivery’ is False): Unit time for motion simulation in seconde. Every unit time the patient position and radiological depth is updated.
    • ‘synchrotron’ (if ‘staticDelivery’ is False): True to simulate a synchrotron ( time energy change, refill the synchrotron). False for a cyclotron.
    • ‘spillLength’ (if ‘staticDelivery’ and synchrotron’ are True): Duration of a proton spill in s.
    • ‘compensationDynamic’ (if ‘staticDelivery’ is False): True to allow motion compensation, False otherwise.
    • ‘findStartPos’ (if ‘compensationDynamic’ is True): Find a good starting position in the energy layer( see dicomReader.scanningPath for more information).
    • ‘timeMeasureDisplacement’ (if ‘compensationDynamic’ is True): Time to measure the patient motion is s.
compensationFindStartSpotEnerLayer(scanPath, ddCurvesData, strEner)[source]

If MSPT global variables compensationDynamic and findStartPos are True, it look for a ‘good starting position’ for delivery of the current the energy layer. See dicomReader.scanningPath method findStartingPointForMotion() for more information.

Parameters:
  • scanPath – scanning path object (dicomReader.scanningPath.ScanningPathSingleBeam)
  • ddCurvesData – depth dose curves data : physics.ddcurveManager.DDCurves
  • strEner – String indicating if the energy being used has just been set (‘NewEnergy’) or has already been set for at least one beam position (‘SameEnergy’).
Returns:

None if no starting position has been found, otherwise a tuple:

  • index 0: spot weight
  • index 1: spot in the 3D matrices : frame, row, column
  • index 2: x position
  • index 3: y position
  • index 4: energy
  • index 5: list of 2 elements : spot size along x and along y
  • index 6: ‘NewEnergy’ if the energy is changing or ‘SameEnergy’ otherwise
  • index 7: spot type = 1 (native spot) or 2 (spot from added margin)
  • index 8: repainting index
computeBeamletStatic(Xr, Yr, Zr, dmax, z_dd, dd, sig0, xrshift, yrshift, sourceLocation)[source]

This function is only used if MSPT global variables ‘staticDelivery’ is set to False and ‘evaluateDiffStatDyna’ is set to False.

It simulates the irradiation at a beam position on the static body. This allows to highlight the differences between the beams delivered to the static and the dynamic body for a same beam position.

Parameters:
  • Xr – 3D matrix representing x coordinates in the IEC Gantry coordinate system (cm).
  • Yr – 3D matrix representing y coordinates in the IEC Gantry coordinate system (cm).
  • Zr – 3D matrix representing z coordinates in the IEC Gantry coordinate system (cm).
  • dmax – Bragg Peak depth (cm)
  • z_dd – “depth” coordinates for the depth dose curve (cm).
  • dd – “dose” coordinates for the depth dose curve. (Gy.cm ^2 )
  • sig0 – beam size (along x and y IEC gantry axis) at patient entrance (cm): [sig0X,sig0Y]
  • xrshift – x beam shift (from isocenter) used to define target position. Provided in the IEC gantry coordinate system.(cm)
  • sourceLocation – Source location in the IEC Fixed coordinate system(cm).
Apram yrshift:

y beam shift (from isocenter) used to define target position. Provided in the IEC gantry coordinate system.(cm)
Returns:

The processed dose distribution
computeDisplacementVectors(useMotionMonitor=False)[source]

Compute the displacement vector in the IEC fixed coordinate system from the simulated timer. Then convert the coordinated into the IEC Gantry coordinate system and into the CT coordinate system. :param useMotionMonitor: True if MSPT is configured to use motion monitoring, False otherwise.

Returns:If useMotionMonitor is True:
  • A tuple T with:
    • tuple[0] : disp. vector in the IEC Fixed system
    • tuple[1] : disp vector in the IEC Gantry
    • tuple[2] : disp vector in the CT system
    • tuple[3] : disp indices in the CT image (matrix)
  • Else, a dictionary with keys:
    • ‘PatientMotion’ : the tuple T
    • ‘MeasuredMotion’ : a tuple equivalent to T corresponding to the monitor measurements.
findBraggPeak(compDose, deff)[source]

Finds and display the Bragg Peak depth in the beam dose distribution.

Parameters:
  • compDose – Computed 3D dose distribution
  • deff – 3D numpy array of the radiological depth
getCumulDelivDuration()[source]

Get the cumulative time spent at each beam position

Returns:The cumulative irradiation time.
getCurrentTime()[source]

Get the current value of the timer (dynamic delivery)

Returns:Current timer value
getVectorInDiffCoordSystm(dispVec_IECFixed, info='')[source]

Converts a vector defined in the IEC Fixed coordinate system into the IEC grantry coordinate system and the dicom coordinate system.

Parameters:
  • dispVec_IECFixed – Displacement vector in the IEC fixed coordinate system (x,y,z)
  • info – String for information, to display, about the motion.
Returns:

A tuple with the displacement vector in different coordinate systems: ( dispVec_IECFixed ,dispVec_IECG,dispVec_CT,indDispCT ). Note: indDispCT corresponds to the displacement vector as indices in the CT volume: (frame, row, colum).
isPatientInTheVolume(shapeVolume, patientIndices)[source]

Function to verify that the patient is in the field of view when moving.

Parameters:
  • shapeVolume – Shape of the field of view volume (nb frames, nb rows, nb columns).
  • patientIndices – Patient indices in the field of view 3D array.
Returns:

True if the patient is inside, False otherwise
numberOfUnitTimeToDeliverWeight(weight)[source]

Calculate the number of time units needed to deliver a given weight:

Parameters:weight – Beam weight in MU
Returns:A list [ number of time units , weight to be delivered per time unit, remainder to deliver at last time unit]
processDynamicDoseDistrib(computedDose, T0_round, dispVec=None)[source]

Process the computed dose in dynamic mode:

The dose received by the patient (located at its dynamic position: self._dynaPatientLoc) is translated toward the “static position” (self._staticPatientLoc). The dose values located at indices self._dynaPatientLoc (body dynamic position) are moved to indices self._staticPatientLoc (body static position). Then everything outside the patient body is set to zero.

Parameters:
  • computedDose – 3D numpy array representing the 3D dose distribution of the pencilbeam.
  • T0_round – Rounded beam energy
  • dispVec – The displacement vector. By default it is None. It is used if the global variable ‘storeInterDoseDens’ is set to True when configuring MSPT.
Returns:

The processed dose distribution
simulateDelivery(spotPositions)[source]

Simulates the delivery of a proton therapy treatment plan to a patient based on the simulator configuration. It uses the beam scanning method.

Parameters:spotPosition – Treatment plan stored as a scanning path (dicomReader.scanningPath).
Returns:None if the delivery is performed for a static patient or a moving patient without compensation. It returns a compensated treatment plan if the patient is moving and ‘compensationDynamic’ is True: dictionary[beam angle][Energy Rounded][ “ScanSpotPositionMap” / “ScanSpotMetersetWeights”]
storeDictStatisticsRepaint(dictRep)[source]

Store statistics about the repainting: the number of compensated beam positions for each repainting index. It is stored to a csv file in the simulation directory in ‘StatisticsRepaintings/’.

Parameters:dictRep – Dictionary storing for each repainting index the number of compensated positions: dictRep[gantry angle][energy][repainting Index].
timeDeliverSpotWeight(weight)[source]

Return the time spent at one spot to deliver a given weight (MU), knowing the beam intensity and the number_of_protons/MU.

Formula : eq. 1 in “Interplay effects in proton scanning for lung: a 4D Monte Carlo study assessing the impact of tumor and beam delivery parameters.” Dowdell et al. 2013

Parameters:weight – Weight in MU of the beam position.
Returns:Time spent at beam position
updateTime(event, info=None)[source]

For dynamic delivery: Update the delivery timer (expressed in seconds).

Parameters:
  • event –

    The type of event that requires a timer update:

    • ‘Reset’: Reset the timer
    • ‘Energy’: Energy change
    • ‘MoveToSpot’: Change beam position
    • ‘GantryRotation’: Gantry rotation
    • ‘Delivery’: Time spent at a beam position for the delivery
    • ‘Refill’: Time to refill the synchrotron ( if the machine setting is set to Synchrotron)
    • ‘Displacement Measure’: Time to measure the patient displacement (if Compensation is activated)
  • info –

    Information regarding the event

    • If event ‘MoveToSpot’, ‘info’ is the distance between the spots in cm.
    • If event ‘GantryRotation’, ‘info’ is the rotation angle in degrees.
    • If event ‘Delivery’, ‘info’ is the weight in MU.
    • Otherwise info is None
weightDeliveredByUnitTime()[source]

Calculates the weight delivered per time unit

Returns:The calculated weight

Module contents