Advectra Project Documentation

wave_vectors(domain::Domain)

Return a tuple of wave vectors for each axis, default (ky, kx).

domain_kwargs(domain::AbstractArray)

Return the domain specific keyword arguments, depending on the type of AbstractDomain.

area(domain::AbstractDomain)

Compute the area of the domain. By default use prod(lengths(domain)).

lengths(domain::Domain)

Return a tuple of lengths for each axis, default (Ly, Lx).

(diagnostic::Diagnostic)(state, prob, time)

Apply diagnostic method with the right args and kwargs stored in the Diagnostic.

Two dimensional Domain assuming bi-spectral boundary conditions, equiped with transform_plans` for how to transform between physical and spectral 'space'.

The Domain struct is a collection of hints for how to construct the SpectralOperators used in the Linear and NonLinear right hand sides (rhs) used in the SpectralODEProblem. In addition the Domain store info about the wave_vectors associated with the Domain`.

Constructors

Domain(N; L=1, kwargs...)

Domain(Nx, Ny; Lx=1, Ly=1, MemoryType=Array, precision=Float64, real_transform=true, dealiased=true, x0=-Lx / 2, y0=-Ly / 2)

Positional Arguments

For 'square' Domain specifically:

• N: number of points along both x- and y-direction (Integer).

For general 2D Domain specifically:

• Nx: number of points along the x-direction (Integer).
• Ny: number of points along the y-direction (Integer).

Keyword Arguments

For 'square' Domain specifically:

• L: length of domain along both directions (Number).

For general 2D Domain specifically:

• Lx: length of domain along the x-directions (Number).
• Ly: length of domain along the y-directions (Number)

General keyword arguments

• MemoryType: memory Type used to store states, fields, spectral coefficients, etc., also used to configure transform plans. Array is used by default but all <:AbstractArray types should be supported as long as the corresponding MemoryType package is loaded.
• precision: precision Type used in numerical calculations, also applies to precision of type and output. Defaults to Float64. Should be a numerical DataType.
• real_transform: boolean flag to tell the program whether or not to use rfft and irfft methods to transform between physical and spectral space. This halves the number of spectral coefficient needed to be stored. Defaults to true.
• dealiased: whether or not to dealias the Pseudo spectral

method. Defaults to true.

• x0: x-position of the lower left corner of the Domain. Defaults to $x0 = -Lx / 2$.
• y0: y-position of the lower left corner of the Domain. Defaults to $y0 = -Ly / 2$.

Examples

julia> Domain(128; L = 10, precision = Float32)
Domain(Nx:128, Ny:128, Lx:10.0, Ly:10.0, real_transform:true, dealiased:true, MemoryType:Array{Float32}) offset by (-5.0, -5.0)

julia> Domain(128, 256; Ly = 2, real_transform = true, x0 = 0, y0 = 10)
Domain(Nx:128, Ny:256, Lx:1.0, Ly:2.0, real_transform:true, dealiased:true, MemoryType:Array{Float64}) offset by (0.0, 10.0)

Fields

• dx: spatial resolution/grid spacing, dx = 2Lx÷(Nx-1), in x-direction.
• dy: spatial resolution/grid spacing, dy = 2Ly÷(Nx-1), in y-direction.
• x: spatial position of each point along the x-axis. Uniformly distributed by default.
• y: spatial position of each point along the y-axis. Uniformly distributed by default.
• kx: wave vector components along x-axis.
• ky: wave vector components along y-axis.

FFTPlans{FT<:FFTW.Plan, iFT<:FFTW.Plan}

Collection of transform plans using standard FFT.

Nullparamters()

Singleton to signalize that the user has not specified any parameters.

Output{DV, U, UB, T, S, PT, K}

A mutable struct for managing simulation output, diagnostics, and storage.

Fields

