PoPS/doxygen/native__loader_8hpp_source.html

#pragma once


#include <pops/core/state/state.hpp>      // StateVec, Aux, POPS_AUX_FIELDS, kAuxBaseComps

#include <pops/core/foundation/types.hpp>      // POPS_HD, Real

#include <pops/core/state/variables.hpp>  // VariableSet + VariableKind + VariableRole + role_from_name

#include <pops/mesh/layout/box_array.hpp>

#include <pops/mesh/geometry/geometry.hpp>

#include <pops/mesh/storage/multifab.hpp>

#include <pops/mesh/boundary/physical_bc.hpp>  // AuxHaloPolicy (ADC-369: per-field aux halo tail marshaling)

#include <pops/runtime/dynamic/abi_key.hpp>   // pops::abi_key (ABI guard for the native loader)

#include <pops/runtime/dynamic/dynamic_model.hpp>  // IModel: model loaded at runtime (dynamic block)

#include <pops/runtime/context/grid_context.hpp>   // GridContext

#include <pops/runtime/system.hpp>  // pops::System (install_block / grid_context / ensure_aux_width)


#include <algorithm>

#include <cmath>

#include <cstddef>

#include <pops/runtime/dynamic/dynlib.hpp>  // portable dlopen<->LoadLibraryW layer (ADC-99); includes <dlfcn.h> on POSIX

#include <functional>

#include <memory>

#include <stdexcept>

#include <string>

#include <vector>


namespace pops {


namespace native_loader {


template <class Impl>


inline std::vector<double> marshal_aux_halo(Impl* P, int naux) {

  std::vector<double> a = P->copy_state(P->aux, naux);

  const std::size_t nn = static_cast<std::size_t>(P->cfg.n) * static_cast<std::size_t>(P->cfg.n);

  a.resize(static_cast<std::size_t>(naux) * nn + static_cast<std::size_t>(2) * naux, 0.0);

  for (const auto& kv : P->fields_.named_aux_bc_) {

    if (kv.first < 0 || kv.first >= naux)

      continue;

    const std::size_t base =

        static_cast<std::size_t>(naux) * nn + static_cast<std::size_t>(2) * kv.first;

    a[base] = static_cast<double>(static_cast<int>(kv.second.type));

    a[base + 1] = static_cast<double>(kv.second.value);

  }

  return a;

}


POPS_HD inline double limited_slope(double am, double ap, int recon) {

  if (recon == 1) {  // minmod: TVD, robust

    if (am * ap <= 0)

      return 0.0;

    return (std::fabs(am) < std::fabs(ap)) ? am : ap;

  }

  if (recon == 2) {  // van Leer: smoother at extrema

    const double ab = am * ap;

    if (ab <= 0)

      return 0.0;

    return 2.0 * ab / (am + ap);

  }

  return 0.0;  // order 1 (no slope)

}


template <int NV>


std::vector<double> host_residual(const IModel<NV>& m, const std::vector<double>& U,

                                  const std::vector<double>& AUX, int n, double dx, int recon) {

  const std::size_t nn = static_cast<std::size_t>(n) * n;

  auto idx = [&](int i, int j) {

    return static_cast<std::size_t>((j + n) % n) * n + ((i + n) % n);

  };

  auto cell = [&](int i, int j) {

    StateVec<NV> u;

    for (int c = 0; c < NV; ++c)

      u[c] = U[static_cast<std::size_t>(c) * nn + idx(i, j)];

    return u;

  };

  auto aux_at = [&](int i, int j) {  // per-cell aux, periodic; empty => zero

    Aux a{};

    if (AUX.size() >= 3 * nn) {

      const std::size_t k = idx(i, j);

      a.phi = AUX[k];

      a.grad_x = AUX[nn + k];

      a.grad_y = AUX[2 * nn + k];

      // Extra fields marshaled from the SINGLE SOURCE POPS_AUX_FIELDS (pops/core/state.hpp):

      // same table as load_aux on the device side. An extra component is read only if the channel is

      // wide enough ((idx+1)*nn elements). Adding an aux field => 1 line in POPS_AUX_FIELDS,

      // this site (and the other, further down) transports it AUTOMATICALLY. Closes gap #51.

#define POPS_AUX_MARSHAL(name, idx)    \

  if (AUX.size() >= ((idx) + 1) * nn) \

    a.name = AUX[(idx) * nn + k];

      POPS_AUX_FIELDS(POPS_AUX_MARSHAL)

#undef POPS_AUX_MARSHAL

      // Model-NAMED aux fields (ADC-291): extra[e] = aux component kAuxNamedBase + e. Same contract

      // as load_aux (spatial_operator.hpp) and the AOT path (compiled_block_abi.hpp): a component is

      // read ONLY when the channel carries it, so a narrow channel leaves extra[] at 0 (no out-of-

      // bounds). Without this loop a model reading aux.extra_field(k) on the JIT host read 0 silently.

      for (int e = 0; e < kAuxMaxExtra; ++e) {

        const std::size_t comp = static_cast<std::size_t>(kAuxNamedBase + e);

        if (AUX.size() >= (comp + 1) * nn)

          a.extra[e] = AUX[comp * nn + k];

      }

    }

    return a;

  };

  // limited slope of cell (i,j) in direction dir (on the conservative variables)

  auto slope = [&](int i, int j, int dir) {

    StateVec<NV> s{};

    if (recon == 0)

      return s;

    StateVec<NV> Uc = cell(i, j);

    StateVec<NV> Um = (dir == 0) ? cell(i - 1, j) : cell(i, j - 1);

    StateVec<NV> Up = (dir == 0) ? cell(i + 1, j) : cell(i, j + 1);

    for (int c = 0; c < NV; ++c)

      s[c] = limited_slope(Uc[c] - Um[c], Up[c] - Uc[c], recon);

    return s;

  };

  double amax = 0;

  for (int j = 0; j < n; ++j)

    for (int i = 0; i < n; ++i) {

      StateVec<NV> u = cell(i, j);

      Aux a = aux_at(i, j);

      double s = std::max(m.max_wave_speed(u, a, 0), m.max_wave_speed(u, a, 1));

      if (s > amax)

        amax = s;

    }

  // numerical flux at the +dir face of cell (i,j): MUSCL states (cell + neighbor) then Rusanov

  auto face_flux = [&](int i, int j, int dir) {

    const int in = (dir == 0) ? i + 1 : i, jn = (dir == 0) ? j : j + 1;

    StateVec<NV> Uc = cell(i, j), Un = cell(in, jn);

    StateVec<NV> sc = slope(i, j, dir), sn = slope(in, jn, dir), L, R;

    for (int c = 0; c < NV; ++c) {

      L[c] = Uc[c] + 0.5 * sc[c];  // extrapolation toward the face from each side

      R[c] = Un[c] - 0.5 * sn[c];

    }

    StateVec<NV> FL = m.flux(L, aux_at(i, j), dir), FR = m.flux(R, aux_at(in, jn), dir), f;

    for (int c = 0; c < NV; ++c)

      f[c] = 0.5 * (FL[c] + FR[c]) - 0.5 * amax * (R[c] - L[c]);

    return f;

  };

  std::vector<double> Rout(static_cast<std::size_t>(NV) * nn, 0.0);

  for (int j = 0; j < n; ++j)

    for (int i = 0; i < n; ++i) {

      StateVec<NV> Uc = cell(i, j);

      StateVec<NV> Fxr = face_flux(i, j, 0), Fxl = face_flux(i - 1, j, 0);

      StateVec<NV> Fyr = face_flux(i, j, 1), Fyl = face_flux(i, j - 1, 1);

      StateVec<NV> S = m.source(Uc, aux_at(i, j));  // generated source term (force, etc.)

      for (int c = 0; c < NV; ++c)

        Rout[static_cast<std::size_t>(c) * nn + static_cast<std::size_t>(j) * n + i] =

            -((Fxr[c] - Fxl[c]) + (Fyr[c] - Fyl[c])) / dx + S[c];

    }

  return Rout;

}


inline std::vector<std::string> split(const std::string& s, char sep) {

  std::vector<std::string> out;

  std::string cur;

  for (char c : s) {

    if (c == sep) {

      out.push_back(cur);

      cur.clear();

    } else

      cur += c;

  }

  out.push_back(cur);

  return out;

}


struct BlockMeta {

