Propagation and magnetic field¶

The propagation interface is built on top of the geometry to allow both curved and straight-line movement. Field propagation is based on a composition of:

Field: Maps a point in space and time to a field vector.
Equation of motion: Calculates the path derivative of position and momentum given their current state and the templated field.
Integrator: Numerically integrates a new position/momentum state given the start, path derivative, and step length.
Driver: Integrate path segments that satisfy certain error conditions, solving for the required segment length.
Propagator: Given a maximum physics step, advance the geometry state and momentum along the field lines, satisfying constraints (see field driver options) for the maximum geometry error.

Propagation¶

template<class GTV> class LinearPropagator¶: Propagate (move) a particle in a straight line.

template<class DriverT, class GTV> class FieldPropagator¶

Propagate a charged particle in a field.

For a given initial state (position, momentum), it propagates a charged particle along a curved trajectory up to an interaction length proposed by a chosen physics process for the step, possibly integrating sub-steps by an adaptive step control with a required accuracy of tracking in a field. It updates the final state (position, momentum, boundary) along with the step actually taken. If the final position is outside the current volume, it returns a geometry limited step and the state at the intersection between the curve trajectory and the first volume boundary using an iterative step control method within a tolerance error imposed on the closest distance between two positions by the field stepper and the linear projection to the volume boundary.

Note

This follows similar methods as in Geant4’s G4PropagatorInField class.

template<template<class EquationT> class StepperT, class FieldT, class GTV> decltype(auto) celeritas::make_mag_field_propagator(FieldT &&field, FieldDriverOptions const &options, ParticleTrackView const &particle, GTV &&geometry)¶

Create a magnetic field propagator.

Example:

FieldDriverOptions driver_options,
auto propagate = make_mag_field_propagator<DormandPrinceStepper>(
   UniformField{{1, 2, 3}},
   driver_options,
   particle,
   &geo);
propagate(0.123);

Field data input and options¶

These classes correspond to JSON input files to the field setup.

struct UniformFieldParams

Input data and options for a uniform field.

Public Members

Real3 field = {0, 0, 0}: Field strength (native units)

struct RZMapFieldInput

Input data for an magnetic R-Z vector field stored on an R-Z grid.

The magnetic field is discretized at nodes on an R-Z grid, and each point the field vector is approximated by a 2-D vector in R-Z. The input units of this field are in NATIVE UNITS (cm/gauss when CGS). An optional _units field in the input can specify whether the input is in SI or CGS units, with allowable values of “si”, “cgs”, or “clhep”. The native CLHEP unit strength is 1000*tesla.

The field values are all indexed with R having stride 1: [Z][R]

Public Functions

inline explicit operator bool() const: Whether all data are assigned and valid.

Public Members

double min_z = {}: Lower z coordinate [len].

double max_z = {}: Last z coordinate [len].

double min_r = {}: Lower r coordinate [len].

double max_r = {}: Last r coordinate [len].

std::vector<double> field_z: Flattened Z field component [bfield].

std::vector<double> field_r: Flattened R field component [bfield].

The field driver options are not yet a stable part of the API:

struct FieldDriverOptions

Configuration options for the field driver.

TODO: replace epsilon_rel_max with 1/epsilon_rel_max^2 TODO: replace safety with step_shrink_mul (or something to indicate that it’s a multiplicative factor for reducing the step, not anything with geometry) TODO: remove errcon

Public Functions

inline explicit operator bool() const: Whether all data are assigned and valid.

Public Members

real_type minimum_step = 1.0e-5 * units::millimeter: The minimum length of the field step.

real_type delta_chord = 0.25 * units::millimeter: The maximum sagitta of each substep (“miss distance”)

real_type delta_intersection = 1.0e-4 * units::millimeter: Accuracy of intersection of the boundary crossing.

real_type epsilon_step = 1.0e-5: Discretization error tolerance for each field substep.

real_type epsilon_rel_max = 1.0e-3: Targeted discretization error for “integrate step”.

real_type errcon = 1.0e-4: UNUSED: Targeted discretization error for “one good step”.

real_type pgrow = -0.20: Exponent to increase a step size.

real_type pshrink = -0.25: Exponent to decrease a step size.

real_type safety = 0.9: Scale factor for the predicted step size.

real_type max_stepping_increase = 5: Largest allowable relative increase a step size.

real_type max_stepping_decrease = 0.1: Smallest allowable relative decrease in step size.

short int max_nsteps = 100: Maximum number of integrations (or trials)

short int max_substeps = 10: Maximum number of substeps in the field propagator.

Public Static Attributes

static constexpr real_type initial_step_tol = 1e-6: Initial step tolerance.

static constexpr real_type dchord_tol = 1e-5 * units::millimeter: Chord distance fudge factor.

static constexpr real_type min_chord_shrink = 0.5: Lowest allowable scaling factor when searching for a chord.