C ABI of an AOT-COMPILED block: a model generated by the DSL, compiled ahead-of-time into a .so, exposes its residual / advance / wave speed / Poisson right-hand side through extern "C" functions. More...

#include <pops/runtime/builders/block/block_builder.hpp>
#include <pops/mesh/layout/box_array.hpp>
#include <pops/mesh/layout/distribution_mapping.hpp>
#include <pops/mesh/boundary/fill_boundary.hpp>
#include <pops/mesh/execution/for_each.hpp>
#include <pops/mesh/geometry/geometry.hpp>
#include <pops/mesh/storage/multifab.hpp>
#include <pops/mesh/boundary/physical_bc.hpp>
#include <pops/core/model/physical_model.hpp>
#include <pops/core/state/variables.hpp>
#include <pops/runtime/config/runtime_params.hpp>
#include <pops/runtime/module_capabilities.hpp>
#include <string>
#include <type_traits>
#include <utility>

Include dependency graph for compiled_block_abi.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	pops::compiled_block::LocalGrid
	Local single-grid mesh rebuilt inside the .so + aux filled from the System array. More...

struct	pops::compiled_block::HasRuntimeParams< B, class >
	Detects (SFINAE) whether a brick B exposes a `params` member of type pops::RuntimeParams (DSL bricks carry one only if a formula reads a runtime parameter, P7-b). More...

struct	pops::compiled_block::HasRuntimeParams< B, std::void_t< decltype(std::declval< B & >().params)> >

Namespaces
namespace	pops

namespace	pops::compiled_block

Macros
#define	POPS_AUX_MARSHAL(name, idx)

#define	POPS_DEFINE_COMPILED_BLOCK(MODEL)
	Defines the extern "C" ABI of the compiled block for the model `MODEL` (a top-level alias WITHOUT a comma: write `using Model = pops::CompositeModel<...>;` then pass this alias).

Functions
LocalGrid	pops::compiled_block::make_grid (int n, double dx, double dy, bool periodic, const double *aux_in, int naux)
	`naux` = width of the aux channel the model READS (aux_comps<Model>(), >= 3).

void	pops::compiled_block::fill_interior (MultiFab &mf, const double *in, int n, int nv)
	Copies `nv` components of the component-major flat array `in` into the INTERIOR of fab(0) (without touching the ghosts).

void	pops::compiled_block::extract (const MultiFab &mf, double *out, int n, int nv)
	Copies the INTERIOR of fab(0) (`nv` components) into the component-major flat array `out`.

template<class B >
void	pops::compiled_block::apply_runtime_params (B &b, const RuntimeParams &rp)
	Writes `rp` into the `params` member of brick `b` if it has one (P7-b); otherwise no-op.

template<class Model >
Model	pops::compiled_block::make_model_with_params (const double *pvals, int npar)
	Builds a Model (CompositeModel<Hyp, Src, Ell>) and injects the `npar` runtime parameter values `pvals` into EACH brick that carries a `params` member (P7-b).

template<class B >
int	pops::compiled_block::brick_nparams (const B &b)
	Number of runtime parameters the `params` member of a brick `b` carries (0 if the brick has none).

template<class Model >
RuntimeParams	pops::compiled_block::model_params (const Model &model)
	`params` block (full RuntimeParams) of the model: the FIRST brick that carries one (all carry the same full block when the model has runtime params).

template<class Model >
int	pops::compiled_block::model_nparams ()
	Number of runtime parameters declared by `Model` (P7-b): max of the `params.count` of its 3 bricks (each carries the SAME full block when the model has runtime params; 0 everywhere otherwise).

template<class Model >
void	pops::compiled_block::model_param_defaults (double *out)
	Writes the DECLARATION values of `Model's` runtime parameters into `out` (at least model_nparams<Model>() doubles).

template<class Model >
void	pops::compiled_block::residual (const double U, double R, const double aux_in, int n, double dx, double dy, bool periodic, const std::string &lim, const std::string &riem, bool recon_prim, const double pvals=nullptr, int npar=0, double pos_floor=0)
	Residual -div F + S of the production path (assemble_rhs<Limiter, Flux>) on the generated model.

template<class Model >
void	pops::compiled_block::advance (double U, const double aux_in, int n, double dx, double dy, bool periodic, const std::string &lim, const std::string &riem, bool recon_prim, bool imex, double dt, int nsub, const double *pvals=nullptr, int npar=0, double pos_floor=0)
	Advances by `nsub` substeps (explicit SSPRK2, or ForwardEuler + implicit source if imex).

template<class Model >
double	pops::compiled_block::max_speed (const double U, const double aux_in, int n, double dx, double dy, bool periodic, const double *pvals=nullptr, int npar=0)
	Max wave speed of the block (for the CFL step on the System side) via make_max_speed on the generated model.

