LidNodeData.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Caleb Buahin

 
#ifndef OPENSWMM_LID_NODE_DATA_HPP
#define OPENSWMM_LID_NODE_DATA_HPP
#include <array>
#include <vector>
#include <string>
#include "../hydrology/RichardsColumn.hpp"
#include "../hydrology/Infiltration.hpp"
 
namespace openswmm {
// Authored, ordered layers. Thickness/suction are in rain-depth units (in/mm),
// conductivity in in/hr or mm/hr. BOTTOM is a boundary, not a numbered layer.
enum class LidNodeLayerKind { Surface = 0, Media = 1, Aggregate = 2, Bottom = 3 };
struct LidLayerTreatment {
    std::string pollutant;
    double removal = 0.0;   // fraction of outgoing mass
    double decay = 0.0;     // first-order rate, per day
    std::string expression; // optional R= or C=, applied after fixed removal
};
struct LidNodeLayer {
    LidNodeLayerKind kind = LidNodeLayerKind::Media;
    std::array<double, 7> params{};
    std::vector<LidLayerTreatment> treatment;
    richards::Material retention; // explicit inverse-metre parameters
    richards::Options flow;       // control options, stored on first layer only
};
struct LidNodeCell {
    double bottom = 0.0, top = 0.0; // feet above invert
    double geometric_volume = 0.0, area = 0.0;
    double porosity = 1.0, theta = 0.0, field_capacity = 0.0, wilting_point = 0.0;
    double conductivity = 0.0, conductivity_slope = 0.0, suction = 0.0;
    LidNodeLayerKind kind = LidNodeLayerKind::Aggregate;
    int layer = 0;
};
struct LidWaterTransfer {
    int from, to;
    double volume;
}; // -1 mobile, -2 lateral, -3 evaporation
struct LidPortTransfer {
    int link, cell;
    double volume;
}; // positive into held water
struct LidNodeState {
    bool richards = false;
    std::vector<double> richards_water;    // ft3, full porous stores; surface row is unused
    std::vector<double> richards_pressure; // ft, negative means suction
    richards::Report richards_report;      // SI diagnostics for last accepted interval
    double richards_bottom_loss = 0.0;     // ft3, outside-mesh system loss
    double richards_completed_time = 0.0;  // internal owner clock; R5 joint restart still guarded
    double richards_mesh_start =
        0.0; // accepted hydraulic interval; transient until joint restart qualifies
    bool richards_mesh_pending_finish = false; // accepted interval awaits one hydraulic port finish
    bool richards_mesh_routed = false; // final native routing trial awaits finish; no replay/reset
    // One modified Green-Ampt history for the media directly below SURFACE.
    // Other layer/port wetting uses the physical cell and mobile inventories.
    GreenAmptState surface_infil;
    int infiltration_cell = -1;
    double infiltration_head = 0.0; // last reconciled mobile water-table depth
 
    std::vector<double> quality_mass; // [cell * pollutant + pollutant], retained stores
    std::vector<double> quality_old_water;
    std::vector<LidWaterTransfer> quality_transfers;
    std::vector<LidPortTransfer> quality_ports;
    std::vector<double> quality_outlet_conc; // [link * pollutant + pollutant], NaN means mobile
    std::vector<double>
        thermal_energy; // canonical J per physical cell; never a dry-temperature display value
    std::vector<double>
        thermal_ground_contact_j; // cumulative signed soil-contact receipt, positive into each LID cell
    double quality_old_mobile = 0.0;
    double mobile_delta = 0.0; // accepted port balance in the current hydraulic iteration
    std::vector<double>
        port_delta; // accepted link exchange volumes, reset each hydraulic iteration
    std::vector<LidNodeCell> cells; // top to bottom; MEDIA subdivided dynamically
    double held_volume = 0.0;
    double evap_volume = 0.0;
    double captured_flow = 0.0;
    double treated_volume = 0.0;
};
enum class LidNodeBottom { Current = 0, Sealed = 1, MeshAquifer = 2 };
struct LidNodeConfig {
    int control = -1;
    double initial_saturation = 0.0; // percent
    LidNodeBottom bottom = LidNodeBottom::Current;
};
struct LidNodeOutlet {
    int link = -1;
    int layer = 1; // one-based, top to bottom
    bool top = false;
};
} // namespace openswmm
#endif