A fire engine behind the shared coupling layer. More...

#include <ERF_FireEngine.H>

Inheritance diagram for FireEngine:

Public Member Functions
virtual	~FireEngine ()=default

virtual const char *	name () const =0
	Name of the engine, as erf.fire.engine selects it. More...

virtual void	verify_prerequisites (const ERF &erf, int lev)=0
	Check the engine's own inputs against the ERF configuration. More...

virtual void	initialize (const ERF &erf, int lev, const FireGrid &fg, const SurfaceLayer surface_layer, const amrex::MultiFab z_phys_nd_atm)=0
	Set the engine up on the fire grid. More...

virtual void	start_run (amrex::Real stop_time, int max_step, int steps_per_coarse_step)
	Start-up after initialize(), once the run's end is known. More...

virtual void	advance (const FireForcing &forcing)=0
	Advance the fire over one step of its level. More...

virtual void	fill_fluxes (FireFluxes &fluxes)=0
	The fluxes of the step just taken, on the fire grid. More...

virtual amrex::Real	smoke_heat_per_kg () const =0
	Heat released per kilogram of fuel burned [J/kg], matching the sensible flux last handed over, to turn it into the fuel burnt that the smoke emission factor applies to. More...

virtual bool	wants_surface_precip () const
	The engine needs the surface precipitation accumulation in FireForcing. More...

virtual bool	needs_surface_layer () const
	The engine needs a surface layer at the bottom boundary. More...

virtual const amrex::MultiFab *	heat_open_fraction_atm () const
	Optional heat placement per atmospheric column, for erf.fire.heat_open_fraction: the fraction of the column's footprint open to the air [0-1] and the mean roof height of the rest [m], on the k = 0 slabs of the fire grid's level with one ghost cell: one slab per box of the level, in the level's box order and on its DistributionMapping (the coupling reads them with the level's MFIter and stops otherwise). nullptr when the engine has no such blocking. More...

virtual const amrex::MultiFab *	roof_height_atm () const

virtual void	write_checkpoint (const std::string &checkpointname) const
	Write the engine's own state to the checkpoint directory. More...

virtual void	read_checkpoint (const std::string &restart_chkfile, int max_level, int step)
	Restore the engine's state from a checkpoint on a restart. More...

virtual void	write_plotfile (const std::string &plotfile_prefix, amrex::Real time, int step) const
	Write the engine's plotfile of the fire grid. More...

virtual std::vector< std::string >	plot_var_names () const
	Fire fields the ERF plotfile can carry, by name. More...

virtual const amrex::MultiFab *	plot_var (const std::string &name) const
	The field plot_var_names() lists as name, on the fire grid. More...

virtual amrex::Real	burned_area () const
	Area burned so far [m2], for the run log; negative when the engine does not track it. More...

virtual const amrex::MultiFab *	level_set () const
	Level set on the fire grid, negative where burned; nullptr if the engine has none. More...

virtual const amrex::MultiFab *	reference_wind () const
	Wind (u, v) [m/s] the engine sampled at reference_wind_height() on the fire grid; nullptr if none. More...

virtual amrex::Real	reference_wind_height () const
	Height above ground [m] of reference_wind(). More...

virtual const amrex::MultiFab *	heat_release () const

Detailed Description

A fire engine behind the shared coupling layer.

The coupling calls, in this order:

verify_prerequisites() once at start-up, after its own checks of the ERF configuration and before it builds the fire grid;
initialize() once, with the fire grid built, then start_run();
read_checkpoint() on a restart, right after start_run();
advance() then fill_fluxes() once per step of the fire grid's level, after that level's dycore;
smoke_heat_per_kg(), heat_open_fraction_atm() and roof_height_atm() when it injects the lagged fluxes, at every Runge-Kutta stage of the next step;
write_plotfile() on the fire plotfile schedule (erf.fire.plot_int, erf.fire.plot_per), and write_checkpoint() from FireCoupler::write_checkpoint when ERF writes a checkpoint;
plot_var_names() once, when the coupler is constructed (before verify_prerequisites), and plot_var() each time ERF writes its own plotfile, for the fire fields that file carries.

The getters at the end (level set, reference wind, heat release) are what other surface models may read from the fire (a dust or smoke source model, for example); an engine that has none returns nullptr and those couplings do nothing.

Constructor & Destructor Documentation

◆ ~FireEngine()

virtual FireEngine::~FireEngine ( )

virtualdefault

Member Function Documentation

◆ advance()

virtual void FireEngine::advance ( const FireForcing & forcing )

pure virtual

Advance the fire over one step of its level.

Implemented in FireEngineTemplate.

◆ burned_area()

virtual amrex::Real FireEngine::burned_area ( ) const

inlinevirtual

