Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updated the Introduction, build for MacOS #281

Merged
merged 3 commits into from
Jun 2, 2022
Merged

Updated the Introduction, build for MacOS #281

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
99c2e4c
Updated the Introduction, build for MacOS
natalie-perlin May 27, 2022
35d178f
Update Introduction.rst
natalie-perlin May 31, 2022
5982034
Update Introduction.rst
natalie-perlin Jun 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 7 additions & 12 deletions docs/UsersGuide/source/BuildRunSRW.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,7 @@ Set Up the Workflow Environment

.. attention::
If users successfully built the executables in :numref:`Step %s <DevBuild>`, they should skip to step :numref:`Step %s <Data>`.
For the CMake steps on MacOS systems, follow the approach in :numref:`Step %s <MacDetails>`.

If the ``devbuild.sh`` approach failed, users need to set up their environment to run a workflow on their specific platform. First, users should make sure ``Lmod`` is the app used for loading modulefiles. This is the case on most Level 1 systems; however, on systems such as Gaea/Odin, the default modulefile loader is from Cray and must be switched to Lmod. For example, on Gaea, assuming a ``bash`` login shell, run:

Expand Down Expand Up @@ -339,25 +340,20 @@ Then, users must source the Lmod setup file, just as they would on other systems
source etc/lmod-setup.sh macos
module use <path/to/ufs-srweather-app/modulefiles>
module load build_macos_gnu
export LDFLAGS="-L${MPI_ROOT}/lib"

In a csh/tcsh shell, users would run ``source etc/lmod-setup.csh macos`` in place of the first line in the code above.

.. note::
If you execute ``source etc/lmod-setup.sh`` on systems that don't need it, it will simply do a ``module purge``.

Additionally, for Option 1 systems, set the variable ``ENABLE_QUAD_PRECISION`` to ``OFF`` in line 35 of the ``$SRW/src/ufs-weather-model/FV3/atmos_cubed_sphere/CMakeLists.txt`` file. This change is optional if using Option 2 to build the SRW App. Using a text editor (e.g., vi, vim, emacs):
Additionally, for Option 1 systems, set the variable ``ENABLE_QUAD_PRECISION`` to ``OFF`` in ``$SRW/src/ufs-weather-model/FV3/atmos_cubed_sphere/CMakeLists.txt`` file. This change is optional if using Option 2 to build the SRW App. You could use a streamline editor `sed` to change it:

.. code-block:: console

option(ENABLE_QUAD_PRECISION "Enable compiler definition -DENABLE_QUAD_PRECISION" OFF)

