MIEM API

namespace miem

Typedefs

using Real = float

using Index = std::size_t

Enums

enum class SourceMode

Whether a source reads offline files or is computed online.

Values:

enumerator Offline

enumerator Online

enum class SourceType

Emission inventory sector a source represents.

Values:

enumerator Anthropogenic

enumerator Fire

enumerator Biogenic

enumerator Dust

enumerator SeaSalt

enumerator Lightning

enum class TemporalInterpolation

Scheme used to interpolate between successive input time slices.

Values:

enumerator Linear

enumerator Nearest

enumerator None

enum class VerticalInjection

Where a source deposits its emissions in the vertical column.

Values:

enumerator Surface

enumerator Plume

enum class RegriddingType

Horizontal regridding scheme applied to a source’s input grid.

Values:

enumerator None

enumerator Scrip

enum class InterpolationMode

Interpolation mode for the two-slice bracket.

Values:

enumerator kLinear

Linear blend between the two slices.

enumerator kNearest

Snap to the nearer slice in time.

enumerator kNone

Hold the left slice (no blending).

class Emissions

class EmissionsArray

#include <miem/emissions_state.hpp>

Two-dimensional view backed by a flat std::vector<Real>.

Rows are species, columns are cells. Stored in species-major (row-major) order, so &data()[species_idx*n_cells_] is the start of a row.

Public Functions

inline void Resize(int n_species, int n_cells)

Resize to n_species x n_cells and zero-fill.

inline void SetSpecies(const std::vector<std::string> &names)

Set the species names and rebuild the name-to-index map.

inline Real operator()(int cell, const std::string &species) const

Value at (cell, species) by name; zero if not present.

inline Real &At(int species_idx, int cell)

Mutable reference at (species_idx, cell).

inline Real At(int species_idx, int cell) const

Value at (species_idx, cell).

inline int n_species() const

Row count.

inline int n_cells() const

Column count.

struct EmissionsState

#include <miem/emissions_state.hpp>

Per-cell, per-species emissions output returned by Emissions::Run.

Holds the surface flux and volumetric tendency arrays, plus optional per-sector diagnostic fluxes. All field names carry a trailing underscore.

Memory layout:

• surface_flux_ : species-major, [species_idx*n_cells_+cell_idx]

• tendency_ : species + level major, [species_idx*n_vert_levels_*n_cells_ + level_idx*n_cells_ + cell_idx]

The convenience accessor operator()(cell, species) resolves by species name via an index map maintained alongside the species list. Raw-pointer accessors are exposed for the zero-copy hand-off to the host model / MUSICA layer.

Public Functions

void Resize(int n_species, int n_cells, int n_vert_levels)

Resize all arrays to the given dimensions and zero-fill.

void Zero()

Zero all flux and tendency arrays in place.

inline bool HasSectors() const

True iff any per-sector diagnostic fluxes are present.

const EmissionsArray *GetSectorFlux(const std::string &sector) const

Sector flux by name; returns nullptr if the sector is absent.

Public Members

int n_species_ = 0

Number of emission species.

int n_cells_ = 0

Number of horizontal cells.

int n_vert_levels_ = 0

Number of vertical levels.

std::vector<std::string> species_names_

Emission species names.

std::vector<int> emis_to_chem_idx_

Maps emission species index to host chemistry species index (-1 if not present). Populated by Emissions::ResolveHostIndices.

std::vector<int> injection_layer_

Per-species injection layer (0 = surface).

EmissionsArray surface_flux_

(n_species, n_cells) [kg m-2 s-1].

std::vector<Real> tendency_

Volumetric tendency, flat (n_species * n_vert_levels * n_cells) [kg kg-1 s-1].

std::map<std::string, EmissionsArray> sector_fluxes_

Optional diagnostic per-sector fluxes (same shape as surface_flux_).

std::vector<std::string> sector_names_

Sector insertion order.

class FluxConverter

#include <miem/flux_converter.hpp>

Converts surface emission fluxes into volumetric tendencies.

Converts a surface emission flux [kg m-2 s-1] into a volumetric tendency [kg kg-1 s-1] at a given injection layer, using a host-supplied air density [kg m-3] and layer thickness [m]:

\[ \text{tendency} = \frac{\text{flux}}{\rho_\text{air} \, \Delta z} \]

