CSV backend for catchment output. More...

#include <CatchmentCsvOutputMgr.hpp>

Inheritance diagram for utils::CatchmentCsvOutputMgr:

Collaboration diagram for utils::CatchmentCsvOutputMgr:

Public Member Functions
	CatchmentCsvOutputMgr (std::string output_root, std::optional< std::string > aggregated_filename, int precision, std::vector< FeatureDescriptor > descriptors)

	~CatchmentCsvOutputMgr () override

void	receive_data_entry (const std::string &formulation_id, const std::string &catchment_id, const time_marker &data_time_marker, const std::vector< double > &values) override
	Receive a data entry for a catchment at a given simulation time, specifying the formulation id.

void	commit_writes () override
	Flush any data buffered since the last commit out to the underlying sink.

void	close () override
	Close down this manager: commit everything received, finalize the output, and close files.

bool	is_closed () override
	A test of whether this instance is closed.

virtual void	receive_data_entry (const std::string &catchment_id, const time_marker &data_time_marker, const std::vector< double > &values)
	Receive a data entry for a catchment using the default formulation id.

Static Public Member Functions
static std::string	default_formulation_id ()
	The formulation id used when a caller omits one (the common single-formulation case).

Private Member Functions
std::filesystem::path	output_path (const std::string &formulation_id, const std::string &catchment_id)
	Resolve the output file path for a (formulation, catchment).

std::ofstream *	stream_for (const std::string &formulation_id, const std::string &catchment_id)
	Resolve the stream a (formulation, catchment)'s rows are written to, or nullptr if not registered.

void	add_feature (const FeatureDescriptor &descriptor)
	Open the file(s) and write the header for one descriptor; called for each at construction.

Private Attributes
const std::string	output_root_

const std::optional< std::string >	aggregated_filename_

const int	precision_

bool	closed_ = false

std::unordered_map< std::filesystem::path, std::shared_ptr< std::ofstream > >	streams_

Detailed Description

CSV backend for catchment output.

A single map of open output streams, keyed by resolved file path, backs both groupings:

per-feature: one file per (formulation, catchment).
aggregated: the catchments of a formulation share one file (the aggregated filename), with a leading catchment_id column; the header is written once per file. In both cases the default formulation id keeps the flat "<output_root><name>" layout, and any other formulation id is placed in a "<output_root><formulation_id>/" subdirectory – so independent formulation setups never collide, and each aggregated file holds a single formulation's (uniform) column set.

Rows are written immediately on receipt (commit_writes only flushes). Values are rendered to text at a uniform significant-digit precision fixed at construction.

Constructor & Destructor Documentation

◆ CatchmentCsvOutputMgr()

CatchmentCsvOutputMgr::CatchmentCsvOutputMgr	(	std::string	output_root,
		std::optional< std::string >	aggregated_filename,
		int	precision,
		std::vector< FeatureDescriptor >	descriptors )

Parameters

output_root	The directory to write into: a resolved path with a trailing slash (as produced by realization::config normalization, e.g. "./" or "out/rank_3/"), not a filename prefix. Created here (along with any per-formulation subdirectories) if it does not exist, so callers need not pre-create it.
aggregated_filename	File name used for each formulation's shared file when `aggregate` is true (e.g. "cat_output.csv", or "cat_rank_<N>.csv" for a per-rank MPI file). When present, the catchments of each formulation share one aggregated file (the catchment id becomes a leading column); nullopt is one file per catchment.
precision	Significant digits applied uniformly when rendering all values to text.
descriptors	The full set of catchments (and their fields) this manager will write; files are opened and headers written for all of them here, so the manager is ready to receive data immediately after construction.

References add_feature().

◆ ~CatchmentCsvOutputMgr()

CatchmentCsvOutputMgr::~CatchmentCsvOutputMgr ( )

override

References close().

Member Function Documentation

◆ add_feature()

void CatchmentCsvOutputMgr::add_feature ( const FeatureDescriptor & descriptor )

private

Open the file(s) and write the header for one descriptor; called for each at construction.

References aggregated_filename_, utils::FeatureDescriptor::catchment_id, utils::FeatureDescriptor::fields, utils::FeatureDescriptor::formulation_id, output_path(), precision_, and streams_.

Referenced by CatchmentCsvOutputMgr().

◆ close()

void CatchmentCsvOutputMgr::close ( )

overridevirtual

Close down this manager: commit everything received, finalize the output, and close files.

The expected shape is close() == commit_writes (flush all received data) followed by finalizing and closing the sink, so callers never need a separate commit_writes() before close(). commit_writes() remains available for mid-run flushes.

close() is the point at which a commit/finalize failure is reported, so it may throw; call it explicitly if you need to observe such errors. A backend's destructor should still call close() as a best-effort backstop, but must never let an exception escape the destructor.

Once closed, a manager cannot receive new data; subsequent receive_data_entry calls should throw. close() is idempotent – calling it on an already-closed instance returns.

Implements utils::CatchmentOutputsMgr.

