EntityTools

struct EntityData 
    path::String
    steps::Vector{Int64}
    times::Vector{Float64}
    settings::Dict{String, Any}
    fields::Union{FieldInfo, Nothing}
    particles::Union{ParticleInfo, Nothing}
    spectra::Union{SpectrumInfo, Nothing}
end

Struct to store metadata of an Entity simulation.

EntityData(sim_path::String; verbose=false)

Reads an overview of the simulation into an EntityData struct.

EntityUnits{T <: Real}

A struct to hold the normalized units for a plasma simulation. The fields are:

• skindepth0: The skin depth in normalized units.
• larmor0: The Larmor radius in normalized units.
• sigma0: The magnetization parameter, calculated as (skindepth0/larmor0)^2.
• B0: The magnetic field strength in normalized units, calculated as 1/larmor0.
• omegaB0: The cyclotron frequency in normalized units, calculated as B0.
• q0: The charge normalization factor, calculated as 1/(n0 * skindepth0^2).
• V0: The volume normalization factor, calculated as dx0^size(extent, 1).
• n0: The number density normalization factor, calculated as ppc0 / V0.

EntityUnits(data::EntityData)

Constructs the units from the simulation settings stored in data. Returns an EntityUnits struct containing the normalized units for the simulation.

EntityUnits(toml_path::String)

Reads the normalized units from the simulations' parameter file at the specified path.

struct FieldInfo <: DataInfo
    fields::Vector{String}
end

Struct to store info on field output.

struct ParticleInfo <: DataInfo
    species::Vector{Int64}
    properties::Vector{String}
end

Struct to store info on particle output.

SimOutput

Container for all per-step records parsed from a .out file. Iterable and indexable by step index. The set of substep and species names observed across the whole run is kept in substep_names / species_labels.

struct SpectrumInfo <: DataInfo
    species::Vector{Int64}
end

Struct to store info on output spectra.

StepData

Per-step record from an entity .out file. All times are in seconds. Substep timings are accessible by name: step["CurrentDeposit"].

sum(sim::SimOutput)              -> seconds
sum(sim::SimOutput, name)        -> seconds
maximum(sim::SimOutput, name)    -> seconds
minimum(sim::SimOutput, name)    -> seconds
mean(sim::SimOutput)             -> seconds
mean(sim::SimOutput, name)       -> seconds

Aggregate over the simulation. With no name, the aggregate runs over the per-step Total line. With a name, it runs over the named substep (e.g. "CurrentDeposit"); steps where the substep is absent are skipped.

adios2_throughput(path::AbstractString)

Read an ADIOS2 BP5 profiling.json and return a NamedTuple with:

• aggregate_TBps : Σwbytes(all ranks) / max(durable_us) [decimal TB/s]
• per_rank_mean_GBps : mean over writer ranks of wbytes / durable_us [decimal GB/s]
• per_rank_std_GBps : stddev of the same
• per_rank_raw_GBps : mean of wbytes / Σwrite.mus over writer ranks [decimal GB/s] — the raw POSIX write() rate, kept for reference; this measures the rate of memcpy into the page/client cache and overstates durable bandwidth, often above the filesystem spec
• n_writers : number of ranks that issued writes (BP5 aggregators)
• n_ranks : total ranks in the profile

durable_us per rank is ES + ES_close + DC_WaitOnAsync1 + DC_WaitOnAsync2, i.e. the EndStep window plus the Close-time drain of BP5's async writer thread. With AsyncWrite=ON, EndStep returns before bytes are durable; the drain shows up as DC_WaitOnAsync* at Close. Using this window gives bandwidth bounded by what actually reached storage.

Aggregate throughput uses max(durable_us) over all ranks (writers and non-writers) — non-writer ranks still block at Close waiting for the aggregator, and the wall clock is bounded by the slowest rank.

bp_to_vtk(data::EntityData, vtk_file::String, i_step::Integer)