  bool has_gamma = false;

  double gamma = 1.4;

  VariableSet cons{VariableKind::Conservative, {}, 0, {}};

  VariableSet prim{VariableKind::Primitive, {}, 0, {}};

};


inline VariableSet parse_var_set(VariableKind kind, const std::string& names_csv,

                                 const std::string& roles_csv) {

  VariableSet vs{kind, {}, 0, {}};

  if (names_csv.empty())

    return vs;  // no names transported: empty set (the caller will set its fallback)

  vs.names = split(names_csv, ',');

  vs.size = static_cast<int>(vs.names.size());

  parse_roles_into(vs, roles_csv);  // canonical roles + any user-defined role label (ADC-292)

  return vs;

}


inline BlockMeta read_block_meta(pops::dynlib::handle h) {

  BlockMeta m;

  auto names_fn =

      reinterpret_cast<const char* (*)()>(pops::dynlib::sym(h, "pops_compiled_var_names"));

  auto roles_fn = reinterpret_cast<const char* (*)()>(pops::dynlib::sym(h, "pops_compiled_roles"));

  auto gamma_fn = reinterpret_cast<double (*)()>(pops::dynlib::sym(h, "pops_compiled_gamma"));

  std::string names = names_fn ? std::string(names_fn()) : std::string();

  std::string roles = roles_fn ? std::string(roles_fn()) : std::string();

  // "cons|prim": index 0 = conservative set, index 1 = primitive set (each possibly empty).

  std::vector<std::string> nparts = split(names, '|');

  std::vector<std::string> rparts = split(roles, '|');

  auto part = [](const std::vector<std::string>& v, std::size_t i) {

    return i < v.size() ? v[i] : std::string();

  };

  m.cons = parse_var_set(VariableKind::Conservative, part(nparts, 0), part(rparts, 0));

  m.prim = parse_var_set(VariableKind::Primitive, part(nparts, 1), part(rparts, 1));

  if (gamma_fn) {

    m.has_gamma = true;

    m.gamma = gamma_fn();

  }

  return m;

}


template <typename ImplT, int NV>


void push_dynamic(ImplT* P, const std::string& name, pops::dynlib::handle h, int substeps,

                  std::vector<std::string> names, int recon) {

  auto mk = reinterpret_cast<void* (*)()>(pops::dynlib::sym(h, "pops_make_model"));

  auto del = reinterpret_cast<void (*)(void*)>(pops::dynlib::sym(h, "pops_destroy_model"));

  if (!mk || !del) {

    pops::dynlib::close(h);

    throw std::runtime_error(

        "add_dynamic_block: pops_make_model / pops_destroy_model missing from the .so");

  }

  std::shared_ptr<IModel<NV>> im(static_cast<IModel<NV>*>(mk()), [del, h](IModel<NV>* p) {

    del(p);

    pops::dynlib::close(h);

  });

  // The loaded model can read extra aux fields (n_aux > 3, e.g. B_z): we

  // widen the SHARED aux channel so set_magnetic_field populates it and the host marshaling

  // transports them. Base model (3) -> no-op. The closures read P->aux_ncomp_ at call time.

  P->ensure_aux_width(im->n_aux());

  const int n = P->cfg.n;

  const double dx = P->cfg.L / P->cfg.n;


  std::function<void(MultiFab&, MultiFab&)> rhs_into = [P, im, n, dx, recon](MultiFab& U,

                                                                             MultiFab& R) {

    // HOST path (dynamic block): same MPI guard as add_poisson. On a rank without a local box

    // (local_size()==0 at np>1) there is nothing to marshal; the owner rank carries the full

    // physics. Without this guard, copy_state(U) / write_state(R) would dereference a nonexistent fab(0).

    // No collective MPI operation here -> one-sided no-op, no deadlock risk.

    if (U.local_size() == 0)

      return;

    P->write_state(R, NV,

                   host_residual<NV>(*im, P->copy_state(U, NV),

                                     P->copy_state(P->aux, P->aux_ncomp_), n, dx, recon));

  };

  std::function<Real(const MultiFab&)> max_speed = [P, im, n](const MultiFab& U) -> Real {

    // Same MPI guard: empty rank -> local speed 0 (the downstream all_reduce_max takes the global max,

    // the owner contributes the real value). No collective here -> no-op without deadlock.

    if (U.local_size() == 0)

      return Real(0);

    std::vector<double> u = P->copy_state(U, NV), aux = P->copy_state(P->aux, P->aux_ncomp_);

    const std::size_t nn = static_cast<std::size_t>(n) * n;

    Real mx = 0;

    for (std::size_t c0 = 0; c0 < nn; ++c0) {

      StateVec<NV> s;

      for (int c = 0; c < NV; ++c)

        s[c] = u[static_cast<std::size_t>(c) * nn + c0];

      Aux a{};

      if (aux.size() >= 3 * nn) {

        a.phi = aux[c0];

        a.grad_x = aux[nn + c0];

        a.grad_y = aux[2 * nn + c0];

        // Extra fields: same SINGLE SOURCE POPS_AUX_FIELDS as load_aux and the other marshaling

        // site (host_residual). cf. note above; adding a field = 1 line.

#define POPS_AUX_MARSHAL(name, idx)    \

  if (aux.size() >= ((idx) + 1) * nn) \

    a.name = aux[(idx) * nn + c0];

        POPS_AUX_FIELDS(POPS_AUX_MARSHAL)

#undef POPS_AUX_MARSHAL

        // Model-NAMED aux fields (ADC-291): same single-source contract as the host_residual site.

        for (int e = 0; e < kAuxMaxExtra; ++e) {

          const std::size_t comp = static_cast<std::size_t>(kAuxNamedBase + e);

          if (aux.size() >= (comp + 1) * nn)

            a.extra[e] = aux[comp * nn + c0];

        }

      }

      Real v = std::max(im->max_wave_speed(s, a, 0), im->max_wave_speed(s, a, 1));

      if (v > mx)

        mx = v;

    }

    return mx;

  };

  std::function<void(MultiFab&, Real, int)> advance = [P, im, n, dx, recon](MultiFab& U, Real dt,

                                                                            int nsub) {

    // Same MPI guard: empty rank -> no-op (nothing to marshal). No collective -> without deadlock.

    if (U.local_size() == 0)

      return;

    const Real hh = dt / nsub;

    const std::vector<double> aux = P->copy_state(P->aux, P->aux_ncomp_);  // frozen aux (splitting)

    for (int s = 0; s < nsub; ++s) {  // explicit Euler per substep (host path, prototype)

      std::vector<double> u = P->copy_state(U, NV);

      std::vector<double> res = host_residual<NV>(*im, u, aux, n, dx, recon);

      for (std::size_t k = 0; k < u.size(); ++k)

        u[k] += hh * res[k];

      P->write_state(U, NV, u);

    }

  };

  // Contribution of the dynamic block to the system Poisson: rhs += elliptic_rhs(U) per cell.

  // Model without an elliptic part => elliptic_rhs is 0 (no effect), thus backward-compatible.

  std::function<void(const MultiFab&, MultiFab&)> add_poisson = [P, im, n](const MultiFab& U,

                                                                           MultiFab& rhs) {

    // HOST path (dynamic block .so prototype): it marshals the box to a full n*n

    // array and treats it as replicated. On a rank without a local box (System distributes ONE box,

    // so local_size()==0 at np>1 on the non-owner ranks) there is nothing to marshal:

    // we skip, the owner rank carries the full contribution to the right-hand side. Without

    // this guard, copy_state(U) / rhs.fab(0) would dereference a nonexistent fab (host crash).

    if (rhs.local_size() == 0)

      return;

    std::vector<double> u = P->copy_state(U, NV);

    const std::size_t nn = static_cast<std::size_t>(n) * n;

    Array4 r = rhs.fab(0).array();

    const Box2D v = rhs.box(0);

    for (int j = v.lo[1]; j <= v.hi[1]; ++j)

      for (int i = v.lo[0]; i <= v.hi[0]; ++i) {

        const std::size_t k = static_cast<std::size_t>(j - v.lo[1]) * n + (i - v.lo[0]);

        StateVec<NV> s;

        for (int c = 0; c < NV; ++c)

          s[c] = u[static_cast<std::size_t>(c) * nn + k];

        r(i, j, 0) += im->elliptic_rhs(s);

      }

  };

  // OPTIONAL metadata (names / roles / gamma) carried by the extended ABI of the .so. Symmetric

  // to the AOT path. Absent from an old .so -> empty meta -> fallback (names u0.. / no roles /

  // gamma 1.4). PRIORITY to the explicit name (names=), then meta, then fallback; roles + primitive

  // come ONLY from the ABI (the API does not expose them).

  const BlockMeta meta = read_block_meta(h);

  VariableSet cons_vs = meta.cons, prim_vs = meta.prim;

  if (!names.empty()) {

    if (static_cast<int>(names.size()) != NV)

      throw std::runtime_error("System::add_dynamic_block: names= has " +

                               std::to_string(names.size()) + " names but block '" + name +

                               "' has " + std::to_string(NV) + " variables");

    cons_vs.names = names;

    cons_vs.size = static_cast<int>(names.size());

  }

  if (cons_vs.names.empty()) {

    for (int c = 0; c < NV; ++c)

      cons_vs.names.push_back("u" + std::to_string(c));

    cons_vs.size = NV;

  }

  if (prim_vs.names.empty())

    prim_vs = {VariableKind::Primitive, cons_vs.names, cons_vs.size, {}};

  const double gamma = meta.has_gamma ? meta.gamma : 1.4;


  typename ImplT::Species block{name,

                                MultiFab(P->ba, P->dm, NV, 2),

                                NV,

                                substeps,

                                true,

                                /*stride=*/1,

                                gamma,

                                std::move(advance),

                                std::move(rhs_into),

                                std::move(max_speed),

                                std::move(add_poisson)};

  block.cons_vars = std::move(cons_vs);

  block.prim_vars = std::move(prim_vs);

  // POINTWISE cons <-> prim conversions OF THE MODEL (set/get_primitive_state): forwarded by

  // the virtual interface IModel<NV> (ModelAdapter delegates to M.to_primitive/to_conservative when

  // M exposes them, otherwise identity). An old .so whose model has no conversion thus falls back

  // on identity -- exact for a scalar (prim == cons). StateVec<NV> shares the width NV.

  block.prim_to_cons = [im](const double* in, double* out) {

    StateVec<NV> p{};

    for (int c = 0; c < NV; ++c)

      p[c] = static_cast<Real>(in[c]);

    const StateVec<NV> u = im->to_conservative(p);

    for (int c = 0; c < NV; ++c)

      out[c] = static_cast<double>(u[c]);

  };

  block.cons_to_prim = [im](const double* in, double* out) {

    StateVec<NV> u{};

    for (int c = 0; c < NV; ++c)

      u[c] = static_cast<Real>(in[c]);

    const StateVec<NV> p = im->to_primitive(u);

    for (int c = 0; c < NV; ++c)

      out[c] = static_cast<double>(p[c]);

  };

  P->sp.push_back(std::move(block));

  P->sp.back().U.set_val(Real(0));

}


template <typename ImplT>


void add_dynamic_block(System* self, ImplT* P, const std::string& name, const std::string& so_path,

                       int substeps, const std::vector<std::string>& names,

                       const std::string& recon) {

  (void)self;

  if (substeps < 1)

    throw std::runtime_error("System::add_dynamic_block: substeps >= 1");

  int recon_id = 0;  // MUSCL reconstruction order of the face states (conservative)

  if (recon == "none")

    recon_id = 0;

  else if (recon == "minmod")

    recon_id = 1;

  else if (recon == "vanleer")

    recon_id = 2;

  else

    throw std::runtime_error(

        "System::add_dynamic_block: recon 'none' | 'minmod' | 'vanleer' "

        "(got '" +

        recon + "')");

  pops::dynlib::handle h = pops::dynlib::open(so_path);

  if (!h) {

    const std::string e = pops::dynlib::last_error();

    throw std::runtime_error("add_dynamic_block: dlopen('" + so_path +

                             "'): " + (e.empty() ? std::string("?") : e));

  }

  auto nv_fn = reinterpret_cast<int (*)()>(pops::dynlib::sym(h, "pops_model_nvars"));

  if (!nv_fn) {

    pops::dynlib::close(h);

    throw std::runtime_error("add_dynamic_block: pops_model_nvars missing from the .so");

  }

  const int nv = nv_fn();

  switch (nv) {

    case 1:

      push_dynamic<ImplT, 1>(P, name, h, substeps, names, recon_id);

      break;

    case 3:

      push_dynamic<ImplT, 3>(P, name, h, substeps, names, recon_id);

      break;

    case 4:

      push_dynamic<ImplT, 4>(P, name, h, substeps, names, recon_id);

      break;

    default:

      pops::dynlib::close(h);

      throw std::runtime_error("add_dynamic_block: n_vars=" + std::to_string(nv) +

                               " unsupported (1, 3, 4)");

  }

}


template <typename ImplT>


void add_compiled_block(System* self, ImplT* P, const std::string& name, const std::string& so_path,

                        const std::string& limiter, const std::string& riemann,

                        const std::string& recon, const std::string& time, int substeps,

                        const std::vector<std::string>& names, double pos_floor = 0) {

  (void)self;

  if (substeps < 1)

    throw std::runtime_error("System::add_compiled_block: substeps >= 1");

  if (recon != "conservative" && recon != "primitive")

    throw std::runtime_error("System::add_compiled_block: recon 'conservative' | 'primitive'");

  // NB: the AOT path (.so) marshals time->imex without an explicit RK scheme: only SSPRK2 is wired

  // in the extern "C" ABI of the .so. "ssprk3" and "euler" are therefore NOT supported here (the

  // advance would remain SSPRK2, silently) -> we reject them; exposing them would require extending the

  // ABI of the .so (out of scope ADC-174). They are carried by the native add_block AND backend='production'

  // (add_native_block: the template marshals method down to make_block of the loader).

  if (time != "explicit" && time != "imex")

    throw std::runtime_error(

        "System::add_compiled_block: time 'explicit' | 'imex' (ssprk3, euler and "

        "the IMEX-RK family ARS(2,2,2) -> native add_block or backend='production'; "

        "the AOT path only exposes SSPRK2 + local backward-Euler)");

  // WENO5 (5-point stencil, 3 ghosts) is now EXPOSED by the AOT path: the local grid of the

  // .so allocates block_n_ghost(limiter) (compiled_block_abi.hpp), 3 for weno5, so assemble_rhs does not read

  // out of bounds. limiter is validated by make_block in the .so (none|minmod|vanleer|weno5).

  const int recon_prim = (recon == "primitive") ? 1 : 0;

  const int imex = (time == "imex") ? 1 : 0;


  pops::dynlib::handle h = pops::dynlib::open(so_path);

  if (!h) {

    const std::string e = pops::dynlib::last_error();

    throw std::runtime_error("add_compiled_block: dlopen('" + so_path +

                             "'): " + (e.empty() ? std::string("?") : e));

  }

  // extern "C" ABI of the compiled block (compiled_block_abi.hpp). The .so runs the production path

  // (assemble_rhs<Limiter, Flux>, SSPRK2/IMEX) on the generated model; only flat arrays

  // pass through (no C++ object shared across the dlopen, thus RTLD_LOCAL without ABI risk).

  using nv_fn_t = int (*)();

  using res_fn_t = void (*)(const double*, double*, const double*, int, double, double, int,

                            const char*, const char*, int);

  using adv_fn_t = void (*)(double*, const double*, int, double, double, int, const char*,

                            const char*, int, int, double, int);

  using max_fn_t = double (*)(const double*, const double*, int, double, double, int);

  using poi_fn_t = void (*)(const double*, double*, int);

  auto nv_fn = reinterpret_cast<nv_fn_t>(pops::dynlib::sym(h, "pops_model_nvars"));

  auto res_fn = reinterpret_cast<res_fn_t>(pops::dynlib::sym(h, "pops_compiled_residual"));

  auto adv_fn = reinterpret_cast<adv_fn_t>(pops::dynlib::sym(h, "pops_compiled_advance"));

  auto max_fn = reinterpret_cast<max_fn_t>(pops::dynlib::sym(h, "pops_compiled_max_speed"));

  auto poi_fn = reinterpret_cast<poi_fn_t>(pops::dynlib::sym(h, "pops_compiled_poisson_rhs"));

  if (!nv_fn || !res_fn || !adv_fn || !max_fn || !poi_fn) {

    pops::dynlib::close(h);

    throw std::runtime_error(

        "add_compiled_block: compiled block ABI missing from the .so (regenerate via "

        "dsl.compile_aot / compile_or_jit(mode='compile'))");

  }

  const int nv = nv_fn();

  // Width of the aux channel that the compiled model READS (B_z, T_e...). Symmetric to the JIT path

  // (IModel::n_aux). Optional: an old .so without this symbol falls back on the base contract (3).

  auto naux_fn = reinterpret_cast<nv_fn_t>(pops::dynlib::sym(h, "pops_compiled_naux"));

  const int naux = naux_fn ? naux_fn() : kAuxBaseComps;

  // RUNTIME PARAMS (P7-b): SUFFIXED `_p` variants that take a flat block (const double*, int) of

  // runtime parameter values, injected into the model before execution. OPTIONAL: a .so

  // generated before this work (or a model without runtime params) does not expose them / declares nparams=0 ->

  // we keep the historical symbols (const-params path, bit-identical). We SEED the value block

  // to the declaration defaults (pops_compiled_param_defaults) so a later set_param overwrites

  // only one entry without resetting the others to zero.

  auto nparams_fn = reinterpret_cast<nv_fn_t>(pops::dynlib::sym(h, "pops_compiled_nparams"));

  const int nparams = nparams_fn ? nparams_fn() : 0;

  using res_p_fn_t = void (*)(const double*, double*, const double*, int, double, double, int,

                              const char*, const char*, int, const double*, int, double);

  using adv_p_fn_t = void (*)(double*, const double*, int, double, double, int, const char*,

                              const char*, int, int, double, int, const double*, int, double);

  using max_p_fn_t =

      double (*)(const double*, const double*, int, double, double, int, const double*, int);

  using poi_p_fn_t = void (*)(const double*, double*, int, const double*, int);

  auto res_p_fn = reinterpret_cast<res_p_fn_t>(pops::dynlib::sym(h, "pops_compiled_residual_p"));

  auto adv_p_fn = reinterpret_cast<adv_p_fn_t>(pops::dynlib::sym(h, "pops_compiled_advance_p"));

  auto max_p_fn = reinterpret_cast<max_p_fn_t>(pops::dynlib::sym(h, "pops_compiled_max_speed_p"));

  auto poi_p_fn = reinterpret_cast<poi_p_fn_t>(pops::dynlib::sym(h, "pops_compiled_poisson_rhs_p"));

  // SHARED block of current values: captured by the closures AND registered in P->block_params_

  // (set_block_params writes there -> the closures see the new value at the next step). Empty if the

  // block has no runtime param or if the `_p` ABI is absent (old .so): the closures then call

  // the historical symbols (const path). Non-null pv triggers the `_p` path.

  std::shared_ptr<std::vector<double>> pv;

  const bool use_params = (nparams > 0 && res_p_fn && adv_p_fn && max_p_fn && poi_p_fn);

  // POSITIVITY LIMITER (ADC-76): pos_floor > 0 goes through the `_p` variants (the only signatures

  // that carry it). An old .so without `_p` cannot apply it -> clear error (never a silent

  // path without positivity). pos_floor <= 0: historical paths, bit-identical.

  if (pos_floor > 0 && (!res_p_fn || !adv_p_fn))

    throw std::runtime_error(

        "add_compiled_block: positivity_floor > 0 requires the `_p` ABI of the .so (regenerate the "

        "compiled module with the current headers)");

  if (use_params) {

    pv = std::make_shared<std::vector<double>>(static_cast<std::size_t>(nparams), 0.0);

    auto defs_fn =

        reinterpret_cast<void (*)(double*)>(pops::dynlib::sym(h, "pops_compiled_param_defaults"));

    if (defs_fn)

      defs_fn(pv->data());  // seed to the declaration defaults

  }  // registration in P->block_params_ DEFERRED to just before push_back (after the validations that

  // may throw: avoids an orphan entry without an associated block if the addition fails).

  // OPTIONAL metadata (names / roles / gamma) transported by the extended ABI of the .so. Absent

  // from an old .so -> empty meta, we fall back on the fallback (names u0.. / no roles / gamma 1.4).

  const BlockMeta meta = read_block_meta(h);

  // Widen the SHARED aux channel so set_magnetic_field/T_e populate it and the marshaling

  // transports the extra components to the .so. Base model (3) -> no-op (bit-identical).

  P->ensure_aux_width(naux);

  std::shared_ptr<void> lib(h, [](void* p) {  // closes the .so when the closures die

    pops::dynlib::close(static_cast<pops::dynlib::handle>(p));

  });

  const int n = P->cfg.n;

  const double dx = P->geom.dx(), dy = P->geom.dy();

  const int per = P->periodic_ ? 1 : 0;

  const std::string lim = limiter, riem = riemann;


  std::function<void(MultiFab&, MultiFab&)> rhs_into = [P, lib, res_fn, res_p_fn, pv, nv, naux, n,

                                                        dx, dy, per, lim, riem, recon_prim,

                                                        pos_floor](MultiFab& U, MultiFab& R) {

    // HOST path (compiled block .so): same MPI guard as add_poisson. On a rank without a local

    // box (local_size()==0 at np>1) there is nothing to marshal; the owner rank carries

    // the full physics. No collective here -> one-sided no-op, no deadlock.

    if (U.local_size() == 0)

      return;

    // ADC-369: marshal naux comps + the per-field halo tail (read by make_grid in the .so).

    std::vector<double> u = P->copy_state(U, nv), a = marshal_aux_halo(P, naux);

    std::vector<double> r(static_cast<std::size_t>(nv) * n * n, 0.0);

    if (pv || pos_floor > 0)  // `_p` variant: RUNTIME params (P7-b) and/or positivity (ADC-76)

      res_p_fn(u.data(), r.data(), a.data(), n, dx, dy, per, lim.c_str(), riem.c_str(), recon_prim,

               pv ? pv->data() : nullptr, pv ? static_cast<int>(pv->size()) : 0, pos_floor);

    else

      res_fn(u.data(), r.data(), a.data(), n, dx, dy, per, lim.c_str(), riem.c_str(), recon_prim);

    P->write_state(R, nv, r);

  };

  std::function<void(MultiFab&, Real, int)> advance = [P, lib, adv_fn, adv_p_fn, pv, nv, naux, n,

                                                       dx, dy, per, lim, riem, recon_prim, imex,

                                                       pos_floor](MultiFab& U, Real dt, int nsub) {

    // Same MPI guard: empty rank -> no-op. No collective -> without deadlock.

    if (U.local_size() == 0)

      return;

    std::vector<double> u = P->copy_state(U, nv), a = marshal_aux_halo(P, naux);  // ADC-369 tail

    if (pv || pos_floor > 0)  // `_p` variant: RUNTIME params (P7-b) and/or positivity (ADC-76)

      adv_p_fn(u.data(), a.data(), n, dx, dy, per, lim.c_str(), riem.c_str(), recon_prim, imex,

               static_cast<double>(dt), nsub, pv ? pv->data() : nullptr,

               pv ? static_cast<int>(pv->size()) : 0, pos_floor);

    else

      adv_fn(u.data(), a.data(), n, dx, dy, per, lim.c_str(), riem.c_str(), recon_prim, imex,

             static_cast<double>(dt), nsub);

    P->write_state(U, nv, u);

  };

  std::function<Real(const MultiFab&)> max_speed = [P, lib, max_fn, max_p_fn, pv, nv, naux, n, dx,

                                                    dy, per](const MultiFab& U) -> Real {

    // Same MPI guard: empty rank -> local speed 0. The downstream all_reduce_max takes the global max.

    if (U.local_size() == 0)

      return Real(0);

    std::vector<double> u = P->copy_state(U, nv), a = marshal_aux_halo(P, naux);  // ADC-369 tail

    if (pv)  // RUNTIME params (P7-b)

      return max_p_fn(u.data(), a.data(), n, dx, dy, per, pv->data(), static_cast<int>(pv->size()));

    return max_fn(u.data(), a.data(), n, dx, dy, per);

  };

  std::function<void(const MultiFab&, MultiFab&)> add_poisson = [P, lib, poi_fn, poi_p_fn, pv, nv,

                                                                 n](const MultiFab& U,

                                                                    MultiFab& rhs) {

    // HOST path (compiled block .so prototype): same MPI guard as the dynamic block. On a

    // rank without a local box (local_size()==0 at np>1) there is nothing to marshal -> we skip, the

    // owner rank carries the full contribution. Without it copy_state(U) / rhs.fab(0)

    // would dereference a nonexistent fab (host crash).

    if (rhs.local_size() == 0)

      return;

    std::vector<double> u = P->copy_state(U, nv);

    std::vector<double> pr(static_cast<std::size_t>(n) * n, 0.0);

    if (pv)  // RUNTIME params (P7-b)

      poi_p_fn(u.data(), pr.data(), n, pv->data(), static_cast<int>(pv->size()));

    else

      poi_fn(u.data(), pr.data(), n);

    Array4 r = rhs.fab(0).array();

    const Box2D v = rhs.box(0);

    for (int j = v.lo[1]; j <= v.hi[1]; ++j)

      for (int i = v.lo[0]; i <= v.hi[0]; ++i)

        r(i, j, 0) += pr[static_cast<std::size_t>(j - v.lo[1]) * n + (i - v.lo[0])];

  };


  // Variable descriptors: PRIORITY to the explicit name passed by the caller (names=), otherwise to the

  // NAMES carried by the extended ABI of the .so (meta), otherwise fallback u0.. . The ROLES and the PRIMITIVE do not

  // transit EXCEPT through the ABI (the API has no way to provide them): we take them from meta as-is.

  VariableSet cons_vs = meta.cons, prim_vs = meta.prim;

  if (!names.empty()) {  // explicit override of the conservative names

    if (static_cast<int>(names.size()) != nv)

      throw std::runtime_error("System::add_compiled_block: names= has " +

                               std::to_string(names.size()) + " names but block '" + name +

                               "' has " + std::to_string(nv) + " variables");

    cons_vs.names = names;

    cons_vs.size = static_cast<int>(names.size());

  }

  if (cons_vs.names.empty()) {  // neither names= nor meta: historical fallback u0..

    for (int c = 0; c < nv; ++c)

      cons_vs.names.push_back("u" + std::to_string(c));

    cons_vs.size = nv;

  }

  if (prim_vs.names.empty())

    prim_vs = {VariableKind::Primitive, cons_vs.names, cons_vs.size, {}};

  // gamma: carried by the ABI if the model declares it (pops_compiled_gamma), otherwise historical default 1.4.

  const double gamma = meta.has_gamma ? meta.gamma : 1.4;

  typename ImplT::Species block{name,

                                MultiFab(P->ba, P->dm, nv, 2),

                                nv,

                                substeps,

                                true,

                                /*stride=*/1,

                                gamma,

                                std::move(advance),

                                std::move(rhs_into),

                                std::move(max_speed),

                                std::move(add_poisson)};

  block.cons_vars = std::move(cons_vs);

  block.prim_vars = std::move(prim_vs);

  // cons <-> prim conversions OF THE MODEL via the extended ABI of the .so (set/get_primitive_state). The

  // symbols operate on flat component-major arrays c*nn+k: called with n=1 (thus nn=1),

  // they convert ONE cell (in/out = nv doubles), which is exactly the CellConvert contract.

  // OPTIONAL: a .so generated before this work does not expose them -> empty conversion -> identity (the

  // set/get_primitive_state path then falls back on prim == cons, exact for a scalar).

  using cv_fn_t = void (*)(const double*, double*, int);

  auto p2c_fn = reinterpret_cast<cv_fn_t>(pops::dynlib::sym(h, "pops_compiled_to_conservative"));

  auto c2p_fn = reinterpret_cast<cv_fn_t>(pops::dynlib::sym(h, "pops_compiled_to_primitive"));

  // P7-b: if the block has runtime params, the cons<->prim conversions must see them too (the

  // conversion can read a runtime param). We then prefer the `_p` variants with the SHARED block.

  using cv_p_fn_t = void (*)(const double*, double*, int, const double*, int);

  auto p2c_p_fn =

      reinterpret_cast<cv_p_fn_t>(pops::dynlib::sym(h, "pops_compiled_to_conservative_p"));

  auto c2p_p_fn = reinterpret_cast<cv_p_fn_t>(pops::dynlib::sym(h, "pops_compiled_to_primitive_p"));

  if (pv && p2c_p_fn)

    block.prim_to_cons = [lib, p2c_p_fn, pv](const double* in, double* out) {

      p2c_p_fn(in, out, 1, pv->data(), static_cast<int>(pv->size()));

    };

  else if (p2c_fn)

    block.prim_to_cons = [lib, p2c_fn](const double* in, double* out) { p2c_fn(in, out, 1); };

  if (pv && c2p_p_fn)

    block.cons_to_prim = [lib, c2p_p_fn, pv](const double* in, double* out) {

      c2p_p_fn(in, out, 1, pv->data(), static_cast<int>(pv->size()));

    };

  else if (c2p_fn)

    block.cons_to_prim = [lib, c2p_fn](const double* in, double* out) { c2p_fn(in, out, 1); };

  // PROJECTION PONCTUELLE post-pas (ADC-177) : symboles OPTIONNELS de l'ABI etendue

  // (pops_compiled_has_projection / pops_compiled_project_p). Un .so genere avant ce chantier ne les

  // expose pas -> aucune projection installee (chemin historique, bit-identique). has==1 sans la

  // fonction de projection = .so incoherent -> erreur EXPLICITE plutot qu'un hook silencieusement

  // ignore. Le stepper applique la fermeture a la FIN de chaque macro-pas entier (cf. SystemStepper).

  auto has_proj_fn = reinterpret_cast<nv_fn_t>(pops::dynlib::sym(h, "pops_compiled_has_projection"));

  if (has_proj_fn && has_proj_fn() != 0) {

    using proj_fn_t = void (*)(double*, const double*, int, const double*, int);

    auto proj_fn = reinterpret_cast<proj_fn_t>(pops::dynlib::sym(h, "pops_compiled_project_p"));

    // Pas de close(h) ici : le shared_ptr `lib` possede deja le handle (fermeture a sa destruction).

    if (!proj_fn)

      throw std::runtime_error(

          "add_compiled_block : pops_compiled_has_projection() == 1 mais pops_compiled_project_p "

          "absent du .so (regenerer via dsl.compile(backend='aot'))");

    block.project = [P, lib, proj_fn, pv, nv, n](MultiFab& U) {

      // Meme garde MPI que les autres fermetures marshalees : rang sans box locale -> no-op

      // unilateral (pas de collectif ici, aucun risque d'interblocage).

      if (U.local_size() == 0)

        return;

      // NB (ADC-369): the projection reads the aux POINTWISE (compiled_block_abi::pointwise_project,

      // no make_grid, no ghost) -> it needs NO per-field halo tail, so we marshal the plain aux here.

      std::vector<double> u = P->copy_state(U, nv), a = P->copy_state(P->aux, P->aux_ncomp_);

      proj_fn(u.data(), a.data(), n, pv ? pv->data() : nullptr,

              pv ? static_cast<int>(pv->size()) : 0);

      P->write_state(U, nv, u);

    };

  }

  // P7-b: register the SHARED block of runtime params AFTER the validations (all passed here):

  // set_block_params will find it by name, and the block closures share the same shared_ptr.

  if (pv)

    P->block_params_[name] = pv;

  P->sp.push_back(std::move(block));

  P->sp.back().U.set_val(Real(0));

}


template <typename ImplT>


void add_native_block(System* self, ImplT* P, const std::string& name, const std::string& so_path,

                      const std::string& limiter, const std::string& riemann,

                      const std::string& recon, const std::string& time, double gamma, int substeps,

                      bool evolve, int stride, double pos_floor = 0) {

  (void)P;

  if (substeps < 1)

    throw std::runtime_error("System::add_native_block: substeps >= 1");

  if (stride < 1)

    throw std::runtime_error("System::add_native_block: stride >= 1");

  // UPFRONT validation of the scheme (like add_block / add_compiled_block): add_compiled_model interprets

  // imex = (time=="imex"), recon_prim = (recon=="primitive") and the explicit RK scheme

  // method = ssprk3 | euler | ssprk2 according to time; an unknown string would fall back SILENTLY on

  // explicit/ssprk2/conservative. We thus reject a typo HERE rather than running a

  // scheme different from the one requested. "ssprk3" (order 3, to pair with weno5) and "euler" (ForwardEuler,

  // order 1: fidelity to first-order references, validation -- ADC-174) are ACCEPTED: the template

  // add_compiled_model marshals them down to make_block of the .so, like the native path add_block. limiter/riemann are validated by make_block in the loader (clear

  // exception, shared ABI verified further down).

  if (recon != "conservative" && recon != "primitive")

    throw std::runtime_error("System::add_native_block: recon 'conservative' | 'primitive' (got '" +

                             recon + "')");

  if (time != "explicit" && time != "ssprk3" && time != "euler" && time != "imex")

    throw std::runtime_error(

        "System::add_native_block: time 'explicit' | 'ssprk3' | 'euler' | 'imex' "

        "(got '" +

        time +

        "'; the IMEX-RK family ARS(2,2,2) is wired only on "

        "a composite model pops.Model(...) -> native add_block)");

  // WENO5 (5-point stencil, 3 ghosts) is now EXPOSED by the native path: the loader inlines

  // add_compiled_model which, after install_block, reallocates the block state to block_n_ghost(limiter) (3

  // for weno5) -- SAME mechanism as add_block. assemble_rhs thus does not read out of bounds. limiter is

  // validated by make_block in the loader (none|minmod|vanleer|weno5).

  // "production" path of the DSL: the generated .so loader (emit_cpp_native_loader) inlines the header

  // template add_compiled_model<ProdModel>, which builds the closures on the REAL CONTEXT of the

  // System (grid_context) and installs the block via install_block -- NATIVE path, zero-copy, SAME

  // MultiFab as add_block (no marshaling of flat arrays like add_compiled_block). The loader

  // thus calls out-of-line methods of pops::System DEFINED in THIS module; they must be

  // resolved through the dlopen against the already-loaded _pops module.

  // ELF PORTABILITY (Linux): CPython loads _pops in RTLD_LOCAL, so its symbols are NOT in

  // the global scope and the loader could not resolve them. We thus PROMOTE the current module to

  // global scope (RTLD_NOLOAD = without reloading it, just promote; RTLD_GLOBAL OR'ed into the

  // flags of the already-loaded object). The module path is found by dladdr on an exported symbol

  // (pops::abi_key). On macOS it is harmless (the loader already resolves via dynamic_lookup).

#if defined(_WIN32)

  // Windows (ADC-100): NO RTLD_GLOBAL. The generated .dll is linked at COMPILATION against the

  // import libraries: _pops.lib (System symbols POPS_EXPORT: install_block/grid_context/...) and

  // kokkoscore.lib (Kokkos runtime SHARED as a DLL). Its undefineds are thus resolved by the OS loader

  // against _pops.pyd and kokkos*.dll already loaded -- no need to promote a global scope. We

  // simply load the .dll and resolve pops_install_native.

  pops::dynlib::handle h = pops::dynlib::open(so_path);

  if (!h)

    throw std::runtime_error(

        "add_native_block: LoadLibrary('" + so_path + "'): " + pops::dynlib::last_error() +

        " (the .dll must be linked against _pops.lib + kokkoscore.lib; cf. ADC-100)");

  {

    auto key_fn = reinterpret_cast<const char* (*)()>(pops::dynlib::sym(h, "pops_native_abi_key"));

    if (!key_fn) {

      pops::dynlib::close(h);

      throw std::runtime_error("add_native_block: pops_native_abi_key missing from the .dll");

    }

    const std::string loader_key = key_fn();

    const std::string module_key = abi_key();

    if (loader_key != module_key) {

      pops::dynlib::close(h);

      throw std::runtime_error("add_native_block: incompatible ABI -- loader key '" + loader_key +

                               "' != module key '" + module_key + "'");

    }

    using install_fn_t = void (*)(void*, const char*, const char*, const char*, const char*,

                                  const char*, double, int, int, int, double);

    auto install = reinterpret_cast<install_fn_t>(pops::dynlib::sym(h, "pops_install_native"));

    if (!install) {

      pops::dynlib::close(h);

      throw std::runtime_error("add_native_block: pops_install_native missing from the .dll");

    }

    install(static_cast<void*>(self), name.c_str(), limiter.c_str(), riemann.c_str(), recon.c_str(),

            time.c_str(), gamma, substeps, evolve ? 1 : 0, stride, pos_floor);

  }

  // .dll left loaded for the duration of the process (the block points to code that lives in it).

#else

  {

    Dl_info info;

    if (dladdr(reinterpret_cast<void*>(&pops::abi_key), &info) && info.dli_fname)

      dlopen(info.dli_fname, RTLD_NOW | RTLD_GLOBAL | RTLD_NOLOAD);

  }

  // RTLD_GLOBAL: places the loader symbols in the global scope AND lets the loader resolve

  // its undefineds (the exported System methods POPS_EXPORT) against the already-loaded images. RTLD_NOW:

  // immediate resolution -> a missing System symbol (module without POPS_EXPORT) fails HERE, not in flight.

  void* h = dlopen(so_path.c_str(), RTLD_NOW | RTLD_GLOBAL);

  if (!h) {

    const char* e = dlerror();

    throw std::runtime_error("add_native_block: dlopen('" + so_path +

                             "'): " + std::string(e ? e : "?") +

                             " (the pops::System symbols (install_block/grid_context/"

                             "ensure_aux_width) must be exported AND the _pops module loaded "

                             "globally; cf. POPS_EXPORT)");

  }

  // EXPLICIT ABI GUARD: the key baked into the loader (at ITS compilation) must equal the module

  // key (at ITS compilation). A mismatch = divergent headers / compiler / standard -> memory

  // layout of System/GridContext/BlockClosures potentially different across the boundary ->

  // UB. We throw a CLEAR error rather than letting an incompatible loader through.

  auto key_fn = reinterpret_cast<const char* (*)()>(pops::dynlib::sym(h, "pops_native_abi_key"));

  if (!key_fn) {

    pops::dynlib::close(h);

    throw std::runtime_error(

        "add_native_block: pops_native_abi_key missing from the .so (regenerate via "

        "dsl.compile_native / compile(backend='production'))");

  }

  const std::string loader_key = key_fn();

  const std::string module_key = abi_key();

  if (loader_key != module_key) {

    pops::dynlib::close(h);

    throw std::runtime_error("add_native_block: incompatible ABI -- loader key '" + loader_key +

                             "' != module key '" + module_key +

                             "'. Recompile the loader with the SAME compiler, C++ standard and "

                             "pops headers as the _pops module.");

  }

  // Native installer of the loader: reinterpret_cast<System*>(this) then add_compiled_model<ProdModel>.

  // Scheme (limiter/riemann/recon/time/gamma/substeps) marshaled as flat extern "C" arguments: the

  // loader reconstructs imex/recon_prim and calls the template. evolve is passed so a fixed-background

  // block (not advanced) is possible as via add_block.

  using install_fn_t = void (*)(void*, const char*, const char*, const char*, const char*,

                                const char*, double, int, int, int, double);

  auto install = reinterpret_cast<install_fn_t>(pops::dynlib::sym(h, "pops_install_native"));

  if (!install) {

    pops::dynlib::close(h);

    throw std::runtime_error(

        "add_native_block: pops_install_native missing from the .so (regenerate via "

        "dsl.compile_native / compile(backend='production'))");

  }

  // NB signature: pops_install_native now carries pos_floor (positivity limiter,

  // ADC-76) as the final flat argument. A loader generated BEFORE this addition has a different C

  // signature -- it is REJECTED upstream by the ABI key (POPS_HEADER_SIG changes with the headers), never

  // called with a wrong argument layout.

  install(static_cast<void*>(self), name.c_str(), limiter.c_str(), riemann.c_str(), recon.c_str(),

          time.c_str(), gamma, substeps, evolve ? 1 : 0, stride, pos_floor);

  // The .so stays loaded (RTLD_GLOBAL) for the duration of the process: the installed block points to code

  // (block_builder closures, named functors) that lives in it. We do NOT close it (no ownership

  // to hook onto: the closures are copied into the System registry but their CODE is

  // in the .so). Consistent with a production binary where the model is linked for life.

#endif  // _WIN32 (POSIX-only production path; Windows = throw, cf. ADC-100)

}


}  // namespace native_loader


}  // namespace pops

