Output

mutable struct HistoryOutput{C} <: Aether.Output.AbstractOutput

HistoryOutput(; dt = Inf, every_cycles = 0, columns = (),
              directory = ".", basename = "aether")

Plain-text history of volume integrals and extrema, one row per write, appended and flushed by rank 0 to <directory>/<basename>.hst with a #-prefixed header naming the columns. Fires every dt of simulation time, and additionally every every_cycles cycles when nonzero — per-cycle history while debugging without guessing a tiny dt; at least one trigger must be active.

User columns take the point form of derived field variables (§ the FieldOutput point form): a function of the cell NamedTuple paired with its reduction — + means $\sum f \, dV$; min/max mean the extremum (never volume-weighted):

columns = ("Tmax" => (max, cell -> cell.e / cell.ρ),
           "mass2" => (+, cell -> cell.ρ^2))

After a restore, rows later than the restored clock.t are removed before new rows are appended.

using Aether

HistoryOutput(dt = 0.01, columns = ("Tmax" => (max, cell -> cell.e / cell.ρ),))

# output
HistoryOutput(dt = 0.01, 1 user column)

mutable struct FieldOutput{P, V, EP, D, H} <: Aether.Output.AbstractOutput

FieldOutput(; dt,
            variables = (:primitive,),
            precision = Float32,
            directory = ".", basename = "aether", label = "field",
            engine_parameters = (;))

Write one collective BP5 field dump at each dt boundary, named <directory>/<basename>.<label>.<index%05d>.bp. Each variable is a global interior array without ghost cells, readable through ParaView/VisIt, Python ADIOS2, or read_field.

• variables: a tuple mixing selectors (:primitive, :conserved, :bcc, :dust, :vorticity, :current), canonical names (:dens, :vel1, :mom2, :eint, :etot, :bcc3, :vort1, :curr2, :divv, :divb, :dust1_dens, ...), their math aliases (:ρ, :v1, :ρv2, :e, :E, :B3, :ω1, :J2), and point-form pairs "name" => f with f a function of the cell NamedTuple (cell_point); captures must be isbits. Files use canonical short-ASCII names.
• precision: the file element type — Float32 by default (analysis dumps at half the bytes); pass the state's float type for full precision.
• engine_parameters: BP5 engine options such as NumAggregators, NumSubFiles, and AsyncWrite.

using Aether

FieldOutput(dt = 0.5, variables = (:ρ, :vorticity, "T" => cell -> cell.e / cell.ρ))

# output
FieldOutput(dt = 0.5, variables = (:dens, :vorticity, "T"), Float32)

mutable struct RestartOutput{EP, D, H, FH, FB} <: Aether.Output.AbstractOutput

RestartOutput(; dt = Inf, every_walltime = Inf, walltime_poll_cycles = 10,
              keep = 0, directory = ".", basename = "aether",
              engine_parameters = (;))

Write full-precision BP5 restart dumps named <directory>/<basename>.c<cycle%010d>.rst. The payload contains conserved gas and dust state, MHD face fields, and the clock position; restore! rebuilds derived state and recomputes the timestep.

• every_walltime additionally writes after the requested monotonic walltime, polled every walltime_poll_cycles.
• keep retains the newest committed dumps; 0 retains all dumps.

At least one of dt and every_walltime must be finite. Rank count may change when the mesh construction matches. Exact restore rejects components whose transient state is absent from the payload.

using Aether

RestartOutput(dt = 10.0, keep = 2)

# output
RestartOutput(dt = 10.0, keep = 2)

write!(
    output::Aether.Output.AbstractOutput,
    simulation
) -> Symbol

Write output now, recording :manual for an off-boundary write. Return :skipped after an earlier write in the same cycle. Call this collectively on every rank.

read_field(path::AbstractString; variable)

Read one variable of a FieldOutput dump back as an Array{precision} of the global interior cell dimensions (nx1, nx2, nx3), along with every file attribute as a NamedTuple (t, cycle, mesh construction, provenance, ...). variable accepts the canonical file name or its math alias, as a Symbol or String. Serial — one process reads the whole array; level-aware readers assemble refined dumps when refinement lands. Needs ADIOS2.jl loaded, like writing.

restore!(simulation, path::AbstractString; mode)

Restore the conserved state and clock position from path, rebuild derived state, and recompute the timestep from the restored state and current configuration. Payload schema is validated in every mode, and rank count may change.

• :continue warns on evolution-configuration differences and restarts transient components from a fresh sequence.
• :exact requires matching evolution configuration and rejects transient components.
• :branch follows :continue semantics and requires fresh output destinations.

Requires the ADIOS2 extension.