OpenSWMM Engine  6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Friends | List of all members
openswmm::twoD::SurfaceExchange Class Reference

#include <SurfaceExchange.hpp>

Collaboration diagram for openswmm::twoD::SurfaceExchange:

Public Types

using Capacity = std::function<double(const SurfaceIntakeRequest&, double)>
 

Public Member Functions

std::string plan (const SubsurfaceSolver &, double start, double end, double completed_through, const std::vector< SurfaceIntakeRequest > &, const Capacity *=nullptr)
 Plan donor-limited, receiver-limited intake over a contiguous completed interval.
 
std::string commit (SubsurfaceSolver &, const std::vector< SurfaceIntakeActual > &, const Capacity *=nullptr)
 Settle the current awards against the same aquifer owner.
 
void cancel () noexcept
 Discard pending intake awards without undoing committed receipts.
 
const std::vector< SurfaceIntakeAward > & awards () const noexcept
 Read this exchange transaction's stable result state.
 
const std::vector< SurfaceIntakeReceipt > & receipts () const noexcept
 Read this exchange transaction's stable result state.
 
double completedEnd () const noexcept
 Read this exchange transaction's stable result state.
 

Friends

class CommonSourceStage
 

Member Typedef Documentation

◆ Capacity

using openswmm::twoD::SurfaceExchange::Capacity = std::function<double(const SurfaceIntakeRequest&, double)>

Member Function Documentation

◆ awards()

const std::vector< SurfaceIntakeAward > & openswmm::twoD::SurfaceExchange::awards ( ) const
inlinenoexcept

Read this exchange transaction's stable result state.

Returns
Borrowed object-owned sorted intake-award vector; demand/maximum volumes use m3. Invalidated by plan/cancel/replacement/destruction.
Note
No allocation or ownership transfer; caller serializes reads with mutation and must not free/modify borrowed vectors.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ cancel()

void openswmm::twoD::SurfaceExchange::cancel ( )
noexcept

Discard pending intake awards without undoing committed receipts.

Postcondition
Clears planned flag, borrowed receiver pointer and awards. completedEnd() and the last committed receipts remain unchanged. No receiver water is booked or restored; no allocation/exceptions. Requires exclusive exchange access.

◆ commit()

std::string openswmm::twoD::SurfaceExchange::commit ( SubsurfaceSolver & gw,
const std::vector< SurfaceIntakeActual > & actual,
const Capacity * prescribed = nullptr )

Settle the current awards against the same aquifer owner.

Validate actual donor withdrawals and book their paired aquifer receipts.

Argument contract The first argument is the borrowed mutable receiver used by plan.
The actual-transfer vector must match awards order/count and contain paired water m3/species inventory in receiver order. The optional Capacity callback is reevaluated synchronously and must match planning semantics.
Returns
Empty on success, refusal text before booking on invalid/stale data. Allocation exceptions during receiver receipt retention can leave partial booking; caller supplies an enclosing transaction when required.
Note
Does not install donor trial state. No callback/input-array pointers are retained after successful settlement.
Parameters
[in,out]gwSame live receiver instance retained by the pending plan; serial access prevents intervening capacity/owner mutations during settlement.
[in]actualBorrowed vector exactly matching awards() ORDER/count. Each volume is finite nonnegative m3 no greater than its maximum. Each mass tuple matches the receiver's species order, native concentration*m3 (age s*m3, temperature degrees C*m3); zero water requires zero tuple, only temperature may be negative.
[in]prescribedOptional synchronous capacity callback with the same units/semantics used during plan; it is reevaluated to reject stale trials.
Returns
Empty after successful booking, otherwise validation/refusal text before receiver mutation. A refused plan remains available for cancel/retrial.
Postcondition
Successful commit appends retained provenance where configured, books pending water/species, advances wetting-front/remaining allowance, replaces receipts(), advances completedEnd(), and clears the plan. It does not install the caller's donor trial state.
Note
Preflight validation/local receipt allocation precedes booking. Receiver provenance vectors may still allocate during retainSourceReceipt(); an allocation exception can interrupt the booking loop after earlier receipts were applied. The caller needs an enclosing owner transaction when exception rollback is required. No input/callback pointers retained after success; copied receipts remain object-owned.
Here is the call graph for this function:

◆ completedEnd()

double openswmm::twoD::SurfaceExchange::completedEnd ( ) const
inlinenoexcept

Read this exchange transaction's stable result state.

Returns
Last successfully committed contiguous endpoint in elapsed seconds; initially zero and preserved by cancel.
Note
No allocation or ownership transfer; caller serializes reads with mutation and must not free/modify borrowed vectors.

◆ plan()

std::string openswmm::twoD::SurfaceExchange::plan ( const SubsurfaceSolver & gw,
double start,
double end,
double completed,
const std::vector< SurfaceIntakeRequest > & requests,
const Capacity * prescribed = nullptr )

Plan donor-limited, receiver-limited intake over a contiguous completed interval.

Reserve a contiguous completed source interval against donor and receiver budgets.

Argument contract The borrowed receiver must remain alive until commit/cancel.
start/end/completed_through use elapsed seconds. The request array is borrowed during the call and copied into awards; request area m2, pond head m and water ceilings/candidates m3. The optional final Capacity pointer is a synchronous borrowed callback returning capacity m3 for a request and interval seconds.
Returns
Empty for a published pending plan, otherwise refusal text. No receiver state is changed; allocation/callback exceptions propagate.
Note
Detailed validation and deterministic scaling are documented with the implementation. Public plan publication requires exclusive access and no previous pending plan.
Parameters
[in]gwBorrowed active spatial aquifer with stable covered-cell areas/capacity/headroom. Its identity is retained until commit/cancel, so it must remain alive and unmoved.
[in]startFinite nonnegative elapsed start time, s; exactly completedEnd().
[in]endFinite elapsed endpoint, s, strictly greater than start and no later than completed.
[in]completedFinite source-completion evidence through at least end, elapsed seconds; canonical declaration calls this completed_through.
[in]requestsBorrowed candidate transfers: nonempty source id, zero-based receiver cell, contact area m2, pond head m, water_ceiling/candidate volumes m3. A donor's ceiling must match across its cells; duplicate donor/cell pairs are refused.
[in]prescribedOptional borrowed synchronous capacity callback, invoked with request and interval seconds and returning finite nonnegative capacity m3; NULL queries gw capacity. Callback must be nonempty when supplied and not mutate/reenter this exchange or receiver.
Returns
Empty on a published plan, otherwise refusal text with no receiver water booked. Existing plan is preserved if another plan is already pending.
Postcondition
Sorts awards by stable donor/cell identity, scales demands to each donor's available water and each cell's receiver headroom, retains copied requests and receiver identity. Denied capacity is not reassigned to another cell.
Note
Requires serial exclusive exchange access and stable receiver reads. Local allocation/callback exceptions propagate before the final plan publication; no request/callback storage is retained, but the receiver pointer is borrowed until settlement/cancel.
Here is the call graph for this function:

◆ receipts()

const std::vector< SurfaceIntakeReceipt > & openswmm::twoD::SurfaceExchange::receipts ( ) const
inlinenoexcept

Read this exchange transaction's stable result state.

Returns
Borrowed object-owned last successful settlement receipts, with copied paired source tuples. Invalidated by the next successful commit/replacement/destruction; cancel preserves them.
Note
No allocation or ownership transfer; caller serializes reads with mutation and must not free/modify borrowed vectors.
Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ CommonSourceStage

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