• stride::Int: Number of steps between stored samples.
• diagnostics::DV: Array of Diagnostics.
• u::U: Array for storing simulation states in memory.
• state_buffer::UB: Buffer for storing physical space state.
• t::T: Array for storing time points.
• simulation::S: HDF5 group or Nothing, representing the simulation storage.
• physical_transform::PT: Function to transform the state in physical space.
• store_hdf::Bool: Whether to store output in HDF5 format.
• store_locally::Bool: Whether to store output in memory.
• transformed::Bool: Indicates if the state has been transformed to physical space.
• h5_kwargs::K: Named tuple of keyword arguments for HDF5 storage.
• resume::Bool: Whether to resume from an existing output file.

Constructor

Output(prob::SOP; filename::FN, diagnostics::DV, stride::Integer, physical_transform::PT, simulation_name::SN, store_hdf::Bool, store_locally::Bool, storage_limit::AbstractString, h5_kwargs...)

Creates an Output object for a given SpectralODEProblemprob`. Handles setup for HDF5 and local storage, initializes diagnostics, and manages sampling stride.

Keyword Arguments

• filename: Name of the HDF5 file for output (default: random temporary name).
• diagnostics: Array of diagnostics to compute (default: DEFAULT_DIAGNOSTICS).
• stride: Number of steps between samples (default: -1 (lets the program decide)).
• physical_transform: Function to transform state in physical space (default: identity).
• simulation_name: Name for the simulation group in HDF5 (default: :timestamp).
• store_hdf: Store output in HDF5 file (default: true).
• store_locally: Store output in memory (default: true).
• storage_limit: Limit for field storage (default: empty string).
• h5_kwargs...: Additional keyword arguments for HDF5 storage (merged with defaults).
• resume: Resume from existing output file (default: false).

Usage

Create an Output object to manage simulation results, diagnostics, and storage options for a given spectral ODE problem.

SpectralODEProblem(L::Function, N::Function, u0, domain::AbstractDomain, tspan;
    p=NullParameters(), dt=0.01, remove_modes::Function=remove_nothing, kwargs...)
SpectralODEProblem(N::Function, u0, domain::AbstractDomain, tspan;
    p=NullParameters(), dt=0.01, remove_modes::Function=remove_nothing, kwargs...)

Collection of data needed to specify the spectral ODE problem to be solved. The user needs to specify the non-linear operator N, with the linear operator L being optional and otherwise assumed tp be zero. In addition the domain, initial condition u0 and timespan tspan needs to be specified. The parameters p will be passed onto the RHS/operators and the timestep dt is used by the temporal scheme. There is also the option to add a method remove_modes to remove certain modes after each timestep. Other kwargs can be stored in the struct, however these are currently unused.

rFFTPlans{FT<:FFTW.Plan, iFT<:FFTW.Plan}

Collection of transform plans using real FFT (rFFT), utilizing hermitian symmetry.

_compute_radial_COM_velocity!(memory, X_COM, time)

Compute radial COM velocity based on current X_COM and previous memory positions.

!!! warning The memory Dict is altered to store the current state as the previous for next sample.

add_h5_if_missing(filename::AbstractString)

Makes sure the filename has an extension, if not the .h5 extension is added.

allocate_coefficients(u0, transformplans::AbstractTransformPlans)

Recursively iterates trough the initial condition data structure to try to get to the lowest level Array and then allocates the needed shape after applying the fwd transform.

area(domain::AbstractDomain)

Compute the area of the domain. By default use prod(lengths(domain)).

assert_no_nan(u::AbstractArray, t)
assert_no_nan(u::AbstractGPUArray, t)

Checks if the first entry in u is NaN, if so a breakdown occured and an error is thrown.

build_probe_diagnostic(; name, method, positions, domain, quantities, 
assumes_spectral_state=false, interpolation)

General build method for probe diagnostics which prepares the positions and metadata.

cfl(state, prob, time, velocity=Val(:ExB), component=Val(:x); silent=false)

Compute CFL based on which velocity and what component, if silent=false then the results are printed.

See compute_velocity and compute_cfl for available options for velocity and component respectively.

Return

Array where row represent the component and the first column is the max cfl, with the remaining columns being indices.

check_storage_size(storage_limit::Int, N_steps::Int, stride::Int, sample; context="")

Checks that the needed storage does not exceed the storage_limit, otherwise an error is thrown, which recommends the minimum divisor satisfying the storage limit. In addition the error checks of recommend_stride are performed, which may trigger before the storage check.

compute_cfl(velocities::Tuple, prob, time; component::Symbol=:x)

Compute CFL-criterion for each velocity, based on which component is requested.

component options

• :x or :radial: return v_x*dt/dx.
• :y or :poloidal: return v_y*dt/dy.
• :both: return both :x and :y components.
• :magnitude: return hypot(vx, vy, ...)*dt/hypot(dx, dy, ...).

compute_number_of_steps(prob::SpectralODEProblem)

Computes the number of time steps the integrator needs to solve the problem prob. The last step might be fractional and is therefore rounded up due to the fixed prob.dt.

compute_radial_COM_position(field, prob, time)

Compute radial COM position for field (n) X_COM = ∑nx/∑n, excluding the boundary.

compute_storage_need(N_steps::Int, stride::Int, sample::AbstractArray; context="")

Computes the storage needed to store N_steps÷stridesamples with sizeof(sample).

compute_velocity(state, prob, time, velocity::Symbol=:ExB)

Compute the velocity fields, i.e. (vx, vy), based on velocity method.

velocity options:

• :ExB: uses (-∂ϕ∂y, ∂ϕ∂x)
• :burger: uses the state as the velocity magnitude.

Return

Tuple (vx, vy).

construct_transform_plans(utmp, ::Type{Domain}, ::Val{false})
construct_transform_plans(utmp, ::Type{Domain}, ::Val{true})

Constructs transform plans based on Domain type and if Real or Complex valued fields.

create_or_open_group(parent::Union{HDF5.File,HDF5.Group}, path::AbstractString; properties...)

Creates or opens an HDF5 group at the specified path within the given parent (which can be an HDF5.File or HDF5.Group). If the group at path exists, it is opened using open_group; otherwise, a new group is created using create_group. Additional keyword arguments (properties...) are passed onto the group creation or opening functions.

prepare_sampling(stride::Int, storage_limit, prob::SpectralODEProblem)

Prepares the sampling strategy for storing simulation states based on the desired stride and storage limit. Determines the number of samples to store and the stride between samples.

Arguments

• stride::Int: The proposed stride between samples. If set to -1, the function

will automatically recommend an appropriate stride based on the storage limit.

• storage_limit: The maximum allowed storage size for the output of fields, as a

string (e.g., "100 MB"). The limit does not affect the storage size of the Diagnostics! If empty, no storage constraint is applied.

• prob::SpectralODEProblem: The SpectralODEProblem` containing the size of the fields.

