diff --git a/Docs/sphinx_doc/Checkpoint.rst b/Docs/sphinx_doc/Checkpoint.rst index d19799a1..554cff69 100644 --- a/Docs/sphinx_doc/Checkpoint.rst +++ b/Docs/sphinx_doc/Checkpoint.rst @@ -22,34 +22,34 @@ Writing the Checkpoint "Files" List of Parameters ------------------ -+---------------------------------+----------------+----------------+----------------+ -| Parameter | Definition | Acceptable | Default | -| | | Values | | -+=================================+================+================+================+ ++----------------------------------+----------------+----------------+----------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++==================================+================+================+================+ | **remora.check_file** | prefix for | String | “*chk*” | -| | restart files | | | -+---------------------------------+----------------+----------------+----------------+ +| | restart files | | | ++----------------------------------+----------------+----------------+----------------+ | **remora.check_int** | how often (by | Integer | -1 | -| | level-0 time | :math:`> 0` | | -| | steps) to | | | -| | write restart | | | -| | files | | | -+---------------------------------+----------------+----------------+----------------+ +| | level-0 time | :math:`> 0` | | +| | steps) to | | | +| | write restart | | | +| | files | | | ++----------------------------------+----------------+----------------+----------------+ Restarting ========== -+---------------------------------+----------------+----------------+----------------+ -| Parameter | Definition | Acceptable | Default | -| | | Values | | -+=================================+================+================+================+ ++----------------------------------+----------------+----------------+----------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++==================================+================+================+================+ | **remora.restart** | name of the | String | not used if | -| | file | | not set | -| | (directory) | | | -| | from which to | | | -| | restart | | | -| | files | | | -+---------------------------------+----------------+----------------+----------------+ +| | file | | not set | +| | (directory) | | | +| | from which to | | | +| | restart | | | +| | files | | | ++----------------------------------+----------------+----------------+----------------+ .. _examples-of-usage-7: diff --git a/Docs/sphinx_doc/Inputs.rst b/Docs/sphinx_doc/Inputs.rst index f1011aeb..afbd87a1 100644 --- a/Docs/sphinx_doc/Inputs.rst +++ b/Docs/sphinx_doc/Inputs.rst @@ -477,59 +477,59 @@ Physics Parameters List of Parameters ------------------ -+----------------------------------+----------------------------------+-------------------+---------------+ -| Parameter | Definition | Acceptable | Default | -| | | Values | | -+==================================+==================================+===================+===============+ -| **remora.ggrav** | Gravitational field strength | Real number | 9.81 | -| | [kg m/s^2] | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.R0** | Background density [kg/m^3] | Real number | 1028 | -| | used in Linear Equation of | | | -| | State. May be used in setup | | | -| | of some problems. | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.S0** | Background salinity | Real number | 35 | -| | (nondimensional) used in | | | -| | Linear Equation of State | | | -| | State. May be used in setup | | | -| | of some problems. | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.T0** | Background temperature | Real number | 5 | -| | (Celsius) used in | | | -| | Linear Equation of State | | | -| | State. May be used in setup | | | -| | of some problems. | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.Tcoef** | Linear EOS parameter | Real number | 1.7e-4 | -| | (1/Celsius) | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.Scoef** | Linear EOS parameter | Real number | 0.0 | -| | (nondimensional) | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.rho0** | Mean density (kg/m^3) used | Real number | 1025 | -| | when Boussinesq approx is | | | -| | inferred | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.coriolis_type** | Type of Coriolis forcing. | `beta_plane` / | `beta_plane` | -| | beta_plane uses a linear | `custom` / | | -| | approximation. Custom is | `real | | -| | calculated from a function in | | | -| | prob.cpp, and Real is read from | | | -| | the netcdf grid file | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.coriolis_f0** | f-plane constant for | Real number | 0.0 | -| | Coriolis param | | | -| | :math:`f = f_0 + \beta y` | | | -| | when using beta plane | | | -| | Coriolis type | | | -+----------------------------------+----------------------------------+-------------------+---------------+ -| **remora.coriolis_beta** | beta-plane constant for | Real number | 0.0 | -| | Coriolis param | | | -| | :math:`f = f_0 + \beta y` | | | -| | when using beta plane | | | -| | Coriolis type | | | -+----------------------------------+----------------------------------+-------------------+---------------+ ++----------------------------------+--------------------------------------+-------------------+----------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++==================================+======================================+===================+================+ +| **remora.ggrav** | Gravitational field strength | Real number | 9.81 | +| | [kg m/s^2] | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.R0** | Background density [kg/m^3] | Real number | 1028 | +| | used in Linear Equation of | | | +| | State. May be used in setup | | | +| | of some problems. | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.S0** | Background salinity | Real number | 35 | +| | (nondimensional) used in | | | +| | Linear Equation of State | | | +| | State. May be used in setup | | | +| | of some problems. | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.T0** | Background temperature | Real number | 5 | +| | (Celsius) used in | | | +| | Linear Equation of State | | | +| | State. May be used in setup | | | +| | of some problems. | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.Tcoef** | Linear EOS parameter | Real number | 1.7e-4 | +| | (1/Celsius) | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.Scoef** | Linear EOS parameter | Real number | 0.0 | +| | (nondimensional) | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.rho0** | Mean density (kg/m^3) used | Real number | 1025 | +| | when Boussinesq approx is | | | +| | inferred | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.coriolis_type** | Type of Coriolis forcing. | ``beta_plane`` / | ``beta_plane`` | +| | ``beta_plane`` uses a linear | ``custom`` / | | +| | approximation. ``custom`` is | ``real`` | | +| | calculated from a function in | | | +| | ``prob.cpp``, and ``real`` is | | | +| | read from the netcdf grid file | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.coriolis_f0** | f-plane constant for | Real number | 0.0 | +| | Coriolis param | | | +| | :math:`f = f_0 + \beta y` | | | +| | when using beta plane | | | +| | Coriolis type | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ +| **remora.coriolis_beta** | beta-plane constant for | Real number | 0.0 | +| | Coriolis param | | | +| | :math:`f = f_0 + \beta y` | | | +| | when using beta plane | | | +| | Coriolis type | | | ++----------------------------------+--------------------------------------+-------------------+----------------+ Numerical Algorithms ==================== diff --git a/Docs/sphinx_doc/InputsPhysics.rst b/Docs/sphinx_doc/InputsPhysics.rst index 247f3862..9fcadda6 100644 --- a/Docs/sphinx_doc/InputsPhysics.rst +++ b/Docs/sphinx_doc/InputsPhysics.rst @@ -9,12 +9,12 @@ Diffusive Physics List of Parameters ------------------ -+----------------------------------+--------------------+---------------------+-------------+ -| Parameter | Definition | Acceptable | Default | -| | | Values | | -+==================================+====================+=====================+=============+ ++-----------------------------------+--------------------+---------------------+-------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++===================================+====================+=====================+=============+ | **remora.spatial_order** | | 2 / 3 / 4 / 5 / 6 | 2 | -+----------------------------------+--------------------+---------------------+-------------+ ++-----------------------------------+--------------------+---------------------+-------------+ Forcing Terms ============= @@ -24,16 +24,16 @@ Forcing Terms List of Parameters ------------------ -+----------------------------------+-----------------------------+-------------------+-------------+ -| Parameter | Definition | Acceptable | Default | -| | | Values | | -+==================================+=============================+===================+=============+ ++-----------------------------------+-----------------------------+-------------------+-------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++===================================+=============================+===================+=============+ | **remora.use_coriolis** | Include Coriolis terms. | true / false | false | -| | Coriolis parameter :math`f` | | | -| | is hard-coded for Upwelling | | | -| | problem in | | | -| | ``REMORA::Advance()`` | | | -+----------------------------------+-----------------------------+-------------------+-------------+ +| | Coriolis parameter :math`f` | | | +| | is hard-coded for Upwelling | | | +| | problem in | | | +| | ``REMORA::Advance()`` | | | ++-----------------------------------+-----------------------------+-------------------+-------------+ Initialization @@ -51,23 +51,23 @@ REMORA can be initialzed in different ways. These are listed below: List of Parameters ------------------ -+-----------------------------+-------------------+--------------------+------------+ -| Parameter | Definition | Acceptable | Default | -| | | Values | | -+=============================+===================+====================+============+ ++------------------------------+-------------------+--------------------+------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++==============================+===================+====================+============+ | **remora.init_type** | Initialization | “custom”, | “*custom*” | -| | type | “ideal”, | | -| | | “real”, | | -| | | "input_sounding" | | -+-----------------------------+-------------------+--------------------+------------+ +| | type | “ideal”, | | +| | | “real”, | | +| | | "input_sounding" | | ++------------------------------+-------------------+--------------------+------------+ | **remora.nc_init_file** | NetCDF file with | String | NONE | -| | initial mesocale | | | -| | data | | | -+-----------------------------+-------------------+--------------------+------------+ +| | initial mesocale | | | +| | data | | | ++------------------------------+-------------------+--------------------+------------+ | **remora.nc_bdy_file** | NetCDF file with | String | NONE | -| | mesocale data at | | | -| | lateral boundaries| | | -+-----------------------------+-------------------+--------------------+------------+ +| | mesocale data at | | | +| | lateral boundaries| | | ++------------------------------+-------------------+--------------------+------------+ Notes ----------------- diff --git a/Docs/sphinx_doc/MeshRefinement.rst b/Docs/sphinx_doc/MeshRefinement.rst index d353a71d..0eaa99e9 100644 --- a/Docs/sphinx_doc/MeshRefinement.rst +++ b/Docs/sphinx_doc/MeshRefinement.rst @@ -145,8 +145,7 @@ the fine level also communicates data back to the coarse level in two ways: - The fine momenta are conservatively averaged onto the coarse faces covered by fine mesh. -- A "reflux" operation is performed for all cell-centered data; this updates values on the coarser -level outside of regions covered by the finer level. +- A "reflux" operation is performed for all cell-centered data; this updates values on the coarser level outside of regions covered by the finer level. Advected quantities which are advanced in conservation form will lose conservation with one-way coupling. Two-way coupling ensures conservation of the advective contribution to all scalar updates but diff --git a/Docs/sphinx_doc/Numerical_Solution_Technique.rst b/Docs/sphinx_doc/Numerical_Solution_Technique.rst index 9913bbc0..0bb2b417 100644 --- a/Docs/sphinx_doc/Numerical_Solution_Technique.rst +++ b/Docs/sphinx_doc/Numerical_Solution_Technique.rst @@ -53,6 +53,7 @@ Staggered Vertical Grid ~~~~~~~~~~~~~~~~~~~~~~~ .. image:: figures/vertical_grid.png :width: 60% + In this diagram, indices are 1-indexed (as in ROMS), while the indices in REMORA are 0-indexed. The total thickness of the water column is :math:`\zeta\left(i,j\right)+h\left(i,j\right)`. The bathymetry (``h``) is usually time invariant whereas the free-surface (``zeta``) evolves in time. At input and output, the bathymetry is always a positive quantity. However, the depths ``z_r(i,j,k)`` and ``z_w(i,j,k)`` are negative for all locations below the mean sea level. @@ -86,7 +87,7 @@ Grid Variables +-------------------------------------------------+-----------------------------+------------------------------------------------------------------+-------------------+-------------------+ | :math:`\psi` | | | corners | | +-------------------------------------------------+-----------------------------+------------------------------------------------------------------+-------------------+-------------------+ -| :math:`H_z` | ``vec_Hz` | level thickness | center | | +| :math:`H_z` | ``vec_Hz`` | level thickness | center | | +-------------------------------------------------+-----------------------------+------------------------------------------------------------------+-------------------+-------------------+ | :math:`\omega` | | vertical velocity | bottom/top faces | | +-------------------------------------------------+-----------------------------+------------------------------------------------------------------+-------------------+-------------------+ diff --git a/Docs/sphinx_doc/Plotfiles.rst b/Docs/sphinx_doc/Plotfiles.rst index b87f810d..a90c70e6 100644 --- a/Docs/sphinx_doc/Plotfiles.rst +++ b/Docs/sphinx_doc/Plotfiles.rst @@ -3,9 +3,9 @@ .. _sec:Plotfiles: -****** +********* Plotfiles -****** +********* .. toctree:: :maxdepth: 1 @@ -24,45 +24,45 @@ frequency and content of the two streams are controlled separately. List of Parameters ------------------ -+-----------------------------+------------------+-----------------------+------------+ -| Parameter | Definition | Acceptable | Default | -| | | Values | | -+=============================+==================+=======================+============+ ++------------------------------+------------------+-----------------------+------------+ +| Parameter | Definition | Acceptable | Default | +| | | Values | | ++==============================+==================+=======================+============+ | **remora.plotfile_type** | AMReX or NETCDF | "amrex" or | "amrex" | -| | | "netcdf / "NetCDF" | | -+-----------------------------+------------------+-----------------------+------------+ +| | | "netcdf / "NetCDF" | | ++------------------------------+------------------+-----------------------+------------+ | **remora.plot_file_1** | prefix for | String | “*plt_1_*” | -| | plotfiles | | | -| | at first freq. | | | -+-----------------------------+------------------+-----------------------+------------+ +| | plotfiles | | | +| | at first freq. | | | ++------------------------------+------------------+-----------------------+------------+ | **remora.plot_file_2** | prefix for | String | “*plt_2_*” | -| | plotfiles | | | -| | at seoncd freq. | | | -+-----------------------------+------------------+-----------------------+------------+ +| | plotfiles | | | +| | at seoncd freq. | | | ++------------------------------+------------------+-----------------------+------------+ | **remora.plot_int_1** | how often (by | Integer | -1 | -| | level-0 time | :math:`> 0` | | -| | steps) to write | | | -| | plot files | | | -| | at first freq. | | | -+-----------------------------+------------------+-----------------------+------------+ +| | level-0 time | :math:`> 0` | | +| | steps) to write | | | +| | plot files | | | +| | at first freq. | | | ++------------------------------+------------------+-----------------------+------------+ | **remora.plot_int_2** | how often (by | Integer | -1 | -| | level-0 time | :math:`> 0` | | -| | steps) to write | | | -| | plot files | | | -| | at seoncd freq. | | | -+-----------------------------+------------------+-----------------------+------------+ +| | level-0 time | :math:`> 0` | | +| | steps) to write | | | +| | plot files | | | +| | at seoncd freq. | | | ++------------------------------+------------------+-----------------------+------------+ | **remora.plot_vars_1** | name of | list of names | None | -| | variables to | | | -| | include in | | | -| | plotfiles | | | -| | at first freq. | | | -+-----------------------------+------------------+-----------------------+------------+ +| | variables to | | | +| | include in | | | +| | plotfiles | | | +| | at first freq. | | | ++------------------------------+------------------+-----------------------+------------+ | **remora.plot_vars_2** | name of | list of names | None | -| | variables to | | | -| | include in | | | -| | plotfiles | | | -| | at seoncd freq. | | | -+-----------------------------+------------------+-----------------------+------------+ +| | variables to | | | +| | include in | | | +| | plotfiles | | | +| | at seoncd freq. | | | ++------------------------------+------------------+-----------------------+------------+ .. _notes-5: diff --git a/Docs/sphinx_doc/Time_Stepping.rst b/Docs/sphinx_doc/Time_Stepping.rst index 146815b2..1da9e42a 100644 --- a/Docs/sphinx_doc/Time_Stepping.rst +++ b/Docs/sphinx_doc/Time_Stepping.rst @@ -21,27 +21,27 @@ Rutgers ROMS: Timestepping table from ``Shchepetkin and McWilliams (2008a)``: -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ -| |SCRUM 3.0 |Rutgers | AGRIF | UCLA | Non-hydrostatic | -+================================+===============================+=====================+==========================+===================+===================+ -| barotropic | LF-TR |LF-AM3 with FB |LF-AM3 with FB | Gen. FB | Gen. FB | -| mode | | feedback | feedback :math:`\dagger` | (AB3-AM4) | (AB3-AM4) | -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ -| 2-D :math:`\alpha_{\max}`,iter.| :math:`\sqrt{2}, (2)\ddagger` | :math:`1.85, (2)` |:math:`1.85, (2)` | :math:`1.78, (1)` | :math:`1.78, (1)` | -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ -| 3-D momenta | AB3 | AB3 | LF-AM3 | LF-AM3 | AB3 (mod) | -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ -| Tracers | AB3 | LF-TR | LF-AM3 | LF-AM3 | AB3 (mod) | -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ -| internal | AB3 | Gen. FB | LF-AM3, | LF-AM3 | Gen. FB | -| waves | | (AB3-TR) | FB feedback | FB feedback | (AB3-AM4) | -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ -| :math:`\alpha_{\max}`,advect. | :math:`0.72` | :math:`0.72` | :math:`1.587` | :math:`1.587` | :math:`0.78` | -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ -| :math:`\alpha_{\max}`,Cor. | :math:`0.72` | :math:`0.72` | :math:`1.587` | :math:`1.587` | :math:`0.78 | -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ -| :math:`\alpha_{\max}`,int. w. | :math:`0.72, (1)` | :math:`1.14, (1,2)` | :math:`1.85, (2)` | :math:`1.85, (2)` | :math:`1.78, (1)` | -+--------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ +| | SCRUM 3.0 | Rutgers | AGRIF | UCLA | Non-hydrostatic | ++=================================+===============================+=====================+==========================+===================+===================+ +| barotropic | LF-TR | LF-AM3 with FB | LF-AM3 with FB | Gen. FB | Gen. FB | +| mode | | feedback | feedback :math:`\dagger` | (AB3-AM4) | (AB3-AM4) | ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ +| 2-D :math:`\alpha_{\max}`,iter. | :math:`\sqrt{2}, (2)\ddagger` | :math:`1.85, (2)` | :math:`1.85, (2)` | :math:`1.78, (1)` | :math:`1.78, (1)` | ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ +| 3-D momenta | AB3 | AB3 | LF-AM3 | LF-AM3 | AB3 (mod) | ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ +| Tracers | AB3 | LF-TR | LF-AM3 | LF-AM3 | AB3 (mod) | ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ +| internal | AB3 | Gen. FB | LF-AM3, | LF-AM3 | Gen. FB | +| waves | | (AB3-TR) | FB feedback | FB feedback | (AB3-AM4) | ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ +| :math:`\alpha_{\max}`,advect. | :math:`0.72` | :math:`0.72` | :math:`1.587` | :math:`1.587` | :math:`0.78` | ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ +| :math:`\alpha_{\max}`,Cor. | :math:`0.72` | :math:`0.72` | :math:`1.587` | :math:`1.587` | :math:`0.78` | ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ +| :math:`\alpha_{\max}`,int. w. | :math:`0.72, (1)` | :math:`1.14, (1,2)` | :math:`1.85, (2)` | :math:`1.85, (2)` | :math:`1.78, (1)` | ++---------------------------------+-------------------------------+---------------------+--------------------------+-------------------+-------------------+ *Note:* :math:`\dagger` The generalized FB barotropic mode was ported into the newest AGRIF code at the end of 2007. :math:`\ddagger` The number in parentheses (e.g., 2) indicates the number of r.h.s. computations per time step. If there are two parenthesized numbers, the first one is for momenta, the second for tracers. diff --git a/Docs/sphinx_doc/building.rst b/Docs/sphinx_doc/building.rst index 4d275456..639c40d8 100644 --- a/Docs/sphinx_doc/building.rst +++ b/Docs/sphinx_doc/building.rst @@ -102,7 +102,7 @@ in the directory where the executable has been built. CMake ~~~~~ -CMake is often preferred by developers of REMORA; CMake allows for building as well as easy testing and verification of REMORA through the use of CTest which is included in CMake. +CMake is often preferred by developers of REMORA; CMake allows for building as well as easy testing and verification of REMORA through the use of CTest which is included in CMake. CTest functionality requires additional options, described in :ref:`Testing`. Using CMake involves an additional configure step before using the ``make`` command. It is also expected that the user has cloned the REMORA repo with the ``--recursive`` option or performed ``git submodule init; git submodule update`` in the REMORA repo to populate its submodules. diff --git a/Docs/sphinx_doc/index.rst b/Docs/sphinx_doc/index.rst index b8b7e838..ff03a0f1 100644 --- a/Docs/sphinx_doc/index.rst +++ b/Docs/sphinx_doc/index.rst @@ -1,7 +1,7 @@ :orphan: REMORA ------ +------ REMORA is currently under development as a next-generation version of the Regional Ocean Modeling System (ROMS). @@ -36,6 +36,7 @@ In addition to this documentation, there is API documentation for REMORA generat .. toctree:: :caption: USER GUIDE :maxdepth: 1 + :hidden: GettingStarted.rst Inputs.rst