#include <mass_balance.hpp>

Inheritance diagram for models::bmi::protocols::NgenMassBalance:

Collaboration diagram for models::bmi::protocols::NgenMassBalance:

Public Member Functions
	NgenMassBalance (const ModelPtr &model, const Properties &properties)
	Mass Balance protocol.

	NgenMassBalance ()
	Construct a new, default Ngen Mass Balance object.

virtual	~NgenMassBalance () override

Static Protected Member Functions
static auto	error_or_warning (const ProtocolError &err) -> expected< void, ProtocolError >
	Handle a ProtocolError by either throwing it or logging it as a warning.

Private Member Functions
auto	run (const ModelPtr &model, const Context &ctx) const -> expected< void, ProtocolError > override
	Run the mass balance protocol.

nsel_NODISCARD auto	check_support (const ModelPtr &model) -> expected< void, ProtocolError > override
	Check if the mass balance protocol is supported by the model.

auto	initialize (const ModelPtr &model, const Properties &properties) -> expected< void, ProtocolError > override
	Check the model for support and initialize the mass balance protocol from the given properties.

bool	is_supported () const override final
	Whether the protocol is supported by the model.

Private Attributes
double	tolerance

int	frequency

bool	supported = false

bool	check

bool	is_fatal

Constructor & Destructor Documentation

◆ NgenMassBalance() [1/2]

models::bmi::protocols::NgenMassBalance::NgenMassBalance	(	const ModelPtr &	model,
		const Properties &	properties )

Mass Balance protocol.

This protocol run()s a simple mass balance calculation by querying the model for a set of mass balance state variables and computing the basic mass balance as balance = mass_in - mass_out - mass_stored - mass_leaked. It is then checked against a tolerance value to determine if the mass balance is acceptable.

Constructor for the NgenMassBalance protocol

This constructor initializes the mass balance protocol with the given model and properties.

Parameters

model A shared pointer to a Bmi_Adapter object which should be initialized before being passed to this constructor.

References initialize().

◆ NgenMassBalance() [2/2]

models::bmi::protocols::NgenMassBalance::NgenMassBalance ( )

Construct a new, default Ngen Mass Balance object.

By default, the protocol is considered unsupported and won't be checked

◆ ~NgenMassBalance()

models::bmi::protocols::NgenMassBalance::~NgenMassBalance ( )

overridevirtualdefault

Member Function Documentation

◆ check_support()

auto models::bmi::protocols::NgenMassBalance::check_support ( const ModelPtr & model ) -> expected<void, ProtocolError>

overrideprivatevirtual

Check if the mass balance protocol is supported by the model.

Returns: expected<void, ProtocolError> May contain a ProtocolError if the protocol is not supported by the model.

Implements models::bmi::protocols::NgenBmiProtocol.

References models::bmi::protocols::INPUT_MASS_NAME, models::bmi::protocols::INTEGRATION_ERROR, models::bmi::protocols::LEAKED_MASS_NAME, models::bmi::protocols::OUTPUT_MASS_NAME, models::bmi::protocols::STORED_MASS_NAME, and models::bmi::protocols::UNITIALIZED_MODEL.

◆ error_or_warning()

static auto models::bmi::protocols::NgenBmiProtocol::error_or_warning ( const ProtocolError & err ) -> expected<void, ProtocolError>

inlinestaticprotectedinherited

Handle a ProtocolError by either throwing it or logging it as a warning.

Parameters

err	The ProtocolError to handle

Returns: expected<void, ProtocolError> Returns an empty expected if the error was logged as a warning, otherwise throws the ProtocolError.

Exceptions

ProtocolError if the error is of type PROTOCOL_ERROR

References models::bmi::protocols::INTEGRATION_ERROR, models::bmi::protocols::PROTOCOL_ERROR, models::bmi::protocols::PROTOCOL_WARNING, models::bmi::protocols::UNITIALIZED_MODEL, and models::bmi::protocols::UNSUPPORTED_PROTOCOL.

Referenced by models::bmi::protocols::NgenBmiProtocols::run().

◆ initialize()