Notes

• If both stride and storage_limit are unspecified, all steps are recorded.
• The function validates and adjusts stride to ensure it is within feasible bounds.
• Issues a warning if the last step has a different stride than the rest.

differential_area(domain::AbstractDomain)

Compute the differential area of the domain. By default use prod(differential_area(domain)).

differential_elements()

Return a tuple of differential elements, the grid spacing along each axis, default (dy, dx).

domain_kwargs(domain::AbstractArray)

Return the domain specific keyword arguments, depending on the type of AbstractDomain.

energy_spectrum(power_spectrum::AbstractArray, prob, time, ::Val{spectrum})

Computes the energy spectrum E(k), based on the spectrum argument.

spectrum options:

• :radial: radial (kx) spectrum, averaged over the poloidal direction.
• :poloidal: poloidal (ky) spectrum, averaged over the radial direction.
• :wavenumber: wavenumber (k) spectrum, averaged over wavenumber magnitude |k|.

Returns:

(wavenumbers, E) where E = E(k) (`Tuple`).

ensure_in_domain(position, domain::Domain)

Checks if the position is inside the domain. Throws error if not.

format_bytes(nbytes::Integer)

Formats the number of bytes into a "human readable" format. For example: 1032 ⇒ "1.03 KB".

frequencies(state)

