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