auto models::bmi::protocols::NgenMassBalance::initialize	(	const ModelPtr &	model,
		const Properties &	properties ) -> expected<void, ProtocolError>

overrideprivatevirtual

Check the model for support and initialize the mass balance protocol from the given properties.

If the model does not support the mass balance protocol, an exception will be thrown, and no mass balance will performed when run() is called.

A private initialize call is used since it only makes sense to check/run the protocol once the model adapter is fully constructed. This should be called by the owner of the NgenMassBalance instance once the model is ready.

Parameters

properties Configurable key/value properties for the mass balance protocol. If the map contains "mass_balance" object, then the following properties are used to configure the protocol: tolerance: double, default 1.0E-16. check: bool, default true. Whether to perform mass balance check. frequency: int, default 1. How often (in time steps) to check mass balance. fatal: bool, default false. Whether to treat mass balance errors as fatal. Otherwise, mass balance checking will be disabled (check will be false)

Returns: expected<void, ProtocolError> May contain a ProtocolError if initialization fails for any reason, since the protocol must be effectively "optional", failed initialization results in the protocol being disabled for the duration of the simulation.

Implements models::bmi::protocols::NgenBmiProtocol.

References models::bmi::protocols::CHECK_KEY, models::bmi::protocols::CONFIGURATION_KEY, models::bmi::protocols::FATAL_KEY, models::bmi::protocols::FREQUENCY_KEY, models::bmi::protocols::PROTOCOL_WARNING, and models::bmi::protocols::TOLERANCE_KEY.

Referenced by NgenMassBalance().

◆ is_supported()

bool models::bmi::protocols::NgenMassBalance::is_supported ( ) const

finaloverrideprivatevirtual

Whether the protocol is supported by the model.

Returns: true the model exposes the required mass balance variables; false the model does not support mass balance checking via this protocol

Implements models::bmi::protocols::NgenBmiProtocol.

References supported.

◆ run()

auto models::bmi::protocols::NgenMassBalance::run	(	const ModelPtr &	model,
		const Context &	ctx ) const -> expected<void, ProtocolError>

overrideprivatevirtual

Run the mass balance protocol.

If the configured frequency is -1, the mass balance will only be checked at the end of the simulation. If the frequency is greater than 0, the mass balance will be checked at the specified frequency based on the current_time_step and the total_steps provided in the Context.

Warns or errors at each check if total mass balance is not within the configured acceptable tolerance.

Returns: expected<void, ProtocolError> May contain a ProtocolError if the protocol fails for any reason. Errors of ProtocolError::PROTOCOL_WARNING severity should be logged as warnings, but not cause the simulation to fail.

Implements models::bmi::protocols::NgenBmiProtocol.

References models::bmi::protocols::INPUT_MASS_NAME, models::bmi::protocols::LEAKED_MASS_NAME, models::bmi::protocols::OUTPUT_MASS_NAME, models::bmi::protocols::PROTOCOL_ERROR, models::bmi::protocols::PROTOCOL_WARNING, models::bmi::protocols::STORED_MASS_NAME, and models::bmi::protocols::UNITIALIZED_MODEL.

Member Data Documentation

◆ check

bool models::bmi::protocols::NgenMassBalance::check

private

◆ frequency

int models::bmi::protocols::NgenMassBalance::frequency

private

◆ is_fatal

bool models::bmi::protocols::NgenMassBalance::is_fatal

private

◆ supported

bool models::bmi::protocols::NgenMassBalance::supported = false

private

Referenced by is_supported().

◆ tolerance

double models::bmi::protocols::NgenMassBalance::tolerance

private

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

include/utilities/bmi/mass_balance.hpp
src/utilities/bmi/mass_balance.cpp

Public Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ NgenMassBalance() [1/2]

◆ NgenMassBalance() [2/2]

◆ ~NgenMassBalance()

Member Function Documentation

◆ check_support()

◆ error_or_warning()

◆ initialize()

◆ is_supported()

◆ run()

Member Data Documentation

◆ check

◆ frequency

◆ is_fatal

◆ supported

◆ tolerance