Displays a heatmap of the mode-amplitudes using log scale.

get_index(position, domain)

Return Tuple of indices, the closest index for each dimension.

get_label(domain::Domain)

Return a tuple of labels (Symbols) for each axis, default (:y, :x).

get_log_modes(state_hat, prob, time; axis::Symbol=:diag)

Return log(|state_hat|) along an axis. See get_modes for the axis options.

get_modes(state_hat, prob, time; axis::Symbol=:both)

Return state_hat, along an axis.

axis options (Symbol):

• kx: gets modes along the kx axis in spectral space.
• ky: gets modes along the ky axis in spectral space.
• both: gets all the modes in spectral space.
• kx: gets modes along the kx=ky line in spectral space.

get_points(domain::Domain)

Return a tuple of points along each axis, default (y, x).

handle_output!(output::O, step::Integer, u::T, prob::SOP, t::N)

Handles output operations for a simulation step, including state storage, diagnostics sampling, and mode removal. Ensures the spectral state is only transformed once per step. In addition a check is performed to detect breakdowns, to throw an error.

handle_simulation_name(simulation_name)

Creates a simulation_name string based on the users input.

Supported symbols:

• :filename creates a string with the basename of the file without the extension.
• :timestamp creates a timestamp string using Dates.now().
• :parameters creates a string with the parameter names and values.

initialize_diagnostics(prob, state, state_hat, t0)

Build diagnostics from prob.diagnostic_recipes and sample.

isinplace(prob::AbstractODEProblem{iip}) where {iip}
isinplace(f::Function)
isinplace(L::Function, N::Function)

Checks whether or not the functions are in place. Works like a trait.

kinetic_energy_spectrum(state_hat, prob, time, spectrum=Val(:radial))

Computes energy spectrum of the kinetic power spectrum |̂Ω(k)|², based on spectrum type.

See energy_spectrum for spectrum type options.

lengths(domain::Domain)

Return a tuple of lengths for each axis, default (Ly, Lx).

maybe_sample_diagnostics!(output, step::Integer, u, prob, t)

Iterates through the list of diagnostics (output.diagnostics) and determines whether or not to sample the diagnostic.

nearest_divisor(N::Int, target::Int)

Finds the nearest divisor of N to the target. If N is prime 1 is returned.

next_divisor(N, target)

Finds the smallest divisor of N that is ≥ target. If none exists (i.e. target > N), N is returned.

pad_size(Ns::NTuple{N,Int})

Computes the zero-pad size for the size Tuple $Ns$ following the 3/2 rule.

parameter_string(parameters::AbstractDict)
parameter_string(parameters::AbstractDict)

Creates a human readable string listing the parameters with values, for example: (κ=0.1,σ=0.02) ⇒ "κ=0.1, σ=0.02".

Allows for single method()

parse_storage_limit(limit::Integer)
parse_storage_limit(limit::AbstractString)

Parses a storage limit specified either as an integer (number of bytes) or as a string with optional units (defaults to B). Supports both decimal and binary units up to "EiB", with a decimal number of bytes. For example: "10MB", "5.2 GiB", "1024".

physical_flux(n_hat::T, dϕ_hat::T, domain)

Compute the flux in physical space given a 'spectal gradient' of ϕ and the spectral n. Dispatches on AbstractArray type T to differentiate between CPU and GPU.

poloidal_flux(state_hat, prob, time)

Computes Γ0(t) = 1/(LxLy)∫0^Lx∫0^Ly nvy dydx, does not take into acount dealiasing.

potential_energy_spectrum(state_hat, prob, time, spectrum=Val(:radial))

Computes energy spectrum of the potential power spectrum |̂n(k)|², based on spectrum type.

See energy_spectrum for spectrum type options.

prepare_indices(positions, domain::Domain)

Prepare an Array of LinearIndices related to the fields on the domain, for quicker parallel access.

prepare_initial_state(prob; physical_transform=identity)