An optional runtime mass-conservation check (gated by MIEM_CHECK_MASS_CONSERVATION, default ON in Debug / OFF in Release) verifies that the column-integrated reconstruction \( \sum_k \text{tendency}_k \, \rho_k \, \Delta z_k \) equals the input surface flux to within kMassToleranceFactor of \( |\text{flux}| \).

Public Static Functions

static void Apply(EmissionsState &state, const Real *air_density, const Real *layer_thickness, int n_atm_elements)

Convert state.surface_flux_ into state.tendency_ in place.

Both atmospheric arrays use the layout [level*n_cells+cell] and must hold exactly n_vert_levels_*n_cells_ elements.

Parameters:

• state – Emissions state; reads surface_flux_, writes tendency_.

• air_density – Air density [kg m-3], one value per atm element.

• layer_thickness – Layer thickness [m], one value per atm element.

• n_atm_elements – Length of air_density and layer_thickness.

Throws:

MiemException – (Validation / CELL_COUNT_MISMATCH) on a size mismatch, and (Validation / MASS_CONSERVATION) when MIEM_CHECK_MASS_CONSERVATION is enabled and the column integral drifts beyond kMassToleranceFactor.

static Real FluxToTendency(Real flux_kg_m2_s, Real air_density_kg_m3, Real layer_thickness_m)

Per-species, per-cell scalar form of the flux-to-tendency map.

Parameters:

• flux_kg_m2_s – Surface flux [kg m-2 s-1].

• air_density_kg_m3 – Air density [kg m-3].

• layer_thickness_m – Layer thickness [m].

Returns:

Volumetric tendency [kg kg-1 s-1], or zero when the denominator is non-positive.

Public Static Attributes

static Real kMassToleranceFactor = static_cast<Real>(1e-9)

Maximum allowed relative drift in the mass-conservation check.

struct MiemException : public std::runtime_error

#include <miem/util/miem_exception.hpp>

The single MIEM exception type, modeled on micm::MicmException.

Carries a string-literal category_ and an integer code_ (see error.hpp for the MIEM_ERROR_CATEGORY_* / MIEM_*_ERROR_CODE_* macros). Every public MIEM entry point throws this on failure; at the C/Fortran boundary musica::HandleErrors() catches it and converts it to a MUSICA Error struct, preserving the category and code. This mirrors how MICM throws micm::MicmException.

Public Members

const char *category_

A MIEM_ERROR_CATEGORY_* string literal.

int code_

A MIEM_*_ERROR_CODE_* value.

struct Regridding

#include <miem/source_types.hpp>

Regridding specification, set once on the EmissionsBuilder.

v1 accepts only type_ equal to RegriddingType::None; EmissionsBuilder::Build() rejects any other value.

Public Members

RegriddingType type_ = RegriddingType::None

Regridding scheme; only None in v1.

std::string weights_file_

Weights path; unused while type_ is None.

struct Source

#include <miem/source_types.hpp>

Description of a single emission source, the unit added to an EmissionsBuilder.

MIEM mirrors MICM: there is no aggregate “config” object. A host (or musica’s translator) hands the runtime a collection of domain objects, and Source is that object &#8212; the emissions analog of a single micm::Process. Add one per inventory to an EmissionsBuilder.

A Source is a plain value type: it holds no open files or runtime state. The builder turns each Source into a runtime EmissionSource (via SourceFactory) when EmissionsBuilder::Build() is called. All field names carry a trailing underscore.

Category and hierarchy follow the HEMCO pattern:

• Sources in different categories are summed.

• Within a category, the highest-hierarchy source wins per cell.

Duplicate (category, hierarchy) pairs are rejected at Build() time.

Public Members

std::string name_

Diagnostic name for the source.

SourceMode mode_ = SourceMode::Offline

Offline files vs online computation.

SourceType type_ = SourceType::Anthropogenic

Inventory sector.

std::string file_pattern_

File pattern with optional {YYYY}{MM}{DD}{HH} tokens. Already resolved by musica’s translator: MIEM receives a concrete path.

std::string convention_ = "eccad"

Inventory convention: the on-disk NetCDF layout MIEM assumes when it reads this source’s files. v1 accepts only “eccad” (case-insensitive); anything else is UnknownConvention at build time.

