Namespaces
namespace	anonymous_namespace{deserialization.cpp}

namespace	anonymous_namespace{serialization.cpp}

namespace	serialization

Classes
struct	Context

class	NgenBmiProtocol

class	NgenBmiProtocols

class	NgenDeserializationProtocol

class	NgenMassBalance

class	NgenSerializationProtocol

class	ProtocolError

struct	ReservedVar
	(Reserved-name, expected-unit-string) pair used by both the save and restore protocols' `check_support` probes. More...

Typedefs
using	ModelPtr = std::shared_ptr<models::bmi::Bmi_Adapter>

using	Properties = geojson::PropertyMap

using	SerializationRecord = ::ngen::serialization::Record

using	SerializationRecordView = ::ngen::serialization::RecordView

Enumerations
enum class	Error { UNITIALIZED_MODEL , UNSUPPORTED_PROTOCOL , INTEGRATION_ERROR , PROTOCOL_ERROR , PROTOCOL_WARNING }

enum class	Protocol { MASS_BALANCE , SERIALIZATION , DESERIALIZATION }

Functions
auto	operator<< (std::ostream &os, Protocol p) -> std::ostream &

auto	read_validated_prefix (std::istream &in, serialization::wire_format::RecordPrefix &prefix) -> expected< Status, std::string >

nsel_NODISCARD auto	write_record (std::ostream &out, const SerializationRecordView &rec) -> expected< void, std::string >
	Append a record to `out` using the v0.2 wire format (fixed-size prefix + id bytes + payload bytes).

nsel_NODISCARD auto	write_record (std::ostream &out, const SerializationRecord &rec) -> expected< void, std::string >
	Overload accepting an owning `SerializationRecord`.

nsel_NODISCARD auto	read_next_record (std::istream &in, SerializationRecord &rec) -> expected< Status, std::string >
	Read the next record from `in`.

nsel_NODISCARD auto	read_record_length (std::istream &in, uint64_t &body_out) -> expected< Status, std::string >
	Read the prefix at the current stream position and report the record's body length (id bytes + payload bytes) without reading either.

nsel_NODISCARD auto	read_record_metadata (std::istream &in, serialization::wire_format::RecordPrefix &prefix_out, std::string &id_out) -> expected< Status, std::string >
	Read the prefix and id at the current stream position and skip past the payload, leaving `in` positioned at the start of the next record (or at EOF).

Variables
const int	BMI_SUCCESS = 0

const int	BMI_FAILURE = 1

const int	MAX_COMPONENT_NAME = 2048

const int	MAX_VAR_NAME = 2048

const int	MAX_UNITS_NAME = 2048

const int	MAX_TYPE_NAME = 2048

const int	MAX_LOCATION_NAME = 2048

constexpr const char *const	DESERIALIZATION_RESTORE_KEY = "restore"
	Restore-side sub-block key under the top-level `serialization` block.

constexpr const char *const	DESERIALIZATION_STEP_KEY = "step"
	Restore-side "which step to load" key.

constexpr const char *const	DESERIALIZATION_STEP_LATEST = "latest"
	Sentinel value for `step` meaning "latest step present for this id".

constexpr const char *const	DESERIALIZATION_TIMESTAMP_KEY = "timestamp"
	Restore-side "match by simulation timestamp" key.

constexpr const char *const	DESERIALIZATION_ID_SUBSET_KEY = "id_subset"
	Optional restore-side list of ids to index.

constexpr const char *const	INPUT_MASS_NAME = "ngen::mass_in"
	Mass balance variable names.

constexpr const char *const	OUTPUT_MASS_NAME = "ngen::mass_out"

constexpr const char *const	STORED_MASS_NAME = "ngen::mass_stored"

constexpr const char *const	LEAKED_MASS_NAME = "ngen::mass_leaked"

constexpr const char *const	CONFIGURATION_KEY = "mass_balance"
	Configuration keys for defining configurable properties of the protocol.

