emout.core.backtrace package¶

Submodules¶

emout.core.backtrace.backtrace_result module¶

Single-particle backtrace result container.

BacktraceResult stores the trajectory and field values along a single particle backtrace and provides attribute-based column access.

class emout.core.backtrace.backtrace_result.BacktraceResult(ts, probability, positions, velocities, unit=None)[source]¶

Bases: object

Container for a single-particle backtrace result.

Attributes (all NumPy arrays):

ts – shape (N_steps,)
probability – shape (N_steps,)
positions – shape (N_steps, 3) (x, y, z)
velocities – shape (N_steps, 3) (vx, vy, vz)

Usage:

ts, prob, pos, vel = result      # tuple unpacking

result.pair("x", "y").plot()     # x vs y
result.pair("t", "x").plot()     # t vs x
result.tx.plot()                 # shorthand for pair("t", "x")
result.yvz.plot()               # shorthand for pair("y", "vz")

pair(var1, var2)[source]¶

Extract two variables and return an XYData.

Parameters var1 and var2 must each be one of 't', 'x', 'y', 'z', 'vx', 'vy', 'vz'.

Examples:

result.pair("x", "y")   # x vs y
result.pair("t", "x")   # t vs x
result.pair("z", "vy")  # z vs vy

Return type:: XYData

emout.core.backtrace.multi_backtrace_result module¶

Multi-particle backtrace result container.

MultiBacktraceResult aggregates multiple BacktraceResult instances and supports sampling, iteration, and statistical queries.

class emout.core.backtrace.multi_backtrace_result.MultiBacktraceResult(ts_list, probabilities, positions_list, velocities_list, last_indexes, unit=None)[source]¶

Bases: object

Container for multiple particle backtrace results.

Attributes (all NumPy arrays):

ts_list – shape (N_traj, N_steps)
probabilities – shape (N_traj,)
positions_list – shape (N_traj, N_steps, 3)
velocities_list – shape (N_traj, N_steps, 3)
last_indexes – shape (N_traj,)

Usage:

ts_list, probs, pos_list, vel_list = result  # tuple unpacking

result.pair("x", "y")  # MultiXYData: x vs y per trajectory
result.pair("t", "x")  # t vs x per trajectory
result.tvx             # shorthand for pair("t", "vx")

result.sample(10)      # randomly sample 10 trajectories
result.sample([0,2,5]) # pick specific trajectory indices

result.yvz.plot()

pair(var1, var2)[source]¶

Extract two variables and return a MultiXYData.

Parameters var1 and var2 must each be one of 't', 'x', 'y', 'z', 'vx', 'vy', 'vz'.

Examples:

result.pair("x", "y")  # x vs y per trajectory
result.pair("t", "x")  # t vs x per trajectory
result.tvy             # shorthand for pair("t", "vy")

Return type:: MultiXYData

sample(indices, random_state=None)[source]¶

Sample a subset of trajectories and return a new result.

Parameters:

indices (Sequence[int], range, or slice) – Positive integer k: randomly sample k trajectories.
indices – Explicit index selection.
random_state (int, optional) – Random seed for reproducible sampling.

Return type:

MultiBacktraceResult

emout.core.backtrace.probability_result module¶

Energy-flux probability distribution results.

ProbabilityResult computes and visualises energy-resolved pitch-angle distributions, while HeatmapData wraps 2-D histogram payloads.

class emout.core.backtrace.probability_result.HeatmapData(X, Y, Z, xlabel='X', ylabel='Y', title='Heatmap', units=None)[source]¶

Bases: object

2-D histogram data with axis labels and a plot helper.

Stores bin edges, counts, and axis metadata produced by ProbabilityResult computations.

plot(ax=None, cmap='viridis', use_si=True, offsets=None, **plot_kwargs)[source]¶

Plot the heatmap with pcolormesh().

Parameters:

ax (matplotlib.axes.Axes, optional) – Target axes. If None, uses the current axes.
cmap (str, default "viridis") – Colormap name.
use_si (bool, default True) – Convert axes to SI units when unit info is available.
offsets (tuple of (float or str), optional) – (x_offset, y_offset) applied to the grid axes. Accepts "left", "center", "right" or a numeric shift.
**plot_kwargs – Forwarded to matplotlib.axes.Axes.pcolormesh().

Return type:

matplotlib.axes.Axes

class emout.core.backtrace.probability_result.ProbabilityResult(phases, probabilities, dims, ret_particles, particles, ispec, inp, unit=None)[source]¶

Bases: object

Phase-space probability distribution result.

