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. Input positions, velocities, phase-space axes, and dt are forwarded to vdsolverf in EMSES simulation units; convert SI values before calling these APIs.

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 in EMSES simulation units.

  • velocity (np.ndarray) – Initial particle velocity in EMSES simulation units.

  • ispec (int, optional) – Particle species index (0-based)

  • istep (int, optional) – Starting time-step index

  • dt (float or None, optional) – Time step size in EMSES simulation units. The value is forwarded unchanged; passing a negative value such as -data.inp.dt runs the solver in the opposite integration direction.

  • 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 in EMSES simulation units, shape (N, 3).

  • velocities (np.ndarray) – Particle velocity array in EMSES simulation units, 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 in EMSES simulation units. The value is forwarded unchanged; passing a negative value such as -data.inp.dt runs the solver in the opposite integration direction.

  • 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 vdsolverf.core.Particle objects whose positions and velocities are already in EMSES simulation units.

  • ispec (int, optional) – Particle species index (0-based)

  • istep (int, optional) – Starting time-step index

  • dt (float or None, optional) – Time step size in EMSES simulation units. The value is forwarded unchanged; passing a negative value such as -data.inp.dt runs the solver in the opposite integration direction.

  • 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) in EMSES simulation units.

  • y (tuple of (float, float, int) or sequence of float) – Y coordinates or grid specification in EMSES simulation units.

  • z (tuple of (float, float, int) or sequence of float) – Z coordinates or grid specification in EMSES simulation units.

  • vx (tuple of (float, float, int) or sequence of float) – Velocity x-component values or grid specification in EMSES simulation units.

  • vy (tuple of (float, float, int) or sequence of float) – Velocity y-component values or grid specification in EMSES simulation units.

  • vz (tuple of (float, float, int) or sequence of float) – Velocity z-component values or grid specification in EMSES simulation units.

  • ispec (int, optional) – Particle species index (0-based)

  • istep (int, optional) – Starting time-step index

  • dt (float or None, optional) – Time step size in EMSES simulation units. The value is forwarded unchanged; passing a negative value such as -data.inp.dt runs the solver in the opposite integration direction.

  • 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 in EMSES simulation units, shape (N, 3).

  • velocities (np.ndarray) – Particle velocity array in EMSES simulation units, 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 in EMSES simulation units. The value is forwarded unchanged; passing a negative value such as -data.inp.dt runs the solver in the opposite integration direction.

  • 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 vdsolverf.core.Particle objects whose positions and velocities are already in EMSES simulation units.

  • ispec (int, optional) – Particle species index (0-based)

  • istep (int, optional) – Starting time-step index

  • dt (float or None, optional) – Time step size in EMSES simulation units. The value is forwarded unchanged; passing a negative value such as -data.inp.dt runs the solver in the opposite integration direction.

  • 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.trace_result module

Integrated trace workflow result containers.

class emout.core.backtrace.trace_result.TraceResult(direction, probabilities=None, backward_traces=None, forward_traces=None, phases=None, dims=None, particles=None, unit=None)[source]

Bases: object

Integrated result returned by the high-level data.trace API.

The object always has the same shape regardless of which payloads were requested. Probability and trajectory payloads that were not requested are stored as None.

property alpha

Return probability-derived alpha values, or None if unavailable.

pair(var1, var2)[source]

Project the probability result onto a two-axis plane.

plot(var1='vx', var2='vz', kind='auto', direction=None, **plot_kwargs)[source]

Plot probabilities when available, otherwise plot trajectories.

plot3d(direction=None, plotter=None, use_si=True, offsets=None, show=False, alpha='auto', color='white', line_width=2.0, tube_radius=None, **mesh_kwargs)[source]

Draw trajectories on a PyVista plotter and return it.

Passing an existing plotter overlays the trajectories on the caller’s current 3-D field or boundary view.

plot_probabilities(var1='vx', var2='vz', **plot_kwargs)[source]

Plot the probability projection for var1 and var2.

plot_traces(var1='x', var2='z', direction=None, alpha='auto', **plot_kwargs)[source]

Plot trajectory pairs with optional probability-derived alpha.

property traces

Return the unambiguous trajectory payload.

both() results contain two trajectory payloads, so callers must use backward_traces or forward_traces explicitly.

emout.core.backtrace.trace_wrapper module

High-level trace workflow facade built on top of backtrace solvers.

class emout.core.backtrace.trace_wrapper.TraceWrapper(directory, inp, unit, remote_open_kwargs=None)[source]

Bases: object

High-level trace API exposed as data.trace.

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

Compute a backward trace workflow over a phase-space grid.

Return type:

TraceResult

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

Compute backward and forward trajectories from one phase-space grid.

Return type:

TraceResult

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

Compute a forward trace workflow over a phase-space grid.

Return type:

TraceResult

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.

class emout.core.backtrace.TraceResult(direction, probabilities=None, backward_traces=None, forward_traces=None, phases=None, dims=None, particles=None, unit=None)[source]

Bases: object

Integrated result returned by the high-level data.trace API.

The object always has the same shape regardless of which payloads were requested. Probability and trajectory payloads that were not requested are stored as None.

property alpha

Return probability-derived alpha values, or None if unavailable.

pair(var1, var2)[source]

Project the probability result onto a two-axis plane.

plot(var1='vx', var2='vz', kind='auto', direction=None, **plot_kwargs)[source]

Plot probabilities when available, otherwise plot trajectories.

plot3d(direction=None, plotter=None, use_si=True, offsets=None, show=False, alpha='auto', color='white', line_width=2.0, tube_radius=None, **mesh_kwargs)[source]

Draw trajectories on a PyVista plotter and return it.

Passing an existing plotter overlays the trajectories on the caller’s current 3-D field or boundary view.

plot_probabilities(var1='vx', var2='vz', **plot_kwargs)[source]

Plot the probability projection for var1 and var2.

plot_traces(var1='x', var2='z', direction=None, alpha='auto', **plot_kwargs)[source]

Plot trajectory pairs with optional probability-derived alpha.

property traces

Return the unambiguous trajectory payload.

both() results contain two trajectory payloads, so callers must use backward_traces or forward_traces explicitly.

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

Bases: object

High-level trace API exposed as data.trace.

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

Compute a backward trace workflow over a phase-space grid.

Return type:

TraceResult

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

Compute backward and forward trajectories from one phase-space grid.

Return type:

TraceResult

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

Compute a forward trace workflow over a phase-space grid.

Return type:

TraceResult