Configuration Reference

A simulation is described by one flat Dict{Symbol, Any}. Keys are grouped into namespaces by prefix: :Grid_Ns belongs to the Grid namespace and reaches the builder as :Ns (see extract_namespace). Keys without a prefix are global.

Most namespaces configure numerical components of HyperCloudCore; their builders and defaults are documented in HyperCloudCore's Config-Driven Builders.

A method dictionary (for example from create_method) is merged on top of the shared parameters, so any key below may appear in either place.

Global keys

Key	Default	Meaning
`:sim_func_name`	—	Pipeline to run: `:run_direct_simulation` or `:run_kinetic_simulation`. Set automatically by `create_method`.
`:tmax`	—	Final time. `:Time_tmax` overrides it.
`:snapshots`	—	Number of output intervals; `snapshots + 1` states are stored, including `t = 0`.
`:remove_ghosts`	`true`	Drop boundary/ghost particles from the stored snapshots.
`:T`	`Float64`	Floating-point type of the simulation.
`:real_type`	`Float64`	Floating-point type of the exact reference (`analytical_solution`).
`:save_relax`	`false`	Kinetic runs only: store the raw kinetic variables instead of the macroscopic state.

`PDE_` — equation

Key	Used by	Meaning
`:name`	all	`:linear`, `:burgers` or `:euler`. Required.
`:D`	`:burgers`, `:euler`	Spatial dimension. Linear advection infers `D` from `:velocities`.
`:velocities`	`:linear`	One entry per dimension describing $A_d$; see Linear Advection.
`:gamma`	`:euler`	Ratio of specific heats.

The Euler representation is read from the same namespace by parse_representation: :representation is :conservative (default), :primitive or :lagrangian, the latter two with an integration :path (default :mapped).

`Grid_` — domain and particles

Key	Default	Meaning
`:domain`	—	`:rectangular`, `:spherical`, or a pre-built `GeometricDomain`. Required.
`:mins`, `:maxs`	—	Bounding box (tuples of length `D`). A spherical domain uses their midpoint as center and half the first extent as radius.
`:periodic`	`false`	`Bool` or `NTuple{D, Bool}`.
`:bc`	none	Boundary conditions: `Dict(tag => bc)` where `bc` is an `AbstractBoundaryCondition`, `:outflow`, `:fixed_dirichlet`, or the name of a zero-argument constructor (looked up in HyperCloudCore, then in `Main`; see `parse_bc`). A string is parsed as Julia code.
`:Ns`	—	Particles per direction (tuple). The nominal spacing is `(maxs - mins) ./ Ns`.
`:randomness_factor`	—	Jitter per direction as a fraction of the spacing (tuple).
`:seed`	`42`	RNG seed for the jitter.
`:mover`	`:none`	Grid motion: `:none`, `:lagrangian`, `:scaled_lagrangian` (factor `:mover_alpha`) or `:sinusoidal` (amplitude `:mover_amplitude`); see Moving Grids. Lagrangian movers need `fluid_velocity` for the equation; all built-in equations define it.
`:volumes`	`:shepard`	Particle volume estimator: `:shepard` (`:volumes_sweeps`) or `:mls` (`:volumes_degree`, `:volumes_samples_per_dx`); see Particle Volumes.

The key is `:Grid_bc`

Boundary conditions are read from :Grid_bc. A key such as :Grid_bc_map is silently ignored.

`Weight_` — MLS weight function

Key	Meaning
`:name`	`:exponential` or `:inverse`. Required.
`:range`	Support radius in multiples of the largest grid spacing. Required. High reconstruction orders need a larger range (the examples use `5.5`).
`:alpha`	Shape parameter of the weight. Required.

`IC_` — initial condition

:name selects the initial condition; every other key is converted to the simulation type T.

`:name`	Type	Keys
`:gauss`	`Gauss`	`:a` (amplitude, length `M`), `:b` (center, length `D`), `:width`
`:box`	`Box`	`:u_bg`, `:u_box` (length `M`), `:mins`, `:maxs` (length `D`)
`:sine`	`Sine`	`:a`, `:c_offset` (length `M`), `:period` (length `D`)
`:riemann`	`Riemann`	`:uL`, `:uR` (length `M`), `:p0` (length `D`), `:n` (optional, default `+x`, normalized)
`:s_riemann`	`SRiemann`	as `:riemann`, plus `:width`
`:q_riemann`	`QRiemann`	`:states` (tuple of `2^D` states, binary ordering), `:p0`

States are given in the variables the equation evolves. For Euler these are the conservative variables $(\rho, \rho\vec u, E)$.

`Scheme_` — spatial discretization

Key	Default	Meaning
`:name`	—	`:MUSCL`, `:Upwind`, `:Central` or `:WENO`. Required.
`:order`	—	Consistency order (expected convergence rate; MUSCL reconstructs with degree `order - 1`). `:Upwind` only supports `1`, `:WENO` needs at least `2`.
`:MLS_order`	`0`	Fixed order of the MLS divergence operator; `0` follows each particle's current order.
`:upwind_alg_nd`	—	`:Upwind` only: `:Classic` (any system), `:Tiwari` (scalar) or `:Praveen` (scalar, 2D).