Stores a 6-D grid of arrival probabilities and provides methods to project onto any 2-variable plane (var1, var2) as a HeatmapData.

energy_spectrum(energy_bins=None)[source]¶

Compute the energy spectrum.

Parameters:: energy_bins (int or array-like, optional) – Bin specification for the energy histogram. An integer sets the number of bins; an array sets the bin edges.
Returns:: (hist, bin_edges) – histogram counts and bin edge array.
Return type:: tuple of (np.ndarray, np.ndarray)

pair(var1, var2)[source]¶

Project onto a 2-variable plane and return a HeatmapData.

Parameters var1 and var2 must each be one of 'x', 'y', 'z', 'vx', 'vy', 'vz'. Axes not selected are integrated out using the trapezoidal rule.

Return type:: HeatmapData

plot_energy_spectrum(energy_bins=None, scale='log')[source]¶

Plot the energy spectrum.

Parameters:

energy_bins (int or array-like, optional) – Bin specification for the energy histogram. An integer sets the number of bins; an array sets the bin edges.
scale (str, optional) – Axis scale (e.g. "log", "linear").

emout.core.backtrace.solver_wrapper module¶

High-level wrapper for particle backtrace solvers.

BacktraceWrapper configures field interpolation, integrator parameters, and optional Dask-based remote execution, then delegates to the underlying ODE solver.

class emout.core.backtrace.solver_wrapper.BacktraceWrapper(directory, inp, unit, remote_open_kwargs=None)[source]¶

Bases: object

High-level wrapper for particle backtrace solvers.

Configures field interpolation, integrator parameters, and optional Dask-based remote execution, then delegates to the underlying ODE solver.

get_backtrace(position, velocity, ispec=0, istep=-1, dt=None, max_step=30000, output_interval=1, use_adaptive_dt=False, **kwargs)[source]¶

Run a single-particle backtrace and return the trajectory.

Parameters:

position (np.ndarray) – Initial particle position
velocity (np.ndarray) – Initial particle velocity
ispec (int, optional) – Particle species index (0-based)
istep (int, optional) – Starting time-step index
dt (float or None, optional) – Time step size
max_step (int, optional) – Maximum number of backtrace steps
output_interval (int, optional) – Output interval in steps
use_adaptive_dt (bool, optional) – If True, use adaptive time stepping during backtrace
**kwargs (dict) – Additional keyword arguments forwarded to the underlying function.

Returns:

Trajectory data containing times, probability, positions, and velocities.

Return type:

BacktraceResult

get_backtraces(positions, velocities, ispec=0, istep=-1, dt=None, max_step=10000, output_interval=1, use_adaptive_dt=False, n_threads=4, **kwargs)[source]¶

Run backtraces for multiple particles and return aggregated results.

Parameters:

positions (np.ndarray) – Particle position array, shape (N, 3)
velocities (np.ndarray) – Particle velocity array, shape (N, 3)
ispec (int, optional) – Particle species index (0-based)
istep (int, optional) – Starting time-step index
dt (float or None, optional) – Time step size
max_step (int, optional) – Maximum number of backtrace steps
output_interval (int, optional) – Output interval in steps
use_adaptive_dt (bool, optional) – If True, use adaptive time stepping during backtrace
n_threads (int, optional) – Number of parallel threads
**kwargs (dict) – Additional keyword arguments forwarded to the underlying function.

Returns:

Aggregated trajectory data for all particles.

Return type:

MultiBacktraceResult

get_backtraces_from_particles(particles, ispec=0, istep=-1, dt=None, max_step=10000, output_interval=1, use_adaptive_dt=False, n_threads=4, **kwargs)[source]¶

Run backtraces from pre-built Particle objects.

Parameters:

particles (Sequence[Any]) – Collection of particles to backtrace
ispec (int, optional) – Particle species index (0-based)
istep (int, optional) – Starting time-step index
dt (float or None, optional) – Time step size
max_step (int, optional) – Maximum number of backtrace steps
output_interval (int, optional) – Output interval in steps
use_adaptive_dt (bool, optional) – If True, use adaptive time stepping during backtrace
n_threads (int, optional) – Number of parallel threads
**kwargs (dict) – Additional keyword arguments forwarded to the underlying function.

Returns:

Aggregated trajectory data for all particles.

Return type:

MultiBacktraceResult

get_probabilities(x, y, z, vx, vy, vz, ispec=0, istep=-1, dt=None, max_step=10000, use_adaptive_dt=False, n_threads=4, remote=True, **kwargs)[source]¶

Compute arrival probabilities over a 6-D phase-space grid.

Parameters:

