Initial Conditions

An initial condition is a callable struct that subtypes InitialCondition. It takes a position pos::Space{D} and returns the state State{M} at that point.

set_initial_conditions! evaluates it at every particle. The kinetic pipeline uses a second method that maps the macroscopic state to the kinetic equilibrium (see Kinetic Relaxation).

In a configuration the initial condition is selected with :IC_name; build_ic converts all IC_ parameters to the simulation type T. The keys of each type are listed in the Configuration Reference.

Available initial conditions

Type	`:IC_name`	State at `pos`
`Gauss`	`:gauss`	$a \exp\left(-\lVert pos - b \rVert^2 / \mathrm{width}^2\right)$
`Box`	`:box`	`u_box` if `mins .<= pos .<= maxs` in every direction, else `u_bg`
`Sine`	`:sine`	$a \sin\left(2\pi \sum_d pos_d / \mathrm{period}_d\right) + c_\mathrm{offset}$
`Riemann`	`:riemann`	`uL` if $(pos - p_0) \cdot n < 0$, else `uR`
`SRiemann`	`:s_riemann`	$\frac{u_L + u_R}{2} - \frac{u_L - u_R}{\pi} \arctan\left(\frac{(pos - p_0)\cdot n}{\mathrm{width}}\right)$
`QRiemann`	`:q_riemann`	`u_states[1 + Σ_d 2^(d-1) (pos_d ≥ p0_d)]`

Notes:

Riemann normals. build_ic normalizes n (default $+x$). uL lies on the side the normal points away from.
Quadrant ordering. QRiemann needs 2^D states in binary order. In 2D: (bottom-left, bottom-right, top-left, top-right).
Precision. Gauss and SRiemann store their parameters in the precision of the amplitude/state. A Float32 configuration therefore evaluates entirely in Float32.

Adding an initial condition

Define a struct, make it callable, and add a builder method:

using HyperCloud, StaticArrays

struct Ring{D, M, T} <: InitialCondition
    u_in::State{M, T}
    u_out::State{M, T}
    center::Space{D, T}
    radius::T
end

(ic::Ring)(pos::Space{D}) where {D} = sum(abs2, pos - ic.center) < ic.radius^2 ? ic.u_in : ic.u_out

function HyperCloud.build_ic(::Val{:ring}, conf::Dict, ctx::Dict)
    T, D, M = ctx[:T]::DataType, ctx[:D]::Int, ctx[:M]::Int
    return Ring(State{M, T}(Tuple(T.(conf[:u_in]))), State{M, T}(Tuple(T.(conf[:u_out]))),
                Space{D, T}(Tuple(T.(conf[:center]))), T(conf[:radius]))
end

:IC_name => :ring now selects it. To use it as a reference solution, add an analytic_closure method for the equations where it has one (see PDE Architecture).

API

HyperCloud.InitialCondition — Type

InitialCondition

Abstract base type for all initial condition functors in the framework. Functors derived from this type evaluate the starting state of the physical system at a given spatial coordinate.

source

HyperCloud.set_initial_conditions! — Function

set_initial_conditions!(pg::ParticleGrid, eq::HyperbolicPDE, IC::InitialCondition)
set_initial_conditions!(pg::ParticleGrid, st::RelaxationSourceTerm, IC::InitialCondition, eq_macro::HyperbolicPDE)

Evaluates the initial condition functor and applies it to the particle grid.

Direct formulation: evaluates IC at every particle position and assigns the physical state to pg.rhos.
Kinetic formulation: evaluates the macroscopic state and physical fluxes at every particle and initializes the kinetic variables directly in the Maxwellian equilibrium, component by component.

source

HyperCloud.Box — Type

Box{D, M, T} <: InitialCondition

Defines a discontinuous rectangular sub-region.

Fields

u_bg::State{M, T}: The background state applied outside the box.
u_box::State{M, T}: The interior state applied within the box.
mins::Space{D, T}: The lower spatial bounds of the rectangular region.
maxs::Space{D, T}: The upper spatial bounds of the rectangular region.

Evaluates to u_box if mins .<= pos .<= maxs holds in every direction (the boundary belongs to the box), and to u_bg otherwise. Mixed-precision inputs are promoted to one T.

source

HyperCloud.Gauss — Type

Gauss{D, M, T} <: InitialCondition

Evaluates a smooth, multi-dimensional Gaussian pulse.

Fields

a::State{M, T}: The amplitude state vector.
b::Space{D, T}: The spatial center coordinate of the pulse.
width::T: The parameter controlling the spatial spread of the bell curve.

The physical state is computed as a * exp(-sum(abs2, pos - b) / width^2). The center and width are converted to the precision T of the amplitude, so a Float32 amplitude gives a pure Float32 pulse even if b or width are Float64.

source

HyperCloud.QRiemann — Type

QRiemann{D, M, N_states, T} <: InitialCondition

Defines a multi-dimensional quadrant Riemann problem that partitions the domain into orthogonal regions intersecting at a central point.

Fields

u_states::NTuple{N_states, State{M, T}}: A tuple of constant physical states corresponding to each spatial quadrant.
p0::Space{D, T}: The central intersection point of the quadrants.

The state index is 1 + Σ_d 2^(d-1) * (pos[d] >= p0[d]), so u_states must hold 2^D states ordered by binary encoding. In 2D: (bottom-left, bottom-right, top-left, top-right).

source

HyperCloud.Riemann — Type

Riemann{D, M, T} <: InitialCondition

Defines a standard discontinuous Riemann problem (e.g., a shock tube or half-space) split by a hyperplane.

Fields

uL::State{M, T}: The physical state vector on the "left" side of the hyperplane.
uR::State{M, T}: The physical state vector on the "right" side of the hyperplane.
p0::Space{D, T}: An origin point located exactly on the separating hyperplane.
n::Space{D, T}: The normal vector of the hyperplane pointing toward the right state.

Returns uL if the dot product of the relative position and the normal is negative, and uR otherwise.

source

HyperCloud.Sine — Type

Sine{D, M, T} <: InitialCondition

Evaluates a smooth, multi-dimensional periodic sinusoidal wave.

Fields

a::State{M, T}: The amplitude state of the wave.
period::Space{D, T}: The spatial periodicity along each axis.
c_offset::State{M, T}: The constant background offset state.

The physical state is a * sin(2π * sum(pos ./ period)) + c_offset. It is evaluated with sinpi, which keeps the input precision (no promotion to Float64 via pi) and is exact at integer multiples of the period.

source

HyperCloud.SRiemann — Type

SRiemann{D, M, T} <: InitialCondition

Smoothed, continuous approximation of a standard Riemann problem that avoids infinite initial gradients at the interface.

Fields

uL::State{M, T}: The asymptotic physical state on the "left".
uR::State{M, T}: The asymptotic physical state on the "right".
p0::Space{D, T}: A point located on the central interface.
n::Space{D, T}: The normal vector pointing toward the right state.
width::T: Controls the steepness of the transition.

Uses an arctangent to blend smoothly between uL and uR over the given width. All fields are converted to the precision T of uL.

source