mspt.simulator package

Submodules

mspt.simulator.globalVariables module

class mspt.simulator.globalVariables.GlobalVariables(configFilename)[source]

Bases: dict

The class GlobalVariables is a subclass of dictionary to manage the configuration parameters from the input configuration file provided.

Parameters:configFilename – Path to the configuration file. (.txt or .py)
authorizedKeys[source]

Get a list of the authorized keys in the configuration file.

buildSettingsForScanningDelivery()[source]

Builds a dictionary for the initialization of the ScanningPath (in dicomReader package) .

checkConfigData()[source]

Check the configuration keys to ensure that all the needed keys are present. If they are missing they are added to the GlobalVariables instance with the default settings. The parameters verified in this function correspond to variables common between static and dynamic delivery.

processConfigMotionSimul()[source]

Process the keys:values specifically needed for the dynamic delivery.

processConfigStaticSimul()[source]

Process the keys:values specifically needed for the static delivery.

mspt.simulator.simulatorMSPT module

class mspt.simulator.simulatorMSPT.MSPT(params, globalVars=None)[source]

Bases: object

The class “MSPT”, is the main class of the simulator. It controls the global simulation process.

Parameters:
  • params –

    List of the input files of the simulator:

    • The path to a CT dicom directory in which is contained the CT dicom series.
    • The path to the RP dicom file (treatment plan)
    • The path to the RS dicom file (structures defined in the CT)
    • (optional) The path to the RD dicom file (expected dose distribution)
    • (optional) The path to the file configuring MSPT. If no file is provided MSPT will run a simulation on a static patient and MSPT will be configured using default settings (see simulator.globalVariables). If provided, the configuration file is received by MSPT but the configuration can be performed before. In such case ‘globalVars’ should not be None.
  • globalVars –

    Dictionary containing the configuration data of MSPT. If None:

    • If the configuration file is provided: MSPT will be configured using this file. The missing parameters will be set to default.
    • If the configuration file is not provided: SPT will be configured with default settings: static delivery and output data stored to local directory.

Note