x (tuple of (float, float, int) or sequence of float) – X coordinates or grid specification (start, stop, n)
y (tuple of (float, float, int) or sequence of float) – Y coordinates or grid specification
z (tuple of (float, float, int) or sequence of float) – Z coordinates or grid specification
vx (tuple of (float, float, int) or sequence of float) – Velocity x-component values or grid specification
vy (tuple of (float, float, int) or sequence of float) – Velocity y-component values or grid specification
vz (tuple of (float, float, int) or sequence of float) – Velocity z-component values or grid specification
ispec (int, optional) – Particle species index (0-based)
istep (int, optional) – Starting time-step index
dt (float or None, optional) – Time step size
max_step (int, optional) – Maximum number of backtrace steps
use_adaptive_dt (bool, optional) – If True, use adaptive time stepping during backtrace
n_threads (int, optional) – Number of parallel threads
**kwargs (dict) – Additional keyword arguments forwarded to the underlying function.

Returns:

Phase-space probability distribution.

Return type:

ProbabilityResult

get_probabilities_from_array(positions, velocities, ispec=0, istep=-1, dt=None, max_step=10000, use_adaptive_dt=False, n_threads=4, **kwargs)[source]¶

Compute arrival probabilities from position/velocity arrays.

Parameters:

positions (np.ndarray) – Particle position array, shape (N, 3)
velocities (np.ndarray) – Particle velocity array, shape (N, 3)
ispec (int, optional) – Particle species index (0-based)
istep (int, optional) – Starting time-step index
dt (float or None, optional) – Time step size
max_step (int, optional) – Maximum number of backtrace steps
use_adaptive_dt (bool, optional) – If True, use adaptive time stepping during backtrace
n_threads (int, optional) – Number of parallel threads
**kwargs (dict) – Additional keyword arguments forwarded to the underlying function.

Returns:

Raw probability array returned by the backend.

Return type:

Any

get_probabilities_from_particles(particles, ispec=0, istep=-1, dt=None, max_step=10000, use_adaptive_dt=False, n_threads=4, **kwargs)[source]¶

Compute arrival probabilities from pre-built Particle objects.

Parameters:

particles (Sequence[Any]) – Collection of particles for probability computation
ispec (int, optional) – Particle species index (0-based)
istep (int, optional) – Starting time-step index
dt (float or None, optional) – Time step size
max_step (int, optional) – Maximum number of backtrace steps
use_adaptive_dt (bool, optional) – If True, use adaptive time stepping during backtrace
n_threads (int, optional) – Number of parallel threads
**kwargs (dict) – Additional keyword arguments forwarded to the underlying function.

Returns:

Raw probability array returned by the backend.

Return type:

Any

emout.core.backtrace.xy_data module¶

Lightweight x-y pair data containers for backtrace visualisation.

XYData holds a single named curve, while MultiXYData groups several curves for overlay plotting.

class emout.core.backtrace.xy_data.MultiXYData(x, y, last_indexes, xlabel='x', ylabel='y', title=None, units=None)[source]¶

Bases: object

Collection of XYData curves for overlay plotting.

plot(ax=None, use_si=True, gap=None, offsets=None, **plot_kwargs)[source]¶

Plot all series as overlaid line plots.

Parameters:

ax (matplotlib.axes.Axes, optional) – Target axes.
use_si (bool, default True) – Convert to SI units when available.
gap (float, optional) – Insert NaN breaks where consecutive-point distance exceeds gap.
offsets (tuple of (float or str), optional) – (x_offset, y_offset) applied after unit conversion.
**plot_kwargs – Forwarded to matplotlib.axes.Axes.plot(). alpha may be a scalar or a per-series array of length N.

Return type:

matplotlib.axes.Axes

class emout.core.backtrace.xy_data.XYData(x, y, xlabel='x', ylabel='y', title=None, units=None)[source]¶

Bases: object

Named x-y curve with optional unit labels and a plot helper.

plot(ax=None, use_si=True, gap=None, offsets=None, **plot_kwargs)[source]¶

Plot the x-y curve.

Parameters:

ax (matplotlib.axes.Axes, optional) – Target axes. If None, uses the current axes.
use_si (bool, default True) – Convert to SI units when available.
gap (float, optional) – Insert NaN breaks where consecutive-point distance exceeds gap.
offsets (tuple of (float or str), optional) – (x_offset, y_offset) applied after unit conversion.
**plot_kwargs – Forwarded to matplotlib.axes.Axes.plot().

Return type:

matplotlib.axes.Axes

Module contents¶

Backtrace analysis subpackage.

Provides solvers and result containers for computing particle backtraces and energy-flux probability distributions from EMSES output.