Tracker

class plasmapy.diagnostics.charged_particle_radiography.synthetic_radiography.Tracker(grids: AbstractGrid | Iterable[AbstractGrid], source: Quantity, detector: Quantity, detector_hdir=None, verbose: bool = True)

Bases: object

Represents a charged particle radiography experiment with simulated or calculated E and B fields given at positions defined by a grid of spatial coordinates. The particle source and detector plane are defined by vectors from the origin of the grid.

Parameters:

• grids (AbstractGrid or subclass thereof, or list) – of same. A Grid object or list of grid objects containing the required quantities [E_x, E_y, E_z, B_x, B_y, B_z]. If any of these quantities are missing, a warning will be given and that quantity will be assumed to be zero everywhere.

• source (Quantity, shape (3)) –

  A vector pointing from the origin of the grid to the location of the particle source. This vector will be interpreted as being in either cartesian, cylindrical, or spherical coordinates based on its units. Valid geometries are:

  • Cartesian (x,y,z) : (meters, meters, meters)

  • Cylindrical (r, theta, z) : (meters, radians, meters)

  • Spherical (r, theta, phi) : (meters, radians, radians)

  In spherical coordinates theta is the polar angle.

• detector (Quantity, shape (3)) – A vector pointing from the origin of the grid to the center of the detector plane. The vector from the source point to this point defines the normal vector of the detector plane. This vector can also be specified in cartesian, cylindrical, or spherical coordinates (see the source keyword).

• detector_hdir (numpy.ndarray, shape (3), optional) –

  A unit vector (in Cartesian coordinates) defining the horizontal direction on the detector plane. By default, the horizontal axis in the detector plane is defined to be perpendicular to both the source-to-detector vector and the z-axis (unless the source-to-detector axis is parallel to the z axis, in which case the horizontal axis is the x-axis).

  The detector vertical axis is then defined to be orthogonal to both the source-to-detector vector and the detector horizontal axis.

• verbose (bool, optional) – If true, updates on the status of the program will be printed into the standard output while running.

Attributes Summary

max_deflection	The maximum deflection experienced by one of the particles, determined by comparing their initial and final velocity vectors.
num_grids
on_any_grid	Binary array for each particle indicating whether it is currently on ANY grid.
results_dict	A dictionary containing the results of the simulation.

Methods Summary

add_wire_mesh(location, extent, nwires, ...)	Add a wire mesh grid between the particle source and the object grid that blocks particles whose paths intersect the wires.
create_particles(nparticles, particle_energy)	Generates the angular distributions about the Z-axis, then rotates those distributions to align with the source-to-detector axis.
load_particles(x, v[, particle])	Load arrays of particle positions and velocities.
run([dt, field_weighting])	Runs a particle-tracing simulation.
save_results(path)	Save the simulations results results_dict to a numpy .npz file format (see numpy.lib.format) using numpy.savez.

Attributes Documentation

max_deflection

The maximum deflection experienced by one of the particles, determined by comparing their initial and final velocity vectors.

This value can be used to determine the charged particle radiography regime using the dimensionless number defined by Kugland et al. 2012

Returns:

max_deflection – The maximum deflection in radians

Return type:

float

num_grids

on_any_grid

Binary array for each particle indicating whether it is currently on ANY grid.

results_dict

A dictionary containing the results of the simulation.

Dictionary keys and descriptions.

Key	Type	Description
"source"	ndarray	The source location vector, in meters.
"detector"	ndarray	The detector location vector, in meters.
"mag"	float	The system magnification.
"nparticles"	int	Number of particles in the simulation.
"max_deflection"	ndarray	The maximum deflection experienced by a particle in the simulation, in radians.
"x"	ndarray, [nparticles,]	The x-coordinate location where each particle hit the detector plane, in meters.
"y"	ndarray, [nparticles,]	The y-coordinate location where each particle hit the detector plane, in meters.
"v"	ndarray, [nparticles, 3]	The velocity of each particle when it hits the detector plane, in meters per second. The velocity is in a coordinate system relative to the detector plane. The components are [normal, horizontal, vertical] relative to the detector plane coordinates.
"x0"	ndarray, [nparticles,]	The x-coordinate location where each particle would have hit the detector plane if the grid fields were zero, in meters. Useful for calculating the source profile.
"y0"	ndarray, [nparticles,]	The y-coordinate location where each particle would have hit the detector plane if the grid fields were zero, in meters. Useful for calculating the source profile.
"v0"	ndarray, [nparticles, 3]	The velocity of each particle when it hit the detector plan if the grid fields were zero, in meters per second. The velocity is in a coordinate system relative to the detector plane. The components are [normal, horizontal, vertical] relative to the detector plane coordinates.

Methods Documentation

add_wire_mesh(location, extent, nwires, wire_diameter, mesh_hdir=None, mesh_vdir=None)

Add a wire mesh grid between the particle source and the object grid that blocks particles whose paths intersect the wires.

Parameters:

• location (Quantity, shape (3)) –

  A vector pointing from the origin of the grid to the center of the mesh grid. This location must be between the source and the object grid.

  This vector will be interpreted as being in either cartesian, cylindrical, or spherical coordinates based on its units. Valid geometries are:

  • Cartesian (x,y,z) : (meters, meters, meters)

  • Cylindrical (r, theta, z) : (meters, radians, meters)

  • Spherical (r, theta, phi) : (meters, radians, radians)

  In spherical coordinates theta is the polar angle.

