adam_flume_common_object

ADAM, FLUME common object: data and methods shared by all backends.

flume_common_object extends the library realm_object (which owns grid, tree, field, maps, IO, AMR, IB, RK and WENO objects) with the FLUME physics layer. The backends (flume_cpu_object, flume_fnl_object) extend it and implement the forest contract. Initialization order (issue #35, section 6.1): IO, numerics, physics (decides nv), blocks budget with the real per-block fields count, realm, BCs (before the first map build, so periodicity is seen by the tree), time, IC, diagnostics, fields allocation, uniform refinement.

Source: src/app/flume/common/adam_flume_common_object.F90

Dependencies

Contents

• flume_common_object
• amr_update
• mark_by_geometry
• mark_by_gradient
• mark_by_solid
• mark_by_lohner
• mark_runtime
• check_regridded_state
• accumulate_seam_skin
• add_seam_gravity_work
• allocate_common
• compute_phi
• compute_fields_number
• destroy_common
• initialize
• report_divb
• log_dt_limit
• report_glm_speed
• stop_nonfinite
• load_restart_files
• save_restart_files
• save_xh5f
• set_divb_seam
• set_potential
• solve_potential
• solve_potential_packed
• set_glm_damping
• save_slices
• coupling_descriptor_forest
• seam_skin_cell
• check_slices
• compute_mhd_derived
• compute_q_aux_host
• check_ngc_number
• check_positivity_limiter
• check_gravity
• log_gravity_regime
• log_self_gravity
• check_dissipation
• check_runtime_amr
• check_divb_flux
• check_weno_scheme
• initialize_riemann_scheme
• io_initialize
• is_regrid_step
• glm_lambda
• output_factors
• output_names
• null_freeze
• wall_temperature_bound
• nonfinite_total
• ib_cut_spacing
• refinement_by_spacing
• reflux_positivity_theta
• reflux_internal_energy
• block_spacing
• poisson_iterations
• runtime_amr_forest

Variables

Name	Type	Attributes	Description
SCHEME_TIME_TAG	character(len=11)	parameter	Time-integration family tag (forest admissibility).
MHD_DERIVED_NAME	character(len=4)	parameter	MHD derived fields names.

Derived Types

flume_common_object

FLUME common object: data and methods shared by all backends.

Inheritance

Extends: realm_object

Components

Name	Type	Attributes	Description
io	type(io_object)		IO handler.
amr	type(amr_object)		AMR marker handler.
slices	type(slices_object)		Slices handler.
blanesmoan	type(blanesmoan_object)		Blanes-Moan integrator.
cfm	type(cfm_object)		Commutator-Free Magnus integrator.
leapfrog	type(leapfrog_object)		Leapfrog integrator.
flail	type(flail_object)		Linear algebra methods handler.
weno	type(weno_object)		WENO reconstructor.
ib	type(ib_object)		Immersed boundary.
rk	type(rk_object)		Runge-Kutta integrator.
adam	type(adam_object)		ADAM, grid + tree + field + maps orchestrator.
fdv_scheme	character(len=:)	allocatable	FDV scheme, fd/fv.
fdv_order	integer(kind=I4P)		Order of finite difference/volume schemes, general order.
fdv_half_stencil	integer(kind=I4P)		Half stencil length of finite difference/volume schemes.
fdv_half_stencils	integer(kind=I4P)		Half stencil length of fdv schemes for each derivative up to 6.
ngc	integer(kind=I4P)	pointer	Number of ghost cells.
ni	integer(kind=I4P)	pointer	Number of cells in i direction.
nj	integer(kind=I4P)	pointer	Number of cells in j direction.
nk	integer(kind=I4P)	pointer	Number of cells in k direction.
nb	integer(kind=I4P)	pointer	Total blocks number for MPI.
blocks_number	integer(kind=I4P)	pointer	Actual blocks number.
nv	integer(kind=I4P)	pointer	Number of variables in q vector.
realm_index	integer(kind=I4P)		Inter-realm seam coupling — currently-published stage buffer key.
stage_active	integer(kind=I4P)		A copy of the forest's flux register (its faces and lookup, the accumulators unused), refreshed by the forest each
flux_register_copy	type(flux_register_object)		Procedure pointer TBPs for FDV operators (set at initialization by backend).
compute_block_total_variation	procedure(compute_block_total_variation_interface)	pass(self), pointer	Compute TV.
compute_curl	procedure(compute_curl_interface)	pass(self), pointer	Compute curl.
compute_curl_extended	procedure(compute_curl_interface)	pass(self), pointer	Compute curl on extended support.
compute_derivative1	procedure(compute_derivative1_interface)	pass(self), pointer	Compute deriv1.
compute_derivative2	procedure(compute_derivative2_interface)	pass(self), pointer	Compute deriv2.
compute_derivative4	procedure(compute_derivative4_interface)	pass(self), pointer	Compute deriv4.
compute_divergence	procedure(compute_divergence_interface)	pass(self), pointer	Compute dive.
compute_gradient	procedure(compute_gradient_interface)	pass(self), pointer	Compute grad.
compute_gradient_extended	procedure(compute_gradient_interface)	pass(self), pointer	Compute gradient on extended support.
compute_laplacian	procedure(compute_laplacian_interface)	pass(self), pointer	Compute laplac.
amr_locked_	logical		Runtime AMR locked after initialization.
save_auxiliary_fields	logical		Save the auxiliary variables with the fields.
glm_speed_reported	real(kind=R8P)		Largest wave speed above c_h reported so far.
divb_reported	real(kind=R8P)		Largest monitored measure above divb_tol reported so far.
divb_seam	integer(kind=I4P)	allocatable	Seam faces flags of the div(B) history [nb, 6].
q	real(kind=R8P)	allocatable	Conservative variables [nv, 1-ngc:ni+ngc, ..., nb].
dq	real(kind=R8P)	allocatable	Residuals [nv, 1-ngc:ni+ngc, ..., nb].
q_aux	real(kind=R8P)	allocatable	Auxiliary variables [nv_aux, 1-ngc:ni+ngc, ..., nb].
phi_grav	real(kind=R8P)	allocatable	Gravitational potential [1-ngc:ni+ngc, ..., nb] (issue #81);
poisson	class(poisson_fft_object)	allocatable	Self-gravity Poisson solver (issue #81; FNL: the cuFFT one).
poisson_mg	type(poisson_mg_object)	allocatable	Self-gravity on AMR grids (issue #81, P5b): the multigrid
poisson_wall	real(kind=R8P)		Wall time of the last Poisson solve (s).
q_name	type(string)	allocatable	Conservative variables names.
dq_name	type(string)	allocatable	Residuals names.
q_aux_name	type(string)	allocatable	Auxiliary variables names.
bc	type(flume_bc_object)		Boundary conditions.
diagnostics	type(flume_diagnostics_object)		Diagnostics.
ic	type(flume_ic_object)		Initial conditions.
numerics	type(flume_numerics_object)		Numerics.
physics	type(flume_physics_object)		Physics.
units	type(flume_reference_object)		Reference layer (dimensional input, issue #49).
time	type(flume_time_object)		Time handler.

Type-Bound Procedures

Name	Attributes	Description
load_fdv_from_file	pass(self)	Load FDV config from file.
initialize_forest	pass(self)	Invoked by forest%initialize per realm at startup.
compute_local_dt_forest	pass(self)	Invoked by forest%compute_global_dt during the min reduction.
advance_one_step_forest	pass(self)	Invoked by forest%evolve_one_step per realm per timestep.
stages_per_step_forest	pass(self)	Number of integrator stages this realm exposes per step.
open_step_forest	pass(self)	Per-step prologue (multi-realm path).
begin_stage_forest	pass(self)	Begin one integrator stage on this realm (multi-realm path).
end_stage_forest	pass(self)	End the stage: residuals + assignment (multi-realm path).
close_step_forest	pass(self)	Per-step epilogue (multi-realm path).
post_step_forest	pass(self)	Invoked by forest%post_step per realm per timestep.
regrid_forest	pass(self)	Invoked by forest%regrid per realm per timestep (#74).
is_done_forest	pass(self)	Invoked by forest%is_done during the termination reduction.
finalize_forest	pass(self)	Invoked by forest%finalize per realm at shutdown.
finalize_mpi_forest	pass(self)	Process-global MPI finalize; forest calls it ONCE after all.
fill_seam_from_peer_forest	pass(self)	Receive-side roundtrip: copy peer's interior into self's ghosts.
pack_seam_cells_forest	pass(self)	Pack own cells of the cross-rank seam send rows.
unpack_seam_cells_forest	pass(self)	Unpack the cross-rank seam receive rows into own ghosts.
after_topology_build_forest	pass(self)	Backend hook invoked once after the forest builds the seam maps.
apply_reflux_to_stage_forest	pass(self)	Apply Berger-Colella reflux to self's stage buffer.
close_block_xh5f	nopass	Close XH5F file block.
close_file_xh5f	nopass	Close XH5F file.
open_block_xh5f	pass(self)	Open block file XH5F.
open_file_xh5f	pass(self)	Open file XH5F.
save_q_xh5f	pass(self)	Save in XH5F (XDMF/HDF5) format.
compute_curl_fd_extended	pass(self)	Compute curl of vector field, finite difference, even for half gcs.
compute_gradient_fd_extended	pass(self)	Compute gradient of scalar field, finite difference, even for half
amr_update	pass(self)	Do AMR update (initialization-time only).
runtime_amr_forest	pass(self)	Whether this realm regrids during the run (issue #74).
mark_by_geometry	pass(self)	Mark blocks to be refined by a primitive geometric box.
mark_by_gradient	pass(self)	Mark blocks by the gradient of a conservative or auxiliary variable.
mark_by_solid	pass(self)	Mark blocks crossed by the surface of an immersed solid.
mark_by_lohner	pass(self)	Mark blocks by the Loehner estimator of a variable (issue #74).
mark_runtime	pass(self)	Combine the markers into the flags of a runtime regrid (issue #74).
check_regridded_state	pass(self)	Stop on an inadmissible state after a regrid (issue #74).
is_regrid_step	pass(self)	Whether the step just closed is a runtime regrid step (issue #74).
accumulate_seam_skin	pass(self)	Route one weighted seam face skin to the forest's flux register.
add_seam_gravity_work	pass(self)	Add the seam gravity work of self-gravity to a seam skin.
allocate_common	pass(self)	Allocate common data.
compute_fields_number	pass(self)	Compute the block-sized fields allocated per block.
compute_phi	pass(self)	Compute the immersed solids distance function (host).
destroy_common	pass(self)	Free common data.
glm_lambda	pass(self)	Return the GLM bound of the local dt, c_h max sum_d 1/dx_d.
initialize	pass(self)	Initialize the common data.
log_dt_limit	pass(self)	Log which limit, hyperbolic or diffusive, sets dt.
log_gravity_regime	pass(self)	Log the velocity gravity adds in a step (issue #73).
log_self_gravity	pass(self)	Log the self-gravity regime (issue #81).
poisson_iterations	pass(self)	FCG iterations of the last multigrid solve.
wall_temperature_bound	pass(self)	Return the hottest isothermal wall temperature of the dt bound.
null_freeze	pass(self)	Return the variable each null direction freezes.
output_factors	pass(self)	Return the output factors of written variables.
output_names	pass(self)	Return the names of every written variable.
report_divb	pass(self)	Reduce and save the div(B) norms, apply the divb_tol monitor.
report_glm_speed	pass(self)	Check c_h against the fastest wave (warning or stop).
nonfinite_total	pass(self)	Sum the non-finite values count over the ranks.
stop_nonfinite	pass(self)	Stop on a non-finite state, locating it on every rank.
load_restart_files	pass(self)	Load restart files.
save_restart_files	pass(self)	Save restart files.
save_slices	pass(self)	Save the slices on their cadence.
save_xh5f	pass(self)	Save fields in XH5F format.
set_divb_seam	pass(self)	Set the seam faces flags of the div(B) history.
set_glm_damping	pass(self)	Set the GLM damping once the grid exists.
set_potential	pass(self)	Set the gravitational potential of the current grid.
solve_potential	pass(self)	Solve the self-gravity potential of a host state.
solve_potential_packed	pass(self)	Solve the self-gravity potential of a packed density.
coupling_descriptor_forest	pass(self)	Return the realm coupling descriptor.
block_spacing	pass(self)	Return the spacing of a block by a delta criterion.
check_ngc_number	pass(self)	Check the ghost cells number against the stencils.
check_dissipation	pass(self)	Refuse the dissipative terms not implemented yet.
check_runtime_amr	pass(self)	Check [amr] frequency, default the prolongation (#74).
check_divb_flux	pass(self)	Check [diagnostics] divb_flux (#68 A2).
check_positivity_limiter	pass(self)	Refuse the limiter where it cannot work.
check_gravity	pass(self)	Refuse gravity where it is not defined (issue #73).
check_slices	pass(self)	Check the slices interpolation types.
check_weno_scheme	pass(self)	Refuse the centred WENO schemes.
initialize_riemann_scheme	pass(self)	Check and set up the weno-riemann scheme.
compute_mhd_derived	pass(self)	Compute the MHD derived output fields of one block.
compute_q_aux_host	pass(self)	Compute the auxiliary variables of the host q.
io_initialize	pass(self)	Build the variables names.

Subroutines

amr_update

Do AMR update: amr%iters sweeps over the markers until the grid stabilizes (initialization-time only). The gradient marker reads the ghosts of the internal block faces, refreshed on the host before it (issue #76); the Loehner marker is skipped: it also reads the ghosts of the physical faces, whose boundary conditions only the backends apply; it acts at the runtime regrids (mark_runtime, issue #74).

subroutine amr_update(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

mark_by_geometry

Mark blocks to be refined by a primitive axis-aligned box (deterministic, solution-independent).

A block is flagged TO_BE_REFINED iff its centroid lies inside [box_emin, box_emax] and its refinement level is below target_level; every other block is left untouched (the marker is additive).

subroutine mark_by_geometry(self, box_emin, box_emax, target_level, do_init)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
box_emin	real(kind=R8P)	in		Box minimum corner.
box_emax	real(kind=R8P)	in		Box maximum corner.
target_level	integer(kind=I4P)	in		Refine blocks below this level.
do_init	logical	in	optional	Re-initialize refinements queries.

Call graph

mark_by_gradient

Mark blocks by the gradient magnitude of a conservative (field = 1) or auxiliary (field = 2) variable.

CHASE semantics: the admissible cell spacing of a block is delta_fine where max |grad var| > tol, else delta_coarse; a block coarser than admissible is refined, a block whose parent (spacing doubled) would still be admissible is derefined, any other block is left untouched. The spacing of a block is chosen by delta_type (x, y, z or max). The gradient is centred, across the block faces too: a jump lying on an internal face (between two blocks, or periodic) is seen by the cells on both sides of it (issue #76: with interior-only differences each block saw a constant state up to the face, and Sod on [0, 1], its jump on a block face at every level, was never refined there). It is one-sided at the faces on the realm boundary (physical or seam), whose ghosts it never reads. The caller refreshes the ghosts of the internal faces: the initial AMR on the host (amr_update), the runtime regrids with the backend's full ghost update (regrid_forest).

subroutine mark_by_gradient(self, field, ivar, tol, delta_type, delta_fine, delta_coarse)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
field	integer(kind=I4P)	in		Marker field: 1 conservative, 2 auxiliary variables.
ivar	integer(kind=I4P)	in		Variable index in the marker field.
tol	real(kind=R8P)	in		Gradient magnitude tolerance.
delta_type	character(len=*)	in		Block spacing criterion: x, y, z, max.
delta_fine	real(kind=R8P)	in		Admissible spacing where the gradient exceeds tol.
delta_coarse	real(kind=R8P)	in		Admissible spacing elsewhere.

Call graph

mark_by_solid

Mark blocks by the surface of immersed solid solid: CHASE semantics, with the refine/derefine rule of the gradient marker.

A block is crossed by the surface when its distance function (interior and ghost cells) changes sign; its admissible spacing is then delta_fine, delta_coarse otherwise. The distance function must be current (the caller computes it on the present grid). A run without solids, or a solid index out of range, is fatal (CHASE read phi unallocated in that case, issue #35 C-8).

subroutine mark_by_solid(self, solid, delta_type, delta_fine, delta_coarse)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
solid	integer(kind=I4P)	in		Solid index.
delta_type	character(len=*)	in		Block spacing criterion: x, y, z, max.
delta_fine	real(kind=R8P)	in		Admissible spacing across the surface.
delta_coarse	real(kind=R8P)	in		Admissible spacing elsewhere.

Call graph

mark_by_lohner

Mark blocks by the Loehner (1987) estimator of a conservative (field = 1) or auxiliary (field = 2) variable (issue #74, D-M5-8).

The dimension-sum form of FLASH and PLUTO: on a cell, E = sqrt(sum_d N_d^2 / sum_d D_d^2) over the active directions, N_d = |u_+ - 2 u + u_-| and D_d = |u_+ - u| + |u - u_-| + epsilon (|u_+| + 2 |u| + |u_-|) + floor, with u_+- the neighbours along d. E lies in [0, 1], independent of the scale of u and of the cell size: about 0 where u is smooth on the grid, about 1 at a jump; epsilon keeps ripples small relative to u from triggering. On a variable that vanishes in quiet regions (the field outside a magnetic loop) that filter filters nothing: round-off noise is all there is, and it reads E ~ 1; floor, an absolute variation (default 0, the FLASH/PLUTO form), turns the variations well below it into noise (#74 P4). A block takes the largest E over its interior cells and buffer ghost layers (a feature at a neighbour's edge marks this block too): refined above refine_tol, derefined below derefine_tol, untouched between (the hysteresis band keeps a block near the threshold from flipping at every regrid). The caller refreshes the ghost cells of q.

subroutine mark_by_lohner(self, field, ivar, refine_tol, derefine_tol, epsilon, floor, buffer)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
field	integer(kind=I4P)	in		Marker field: 1 conservative, 2 auxiliary variables.
ivar	integer(kind=I4P)	in		Variable index in the marker field.
refine_tol	real(kind=R8P)	in		Refine above this estimator value.
derefine_tol	real(kind=R8P)	in		Derefine below this estimator value.
epsilon	real(kind=R8P)	in		Noise filter, relative to the variable.
floor	real(kind=R8P)	in		Noise filter, absolute variation.
buffer	integer(kind=I4P)	in		Ghost layers the estimator reads.

Call graph

mark_runtime

Combine the markers into the flags of a runtime regrid (issue #74, D-M5-8).

Each marker votes per block: refine, keep (untouched) or derefine. A block is refined when any marker asks for it, derefined only when every marker agrees, untouched otherwise; a block at the base level (iu_ref_levels, the uniform level of the initial grid) is never derefined. The geometric box votes refine inside the box below its target level, keep inside at the target level, derefine elsewhere (outside the box, or inside above the target): as a vote it must not pin the grid outside its box, as it would if "untouched" vetoed the other markers there. The initial AMR (amr_update) is unchanged: there the markers act one after the other. The caller refreshes the ghost cells of q (the Loehner marker and the solid marker read them).

subroutine mark_runtime(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

check_regridded_state

Stop on an inadmissible state after a runtime regrid (issue #74): density or pressure not positive on an interior cell. The conservative prolongation keeps every conserved variable in the range of its stencil, so the density stays positive, but the pressure is a nonlinear function of the conserved variables and a child of a cell next to a strong jump can lose it; the run is stopped here, at its cause, rather than later at a non-finite flux.

subroutine check_regridded_state(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

accumulate_seam_skin

Route one seam face skin of block b, face fec, weighted by weight, to the forest's flux register.

Shared by the backends (the register is host-side): the CPU packs skin from its face fluxes, the FNL backend packs it on the device and copies it to the host. skin(v, c) is the face flux with the cell index c running over the two tangential axes, inner fastest (x faces: j, k; y faces: i, k; z faces: i, j), the register order. Coarse side (positive register index): the skin is the coarse face. Fine side (negative index): on an intra-realm AMR seam the skin is 2:1-restricted (2x2 average; 2x1 across the unrefined z of a quadtree, issue #46) into this block's quadrant of the coarse face, the quadrant offset precomputed by the forest from the Morton codes (maps%amr_seam_quadrant); on an inter-realm mirror seam (same resolution) it is accumulated unrestricted into the register faces it overlaps (maps%seam_overlap, issue #51: the blocks of the two realms need not line up; one full-skin overlap when they do).

FLUME weighs every stage by its SSP coefficient, weight = beta_s: the register then holds the flux of the whole step, sum_s beta_s F_s, exactly the flux the committed update q + dt sum_s beta_s dq_s used, and the end-of-step correction restores conservation to round-off (issue #35, P5; AMReX non-subcycled flux register).

subroutine accumulate_seam_skin(self, flux_register, b, fec, weight, skin)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
flux_register	class(flux_register_object)	inout		Forest's flux register.
b	integer(kind=I4P)	in		Block index.
fec	integer(kind=I4P)	in		Face (1..6: -x, +x, -y, +y, -z, +z).
weight	real(kind=R8P)	in		Stage weight.
skin	real(kind=R8P)	in		Face skin (nv, inner_n*outer_n).

Call graph

add_seam_gravity_work

Add the gravity work of self-gravity across a 2:1 AMR seam to the energy row of a seam skin (issue #81, P5b), so that the end-of-step reflux makes E + W telescope exactly at the seam.

The potential sources give each cell 1/2 g F per face (add_potential_sources), g its own face gravity and F the face mass flux. The mass update moves A_f F_f across every fine sub-face f of a coarse face, which changes W by s A_f F_f (Phi_f - Phi_C) (s = +1 when the fine side lies at +axis of the coarse cell C), so exact E + W needs the seam's energy sources to sum to s sum_f A_f F_f (Phi_C - Phi_f); the two kernels give instead the multigrid's mean-flux gravity ((mean_f - Phi_C) / (1.5 h) on both sides). The difference rides on the register's energy entry, which the reflux turns into sgn (G_coarse - G_fine) / H in the coarse cell:

• coarse skin: G_c = -s 1/2 g_c F_c H (takes the coarse cell's own seam source back);
• fine skin: G_f = -F_f (Phi_C - Phi_f) + s 1/2 g_f F_f h (the exact two-point work, less the fine cell's own source, which stays: the fine cells keep the consistent gravity). The fine side recovers Phi_C from its ghost, Phi_C = mean_f - 1.5 (Phi_f - Phi_ghost) (the multigrid's ghost fill), mean_f the mean of the fine skin cells of the coarse face. Every term is per stage, weighted with the fluxes, so the identity holds stage by stage. Exact only where the reflux corrects every seam cell (not under the troubled reflux policy) and the positivity limiter does not act (its gravity energy correction, M7).

subroutine add_seam_gravity_work(self, flux_register, b, fec, skin)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
flux_register	class(flux_register_object)	in		Forest's flux register.
b	integer(kind=I4P)	in		Block index.
fec	integer(kind=I4P)	in		Face (1..6: -x, +x, -y, +y, -z, +z).
skin	real(kind=R8P)	inout		Face skin (nv, inner_n*outer_n).

Call graph

allocate_common

Allocate common data.

subroutine allocate_common(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

compute_phi

Compute the distance function of the immersed solids on the host (a no-op without solids); the solids are static, so the backends compute it once per grid (initialization, restart, initial AMR).

subroutine compute_phi(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

compute_fields_number

Compute the block-sized fields FLUME allocates per block, the fields_number of the blocks budget.

Both backends allocate the same nb-sized arrays, on the host (CPU) or on the device (FNL): q, dq (2 nv), q_aux (nv_aux), the three face fluxes (3 nv, counted as full block fields) and the Runge-Kutta stages (rk_stored_stages_number nv), plus the positivity limiter's cell factors (nv, q-shaped for the ghost exchange), the fourth-order gravity energy correction (1, every run, issue #73 M7-G2a), the equilibrium residual of the well-balanced mode (nv, M7-G2b) and the gravitational potential (1, issue #81). Requires physics and numerics initialized.

subroutine compute_fields_number(self, file_parameters, fields_number)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
file_parameters	type(file_ini)	in		Simulation parameters ini file handler.
fields_number	integer(kind=I4P)	out		Block-sized fields allocated per block.

Call graph

destroy_common

Free common data.

subroutine destroy_common(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

initialize

Initialize the common data (issue #35, section 6.1, step 3).

subroutine initialize(self, filename, memory_avail, nv, fields_number, verbose, L0)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout	target	The equation.
filename	character(len=*)	in		Input file name.
memory_avail	real(kind=R8P)	in	value	Memory available for single MPI process.
nv	integer(kind=I4P)	in	optional	Unused: nv is decided by the physics.
fields_number	integer(kind=I4P)	in	optional	Block-sized fields per block (default: computed).
verbose	logical	in	optional	Trigger verbose output.
L0	real(kind=R8P)	in	optional	Unused: FLUME is dimensional.

Call graph

report_divb

Reduce the div(B) norms of this rank over all ranks, save the div(B) history row and apply the monitor (issue #41, D-10; on the normalised D_flux since issue #68 G1): max h|D_flux| / max|B| > [mhd].(divb_tol) (> 0) is fatal with divb_error, otherwise a warning logged by rank 0 each time the measure exceeds the largest one reported so far. The D_flux norms come with [diagnostics] divb_flux, which divb_tol > 0 requires (check_divb_flux).

subroutine report_divb(self, norms)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
norms	real(kind=R8P)	in		This rank's max|div B|, sum |div B| dV, seam-local

Call graph

log_dt_limit

Log, once per run (rank 0, all ranks reduce), whether the time step is limited by the hyperbolic or by the diffusive part of dt = CFL / max(lambda_hyp + lambda_dif) (issue #65, D-M4-3), with the minimum cell Reynolds number.

subroutine log_dt_limit(self, lambda_hyp, lambda_dif, re_cell_min)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
lambda_hyp	real(kind=R8P)	in		Maximum of the hyperbolic part of this rank.
lambda_dif	real(kind=R8P)	in		Maximum of the diffusive part of this rank.
re_cell_min	real(kind=R8P)	in		Minimum cell Reynolds number of this rank.

Call graph

report_glm_speed

Check the GLM cleaning speed against the fastest wave (issue #41, section 3.5, D-9): max(|u_d| + c_{f,d}) > c_h is fatal with [mhd].(glm_ch_check) = error, otherwise a warning logged by rank 0 each time the speed exceeds the largest one reported so far (GLM stays stable, dt includes c_h, but the cleaning is slower than the fastest wave).

subroutine report_glm_speed(self, speed_max)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
speed_max	real(kind=R8P)	in		Fastest wave speed of this rank.

Call graph

stop_nonfinite

Stop the run on a non-finite (NaN or infinite) committed state (issue #45), reporting on every rank the first non-finite value of the host q (the caller has made it current): block Morton code, cell centre, variable. Every rank calls it after the reduction, so the stop is collective (the first error_stop aborts the others, #43).

subroutine stop_nonfinite(self, n_total)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
n_total	integer(kind=I8P)	in		Non-finite values number of all ranks.

Call graph

load_restart_files

Load restart files.

subroutine load_restart_files(self, t, time)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
t	integer(kind=I4P)	out		Time iteration.
time	real(kind=R8P)	out		Time.

Call graph

save_restart_files

Save restart files.

subroutine save_restart_files(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

save_xh5f

Save fields in XH5F format: q always, dq when [IO].(save_residual_fields), the auxiliary variables (computed from the saved q, ghost cells included) when [IO].(save_auxiliary_fields). With [reference] output_units = dimensional every field, the grid and the time are multiplied by their output factors (a scaled copy of each block, the state itself is untouched).

subroutine save_xh5f(self, output_basename, with_ghost)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
output_basename	character(len=*)	in	optional	Output basename.
with_ghost	logical	in	optional	Flag to save ghost cells.

Call graph

set_divb_seam

Set the seam faces flags of the div(B) history (issue #41, D-10): a block face is a seam face when the forest registered it in the flux register (a 2:1 AMR or inter-realm seam, inter_realm_face_register_index /= 0). Sized by the block capacity nb, as every block-indexed device array: on a rank that owns no block (blocks_number = 0) a blocks_number-sized array is empty and its device copy (FNL) a zero-byte allocation, which the device allocator returns as a null pointer and FUNDAL reports as failed (issue #82). The rows past blocks_number stay 0 and are never read.

subroutine set_divb_seam(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

set_potential

Set the gravitational potential of the current grid, ghost cells included (issue #81, M8-P1). With [gravity] potential = linear it is Phi = -g . x at the cell centres, the constant field written as a potential; with self_gravity (M8-P3) the Poisson solver is set up on the current grid and Phi is solved from the host state q: on a uniform grid the FFT solver (periodic or isolated), on an AMR grid (leaves at more than one level, P5b) the multigrid solver, its coarsest level solved by the FFT solver of the backend, periodic or isolated (the symmetric James step, issue #87: every leaf on the domain boundary at the coarsest level, which a regrid that refines a boundary block breaks, fatal in the solver's initialize, D-87-4); without a potential the array is a one-cell placeholder (the kernels take it and do not read it). Sized by the block capacity nb, as the other block arrays; call it after the initial grid and after every regrid.

subroutine set_potential(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

solve_potential

Solve the self-gravity potential of the host state q (issue #81, M8-P3): L_h Phi = 4 pi G (rho - mean rho), every ghost layer filled (the FFT solver's wrap, or the multigrid's ghost fill on AMR), the wall time kept in poisson_wall; optionally the energy sum_cells rho Phi dV (every rank). The FNL backend solves from the device state with solve_potential_gpu, through solve_potential_packed.

subroutine solve_potential(self, q, energy)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
q	real(kind=R8P)	in		State.
energy	real(kind=R8P)	out	optional	sum_cells rho Phi dV.

Call graph

solve_potential_packed

Solve the self-gravity potential from the packed interior density of the active blocks (block-major, i fastest), into phi_grav with every ghost filled (issue #81): the FNL backend's host step. Optionally the energy sum_cells rho Phi dV (every rank).

subroutine solve_potential_packed(self, buf, energy)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.
buf	real(kind=R8P)	in		Packed density.
energy	real(kind=R8P)	out	optional	sum_cells rho Phi dV.

Call graph

set_glm_damping

Set the GLM damping once the grid exists (issue #41, section 3.5): the minimum cell spacing of the realm over the active directions (MPI-reduced) is the min-cell damping length. With runtime regridding ([amr] frequency > 0, issue #74) it is the spacing of the finest level allowed ([amr] max_level), fixed for the run whatever the grid holds. A no-op without GLM.

subroutine set_glm_damping(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

save_slices

Save the slices (library slices_object, [slices] / [slice_N]) of the conservative variables on their cadence; the caller has refreshed the ghost cells of the host q (the interpolation stencils read them).

subroutine save_slices(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

coupling_descriptor_forest

Return the realm coupling descriptor checked by the forest for stage-coincident admissibility.

subroutine coupling_descriptor_forest(self, scheme_time, rk_scheme, nv)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
scheme_time	character(len=:)	out	allocatable	Time-integration family tag.
rk_scheme	character(len=:)	out	allocatable	Within-family scheme tag.
nv	integer(kind=I4P)	out		Number of conserved variables on this realm.

Call graph

seam_skin_cell

Return the interior cell (i, j, k) of skin cell c on the face of normal axis and side sgn (register order, inner tangential axis fastest). Shared by the host and device reflux applications.

Attributes: pure

subroutine seam_skin_cell(axis, sgn, ni, nj, nk, c, i, j, k)

Arguments

Name	Type	Intent	Attributes	Description
axis	integer(kind=I4P)	in		Face normal axis, 1..3.
sgn	integer(kind=I4P)	in		Face side, +1 maximum, -1 minimum.
ni	integer(kind=I4P)	in		Grid dimensions.
nj	integer(kind=I4P)	in		Grid dimensions.
nk	integer(kind=I4P)	in		Grid dimensions.
c	integer(kind=I4P)	in		Skin cell index.
i	integer(kind=I4P)	out		Interior cell (0 on a malformed axis).
j	integer(kind=I4P)	out		Interior cell (0 on a malformed axis).
k	integer(kind=I4P)	out		Interior cell (0 on a malformed axis).

Call graph

check_slices

Check the interpolation type of every slice: the library interpolation leaves the value undefined for an unknown type, so an unknown one is fatal here.

subroutine check_slices(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

compute_mhd_derived

Compute the MHD derived output fields of block b (issue #41, section 9) from the host q and q_aux: total pressure pt = p + |B|^2 / 2, plasma beta 2 p / |B|^2 (huge where B = 0), |B| (every cell), and div B (interior cells, zero on the ghost cells) by the centred finite difference of the div(B) history (the library derivative, half stencil [fdv], null directions weighted zero). The caller has refreshed the ghost cells.

subroutine compute_mhd_derived(self, b, derived)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
b	integer(kind=I4P)	in		Block index.
derived	real(kind=R8P)	out		pt, beta, bmag, divb.

Call graph

compute_q_aux_host

Compute the auxiliary variables of the host q on every cell, ghost cells included (output and AMR marking only: the backends compute their own auxiliary variables in the space operator). The model is selected outside the loops.

subroutine compute_q_aux_host(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

check_ngc_number

Check the ghost cells number against the WENO stencil half-width (weno-riemann: at least 2, the correction reads cells i-1 ... i+2), and with gravity one more (the face beyond each block end, issue #73, M7-G2a).

subroutine check_ngc_number(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

check_positivity_limiter

Refuse the positivity limiter (issue #47, D-9, D-10) where it cannot work: with the mixed GLM (psi changes B_n outside the energy, so no backbone is admissible, M3-P0), with a Runge-Kutta scheme that is not SSP (the limiter makes each forward-Euler step of size dt admissible, and only an SSP scheme is a convex combination of such steps, all of size at most dt), and with immersed solids (the cut-cell flux difference is not the backbone's). The backends refuse it on multi-realm runs (the inter-realm seam carries no limiting factor).

subroutine check_positivity_limiter(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

check_gravity

Refuse the external gravity (issue #73, M7-G1) where its sources are not defined: a component along a null direction (the energy source comes from the face mass fluxes, which a null direction does not have, so the momentum would gain kinetic energy that the energy does not) and immersed solids (the flux difference there uses the spacing cut by the surface, the energy source does not).

subroutine check_gravity(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

log_gravity_regime

Log once (rank 0, at the first step; every rank reduces) how stiff gravity is (issue #73, D-M7-6): |g| dt against the signal speed bound CFL h_min / dt (dt = CFL / lambda_max and lambda_max >= c_max / h_min), so the ratio |g| dt^2 / (CFL h_min) is at least the velocity gravity adds in a step over the fastest wave speed. No time step limit is imposed: a ratio near 1 or above says gravity, not the waves, should set dt.

subroutine log_gravity_regime(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

log_self_gravity

Log once, with log_gravity_regime, the self-gravity regime (issue #81): the free-fall time of the densest cell, t_ff = sqrt(3 pi / (32 G rho_max)), against dt (a warning above t_ff / 10: the collapse would be under-resolved in time), and the wall time of the last Poisson solve.

subroutine log_self_gravity(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

check_dissipation

Refuse the dissipative terms where they are not computed (issue #65): immersed solids, whose walls are inviscid (the eikonal inversion mirrors the normal velocity only), and the 4th-order fluxes without the 3 ghost cells they read (the 2nd-order ones read 1). The viscous and heat fluxes exist for every model (P2, P3), the Ohmic ones for MHD (P3; resistivity on Euler is refused by the dissipation object).

subroutine check_dissipation(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

check_runtime_amr

Check [amr] frequency, the runtime regrid cadence (issue #74, M5): 0 disables runtime regridding (the AMR of the initial condition only, as before M5), n > 0 regrids every n steps with the markers of [amr_marker_N] (mark_runtime). A negative value is an input error, and so are runtime regridding without markers, a Loehner marker reading more ghost layers than the stencil has (buffer <= ngc - 1) and an STL geometry marker.

[amr] regrid_prolongation defaults to conservative in FLUME (owner decision D-M5-2): a regrid then keeps the conserved integrals; the library default, linear, is kept only when the input asks for it.

subroutine check_runtime_amr(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

check_divb_flux

Check [diagnostics] divb_flux (issue #68 A2): D_flux is the divergence of the interface field the cleaning acts on, read from the psi face fluxes, so it needs GLM or EGLM; its residual evaluation runs on the idle RK stage buffers (the committed state copied into the first, the residual into the second), so it needs two stages.

subroutine check_divb_flux(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

check_weno_scheme

Refuse the centred WENO schemes: the flux splitting calls the upwind primitive only, so a weno-c-* scheme would silently run it at order 2S-1 (issue #47). Refuse the scale-invariant weights on primitive variables: their descaler is the magnitude of each field, and a velocity or a magnetic field component crossing zero has none of its own, so the weights would lose accuracy on smooth data (issue #49; the characteristic and conservative variables take the magnitude of the projected state).

subroutine check_weno_scheme(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

initialize_riemann_scheme

Check the Riemann solver against the physical model and build the WENO interpolation tables (weno-riemann only, issue #47): the Euler model takes llf, hll, hllc; the MHD models llf, hll, hlld.

subroutine initialize_riemann_scheme(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

io_initialize

Build the variables names from the physical model (the same predicate that decided nv).

subroutine io_initialize(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	inout		The equation.

Call graph

Functions

is_regrid_step

Return whether the step just closed is a runtime regrid step: [amr] frequency > 0 and the step count a multiple of it (issue #74). The step count is restored by a restart, so a restarted run regrids on the same steps.

Returns: logical

function is_regrid_step(self) result(yes)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

glm_lambda

Return the GLM bound of the local time step, c_h max_b sum_{d active} 1 / dx_d (issue #41, section 3.5): the (B_n, psi) waves travel at c_h along every active direction, the multi-dimensional form of dt <= CFL dx / c_h consistent with the fluid bound sum_d (|u_d| + c_{f,d}) / dx_d. Zero without GLM; local (the forest reduces dt).

Returns: real(kind=R8P)

function glm_lambda(self) result(lambda)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

output_factors

Return the output factors of written variables (1 with code output units, issue #49 N2c).

Returns: real(kind=R8P)

function output_factors(self, names) result(factor)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
names	type(string)	in		Variables names.

Call graph

output_names

Return the names of every variable FLUME may write: conservative, residuals, auxiliary and, for MHD, derived.

Returns: type(string)

function output_names(self) result(names)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

null_freeze

Return, per direction, the conservative variable whose residual a null direction freezes (0: none).

Euler: the momentum along the null direction (CHASE semantics, issue #35, section 3.4). MHD: none, the 1-D MHD Riemann problems evolve the transverse momentum and field through the fluxes of the active directions (issue #41, M2-P3). Host data passed to the model-independent flux difference: no model branch in the kernels.

Returns: integer(kind=I4P)

function null_freeze(self) result(freeze)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

wall_temperature_bound

Return the hottest isothermal wall temperature that the diffusive time step bound must cover (issue #65, P2): 0 without isothermal walls, and with constant laws (the coefficients then do not depend on the temperature).

Attributes: pure

Returns: real(kind=R8P)

function wall_temperature_bound(self) result(t_wall)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

nonfinite_total

Return the number of non-finite values of the committed state over every rank (issue #45).

Returns: integer(kind=I8P)

function nonfinite_total(self, n_local) result(n_total)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
n_local	integer(kind=I8P)	in		Non-finite values number of this rank.

Call graph

ib_cut_spacing

Return the spacing of a fluid cell along one direction, shortened where the solid surface crosses its stencil (CHASE semantics, issue #35 D-9).

When the fluid cell (phi_c < 0) has one neighbour inside the solid (phi_m phi_p < 0), the surface lies at the distance delta = -phi_c / (phi_s - phi_c) ds from the cell centre towards the solid neighbour s, and the spacing becomes ds / 2 + delta; otherwise it is ds. phi_s > 0 > phi_c there, so phi_s - phi_c > 0 needs no guard: CHASE added an absolute 1e-12, a length that broke the scaling covariance of the scheme (issue #49).

Attributes: pure

Returns: real(kind=R8P)

function ib_cut_spacing(phi_c, phi_m, phi_p, ds) result(ds_cut)

Arguments

Name	Type	Intent	Attributes	Description
phi_c	real(kind=R8P)	in		Distance function of the cell (negative in the fluid).
phi_m	real(kind=R8P)	in		Distance function of the minus neighbour.
phi_p	real(kind=R8P)	in		Distance function of the plus neighbour.
ds	real(kind=R8P)	in		Spacing.

Call graph

refinement_by_spacing

Return the refinement query of a block of spacing dc against the admissible spacing delta: refine when too coarse, derefine when its parent (spacing doubled) would still be admissible, untouched otherwise.

Attributes: pure

Returns: integer(kind=I4P)

function refinement_by_spacing(dc, delta) result(refinement)

Arguments

Name	Type	Intent	Attributes	Description
dc	real(kind=R8P)	in		Block spacing.
delta	real(kind=R8P)	in		Admissible spacing.

Call graph

reflux_positivity_theta

Largest fraction theta in [0, 1] of the end-of-step reflux correction d that keeps the coarse cell q admissible (issue #88): the density and the internal energy of q + theta d stay at least POSITIVITY_LIMITER_KAPPA times those of q, the positivity limiter's relative floor. The correction is applied after the stages, where the limiter has already acted, so without this a near-vacuum coarse cell at a 2:1 seam can be driven to a negative internal energy. The internal energy E - |m|^2 / (2 rho) - mag_w |B|^2 / 2 - psi_w psi^2 / 2 (mag_w 1 for MHD, psi_w 1 for EGLM, as the models' internal_energy) is concave in theta, so the admissible fractions are an interval holding 0, whose end the bisection finds. 1 when the full correction is admissible, and for a cell that is not admissible to begin with (left to the scheme).

Attributes: pure

Returns: real(kind=R8P)

function reflux_positivity_theta(nv, q, d, mag_w, psi_w) result(theta)

Arguments

Name	Type	Intent	Attributes	Description
nv	integer(kind=I4P)	in		Variables number.
q	real(kind=R8P)	in		Coarse cell state before the correction.
d	real(kind=R8P)	in		Full correction (scale times the flux mismatch).
mag_w	real(kind=R8P)	in		Weight of the magnetic energy (1 MHD, 0 Euler).
psi_w	real(kind=R8P)	in		Weight of psi^2/2 in the total energy (1 EGLM, 0 otherwise).

Call graph

reflux_internal_energy

Internal energy per unit volume of a state, any model by the weights of reflux_positivity_theta.

Attributes: pure

Returns: real(kind=R8P)

function reflux_internal_energy(nv, q, mag_w, psi_w) result(e)

Arguments

Name	Type	Intent	Attributes	Description
nv	integer(kind=I4P)	in		Variables number.
q	real(kind=R8P)	in		Conservative variables.
mag_w	real(kind=R8P)	in		Weight of the magnetic energy.
psi_w	real(kind=R8P)	in		Weight of psi^2/2.

Call graph

block_spacing

Return the spacing of block b by the AMR delta criterion: x, y, z, or max over the active directions.

Returns: real(kind=R8P)

function block_spacing(self, b, delta_type) result(dc)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.
b	integer(kind=I4P)	in		Block index.
delta_type	character(len=*)	in		Delta criterion.

Call graph

poisson_iterations

FCG iterations of the last multigrid solve (0 without the multigrid solver).

Returns: integer(kind=I4P)

function poisson_iterations(self) result(iterations)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph

runtime_amr_forest

Return whether this realm regrids during the run: [amr] frequency > 0 (issue #74).

Returns: logical

function runtime_amr_forest(self) result(yes)

Arguments

Name	Type	Intent	Attributes	Description
self	class(flume_common_object)	in		The equation.

Call graph