Clipped outflow made default for momentum equation (#1340)

* Clipped outflow made default for momentum equation
* update docs and README about pressure_outflow
* inputs documentation
* docs correction

amr-wind/boundary_conditions/README.org

@@ -33,7 +33,8 @@ The boundary conditions that can be specified in the input file are:
   the standard outflow BC for velocity and scalars. For MAC projection and
   nodal-projection, it uses a Dirichlet BC for pressure. The value of pressure
   at the boundary is specified in the input file (default = 0). This can be
-  used as an inflow condition if ...
+  used as an inflow condition (though not recommended) via the input argument
+  "allow_inflow_at_pressure_outflow" associated with the desired equation.
 
 - =no_slip_wall= :: Like =mass_inflow=, this sets =BCRec= to =ext_dir= and
   specifies Dirichlet BC for the linear solvers. However, it differs from

amr-wind/equation_systems/icns/icns_advection.H

@@ -183,10 +183,6 @@ struct AdvectionOp<ICNS, fvm::Godunov>
             } else {
                 limiter_type = PPM::default_limiter;
             }
-            if ((godunov_scheme == godunov::scheme::WENOZ) ||
-                (godunov_scheme == godunov::scheme::WENO_JS)) {
-                m_allow_inflow_on_outflow = true;
-            }
 
             // if state is NPH, then n and n+1 are known, and only
             // spatial extrapolation is performed

docs/sphinx/user/inputs_Boundary_conditions.rst

@@ -87,3 +87,28 @@ The most applicable use case for this boundary condition is with the
 :ref:`amrwind-abl-bndry-io` for flows that change directions
 across the vertical coordinate or with time.
 The work to integrate this condition with the ABL class is under progress.
+
+Pressure outflow boundary conditions
+````````````````````````````````````
+
+The pressure_outflow boundary condition is the most common boundary condition used
+when flow out of a boundary is desired. By default, this sets the pressure at the outflow
+plane to 0 and assumes a zero gradient for other flow quantities (e.g., velocity and
+scalars). Also by default, this boundary condition clips fluxes that would be advected
+into the domain, which is for the sake of stability.
+
+Having a uniform pressure value at the outflow is not often physically valid for
+flows of interest, such as stratified ABLs and ocean waves. However, instead of changing
+the target pressure of the boundary condition, it is typically more useful to change the
+formulation of the source terms, transforming the pressure variable into the difference
+between the true pressure and some constant, non-uniform reference pressure profile.
+In the context of stratified ABLs, which typically apply gravity through the 
+BoussinesqBuoyancy source term, this pressure modification is realized with the
+additional source term ABLMeanBoussinesq. In the context of ocean waves, which typically
+apply gravity through the GravityForcing source term, this pressure modification is
+realized through the input option "ICNS.use_perturb_pressure".
+
+Finally, the default clipping of inflow at pressure_outflow boundaries can be disabled.
+This is not recommended, but it is possible with the input option
+"allow_inflow_at_pressure_outflow". This input argument is appended to the PDE name
+where it should be applied (e.g., ICNS, temperature, or tke).

docs/sphinx/user/inputs_Momentum_Sources.rst

@@ -239,3 +239,30 @@ Section: Momentum Sources
 
    This term turns off the sponge layer. This term is required for terrain simulations with periodic 
    boundary conditions. The default value is 0. 
+
+
+The following arguments are influential when ``GravityForcing`` is included in :input_param:`ICNS.source_terms`.
+
+   .. input_param:: ICNS.use_perturb_pressure
+
+   **type:** Boolean, optional, default = false
+
+   When this option is off, the GravityForcing term is simply :math:`g`, which becomes
+   :math:`\rho g` when included in the momentum equation. By activating this option,
+   the momentum term applied by GravityForcing will become :math:`(\rho - \rho_0) g`,
+   where :math:`rho_0` is some constant reference density profile. The reference density field
+   can be created by either MultiPhase physics or anelastic ABL physics. By using the
+   reference density, the pressure field seen by the solver is represented as a
+   perturbation from a reference pressure field, enabling pressure_outflow boundary
+   conditions to better handle certain flows, e.g., those with equilibrium pressure gradients
+   parallel to the outflow plane.
+
+   .. input_param:: ICNS.reconstruct_true_pressure
+
+   **type:** Boolean, optional, default = false
+
+   This option is only valid when the perturbational pressure form is being used, i.e.,
+   :input_param:`ICNS.use_perturb_pressure` = true. Reconstructing the true pressure
+   adds back the reference pressure profile to obtain the full pressure after the
+   pressure solve has been performed. This makes no difference to the flow evolution,
+   but it changes the field available for post-processing or coupling to overset solvers.

docs/sphinx/user/inputs_incflo.rst

@@ -23,6 +23,13 @@ as initial conditions and discretization options.
    Specify reference density. 
    For the most part if :input_param:`incflo.constant_density` = true then `incflo.density` sets a constant density everywhere.
    Refer to the field initializer for your chosen :input_param:`incflo.physics` for how `incflo.density` is used.
+
+.. input_param:: incflo.gravity
+
+   **type:** List of three Real numbers, optional, default = 0 0 -9.81
+
+   Acceleration due to gravity in m/s\ :sup:`2` \. This constant vector is used by all parts
+   of the solver related to gravity.
 
 .. input_param:: incflo.velocity