• extent (Tuple of 1 or 2 Quantity) – The size of the mesh grid (in the mesh plane). If one value is provided, the mesh is circular and the value provided is interpreted as the diameter. If two values are provided, the mesh is rectangular and the values are interpreted as the width and height respectively.

• nwires (Tuple of 1 or 2 ints, or a single int) – The number of wires in the horizontal and vertical directions. If only one value is provided, the number in the two directions is assumed to be equal. Note that a wire will cross the center of the mesh only when nwires is odd.

• wire_diameter (Quantity) – The diameter of the wires.

• mesh_hdir (numpy.ndarray, shape (3), optional) – A unit vector (in Cartesian coordinates) defining the horizontal direction on the mesh plane. Modifying this vector can rotate the mesh in the plane or tilt the mesh plane relative to the source-detector axis. By default, mesh_hdir is set equal to detector_hdir (see detector_hdir keyword in __init__).

• mesh_vdir (numpy.ndarray, shape (3), optional) – A unit vector (in Cartesian coordinates) defining the vertical direction on the mesh plane. Modifying this vector can tilt the mesh relative to the source-detector axis. By default, mesh_vdir is defined to be perpendicular to mesh_hdir and the detector plane normal (such that the mesh is parallel to the detector plane).

Raises:

ValueError – Raises a ValueError if the provided mesh location is not between the source and the object grid.

create_particles(nparticles, particle_energy, max_theta=None, particle: Particle = Particle('p+'), distribution='monte-carlo', random_seed=None) → None

Generates the angular distributions about the Z-axis, then rotates those distributions to align with the source-to-detector axis.

By default, particles are generated over almost the entire pi/2. However, if the detector is far from the source, many of these particles will never be observed. The max_theta keyword allows these extraneous particles to be neglected to focus computational resources on the particles who will actually hit the detector.

Parameters:

• nparticles (integer) – The number of particles to include in the simulation. The default is 1e5.

• particle_energy (Quantity) – The energy of the particle, in units convertible to eV. All particles are given the same energy.

• max_theta (Quantity, optional) – The largest velocity vector angle (measured from the source-to-detector axis) for which particles should be generated. Decreasing this angle can eliminate particles that would never reach the detector region of interest. If no value is given, a guess will be made based on the size of the grid. Units must be convertible to radians.

• particle (Particle or string representation of same, optional) – Representation of the particle species as either a Particle object or a string representation. The default particle is protons.

• distribution (str) –

  A keyword which determines how particles will be distributed in velocity space. Options are:

  • ’monte-carlo’: velocities will be chosen randomly,

    such that the flux per solid angle is uniform.

  • ’uniform’: velocities will be distributed such that,

    left unperturbed,they will form a uniform pattern on the detection plane. This method requires that nparticles be a perfect square. If it is not, nparticles will be set as the largest perfect square smaller than the provided nparticles.

  Simulations run in the 'uniform' mode will imprint a grid pattern on the image, but will well-sample the field grid with a smaller number of particles. The default is 'monte-carlo'.

• random_seed (int, optional) – A random seed to be used when generating random particle distributions, e.g. with the monte-carlo distribution.

load_particles(x, v, particle: Particle = Particle('p+'))

Load arrays of particle positions and velocities.

Parameters:

• x (Quantity, shape (N,3)) – Positions for N particles

• v (Quantity, shape (N,3)) – Velocities for N particles

• particle (particle-like, optional) – Representation of the particle species as either a Particle object or a string representation. The default particle is protons.

• distribution (str) –

  A keyword which determines how particles will be distributed in velocity space. Options are:

  • ’monte-carlo’: velocities will be chosen randomly,

    such that the flux per solid angle is uniform.

  • ’uniform’: velocities will be distributed such that,

    left unperturbed,they will form a uniform pattern on the detection plane.

  Simulations run in the 'uniform' mode will imprint a grid pattern on the image, but will well-sample the field grid with a smaller number of particles. The default is 'monte-carlo'.

run(dt=None, field_weighting='volume averaged')

Runs a particle-tracing simulation. Timesteps are adaptively calculated based on the local grid resolution of the particles and the electric and magnetic fields they are experiencing. After all particles have left the grid, they are advanced to the detector plane where they can be used to construct a synthetic diagnostic image.

Parameters:

• dt (Quantity, optional) – An explicitly set timestep in units convertible to seconds. Setting this optional keyword overrules the adaptive time step capability and forces the use of this timestep throughout. If a tuple of timesteps is provided, the adaptive timestep will be clamped between the first and second values.

• field_weighting (str) –

  String that selects the field weighting algorithm used to determine what fields are felt by the particles. Options are:

  • ’nearest neighbor’: Particles are assigned the fields on

    the grid vertex closest to them.

  • ’volume averaged’The fields experienced by a particle are a

    volume-average of the eight grid points surrounding them.

  The default is ‘volume averaged’.

Return type:

None

save_results(path) → None

Save the simulations results results_dict to a numpy .npz file format (see numpy.lib.format) using numpy.savez.

Parameters:

path (str or os.path) – Either the filename (string) or an open file (file-like object) where the data will be saved. If file is a string or a Path, the .npz extension will be appended to the filename if it is not already there.

Notes

Useful for saving the results from a simulation so they can be loaded at a later time and passed into synthetic_radiograph.