The schemes are described in HyperCloudCore: MUSCL, Upwind, Central and WENO (scalar equations only).

`Flux_`, `Limiter_`, `MOOD_`

Key	Default	Meaning
`:Flux_name`	—	`:Rusanov` or `:Upwind`. Required.
`:Limiter_name`	`:none`	`:none`, `:minmod`, `:superbee`, `:VK` (Venkatakrishnan), `:BJ` (Barth–Jespersen).
`:Limiter_mode`	—	Required by every active limiter, e.g. `:hard`.
`:MOOD_criterion`	`:none`	`:none`, `:only`, `:U1`, `:U2`.
`:MOOD_strategy`	`:none`	`:EPD0`, `:SEPD0`, `:EPD1`, `:EPD2`. Required when a criterion is set.
`:MOOD_delta_relax`	—	Required by `:U1`/`:U2`. Multiplied by the cell volume `prod(dx)`.

See HyperCloudCore's Numerical Flux Functions, the limiters and MOOD for what the options do.

`Time_` — time stepping

Key	Meaning
`:stepper`	Explicit: `:Euler`, `:RK2` (SSP), `:RK2Ralston`, `:RK3` (SSP), `:RK4` (classical). IMEX: `:IMEXEuler`, `:ARS222`, `:ARS233`, `:PRSSP3`, `:SSP332`.
`:CFL`	CFL number; the step is recomputed every iteration. It is not a classical Courant number, see what the CFL number means on a point cloud.
`:dt`	Fixed time step, used when `:CFL` is absent.
`:tmax`	Optional override of the global `:tmax`.
`:reset_orders_per_stage`	`true` restores the maximum order before every stage (default `false`: orders lowered by MOOD stay lowered for the step).
`:full_search_per_stage`	`true` rebuilds the neighbour lists at every stage of a moving grid (default `false`).

IMEX steppers treat the source terms implicitly and are used with the kinetic pipeline. See HyperCloudCore's Butcher Tableaus for the properties of each tableau.

`Adapt_` — particle insertion and merging

Optional; mainly for Lagrangian grids. See Particle insertion and merging.

Key	Default	Meaning
`:enabled`	`false`	Insert and merge particles between time steps.
`:max_gap`, `:min_gap`	`1.6`, `0.5`	Pair distances (in units of the spacing) above which a particle is inserted and below which a pair is merged.
`:clearance`	`0.7`	Free radius required around an insertion point.
`:samples_per_dx`	`2`	Lattice resolution of the conservative remap.
`:exclude_reduced_order`	`true`	No events near particles whose MOOD order was lowered.

The number of particles at the end is stored in the statistic final_particle_count.

`Kinetic_` — relaxation system

Only read by run_kinetic_simulation.

Key	Default	Meaning
`:velocities`	—	Kinetic speeds, one `NK`-tuple per dimension. Use `generate_relax_params`.
`:indices`	—	`Vector{Int}` of edges mapping kinetic to macroscopic variables (see `Kin2Macro`).
`:epsilon`	—	Relaxation time $\epsilon$.
`:interior_factor`	`D`	Scaling of the inverse kinetic speeds in the Maxwellian.
`:save_relax`	`false`	Same as the global key.

Complete example

using HyperCloud, StaticArrays

vels, idx = generate_relax_params(2.0, 1, 1)

params = Dict{Symbol, Any}(
    :sim_func_name => :run_kinetic_simulation,
    :tmax => 0.5, :snapshots => 10,

    :PDE_name => :burgers, :PDE_D => 1,

    :Grid_domain => :rectangular, :Grid_mins => (-1.0,), :Grid_maxs => (1.0,),
    :Grid_periodic => true, :Grid_Ns => (200,),
    :Grid_randomness_factor => (0.2,), :Grid_seed => 10,

    :Weight_name => :exponential, :Weight_alpha => 1.0, :Weight_range => 5.5,

    :IC_name => :gauss, :IC_a => (1.0,), :IC_b => (0.0,), :IC_width => 0.5,

    :Scheme_name => :MUSCL, :Scheme_order => 2,
    :Flux_name => :Rusanov, :Limiter_name => :none,
    :MOOD_criterion => :U2, :MOOD_strategy => :EPD1, :MOOD_delta_relax => 1e-4,

    :Time_stepper => :ARS222, :Time_CFL => 0.2,

    :Kinetic_velocities => vels, :Kinetic_indices => idx, :Kinetic_epsilon => 1e-6,
)

sim = run_kinetic_simulation(params)   # `nothing` if anything failed (the error is logged)
exact = analytical_solution(params)
exact(SVector(0.3, 0.5))               # exact state at x = 0.3, t = 0.5