models::bmi::protocols::NgenDeserializationProtocol Class Reference

#include <deserialization.hpp>

Inheritance diagram for models::bmi::protocols::NgenDeserializationProtocol:

Collaboration diagram for models::bmi::protocols::NgenDeserializationProtocol:

Public Member Functions
	NgenDeserializationProtocol (const ModelPtr &model, const Properties &properties)
	Restore-side state deserialization protocol.
	NgenDeserializationProtocol ()
virtual	~NgenDeserializationProtocol () 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 BMI protocol against the given model.
nsel_NODISCARD auto	check_support (const ModelPtr &model) -> expected< void, ProtocolError > override
	Check if the BMI protocol is supported by the model.
auto	initialize (const ModelPtr &model, const Properties &properties) -> expected< void, ProtocolError > override
	Parse top-level path and the restore sub-block.
bool	is_supported () const override final
	Whether the protocol is supported by the model.

Private Attributes
bool	by_timestamp = false
int64_t	target_simulation_timestamp = 0
bool	step_latest = true
int	target_step = 0
::ngen::serialization::IdPredicate	id_scope
bool	supported = false
bool	check
bool	is_fatal
std::shared_ptr<::ngen::serialization::RecordBackend >	backend_

Constructor & Destructor Documentation

NgenDeserializationProtocol() [1/2]

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

Restore-side state deserialization protocol.

Sibling of NgenSerializationProtocol. At run(), opens a Reader on the protocol's RecordBackend, looks up a Record matching the Context's id and the configured step/timestamp selector, and writes the payload bytes to the model via SetValue(ngen::serialization_state, ...).

The protocol does not care about the simulation's current time step — restore is a one-shot operation and the caller decides at which lifecycle point to invoke it. The protocol does not track whether it has already fired: a second run() call re-opens a Reader, looks up the same record (the match-mode config is set once in initialize() and never changes), and re-applies the same payload bytes to the model — effectively rewinding it to the restore point. Callers that want "restore once" should invoke the protocol a single time.

To restore from a different record later in the run (e.g. a multi-phase driver advancing to a later checkpoint without rewinding), construct a separate NgenDeserializationProtocol instance configured for the new target step/timestamp. Each instance carries its own match-mode state and its own backend handle; they are independent. Reusing one instance with a different config in mind is not supported — initialize() is the only place the match mode is set.

Scope filtering applies at two layers:

• Index scope: an optional id_subset passed at initialize() time registers this caller's contribution to the backend's index scope. Records outside the union of every registered scope are never indexed.
• Read scope: each run() opens a Reader for the current ctx.id — the one feature the caller is asking about. The Reader cannot return any other id's record.

References initialize().

NgenDeserializationProtocol() [2/2]

models::bmi::protocols::NgenDeserializationProtocol::NgenDeserializationProtocol

(

)

~NgenDeserializationProtocol()

models::bmi::protocols::NgenDeserializationProtocol::~NgenDeserializationProtocol ( )

overridevirtualdefault

Member Function Documentation

check_support()

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

overrideprivatevirtual

Check if the BMI protocol is supported by the model.

It is the caller's responsibility to ensure that the model provided is consistent with the model provided to the object's initialize() and run() methods, hence the protected nature of this function.

Parameters

model

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

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::INTEGRATION_ERROR, models::bmi::protocols::RESERVED_VARS, 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(), and models::bmi::protocols::NgenSerializationProtocol::run().

initialize()

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

overrideprivatevirtual

Parse top-level path and the restore sub-block.

Recognized keys: serialization.path (string, required when restore.check is true) serialization.restore.check (bool, default true when restore block present) serialization.restore.fatal (bool, default true) serialization.restore.step ("latest" or int, default "latest") serialization.restore.timestamp (string, optional; wins over step if set) serialization.restore.id_subset (array of strings, optional; caps index memory)

Absent top-level block or absent restore sub-block disables the protocol silently.

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

References ngen::serialization::FileBackend::create(), models::bmi::protocols::DESERIALIZATION_ID_SUBSET_KEY, models::bmi::protocols::DESERIALIZATION_RESTORE_KEY, models::bmi::protocols::DESERIALIZATION_STEP_KEY, models::bmi::protocols::DESERIALIZATION_STEP_LATEST, models::bmi::protocols::DESERIALIZATION_TIMESTAMP_KEY, models::bmi::protocols::INTEGRATION_ERROR, models::bmi::protocols::PROTOCOL_ERROR, models::bmi::protocols::PROTOCOL_WARNING, models::bmi::protocols::SERIALIZATION_CHECK_KEY, models::bmi::protocols::SERIALIZATION_CONFIGURATION_KEY, models::bmi::protocols::SERIALIZATION_FATAL_KEY, models::bmi::protocols::SERIALIZATION_PATH_KEY, and ngen::serialization::UNPARSEABLE_TIMESTAMP_SENTINEL.

Referenced by NgenDeserializationProtocol().

is_supported()

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

finaloverrideprivatevirtual

Whether the protocol is supported by the model.

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

References supported.

run()

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

overrideprivatevirtual

Run the BMI protocol against the given model.

Execute the logic of the protocol with the provided context and model. It is the caller's responsibility to ensure that the model provided is consistent with the model provided to the object's initialize() and check_support() methods, hence the protected nature of this function.

Parameters

ctx	Contextual information for the protocol run
model	A shared pointer to a Bmi_Adapter object which should be initialized before being passed to this method.

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 ngen::serialization::exact_id(), models::bmi::protocols::PROTOCOL_ERROR, models::bmi::protocols::PROTOCOL_WARNING, models::bmi::protocols::SERIALIZATION_SIZE_NAME, models::bmi::protocols::SERIALIZATION_STATE_NAME, and models::bmi::protocols::UNITIALIZED_MODEL.

Member Data Documentation

backend_

std::shared_ptr<::ngen::serialization::RecordBackend> models::bmi::protocols::NgenDeserializationProtocol::backend_

private

by_timestamp

bool models::bmi::protocols::NgenDeserializationProtocol::by_timestamp = false

private

check

bool models::bmi::protocols::NgenDeserializationProtocol::check

private

id_scope

::ngen::serialization::IdPredicate models::bmi::protocols::NgenDeserializationProtocol::id_scope

private

is_fatal

bool models::bmi::protocols::NgenDeserializationProtocol::is_fatal

private

step_latest

bool models::bmi::protocols::NgenDeserializationProtocol::step_latest = true

private

supported

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

private

Referenced by is_supported().

target_simulation_timestamp

int64_t models::bmi::protocols::NgenDeserializationProtocol::target_simulation_timestamp = 0

private

target_step

int models::bmi::protocols::NgenDeserializationProtocol::target_step = 0

private

---

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

• include/utilities/bmi/deserialization.hpp
• src/utilities/bmi/deserialization.cpp