openswmm::runoff_iface::RunoffInterfaceFile Class Reference

Runoff interface file manager. More...

#include <RunoffInterface.hpp>

Collaboration diagram for openswmm::runoff_iface::RunoffInterfaceFile:

Public Member Functions
	~RunoffInterfaceFile ()
	Finalize a SAVE header and close any owned stream through close(). Close/write errors are ignored; caller first serializes outstanding IO.
int	openForWrite (const std::string &path, int n_subcatch, int n_pollut, int flow_units)
	Open/truncate a binary runoff output and write a placeholder header.
int	openForRead (const std::string &path, int n_subcatch, int n_pollut, int flow_units)
	Open a compatible native runoff file and position at its first record.
void	saveResults (const SimulationContext &ctx, double dt)
	Append one native timestep and project-unit subcatchment result record.
bool	readResults (SimulationContext &ctx, double *dt_out=nullptr)
	Restore one timestep's native runoff record with legacy unit conversions.
void	close ()
	Backpatch SAVE maxSteps then close the owned stream. Safe when closed; ignores seek/write/close failures. Stored step count narrows to int32; caller keeps it representable. Clears only fp_, retaining mode, counts, unit selection and buffer. Does not modify any simulation context.
bool	isOpen () const
	Test owned stream presence.

Detailed Description

Runoff interface file manager.

Owns a native FILE cursor; do not copy an owner with active IO. Serialize all reads/writes/close, and call open only on a closed object: open overwrites fp_ without closing an earlier stream. Binary layout is host-native and requires compatible model index order; header counts alone do not prove it.

Constructor & Destructor Documentation

~RunoffInterfaceFile()

openswmm::runoff_iface::RunoffInterfaceFile::~RunoffInterfaceFile ( )

inline

Finalize a SAVE header and close any owned stream through close(). Close/write errors are ignored; caller first serializes outstanding IO.

Here is the call graph for this function:

Member Function Documentation

close()

void openswmm::runoff_iface::RunoffInterfaceFile::close

(

)

Backpatch SAVE maxSteps then close the owned stream. Safe when closed; ignores seek/write/close failures. Stored step count narrows to int32; caller keeps it representable. Clears only fp_, retaining mode, counts, unit selection and buffer. Does not modify any simulation context.

Here is the caller graph for this function:

isOpen()

bool openswmm::runoff_iface::RunoffInterfaceFile::isOpen ( ) const

inline

Test owned stream presence.

Returns

True exactly when fp_ is nonnull, including EOF/error streams. This does not indicate mode, valid header/next record, or successful pending writes.

openForRead()

int openswmm::runoff_iface::RunoffInterfaceFile::openForRead	(	const std::string &	path,
		int	n_subcatch,
		int	n_pollut,
		int	flow_units )

Open a compatible native runoff file and position at its first record.

Parameters

path	UTF-8 filename; owner must already be closed.
n_subcatch	Expected nonnegative model count fitting int32; later ctx arrays must have at least this many compatible ordered rows.
n_pollut	Expected nonnegative count with 8+n_pollut representable and allocatable.
flow_units	Expected valid enum [0,5]; exact header equality required.

Returns

Zero after header comparison/setup; -1 open failure, -2 bad stamp, -3 count/ unit mismatch. Rejection closes the newly opened stream. Header scalar read counts are unchecked; use only complete qualified headers. Ignores maxSteps and does not validate payload length, dates, names, value finiteness or endianness. Allocation failures propagate; no previous stream is closed automatically.

Here is the call graph for this function:

openForWrite()

int openswmm::runoff_iface::RunoffInterfaceFile::openForWrite	(	const std::string &	path,
		int	n_subcatch,
		int	n_pollut,
		int	flow_units )

Open/truncate a binary runoff output and write a placeholder header.

Parameters

path	UTF-8 destination; owner must be closed first. No staged replacement.
n_subcatch	Nonnegative subcatchment count fitting int32, matching later ctx arrays.
n_pollut	Nonnegative pollutant count with 8+n_pollut representable as int and buffer capacity; counts are not validated here.
flow_units	Valid project enum [0,5] selecting display flow and US/SI conversions.

Returns

-1 for open failure, otherwise zero after attempted header writes. Does not check fwrite/ftell or catch allocation failures. Header maxSteps is finalized by close(); records use native float representation and no model-name metadata.

Here is the call graph for this function:

readResults()

bool openswmm::runoff_iface::RunoffInterfaceFile::readResults	(	SimulationContext &	ctx,
		double *	dt_out = nullptr )

Restore one timestep's native runoff record with legacy unit conversions.

Parameters

[in,out]	ctx	Initialized compatible ordered subcatchment arrays with at least stored count; replaces evap/infil/runoff/GW-flow and available pollutant slots. Rainfall/snow-depth/GW-elevation/soil-moisture fields are skipped. Evaporation intentionally divides by rainfall conversion (legacy asymmetry), not EVAPRATE.
[out]	dt_out	Optional writable seconds output; assigned immediately after a successful timestep read, even if a later subcatchment record is truncated.

Returns

True after all rows and count increment, false if closed/writing or any required read is short. False can follow partial context/output mutation. Does not honor header maxSteps, reject nonfinite/negative durations/values, roll back, or distinguish EOF from IO errors. No clock advancement is performed here.

saveResults()

void openswmm::runoff_iface::RunoffInterfaceFile::saveResults	(	const SimulationContext &	ctx,
		double	dt )

Append one native timestep and project-unit subcatchment result record.

Parameters

ctx

Borrowed compatible model with aligned arrays and selected open counts; reads current gage rainfall, evaporation/infiltration, cfs runoff/GW flow and pollutant concentrations. Does not advance clocks or modify context.

dt

Finite positive timestep seconds, narrowed to float without validation. No-op unless open for SAVE. Converts to header project units; runoff below MIN_RUNOFF*area is zeroed with washoff. Snow depth/GW elevation/soil moisture are written zero; rainfall is live gage rate, and LID drain is not added here. Pollutant slots beyond available concentration storage are zero. Ignores write failures and increments step_count regardless; no explicit flush/status is provided.

---

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

• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/RunoffInterface.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/hydrology/RunoffInterface.cpp