template<class Model >
void	pops::compiled_block::to_conservative (const double P, double U, int n, const double *pvals=nullptr, int npar=0)
	PRIMITIVE -> CONSERVATIVE conversion cell by cell (M.to_conservative) on component-major flat arrays ncompnn.

template<class Model >
void	pops::compiled_block::to_primitive (const double U, double P, int n, const double *pvals=nullptr, int npar=0)
	CONSERVATIVE -> PRIMITIVE conversion cell by cell (M.to_primitive).

template<class Model >
void	pops::compiled_block::pointwise_project (double U, const double aux_in, int n, const double *pvals=nullptr, int npar=0)
	PROJECTION PONCTUELLE post-pas (ADC-177) : U(k) <- model.project(U(k), aux(k)) sur les n*n cellules, tableaux plats composante-majeur (meme disposition que to_conservative).

template<class Model >
void	pops::compiled_block::poisson_rhs (const double U, double rhs_out, int n, const double *pvals=nullptr, int npar=0)
	Elliptic right-hand side f(U) of the block (the System adds it to its Poisson sum).

std::string	pops::compiled_block::csv_to_json_array (const std::string &csv)
	A JSON array literal `["a","b",...]` from a comma-separated CSV (empty CSV -> `[]`).

template<class Model >
std::string	pops::compiled_block::model_cons_roles_csv ()
	The conservative-role CSV of `Model`, or an empty string if the model declares no roles.

std::string	pops::compiled_block::compiled_native_entrypoints_csv ()
	The native entrypoint symbols a POPS_DEFINE_COMPILED_BLOCK .so exports, as a CSV.

template<class Model >
std::string	pops::compiled_block::compiled_manifest_json ()
	The per-artifact NativeManifest of `Model` as a JSON string (Spec 5 sec.13.12, criterion #36).

Detailed Description

C ABI of an AOT-COMPILED block: a model generated by the DSL, compiled ahead-of-time into a .so, exposes its residual / advance / wave speed / Poisson right-hand side through extern "C" functions.

The .so RUNS the PRODUCTION path (block_builder.hpp: assemble_rhs<Limiter, Flux>, core SSPRK2/IMEX) on the CompositeModel<Gen...> known AT ITS compilation: the numerics are inlined, identical to a native add_block block. Only the mesh transits through flat arrays (marshaling on the System side, like add_dynamic_block): no C++ symbol dependency across the dlopen (clean ABI). The zero-copy / GPU version (model compiled into the Kokkos build, without marshaling) is a separate path.

Array layout: component-major c*n*n + j*n + i (like System::copy_state). A generated .so reduces to: include the brick + this header, write namespace pops_generated { using Model = pops::CompositeModel<...>; } then POPS_DEFINE_COMPILED_BLOCK(pops_generated::Model).

Macro Definition Documentation

◆ POPS_AUX_MARSHAL

#define POPS_AUX_MARSHAL	(	name,
		idx
	)

Value:

if constexpr (naux > (idx)) \

a.name = static_cast<Real>(aux_in[(idx) * nn + k]);

◆ POPS_DEFINE_COMPILED_BLOCK

#define POPS_DEFINE_COMPILED_BLOCK ( MODEL )

Defines the extern "C" ABI of the compiled block for the model MODEL (a top-level alias WITHOUT a comma: write using Model = pops::CompositeModel<...>; then pass this alias).

P7-b (RUNTIME PARAMS). IN ADDITION to the historical symbols (unchanged, thus bit-identical for a model without a runtime param), we emit _p-SUFFIXED variants that take a flat block of runtime parameters (const double* pvals, int npar) injected into the model before execution, and pops_compiled_nparams() (number of runtime params of the model, 0 if none). The loader (native_loader.hpp) PREFERS the _p symbols when present; an old .so without them falls back to the historical symbols (no runtime param). The historical symbols delegate to the same templates with pvals=nullptr/npar=0 -> strict bit-identity of the const-params path.

ADC-177 (PROJECTION PONCTUELLE post-pas) : symboles OPTIONNELS pops_compiled_has_projection() (1 si le modele declare le trait HasPointwiseProjection, 0 sinon) et pops_compiled_project_p (U <- project(U, aux) sur les tableaux plats). Un vieux .so ne les expose pas -> le loader n'installe aucune projection (bit-identique). Un .so NEUF charge par un VIEUX module : la projection serait ignoree (le vieux loader n'interroge pas ces symboles) – combinaison exclue en pratique, dsl.py et le module _pops etant livres ensemble (cf. docs/DSL_API.md).

include/pops/runtime/builders/compiled/compiled_block_abi.hpp File Reference¶

Classes

Namespaces

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ POPS_AUX_MARSHAL

◆ POPS_DEFINE_COMPILED_BLOCK