APIs

BATSRUS data reader and analyzer.

Alias for backward compatibility and convenience.

BATSRUS output high-level struct.

Batsrus file head information.

Batsrus structured data container, with Dim being the dimension of output.

Batsrus unstructured data container, with Dim being the dimension of output.

Type for Batsrus file information.

BATSRUS output standalone header information.

Build the global block enumeration shared by the connectivity and VTK writers: per-processor node lists sorted by local block index, and the node -> global block index mapping (blocks are numbered over processors in ascending order).

cutdata(data, var; plotrange=[-Inf,Inf,-Inf,Inf], dir="x", sequence=1)

Get 2D plane cut in orientation dir for var out of 3D box data within plotrange. The returned 2D data lies in the sequence plane from - to + in dir.

getfilesize(fileID::IOStream, lenstr::Int32, ::Val{FileType})

Return the size in bytes for one snapshot.

_keep_particle(val, check_x, xlo, xhi, check_y, ylo, yhi, check_z, zlo, zhi)

Return whether val (indexable by 1:3 for x/y/z) falls within all active range filters. Shared by the in-memory and per-grid selection paths so the two passes cannot diverge.

Adjust 2D plot ranges.

Create buffer for x and w.

animate(files::Vector{String}; kwargs...)

Save figures or create an animation from a sequence of SWMF output files. Stub to be implemented by plotting extensions.

Notable behaviors:

• vmin/vmax set to Inf are determined by scanning all snapshots, so the color scale stays consistent across the animation.
• plotinterval = nothing auto-detects the finest grid resolution (see finest_resolution), which is essential for AMR/unstructured output.
• If plot_kwargs is not provided, the colormap is selected automatically: RdBu_r with symmetric limits for bipolar data, turbo otherwise.

classify_particles(data, region; vdim=3, bulk_vel=nothing, vth=nothing, nsigma=3.0)

Classify particles in a spatial region into core Maxwellian and suprathermal populations.

Arguments

• data::AMReXParticle: Particle data.
• region: Passed as kwargs x_range, y_range, z_range.
• vdim: Velocity dimension (1, 2, or 3).
• bulk_vel: Core bulk velocity. If nothing, estimated from peak density.
• vth: Core thermal velocity. Must be provided.
• nsigma: Threshold for classification in units of thermal velocity.

Returns

• (core, suprathermal): Two matrices containing the classified particles.

cutplot(data, var, cut; kwargs...)

Plot a 2D slice of the data. Stub to be implemented by plotting extensions.

 fillCellNeighbors!(batl, iCell_G, DiLevelNei_III, iNodeNei_III, nodeToGlobalBlock_I)

Fill neighbor cell indexes for the given block. The faces, edges, and vertices are ordered from left (-) to right (+) in x-y-z sequentially.

Vertices: Edges: (10,11 ignored)

7 ----- 8        . --4-- .

• . - . 7 . 8 . 5 —– 6 . . –3– . 12 . . . . . . . . . 3 —– 4 9 . –2– . . - . - . 5 . 6 1 —– 2 . –1– .

Only tested for 3D.

fill_vector_from_scalars(bd::BatsrusIDL, var)

Construct vector of var from its scalar components. Alternatively, check get_vectors for returning vector components as separate arrays.

find_grid_block(batl, xyz_D)

Return processor local block index that contains a point. Input location should be given in Cartesian coordinates.

Find neighbors for any node in the tree. Only for Cartesian now.

find_tree_node(batl, Coord_D)

Find the node that contains a point. The point coordinates should be given in generalized coordinates normalized by the domain size.

Find variable index in the BATSRUS data.

finest_resolution(bd::BatsrusIDL)

Return the finest grid spacing min(dx, dy) of a 2D dataset bd.

For generalized coordinates (AMR/unstructured output), this is the minimum spacing between unique cell centers along each axis; small spacings relative to the axis span (below 1e-5 of the span) are filtered out to ignore duplicated nodes. For structured output, the coordinate steps are used directly.

This is useful to select an appropriate sampling interval when interpolating AMR data onto a uniform mesh, e.g. for interp2d or animate.

generate_mock_amrex_data(output_dir::String; num_particles::Int=10, 
    real_component_names::Vector{String}=["u", "v"],
    particle_gen::Function)

Generate mock AMReX particle data for testing and benchmarking.

Arguments

