How to: Electromagnetic fields#

GATE provides an interface to define electromagnetic fields within simulation volumes. Under the hood, GATE configures Geant4’s field tracking machinery (equation of motion, Runge-Kutta stepper, chord finder) for you.

Fields are defined as standalone objects, then attached to one or more volumes with add_field(). Each volume can hold at most one field. A single field object can be shared across multiple volumes.

Fields are attached to logical volumes, so they automatically propagate to all physical placements of that volume. Dynamic geometry changes are supported: if a field is attached to a volume that is later moved or rotated, the field will move/rotate with it.

All field definitions are relative to the local coordinate system they are attached to. This means that, for instance, if a field is attached to a volume that is rotated, the field vector will be rotated accordingly.

Quick example#

import opengate as gate
from opengate.geometry import fields

sim = gate.Simulation()
tesla = gate.g4_units.tesla
cm = gate.g4_units.cm

box = sim.add_volume("Box", "magnet")
box.size = [50 * cm, 50 * cm, 50 * cm]
box.material = "G4_Galactic"

field = fields.UniformMagneticField(name="B_field_for_box")
field.field_vector = [0, 1 * tesla, 0]
box.add_field(field)

Available field types#

Magnetic fields#

UniformMagneticField – Constant magnetic field throughout the volume. Uses the native Geant4 G4UniformMagField under the hood.

field = fields.UniformMagneticField(name="B_uniform")
field.field_vector = [0, 0, 2 * tesla]   # [Bx, By, Bz] <- relative to the volume's local coordinate system
box.add_field(field)

QuadrupoleMagneticField – Quadrupole magnetic field defined via a field gradient. Uses the native Geant4 G4QuadrupoleMagField under the hood. The field is always oriented such that the optical axis is along the local Z direction of the volume and one of the south poles sits in the +XY quadrant.

field = fields.QuadrupoleMagneticField(name="B_quad")
field.gradient = 10 * tesla / m   # field gradient (T/m)
box.add_field(field)

SextupoleMagneticField – Sextupole magnetic field defined via a field gradient. Uses the native Geant4 G4SextupoleMagField under the hood. The field is always oriented such that the optical axis is along the local Z direction of the volume and one of the north poles sits in the +Y direction.

field = fields.SextupoleMagneticField(name="B_sext")
field.gradient = 10 * tesla / m   # field gradient (T/m)
box.add_field(field)

CustomMagneticField – Arbitrary magnetic field defined by a Python callback. The function receives (x, y, z, t) in Geant4 internal units and must return [Bx, By, Bz].

def my_B_field(x, y, z, t): # <- relative to the volume's local coordinate system
    # Spatially varying field
    return [0, (1 + x * z / m**2) * tesla, 0] # <- relative to the volume's local coordinate system

field = fields.CustomMagneticField(name="B_custom")
field.field_function = my_B_field
box.add_field(field)

Warning

Performance warning

Custom fields are evaluated via a Python callback for every field evaluation during tracking. This will significantly slow down the simulation. Prefer native types when possible. We are currently working on developing a faster custom field implementation. For more details, see Performance: native vs custom fields.

MappedMagneticField – Magnetic field defined by values on a regular 3D Cartesian grid. Field values are interpolated between grid points (trilinear by default). This is the recommended approach for importing fields from external calculations (e.g. finite element solvers) or for replacing a slow CustomMagneticField with a pre-sampled C++ equivalent.

The field is specified as a 2D array with columns [x, y, z, Bx, By, Bz] in Geant4 internal units. The grid must be regular (uniform spacing along each axis) and complete (every combination of the sampled x, y, z values must be present). All coordinates are in the local frame of the attached volume. Degenerate axes are not allowed, so the minimum valid grid is 2×2×2 (eight corner points).

import numpy as np

# data.csv has columns: x, y, z (in mm), Bx, By, Bz (in T)
mm = gate.g4_units.mm
tesla = gate.g4_units.tesla

field_matrix = np.loadtxt("data.csv", delimiter=",")
field_matrix[:, :3] *= mm      # convert positions to Geant4 internal length units
field_matrix[:, 3:] *= tesla   # convert field to Geant4 internal field units

field = fields.MappedMagneticField(name="B_mapped")
field.field_matrix = field_matrix
box.add_field(field)

Warning

Points outside the grid

If the grid does not cover the entire volume, field values will be extrapolated outside the grid using the nearest valid value (i.e. clamping to the edge). We recommend defining the grid to cover the entire volume to avoid unexpected behaviour.

Electric fields#

UniformElectricField – Constant electric field. Uses the native Geant4 G4UniformElectricField under the hood.