Area burned so far [m2], for the run log; negative when the engine does not track it.

Reimplemented in FireEngineTemplate.

296 { return amrex::Real(-1.0); }

Real

amrex::Real Real

Definition: ERF_ShocInterface.H:19

◆ fill_fluxes()

virtual void FireEngine::fill_fluxes ( FireFluxes & fluxes )

pure virtual

The fluxes of the step just taken, on the fire grid.

Means over exactly [forcing.time, forcing.time + forcing.dt] of the last advance() (see FireFluxes). Called after advance(), only when the coupling injects heat or smoke.

Implemented in FireEngineTemplate.

◆ heat_open_fraction_atm()

virtual const amrex::MultiFab* FireEngine::heat_open_fraction_atm ( ) const

inlinevirtual

Optional heat placement per atmospheric column, for erf.fire.heat_open_fraction: the fraction of the column's footprint open to the air [0-1] and the mean roof height of the rest [m], on the k = 0 slabs of the fire grid's level with one ghost cell: one slab per box of the level, in the level's box order and on its DistributionMapping (the coupling reads them with the level's MFIter and stops otherwise). nullptr when the engine has no such blocking.

Reimplemented in FireEngineTemplate.

222 { return nullptr; }

◆ heat_release()

virtual const amrex::MultiFab* FireEngine::heat_release ( ) const

inlinevirtual

Heat released by the fire on the fire grid [W/m2], before any partition into sensible and latent flux; nullptr if the engine has none.

Reimplemented in FireEngineTemplate.

306 { return nullptr; }

◆ initialize()

virtual void FireEngine::initialize	(	const ERF &	erf,
		int	lev,
		const FireGrid &	fg,
		const SurfaceLayer *	surface_layer,
		const amrex::MultiFab *	z_phys_nd_atm
	)

pure virtual

Set the engine up on the fire grid.

Parameters

[in]	erf	ERF instance (public AmrCore accessors only)
[in]	lev	The level the fire grid refines
[in]	fg	The fire grid the coupling built
[in]	surface_layer	The bottom surface layer; never null when needs_surface_layer() is true, and nullptr when it is false and the bottom boundary is not one
[in]	z_phys_nd_atm	Nodal height of level lev [m] (ERF always passes it)

Implemented in FireEngineTemplate.

◆ level_set()

virtual const amrex::MultiFab* FireEngine::level_set ( ) const

inlinevirtual

Level set on the fire grid, negative where burned; nullptr if the engine has none.

Reimplemented in FireEngineTemplate.

299 { return nullptr; }

◆ name()

virtual const char* FireEngine::name ( ) const

pure virtual

Name of the engine, as erf.fire.engine selects it.

Implemented in FireEngineTemplate.

Referenced by plot_var(), and read_checkpoint().

Here is the caller graph for this function:

◆ needs_surface_layer()

virtual bool FireEngine::needs_surface_layer ( ) const

inlinevirtual

The engine needs a surface layer at the bottom boundary.

True by default: the coupling then stops at start-up unless zlo.type = surface_layer. An engine that reads nothing from the surface layer (it takes the wind and heights from FireForcing alone) returns false and may run over any bottom boundary.

Reimplemented in FireEngineTemplate.

210 { return true; }

◆ plot_var()

virtual const amrex::MultiFab* FireEngine::plot_var ( const std::string & name ) const

inlinevirtual

The field plot_var_names() lists as name, on the fire grid.

One component, on FireGrid::ba and FireGrid::dm, valid until the next advance(). The coupler averages it over each atmospheric column (the grid_ratio^2 fire cells under it) and writes it into the k = 0 layer of the ERF plotfile, zero elsewhere. nullptr writes zeros.

Reimplemented in FireEngineTemplate.

     {
         amrex::ignore_unused(name);
         return nullptr;
     }

Here is the call graph for this function:

◆ plot_var_names()

virtual std::vector<std::string> FireEngine::plot_var_names ( ) const

inlinevirtual

Fire fields the ERF plotfile can carry, by name.

The names the deck may list in erf.plot_vars_* (for example "fire_phi", "fire_heat_flux"); they should start with "fire_" so they never collide with an ERF variable. The coupler asks once, when it is constructed: before initialize() and before ERF reads its plot variable lists, so the answer depends on the engine's inputs only. The default lists none.

Reimplemented in FireEngineTemplate.

279 { return {}; }

◆ read_checkpoint()

virtual void FireEngine::read_checkpoint	(	const std::string &	restart_chkfile,
		int	max_level,
		int	step
	)

inlinevirtual

Restore the engine's state from a checkpoint on a restart.

Parameters

[in]	restart_chkfile	The checkpoint directory
[in]	max_level	ERF's max_level (the levels to look for the fire state on)
[in]	step	The step count of the fire grid's level at the checkpoint

