momentumsolvers.h

Go to the documentation of this file.

#ifndef MOMENTUNSOLVERS_H
#define MOMENTUMSOLVERS_H
 
#include "variables.h" // Provides definitions for UserCtx, SimCtx, IBMNodes, etc.
#include "logging.h"
#include "rhs.h"
#include "Boundaries.h"
 
/*================================================================================*
 *                        MOMENTUM EQUATION SOLVERS                               *
 *================================================================================*/
 
/**
 * @brief Advances the momentum equations using an explicit 4th-order Runge-Kutta scheme.
 * @param user Array of UserCtx structs for all blocks.
 * @param ibm  (Optional) Pointer to IBM data. Pass NULL if disabled.
 * @param fsi  (Optional) Pointer to FSI data. Pass NULL if disabled.
 * @return PetscErrorCode 0 on success.
 *
 * @note Testing status:
 *       The explicit RK path remains on the near-term backlog for direct
 *       positive-path bespoke coverage; today it is weaker than the dual-time
 *       path in the test surface.
 */
extern PetscErrorCode MomentumSolver_Explicit_RungeKutta4(UserCtx *user, IBMNodes *ibm, FSInfo *fsi);
 
/**
 * @brief Solves the Momentum Equations using Dual-Time Stepping with a Fixed-Point RK4 Smoother.
 *
 * =================================================================================================
 * GLOSSARY & THEORETICAL BASIS
 * =================================================================================================
 * 1. METHODOLOGY: Dual-Time Stepping (Pseudo-Time Integration)
 * We aim to solve the implicit BDF equation:  R_spatial(U) + dU/dt_physical = 0.
 * We do this by introducing a fictitious "Pseudo-Time" (tau) and iterating to steady state:
 * dU/d(tau) = - [ R_spatial(U) + BDF_Terms(U) ]
 * When dU/d(tau) -> 0, the physical time step is satisfied.
 * 2. ALGORITHM: Fixed-Point Iteration with Explicit Runge-Kutta
 * This is technically a Fixed-Point iteration on the operator:
 * U_new = U_old + pseudo_dt_scaling * dt_pseudo * Total_Residual(U_old)
 * We use a 4-Stage Explicit RK scheme (Jameson-Schmidt-Turkel coeffs) to smooth errors.
 * 3. STABILITY: Backtracking Line Search
 * If a pseudo-time step causes the Residual or Solution Error to GROW (Divergence),
 * the solver "Backtracks": it restores the previous solution, cuts the pseudo-time step
 * scaling factor (pseudo_dt_scaling) in half, and retries the iteration.
 * =================================================================================================
 * VARIABLE MAPPING
 * =================================================================================================
 * -- Physics Variables (Legacy Names Kept) --
 * ti   : Physical Time Step Index.
 * dt   : Physical Time Step size (Delta t).
 * st   : Pseudo-Time Step size (Delta tau).
 * alfa : Runge-Kutta stage coefficients {1/4, 1/3, 1/2, 1}.
 * -- Convergence & Solver Control (Renamed) --
 * pseudo_iter       : Counter for the inner dual-time loop.
 * pseudo_dt_scaling : Adaptive scalar for the pseudo-time step (formerly lambda).
 * delta_sol_norm    : The L_inf norm of the change in solution (dU).
 * resid_norm        : The L_inf norm of the Total Residual (RHS).
 * =================================================================================================
 *
 * @param user Primary `UserCtx` input for the operation.
 * @param ibm Parameter `ibm` passed to `MomentumSolver_DualTime_Picard_RK4()`.
 * @param fsi Parameter `fsi` passed to `MomentumSolver_DualTime_Picard_RK4()`.
 * @return PetscErrorCode 0 on success.
 *
 * @note Testing status:
 *       This solver is covered primarily through runtime smoke and orchestration
 *       tests. A smaller direct invariant-style positive-path harness remains
 *       part of the next-gap backlog.
 */
PetscErrorCode MomentumSolver_DualTime_Picard_RK4(UserCtx *user, IBMNodes *ibm, FSInfo *fsi);
 
#endif // MOMENTUMSOLVERS_H