Prepares the initial state by applying the user defined physical_transform, if any, to a copy of the initial condition stored in prob, returning it alongside the initial time.

prepare_metadata(; positions::AbstractArray{<:Tuple}, quantities::String)
prepare_metadata(; positions::AbstractArray{<:Tuple}, quantities::AbstractArray{<:String})

Prepare a human readable overview of positions of probes and what is measured.

prepare_operator_recipes(operators::Symbol,
                              additional_operators::Vector{<:OperatorRecipe},
                              diagnostics::Vector{<:DiagnosticRecipe})

Use switches to get a list of OperatorRecipes and append the additional_operators and required_operators by the diagnostics to it.

prepare_positions(positions, domain)

Convert positions into an Array{<:Tuples}, and check if the positions are in the domain.

prepare_transform_plans(Nx, Ny, use_cuda, precision, real_transform)

Prepare transform plan by preparing a domain using dispatching to call the right construction method.

print_cfl(maximas::Tuple, prob, time, component::Val{Symbol})

Print the max CFL number alongside index and time in a human readable format.

probe_all(state, prob, time; positions, interpolation=nothing)

Probe the density (n), vorticity (Ω), potential (ϕ), radial velocity field (vᵣ) and radial flux (Γ), at the given positions all "at once".

probe_density(state, prob, time; positions, interpolation=nothing)

Probe the density field, n, at the given positions.

probe_field(field::AbstractArray, domain::AbstractDomain, positions::AbstractArray,
                 interpolation::Nothing=nothing)
probe_field(field::AbstractArray, domain::AbstractDomain, positions::AbstractArray,
                 interpolation::AbstractInterpolation)

Probe the field at multiple positions using the domain to determine the indices. The method is dispatched on the interpolation method.

probe_field(field::AbstractArray, domain::AbstractDomain, position::Tuple)
probe_field(field::AbstractInterpolation, domain::AbstractDomain, position::Tuple)

Probe the field at one position using the domain to determine the index.

probe_potential(state, prob, time; positions, interpolation=nothing)

Probe the potential field, ϕ, at the given positions.

probe_radial_velocity(state, prob, time; positions, interpolation=nothing)

Probe the radial velocity field, vᵣ, at the given positions.

probe_temperature(state, prob, time; positions, interpolation=nothing)

Probe the temperature field, Ω, at the given positions.

probe_vorticity(state, prob, time; positions, interpolation=nothing)

Probe the vorticity field, Ω, at the given positions.

progress_bar(state, prob, time, progress; t0, dt)

Update `progress_bar` (`Progress` type from `ProgressMeter`.jl) based on evolution `time`.

### Keyword arguments:
- `t0`: start time (Number)
- `dt`: timestep (Number)

radial_COM(state, prob, time, memory=Dict(); field_idx::Int = 1)

Compute the radial position X_COM and velocity V_COM as long as memory is passed.

Returns

Array where first column/entry is the position and the second is the velocity.

radial_flux(state_hat, prob, time)

Computes Γ0(t) = 1/(LxLy)∫0^Lx∫0^Ly nvx dydx, does not take into acount dealiasing.

recommend_stride(storage_limit::Int, N_steps::Int, sample::AbstractArray; context="")

Recommends the closest divisor to the minimum stride needed to fullfil the storage_limit. If the storage_limit is too strict an error is thrown, which informs the user of the minimum limit.

restore_checkpoint(simulation::HDF5.Group, prob::SOP, scheme::SA) where {
SOP<:SpectralODEProblem,SA<:AbstractODEAlgorithm}

Restores Cache for scheme from checkpoint stored in simulation.

rewrite_dataset(parent::Union{HDF5.File,HDF5.Group}, name::AbstractString, data; pv...)

Deletes the dataset if it allready exists and creates and writes to a new dataset.

TODO write actuall string: The spectral state u is transformed to the real state U, with the user defined physical_transform applied, before being stored.

save_checkpoint!(output::O, cache::C, step::Integer, t::N) where {O<:Output,
C<:AbstractCache,N<:Number}