constexpr const char *const	TOLERANCE_KEY = "tolerance"

constexpr const char *const	FATAL_KEY = "fatal"

constexpr const char *const	CHECK_KEY = "check"

constexpr const char *const	FREQUENCY_KEY = "frequency"

constexpr const char *const	SERIALIZATION_CREATE_NAME = "ngen::serialization_create"
	Reserved BMI variable names driving the protocol's capture sequence.

constexpr const char *const	SERIALIZATION_FREE_NAME = "ngen::serialization_free"

constexpr const char *const	SERIALIZATION_SIZE_NAME = "ngen::serialization_size"

constexpr const char *const	SERIALIZATION_STATE_NAME = "ngen::serialization_state"

constexpr const char *const	SERIALIZATION_CONFIGURATION_KEY = "serialization"
	Top-level configuration key.

constexpr const char *const	SERIALIZATION_PATH_KEY = "path"
	Shared path key at the top-level block.

constexpr const char *const	SERIALIZATION_SAVE_KEY = "save"
	Save-side sub-block key.

constexpr const char *const	SERIALIZATION_CHECK_KEY = "check"
	Save-side / restore-side shared sub-keys.

constexpr const char *const	SERIALIZATION_FATAL_KEY = "fatal"

constexpr const char *const	SERIALIZATION_FREQUENCY_KEY = "frequency"

constexpr ReservedVar	RESERVED_VARS []

constexpr uint64_t	MAX_RECORD_PAYLOAD_BYTES = NGEN_BMI_MAX_RECORD_PAYLOAD_BYTES

Typedef Documentation

◆ ModelPtr

using models::bmi::protocols::ModelPtr = std::shared_ptr<models::bmi::Bmi_Adapter>

◆ Properties

using models::bmi::protocols::Properties = geojson::PropertyMap

◆ SerializationRecord

using models::bmi::protocols::SerializationRecord = ::ngen::serialization::Record

◆ SerializationRecordView

using models::bmi::protocols::SerializationRecordView = ::ngen::serialization::RecordView

Enumeration Type Documentation

◆ Error

enum class models::bmi::protocols::Error

strong

Enumerator
UNITIALIZED_MODEL
UNSUPPORTED_PROTOCOL
INTEGRATION_ERROR
PROTOCOL_ERROR
PROTOCOL_WARNING

◆ Protocol

enum class models::bmi::protocols::Protocol

strong

Enumerator
MASS_BALANCE
SERIALIZATION
DESERIALIZATION

Function Documentation

◆ operator<<()

auto models::bmi::protocols::operator<<	(	std::ostream &	os,
		Protocol	p ) -> std::ostream&

References DESERIALIZATION, MASS_BALANCE, and SERIALIZATION.

◆ read_next_record()

nsel_NODISCARD auto models::bmi::protocols::read_next_record	(	std::istream &	in,
		SerializationRecord &	rec ) -> expected<Status, std::string>

inline

Read the next record from in.

Returns: Status::Ok if a full record was read; Status::Eof if the stream was at EOF before reading began OR if the stream ended mid-record (truncation in the prefix, the id, or the payload) — torn files therefore stop cleanly at the last intact record. Error arm if the prefix's magic bytes are wrong, the wire_version is unsupported, or payload_length exceeds MAX_RECORD_PAYLOAD_BYTES.

References models::bmi::protocols::serialization::wire_format::RecordPrefix::checkpoint_epoch, models::bmi::protocols::serialization::wire_format::Eof, models::bmi::protocols::serialization::wire_format::RecordPrefix::id_length, models::bmi::protocols::serialization::wire_format::Ok, models::bmi::protocols::serialization::wire_format::RecordPrefix::payload_length, read_validated_prefix(), models::bmi::protocols::serialization::wire_format::RecordPrefix::simulation_timestamp, and models::bmi::protocols::serialization::wire_format::RecordPrefix::time_step.

Referenced by ngen::serialization::FileBackend::Reader::load_at().

◆ read_record_length()

