Skip to content

Commit

Permalink
Merge pull request #214 from hklion/bc_docs
Browse files Browse the repository at this point in the history 
BC documentation
  • Loading branch information
@hklion
hklion authored Jun 20, 2024
2 parents f66ff4e + 105064b commit d7549a7
Show file tree
Hide file tree
Showing 4 changed files with 157 additions and 126 deletions.
116 changes: 30 additions & 86 deletions Docs/sphinx_doc/BoundaryConditions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,39 +4,8 @@

.. _sec:domainBCs:

Filling Ghost Values
--------------------------
REMORA uses an operation called ``FillPatch`` to fill the ghost cells/faces for each grid of data.
The data is filled outside the valid region with a combination of three operations: interpolation
from coarser level, copy from same level, and enforcement of physical boundary conditions.

Interpolation from Coarser level
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Interpolation is controlled by which interpolater we choose to use. The default is
conservative interpolation for cell-centered quantities, and analogous for faces.
The paradigm is that fine faces on a coarse-fine boundary are filled as Dirichlet
boundary conditions from the coarser level; all faces outside the valid region are
similarly filled, while fine faces inside the valid region are not over-written.

Copy from other grids at same level (includes periodic boundaries)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is part of the ``FillPatch`` operation, but can also be applied independently,
e.g. by the call

::

mf.FillBoundary(geom[lev].periodicity());

would fill all the ghost cells/faces of the grids in MultiFab ``mf``, including those
that occur at periodic boundaries.

In the ``FillPatch`` operation, ``FillBoundary`` always overrides any interpolated values, i.e. if
there is fine data available (except at coarse-fine boundary) we always use it.

Imposition of physical/domain boundary conditions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Physical/Domain Boundary Conditions
===================================

There are two primary types of physical/domain boundary conditions: those which rely only on the
data in the valid regions, and those which rely on externally specified values.
Expand Down Expand Up @@ -78,84 +47,59 @@ 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 | Density | Theta | Scalar |
+============+==============+================+================+==================+===============+
| inflow | ext_dir | ext_dir | ext_dir | ext_dir | ext_dir |
+------------+--------------+----------------+----------------+------------------+---------------+
| outflow | foextrap | foextrap | foextrap | foextrap | foextrap |
+------------+--------------+----------------+----------------+------------------+---------------+
| slipwall | ext_dir | foextrap | foextrap | ext_dir/foextrap | foextrap |
+------------+--------------+----------------+----------------+------------------+---------------+
| noslipwall | ext_dir | ext_dir | foextrap | ext_dir/foextrap | foextrap |
+------------+--------------+----------------+----------------+------------------+---------------+
| symmetry | reflect_odd | reflect_even | reflect_even | reflect_even | reflect_even |
+------------+--------------+----------------+----------------+------------------+---------------+
+------------+--------------+----------------+------------------+
| 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 |
+------------+--------------+----------------+------------------+

Periodic boundary conditions are specified by the ``geometry.is_periodic`` flag as described in :ref:`Problem Geometry`<geometry-parameters>`.

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<list-of-parameters-15>`), and surface wind speed is specified by the function ``init_custom_smflux`` in ``prob.cpp``.

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.
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.density = 1.
xlo.theta = 300.
xlo.temp = 15.
xlo.scalar = 2.

sets the boundary condtion type at the low x face to be an inflow with xlo.type = “Inflow”.

xlo.velocity = 1. 0. 0. sets all three componentns the inflow velocity,
xlo.density = 1. sets the inflow density,
xlo.theta = 300. sets the inflow potential temperature,
xlo.scalar = 2. sets the inflow value of the advected scalar

The "slipwall" and "noslipwall" types have options for adiabatic vs Dirichlet boundary conditions.
If a value for theta is given for a face with type "slipwall" or "noslipwall" then the boundary
condition for theta is assumed to be "ext_dir", i.e. theta is specified on the boundary.
If not value is specified then the wall is assumed to be adiabiatc, i.e. there is no temperature
flux at the boundary. This is enforced with the "foextrap" designation.

For example

::

zlo.type = "NoSlipWall"
zhi.type = "NoSlipWall"

zlo.theta = 301.0

