Ion Pencil Beam Source#

Description#

The IonPencilBeamSource inherits from the GenericSource and retains therefore the same input parameters. The main difference consists in the sampling of the position and direction of the particles, which are not sampled independently, but are correlated. In fact, the Pencil Beam source is meant to describe a beam that can converge or diverge. This behaviour is modeled according to the Fermi-Eyges theory (Techniques of Proton Radiotherapy: Transport Theory B. Gottschalk May 1, 2012), that describes the correlated momentum spread of the particle with 4 parameters (each for x and y direction, assuming a beam directed as z):

  • spot size 𝜎

  • divergence 𝜃

  • emittance 𝜀

  • convergence flag [1,0]

The parameters must satisfy the condition:

pi * sigma * theta >= epsilon
image

image#

The user can set the beam parameters as shown in the example below, for a 120 MeV/n carbon ion beam.

source = sim.add_source("IonPencilBeamSource", "mysource")
source.energy.mono = 1440 * MeV
source.particle = "ion 6 12"  # carbon
source.position.translation = [100 * mm, 0 * mm, 0 * cm]
source.n = 20000
source.direction.partPhSp_x = [
    2.3335754 * mm,
    2.3335754 * mrad,
    0.00078728 * mm * mrad,
    0,
]
source.direction.partPhSp_y = [
    1.96433431 * mm,
    0.00079118 * mrad,
    0.00249161 * mm * mrad,
    0,
]

Note

The Pencil Beam source is created by default directed as the positive z axis. To rotate the source, use the source.position.rotation option.

Check all test044 for usage examples.

Reference#

class IonPencilBeamSource(*args, **kwargs)[source]#

Pencil Beam source

User input parameters and default values:

  • activity:

    • Default value: 0

    • Description: Activity of the source in Bq (exclusive with ‘n’)

  • attached_to:

    • Default value: world

    • Description: Name of the volume to which the source is attached.

  • direction:

    • Default value: {‘type’: ‘iso’, ‘theta’: [0, 3.141592653589793], ‘phi’: [0, 6.283185307179586], ‘momentum’: [0, 0, 1], ‘focus_point’: [0, 0, 0], ‘sigma’: [0, 0], ‘acceptance_angle’: {‘skip_policy’: ‘SkipEvents’, ‘volumes’: [], ‘intersection_flag’: False, ‘normal_flag’: False, ‘normal_vector’: [0, 0, 1], ‘normal_tolerance’: 0.05235987755982989}, ‘accolinearity_flag’: False, ‘accolinearity_fwhm’: 0.008726646259971648, ‘histogram_theta_weights’: [], ‘histogram_theta_angles’: [], ‘histogram_phi_weights’: [], ‘histogram_phi_angles’: []}

    • Description: Define the direction of the primary particles

  • direction_relative_to_attached_volume:

    • Default value: False

    • Description: Should we update the direction of the particle when the volume is moved (with dynamic parametrisation)?

  • end_time:

    • Default value: None

    • Description: End time of the source

  • energy:

    • Default value: {‘type’: ‘mono’, ‘mono’: 0, ‘sigma_gauss’: 0, ‘is_cdf’: False, ‘min_energy’: None, ‘max_energy’: None, ‘spectrum_type’: None, ‘spectrum_weights’: [], ‘spectrum_energies’: [], ‘spectrum_energy_bin_edges’: [], ‘spectrum_histogram_interpolation’: None}

    • Description: Define the energy of the primary particles

  • half_life:

    • Default value: -1

    • Description: Half-life decay (-1 if no decay). Only when used with ‘activity’

  • ion:

    • Default value: {‘Z’: 0, ‘A’: 0, ‘E’: 0}

    • Description: If the particle is an ion, you must set Z: Atomic Number, A: Atomic Mass (nn + np +nlambda), E: Excitation energy (i.e. for metastable)

  • mother:

    • Deprecated: The user input parameter ‘mother’ is deprecated. Use ‘attached_to’ instead.

  • n:

    • Default value: 0

    • Description: Number of particle to generate (exclusive with ‘activity’)

  • name (must be provided):

    • Default value: None

  • particle:

    • Default value: gamma

    • Description: Name of the particle generated by the source (gamma, e+ … or an ion such as ‘ion 9 18’)

  • position:

    • Default value: {‘type’: ‘point’, ‘radius’: 0, ‘sigma_x’: 0, ‘sigma_y’: 0, ‘size’: [0, 0, 0], ‘translation’: [0, 0, 0], ‘rotation’: array([[1., 0., 0.],, [0., 1., 0.],, [0., 0., 1.]]), ‘confine’: None}

    • Description: Define the position of the primary particles

  • start_time:

    • Default value: None

    • Description: Starting time of the source

  • tac_activities:

    • Default value: None

    • Description: TAC: Time Activity Curve, this set the vector for the activities. Must be used with tac_times.

  • tac_times:

    • Default value: None

    • Description: TAC: Time Activity Curve, this set the vector for the times. Must be used with tac_activities.

  • user_particle_life_time:

    • Default value: -1

    • Description: FIXME

  • weight:

    • Default value: -1

    • Description: Particle initial weight (for variance reduction technique)

  • weight_sigma:

    • Default value: -1

    • Description: if not negative, the weights of the particle are a Gaussian distribution with this sigma