nsel_NODISCARD auto models::bmi::protocols::read_record_length	(	std::istream &	in,
		uint64_t &	body_out ) -> expected<Status, std::string>

inline

Read the prefix at the current stream position and report the record's body length (id bytes + payload bytes) without reading either.

Parameters

in	Input stream positioned at the start of a record (a fixed-size prefix), or at EOF.
body_out	On `Status::Ok`, populated with the number of bytes remaining in this record after the prefix — i.e. `id_length + payload_length`. A caller that wants to skip past the record without reading any of its contents calls `in.seekg(body_out, std::ios::cur)`.

Returns: Status::Ok if a full prefix was read; Status::Eof on EOF or a truncated prefix; error arm on bad magic, unsupported wire_version, or payload_length exceeding MAX_RECORD_PAYLOAD_BYTES.

References models::bmi::protocols::serialization::wire_format::Eof, models::bmi::protocols::serialization::wire_format::RecordPrefix::id_length, models::bmi::protocols::serialization::wire_format::Ok, models::bmi::protocols::serialization::wire_format::RecordPrefix::payload_length, and read_validated_prefix().

◆ read_record_metadata()

nsel_NODISCARD auto models::bmi::protocols::read_record_metadata	(	std::istream &	in,
		serialization::wire_format::RecordPrefix &	prefix_out,
		std::string &	id_out ) -> expected<Status, std::string>

inline

Read the prefix and id at the current stream position and skip past the payload, leaving in positioned at the start of the next record (or at EOF).

This is the fast walker a RecordBackend's index builder uses to construct an in-memory index without ever reading payload bytes — the cost per record is O(prefix + id_size) regardless of payload size.

Returns: Status::Ok if metadata was read AND the payload was successfully skipped; Status::Eof on EOF or any truncation; error arm on bad magic, unsupported wire_version, or payload_length exceeding MAX_RECORD_PAYLOAD_BYTES.

References models::bmi::protocols::serialization::wire_format::Eof, models::bmi::protocols::serialization::wire_format::Ok, and read_validated_prefix().

Referenced by ngen::serialization::FileBackend::Index::build().

◆ read_validated_prefix()

auto models::bmi::protocols::read_validated_prefix	(	std::istream &	in,
		serialization::wire_format::RecordPrefix &	prefix ) -> expected<Status, std::string>

inline

References models::bmi::protocols::serialization::wire_format::Eof, models::bmi::protocols::serialization::wire_format::RecordPrefix::MAGIC, MAX_RECORD_PAYLOAD_BYTES, models::bmi::protocols::serialization::wire_format::Ok, models::bmi::protocols::serialization::wire_format::read_record_prefix(), and models::bmi::protocols::serialization::wire_format::RecordPrefix::VERSION.

Referenced by read_next_record(), read_record_length(), and read_record_metadata().

◆ write_record() [1/2]

nsel_NODISCARD auto models::bmi::protocols::write_record	(	std::ostream &	out,
		const SerializationRecord &	rec ) -> expected<void, std::string>

inline

Overload accepting an owning SerializationRecord.

Identical wire output to the SerializationRecordView overload above. The body mirrors the View path because RecordView's id field is itself an owning std::string — constructing a view to delegate would force an unnecessary id-string copy. The payload type is the only field where the two records diverge, and out.write(payload.data(), payload.size()) is the same call shape for std::vector<char> and boost::span<const char>.

References models::bmi::protocols::serialization::wire_format::RecordPrefix::checkpoint_epoch, models::bmi::protocols::serialization::wire_format::RecordPrefix::id_length, models::bmi::protocols::serialization::wire_format::RecordPrefix::payload_length, models::bmi::protocols::serialization::wire_format::RecordPrefix::simulation_timestamp, models::bmi::protocols::serialization::wire_format::RecordPrefix::time_step, and models::bmi::protocols::serialization::wire_format::write_record_prefix().

◆ write_record() [2/2]