volt = gate.g4_units.volt
m = gate.g4_units.m

field = fields.UniformElectricField(name="E_uniform")
field.field_vector = [1e6 * volt / m, 0, 0]   # [Ex, Ey, Ez] <- relative to the volume's local coordinate system
box.add_field(field)

CustomElectricField – Arbitrary electric field defined by a Python callback. The function receives (x, y, z, t) in Geant4 internal units and must return [Ex, Ey, Ez].

def my_E_field(x, y, z, t): # <- relative to the volume's local coordinate system
    return [1e6 * volt / m, 0, 0] # <- relative to the volume's local coordinate system

field = fields.CustomElectricField(name="E_custom")
field.field_function = my_E_field
box.add_field(field)

Warning

Performance warning

Same GIL overhead as CustomMagneticField. See Performance: native vs custom fields.

MappedElectricField – Electric field defined on a regular 3D Cartesian grid, same interface as MappedMagneticField. Columns are [x, y, z, Ex, Ey, Ez].

field = fields.MappedElectricField(name="E_mapped")
field.field_matrix = field_matrix   # columns: [x, y, z, Ex, Ey, Ez], values in Geant4 internal units
box.add_field(field)

Electromagnetic fields#

Combined magnetic and electric fields.

UniformElectroMagneticField – Constant electromagnetic field. Uses the GATE C++ implementation GateUniformElectroMagneticField under the hood.

volt = gate.g4_units.volt
m = gate.g4_units.m

field = fields.UniformElectroMagneticField(name="EM_uniform")
field.field_vector_B = [0, 0, 1 * tesla]          # [Bx, By, Bz] in local coordinates
field.field_vector_E = [1e6 * volt / m, 0, 0]     # [Ex, Ey, Ez] in local coordinates
box.add_field(field)

CustomElectroMagneticField – Arbitrary combined field. The callback must return all six components [Bx, By, Bz, Ex, Ey, Ez].

def my_EM_field(x, y, z, t):
    return [0, 1 * tesla, 0, 1e6 * volt / m, 0, 0]

field = fields.CustomElectroMagneticField(name="EM_custom")
field.field_function = my_EM_field
box.add_field(field)

Warning

Performance warning

Same GIL overhead as CustomMagneticField. See Performance: native vs custom fields.

MappedElectroMagneticField – Combined B and E field, each defined on its own independent regular 3D Cartesian grid. The two grids do not need to share the same resolution or spatial extent.

field = fields.MappedElectroMagneticField(name="EM_mapped")
field.field_matrix_B = b_matrix   # columns: [x, y, z, Bx, By, Bz], values in Geant4 internal units
field.field_matrix_E = e_matrix   # columns: [x, y, z, Ex, Ey, Ez], values in Geant4 internal units
box.add_field(field)

Integration and accuracy parameters#

All field types inherit the following parameters that control the numerical integration of the equation of motion. The defaults are suitable for most cases, but they can be tuned for better accuracy or performance.

Parameter

Default

Description

stepper

DormandPrince745

Stepping algorithm used for integrating the equation of motion. See Steppers for available options.

step_minimum

0.01 mm

Minimum step size for the chord finder.

delta_chord

0.001 mm

Maximum sagitta (miss distance between the chord approximation and the true curved trajectory).

delta_one_step

0.001 mm

Positional accuracy per integration step.

delta_intersection

0.0001 mm

Positional accuracy at volume boundaries.

min_epsilon_step

1e-7

Minimum relative integration accuracy.

max_epsilon_step

1e-5

Maximum relative integration accuracy.

Example:

field = fields.UniformMagneticField(name="B")
field.field_vector = [0, 0, 1 * tesla]
field.stepper = "DormandPrince745"
field.delta_chord = 0.01 * mm
field.step_minimum = 0.1 * mm
box.add_field(field)

Steppers#

For general fields (electric and/or magnetic components):

  • DormandPrince745 (default)

  • ClassicalRK4

  • CashKarpRKF45

  • BogackiShampine45

  • BogackiShampine23

  • DormandPrinceRK56

  • DormandPrinceRK78

For purely magnetic fields, the following additional steppers are available:

  • NystromRK4

  • ExactHelicalStepper

Please refer to the Geant4 documentation for details on the characteristics and recommended use cases for each stepper type.

Attaching fields to volumes#

Use add_field() to attach a field to a volume. The volume must already be added to the simulation.

box = sim.add_volume("Box", "my_box")
# ...configure box and define field
box.add_field(field)

One field per volume. Attempting to attach a second field raises an error.

Shared fields. The same field object can be attached to multiple volumes. This is useful when several volumes should have the same field configuration:

field = fields.UniformMagneticField(name="B_shared")
field.field_vector = [0, 0, 1 * tesla]
box1.add_field(field)
box2.add_field(field)

Unique names. Field names must be unique across the simulation. Two different field objects with the same name will raise an error.

Propagation to daughter volumes. A field attached to a volume automatically propagates to all of its daughter volumes. A daughter volume can override this by attaching its own field. In that case, the parent’s field stops at the daughter’s boundary and the daughter’s field is used inside. This mirrors standard Geant4 behaviour.

Behaviour with repeated placements. When a volume with a field is repeatedly placed (i.e. a logical volume with several physical placements), each physical instance will have the field in its own local coordinate system.

Behaviour with dynamic geometry changes. If a field is attached to a volume that is later moved or rotated, the field will move/rotate with it.

outer = sim.add_volume("Box", "outer")
inner = sim.add_volume("Box", "inner")
inner.mother = "outer"

field_outer = fields.UniformMagneticField(name="B_outer")
field_outer.field_vector = [0, 0, 1 * tesla]
outer.add_field(field_outer)
# "inner" inherits B_outer automatically.

# To override it inside the daughter, attach a different field:
field_inner = fields.UniformMagneticField(name="B_inner")
field_inner.field_vector = [0, 2 * tesla, 0]
inner.add_field(field_inner)
# Now "inner" uses B_inner; "outer" still uses B_outer outside of "inner".

Visualizing fields#

Geant4 can overlay field arrows on the visualization of the geometry. The Geant4 command is /vis/scene/add/magneticField <arrow density> <arrow type> (or /vis/scene/add/electricField for electric fields). It can be passed to GATE via the visu_commands parameter:

sim.visu = True
sim.visu_type = "qt"
sim.visu_commands.append("/vis/scene/add/magneticField 20 fullArrow")
sim.visu_commands.append("/vis/scene/add/electricField 20 fullArrow")

Performance: native vs custom fields#

Native field types (UniformMagneticField, UniformElectricField, QuadrupoleMagneticField, SextupoleMagneticField, UniformElectroMagneticField) are evaluated entirely in C++ by Geant4 (or GATE in the case of the uniform electromagnetic field). They have no Python overhead and are the recommended choice when they match your use case.

Custom fields (CustomMagneticField, CustomElectricField, CustomElectroMagneticField) call a Python function for every evaluation of GetFieldValue during tracking. This means that the GIL is acquired and released on every call, which can significantly slow down the simulation, especially in multithreaded mode where all threads serialize through the Python callback.

Recommendation: Use native types whenever possible. For spatially varying fields, use a mapped field type (MappedMagneticField, MappedElectricField, MappedElectroMagneticField): define the field on a grid once at setup and let the C++ interpolator handle all evaluations during tracking with zero Python overhead.

Examples#

The field implementation is covered by the test099_fields_* tests in opengate/tests/src/geometry/. These tests can be used as examples of how to define and use fields in GATE. They include:

  • test099_fields_analytical_B – Uniform B field vs analytical cyclotron radius.

  • test099_fields_analytical_E – Uniform E field vs analytical energy gain.

  • test099_fields_custom_vs_native_B – Custom trampoline B vs native G4 (bit-identical).

  • test099_fields_custom_vs_native_E – Custom trampoline E vs native G4 (bit-identical).

  • test099_fields_mapped_vs_uniform_B – MappedMagneticField (constant grid) vs UniformMagneticField.

  • test099_fields_mapped_vs_uniform_E – MappedElectricField (constant grid) vs UniformElectricField.

  • test099_fields_multi_volume_refresh – Uniform field shared across two volumes; one is dynamically rotated between runs.

  • test099_fields_mapped_multi_volume_refresh – Same as above with a MappedMagneticField.

  • test099_fields_repeated_placements – Uniform field on a single box vs the same total depth split into repeated slabs.

  • test099_fields_mapped_repeated_placements – Same as above with a MappedMagneticField.

  • test099_fields_rotated_volume – Uniform field shared between an unrotated and a rotated volume.

  • test099_fields_mapped_rotated_volume – Same as above with a MappedMagneticField.

  • test099_fields_serialization – Round-trip serialization for all non-custom types.

  • test099_fields_api – API guards.

  • test099_fields_stepper_em – Comparison of different steppers for a uniform E field.

  • test099_fields_stepper – Comparison of different steppers for a uniform B field.

Class reference#

class FieldBase(*args, **kwargs)[source]

Base class for electric and magnetic fields.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

close() → None[source]

Dummy implementation for inherited classes which do not implement this method.

