From 2835601638aa5b817d28d3093cd46a49bcee43a3 Mon Sep 17 00:00:00 2001 From: "Jean M. Sexton" Date: Tue, 10 Sep 2024 10:48:32 -0500 Subject: [PATCH] Update Getting Started and build parts of docs --- Docs/sphinx_doc/InputFiles.rst | 4 +++- Docs/sphinx_doc/Inputs.rst | 29 +++++++++++++++++++++++++++++ Docs/sphinx_doc/building.rst | 29 +++++++++++++++++++++++++++++ Docs/sphinx_doc/testing.rst | 4 ++-- 4 files changed, 63 insertions(+), 3 deletions(-) diff --git a/Docs/sphinx_doc/InputFiles.rst b/Docs/sphinx_doc/InputFiles.rst index cade2770..911b6360 100644 --- a/Docs/sphinx_doc/InputFiles.rst +++ b/Docs/sphinx_doc/InputFiles.rst @@ -16,4 +16,6 @@ Also, any entry that can be specified in the inputs file can also be specified o mpirun -np 64 ./REMORA3d.gnu.DEBUG.MPI.ex inputs amr.restart=chk0030 remora.use_gravity=true -See :ref:`sec:Inputs` for details on run-time options that can be specified. +See :ref:`sec:Inputs` for details on run-time options that can be specified. If running on a Mac and getting +errors like ``SIGILL Invalid, privileged, or ill-formed instruction``, see the note on that page about +runtime error-checking options. diff --git a/Docs/sphinx_doc/Inputs.rst b/Docs/sphinx_doc/Inputs.rst index c2831595..62385484 100644 --- a/Docs/sphinx_doc/Inputs.rst +++ b/Docs/sphinx_doc/Inputs.rst @@ -686,3 +686,32 @@ These parameters are used to calculate the vertical S-grid stretch/transform fun .. include:: InputsPhysics.rst + + +Runtime Error Checking +====================== + +Through `AMReX functionality `_, +REMORA supports options to raise errors when NaNs, division by zero, and overflow errors +are detected. These checks are activated at runtime using the input parameters below. + +.. note:: + + When running on Macs using the Apple-Clang compilers with optimization + (``DEBUG = FALSE`` in the ``GNUmakefile``), these checks may lead to false positives + due to optimizations performed by the compiler and the flags should be turned off. + It is still possible to run with these error checks with Apple-Clang debug builds. + +List of Parameters +------------------ + ++-----------------------------+---------------------------+-------------------+------------+ +| Parameter | Definition | Acceptable Values | Default | ++=============================+===========================+===================+============+ +| **amrex.fpe_trap_invalid** | Raise errors for NaNs | 0 / 1 | 0 | ++-----------------------------+---------------------------+-------------------+------------+ +| **amrex.fpe_trap_zero** | Raise errors for divide | 0 / 1 | 0 | +| | by zero | | | ++-----------------------------+---------------------------+-------------------+------------+ +| **amrex.fpe_trap_overflow** | Raise errors for overflow | 0 / 1 | 0 | ++-----------------------------+---------------------------+-------------------+------------+ diff --git a/Docs/sphinx_doc/building.rst b/Docs/sphinx_doc/building.rst index f4710da5..964091be 100644 --- a/Docs/sphinx_doc/building.rst +++ b/Docs/sphinx_doc/building.rst @@ -5,6 +5,31 @@ Building REMORA can be built using either GNU Make or CMake. The following instructions apply to building on any system. We also provide instructions for building on :ref:`Perlmutter`. +Minimum Requirements +~~~~~~~~~~~~~~~~~~~~ + +ERF requires a C++ compiler that supports the C++17 standard and a C compiler that supports the C99 standard. +Building with GPU support may be done with CUDA, HIP, or SYCL. +For CUDA, REMORA requires versions >= 11.0. For HIP and SYCL, only the latest compilers are supported. +Prerequisites for building with GNU Make include Python (>= 2.7, including 3) and standard tools available +in any Unix-like environments (e.g., Perl and sed). For building with CMake, the minimal requirement is version 3.18. + + .. note:: + **While REMORA is designed to work with SYCL, we do not make any guarantees that it will build and run on your Intel platform.** + +Paradigm +~~~~~~~~~~ + +REMORA uses the paradigm that different executables are built in different subdirectories within the ``Exec`` directory. When +using gmake (see below), the user/developer should build in the directory of the selected problem. When using +cmake (see below), separate executables are built for all of the problem directories listed in ``Exec/CMakeLists.txt``. +The problem directories within ``Exec`` include ``Upwelling`` a test case demonstrating a periodic channel with shelves on each side. +#1) science-relevant setups, such as ``ABL`` for modeling the atmospheric +#boundary layer or ``DensityCurrent`` for running the standard density current test case, etc, 2) regression tests in +#``Exec/RegTests`` that are used for testing specific known aspects of the code functionality, such as boundary conditions or +#Rayleigh damping, and 3) tests for features under development in ``Exec/DevTests``, such as moving terrain. There is a +#README in each problem directory that describes the purpose/role of that problem. + GNU Make ~~~~~~~~ @@ -53,6 +78,10 @@ or if using tcsh, +-----------------+----------------------------------+------------------+-------------+ | USE_CUDA | Whether to enable CUDA | TRUE / FALSE | FALSE | +-----------------+----------------------------------+------------------+-------------+ + | USE_HIP | Whether to enable HIP | TRUE / FALSE | FALSE | + +-----------------+----------------------------------+------------------+-------------+ + | USE_SYCL | Whether to enable SYCL | TRUE / FALSE | FALSE | + +-----------------+----------------------------------+------------------+-------------+ | DEBUG | Whether to use DEBUG mode | TRUE / FALSE | FALSE | +-----------------+----------------------------------+------------------+-------------+ | USE_NETCDF | Whether to compile with NETCDF | TRUE / FALSE | FALSE | diff --git a/Docs/sphinx_doc/testing.rst b/Docs/sphinx_doc/testing.rst index 85d2fe8e..47ccec1c 100644 --- a/Docs/sphinx_doc/testing.rst +++ b/Docs/sphinx_doc/testing.rst @@ -3,7 +3,7 @@ Testing and Verification ------------------------ -Testing and verification of REMORA can be performed using CTest, which is included in the CMake build system. If one builds REMORA with CMake, the testing suite, and the verification suite, can be enabled during the CMake configure step. A nightly test is reflected on the dashboard `here `_ . +Testing and verification of REMORA can be performed using CTest, which is included in the CMake build system. If one builds REMORA with CMake, the testing suite, and the verification suite, can be enabled during the CMake configure step. An example ``cmake`` configure command performed in the ``Build`` directory in REMORA is shown below with options relevant to the testing suite: @@ -63,7 +63,7 @@ For example, ``Upwelling`` problem with input file ``Exec/Upwelling/inputs`` sol Any file in the test directory will be copied during CMake configure to the test's working directory. The input files meant for regression test run only until a few time steps. The reference solution that the -regression test will refer to should be placed in ``Tests/REMORA-Gold-Files/``. Next, edit the +regression test will refer to should be placed in ``Tests/REMORA_Gold_Files/``. Next, edit the ``Exec/CMakeLists.txt`` and ``Tests/CTestList.cmake`` files, add the problem and the corresponding tests to the list. Note that there are different categories of tests and if your test falls outside of these categories, a new function to add the test will need to be created. After these steps, your test will be