nsel_NODISCARD auto models::bmi::protocols::write_record	(	std::ostream &	out,
		const SerializationRecordView &	rec ) -> expected<void, std::string>

inline

Append a record to out using the v0.2 wire format (fixed-size prefix + id bytes + payload bytes).

Canonical entry point — takes a SerializationRecordView so callers can stream a record whose payload bytes live in a buffer they already own, without materializing a fresh owning copy.

Field mapping at the write site is identity: every prefix field comes directly from the matching record field. Callers who want a wall-clock stamp on checkpoint_epoch set it themselves (typically via std::time(nullptr)) before calling; default-constructed records carry checkpoint_epoch = 0.

Returns the error arm if the stream ends up in a fail state after the prefix / id / payload bytes are issued. The check is post-write — the caller doesn't need to inspect the stream itself.

See the overload below for the SerializationRecord (owning) variant; both produce identical wire output.

References models::bmi::protocols::serialization::wire_format::RecordPrefix::checkpoint_epoch, models::bmi::protocols::serialization::wire_format::RecordPrefix::id_length, models::bmi::protocols::serialization::wire_format::RecordPrefix::payload_length, models::bmi::protocols::serialization::wire_format::RecordPrefix::simulation_timestamp, models::bmi::protocols::serialization::wire_format::RecordPrefix::time_step, and models::bmi::protocols::serialization::wire_format::write_record_prefix().

Referenced by ngen::serialization::FileBackend::Writer::write().

Variable Documentation

◆ BMI_FAILURE

const int models::bmi::protocols::BMI_FAILURE = 1

◆ BMI_SUCCESS

const int models::bmi::protocols::BMI_SUCCESS = 0

◆ CHECK_KEY

const char* const models::bmi::protocols::CHECK_KEY = "check"

constexpr

Referenced by models::bmi::protocols::NgenMassBalance::initialize().

◆ CONFIGURATION_KEY

const char* const models::bmi::protocols::CONFIGURATION_KEY = "mass_balance"

constexpr

Configuration keys for defining configurable properties of the protocol.

Referenced by models::bmi::protocols::NgenMassBalance::initialize().

◆ DESERIALIZATION_ID_SUBSET_KEY

const char* const models::bmi::protocols::DESERIALIZATION_ID_SUBSET_KEY = "id_subset"

constexpr

Optional restore-side list of ids to index.

When present, only records whose id is in this subset are retained in the checkpoint index — useful at scale when a run only needs to restore a known subset of features out of a much larger checkpoint file.

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize().

◆ DESERIALIZATION_RESTORE_KEY

const char* const models::bmi::protocols::DESERIALIZATION_RESTORE_KEY = "restore"

constexpr

Restore-side sub-block key under the top-level serialization block.

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize().

◆ DESERIALIZATION_STEP_KEY

const char* const models::bmi::protocols::DESERIALIZATION_STEP_KEY = "step"

constexpr

Restore-side "which step to load" key.

Accepts an integer or "latest".

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize().

◆ DESERIALIZATION_STEP_LATEST

const char* const models::bmi::protocols::DESERIALIZATION_STEP_LATEST = "latest"

constexpr

Sentinel value for step meaning "latest step present for this id".

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize().

◆ DESERIALIZATION_TIMESTAMP_KEY

const char* const models::bmi::protocols::DESERIALIZATION_TIMESTAMP_KEY = "timestamp"

constexpr

Restore-side "match by simulation timestamp" key.

Parsed as an integer (seconds since epoch, or any monotone encoding the caller chose when writing) and compared against the record's timestamp field. If both timestamp and step are configured, timestamp wins.

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize().

◆ FATAL_KEY

const char* const models::bmi::protocols::FATAL_KEY = "fatal"

constexpr

Referenced by models::bmi::protocols::NgenMassBalance::initialize().

◆ FREQUENCY_KEY

const char* const models::bmi::protocols::FREQUENCY_KEY = "frequency"

constexpr

