mspt.physics package

Submodules

mspt.physics.ddCurvesManager module

class mspt.physics.ddCurvesManager.DDCurves(configData)[source]

Bases: object

Class managing the depth dose curves used in MSPT.

Parameters:configData –

dictionary (globalVariables) storing the data configuring the simulator. Mandatory keys for the depth dose curves are:

  • ‘ddCurves’ : The type of Depth-Dose curves to use. In MSPT only RayStation DD curves are available.
  • ‘typeFloat’: type of numpy float to use: ‘float32’ or ‘float64’.
  • ‘nameDoseCorrecFactor’: name of the dose correction factor to use.

Note

If one wants to add new depth-dose curves, please follow the procedure:

  1. Create a new directory “NAME_NEWFOLDER” in the folder:

    MSPT-MotionSimulatorInProtonTherapy/src/trunk/RefData/DepthDoseData/

  2. Add the depth dose curves in this new directory. Please, note that the depth-dose curves must be stored in .csv files:

    1. 1 file per energy
    2. The name of each file must respect this pattern: ‘depthDoseData-xxx_xxMeV*.csv’ where the x corresponds to digits of the energy and ‘*’ can be any string. For example: depth-dose curve files for 10.20MeV: “depthDoseData-010_20MeV.csv” or “depthDoseData-010_20MeV_SomeInformation.csv” or “depthDoseData-010_20MeV_NAME_NEWFOLDER.csv”
    3. Each file must be organized as follows: 1st row: the depths in cm, 2nd row the corresponding dose in Gy.cm2.

  3. To use these depth-dose curves set the variable ddCurves, of the configuration file, to ‘NAME_NEWFOLDER’.

Note

If one wants to modify the dose corrections factors:

  1. Create a table with 2 columns into a tab delimited ‘.txt’ file:

    1. Then fist line must contains the headers: 1st column: ‘Energy’, 2nd column: ‘Factor’
    2. Then, for each new line: 1st column: the energy in MeV , 2nd column: the corresponding correction factor unitless.
    3. The filename must respect this pattern: ‘doseCorrecFactor__NAMEDATA.txt’ where ‘NAMEDATA’ will be the name you want to give to this data. For example, by default the name for the correction factors used in MSPT is ‘MSPT’, so the file name is ‘doseCorrecFactor_MSPT.txt’

  2. Place the file in the folder MSPT-MotionSimulatorInProtonTherapy/src/trunk/RefData/DoseCorrecFactor/

  3. Set the MSPT configuration variable nameDoseCorrecFactor to ‘NAMEDATA’

And you’re done!

buildFuncBPvsEner()[source]

Creates an interpolation function to provide the BP for a given energy

buildFuncDoseAtBPVsEnergy()[source]

Creates the interpolation function providing the dose at BP for a specific energy

buildFuncEnervsBP()[source]

Creates an interpolation function to provide the energy for a given BP

dataForEnergy(dataType, energy)[source]

Returns the data for a given energy. Data types are:

  • ‘DD_Curve’: the depth dose curve stored in an array (2 rows, n columns).
  • ‘BraggPeak’: Depth of the Bragg Peak (BP) in cm.
  • ‘MaxDose’: Maximum dose value (at Bragg Peak).
  • ‘CumulDose’: Array of the cumulative dose (2 rows, n columns).
  • ‘NbProtons’: Number of protons estimated from the depth dose curve.
  • ‘Ratio-DoseEntrance-BP’: Ratio between the entrance dose and the dose at the BP.
  • ‘DoseAtEntrance’: Dose at patient entrance
  • ‘EnergyLoss’: Array of the energy loss along the depth (2 rows, n columns).
  • ‘EnergyRemaining’: Array of the remaining energy along the depth (2 rows, n columns).
Parameters:
  • dataType – string specifying the dataType
  • energy – energy
Returns:

The data.
doseCorrectionFactor(energy)[source]

Function created to match RayStation absolute dose. It uses a linear interpolation to obtain a multiplicative dose correction factor for an energy.

The function has been obtained by measuring the ratio between the dose obtained in RayStation and in our simulator for single beamlets in water for energies ranging from 30MeV to 245MeV.

Parameters:energy – energy in MeV
Returns:The correction factor
findDoseAtBPForEner(energy)[source]

Obtain the dose at BP for a given energy

Parameters:energy – Desired energy in MeV
Returns:Corresponding BP depth
findEnergyForBraggPeak(desiredBP)[source]

Find an energy for a given Bragg Peak

Parameters:desiredBP – Desired BP depth
Returns:Corresponding energy estimated using a linear interpolation.
generateApproxDDCurveForEnergy(energy)[source]

Generate Depth Dose Curve for a given energy if this energy is outside the lookup table energy range

Parameters:energy – Energy for which to generate a depth-dose curve.

The depth dose curves is generated using a linear interpolation between encompassing energies to obtain the Bragg Peak (BP) location Then it uses the DD curves of the closest and higher energy available E2: the depths position are shifted by the difference between the BP of the generated curve and the BP of E2. The part of the curve is kept where the depth is positive.