would designate theta = 301. at the bottom (zlo) boundary, while
the top boundary condition would be a zero gradient, aka adiabatic
because no value is specified for ``zhi.theta``

We note that "noslipwall" allows for non-zero tangential velocities to be specified, as in the
Couette regression test example, in which we specify
We note that ``noslipwall`` allows for non-zero tangential velocities to be specified, such as

::

geometry.is_periodic = 1 1 0
geometry.is_periodic = 1 0 0

zlo.type = "NoSlipWall"
zhi.type = "NoSlipWall"
ylo.type = "NoSlipWall"
yhi.type = "NoSlipWall"

zlo.velocity = 0.0 0.0 0.0
zhi.velocity = 2.0 0.0 0.0

We also note that in the case of a "slipwall" boundary condition in a simulation with non-zero
viscosity specified, the "foextrap" boundary condition enforces zero strain at the wall.
ylo.velocity = 0.0 0.0 0.0
yhi.velocity = 2.0 0.0 0.0


It is important to note that external Dirichlet boundary data should be specified
as the value on the face of the cell bounding the domain, even for cell-centered
state data.

More general boundary types are a WIP; one type that will be supported soon is the ability
to read in a time sequence of data at a domain boundary and impose this data as "ext_dir"
boundary values using ``FillPatch``.

126 changes: 89 additions & 37 deletions Docs/sphinx_doc/Inputs.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,39 +13,48 @@ The REMORA executable reads run-time information from an “inputs” file whic
This section describes the inputs which can be specified either in the inputs file or on the command line.
If a value is specified on the command line, that value will override a value specified in the inputs file.

.. _geometry-parameters:

Problem Geometry
================

The problem geometry can be specified either by a NetCDF grid file or in the inputs.
Instructions for setting grid, initial, and Dirichelet boundary conditions from NetCDF file can be found
:ref:`here<icbc-parameters>`. If one of these quantities is specified from a NetCDF file, they all must be. Even if the grid is specified in the NetCDF file, the geometry and boundary parameters below must still be set. ``geometry.prob_lo`` and ``geometry.prob_hi`` do not need to agree with the file in this case.

The z-component of ``geometry.prob_lo`` should be more negative than the deepest bathymetry, and the z-compoonent of ``geometry.prob_hi`` should be 0.

List of Parameters
------------------

+--------------------------+-----------------+-----------------+-------------+
| Parameter | Definition | Acceptable | Default |
| | | Values | |
+==========================+=================+=================+=============+
| **geometry.prob_lo** | physical | Real | must be set |
| | location of low | | |
| | corner of the | | |
| | domain | | |
+--------------------------+-----------------+-----------------+-------------+
| **geometry.prob_hi** | physical | Real | 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 | | |
+--------------------------+-----------------+-----------------+-------------+
+--------------------------+-----------------+-------------------+-------------+
| Parameter | Definition | Acceptable | Default |
| | | Values | |
+==========================+=================+===================+=============+
| **geometry.prob_lo** | 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 | |
+--------------------------+-----------------+-------------------+-------------+

Examples of Usage
-----------------

- **geometry.prob_lo** = 0 0 0
defines the low corner of the domain at (0,0,0) in physical space.
- **geometry.prob_lo** = 0 0 -200
defines the low corner of the domain at (0 m,0 m,-200 m) in physical space.

- **geometry.prob_hi** = 1.e8 2.e8 2.e8
defines the high corner of the domain at (1.e8,2.e8,2.e8) in
- **geometry.prob_hi** = 1.e8 2.e8 0
defines the high corner of the domain at (1.e8 m, 2.e8 m, 0 m) in
physical space.

- **geometry.is_periodic** = 0 1 0
Expand All @@ -59,22 +68,63 @@ Domain Boundary Conditions
List of Parameters
------------------