Writes the fields of a given time step from an EntityData object to a VTK file.

compute_fieldlines(r_coords, th_coords, fr_data, fth_data, start_points; kwargs...)

Computes field lines of a vector field defined by radial (fr) and azimuthal (fth) components.

construct_bins_and_centers(bin_min, bin_max, Nbins)

Returns the bins and their center points.

construct_times(sim_path, subfolder, read_steps=false)

Finds all available output times for a given subfolder. If read_steps=true is set it also returns an array of the output steps constructed from file names.

dipole_sampling(; nth::Int=30, pole::Float64=1/16)

Returns an array of angles sampled from a dipole distribution.

find_closest_time(run_info::EntityData, t::Real)

Finds the time in the available outputs that is closest to the requested one

find_idxs(run_info, i_step, t, i, reduction_function, verbose)

Find requested output file(s) based on single/array of steps i_step, time t or file number i. If a reduction_function is provided, options are interpreted as arrays.

get_Temp(N::T, T00::T, V1::T, V2::T, V3::T; adiabatic_index::Real=5/3) where T <: Real

Compute the temperature based on Sridhar et al. (2021, https://arxiv.org/pdf/2107.00263), Appendix C. It uses the number density N, total energy T00, and velocity components V1, V2, and V3. The function uses a root-finding method to solve for the internal energy and then converts it to temperature using the relation T = (2/3) * E_int.

get_histograms(bins, Q)

Computes the histograms for M_s of all shocked particles

monopole_sampling(; nth::Int=30)

Returns an array of angles sampled from a monopole distribution.

omega_p = sqrt(4pin*q^2/m)

parse_compound_time(str)

Parse compound durations like "10s 143ms", "3min 39s", "286ms 625µs" into seconds.

parse_output(path) -> SimOutput

Parse an entity .out log file. The number and names of substeps are discovered dynamically. All times are stored in seconds.

parse_timing(filename)

Reads the output log file and returns a tuple of Arrays of (step_number, timing, active_p).

phase_map(x_q, y_q, x_lim, y_lim; 
          xbins::Int=400, ybins::Int=50,
          show_progress::Bool=true)

Get a 2D histogram of x_q and y_q in the limits x_lim, y_lim over a number if bins xbins and ybins.

polar_contour!(ax, r_coords, th_coords, data_values; kwargs...)

Plots standard contours for 2D polar data on rectilinear axes.

polar_fieldlines!(ax, r_coords, th_coords, fr_data, fth_data; kwargs...)

Plots field lines on an existing Makie axis.

polar_pcolor!(ax, r_coords, th_coords, data_values; kwargs...)

Plots a pseudocolor plot of 2D polar data onto a rectilinear projection. Creates a triangular mesh to cleanly handle non-uniform cells.

power_spectrum(field_x::AbstractArray, field_y::AbstractArray, field_z::AbstractArray; cells_per_skindepth = 1.0)

Computes the power spectrum of the given fields. The fields are expected to be 3D arrays with dimensions (nx, ny, nz) or 2D arrays with dimensions (nx, ny). The cells_per_skindepth parameter is used to scale the frequencies appropriately.

power_spectrum(field::AbstractArray; cells_per_skindepth = 1.0)

Computes the power spectrum of a single scalar field. The field is expected to be a 3D array with dimensions (nx, ny, nz) or a 2D array with dimensions (nx, ny). The cells_per_skindepth parameter is used to scale the frequencies appropriately.

power_spectrum_2D(field_x::AbstractArray, field_y::AbstractArray, field_z::AbstractArray; cells_per_skindepth = 1.0)

Computes the 2D power spectrum of the given fields. The fields are expected to be 3D arrays with dimensions (nx, ny, nz) or 2D arrays with dimensions (nx, ny). The cells_per_skindepth parameter is used to scale the frequencies appropriately.

power_spectrum_2D(field::AbstractArray; cells_per_skindepth = 1.0)

Computes the 2D power spectrum of a single scalar field. The field is expected to be a 2D array with dimensions (nx, ny). The cells_per_skindepth parameter is used to scale the frequencies appropriately.

power_spectrum_3D(field_x::AbstractArray, field_y::AbstractArray, field_z::AbstractArray; k_norm = 1.0)

Computes the 3D power spectrum of the given fields. The fields are expected to be 3D arrays with dimensions (nx, ny, nz). The cells_per_skindepth parameter is used to scale the frequencies appropriately.

power_spectrum_3D(field::AbstractArray; cells_per_skindepth = 1.0)

Computes the 3D power spectrum of a single scalar field. The field is expected to be a 3D array with dimensions (nx, ny, nz). The cells_per_skindepth parameter is used to scale the frequencies appropriately.

rLi(unit::EntityUnits, mi, me)

Larmor radius of a particle with mass mi in normalized units.

read_field(run_info::EntityData, field_name::String; 
                i_step=nothing, t=nothing, i=nothing,
                reduction_function=nothing,
                verbose::Bool=false)

Reads a single field for an individual file. If reduction_function is provied the reduced field is computed for the requested output or a range of outputs.

read_field(run_info::EntityData, field_names::Vector{String}; 
                i_step=nothing, t=nothing, i=nothing,
                reduction_function=nothing,
                slice=nothing,
                verbose::Bool=false)

Read fields with given field_names at a requested step i_step, time t or index i. If a reduction_function it is applied to the fields in the requested step, time or index range.

read_field_info(sim_path)

Reads the info on what fields are stored in the particles files.

read_fields_reduced(run_info::EntityData, field_names::Vector{String}; 
                i, reduction_function, slice, verbose)

Reads fields over an output range and computes a reduction based on reduction_function.

read_particle_info(sim_path)

Reads the info on what fields are stored in the particles files.

read_particles( run_info::EntityData, species::Integer, 
                properties::Vector{String}; 
                i_step=nothing, t=nothing, i=nothing,
                reduction_function=nothing,
                slice=nothing,
                verbose=true )

Read properties for particle species. Give either file number i, time t or step number i_step. If a reduction_function is given it computes the reduction per timestep. In this case you can also give i, t or i_step as arrays to read time series.

read_particles_reduced(run_info::EntityData, species::Integer, 
                       properties::Vector{String}; 
                       i=nothing, reduction_function=nothing,
                       slice=nothing,
                       verbose=false)

Read properties for particle species and apply reduction_function to the data.

read_run_settings(sim_path, subfolder)

Read the general settings of a run from the first file in a subfolder.

read_spectrum(run_info::EntityData, species::Integer; 
              i_step=nothing, t=nothing, i=nothing,
              verbose=true)

Read spectrum for particle species. Give either file number i, time t or step number i_step.

read_spectrum_info(sim_path)

Reads the info on what fields are stored in the spectrum files.

read_times(sim_path, subfolder, read_steps=false)

Finds all available output times for a given subfolder. If read_steps=true is set it also returns an array of the output steps constructed from file names.

reduce_read_positions(sel)

Reduces the individual read positions by finding sub-ranges. Returns an array of read indices and an array with the number of entries per index.

reinterpret_time(time_string)

Takes the time string and computes the duration in seconds

select_first_file(sim_path, subfolder)

Selects the first available file in a subfolder or throws an error

spectrum(Q, spec_min, spec_max; Nbins=100)

Constructs a spectrum dQ/dx between x values between spec_min and spec_max. Uses a number of Nbins=100 by default.

substep_series(sim, name)

Per-step time series (seconds) for substep name. Steps where the substep is absent return NaN.

summary_table(sim) -> Vector{NamedTuple}

One row per substep with (sum, mean, min, max) in seconds, in the order the substeps first appeared in the file.

vA(unit::EntityUnits)

Alfvén speed in normalized units.