• output_dir::String: Directory to save the mock data.
• num_particles::Int: Number of particles to generate.
• real_component_names::Vector{String}: Names of the extra real components (beyond x, y, z).
• particle_gen::Function: A function (i, n_reals) -> tuple that takes an index i (1-based) and the total number of real components n_reals. It should return a tuple of n_reals Float64 values: (x, y, z, comp1, comp2, ...).

Get cell connectivity list.

getRotationMatrix(axis::AbstractVector, angle::Real) --> SMatrix{3,3}

Create a rotation matrix for rotating a 3D vector around a unit axis by an angle in radians. Reference: Rotation matrix from axis and angle

Example

using LinearAlgebra
v = [-0.5, 1.0, 1.0]
v̂ = normalize(v)
θ = deg2rad(-74)
R = getRotationMatrix(v̂, θ)

Return sibling index (1-8) for the given block node matrix.

get_anisotropy(bd::BatsrusIDL, species=0; method=:projection)

Calculate the pressure anisotropy for species. Two methods are supported:

• :projection: direct projection of the pressure tensor onto the magnetic field (default).
• :rotation: rotating the pressure tensor to a field-aligned coordinate system.

get_convection_E(bd::BatsrusIDL)

Return the convection electric field $\mathbf{E} = -\mathbf{u}_i \times \mathbf{B}$.

get_core_population_mask(velocities, bulk_vel, vth, nsigma=3.0)

Identify core population particles based on velocity distribution. Returns a BitVector where true indicates a core particle.

get_current_density(bd::BatsrusIDL)

Calculate the current density $\mathbf{J} = \nabla \times \mathbf{B} / \mu_0$ from the curl of the magnetic field. For PLANETARY units, the result is in $\mu A/m^2$. Currently only supports structured grids.

get_hall_E(bd::BatsrusIDL)

Return the Hall electric field $\mathbf{E}_H = (\mathbf{u}_i - \mathbf{u}_e) \times \mathbf{B}$.

get_magnitude(bd::BatsrusIDL, var = :B)

Calculate the magnitude of vector var. See get_vectors for the options.

get_magnitude2(bd::BatsrusIDL, var)

Calculate the magnitude square of vector var. See get_vectors for the options.

get_particle_field_aligned_transform(b_field, e_field=nothing)

Return a transformation function that converts particle data to a field-aligned coordinate system.

If only b_field is provided, the velocity components are decomposed into parallel and perpendicular to the magnetic field. If e_field is also provided, an orthonormal basis ($\hat{\mathbf{b}}$, $\hat{\mathbf{e}}$, $\hat{\mathbf{d}}$) is created, where $\hat{\mathbf{d}} \propto \mathbf{B} \times \mathbf{E}$ and $\hat{\mathbf{e}} = \hat{\mathbf{d}} \times \hat{\mathbf{b}}$.

The returned function takes (data, names) and returns (new_data, new_names).

get_pe_E(bd::BatsrusIDL, species=0; mass=nothing)

Return the electric field $\mathbf{E}_{p_e} = -\frac{1}{n_e e} \nabla \cdot \mathbf{P}_e$ derived from the divergence of the electron pressure tensor. Units are in μV/m if PLANETARY or km units are used, otherwise 1.0. Note that species 0 is by convention electrons, but it is not guaranteed.

Return mesh range of bd.

Return value range of var in bd. var can be an AbstractString or a Symbol.

get_vectors(bd::BatsrusIDL, var::Symbol)

Return vector components for var as a tuple of arrays.

get_vectors_indices(bd::BatsrusIDL, var::Symbol)

Return indices of vector components for var. Supported symbols are :B, :U, :E, :U0, and :U1.

Read ascii format coordinates and data values.

Read binary format coordinates and data values.

getfilehead(fileID::IoStream, filelist::FileList) -> NameTuple

Obtain the header information from BATSRUS output file of type linked to fileID.

Input arguments

• fileID::IOStream: file identifier.
• filelist::FileList: file information.

Obtain file type.

Type-stable getvar dispatch via Val. The compiler specialises on the symbol and returns a concretely typed array with no runtime branching inside the loop.

getvar(bd::BATS, var::AbstractString) -> Array

Return variable data from string var. This is also supported via direct indexing. Note that the query variable var must be in lowercase!

For derived/computed quantities, you can also pass a Symbol for a fully type-stable result:

• :b — magnetic field magnitude
• :b2 — magnetic field magnitude squared
• :e — electric field magnitude
• :u — bulk velocity magnitude
• :anisotropy0 — pressure anisotropy (2D only, species 0)
• :anisotropy1 — pressure anisotropy (2D only, species 1)