An alternative way to make this change is using a `sed` (streamline editor). From the command line, users can run one of two commands (user's preference):

.. code-block:: console

sed -i -e 's/QUAD_PRECISION\" ON)/QUAD_PRECISION\" OFF)/' CMakeLists.txt
sed -i -e 's/bin\/sh/bin\/bash/g' *sh
sed -i .bak 's/QUAD_PRECISION\" ON)/QUAD_PRECISION\" OFF)/' $SRW/src/ufs-weather-model/FV3/atmos_cubed_sphere/CMakeLists.txt

Proceed to building executables using CMake in :numref:`Step %s <BuildCMake>`

.. _Data:

Expand Down Expand Up @@ -908,7 +904,7 @@ For Option 1 (8 CPUs):

# Architecture information
WORKFLOW_MANAGER="none"
NCORES_PER_NODE=${NCORES_PER_NODE:-8} (Option 2: when 4 CPUs, set to 4)
NCORES_PER_NODE=${NCORES_PER_NODE:-8}
SCHED=${SCHED:-"none"}

# UFS SRW App specific paths
Expand All @@ -925,9 +921,8 @@ For Option 1 (8 CPUs):
RUN_CMD_UTILS="mpirun -np 4"
RUN_CMD_FCST='mpirun -np ${PE_MEMBER01}'
RUN_CMD_POST="mpirun -np 4"
PRE_TASK_CMDS='{ulimit -a;}'

The same settings can be used for Option 2, except that ``NCORES_PER_NODE=${NCORES_PER_NODE:-8}`` should be set to 4 instead of 8.
Using Option 2 with 4 CPUs requires ``NCORES_PER_NODE=${NCORES_PER_NODE:-4}`` in the above example.

.. _MacActivateWFenv:

Expand Down
50 changes: 22 additions & 28 deletions docs/UsersGuide/source/Introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,6 @@ The SRW App v1.0.0 citation is as follows and should be used when presenting res

UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994

..
COMMENT: Update version numbers/citation for release! Also update release date for citation!


How to Use This Document
========================
Expand Down Expand Up @@ -51,7 +48,7 @@ The instructions in this documentation assume that users have certain background
* Familiarity with LINUX/UNIX systems
* Command line basics
* System configuration knowledge (e.g., compilers, environment variables, paths, etc.)
* Numerical Weather Prediction
* Numerical Weather Prediction (concepts of parameterizations: physical, microphysical, convective)
* Meteorology (particularly meteorology at the scales being predicted)

..
Expand All @@ -73,12 +70,12 @@ The UFS SRW Application has been designed so that any sufficiently up-to-date ma

* POSIX-compliant UNIX-style operating system

* >40 GB disk space
* >102 GB disk space

* 18 GB input data from GFS, RAP, and HRRR for "out-of-the-box" SRW App case described in :numref:`Chapter %s <BuildRunSRW>`
* 6 GB for :term:`HPC-Stack` full installation
* 1 GB for ufs-srweather-app installation
* 11 GB for 48hr forecast on CONUS 25km domain
* 54 GB input data from GFS, RAP, and HRRR for "out-of-the-box" SRW App case described in :numref:`Chapter %s <BuildRunSRW>`
natalie-perlin marked this conversation as resolved.
Show resolved Hide resolved
* 8 GB for :term:`HPC-Stack` full installation
* 3 GB for ufs-srweather-app installation
* 17 GB for 12hr forecast on CONUS 25km domain

* 4GB memory (CONUS 25km domain)

Expand All @@ -88,58 +85,55 @@ The UFS SRW Application has been designed so that any sufficiently up-to-date ma

* C and C++ compilers compatible with the Fortran compiler

* gcc v9+, ifort v18+, and clang v9+ (macOS, native Apple clang or LLVM clang) have been tested
* gcc v9+, ifort v18+, and clang v9+ (macOS, native Apple clang, LLVM clang, GNU) have been tested

* Python v3.6+, including prerequisite packages ``jinja2``, ``pyyaml`` and ``f90nml``

* Python packages ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``, and ``pillow`` are required for users who would like to use the provided graphics scripts

* Perl 5

* git v1.8+
* git v2.12+

..
COMMENT: Should curl/wget/TIFF library also be required? These are listed as prerequisites for building HPC-Stack on generic MacOS/Linux
* curl

* wget

..
COMMENT: Should curl/wget/TIFF library also be required? These are listed as prerequisites for building HPC-Stack on generic MacOS/Linux | A: TIFF could be installed with the HPC-stack build; others are needed

The following software is also required to run the SRW Application, but the :term:`HPC-Stack` (which contains the software libraries necessary for building and running the SRW App) can be configured to build these requirements:

* CMake v3.15+
* CMake v3.20+

* MPI (MPICH, OpenMPI, or other implementation)

* Only **MPICH** can be built with HPC-Stack. Other options must be installed separately by the user.

* Software libraries

* netCDF (C and Fortran libraries)
* HDF5
* ESMF 8.2.0
* Jasper
* libJPG
* libPNG
* zlib
* Only **MPICH** or **OpenMPI** can be built with HPC-Stack. Other implementations must be installed separately by the user.

For MacOS systems, some additional software is needed. It is recommended that users install this software using the `Homebrew <https://brew.sh/>`__ package manager for MacOS:

* brew install bash

* OR: brew upgrade bash
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@natalie-perlin Should we just list the software instead of the commands? The commands already appear in the instructions for installing HPC-Stack and in the MacOS-specific SRW instructions. At a minimum, I don't think we need the brew upgrade bash command because we're just listing what they should have on their system. The upgrade statement appears elsewhere in the docs.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The important point here is that bash used to be included with the MacOS system until recently, when Apple stopped supporting and upgrading to a newer bash versions. The latest recent version of bash distributed with the macOS is
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin20)
whereas at least bash v.4 is recommended.
So while it is present in MacOS, it cannot be simply upgraded using homebrew, because there is no previous brew installation of bash .
Thus the comments about
brew install bash and brew upgrade bash

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@natalie-perlin Then the prerequisite we list should be bash v4.x. The logistics of installing it are in other places. If you prefer, I can make that change in my PR tho.

* brew install gcc@11
* brew install cmake
* brew install make
* brew install wget
* brew install lmod
gspetro-NOAA marked this conversation as resolved.
Show resolved Hide resolved
* brew install coreutils
* brew install pkg-config

..
COMMENT: Is this still accurate? It seems like we should delete the last one. And gcc@11 is basically the same as requiring fortran/C/C++ compilers, no? CMake is listed above.
COMMENT: Is this still accurate? It seems like we should delete the last one. And gcc@11 is basically the same as requiring fortran/C/C++ compilers, no? CMake is listed above. | A: updated bash requirements

Optional but recommended prerequisites for all systems:

* Conda for installing/managing Python packages
* Bash v4+
* Rocoto Workflow Management System (1.3.1)
* Python packages ``scipy``, ``matplotlib``, ``pygrib``, ``cartopy``, and ``pillow`` for graphics
* Lmod

..
COMMENT: Lmod is listed as required
gspetro-NOAA marked this conversation as resolved.
Show resolved Hide resolved

.. _ComponentsOverview:

Expand Down