The default stops the run: an engine that does not implement restart says so instead of continuing from its initial state.

Reimplemented in FireEngineTemplate.

     {
         amrex::ignore_unused(restart_chkfile, max_level, step);
         amrex::Abort(std::string("[FIRE] fire engine \"") + name()
                      + "\" does not support restart from a checkpoint");
     }

Here is the call graph for this function:

◆ reference_wind()

virtual const amrex::MultiFab* FireEngine::reference_wind ( ) const

inlinevirtual

Wind (u, v) [m/s] the engine sampled at reference_wind_height() on the fire grid; nullptr if none.

Reimplemented in FireEngineTemplate.

301 { return nullptr; }

◆ reference_wind_height()

virtual amrex::Real FireEngine::reference_wind_height ( ) const

inlinevirtual

Height above ground [m] of reference_wind().

Reimplemented in FireEngineTemplate.

303 { return amrex::Real(0.0); }

◆ roof_height_atm()

virtual const amrex::MultiFab* FireEngine::roof_height_atm ( ) const

inlinevirtual

Reimplemented in FireEngineTemplate.

223 { return nullptr; }

◆ smoke_heat_per_kg()

virtual amrex::Real FireEngine::smoke_heat_per_kg ( ) const

pure virtual

Heat released per kilogram of fuel burned [J/kg], matching the sensible flux last handed over, to turn it into the fuel burnt that the smoke emission factor applies to.

Implemented in FireEngineTemplate.

◆ start_run()

virtual void FireEngine::start_run	(	amrex::Real	stop_time,
		int	max_step,
		int	steps_per_coarse_step
	)

inlinevirtual

Start-up after initialize(), once the run's end is known.

Parameters

[in]	stop_time	ERF's stop_time [s] (numeric_limits max when unset)
[in]	max_step	ERF's max_step, counting level-0 steps (negative when unset)
[in]	steps_per_coarse_step	Steps of the fire grid's level per level-0 step

Reimplemented in FireEngineTemplate.

     {
         amrex::ignore_unused(stop_time, max_step, steps_per_coarse_step);
     }

◆ verify_prerequisites()

virtual void FireEngine::verify_prerequisites	(	const ERF &	erf,
		int	lev
	)

pure virtual

Check the engine's own inputs against the ERF configuration.

Called once at start-up, after the coupling's checks of the grid (verify_fire_prerequisites) and before the fire grid is built. Aborts, naming the input, on a configuration the engine cannot run.

Parameters

[in]	erf	ERF instance (public AmrCore accessors only)
[in]	lev	The level the fire grid refines

Implemented in FireEngineTemplate.

◆ wants_surface_precip()

virtual bool FireEngine::wants_surface_precip ( ) const

inlinevirtual

The engine needs the surface precipitation accumulation in FireForcing.

Reimplemented in FireEngineTemplate.

200 { return false; }

◆ write_checkpoint()

virtual void FireEngine::write_checkpoint ( const std::string & checkpointname ) const

inlinevirtual

Write the engine's own state to the checkpoint directory.

Everything the engine carries from one step to the next, under checkpointname/Level_<lev>/ of the fire grid's level. Called by FireCoupler::write_checkpoint, which then writes the lagged fluxes. The default writes nothing; such an engine cannot restart (read_checkpoint).

Reimplemented in FireEngineTemplate.

     {
         amrex::ignore_unused(checkpointname);
     }

◆ write_plotfile()

virtual void FireEngine::write_plotfile	(	const std::string &	plotfile_prefix,
		amrex::Real	time,
		int	step
	)		const

inlinevirtual

Write the engine's plotfile of the fire grid.

Parameters

[in]	plotfile_prefix	erf.fire.plot_file (the step is appended)
[in]	time	Simulation time [s]
[in]	step	Level-0 step number

The default writes nothing (the engine's fields may still reach the ERF plotfile through plot_var_names()).

Reimplemented in FireEngineTemplate.

     {
         amrex::ignore_unused(plotfile_prefix, time, step);
     }

The documentation for this class was generated from the following file:

Source/FireCoupling/ERF_FireEngine.H

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~FireEngine()

Member Function Documentation

◆ advance()

◆ burned_area()

◆ fill_fluxes()

◆ heat_open_fraction_atm()

◆ heat_release()

◆ initialize()

◆ level_set()

◆ name()

◆ needs_surface_layer()

◆ plot_var()

◆ plot_var_names()

◆ read_checkpoint()

◆ reference_wind()

◆ reference_wind_height()

◆ roof_height_atm()

◆ smoke_heat_per_kg()

◆ start_run()

◆ verify_prerequisites()

◆ wants_surface_precip()

◆ write_checkpoint()

◆ write_plotfile()