Examples

bd["rho"]        # direct file variable (string)
bd[:b]           # derived magnitude (symbol, type-stable)

Return view of variable var in bd.

interp1d(bd::BatsrusIDLStructured, var, loc::AbstractVector{<:AbstractFloat})

Interpolate var at spatial point loc in bd. var can be an AbstractString or a Symbol for derived quantities.

interp1d(bd::BatsrusIDLStructured, var, point1::Vector, point2::Vector)

Interpolate var along a line from point1 to point2 in bd. var can be an AbstractString or a Symbol for derived quantities.

interp2d(bd::BatsrusIDL, var, plotrange=[-Inf, Inf, -Inf, Inf],
 	plotinterval=Inf; kwargs...)

Return 2D interpolated slices of data var from bd. If plotrange is not set, output data resolution is the same as the original.

var can be an AbstractString for file variables or a Symbol for derived quantities (e.g. :b, :anisotropy). Using a Symbol is recommended for performance-critical calls because the returned array type is fully resolved at compile time.

Keyword Arguments

• innermask=false: Whether to mask the inner boundary with NaN.
• rbody=nothing: Radius of the inner mask. If not set, it will be read from the header.
• useMatplotlib=true: Whether to Matplotlib (faster) or NaturalNeighbours for scattered interpolation. If true, a linear interpolation is performed on a constructed triangle mesh.

Perform Triangle interpolation of 2D data W on grid X, Y.

load(filename; npict=1, verbose=false)

Read BATSRUS output files. Stores the npict snapshot from an ascii or binary data file into the arrays of coordinates x and data w.

Return the axis range for 2D outputs. See interp2d.

Generating consistent 2D arrays for passing to plotting functions.

order_children!(batl::Batl, iNode, iMorton::Int, iNodeMorton_I::Vector{Int32})

Recursively apply Morton ordering for nodes below a root block. Store result into iNodeMortonI and iMortonNodeA using the iMorton index.

order_tree(batl)

Return maximum AMR level in the used block and the Morton curve order. Set iNodeMorton_I indirect index arrays according to

1. root node order
2. Morton ordering for each root node

plot_phase!(ax, data, x_variable, y_variable; kwargs...)

Plots the 2D phase space density for selected variables. Stub to be implemented by plotting extensions.

plot_phase(data, args...; ax = nothing, kwargs...)

Plots the 2D phase space density for selected variables. This is a wrapper around plot_phase! that allows passing the axis as a keyword argument.

plotgrid(bd::AbstractBatsrusData, ax=nothing; kwargs...)
plotgrid(batl::Batl, ax=nothing; kwargs...)
plotgrid(head, data, connectivity; ax=nothing, kwargs...)

Plot simulation mesh. Stub to be implemented by plotting extensions.

plotlogdata(data, head::NamedTuple, func::AbstractString; plotmode = "line")

Plot log data. Stub to be implemented by plotting extensions.

Return BATL header from info file. Currently only designed for 2D and 3D.

Read information from log file.

readtecdata(file; verbose=false)

Return header, data and connectivity from BATSRUS Tecplot outputs. Both 2D and 3D binary and ASCII formats are supported.

Examples

file = "3d_ascii.dat"
head, data, connectivity = readtecdata(file)

Return BATL tree structure.

rotateTensorToVectorZ(tensor::AbstractMatrix, v::AbstractVector) -> SMatrix{3,3}

Rotate tensor with a rotation matrix that aligns the 3rd direction with vector, which is equivalent to change the basis from (i,j,k) to (i′,j′,k′) where k′ ∥ vector. Reference: Tensor rotation

showhead(file, head)
showhead(data)
showhead(io, data)

Displaying file header information of BATSRUS data.

slice1d(bd, var, icut::Int=1, dir::Int=2)

Return view of variable var in bd along 1D slice. icut is the index along axis dir. dir == 1 means align with the 2nd (y) axis, dir == 2 means align with the 1st (x) axis. var can be an AbstractString or a Symbol for derived quantities.

Squeeze singleton dimensions for an array A.

streamslice(data, var1, var2, cut; kwargs...)

Plot 2D streamlines. Stub to be implemented by plotting extensions.

subsurface(x, y, data, limits)
subsurface(x, y, u, v, limits)

Extract subset of 2D surface dataset in ndgrid format. See also: subvolume.

subvolume(x, y, z, data, limits)
subvolume(x, y, z, u, v, w, limits)

Extract subset of 3D dataset in ndgrid format. See also: subsurface.