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

Feature 2949 cxx11 doc #2973

Merged
merged 11 commits into from
Sep 19, 2024
Merged

Feature 2949 cxx11 doc #2973

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
9463035
Per #2949, updating installation instructions
jprestop Sep 16, 2024
aeeef13
Per #2949, adding missing colon from note directive
jprestop Sep 16, 2024
e6ff184
Per #2949, third attempt to get the new note to show up
jprestop Sep 16, 2024
6fd57b8
Per #2949, modifying text and format
jprestop Sep 16, 2024
76aedb2
Per #2949, removing images in favor of code blocks for easier modific…
jprestop Sep 16, 2024
19377c5
Per #2949, modified wording for clarity
jprestop Sep 16, 2024
fc101e0
Per #2929, corrected typo
jprestop Sep 16, 2024
4a661aa
Update installation.rst
JohnHalleyGotway Sep 17, 2024
413dbda
Update docs/Users_Guide/installation.rst
jprestop Sep 17, 2024
8432793
Per #2949, testing variable replacement, expect failures
jprestop Sep 17, 2024
52a0ef4
Per #2949, reverting to orignal state after testing
jprestop Sep 18, 2024
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
Binary file removed docs/Users_Guide/figure/installation_dir.png
View file
Open in desktop
Binary file not shown.
Binary file removed docs/Users_Guide/figure/installation_dir_after.png
View file
Open in desktop
Binary file not shown.
97 changes: 63 additions & 34 deletions docs/Users_Guide/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,9 +110,9 @@ format from GitHub, which the script will then install.
To begin, create and change to a directory where the latest version of MET will be
installed. Assuming that the following guidance uses “/d1” as the parent directory,
a suggested format is a path to a “met” directory, followed by the version number
subdirectory (e.g. */d1/met/12.0.0*).
subdirectory (e.g. */d1/met/|version|.0*).
Next, download the
`compile_MET_all.sh <https://raw.githubusercontent.com/dtcenter/MET/main_v12.0/internal/scripts/installation/compile_MET_all.sh>`_
`compile_MET_all.sh <https://raw.githubusercontent.com/dtcenter/MET/main_v|version|/internal/scripts/installation/compile_MET_all.sh>`_
script and
`tar_files.tgz <https://dtcenter.ucar.edu/dfiles/code/METplus/MET/installation/tar_files.tgz>`_
file and place both of these files in the
Expand All @@ -122,7 +122,7 @@ the terminal while in the directory MET will be installed in:

.. code-block:: ini

wget https://raw.githubusercontent.com/dtcenter/MET/main_v12.0/internal/scripts/installation/compile_MET_all.sh
wget https://raw.githubusercontent.com/dtcenter/MET/main_v|version|/internal/scripts/installation/compile_MET_all.sh
wget https://dtcenter.ucar.edu/dfiles/code/METplus/MET/installation/tar_files.tgz

The tar files will need to be extracted in the MET installation directory:
Expand All @@ -144,15 +144,15 @@ Now change directories to the one that was created from expanding the tar files:
cd tar_files

The next step will be to identify and download the latest MET release as a
tar file (e.g. **v12.0.0.tar.gz**) and place it in
tar file (e.g. **v|version|.0.tar.gz**) and place it in
the *tar_files* directory. The file is available from the
MET line under the “RECOMMENDED - COMPONENTS” section on the
`METplus website <https://dtcenter.org/community-code/metplus/download>`_ or
by using a wget command while in the *tar_files* directory:

.. code-block:: ini

wget https://github.com/dtcenter/MET/archive/refs/tags/v12.0.0.tar.gz
wget https://github.com/dtcenter/MET/archive/refs/tags/v|version|.0.tar.gz

.. _Install_Required-libraries-and:

Expand All @@ -162,24 +162,40 @@ Environment Variables to Run Script
Before running the compilation script, there are five environment variables
that are required:
**TEST_BASE**, **COMPILER**, **MET_SUBDIR**, **MET_TARBALL**, and **USE_MODULES**.

If compiling support for Python embedding, the script will need the following
additional environment variables: **MET_PYTHON**, **MET_PYTHON_CC**, and
**MET_PYTHON_LD**. All of these environment variables are discussed
in further detail in the Environment Variable Descriptions section below.
An easy way to set these environment variables is in an environment
configuration file (for example, **install_met_env.<machine_name>**). An
example environment configuration file to start from (**install_met_env.generic_gnu**),
as well as environment configuration files used on HPCs at NCAR and NOAA,
**MET_PYTHON_LD**.