The “eccad” convention follows the file layout published by ECCAD (Emissions of atmospheric Compounds and Compilation of Ancillary Data, https://eccad.aeris-data.fr/) &#8212; the AERIS-hosted repository MIEM’s reference inventories (e.g. CAMS-GLOB-ANT) are distributed through. See the “Inventory conventions” page of the user guide for the variable/dimension/units expectations this implies, and for how non-conforming files are adapted via a dataset descriptor.

SpeciesMap species_map_

Inventory-to-mechanism species map: rewrites this source’s emission flux from the inventory’s species names onto the chemical mechanism’s species (the names MICM solves for), redistributing mass per the configured per-mapping scaling factors. It maps emission flux, not concentration, and only renames/splits species &#8212; it does not itself move data between MIEM and MICM. musica builds it by translating the parsed configuration’s named species_map entry. See SpeciesMap::Apply for the transform.

TemporalInterpolation temporal_interpolation_ = TemporalInterpolation::Linear

Interpolation between successive input time slices.

VerticalInjection vertical_injection_ = VerticalInjection::Surface

Vertical placement of the emitted mass.

int category_ = 0

HEMCO category index.

int hierarchy_ = 1

HEMCO hierarchy level.

Real scaling_factor_ = 1.0

Multiplicative flux scaling.

std::string sector_

Optional diagnostic label.

class SpeciesMap

#include <miem/species_map.hpp>

Programmatic inventory-to-mechanism species mapping.

Built incrementally with AddMapping (typically by musica’s translator from the parsed configuration), then applied at runtime to transform inventory flux into mechanism flux. There is no parsing constructor; schema parsing lives in MechanismConfiguration.

Public Functions

void AddMapping(const std::string &inventory_name, const std::string &mechanism_name, Real scaling_factor = 1.0)

Add a single mapping; rebuilds the cached mechanism index.

void Validate() const

Validate per-inventory-species scaling-factor sums.

Each inventory species’ scaling factors must sum to no more than \( 1.0 \) (plus a small tolerance) to avoid silent mass amplification.

Throws:

MiemException – (Species / SCALING_EXCEEDS_ONE) on the first offending species.

void Apply(const std::vector<Real> &inventory_flux, const std::vector<std::string> &inventory_names, std::vector<Real> &mechanism_flux, int n_cells) const

Transform inventory flux into mechanism flux.

Parameters:

• inventory_flux – Input, laid out as (n_inventory_species*n_cells).

• inventory_names – Names matching the rows of inventory_flux.

• mechanism_flux – Output, laid out as (n_mechanism_species*n_cells); resized, zero-initialized, then accumulated.

• n_cells – Number of horizontal cells.

Throws:

MiemException – (Validation / CELL_COUNT_MISMATCH) when inventory_flux is not sized inventory_names.size()*n_cells.

std::vector<std::string> MechanismSpecies() const

Deduplicated list of mechanism-species names.

std::vector<std::string> InventorySpecies() const

List of inventory-species names.

inline const std::vector<SpeciesMapping> &Mappings() const

The configured mappings.

inline const std::string &MechanismName() const

Name of the chemical mechanism these mappings target.

inline void SetMechanismName(const std::string &name)

Set the chemical-mechanism name.

struct SpeciesMapping

#include <miem/species_map.hpp>

A single inventory-species to mechanism-species mapping.

Public Members

std::string inventory_name_

Name in the emission inventory.

std::string mechanism_name_

Name in the chemical mechanism.

Real scaling_factor_ = 1.0

Mass-based per-mapping scaling.

class TemporalInterpolator

#include <miem/temporal_interpolator.hpp>

Two-time-slice bracket interpolator (linear, nearest, or hold-left).

SetBracket validates that the two slices have matching size and throws on failure. Interpolate is total (no throws, no errors); out-of-range gating is the caller’s responsibility (see OfflineEmissionSource).

Public Functions

void SetBracket(double time_left, double time_right, const std::vector<Real> &data_left, const std::vector<Real> &data_right)

Set the two-slice bracket.

Throws:

MiemException – (Validation / CELL_COUNT_MISMATCH) when the two arrays have different size.

void Interpolate(double time_current, std::vector<Real> &output) const

Interpolate to time_current into output (resized to the bracket size).

Total function; no error path. Linear mode clamps the blend factor to the range [0, 1]; the caller (OfflineEmissionSource) is responsible for keeping time_current within the bracket’s [time_left, time_right] range.

bool CoversTime(double time) const

True iff time lies inside the current bracket’s interval.

inline InterpolationMode Mode() const

The active interpolation mode.

inline double TimeLeft() const

Left edge of the current bracket [s].

inline double TimeRight() const

Right edge of the current bracket [s].