ERF_FireEngine.H File Reference

The interface between the fire coupling and a fire engine. More...

#include <AMReX.H>
#include <AMReX_MultiFab.H>
#include <AMReX_REAL.H>
#include <string>
#include <vector>
#include <ERF_FireGrid.H>

Include dependency graph for ERF_FireEngine.H:

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

Go to the source code of this file.

Classes
struct	FireForcing
	The atmospheric state a fire engine reads at the start of its step. More...
struct	FireFluxes
	The fluxes a fire engine hands to the atmosphere after its step. More...
class	FireEngine
	A fire engine behind the shared coupling layer. More...

Detailed Description

The interface between the fire coupling and a fire engine.

A fire engine advances a fire front on the fire grid and reports the heat it releases. The shared coupling layer (FireCoupler) owns everything that touches the atmosphere: the fire grid's placement, the atmospheric fields handed to the engine, the area average of the engine's fluxes onto the atmospheric columns, their one-step lag, their injection into the atmosphere's sources and the smoke tracer. An engine sees only this interface, the two structs below and the shared helpers it chooses to use (the wind sampler of ERF_FireWindExtract.H, the column grounds of ERF_FireSurfaceHeight.H).

ERF itself contains no engine. An engine lives in its own directory outside ERF (FIRE_HOME in GNU make, ERF_FIRE_ENGINE_DIRS in CMake) and registers itself with ERF_REGISTER_FIRE_ENGINE (ERF_FireEngineRegistry.H). ERF_FireEngineTemplate.H declares every method below for new engines: a method added to FireEngine is declared there too (a pure virtual one that is missing fails the build; an optional one does not).

Memory contract. Every MultiFab the coupling hands an engine (FireForcing, the FireGrid layout) and every one the engine hands back (FireFluxes, the getters below) is an ordinary AMReX MultiFab in the default arena, so on a GPU build its data is on the device. The coupling reads the engine's fields on the device right after the call that returned them. An engine that runs on the host:

• copies what it reads from FireForcing to the host inside advance() (fire_host_copy(), ERF_FireUtils.H, does the copy and the stream synchronisation), because those fields are temporaries of that call;
• owns the MultiFabs it returns, allocated on fg.ba and fg.dm (or the level's k = 0 slabs where stated), and keeps them alive until its next advance(); it fills them on the host and copies them back to device memory (fire_host_copy() the other way) before returning from fill_fluxes() or the getter;
• may hold managed or pinned memory internally, but synchronises the GPU stream (amrex::Gpu::streamSynchronize()) before it touches the host side of data the device may still be writing. The coupling never frees, resizes or keeps across steps a pointer an engine returns.