From 800d9b6aa1690159989955a5ec51e6a8f2dc3a4e Mon Sep 17 00:00:00 2001 From: "Michael Kavulich, Jr" Date: Tue, 21 Nov 2023 13:06:36 -0700 Subject: [PATCH] Update documentation for new build process. Note that the PDF has not been re-generated: my laptop currently lacks the necessary software (hopefully will get it soon). --- scm/doc/TechGuide/chap_quick.tex | 18 +++++++----------- scm/doc/TechGuide/chap_repo.tex | 13 +------------ 2 files changed, 8 insertions(+), 23 deletions(-) diff --git a/scm/doc/TechGuide/chap_quick.tex b/scm/doc/TechGuide/chap_quick.tex index 451613b59..79c539463 100644 --- a/scm/doc/TechGuide/chap_quick.tex +++ b/scm/doc/TechGuide/chap_quick.tex @@ -99,19 +99,15 @@ \subsection{Compilers} release website (\url{https://dtcenter.org/community-code/common-community-physics-package-ccpp/download}). \subsection{Using Existing Libraries on Preconfigured Platforms}\label{section: use_preconfigured_platforms} -Platform-specific scripts are provided to load modules and set the user environment for preconfigured platforms. These scripts load compiler modules (Fortran 2008-compliant), the NetCDF module, Python environment, etc. and set compiler and environment variables. From the top-level code directory (\execout{ccpp-scm} by default), source the correct script for your platform and shell. For \textit{t/csh} shells, -\begin{lstlisting}[language=csh] -source scm/etc/Hera_setup_intel.csh -source scm/etc/Cheyenne_setup_gnu.csh -source scm/etc/Cheyenne_setup_intel.csh -\end{lstlisting} -For bourne/bash shells, -\begin{lstlisting}[language=bash] -. scm/etc/Hera_setup_intel.sh -. scm/etc/Cheyenne_setup_gnu.sh -. scm/etc/Cheyenne_setup_intel.sh +Because the SCM can be built using the so-called \href{https://ufs-weather-model.readthedocs.io/en/latest/Glossary.html#term-spack-stack}{"spack-stack" libraries} maintained for the UFS Weather Model effort, there are many platforms where the SCM can be built using those existing libraries. This can be done by loading provided modules in the \execout{scm/etc/modules} directory (must be done from the top-level "ccpp-scm" directory; otherwise the \execout{module use} command should point to the corresponding absolute path): + +\begin{lstlisting}[language=sh] +module purge +module use scm/etc/modules +module load [machine]_[compiler] \end{lstlisting} +View the contents of the \execout{scm/etc/modules} directory to see if your machine/compiler combination is supported. As of this writing, modulefiles are provided for Intel and GNU compilers on the NCAR machine Derecho, the NOAA machines Hera and Jet, and the NOAA/MSU machine Orion. Loading these modules will set up all the needed compilers, libraries, and other programs needed for building, as well as the python libraries needed for both building and running the SCM. \subsection{Installing Libraries on Non-preconfigured Platforms}\label{section: setup_supported_platforms} For users on supported platforms such as generic Linux or macOS systems that have not been preconfigured, the \execout{hpc-stack} project is suggested for installing prerequisite libraries. Visit \url{https://github.com/NOAA-EMC/hpc-stack} for instructions for installing prerequisite libraries via \execout{hpc-stack} in their docs directory. UFS users who already installed libraries via the \execout{hpc-stack} package only need to set the compiler (\execout{CC, CXX, FC}), NetCDF (\execout{NetCDF\_ROOT}), and \execout{bacio}, \execout{sp} and \execout{w3emc} (\execout{bacio\_ROOT}, \execout{sp\_ROOT}, \execout{w3emc\_ROOT}) environment variables to point to their installation paths in order to compile the SCM. diff --git a/scm/doc/TechGuide/chap_repo.tex b/scm/doc/TechGuide/chap_repo.tex index 4c61361b8..f28f0588e 100644 --- a/scm/doc/TechGuide/chap_repo.tex +++ b/scm/doc/TechGuide/chap_repo.tex @@ -26,32 +26,21 @@ \section{What is included in the repository?} .3 Dockerfile\DTcomment{contains Docker instructions for building the CCPP SCM image}. .2 README.md. .2 scm/. - .3 bin/\DTcomment{build directory (initially empty; populated by cmake)}. .3 data/\DTcomment{build directory (most data directories populated by contrib/get\_all\_static\_data.sh)}. - .4 comparison\_data/\DTcomment{initially empty; contains data with which to compare SCM output}. - .4 physics\_input\_data/\DTcomment{initially empty; contains data needed by the CCPP physics}. - .4 processed\_case\_input/\DTcomment{initially empty; contains initialization and forcing data for cases}. - .4 raw\_case\_input/\DTcomment{initially empty; contains case data to be processed by scripts}. .4 vert\_coord\_data/\DTcomment{contains data to calculate vertical coordinates (from GSM-based GFS only)}. .3 doc/\DTcomment{contains this User's/Technical Guide}. .4 TechGuide/\DTcomment{contains LaTeX for this User's Guide}. .3 etc/\DTcomment{contains case configuration, machine setup scripts, and plotting scripts}. .4 case\_config/\DTcomment{contains case configuration files}. .4 CENTOS\_docker\_setup.sh\DTcomment{contains machine setup for Docker container}. - .4 Cheyenne\_setup\_gnu.csh\DTcomment{setup script for Cheyenne HPC for csh, tcsh}. - .4 Cheyenne\_setup\_gnu.sh\DTcomment{setup script for Cheyenne HPC for sh, bash}. - .4 Cheyenne\_setup\_intel.csh\DTcomment{setup script for Cheyenne HPC for csh, tcsh}. - .4 Cheyenne\_setup\_intel.sh\DTcomment{setup script for Cheyenne HPC for sh, bash}. .4 Desktop\_setup\_gfortran.csh\DTcomment{setup script for Mac Desktop for csh, tcsh}. .4 Desktop\_setup\_gfortran.sh\DTcomment{setup script for Mac Desktop for sh, bash}. - .4 Hera\_setup\_intel.csh\DTcomment{setup script for Theia HPC for csh, tcsh}. - .4 Hera\_setup\_intel.sh\DTcomment{setup script for Theia HPC for sh, bash}. + .4 modules/\DTcomment{Directory containing modulefiles for building on HPC environments (see section \ref{section: use_preconfigured_platforms})}. .4 scm\_qsub\_example.py\DTcomment{example QSUB run script}. .4 scm\_slurm\_example.py\DTcomment{example SLURM run script}. .4 scripts/\DTcomment{Python scripts for setting up cases and plotting}. .5 plot\_configs/\DTcomment{plot configuration files}. .4 tracer\_config\DTcomment{tracer configuration files}. .3 LICENSE.txt. - .3 run/\DTcomment{initially empty; populated by run\_scm.py}. .3 src/\DTcomment{source code for SCM infrastructure, Python run script, CMakeLists.txt for the SCM, example multirun setup files, suite\_info.py}. }}