Merge branch 'develop' into AlexanderRichert-NOAA-patch-1

doc/source/KnownIssues.rst

@@ -109,10 +109,6 @@ macOS
 
    Can happen when trying to use the raster plotting scripts in ``fv3-jedi-tools``. In that case, exporting ``DYLD_LIBRARY_PATH=/usr/lib/:$DYLD_LIBRARY_PATH`` can help. If ``git`` commands fail after this, you might need to verify where ``which git`` points to (Homebrew vs module) and unload the ``git`` module.
 
-6. Not all versions of ``apple-clang@15.0.0`` are currently supported.
-
-   If you are running macOS Sonoma 14.5 you may have a recent version of clang that does not yet build spack packages. On the console you should run ``clang --version`` and verify that the underlying clang compiler is ``clang-1500.1.0.2.5`` which is the version provided with Command Line Tools for XCode 15.1. You can downgrade your Command Line Tool packages by first running ``sudo rm -rf /Library/Developer/CommandLineTools`` then you can download and install the Command Line Tools 15.1 APK from `developer.apple.com <https://developer.apple.com/download/all/>`_. The Apple Developer site requires an iCloud login.
-
 ==============================
 Ubuntu
 ==============================

doc/source/NewSiteConfigs.rst

@@ -32,8 +32,7 @@ The instructions below are for GNU (`gcc`), since this is the easiest and best s
   We have noted problems on some - not all - platforms with ``[email protected]`` when we switched from ``zlib`` to ``zlib-ng`` in spack-stack-1.7.0. These issues went away when using a different version of the compiler (anything between 2021.3.0 and 2021.11.0). It is therefore recommended to avoid using ``[email protected]`` unless it is the only option.
 
 .. [#fn2]
-  Note that ``[email protected]`` compiler versions are fully supported, and ``[email protected]`` will work but requires the :ref:`workaround noted below<apple-clang-15-workaround>`.
-  Also, when using ``[email protected]`` you must use Command Line Tools version 15.1, and the Command Line Tools versions 15.3 and newer are not yet supported.
+  Note that ``[email protected]`` and ``[email protected]`` compiler versions are fully supported, and when using ``[email protected]`` the :ref:`workaround noted below<apple-clang-15-workaround>` is required.
 
 .. [#fn3]
   Support for Nvidia compilers is experimental and limited to a subset of packages. Please refer to :numref:`Section %s <NewSiteConfigs_Linux_CreateEnv_Nvidia>` below.
@@ -285,8 +284,8 @@ Remember to activate the ``lua`` module environment and have MacTeX in your sear
 
 .. _apple-clang-15-workaround:
 .. note::
-  When using apple-clang@15.0.0 (or newer) compilers, you need to manually add the following ldflags spec in the `site/compilers.yaml` file.
-  There are known issues with new features in the Apple linker/loader that comes with the 15.0.0 compiler set, and this change tells the linker/loader to use its legacy features which work fine.
+  When using apple-clang@15.x (or newer) compilers, you need to manually add the following ldflags spec in the `site/compilers.yaml` file.
+  There are known issues with new features in the Apple linker/loader that comes with the 15.x compiler set, and this change tells the linker/loader to use its legacy features which work fine.
 
 .. code-block:: yaml
   :emphasize-lines: 9,10

doc/source/UsingSpackEnvironments.rst

@@ -5,6 +5,17 @@ Using spack-stack environments
 
 The following tutorial assumes you have a functioning spack-stack environment installed local to your system. This environment is provided on platforms described in :numref:`Section %s <Preconfigured_Sites>`. If you intend to run spack-stack on your developer machine or on a new platform, you can create an environment using the steps described in :numref:`Section %s <NewSiteConfigs>`.
 
+There are three steps in setting up a usable development environment.
+The first is to load the spack-stack environment and the second is to create a python virtual environment that is based on the python executable included within the spack-stack installation.
+The reason for the python virtual environment is to ensure that python based applications are utilizing the spack-stack python modules in a consistent manner.
+The third step is to configure your build system to use the python virtual environment created in the second step.
+
+When using a spack-stack environment please utilize the spack-stack installed python modules as much as possible to help maintain the consistency mentioned above.
+Note that after loading the spack-stack environment, all of the spack-stack installed python modules have been added to :code:`PYTHONPATH` so they are immediately accessable in your spack-stack based python virtual environment.
+
+Load the spack-stack environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Spack environments are used by loading the modulefiles generated at the end of the installation process. These modules control the unix environment and allow CMake, ecbuild, and other build toolchains to resolve the version of software intended for the compilation task. The ``spack`` command itself is not needed in this setup, hence the instructions for creating new environments (``source setup.sh`` etc.) can be ignored. The following is sufficient for loading the modules, allowing them to be used while compiling and running user code.
 
 .. note::
@@ -28,3 +39,78 @@ Now list all available modules via ``module available``. You may be required to
 
 .. note::
    When using ``lua`` modules, loading a different module will automatically switch the dependency modules. This is not the case for ``tcl`` modules. For the latter, it is recommended to start over with a clean shell and repeat the above steps.
+
+Create and activate a python virtual environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is important that the creation of the python virtual environment be based on the python executable from the spack-stack installation.
+This ensures consistency for python applications between the python executable and the spack-stack installed python packages (eg., numpy).
+Without this consistency, it is easy for the wrong underlying library versions to get dynamically loaded and cause problems with applications crashing.
+
+After the :code:`module load stack-python-name/python-version` command is run, the environment variable :code:`python_ROOT` will be set to the path where the spack-stack installed python version is located.
+The :code:`python_ROOT` variable can be used to ensure that you get the proper virtual environment set as shown here:
+
+.. code-block:: console
+
+    ${python_ROOT}/bin/python3 -m venv <path-to-python-virtual-env>
+
+Once the virtual environment is set, it must be activated:
+
+.. code-block:: console
+
+   source <path-to-python-virtual-env>/bin/activate
+
+and after activation the spack-stack python executable will be the first one in your PATH.
+The implication of this is that you should activate the python virtual enviroment as the last step in setting up your environment to ensure that the path to the virtual environment python remains first in your PATH. Here is an example of the whole process:
+
+.. code-block:: console
+
+    # start from clean slate
+    module purge
+
+    # load the base packages from the spack-stack environment
+    module use $SPACK_STACK_GNU_ENV/install/modulefiles/Core
+    module load stack-gcc/12.2.0
+    module load stack-openmpi/4.1.4
+    module load stack-python/3.11.7
+
+    # load the additional environments required for your
+    # target application
+    module load jedi-fv3-env
+    module load ewok-env
+    module load soca-env
+
+    # Create and activate the spack-stack based python
+    # virtual environment
+    # Note that you only need to create the virtual environment
+    # the first time. Once created you only need to activate
+    # the virtual environment.
+    cd $HOME/projects/jedi
+    ${python_ROOT}/bin/python3 -m venv jedi_py_venv # first time only
+    source jedi_py_venv/bin/activate
+
+Configure build system to utilize the python virtual environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Configuring your application build system to use the python virtual environment will continue the goal of consistency mentioned above where all python scripts and packages within the target application are based on the spack-stack built python executable and packages.
+
+There are a variety of build systems in use, and CMake is quite commonly used so CMake will be used as an example for this step.
+The CMake variable :code:`Python3_FIND_STRATEGY` can be used in conjunction with the python virtual environment to direct CMake to find and use the desired python virtual environment.
+By default CMake chooses the latest python installation regardless of which comes first in your PATH.
+By setting :code:`Python3_FIND_STRATEGY=LOCATION`, CMake will instead find and use the first python installation found in your PATH.
+This is the reason for making the spack-stack based python virtual environment first in PATH in the step above.
+
+:code:`Python3_FIND_STRATEGY` can be set in two ways: the first in the project's top-level CMakeLists.txt file and the second on the cmake (or ecbuild) command line.
+Here are examples of both methods:
+
+.. code-block:: console
+
+   # In CMakeLists.txt
+   set( Python3_FIND_STRATEGY LOCATION )
+
+.. code-block:: console
+
+   # On the command line
+   cmake -DPython3_FIND_STRATEGY=LOCATION ...
+
+