All of these environment variables are discussed in further detail in the
Environment Variable Descriptions section below. An easy way to set these
environment variables is in an environment configuration file
(for example, **install_met_env.<machine_name>**). An example environment
configuration file to start with (**install_met_env.generic_gnu**),
as well as the environment configuration files used on HPCs at NCAR and NOAA,
can be found in the `MET GitHub repository <https://github.com/dtcenter/MET>`_ in the
`scripts/installation/config <https://github.com/dtcenter/MET/tree/main_v12.0/internal/scripts/installation/config>`_
`scripts/installation/config <https://github.com/dtcenter/MET/tree/main_v|version|/internal/scripts/installation/config>`_
directory.

.. note:: Starting with MET-|version|.0, C++17 is the default C++ standard for MET due to the requirements of its dependent libraries. However, MET itself only makes use of C++11 features.

The ATLAS library (conditionally required for MET, if support for
unstructured grids is desired)
`versions 0.33.0 <https://github.com/ecmwf/atlas/releases/tag/0.33.0>`_
and later requires compiler support for the C++17 standard.

At this time, users with systems that do not yet support the C++17
standard, can still compile MET with an older C++ standard, using an
older version of ATLAS, by adding the MET_CXX_STANDARD variable to
the environment configuration file as described in the **OPTIONAL**
section below.

Environment Variable Descriptions
---------------------------------

.. dropdown:: REQUIRED

**TEST_BASE** – Format is */d1/met/12.0.0*. This is the MET
**TEST_BASE** – Format is */d1/met/|version|.0*. This is the MET
installation directory that was created
the beginning of, :numref:`compile_script_install` and contains the
**compile_MET_all.sh** script, **tar_files.tgz**,
Expand All @@ -194,11 +210,11 @@ Environment Variable Descriptions
provided for the PGI family of compilers through “pgi”. However, this compiler
option is no longer actively tested.

**MET_SUBDIR** – Format is */d1/met/12.0.0*. This is the location where the top-level MET
**MET_SUBDIR** – Format is */d1/met/|version|.0*. This is the location where the top-level MET
subdirectory will
be installed and is often set equivalent to **TEST_BASE** (e.g. ${TEST_BASE}).

**MET_TARBALL** – Format is *v12.0.0tar.gz*. This is the name of the downloaded MET tarball.
**MET_TARBALL** – Format is *v|version|.0.tar.gz*. This is the name of the downloaded MET tarball.

**USE_MODULES** – Format is *TRUE* or *FALSE*. Set to FALSE if using a machine that does not use
modulefiles; set to TRUE if using a machine that does use modulefiles. For more information on
Expand All @@ -218,6 +234,7 @@ Environment Variable Descriptions
following environment variables if using the Intel compilers:

| For non-oneAPI Intel compilers:
|
| export FC=ifort
| export F77=ifort
| export F90=ifort
Expand All @@ -226,6 +243,7 @@ Environment Variable Descriptions


| For oneAPI Intel compilers:
|
| export FC=ifx
| export F77=ifx
| export F90=ifx
Expand All @@ -239,7 +257,6 @@ Environment Variable Descriptions
configuration file, and users with a oneAPI Intel compiler should use the
install_met_env.generic_intel_oneapi configuration file.


.. dropdown:: REQUIRED, IF COMPILING PYTHON EMBEDDING

**MET_PYTHON** – Format is */usr/local/python3*.
Expand Down Expand Up @@ -289,13 +306,13 @@ Environment Variable Descriptions

**export MET_CXX_STANDARD** - Specify the version of the supported
C++ standard. Values may be 11, 14, or 17. The default value is 17.
(e.g. export MET_CXX_STANDARD=11).
(e.g. export MET_CXX_STANDARD=11)


External Library Handling in compile_MET_all.sh
-----------------------------------------------

.. dropdown:: IF THE USER WANTS TO HAVE THE COMPILATION SCRIPT DOWNLOAD THE LIBRARY DEPENDENCIES
.. dropdown:: IF THE USER WANTS TO HAVE THE COMPILATION SCRIPT COMPILE THE LIBRARY DEPENDENCIES

The **compile_MET_all.sh** script will compile and install MET and its
:ref:`required_external_libraries_to_build_MET`, if needed.
Expand Down Expand Up @@ -399,7 +416,21 @@ particular system’s needs, MET is ready for installation. The screenshot below
contents of the installation directory followed by the tar_files subdirectory at
this step on the machine ‘hera’.

