FvOptions.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

 
#ifndef OPENSWMM_ENGINE_FV_OPTIONS_HPP
#define OPENSWMM_ENGINE_FV_OPTIONS_HPP
 
namespace openswmm::fv {

inline constexpr int kMaxLtsTiers = 8;

enum class RiemannSolver : int {
    HLL  = 0,   
    HLLC = 1    
};

enum class Limiter : int {
    MINMOD   = 0,  
    VANLEER  = 1,
    SUPERBEE = 2   
};

enum class ScalarScheme : int {
    UPWIND            = 0,  
    MUSCL             = 1,  
    QUICKEST_ULTIMATE = 2   
};

enum class TimeIntegration : int {
    EULER = 0,  
    RK2   = 1   
};
 
// FV_NODE_COUPLING, FV_NODE_DT and FV_NODE_PICARD were retired 2026-08-29
// (parsed and warned when they ask for the behaviour that no longer exists):
// storage-node coupling is always semi-implicit, the node accuracy bound is
// always armed, and the correction is always a single sweep -- each the
// former default. The SWASHES table that justified FV_NODE_DT was measured
// under the BUCKET junction model described below, three days before that
// model was deleted, and never re-measured
// (plans/FV1D_PERF_PLAN_REVIEW_2026-08-20.md §3.1).
 
// Junctions are always ALGEBRAIC interfaces, not states (matching legacy
// DYNWAVE, where a junction's own surface area is exactly zero and all
// working area belongs to the conduits — here, the cells): degree-2 nodes
// with no local injection pass fluxes straight through as a direct face, and
// every other junction solves its head from the instantaneous flux balance
// per substep. The earlier BUCKET model (MIN_SURFAREA control volume
// integrated in time, FV_JUNCTION_MODEL option) manufactured a millisecond
// dt bound and a transshipment cap dt ≤ V_node/Q that jammed junction-dense
// channels at the crown; it was removed after the algebraic interface passed
// the open-channel validation suite. See ExplicitFvSolver::solveAlgebraicNode.

enum class StructureCoupling : int {
    SUBSTEP      = 0,  
    ROUTING_STEP = 1   
};

enum class Backend : int {
    CPU  = 0,
    AUTO = 1,   
    OMP  = 2,
    CUDA = 3,
    HIP  = 4,
    SYCL = 5
};

struct FvOptions {
    // -- Mesh (plan §3.2) ---------------------------------------------------

    double cell_length = 0.0;

    int min_cells = 4;
 
    // -- Pressure closure (issue #156 Phase 4) -------------------------------
    int pressure_closure = 0;
 
    // -- Unsteady friction (issue #156) --------------------------------------
    // Mirrors SimulationOptions::unsteady_friction / uf_k3 (shared [OPTIONS]
    // keys UNSTEADY_FRICTION / UF_K3, not FV_*); copied in Router::initFv so
    // the solver keeps seeing only FvOptions. Both dimensionless.

    int unsteady_friction = 0;

    double uf_k3 = 0.015;
 
    // -- Scheme -------------------------------------------------------------
 
    double        cfl              = 0.5;
    RiemannSolver riemann          = RiemannSolver::HLLC;
    int           order            = 1;                    
    Limiter       limiter          = Limiter::MINMOD;
    ScalarScheme  scalar_scheme    = ScalarScheme::MUSCL;
    TimeIntegration time_integration = TimeIntegration::EULER;

    double slot_celerity = 100.0;

    bool pressurized_implicit = false;
 
    // -- Coupling -----------------------------------------------------------
 
    StructureCoupling structure_coupling = StructureCoupling::SUBSTEP;
 
    // -- Execution ----------------------------------------------------------
 
    Backend backend = Backend::AUTO;

    long min_parallel_cells = 20000;
 
    // -- Performance levers (plan §5.2) -------------------------------------

    bool compaction = true;

    bool lts = true;

    bool node_feedback_dt = false;

    int lts_max_tiers = 6;

    int cfl_census_interval = 1;
 
    // -- Transport (plan §3.2 / §6.11) --------------------------------------

    double dispersion = 0.0;
};
 
} // namespace openswmm::fv
 
#endif // OPENSWMM_ENGINE_FV_OPTIONS_HPP