From 2319981497dd0a53a9b076faebf0ed68af66da84 Mon Sep 17 00:00:00 2001 From: Hannah Klion Date: Fri, 8 Nov 2024 10:34:44 -0800 Subject: [PATCH 1/2] start updating docs for boundary conditions --- Docs/sphinx_doc/BoundaryConditions.rst | 81 +++++++++++++++++++++----- 1 file changed, 68 insertions(+), 13 deletions(-) diff --git a/Docs/sphinx_doc/BoundaryConditions.rst b/Docs/sphinx_doc/BoundaryConditions.rst index 58eaf3a..b2770c1 100644 --- a/Docs/sphinx_doc/BoundaryConditions.rst +++ b/Docs/sphinx_doc/BoundaryConditions.rst @@ -11,6 +11,51 @@ There are two primary types of physical/domain boundary conditions: those which data in the valid regions, and those which rely on externally specified values. REMORA allows users to specify types of boundary condition with keywords in the inputs file. +The option ``remora.boundary_per_variable`` controls whether conditions are specified on a +per-side or per-variable basis. The options are: + +- inflow + +- outflow + +- slipwall + +- noslipwall + +- symmetry + + + + +Boundary per side +----------------- + +To set boundary conditions per domain side for all variables, set +``remora.boundary_per_variable = false``. This is the default behavior. + +The information for each face is preceded by +``xlo``, ``xhi``, ``ylo``, ``yhi``, ``zlo``, or ``zhi``. + ++----------------------------------+-----------------+-------------------+-------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++==================================+=================+===================+=============+ +| **remora.boundary_per_variable** | physical | [Real Real -Real] | must be set | +| | location of low | | | +| | corner of the | | | +| | domain | | | ++----------------------------------+-----------------+-------------------+-------------+ +| **geometry.prob_hi** | physical | [Real Real 0] | must be set | +| | location of | | | +| | high corner of | | | +| | the domain | | | ++----------------------------------+-----------------+-------------------+-------------+ +| **geometry.is_periodic** | is the domain | 0 if false, 1 | 0 0 0 | +| | periodic in | if true. | | +| | this direction | Z-component must | | +| | | be zero | | ++----------------------------------+-----------------+-------------------+-------------+ + The information for each face is preceded by ``xlo``, ``xhi``, ``ylo``, ``yhi``, ``zlo``, or ``zhi``. @@ -47,19 +92,29 @@ REMORA provides the ability to specify constant Dirichlet BCs in the inputs fil preceded by ``xlo``, ``xhi``, ``ylo``, ``yhi``, ``zlo``, and ``zhi``: -+------------+--------------+----------------+------------------+ -| Type | Normal vel | Tangential vel | T, S, etc. | -+============+==============+================+==================+ -| inflow | ext_dir | ext_dir | ext_dir | -+------------+--------------+----------------+------------------+ -| outflow | foextrap | foextrap | foextrap | -+------------+--------------+----------------+------------------+ -| slipwall | ext_dir | foextrap | ext_dir/foextrap | -+------------+--------------+----------------+------------------+ -| noslipwall | ext_dir | ext_dir | ext_dir/foextrap | -+------------+--------------+----------------+------------------+ -| symmetry | reflect_odd | reflect_even | reflect_even | -+------------+--------------+----------------+------------------+ ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| Type | Normal vel (3D) | Tangential vel (3D) | Normal vel (2D) | Tangential vel (2D) | T, S, etc. | sea surface height | ++===============+====================+=====================+====================+=====================+==================+====================+ +| inflow | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| outflow | foextrap | foextrap | foextrap | foextrap | foextrap | foextrap | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| slipwall | ext_dir | foextrap | ext_dir | foextrap | ext_dir/foextrap | ext_dir/foextrap | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| noslipwall | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir/foextrap | ext_dir/foextrap | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| symmetry | reflect_odd | reflect_even | reflect_odd | reflect_even | reflect_even | reflect_even | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| clamped | clamped | clamped | clamped | clamped | clamped | clamped | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| chapman | N/A | N/A | N/A | N/A | N/A | chapman | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| flather | N/A | N/A | flather | flather | N/A | N/A | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| orlanski | orlanski | orlanski | N/A | N/A | orlanski | N/A | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ +| orlanski_nudg | orlanski | orlanski | N/A | N/A | orlanski | N/A | ++---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ Periodic boundary conditions are specified by the ``geometry.is_periodic`` flag as described in :ref:`Problem Geometry``. From c0f8423a0c86fe411876881badfe99de2ce2d4da Mon Sep 17 00:00:00 2001 From: Hannah Klion Date: Wed, 13 Nov 2024 17:11:18 -0800 Subject: [PATCH 2/2] update documentation for boundary conditions --- Docs/sphinx_doc/BoundaryConditions.rst | 223 ++++++++++++++----------- 1 file changed, 128 insertions(+), 95 deletions(-) diff --git a/Docs/sphinx_doc/BoundaryConditions.rst b/Docs/sphinx_doc/BoundaryConditions.rst index b2770c1..de1938a 100644 --- a/Docs/sphinx_doc/BoundaryConditions.rst +++ b/Docs/sphinx_doc/BoundaryConditions.rst @@ -12,19 +12,10 @@ data in the valid regions, and those which rely on externally specified values. REMORA allows users to specify types of boundary condition with keywords in the inputs file. The option ``remora.boundary_per_variable`` controls whether conditions are specified on a -per-side or per-variable basis. The options are: - -- inflow - -- outflow - -- slipwall - -- noslipwall - -- symmetry - - +per-side (false) or per-variable (true) basis. Conditions are only set on the x- and y-faces. +Boundaries in the z-direction always correspond to the sea floor and surface. Bottom drag is specified with +``remora.rdrag`` (see :ref:`Physics Parameters`), and surface wind +speed is specified by the function ``init_custom_smflux`` in ``prob.cpp``. Boundary per side @@ -34,43 +25,30 @@ To set boundary conditions per domain side for all variables, set ``remora.boundary_per_variable = false``. This is the default behavior. The information for each face is preceded by -``xlo``, ``xhi``, ``ylo``, ``yhi``, ``zlo``, or ``zhi``. - -+----------------------------------+-----------------+-------------------+-------------+ -| Parameter | Definition | Acceptable | Default | -| | | Values | | -+==================================+=================+===================+=============+ -| **remora.boundary_per_variable** | physical | [Real Real -Real] | must be set | -| | location of low | | | -| | corner of the | | | -| | domain | | | -+----------------------------------+-----------------+-------------------+-------------+ -| **geometry.prob_hi** | physical | [Real Real 0] | must be set | -| | location of | | | -| | high corner of | | | -| | the domain | | | -+----------------------------------+-----------------+-------------------+-------------+ -| **geometry.is_periodic** | is the domain | 0 if false, 1 | 0 0 0 | -| | periodic in | if true. | | -| | this direction | Z-component must | | -| | | be zero | | -+----------------------------------+-----------------+-------------------+-------------+ +``bc.xlo.type``, ``bc.xhi.type``, ``bc.ylo.type``, or ``bc.yhi.type``. Spelling of the type matters; capitalization does not. The +options for boundary conditions per side are listed below. -The information for each face is preceded by -``xlo``, ``xhi``, ``ylo``, ``yhi``, ``zlo``, or ``zhi``. +- periodic +- inflow +- outflow +- slipwall +- noslipwall +- symmetry +- clamped -Currently available type of boundary conditions are -``inflow``, ``outflow``, ``slipwall``, ``noslipwall``, or ``symmetry`` -(Spelling of the type matters; capitalization does not.) +Each of these types of physical boundary condition has a mapping to a mathematical boundary condition +for each type; this is summarized in the table below, along with the corresponding ROMS boundary conditions. +If periodic is selected, it must be used for both low and high faces in a direction. The ``geometry.is_periodic`` +flag must match as described in :ref:`ProblemGeometry``. For example, setting :: - xlo.type = "Inflow" - xhi.type = "Outflow" - zlo.type = "SlipWall" - zhi.type = "SlipWall" + bc.xlo.type = "Inflow" + bc.xhi.type = "Outflow" + bc.ylo.type = "periodic" #optional + bc.yhi.type = "periodic" #optional geometry.is_periodic = 0 1 0 @@ -80,64 +58,119 @@ and slip wall on the low and high :math:`y`-faces, and Note that no keyword is needed for a periodic boundary, here only the specification in ``geometry.is_periodic`` is needed. -Each of these types of physical boundary condition has a mapping to a mathematical boundary condition -for each type; this is summarized in the table below. - -.. _sec:dirichlet: - -Dirichlet Boundary Conditions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -REMORA provides the ability to specify constant Dirichlet BCs in the inputs file. We use the following options -preceded by -``xlo``, ``xhi``, ``ylo``, ``yhi``, ``zlo``, and ``zhi``: - -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| Type | Normal vel (3D) | Tangential vel (3D) | Normal vel (2D) | Tangential vel (2D) | T, S, etc. | sea surface height | -+===============+====================+=====================+====================+=====================+==================+====================+ -| inflow | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| outflow | foextrap | foextrap | foextrap | foextrap | foextrap | foextrap | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| slipwall | ext_dir | foextrap | ext_dir | foextrap | ext_dir/foextrap | ext_dir/foextrap | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| noslipwall | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir/foextrap | ext_dir/foextrap | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| symmetry | reflect_odd | reflect_even | reflect_odd | reflect_even | reflect_even | reflect_even | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| clamped | clamped | clamped | clamped | clamped | clamped | clamped | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| chapman | N/A | N/A | N/A | N/A | N/A | chapman | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| flather | N/A | N/A | flather | flather | N/A | N/A | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| orlanski | orlanski | orlanski | N/A | N/A | orlanski | N/A | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ -| orlanski_nudg | orlanski | orlanski | N/A | N/A | orlanski | N/A | -+---------------+--------------------+---------------------+--------------------+---------------------+------------------+--------------------+ - -Periodic boundary conditions are specified by the ``geometry.is_periodic`` flag as described in :ref:`Problem Geometry``. - -Boundaries in the z-direction always correspond to the sea floor and surface, so boundary type selection for ``zlo`` and ``zhi`` will not -affect REMORA behavior. Bottom drag is specified with ``remora.rdrag`` (see :ref:`Physics Parameters`), and surface wind speed is specified by the function ``init_custom_smflux`` in ``prob.cpp``. +Boundary per variable +--------------------- + +To set different boundary conditions for different variables on each side of the domain, set ``remora.boundary_per_variable = true``. +If true, conditions must be set for all of the following variables. + +- temperature: ``bc.temp.type`` +- salinity: ``bc.salt.type`` +- passive scalar: ``bc.scalar.type`` +- 3D u-velocity: ``bc.u.type`` +- 3D v-velocity: ``bc.v.type`` +- 2D u-velocity: ``bc.ubar.type`` +- 2D v-velocity: ``bc.vbar.type`` +- sea surface height: ``bc.zeta.type`` +- turbulent kinetic energy: ``bc.tke.type`` + +They must be set to a list of four conditions in the order West, South, East, North. The options are + +- periodic +- inflow +- outflow +- slipwall +- noslipwall +- symmetry +- clamped +- chapman +- flather +- orlanski +- orlanski_nudg + +The corresponding ROMS conditions are indicated in the tables below. + +For example, setting + +:: + + # West South East North + bc.temp.type = periodic clamped periodic clamped + bc.salt.type = periodic clamped periodic clamped + bc.scalar.type = periodic clamped periodic clamped + bc.u.type = periodic clamped periodic clamped + bc.v.type = periodic clamped periodic clamped + bc.w.type = periodic clamped periodic clamped + bc.ubar.type = periodic flather periodic flather + bc.vbar.type = periodic flather periodic flather + bc.zeta.type = periodic chapman periodic chapman + bc.tke.type = periodic outflow periodic outflow + + geometry.is_periodic = 1 0 0 + +will define a problem that is periodic on the Western and Eastern sides. Temperature, salinity, passive scalar, +3D u-velocity, and 3D v-velocity will be clamped to values given in a NetCDF file specified by +:ref:`remora.nc_bdry_file_0``. The 2D momentum and zeta BCs are calculated from the +Chapman/Flather conditions, with nudging towards values given in the boundary NetCDF file. + +.. _sec:bc-options: + +Boundary condition options +-------------------------- + +Boundary types for per-side or per-variable specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| Type | ROMS name | Normal vel (3D) | Tangential vel (3D) | Normal vel (2D) | Tangential vel (2D) | T, S, etc. | sea surface height | ++=============+===========+====================+=====================+====================+=====================+====================+====================+ +| periodic | Per | periodic | periodic | periodic | periodic | periodic | periodic | ++-------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| inflow | Cla | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir | ++-------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| outflow | Gra | foextrap | foextrap | foextrap | foextrap | foextrap | foextrap | ++-------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| slipwall | Clo | ext_dir (set to 0) | foextrap | ext_dir (set to 0) | foextrap | ext_dir/foextrap | ext_dir/foextrap | ++-------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| noslipwall | N/A | ext_dir (set to 0) | ext_dir (set to 0) | ext_dir (set to 0) | ext_dir (set to 0) | ext_dir/foextrap | ext_dir/foextrap | ++-------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| symmetry | N/A | reflect_odd | reflect_even | reflect_odd | reflect_even | reflect_even | reflect_even | ++-------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| clamped* | N/A | clamped | clamped | clamped | clamped | clamped | clamped | ++-------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ + +Boundary types for per-variable specification ONLY +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| Type | ROMS name | Normal vel (3D) | Tangential vel (3D) | Normal vel (2D) | Tangential vel (2D) | T, S, etc. | sea surface height | ++================+===========+====================+=====================+====================+=====================+====================+====================+ +| chapman* | Che | N/A | N/A | N/A | N/A | N/A | chapman | ++----------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| flather* | Fla | N/A | N/A | flather | flather | N/A | N/A | ++----------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| orlanski | Rad | orlanski | orlanski | N/A | N/A | orlanski | N/A | ++----------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ +| orlanski_nudg* | RadNud | orlanski w/nudging | orlanski w/nudging | N/A | N/A | orlanski w/nudging | N/A | ++----------------+-----------+--------------------+---------------------+--------------------+---------------------+--------------------+--------------------+ + +The asterisks (*) indicate conditions that require the specification of a :ref:`boundary file``. Here ``ext_dir``, ``foextrap``, and ``reflect_even`` refer to AMReX keywords. The ``ext_dir`` type -refers to an "external Dirichlet" boundary, which means the values must be specified by the user. +refers to an "external Dirichlet" boundary, which means the values must be specified by the user, unless +marked as *set to 0* in the table above. The ``foextrap`` type refers to "first order extrapolation" which sets all the ghost values to the same value in the last valid cell/face. (AMReX also has a ``hoextrap``, or "higher order extrapolation" option, which does a linear extrapolation from the two nearest valid values.) -Note that ``outflow`` must be selected for ``xlo``, ``xhi``, ``ylo``, and ``yhi`` when reading boundary data -from a NetCDF file. - As an example, :: - xlo.type = "Inflow" - xlo.velocity = 1. 0.9 0. - xlo.temp = 15. - xlo.scalar = 2. + bc.xlo.type = "Inflow" + bc.xlo.velocity = 1. 0.9 0. + bc.xlo.temp = 15. + bc.xlo.scalar = 2. sets the boundary condition type at the low x face to be an inflow with xlo.type = “Inflow”. @@ -147,11 +180,11 @@ We note that ``noslipwall`` allows for non-zero tangential velocities to be spec geometry.is_periodic = 1 0 0 - ylo.type = "NoSlipWall" - yhi.type = "NoSlipWall" + bc.ylo.type = "NoSlipWall" + bc.yhi.type = "NoSlipWall" - ylo.velocity = 0.0 0.0 0.0 - yhi.velocity = 2.0 0.0 0.0 + bc.ylo.velocity = 0.0 0.0 0.0 + bc.yhi.velocity = 2.0 0.0 0.0 It is important to note that external Dirichlet boundary data should be specified