References closed_, commit_writes(), and streams_.

Referenced by ~CatchmentCsvOutputMgr().

◆ commit_writes()

void CatchmentCsvOutputMgr::commit_writes ( )

overridevirtual

Flush any data buffered since the last commit out to the underlying sink.

A backend that writes eagerly (relying on its own stream buffering) may do little here beyond a flush; one that batches writes accumulated entries now. This is an optional mid-run durability checkpoint – close performs a final commit regardless.

Implements utils::CatchmentOutputsMgr.

References closed_, and streams_.

Referenced by close().

◆ default_formulation_id()

static std::string utils::CatchmentOutputsMgr::default_formulation_id ( )

inlinestaticinherited

The formulation id used when a caller omits one (the common single-formulation case).

Carrying a formulation id lets a simulation run independent formulation setups over the same catchment without their output colliding; backends may organize output by formulation (e.g. a per-formulation file or subdirectory).

Referenced by output_path(), and utils::CatchmentOutputsMgr::receive_data_entry().

◆ is_closed()

bool CatchmentCsvOutputMgr::is_closed ( )

overridevirtual

A test of whether this instance is closed.

Mirrors the sibling NexusOutputsMgr interface, where backends use it as a guard against writing after close; kept here for parity across the two hierarchies.

Returns: Whether this instance is closed.

See also: close

Implements utils::CatchmentOutputsMgr.

References closed_.

◆ output_path()

std::filesystem::path CatchmentCsvOutputMgr::output_path	(	const std::string &	formulation_id,
		const std::string &	catchment_id )

private

Resolve the output file path for a (formulation, catchment).

The file name is the catchment ("<catchment>.csv") per-feature, or the shared aggregated filename when aggregating; the default formulation id keeps the flat "<root><name>" layout, any other id nests under "<root><formulation>/".

References aggregated_filename_, utils::CatchmentOutputsMgr::default_formulation_id(), and output_root_.

Referenced by add_feature(), and stream_for().

◆ receive_data_entry() [1/2]

virtual void utils::CatchmentOutputsMgr::receive_data_entry	(	const std::string &	catchment_id,
		const time_marker &	data_time_marker,
		const std::vector< double > &	values )

inlinevirtual

Receive a data entry for a catchment using the default formulation id.

See also: default_formulation_id

Reimplemented from utils::CatchmentOutputsMgr.

◆ receive_data_entry() [2/2]

void CatchmentCsvOutputMgr::receive_data_entry	(	const std::string &	formulation_id,
		const std::string &	catchment_id,
		const time_marker &	data_time_marker,
		const std::vector< double > &	values )

overridevirtual

Receive a data entry for a catchment at a given simulation time, specifying the formulation id.

Parameters

formulation_id	The id of the formulation involved in producing this data.
catchment_id	The id for the catchment to which this data applies.
data_time_marker	A marker for the current simulation time for the data.
values	The catchment's output values for this time, positionally aligned with the columns the manager was constructed with. Values cross this boundary as typed doubles for the backend to serialize as it sees fit – no string formatting or parsing.

Implements utils::CatchmentOutputsMgr.

References aggregated_filename_, closed_, utils::time_marker::sim_time_index, stream_for(), and utils::time_marker::time_stamp.

◆ stream_for()

std::ofstream * CatchmentCsvOutputMgr::stream_for	(	const std::string &	formulation_id,
		const std::string &	catchment_id )

private

Resolve the stream a (formulation, catchment)'s rows are written to, or nullptr if not registered.

References output_path(), and streams_.

Referenced by receive_data_entry().

Member Data Documentation

◆ aggregated_filename_

const std::optional<std::string> utils::CatchmentCsvOutputMgr::aggregated_filename_

private

Referenced by add_feature(), output_path(), and receive_data_entry().

◆ closed_

bool utils::CatchmentCsvOutputMgr::closed_ = false

private

Referenced by close(), commit_writes(), is_closed(), and receive_data_entry().

◆ output_root_

const std::string utils::CatchmentCsvOutputMgr::output_root_

private

Referenced by output_path().

◆ precision_

const int utils::CatchmentCsvOutputMgr::precision_

private

Referenced by add_feature().

◆ streams_

std::unordered_map<std::filesystem::path, std::shared_ptr<std::ofstream> > utils::CatchmentCsvOutputMgr::streams_

private

Referenced by add_feature(), close(), commit_writes(), and stream_for().

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

include/utilities/output/CatchmentCsvOutputMgr.hpp
src/utilities/output/CatchmentCsvOutputMgr.cpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CatchmentCsvOutputMgr()

◆ ~CatchmentCsvOutputMgr()

Member Function Documentation

◆ add_feature()

◆ close()

◆ commit_writes()

◆ default_formulation_id()

◆ is_closed()

◆ output_path()

◆ receive_data_entry() [1/2]

◆ receive_data_entry() [2/2]

◆ stream_for()

Member Data Documentation

◆ aggregated_filename_

◆ closed_

◆ output_root_

◆ precision_

◆ streams_