create_field_manager(volume_obj) → opengate_core.G4FieldManager[source]

Construct the field and return a configured G4FieldManager.

property delta_chord[source]

delta_chord:

  • Default value: 0.001

  • Description: Maximum miss distance between chord and curved trajectory.

property delta_intersection[source]

delta_intersection:

  • Default value: 0.0001

  • Description: Positional accuracy at volume boundaries.

property delta_one_step[source]

delta_one_step:

  • Default value: 0.001

  • Description: Positional accuracy per integration step.

property field_changes_energy: bool[source]

Whether the field changes particle energy (False for magnetic, True for others).

property max_epsilon_step[source]

max_epsilon_step:

  • Default value: 1e-05

  • Description: Maximum relative integration accuracy.

property min_epsilon_step[source]

min_epsilon_step:

  • Default value: 1e-07

  • Description: Minimum relative integration accuracy.

refresh_transforms() → None[source]

Recompute and push cached world-to-local transforms after dynamic geometry changes.

property step_minimum[source]

step_minimum:

  • Default value: 0.01

  • Description: Minimum step size for the chord finder.

property stepper[source]

stepper:

  • Default value: DormandPrince745

  • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

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

Uniform magnetic field with constant field vector.

field_vector is specified in the local coordinate frame of the attached volume. For a non-rotated volume this is identical to the world frame. For a rotated volume the field direction rotates with the volume.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_vector:

    • Default value: [0, 0, 0]

    • Description: Field vector [Bx, By, Bz] in local volume coordinates. Each component in magnetic field strength units (e.g., Tesla).

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

property field_vector[source]#

field_vector:

  • Default value: [0, 0, 0]

  • Description: Field vector [Bx, By, Bz] in local volume coordinates. Each component in magnetic field strength units (e.g., Tesla).

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

Quadrupole magnetic field with gradient.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • gradient:

    • Default value: 0

    • Description: Field gradient in magnetic field strength units per unit length (e.g., Tesla/meter).

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

property gradient[source]#

gradient:

  • Default value: 0

  • Description: Field gradient in magnetic field strength units per unit length (e.g., Tesla/meter).

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

Sextupole magnetic field with gradient.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • gradient:

    • Default value: 0

    • Description: Field gradient in magnetic field strength units per unit length (e.g., Tesla/meter).

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

property gradient[source]#

gradient:

  • Default value: 0

  • Description: Field gradient in magnetic field strength units per unit length (e.g., Tesla/meter).

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

Custom magnetic field defined by a Python callback function.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_function:

    • Default value: None

    • Description: Python function that takes [x, y, z, t] and returns [Bx, By, Bz], all in local volume coordinates.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

property field_function[source]#

field_function:

  • Default value: None

  • Description: Python function that takes [x, y, z, t] and returns [Bx, By, Bz], all in local volume coordinates.

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

Magnetic field defined by values on a regular 3D Cartesian grid.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_matrix:

    • Default value: None

    • Description: 2D numpy array on a regular Cartesian grid in Geant4 units. Structure: [[x, y, z, field components…], …].

  • interpolation:

    • Default value: trilinear

    • Description: Interpolation method: ‘trilinear’ (default) or ‘nearest’.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

create_field_manager(volume_obj) → opengate_core.G4FieldManager[source]#

Construct the field and return a configured G4FieldManager.

property field_matrix[source]#

field_matrix:

  • Default value: None

  • Description: 2D numpy array on a regular Cartesian grid in Geant4 units. Structure: [[x, y, z, field components…], …].

property interpolation[source]#

interpolation:

  • Default value: trilinear

  • Description: Interpolation method: ‘trilinear’ (default) or ‘nearest’.

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

Uniform electric field with constant field vector.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_vector:

    • Default value: [0, 0, 0]

    • Description: Field vector [Ex, Ey, Ez] in local volume coordinates. Each component in electric field strength units.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

property field_vector[source]#

field_vector:

  • Default value: [0, 0, 0]

  • Description: Field vector [Ex, Ey, Ez] in local volume coordinates. Each component in electric field strength units.

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

Custom electric field defined by a Python callback function.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_function:

    • Default value: None

    • Description: Python function that takes [x, y, z, t] and returns [Ex, Ey, Ez], all in local volume coordinates.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

property field_function[source]#

field_function:

  • Default value: None

  • Description: Python function that takes [x, y, z, t] and returns [Ex, Ey, Ez], all in local volume coordinates.

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