Creates or opens a checkpoint and stors the cacheat time t corresponding to step=step.

setup_simulation_group(file, simulation_name, N_samples, state, prob, t0; h5_kwargs)

Creates a HDF5 group with simulation_name (a "simulation"), and allocates the correct sizes based on N_samples with the fields being chunked with additinal h5_kwargs applied. In addition the inital condition is written along with the attributes of the prob.

setup_local_storage(state, t0, N_samples; store_locally=store_locally)

Allocates vectors in memory for storing the fields alongside the time if the user wants it, otherwise empty vectors are returned.

setup_hdf5_storage(filename, simulation_name, N_samples::Int, state, prob, t0; 
                   store_hdf=store_hdf, h5_kwargs=h5_kwargs)

Creates a HDF5 file, if not existing, and writes a group with simulation_name to it, refered to as a simulation group. If the simulation group does not exists, the h5_kwargs are applied to the "fields" and "t" datasets. The opened simulation is returned.

spectral_length(domain::AbstractDomain)

Return the number of spectral coefficients. (length in spectral space).

spectral_size(domain::AbstractDomain)

Return a tuple containing the size of the spectral coefficient Array (size in spectral space).

spectral_transform!(U<:AbstractArray, transformplan<:FFTW.Plan)
spectral_transform!(U<:Union{Tuple,Vector}, transformplan<:FFTW.Plan)

Spectral transform, applies transform plan p to u in-place returning du.

spectral_transform(U<:AbstractArray, transformplan<:FFTW.Plan)
spectral_transform(U<:Union{Tuple,Vector}, transformplan<:FFTW.Plan)

Spectral transform out-of-place, applies transform plan p to U.

store_checkpoint!(checkpoint::G, cache::C, step::Integer, t::N) where {G<:HDF5.Group,
C<:AbstractCache,N<:Number}

Stores checkpoint by dumping the fields of the cache that are not of type AbstractTableau. This overwrites the previously stored checkpoint.

store_diagnostic!(output, step::Integer, sample, time)

Stores sample to HDF5 file and memory, depending on the state of the output.store_hdf and output.store_locally respectively. The index is computed based on the step.

transform_state!(output, u, p)

Transforms spectral coefficients u_hat into real fields by applying spectral_transform! to the output.state_buffer buffer. The user defined physical_transform is also applied to the buffer, and the output.transformed flag is updated to not transform same field twice.

validate_positions(positions, domain)

Check that all points have the correct length and are within the bounds of the domain.

validate_resume_attributes(simulation::HDF5.Group, prob::SpectralODEProblem)

Checks if the existing HDF5 simulation group matches the current problem configuration for critical parameters: Nx, Ny, dt, and real_transform.

validate_stride(N_steps::Int, stride::Int; context="")

Validates and adjusts the `stride`. If `stride`:

• exceeds N_steps, it is set to N_steps and a warning is issued.
• is less than 1 an ArgumentError is thrown.
• does not evenly divide N_steps, a warning is issued and a suggested divisor is provided.

Returns the validated (and possibly adjusted) stride.

wave_vectors(domain::Domain)

Return a tuple of wave vectors for each axis, default (ky, kx).

wavenumber_metadata(::Val{spectrum}) where spectrum<:Symbol

Return human readable metadata about which wavenumber is stored.

write_attributes(simulation, prob::SpectralODEProblem)
write_attributes(simulation, domain::AbstractDomain)

Writes the esential attributes of the container to the simulation group simulation. The SpectralODEProblem also writes the domain properties.

write_local_state(output, idx, u, t)

Writes the state u at time t to the local storage in the Output struct.

write_to(h5group::HDF5.Group, idx, data, time)

Writes the data at time time to the h5group (HDF5).

Base.show(io::IO, transformplans::AbstractTransformPlans)

Pretty-print AbstractTransformPlans.

Base.show(io::IO, ::MIME"text/plain", transformplans::AbstractTransformPlans)

Compact one-line show of AbstractTransformPlans for use in arrays and etc.