Referenced by models::bmi::protocols::NgenMassBalance::initialize().

◆ INPUT_MASS_NAME

const char* const models::bmi::protocols::INPUT_MASS_NAME = "ngen::mass_in"

constexpr

Mass balance variable names.

Referenced by models::bmi::protocols::NgenMassBalance::check_support(), and models::bmi::protocols::NgenMassBalance::run().

◆ LEAKED_MASS_NAME

const char* const models::bmi::protocols::LEAKED_MASS_NAME = "ngen::mass_leaked"

constexpr

Referenced by models::bmi::protocols::NgenMassBalance::check_support(), and models::bmi::protocols::NgenMassBalance::run().

◆ MAX_COMPONENT_NAME

const int models::bmi::protocols::MAX_COMPONENT_NAME = 2048

◆ MAX_LOCATION_NAME

const int models::bmi::protocols::MAX_LOCATION_NAME = 2048

◆ MAX_RECORD_PAYLOAD_BYTES

uint64_t models::bmi::protocols::MAX_RECORD_PAYLOAD_BYTES = NGEN_BMI_MAX_RECORD_PAYLOAD_BYTES

constexpr

Referenced by read_validated_prefix(), and ngen::serialization::FileBackend::Writer::write().

◆ MAX_TYPE_NAME

const int models::bmi::protocols::MAX_TYPE_NAME = 2048

◆ MAX_UNITS_NAME

const int models::bmi::protocols::MAX_UNITS_NAME = 2048

◆ MAX_VAR_NAME

const int models::bmi::protocols::MAX_VAR_NAME = 2048

◆ OUTPUT_MASS_NAME

const char* const models::bmi::protocols::OUTPUT_MASS_NAME = "ngen::mass_out"

constexpr

Referenced by models::bmi::protocols::NgenMassBalance::check_support(), and models::bmi::protocols::NgenMassBalance::run().

◆ RESERVED_VARS

ReservedVar models::bmi::protocols::RESERVED_VARS[]

constexpr

Initial value:

= {
    {SERIALIZATION_CREATE_NAME, "ngen::trigger"},
    {SERIALIZATION_FREE_NAME,   "ngen::trigger"},
    {SERIALIZATION_SIZE_NAME,   "bytes"        },
    {SERIALIZATION_STATE_NAME,  "ngen::opaque" },
}

Referenced by models::bmi::protocols::NgenDeserializationProtocol::check_support(), and models::bmi::protocols::NgenSerializationProtocol::check_support().

◆ SERIALIZATION_CHECK_KEY

const char* const models::bmi::protocols::SERIALIZATION_CHECK_KEY = "check"

constexpr

Save-side / restore-side shared sub-keys.

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize(), and models::bmi::protocols::NgenSerializationProtocol::initialize().

◆ SERIALIZATION_CONFIGURATION_KEY

const char* const models::bmi::protocols::SERIALIZATION_CONFIGURATION_KEY = "serialization"

constexpr

Top-level configuration key.

Shared by save and restore protocols.

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize(), and models::bmi::protocols::NgenSerializationProtocol::initialize().

◆ SERIALIZATION_CREATE_NAME

const char* const models::bmi::protocols::SERIALIZATION_CREATE_NAME = "ngen::serialization_create"

constexpr

Reserved BMI variable names driving the protocol's capture sequence.

Referenced by models::bmi::protocols::anonymous_namespace{serialization.cpp}::ScopedCapture::ScopedCapture().

◆ SERIALIZATION_FATAL_KEY

const char* const models::bmi::protocols::SERIALIZATION_FATAL_KEY = "fatal"

constexpr

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize(), and models::bmi::protocols::NgenSerializationProtocol::initialize().

◆ SERIALIZATION_FREE_NAME

const char* const models::bmi::protocols::SERIALIZATION_FREE_NAME = "ngen::serialization_free"

constexpr

Referenced by models::bmi::protocols::anonymous_namespace{serialization.cpp}::ScopedCapture::release().