+---------------+---------------------------------+-------------------+----------------------------+
| Parameter | Definition | Acceptable Values | Default |
+===============+=================================+===================+============================+
| **xlo.type** | boundary type of xlo face | | must be set if not periodic|
+---------------+---------------------------------+-------------------+----------------------------+
| **xhi.type** | boundary type of xhi face | | must be set if not periodic|
+---------------+---------------------------------+-------------------+----------------------------+
| **ylo.type** | boundary type of ylo face | | must be set if not periodic|
+---------------+---------------------------------+-------------------+----------------------------+
| **yhi.type** | boundary type of yhi face | | must be set if not periodic|
+---------------+---------------------------------+-------------------+----------------------------+
| **zlo.type** | boundary type of zlo face | | must be set if not periodic|
+---------------+---------------------------------+-------------------+----------------------------+
| **zhi.type** | boundary type of zhi face | | must be set if not periodic|
+---------------+---------------------------------+-------------------+----------------------------+
+---------------+---------------------------------+-------------------+-----------------------------+
| Parameter | Definition | Acceptable Values | Default |
+===============+=================================+===================+=============================+
| **xlo.type** | boundary type of xlo face | see below | must be set if not periodic |
+---------------+---------------------------------+-------------------+-----------------------------+
| **xhi.type** | boundary type of xhi face | see below | must be set if not periodic |
+---------------+---------------------------------+-------------------+-----------------------------+
| **ylo.type** | boundary type of ylo face | see below | must be set if not periodic |
+---------------+---------------------------------+-------------------+-----------------------------+
| **yhi.type** | boundary type of yhi face | see below | must be set if not periodic |
+---------------+---------------------------------+-------------------+-----------------------------+
| **zlo.type** | boundary type of zlo face | slipwall | must be set |
+---------------+---------------------------------+-------------------+-----------------------------+
| **zhi.type** | boundary type of zhi face | slipwall | must be set |
+---------------+---------------------------------+-------------------+-----------------------------+

Currently available type of boundary conditions are
``inflow``, ``outflow``, ``slipwall``, ``noslipwall``, or ``symmetry``
(Spelling of the type matters; capitalization does not.) Z-boundaries are always treated as the seafloor
and surface, and boundary type selection here will not affect program behavior. Domain boundary types
are specified on a per-side basis, rather than a per-variable basis. Inflow, outflow, etc

Usage examples can be found :ref:`here<sec:domainBCs>`.

.. _icbc-parameters:

Imposing Boundary and Initial Conditions from NetCDF File
=========================================================

Grid, initial, and time-dependent boundary data can be specified using NetCDF files, as in ROMS. REMORA expects files in the same format as ROMS.
Currently, if one of these are specified in a file, they all must be. Boundary conditions are currently applied as Dirichelet conditions, as in the ROMS ``clamped`` boundary type. More sophisticated boundary conditions like nudging are a work in progress.

The ``outflow`` option must be selected for ``xlo.type``, ``xhi.type``, ``ylo.type``, and ``yhi.type`` to read the boundary data.

List of Parameters
------------------

+---------------------------+-------------------------------+-------------+--------------------------+
| Parameter | Definition | Acceptable | Default |
| | | Values | |
+===========================+===============================+=============+==========================+
| **remora.ic_bc_type** | read initial, grid, and | | |
| | boundary data from NetCDF | true/false | false |
| | files | | is true |
+---------------------------+-------------------------------+-------------+--------------------------+
| **remora.nc_init_file_0** | initial data NetCDF file name | string | must be set |
| | | | if ``remora.ic_bc_type`` |
| | | | is true |
+---------------------------+-------------------------------+-------------+--------------------------+
| **remora.nc_grid_file_0** | grid data NetCDF file name | string | must be set |
| | | | if ``remora.ic_bc_type`` |
| | | | is true |
+---------------------------+-------------------------------+-------------+--------------------------+
| **remora.nc_bdry_file_0** | boundary data NetCDF file | string | must be set |
| | name | | if ``remora.ic_bc_type`` |
| | | | is true |
+---------------------------+-------------------------------+-------------+--------------------------+

Resolution
==========
Expand Down Expand Up @@ -533,6 +583,8 @@ List of Parameters
+----------------------------------+--------------------------------------+-------------------+----------------+
| **remora.Akt_bak** | Minimum/initial value of Akt | Real number | 1.0e-6 |
+----------------------------------+--------------------------------------+-------------------+----------------+
| **remora.rdrag** | Bottom drag | Real number | 3.0e-4 |
+----------------------------------+--------------------------------------+-------------------+----------------+

List of GLS-specific parameters
-------------------------------
Expand Down
Loading

0 comments on commit d7549a7

Please sign in to comment.