generateTableMissingEnergy(energy, newDDCurve)[source]

Function that generates the dictionary in which is stored all the information about the depth dose curve.

Parameters:
  • energy – Energy in MeV
  • newDDCurve – depth-dose curve generated: 1st row depths in cm, second row dose.

The new dictionary created is added to the look-up table storing the missing energies. The keys of this dictionary are:

  • ‘DD_Curve’ : the depth dose curve
  • ‘BraggPeak’ : Brag Peak depth in cm
  • ‘MaxDose’ : Maximum dose in the DD curve.
  • ‘CumulDose’ : Cumulative dose along the depth
  • ‘NbProtons’ : Number of protons used in the beam corresponding to this DD Curve
  • ‘Ratio-DoseEntrance-BP’ : Ratio between the dose at initial depth and at BP depth.
  • ‘DoseAtEntrance’ : Dose at initial depth
  • ‘EnergyLoss’ : Energy loss along the depth
  • ‘EnergyRemaining’ : Remaining energy along the depth
loadDoseCorrectionFactor()[source]

Function used to import dose correction factor data. It scans the folder /RefData/DoseCorrecFactor/.

Each file matching the pattern ‘doseCorrecFactor_NAMEDATA.txt’. NAMEDATA must also be provided by the mspt global variable : nameDoseCorrecFactor = ‘NAMEDATA’

readCSVFilesInFolder(dirPath)[source]

Function that loads all the Depth-Dose curves contained in a directory

Parameters:dirPath – Path to the directory

The function creates a lookup table (dictionary) whose keys are the energies of the depth dose curves and the value is a dictionary storing the data computed by ‘readFile(filename)’. The keys for each energy:

  • ‘DD_Curve’ : the depth dose curve
  • ‘BraggPeak’ : Brag Peak depth in cm
  • ‘MaxDose’ : Maximum dose in the DD curve.
  • ‘CumulDose’ : Cumulative dose along the depth
  • ‘NbProtons’ : Number of protons used in the beam corresponding to this DD Curve
  • ‘Ratio-DoseEntrance-BP’ : Ratio between the dose at initial depth and at BP depth.
  • ‘DoseAtEntrance’ : Dose at initial depth
  • ‘EnergyLoss’ : Energy loss along the depth
  • ‘EnergyRemaining’ : Remaining energy along the depth
Returns:the look up table.
readFile(filename)[source]

Load depth dose data and computes additional data (data at BP, cumulative dose,number of protons, ratio dose entrance/BP , energy loss, energy remaining) and returns it.

Parameters:filename – Path to file to load
Returns:A list with data:
  1. energy
  2. DD curve stored in a (2,n) array
  3. BP data : depth and dose at the BP
  4. Cumulative dose
  5. Number of protons
  6. Ratio dose
  7. Energy loss
  8. Remaining energy
mspt.physics.ddCurvesManager.computeEnergyLoss(cumDose, energy)[source]

Computes energy loss along depth:

energy loss(z) = dose(z) / cumul_dose * energy
Parameters:
  • cumDose – array of the cumulative dose
  • energy – Energy in MeV
Returns:

Array of the energy loss along the depth
mspt.physics.ddCurvesManager.computeEnergyRemaining(energyLoss, energy)[source]

Computes remaining energy along depth:

remainEnergy(z) = energy - energyLoss(z)
Parameters:
  • energyLoss – Energy loss array
  • energy – energy in MeV
Returns:

Array of the remaining energy along the depth
mspt.physics.ddCurvesManager.computeNbProtonsMCSimul(cumDoseVal, energy)[source]

For given energy , estimate the number of protons used in the corresponding beam in water:

nbProtons = sum_dose[Gy.cm^2] * z_spacing [cm] * rhoWater [kg.cm ^-3] / Energy_Joules

Note

Gy = J / Kg and 1 MeV = 1.602e-13 Joules.

Parameters:
  • cumDoseVal – cumulative dose value at the end of the DD curve range (after the BP)
  • energy – energy in MeV
Returns:

The number of protons estimated.
mspt.physics.ddCurvesManager.cumulDose(dataDDCurve)[source]

Computes the cumulative dose along the depth:

Cumul dose = sum ( dose * dz ), where dose in [Gy.cm^2] * [cm]
Parameters:dataDDCurve – stored in a (2,n) array
Returns:Cumulative dose array
mspt.physics.ddCurvesManager.findBraggPeak(dataDDCurve)[source]

Finds the Bragg Peak (cm) and return the BP with the deposited dose associated in [Gy.cm^2]

Parameters:dataDDCurve – stored in a (2,n) array
Returns:list [ BP depth (cm), dose at BP]

mspt.physics.stoppingPower module

class mspt.physics.stoppingPower.StoppingPower(configData)[source]

Bases: object

The stopping power data has been extracted from the PSTAR database