Electric field defined by values on a regular 3D Cartesian grid.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_matrix:

    • Default value: None

    • Description: 2D numpy array on a regular Cartesian grid in Geant4 units. Structure: [[x, y, z, field components…], …].

  • interpolation:

    • Default value: trilinear

    • Description: Interpolation method: ‘trilinear’ (default) or ‘nearest’.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

create_field_manager(volume_obj) → opengate_core.G4FieldManager[source]#

Construct the field and return a configured G4FieldManager.

property field_matrix[source]#

field_matrix:

  • Default value: None

  • Description: 2D numpy array on a regular Cartesian grid in Geant4 units. Structure: [[x, y, z, field components…], …].

property interpolation[source]#

interpolation:

  • Default value: trilinear

  • Description: Interpolation method: ‘trilinear’ (default) or ‘nearest’.

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

Uniform electromagnetic field with constant magnetic and electric field vectors.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_vector_B:

    • Default value: [0, 0, 0]

    • Description: Magnetic field vector [Bx, By, Bz] in local volume coordinates.

  • field_vector_E:

    • Default value: [0, 0, 0]

    • Description: Electric field vector [Ex, Ey, Ez] in local volume coordinates.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

property field_vector_B[source]#

field_vector_B:

  • Default value: [0, 0, 0]

  • Description: Magnetic field vector [Bx, By, Bz] in local volume coordinates.

property field_vector_E[source]#

field_vector_E:

  • Default value: [0, 0, 0]

  • Description: Electric field vector [Ex, Ey, Ez] in local volume coordinates.

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

Custom electromagnetic field defined by a Python callback function.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_function:

    • Default value: None

    • Description: Python function that takes [x, y, z, t] and returns [Bx, By, Bz, Ex, Ey, Ez], all in local volume coordinates.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

property field_function[source]#

field_function:

  • Default value: None

  • Description: Python function that takes [x, y, z, t] and returns [Bx, By, Bz, Ex, Ey, Ez], all in local volume coordinates.

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

Electromagnetic field with separate B and E grids on regular 3D Cartesian grids.

field_matrix_B and field_matrix_E must have columns [x, y, z, Bx, By, Bz] and [x, y, z, Ex, Ey, Ez] respectively, in Geant4 units. Field lookup is performed entirely in C++ using trilinear or nearest-neighbour interpolation, with B and E computed independently on their respective grids.

User input parameters and default values:

  • delta_chord:

    • Default value: 0.001

    • Description: Maximum miss distance between chord and curved trajectory.

  • delta_intersection:

    • Default value: 0.0001

    • Description: Positional accuracy at volume boundaries.

  • delta_one_step:

    • Default value: 0.001

    • Description: Positional accuracy per integration step.

  • field_matrix_B:

    • Default value: None

    • Description: 2D numpy array on a regular Cartesian grid in Geant4 units. Columns: [x, y, z, Bx, By, Bz].

  • field_matrix_E:

    • Default value: None

    • Description: 2D numpy array on a regular Cartesian grid in Geant4 units. Columns: [x, y, z, Ex, Ey, Ez].

  • interpolation:

    • Default value: trilinear

    • Description: Interpolation method: ‘trilinear’ (default) or ‘nearest’.

  • max_epsilon_step:

    • Default value: 1e-05

    • Description: Maximum relative integration accuracy.

  • min_epsilon_step:

    • Default value: 1e-07

    • Description: Minimum relative integration accuracy.

  • name (must be provided):

    • Default value: None

  • step_minimum:

    • Default value: 0.01

    • Description: Minimum step size for the chord finder.

  • stepper:

    • Default value: DormandPrince745

    • Description: Integration stepper type. General-purpose (any field): ‘DormandPrince745’ (default), ‘ClassicalRK4’, ‘CashKarpRKF45’, ‘BogackiShampine45’, ‘BogackiShampine23’, ‘DormandPrinceRK56’, ‘DormandPrinceRK78’. Magnetic-only: ‘NystromRK4’, ‘ExactHelixStepper’.

create_field_manager(volume_obj) → opengate_core.G4FieldManager[source]#

Construct the field and return a configured G4FieldManager.

property field_matrix_B[source]#

field_matrix_B:

  • Default value: None

  • Description: 2D numpy array on a regular Cartesian grid in Geant4 units. Columns: [x, y, z, Bx, By, Bz].

property field_matrix_E[source]#

field_matrix_E:

  • Default value: None

  • Description: 2D numpy array on a regular Cartesian grid in Geant4 units. Columns: [x, y, z, Ex, Ey, Ez].

property interpolation[source]#

interpolation:

  • Default value: trilinear

  • Description: Interpolation method: ‘trilinear’ (default) or ‘nearest’.

VolumeBase.add_field(field: FieldBase)[source]#