◆ SERIALIZATION_FREQUENCY_KEY

const char* const models::bmi::protocols::SERIALIZATION_FREQUENCY_KEY = "frequency"

constexpr

Referenced by models::bmi::protocols::NgenSerializationProtocol::initialize().

◆ SERIALIZATION_PATH_KEY

const char* const models::bmi::protocols::SERIALIZATION_PATH_KEY = "path"

constexpr

Shared path key at the top-level block.

Referenced by models::bmi::protocols::NgenDeserializationProtocol::initialize(), and models::bmi::protocols::NgenSerializationProtocol::initialize().

◆ SERIALIZATION_SAVE_KEY

const char* const models::bmi::protocols::SERIALIZATION_SAVE_KEY = "save"

constexpr

Save-side sub-block key.

Referenced by models::bmi::protocols::NgenSerializationProtocol::initialize().

◆ SERIALIZATION_SIZE_NAME

const char* const models::bmi::protocols::SERIALIZATION_SIZE_NAME = "ngen::serialization_size"

constexpr

Referenced by models::bmi::protocols::NgenDeserializationProtocol::run(), and models::bmi::protocols::NgenSerializationProtocol::run().

◆ SERIALIZATION_STATE_NAME

const char* const models::bmi::protocols::SERIALIZATION_STATE_NAME = "ngen::serialization_state"

constexpr

Referenced by models::bmi::protocols::NgenDeserializationProtocol::run(), and models::bmi::protocols::NgenSerializationProtocol::run().

◆ STORED_MASS_NAME

const char* const models::bmi::protocols::STORED_MASS_NAME = "ngen::mass_stored"

constexpr

Referenced by models::bmi::protocols::NgenMassBalance::check_support(), and models::bmi::protocols::NgenMassBalance::run().

◆ TOLERANCE_KEY

const char* const models::bmi::protocols::TOLERANCE_KEY = "tolerance"

constexpr

Referenced by models::bmi::protocols::NgenMassBalance::initialize().

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ ModelPtr

◆ Properties

◆ SerializationRecord

◆ SerializationRecordView

Enumeration Type Documentation

◆ Error

◆ Protocol

Function Documentation

◆ operator<<()

◆ read_next_record()

◆ read_record_length()

◆ read_record_metadata()

◆ read_validated_prefix()

◆ write_record() [1/2]

◆ write_record() [2/2]

Variable Documentation

◆ BMI_FAILURE

◆ BMI_SUCCESS

◆ CHECK_KEY

◆ CONFIGURATION_KEY

◆ DESERIALIZATION_ID_SUBSET_KEY

◆ DESERIALIZATION_RESTORE_KEY

◆ DESERIALIZATION_STEP_KEY

◆ DESERIALIZATION_STEP_LATEST

◆ DESERIALIZATION_TIMESTAMP_KEY

◆ FATAL_KEY

◆ FREQUENCY_KEY

◆ INPUT_MASS_NAME

◆ LEAKED_MASS_NAME

◆ MAX_COMPONENT_NAME

◆ MAX_LOCATION_NAME

◆ MAX_RECORD_PAYLOAD_BYTES

◆ MAX_TYPE_NAME

◆ MAX_UNITS_NAME

◆ MAX_VAR_NAME

◆ OUTPUT_MASS_NAME

◆ RESERVED_VARS

◆ SERIALIZATION_CHECK_KEY

◆ SERIALIZATION_CONFIGURATION_KEY

◆ SERIALIZATION_CREATE_NAME

◆ SERIALIZATION_FATAL_KEY

◆ SERIALIZATION_FREE_NAME

◆ SERIALIZATION_FREQUENCY_KEY

◆ SERIALIZATION_PATH_KEY

◆ SERIALIZATION_SAVE_KEY

◆ SERIALIZATION_SIZE_NAME

◆ SERIALIZATION_STATE_NAME

◆ STORED_MASS_NAME

◆ TOLERANCE_KEY