Parameters:configData –

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

  • ‘typeFloat’: type of numpy float to use: ‘float32’ or ‘float64’.
  • ‘nameStopPwrCorrecFactor’ : name of the correction factor for the mass stopping power to use.
  • ‘importNewMassStopPwr’ : True to use new stopping power data, false otherwise. Default is False

Note

MSPT is provided with Mass Stopping Power tables obtained from the PSTAR database for several media: air, adipose, water, muscle and bone. However, if one wants to add mass stopping power data here is the procedure:

  1. Create the table (Energy, Mass stopping power) into a tab delimited ‘.txt’ file (1 file per medium):

    1. The 1st line must contain the headers: 1st column: ‘Kinetic Energy MeV’ , 2nd column: ‘Total Stp. Pow. MeV cm2/g’
    2. Then, for each new line: 1st column: the energy in MeV , 2nd column: the corresponding mass stopping power in MeV.cm2/g. Please note that the energies must be stored in increasing order.
    3. Once all the energies and mass stopping powers have been entered, add a new line where: 1st column: medium density in g/cm3 and 2nd column: -1.0.
    4. The name of each file must respect the pattern: ‘MassStopPwrData-MediumName.txt’

  2. Once all the files have been created (1 per medium!), add these files into the folder MSPT-MotionSimulatorInProtonTherapy/src/trunk/RefData/MassStoppingPower_NewData/

  3. Set the configuration variable importNewMassStopPwr to True to be able to use this new mass stopping power data.

Note

To use another correction factor for the stopping power:

  1. Create a table with 2 columns into a tab delimited ‘.txt’ file:

    1. The fist line must contains the headers: 1st column: ‘Density’, 2nd column: Correction factor
    2. Then, for each new line: 1st column: the density in g/cm3 , 2nd column: the corresponding correction factor unitless.
    3. The filename must respect this pattern: ‘dataCorrecFactorStopPwr_NAMEDATA.txt’ where ‘NAMEDATA’ will be the name you want to give to this data. For example, by default the name for the correction factors used in MSPT is ‘MSPT’, so the file name is ‘dataCorrecFactorStopPwr_MSPT.txt’

  2. Place the file in the folder MSPT-MotionSimulatorInProtonTherapy/src/trunk/RefData/CorrecFactor_StopPwr/

  3. Set the MSPT configuration variable nameStopPwrCorrecFactor to ‘NAMEDATA’

And you’re done!

buildMediumToTable(key, low, high, energy, idxEnergy, idxMaxEnergy)[source]

Function that builds the table to add to the conversion table for a given medium

Parameters:
  • key – Name of the medium
  • low – low bound of the density range
  • high – high bound of the density range
  • energy – energy in MeV
  • idxEnergy – index of the energy in the mass stopping power table (PSTAR data).
  • idxMaxEnergy – index of the maximum energy used in the mass stopping power table (PSTAR data).
Returns:

A table (3,1) :

  • row 0 : low bound of density range , * row 1: high bound of density range, * row 2: rel mass stop pwr associated to the medium for the given energy.
getConversionTableStpPwrForEnergy(energy)[source]

Return a 3 x n array (n being the number of media):

  • row 0 : low bound of density range ,
  • row 1: high bound of density range,
  • row 2: rel mass stop pwr associated. Medium: Air,Adipose,Muscle,Bone
Parameters:energy – Energy in MeV
Returns:COnversion table Density to Rel.ative Mass Stopping power:

Note

Mass stopping power [MeV.cm^-1 / (g.cm^-3)] = [MeV.cm^2.g^-1]

getStopPwrCorrecFactor()[source]

Get the stopping power correction factor table

importCorrecStopPwrData()[source]

Function used to import stopping power correction factor data. It scans the folder /RefData/CorrecFactor_StopPwr/.

Each file matching the pattern ‘dataCorrecFactorStopPwr_NAMEDATA.txt’. NAMEDATA must also be provided by the mspt global variable : nameStopPwrCorrecFactor = ‘NAMEDATA’

importNewStopPwrData()[source]

Function used to import new mass stopping power data. It scans the folder /RefData/MassStoppingPower_NewData/ for mass stopping power files.

Each file matching the pattern ‘MassStopPwrData-MediumName.txt’ is imported and is assigned to the medium “MediumName”. The imported data is added to the dictionary storing the stopping power data for each medium.

loadMassStoppingPowerFromNewData(filename, medium)[source]

Loads Mass Stopping Power data from new data

Parameters:
  • filename – File where the data is stored. The file should be using “tab delimited” format. The first row should be the headers : ‘Kinetic Energy MeV’ and ‘Total Stp. Pow. MeV cm2/g’. The last row should be: 1st column: the density value in g/cm3 , 2nd column: -1.
  • medium – Name of the medium
loadMassStoppingPowerFromPSTARData()[source]

Loads Mass Stopping Power data from the PSTAR data

precomputeMassStopPowerRatios()[source]

Compute relative mass stopping power (relative to water). For each medium divide the mass stopping power by the mass stopping power of water.

Module contents