.. image:: figure/installation_dir.png
.. code-block:: ini

/contrib/met/|version|.0$ ls
compile_MET_all.sh install_met_env.hera tar_files

/contrib/met/|version|.0$ ls tar_files
HDF-EOS2.16v1.00.tar.Z eckit-1.24.4.tar.gz netcdf-4.7.4.tar.gz
HDF4.2r3.tar.gz freetype-2.11.0.tar.gz netcdf-cxx4-4.3.1.tar.gz
atlas-0.30.0.tar.gz g2clib-1.6.4.tar.gz pixman-0.40.0.tar.gz
atlas-0.35.0.tar.gz gsl-1.11.tar.gz proj-7.1.0.tar.gz
bufr_v11.6.0.tar.gz gsl-2.7.1.tar.gz sqlite-autoconf-3430100.tar.gz
cairo-1.16.0.tar.xz hdf5-1.12.2.tar.gz tiff-4.6.0.tar.gz
ecbuild-3.5.0.tar.gz jasper-2.0.25.tar.gz zlib-1.2.11.tar.gz
ecbuild-3.7.0.tar.gz jpegsrc.v9e.tar.gz
eckit-1.20.2.tar.gz libpng-1.6.37.tar.gz

Simply enter the following into the terminal to execute the script:

Expand All @@ -409,14 +440,17 @@ Simply enter the following into the terminal to execute the script:

The screenshot below shows the contents of the installation directory after installation:

.. image:: figure/installation_dir_after.png
.. code-block:: ini

/contrib/met/|version|.0$ ls
MET-|version|.0 bin compile_MET_all.sh external_libs install_met_env.hera share tar_files

To confirm that MET was installed successfully, run the following command from the installation directory to check for errors in the test file:

.. code-block:: ini
grep -i error MET12.0.0/met.make_test.log

grep -i error MET-|version|.0/met.make_test.log

If no errors are returned, the installation was successful.
Due to the highly variable nature of hardware systems, users may encounter issues during
the installation process that result in MET not being installed. If this occurs please
Expand Down Expand Up @@ -463,7 +497,6 @@ version. If a different version is required, select the correct
version from the dropdown option. Follow Docker’s instructions
for a successful installation.


Loading the Latest Docker Image of MET
--------------------------------------

Expand All @@ -474,14 +507,13 @@ MET version number, for example:

.. code-block:: ini

docker pull dtcenter/met:12.0.0
docker pull dtcenter/met:|version|.0

Omitting the
version number will result in an error due to Docker’s behavior
of attempting to retrieve an image with the “latest” tag, which
MET no longer uses.


Running the Docker version of MET
---------------------------------

Expand All @@ -501,8 +533,8 @@ the same way the latest image of MET was pulled:

.. code-block:: ini

docker run -it --rm dtcenter/met:12.0.0 /bin/bash
docker run -it --rm dtcenter/met:|version|.0 /bin/bash

If the usage MET via Docker images was successful, it is highly
recommended to move on
to using the METplus wrappers of the tools, which have their own
Expand Down Expand Up @@ -550,8 +582,7 @@ to make the container:

.. code-block:: ini

singularity build met-12.0.0.sif docker://dtcenter/met:12.0.0

singularity build met-|version|.0.sif docker://dtcenter/met:|version|.0

Running the MET Container
-------------------------
Expand All @@ -562,7 +593,7 @@ MET command line usage:

.. code-block:: ini

singularity exec met-12.0.0.sif plot_data_plane /home/data/fcst_006.grb2 image_output.ps ‘name=”TMP”; level=”Z0”;’
singularity exec met-|version|.0.sif plot_data_plane /home/data/fcst_006.grb2 image_output.ps ‘name=”TMP”; level=”Z0”;’

Stopping the Apptainer Instance
-------------------------------
Expand All @@ -573,7 +604,7 @@ be used otherwise the instance will continue to run in the background:

.. code-block:: ini

singularity instance stop /path/to/container/met-12.0.0.sif met-12.0.0
singularity instance stop /path/to/container/met-|version|.0.sif met-|version|.0

Now that MET is successfully installed, it is highly recommended to
next install the METplus wrappers to take full advantage of
Expand All @@ -583,5 +614,3 @@ Users can also proceed to the
and run through the examples that only utilize the MET processes
(METplus wrapper applications and commands will not work unless
METplus wrappers are also installed).