The configuration file can either be ‘.txt’ or ‘.py’. In this file do not precede variables with an indentation. Enter 1 variable per line: myVariable = Value . All the following variables can be set in this file, but they are not mandatory since they all have a default value:

  • variables common to static and dynamic deliveries:

    • mainPath: String defining the path where the simulation directory will be created. By default: ‘../Data_Simulation/’
    • nameSimulation : corresponds to the path where the simulation output data will be saved. Default: ‘runSimulStatic/’’ for a static delivery, ‘runSimulDynamic/’ for a dynamic simulation.
    • nameProfilage : name of the profilage file created using the package ‘cProfile’. This profilage data can be after studied using the cProfile package in python or with the profilage viewer runsnake . Default: ‘profilagerunSimulStatic.profile’ for a static delivery, ‘profilagerunSimulDynamic.profile’ for a dynamic delivery.
    • removeProfilageData : True (default) or False depending if the user wants to delete the profilage data when the simulation ends.
    • stdOutErrToFile : True or False (default). If True the standard output and error are redirected to a text file in the simulation directory.
    • zipSavedData : True (default) or False. If True, the simulation directory containing the output data is zipped in ‘maintPath’. Note: if the user access directly the class MSPT (not using the ‘__main__’ function) the zip option is not available.
    • copyZip : True (default) or False. If True the zip file is copied to the ‘pathToCopyZip’ directory.
    • pathToCopyZip : String defining where to copy the zip file. Default: ‘../Data_Zip/’
    • typeFloat : The type of numpy float to be used: ‘float32’ or ‘float64’. Default : ‘float64’.
    • emailUser : If the user wants to send an email saying that the simulation ended with the DVH(s) and the the data printed in the standard output (or if the simulation crashed for any reason), he can fill this variable with his e-mail address en fill the next fields. Note: if the user access directly the class MSPT (not using the ‘__main__’ function) the email option is not available. Default: None
    • emailPwd : e-mail password. Default: None
    • emailSMTP : e-mail smpt server address. Default: None
    • emailSMTPPort : smtp server port. Default: None
    • emailRecipient : e-mail address of the e-mail’s recipient. Default: None
    • staticDelivery: True (default) or False. If True the delivery is performed for a static patient. Otherwise for a moving (dynamic) patient.
    • ddCurves: String defining the set of dept-dose curves to use. By default ‘RayStation’. It is also possible to use ‘MCNPX’ or ‘Eclipse’, but these two datasets have not been tested. The user can also add its own depth dose curves. See physics.ddCurvesManager.DDCurve for more information.
    • displayScanPathUpdates : True or False (default). If True it displays the evolution of 2D array representing the scanning path in an energy layer. See dicomReader.scanningPath for more details.
    • saveCTImage : True :save the CT dicom image as tiff image files, False otherwise. Default: True
    • listSaveCTImageAlong (if ‘saveCTImage’ is True): list of the axis along which the user wants to save the CT images of the 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 - default). Examlpes: listSaveCTImageAlong = [] (in this case default value is used) , or listSaveCompDoseAlong = [‘x’] or listSaveCompDoseAlong = [‘x’,’z’] ... Default: [‘z’].
    • skipSaveDensityImage : False to save the 3D density array as a set of png images. True otherwise. Default: True
    • listSaveDensImAlong (if ‘skipSaveDensityImage’ is False): list of the axis along which the user wants to save the density images of the patient. Default: [‘z’].
    • saveDensCPKL (if ‘skipSaveDensityImage’ is False): True if the user wants to store the density 3D array in a cPickle structure (this allows to have access to the 3D numpy array outdise the simulation). False otherwise. Moreover, if False and the patient is moving it will stored the 3D density array every time the array is updated. Default: False.
    • skipSaveStpPwrImage : False to save the 3D relative stopping power array as a set of png images. True otherwise. Default: True
    • listSaveStPwrImAlong (if ‘skipSaveStpPwrImage’ is False): list of the axis along which the user wants to save the rel. stop. power images of the patient. Default: [‘z’].
    • saveStpPwrCPKL (if ‘skipSaveStpPwrImage’ is False):Similar to ‘saveDensCPKL’ to save the 3D array of the relative stopping power. However, if the patient is moving it only stores it once.
    • skipSaveDeff : False to save the 3D radiological depth array as a set of png images. True otherwise. Default: True
    • listSaveDeffAlong : Similar to ‘listSaveDensImAlong’, to save the images of the 3D radiological depth matrix.
    • saveDeffCPKL : Similar to ‘saveDensCPKL’ to save the 3D radiological depth matrix. If the patient is moving it stores the array at every update.
    • skipSaveBeamlets : False to save an image of the dose distribution of each beamlet simulated, True otherwise. Default : True
    • saveBeamletsCPKL (if skipSaveBeamlets is False): True to save the dose distribution of each beamlet (a 3D numpy array) in a cPickle structure.
    • listSaveCompDoseAlong : list of the axis along which the user wants to save the computed dose images (png) of the patient. Default: [‘z’]. Note: This variable is also used to store the density and the pencil beam dose distribution in a dynamic delivery if the variable ‘storeInterDoseDens’ (defined below) is True.
    • saveCompDoseAsDcm : True to save the computed dose distribution into a RD dicom file. False otherwise. Default : True
    • nameCompDose : Name of the output RD dicom file for the computed dose distribution. Default: ‘RD_CompDose_MSPT.dcm’
    • saveRefDoseAsDcm : True to save the expect dose distribution into a RD dicom file (False otherwise). This is useful if the input dose grid must be resampled to the voxel spacing of the input CT dicom series. Moreover, this can only be done if the user provided an inpu RD dicom file. Default : True
    • nameRefDose : Name of the output RD dicom file for the expected dose distribution. Default: ‘RD_RefDose.dcm’
    • saveRefDose : True :save the expected dose distribution image as png image files, False otherwise. Default: True
    • listSaveRefDoseAlong (if saveRefDose True) : list of the axis along which the user wants to save the expected dose distribution images.
    • dvhRelativeVolume : True to convert the volumes into relative volumes in the dose volume histograms. False otherwise. Default: True.
    • displaySliceOrderingInfo : True to display the order and positions (in mm) of the CT dicom slices. False otherwise. Default: False.
    • exportSliceOrderingInfo : True to export the order and positions (in mm) of the CT dicom slices into a cszv file. False otherwise. Default: False.
    • storeMasksAsCPKL : True to store binary matrices representing the patient structures (VOIs: Volumes of Interest) into cPickle structures.
    • protPerMU : Number of protons per Monitor Units (MU). Default: 1e9 prot.MU-1.
    • nameStopPwrCorrecFactor : name of the correction factor for the stopping power to use.
    • importNewMassStopPwr : True to import new mass stopping power data, False (default) otherwise.
    • nameDoseCorrecFactor: name of the dose correction factor to use.

  • variables for dynamic deliveries:

    • unitTimeForDelivery : time unit to simulate the dynamic delivery (moving patient) expressed in seconds. It corresponds to the time resolution. Default: 1e-3.
    • typeMotion : the type of motion applied to the patient: ‘motionNoisyCos’,’motionCos’,’motionBreathHiccup’ or ‘motionBreathCough’. See package motion for more information. Default: ‘motionCos’.
    • arrayPeriod : List of the motion period (in seconds) along x,y, and z axis in the IEC fixed coordinate system. Default : [4.0, 3.5, 0.0].Note: X_IEC fixed= X_Dicom, Y_IEC fixed = Z_Dicom, Z_IEC fixed = -Y_Dicom.
    • arrayAmpl : List of the motion amplitude (in cm) along x,y, and z axis in the IEC fixed coordinate system. Default : [1.0, 1.0, 0.0]
    • arrayPhase : List of the motion initial phase (in rad.) along x,y, and z axis in the IEC fixed coordinate system. Default : [0, 0, 0]
    • arrayStDevPeriod (if ‘typeMotion’ is ‘motionNoisyCos’, ‘motionBreathHiccup’ or ‘motionBreathCough’): List of standard deviations (in seconds) for the gaussian distribution used to simulate changes (noise) in period of the motion along x,y, and z axis in the IEC fixed coordinate system. Default : [0, 0, 0]
    • arrayStDevAmpl (if ‘typeMotion’ is ‘motionNoisyCos’, ‘motionBreathHiccup’ or ‘motionBreathCough’): List of standard deviations (in cm) for the gaussian distribution used to simulate changes (noise) in amplitude of the motion along x,y, and z axis in the IEC fixed coordinate system. Default : [0, 0, 0]
    • ctPadding : True if the user wants to add margins of a specified density (see ‘paddedCTValue’ ) around the current CT image. This is useful, when the moving patient can be outside of the bounding box formed by the borders of the CT image.
    • padValueFRC (if ‘ctPadding’ is True) : Numpy array of 3 integer values : [ number of added frames : nbF, number of added rows : nbR, number of added columns : nbC]. For exemple : [ 0,0,10] will add 10 columns to the right of the CT image and 10 columns to the left of the CT image. Default: [10,10,10].
    • paddedCTValue (if ‘ctPadding’ is True): The value in CT number (Hounsfield Units) to use to pad the CT image. For example: air = -1000 HU, water = 0 HU.
    • storeInterDoseDens : 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. Default: False. Note: It uses the variable ‘listSaveCompDoseAlong’ to save the images.
    • motionDuringBeam : True to allow the patient to move while the beam is irradiating, False otherwise. Default : True.
    • compensationDynamic : True to allow motion compensation, False otherwise. Default : False.
    • measurementStdev (if compensationDynamic is True): List of the standard deviation of the motion monitoring accuracy (in cm.) along x,y, and z axis in the IEC fixed coordinate system. Default : [0.1, 0.1, 0]
    • measurementAvg (if compensationDynamic is True):List of the average of the motion monitoring accuracy (in cm.) along x,y, and z axis in the IEC fixed coordinate system. Default : [0.1, 0.1, 0].
    • timeMeasureDisplacement (if compensationDynamic is True): Time (in seconds) needed to measure the patient displacement with the monitoring system. Default: 1e-3.
    • findStartPos (if compensationDynamic is True):
    • nameNewRPFile (if compensationDynamic is True):
    • addMargins (if compensationDynamic is True):
    • marginsParam (if compensationDynamic is True):
    • updateMargins (if compensationDynamic is True):
    • unlimitedRescanning : True to allow an unlimited number (the maximum, however, is set to 32767 repaintings to avoid infinite loops) of repainting per energy slice. False otherwise.
    • repaintingFactor (if unlimitedRescanning is False): Repainting factor. Default: 1.
    • sliceRepaint : Type of slice repainting method. Types :’IsolayerRepaint’,’ScaledRepaint’ or ‘FullWeightRepainting’. Note: ‘FullWeightRepainting’: we deliver the full weight at once instead of a maximum weight or a scaled weight.
    • volumeRepaint : Type volume repainting method. Types : ‘Volumetric’ and ‘NonVolumetric’. Default : ‘NonVolumetric’.
    • evaluateDiffStatDyna : True to show and store statistics about the differences between dose distributions at a beam position when the patient is moving and when he is static. Default: False.
    • synchrotron : True to make MSPT behave like a synchrotron (i.e., pulsatile proton delivery, time needed to refill the synchrotron and the time to change the energy is longer than for cyclotrons). Otherwise (False) it behaves like a cyclotron (i.e., continuous proton delivery the time to change the energy is shorter. Default: True
    • spillLength ( if synchrotron is True): length in seconds of a proton spill. Default: 5.
    • timeEnergyChange : Time (in seconds) to change the energy. Default: 2.1 ( if synchrotron is True) , 50e-3 ( if synchrotron is False).
    • spotSettlingTime : Time (in seconds) needed to stabilize the beam position. Default : 5e-3.
    • lateralScanningSpeed : Lateral scanning speed of the beam (in cm/s). Default : 1000.
    • verticalScanningSpeed : Vertical scanning speed of the beam (in cm/s). Default : 1000.
    • speedGantryRotation : Gantry rotational speed in degrees / min. Default: 360.
    • beamIntensity : Beam intensity (or extraction rate), i.e. number of protons per second being delivered. Default: 6.8e10
save2DListToCSV(data, filename)[source]

Save a 2D list into a CSV file.

Parameters:
  • data – 2D list
  • filename –

    Name of the output file.

    The csv file is stored in the CSV_Data/ folder of the simulation directory.
save2DSliceToCSV(data, filename)[source]

Save a 2D numpy array to CSV file.

Parameters:
  • data – 2D numpy array
  • filename – Name of the output file.

If the number of columns is greater than 255 and and the number of rows is smaller than 255, we trasnpose the rows and columns in order to be able to open the file in Excel or Numbers. If both dimensions are greater than 255, we remove the same number of columns on the left and on the right, such that the remaining number of columns is 255.

The csv file is stored in the CSV_Data/ folder of the simulation directory.

mspt.simulator.simulatorMSPT.exportListDataToCSV(listsValues, names, pathToSave, filename)[source]

Export a list to a CSV file.

Parameters:
  • listsValues – List of values to store.
  • names – List of headers.
  • pathToSave – Path where to save the CSV file.
  • filename – Name of the output file.

mspt.simulator.tools module

class mspt.simulator.tools.Tools(configData)[source]

Bases: object

Class Tools aims at providing utilities to the simulator.

Parameters:configData – Dictionary storing the MSPT configuration. Mandatory key is ‘typeFloat’ : ‘float32’ or ‘float64’.
evaluateDifference(vol1, vol2)[source]

!Function that computes the difference between two 3D numpy arrays and calculate statistics: absDiff = abs( vol1 - vol2). It also saves the results into a text file (EvalDiffDoseDistrib.txt) in the simulation directory.

Parameters:
  • vol1 – First 3D numpy array
  • vol2 – second 3D numpy array
Returns:

Dictionary with keys:

  • ‘vol1’: Dictionary with keys:

    • “min” : minimum value of vol1
    • “max” : maximum value of vol1
    • “std” : standard deviation value of vol1
    • “avg” : average value of vol1

  • ‘vol2’: Dictionary with keys:

    • “min” : minimum value of vol2
    • “max” : maximum value of vol2
    • “std” : standard deviation value of vol2
    • “avg” : average value of vol2

  • ‘absDiff’: Dictionary with keys:

    • “min” : minimum value of absDiff
    • “max” : maximum value of absDiff
    • “std” : standard deviation value of absDiff
    • “avg” : average value of absDiff
getMatrixHotAndColdSpot(volRef, volTest)[source]

Function that computes the 3D array of hot and cold spots as: diff = volTest - volRef

Parameters:
  • volRef – 3D array of reference
  • volTest – 3D array tested
Returns:

3D array diff.
saveCompensatedRTPlan(rtPlanPath, newRTPlanPath, dictPlan)[source]

Function that save a dictionary storing a treatment plan to a RP dicom file.

Parameters:
  • rtPlanPath – Path to the input RP dicom file.
  • newRTPlanPath – Path to the new RP dicom file.
  • dictPlan – Dictionary storing the new treatment plan : dictionary[beam angle][Energy Rounded][ “ScanSpotPositionMap” / “ScanSpotMetersetWeights”]
showHotColdSpots(volRef, volTest, title=None, pathToSaveImg=None)[source]

Function that display the hot and cold spots on a frame located at the “middle” of the dose distribution.

Parameters:
  • volRef – 3D array of reference
  • volTest – 3D array tested
  • title – Title for the figure. Default: None
  • pathToSaveImg – Path where to save the figure. Default: None

Module contents