abi_key.hpp
ABI key of the pops core: stable string identifying the (compiler, C++ standard, header tree signatur...

box_array.hpp
BoxArray: the set of boxes tiling a level (disjoint, covering).

pops::MultiFab
Field distributed over a level: decomposition (BoxArray) + distribution (DistributionMapping) + ncomp...
Definition multifab.hpp:33

pops::System
Coupled multi-species system, composed at runtime from generic bricks.
Definition system.hpp:89

POPS_AUX_MARSHAL
#define POPS_AUX_MARSHAL(name, idx)

dynamic_model.hpp
TYPE-ERASED model interface: runtime dispatch of a model (via vtable).

dynlib.hpp
PORTABLE dynamic loading: dlopen/dlsym/dlclose (POSIX) <-> LoadLibraryW/ GetProcAddress/FreeLibrary (...

geometry.hpp
Geometry: index-space (Box2D) <-> Cartesian physical-space mapping; PolarGeometry: SIBLING for a glob...

grid_context.hpp
Block grid context plus closures, shared between System (which installs them) and block_builder....

multifab.hpp
MultiFab: a field DISTRIBUTED over a level (equivalent of AMReX's MultiFab).

pops::dynlib::handle
void * handle
Definition dynlib.hpp:33

pops::dynlib::last_error
std::string last_error()
Last error message (best-effort, for diagnostics).
Definition dynlib.hpp:87

pops::dynlib::close
void close(handle h)
Closes h (no-op on a null handle).
Definition dynlib.hpp:71

pops::dynlib::open
handle open(const std::string &path)
Opens a dynamic library (path in UTF-8). Returns a null handle on failure.
Definition dynlib.hpp:48

pops::dynlib::sym
void * sym(handle h, const char *name)
Resolves name in h. Returns nullptr if absent.
Definition dynlib.hpp:62

pops::native_loader::add_dynamic_block
void add_dynamic_block(System *self, ImplT *P, const std::string &name, const std::string &so_path, int substeps, const std::vector< std::string > &names, const std::string &recon)
Body of System::add_dynamic_block. VERBATIM; self = the calling System, P = self->p_....
Definition native_loader.hpp:419

pops::native_loader::add_native_block
void add_native_block(System *self, ImplT *P, const std::string &name, const std::string &so_path, const std::string &limiter, const std::string &riemann, const std::string &recon, const std::string &time, double gamma, int substeps, bool evolve, int stride, double pos_floor=0)
Body of System::add_native_block.
Definition native_loader.hpp:743

pops::native_loader::parse_var_set
VariableSet parse_var_set(VariableKind kind, const std::string &names_csv, const std::string &roles_csv)
Builds a VariableSet from the CSV names / roles (parallel to names; EMPTY roles = not provided -> Var...
Definition native_loader.hpp:208

pops::native_loader::limited_slope
POPS_HD double limited_slope(double am, double ap, int recon)
MUSCL limited slope of a cell from backward difference am and forward ap.
Definition native_loader.hpp:67

pops::native_loader::push_dynamic
void push_dynamic(ImplT *P, const std::string &name, pops::dynlib::handle h, int substeps, std::vector< std::string > names, int recon)
Builds a DYNAMIC block (IModel<NV> model loaded from the .so h) and adds it.
Definition native_loader.hpp:249

pops::native_loader::marshal_aux_halo
std::vector< double > marshal_aux_halo(Impl *P, int naux)
ADC-369: marshal the aux for a COMPILED block – the naux valid components (component-major,...
Definition native_loader.hpp:49

pops::native_loader::split
std::vector< std::string > split(const std::string &s, char sep)
Split s on sep (empty fields kept).
Definition native_loader.hpp:181

pops::native_loader::host_residual
std::vector< double > host_residual(const IModel< NV > &m, const std::vector< double > &U, const std::vector< double > &AUX, int n, double dx, int recon)
Host residual R = -div F* + S(U, aux) (Rusanov, GLOBAL a_max like pops.PythonFlux,...
Definition native_loader.hpp:90

pops::native_loader::add_compiled_block
void add_compiled_block(System *self, ImplT *P, const std::string &name, const std::string &so_path, const std::string &limiter, const std::string &riemann, const std::string &recon, const std::string &time, int substeps, const std::vector< std::string > &names, double pos_floor=0)
Body of System::add_compiled_block. VERBATIM; self = the calling System, P = self->p_....
Definition native_loader.hpp:468

pops::native_loader::read_block_meta
BlockMeta read_block_meta(pops::dynlib::handle h)
Reads (by dlsym, all OPTIONAL) the metadata symbols of an already-open .so (h).
Definition native_loader.hpp:222

pops
Definition amr_hierarchy.hpp:29

pops::VariableKind
VariableKind
Kind of a variable set: conserved (U) or primitive (W).
Definition variables.hpp:22

pops::VariableKind::Primitive
@ Primitive

pops::VariableKind::Conservative
@ Conservative

pops::kAuxBaseComps
constexpr int kAuxBaseComps
Definition state.hpp:147

pops::Real
double Real
Definition types.hpp:30

pops::abi_key
POPS_EXPORT std::string abi_key()
ABI key of the module (TU system.cpp).

pops::kAuxMaxExtra
constexpr int kAuxMaxExtra
Definition state.hpp:100

pops::roles_csv
std::string roles_csv(const VariableSet &vs)
CSV of a VariableSet's roles (role_name, separator ',').
Definition variables.hpp:172

pops::parse_roles_into
void parse_roles_into(VariableSet &vs, const std::string &csv)
Inverse of roles_csv: fill vs.roles (and vs.user_roles for any NON-canonical token) from a roles CSV.
Definition variables.hpp:190

pops::names_csv
std::string names_csv(const VariableSet &vs)
CSV of a VariableSet's names (separator ',').
Definition variables.hpp:158

pops::kAuxNamedBase
constexpr int kAuxNamedBase
Definition state.hpp:154

physical_bc.hpp
PHYSICAL boundary conditions at the domain edge (BCType, BCRec, fill_physical_bc, fill_ghosts).

state.hpp
Pointwise types of the physics layer: StateVec<N> (conserved state) and Aux (auxiliary fields from th...

POPS_AUX_FIELDS
#define POPS_AUX_FIELDS(X)
SINGLE SOURCE of the layout of the EXTRA aux fields (X-macro).
Definition state.hpp:92

pops::Array4
WRITE POD handle (raw pointer + strides) over a Fab2D buffer, indexed by (i, j, c) IN GLOBAL INDICES ...
Definition fab2d.hpp:29

pops::Aux
POINTWISE auxiliary fields shared with the physics: single coupling channel.
Definition state.hpp:123

pops::Aux::phi
Real phi
Definition state.hpp:124

pops::Box2D
2D integer index space, cell-centered.
Definition box2d.hpp:37

pops::Box2D::hi
int hi[2]
Definition box2d.hpp:39

pops::Box2D::lo
int lo[2]
Definition box2d.hpp:38

pops::IModel
Hyperbolic model seen behind a virtual interface (runtime dispatch).
Definition dynamic_model.hpp:27

pops::IModel::source
virtual State source(const State &, const Aux &) const
Source term S(U, aux) (default: zero, model without source).
Definition dynamic_model.hpp:35

pops::IModel::max_wave_speed
virtual Real max_wave_speed(const State &u, const Aux &a, int dir) const =0

pops::IModel::flux
virtual State flux(const State &u, const Aux &a, int dir) const =0

pops::IModel::to_primitive
virtual State to_primitive(const State &u) const
Conservative -> primitive conversion (P = M.to_primitive(U)).
Definition dynamic_model.hpp:42

pops::StateVec
Conserved state vector of fixed size, known at compile time.
Definition state.hpp:29

pops::VariableSet
A model's variable set: kind (cons/prim), names, size, canonical roles (optional, parallel to names; ...
Definition variables.hpp:58

pops::VariableSet::names
std::vector< std::string > names
Definition variables.hpp:60

pops::VariableSet::size
int size
Definition variables.hpp:61

pops::native_loader::BlockMeta
OPTIONAL metadata read by dlsym on a generated .so (names / roles / gamma).
Definition native_loader.hpp:199

pops::native_loader::BlockMeta::gamma
double gamma
Definition native_loader.hpp:201

pops::native_loader::BlockMeta::has_gamma
bool has_gamma
Definition native_loader.hpp:200

pops::native_loader::BlockMeta::cons
VariableSet cons
Definition native_loader.hpp:202

pops::native_loader::BlockMeta::prim
VariableSet prim
Definition native_loader.hpp:203

system.hpp
Runtime multi-species composition: one coupled system, block by block.

types.hpp
Base scalar types and the POPS_HD macro (host+device portability).

POPS_HD
#define POPS_HD
Definition types.hpp:25

variables.hpp
Descriptor of a model's variables (Vars).