ParticleHistory¶

class disco.ParticleHistory(t, x, y, z, ppar, M, B, W, h, stopped, mass, charge, extra_fields=None)[source]¶

Bases: object

History of trajectory tracing.

Arrays are in the shape (n_time_steps, n_particles). Mass and charge are scalars.

If some parameters completed integration in fewer timesteps than others (such as by reaching the integration limit or going out of bounds), the last item will be duplicated to match the shape of the other arrays. The last item before duplication can be found by checking the stopped array, which is a boolean array of the same shape as the other arrays.

Output can be stored and read from disk in HDF5 format. See the load() and save() methods.

Attributes:

tarray with units: Time of the particle state at each step.
xarray with units: X position of the particle at each step.
yarray with units: Y position of the particle at each step.
zarray with units: Z position of the particle at each step.
ppararray with units: Parallel momentum of the particle at each step.
Marray with units: Magnetic moment of the particle at each step.
Barray with units: Magnetic field at the particle position at each step.
Warray with units: Total energy of the particle at each step.
harray with units: Adapative step size used in the integration at each step.
stoppedarray of bool: Boolean array indicating whether the particle stopped at each step.
extra_fieldsdict: Dictionary of additional fields computed during the trajectory tracing. Keys are field names and values are arrays with the same shape as the other arrays.
massscalar with units: Mass of the particles (constant).
chargescalar with units: Charge of the particles (constant).

Notes

See disco.TraceConfig(output_freq=...): for controlling between how many iterations between particle state is saved. If output_freq is set to None (the default), only the first and last points of the trace will be saved.

Examples

Saving output to disk:

>>> hist = disco.trace_trajectory(config, particle_state, field_model)
>>> hist.save("particle_history.h5")

Loading output from disk and plotting:

>>> hist = disco.ParticleHistory.load("particle_history.h5")
>>> hist.plot_xz()
>>> plt.savefig('myplot.png')

Methods Summary

`load`(hdf_path)	Load particle history from an HDF5 file.
`plot_xy`([ax, inds, endpoints, sample, ...])	Plot the particle trajectory in the XY plane.
`plot_xz`([ax, inds, endpoints, sample, ...])	Plot the particle trajectory in the XZ plane.
`plot_yz`([ax, inds, endpoints, sample, ...])	Plot the particle trajectory in the YZ plane.
`save`(hdf_path)	Save particle history to an HDF5 file.

Methods Documentation

classmethod load(hdf_path)[source]¶

Load particle history from an HDF5 file.

Parameters:

hdf_path: str: Path to the HDF5 file from which the history will be loaded.

Returns:

An instance of ParticleHistory containing the loaded data.

Notes

See ParticleHistory.save() to save particle history to an HDF5 file.

plot_xy(ax=None, inds=None, endpoints=False, sample=None, earth=True, grid=True, title='Particle Trajectory in XY Plane')[source]¶

Plot the particle trajectory in the XY plane.

Parameters:

ax: matplotlib axes: Matplotlib axis to plot on. If None, a new figure and axis will be created.
inds: int or list of ints: Indices of the points to plot. If None, all points will be plotted.
endpoints: bool: If True, plot only the start and end points of the trajectory.
sample: int, optional: If specified, randomly sample this many particles to plot.
earth: bool: If True, draw a circle representing the Earth at the origin.
grid: bool: If True, add a grid to the plot.
title: str: Title of the plot.

Returns:

The axis with the plotted trajectory.

Examples

>>> hist = disco.ParticleHistory.load("particle_history.h5")
>>> hist.plot_xy()
>>> plt.savefig('myplot.png')

plot_xz(ax=None, inds=None, endpoints=False, sample=None, earth=True, grid=True, title='Particle Trajectory in XZ Plane')[source]¶

Plot the particle trajectory in the XZ plane.

Parameters:

ax: matplotlib axes: Matplotlib axis to plot on. If None, a new figure and axis will be created.
inds: int or list of ints: Indices of the points to plot. If None, all points will be plotted.
endpoints: bool: If True, plot only the start and end points of the trajectory.
sample: int, optional: If specified, randomly sample this many particles to plot.
earth: bool: If True, draw a circle representing the Earth at the origin.
grid: bool: If True, add a grid to the plot.
title: str: Title of the plot.

Returns:

The axis with the plotted trajectory.

Examples

>>> hist = disco.ParticleHistory.load("particle_history.h5")
>>> hist.plot_xz()
>>> plt.savefig('myplot.png')

plot_yz(ax=None, inds=None, endpoints=False, sample=None, earth=True, grid=True, title='Particle Trajectory in YZ Plane')[source]¶

Plot the particle trajectory in the YZ plane.

Parameters:

ax: matplotlib axes: Matplotlib axis to plot on. If None, a new figure and axis will be created.
inds: int or list of ints: Indices of the points to plot. If None, all points will be plotted.
endpoints: bool: If True, plot only the start and end points of the trajectory.
sample: int, optional: If specified, randomly sample this many particles to plot.
earth: bool: If True, draw a circle representing the Earth at the origin.
grid: bool: If True, add a grid to the plot.
title: str: Title of the plot.

Returns:

The axis with the plotted trajectory.

Examples

>>> hist = disco.ParticleHistory.load("particle_history.h5")
>>> hist.plot_yz()
>>> plt.savefig('myplot.png')

save(hdf_path)[source]¶

Save particle history to an HDF5 file.

Parameters:

hdf_path: str: Path to the HDF5 file where the history will be saved.

Notes

See ParticleHistory.load(): to load particle history from an HDF5 file.

ParticleHistory¶

Navigation

Related Topics