From 2cab4602fbc743380513566fd3ed1011895d2da6 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 31 Mar 2023 18:58:25 -0400 Subject: [PATCH 01/54] Shared docs: Updates to bashdatacatalog, using KPP w/ GC guides This commit informs the GCHP superproject about the following commits that were pushed to the geos-chem-shared-docs submodule: cf2f56a Updated "Using KPP with GEOS-Chem" guide w/ info for KPP 3.0.0 e59bb2e The bashdatacatalog guide now points to geoschem/bashdatacatalog e8b0bd3 Update using-kpp-with-gc.rst supplemental guide Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 228288d9b..cf2f56a3a 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 228288d9bbd3858d353d80199997c6e738284564 +Subproject commit cf2f56a3a557af56d692fc72132b383664e5a10e From 47bccf347a3fd614b08eac896b18a9de0d47b445 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 3 Apr 2023 11:14:18 -0400 Subject: [PATCH 02/54] geos-chem-shared-docs update: Add spack folder here docs/source/geos-chem-shared-docs - Move the spack folder here in anticipation of centralizing the instructions for building libraries with Spack Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index cf2f56a3a..b0e43a290 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit cf2f56a3a557af56d692fc72132b383664e5a10e +Subproject commit b0e43a290c4822862085baa995a03bb4a1415610 From cb1e4c77c3ca2761590d399f8cfb5a936071fa97 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 3 Apr 2023 11:15:57 -0400 Subject: [PATCH 03/54] Remove spack folder This has been migrated to docs/source/geos-chem-shared-docs Signed-off-by: Bob Yantosca --- spack/aws-parallelcluster-3.0.1/packages.yaml | 14 ------- spack/modules.yaml | 13 ------- spack/packages.yaml | 37 ------------------- 3 files changed, 64 deletions(-) delete mode 100644 spack/aws-parallelcluster-3.0.1/packages.yaml delete mode 100644 spack/modules.yaml delete mode 100644 spack/packages.yaml diff --git a/spack/aws-parallelcluster-3.0.1/packages.yaml b/spack/aws-parallelcluster-3.0.1/packages.yaml deleted file mode 100644 index 6729a7369..000000000 --- a/spack/aws-parallelcluster-3.0.1/packages.yaml +++ /dev/null @@ -1,14 +0,0 @@ -packages: - openmpi: - externals: - - spec: "openmpi@4.1.1%gcc@7.3.1 fabrics=none schedulers=auto +cuda+romio+pmi+pmix+thread_multiple" # run ompi_info | grep -i KEYWORD - prefix: /opt/amazon/openmpi - buildable: False - intel-oneapi-mpi: - version: [2021.5.1] - variants: +external-libfabric - libfabric: - externals: - - spec: "libfabric@1.13.0%gcc fabrics=efa,rxm,rxd,shm,mrail,sockets,tcp,udp" # run `fi_info --list` on an exec-node - prefix: /opt/amazon/efa - buildable: False diff --git a/spack/modules.yaml b/spack/modules.yaml deleted file mode 100644 index b0a20e7a8..000000000 --- a/spack/modules.yaml +++ /dev/null @@ -1,13 +0,0 @@ -# DESCRIPTION This file has recommended module settings for GCHP dependencies. It is meant to be -# used by including GCHP/spack as a custom scope for spack. - -modules: - default: - tcl: - naming_scheme: '{name}-{version}' - intel-oneapi-compilers: - environment: - set: - CC: 'icc' - CXX: 'icpc' - FC: 'ifort' diff --git a/spack/packages.yaml b/spack/packages.yaml deleted file mode 100644 index 739c4242f..000000000 --- a/spack/packages.yaml +++ /dev/null @@ -1,37 +0,0 @@ -# DESCRIPTION This file has recommended package settings for GCHP dependencies. It is meant to be -# used by including GCHP/spack as a custom scope for spack. -# -# HOW TO UPGRADE -# 1. Update pacakge..version to the appropriate version number -# 2. Check for changes to the variants by running `spack info @`. Only the -# required extensions should be enabled. -# 3. Verify install spec with updated geoschem-deps/package.yaml by running -# spack -C GCHP/spack spec -I esmf%intel ^intel-oneapi-mpi -# spack -C GCHP/spack spec -I esmf%intel ^openmpi -# Check for duplicate installs (same package different hash) and unnecessary dependencies. - -packages: - hdf5: - variants: ~mpi - esmf: - version: [8.0.1] - variants: ~pio~pnetcdf~xerces - compiler: [intel, gcc] - netcdf-c: - version: [4.8.1] - variants: ~dap~fsync~hdf4~jna~mpi~parallel-netcdf+pic+shared - netcdf-fortran: - version: [4.5.3] - variants: ~doc+pic+shared - cmake: - version: [3.22.2] - variants: ~doc~ncurses+openssl+ownlibs~qt - intel-oneapi-compilers: - version: [2022.0.2] - intel-oneapi-mpi: - version: [2021.5.1] - variants: +external-libfabric - all: - target: [x86_64] - providers: - mpi: [intel-oneapi-mpi, openmpi] From 213c38bcd6101541aeef84b5caef758ce80dd4ab Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 3 Apr 2023 11:17:10 -0400 Subject: [PATCH 04/54] Add symbolic link to docs/source/geos-chem-shared-docs/spack The spack files used for installation of library dependencies have been moved to the geos-chem-shared-docs repository, so that they can be used by GEOS-Chem, GCHP, and HEMCO. Signed-off-by: Bob Yantosca --- spack | 1 + 1 file changed, 1 insertion(+) create mode 120000 spack diff --git a/spack b/spack new file mode 120000 index 000000000..93f0d1546 --- /dev/null +++ b/spack @@ -0,0 +1 @@ +docs/source/geos-chem-shared-docs/spack \ No newline at end of file From b853d40c2887498f3d6d91a82526d91109d2ede0 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 5 Apr 2023 16:27:37 -0400 Subject: [PATCH 05/54] geos-chem-shared-docs update: Add new Spack installation guide This commit now informs the GCHP superproject about the following commits that were pushed to geos-chem-shared-docs: 968a1a4 Remove supplemental-guides/spack.rst Guide bb5c03a Finalize update of spack-guide.rst; Remove older spack.rst guide d65167b Update supplemental-guides/spack-guide.rst for latest build instructions c7eb719 Further updates for spack/packages.yaml 7ca84a1 Further updates to spack/packages.yaml 1a24255 Add updates to the spack/packages.yaml file 211dbbf Update spack/packages.yaml for GCC compiler 10.2.0 9540f40 Update header comments in spack/modules.yaml Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index b0e43a290..968a1a480 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit b0e43a290c4822862085baa995a03bb4a1415610 +Subproject commit 968a1a48023c0785a06eff4dea962e380cc77146 From 5af8852d459e10d401c61b2266e0425c8292997c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 5 Apr 2023 16:28:46 -0400 Subject: [PATCH 06/54] Now point to updated Spack installation guide docs/source/index.rst - Now point to new spack-rst supplemental guide in geos-chem-shared-docs docs/source/building-gchp-dependencies.rst - Removed Signed-off-by: Bob Yantosca --- docs/source/index.rst | 2 +- .../supplement/building-gchp-dependencies.rst | 165 ------------------ 2 files changed, 1 insertion(+), 166 deletions(-) delete mode 100644 docs/source/supplement/building-gchp-dependencies.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index a4d15789d..2d171fac0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -65,7 +65,7 @@ with Spack, as well as how to use Spack to install GCHP's dependencies if needed :maxdepth: 1 :caption: Supplemental Guides - supplement/building-gchp-dependencies.rst + geos-chem-shared-docs/supplemental-guides/spack-guide.rst supplement/setting-up-aws-parallelcluster.rst supplement/caching-input-data.rst supplement/containers.rst diff --git a/docs/source/supplement/building-gchp-dependencies.rst b/docs/source/supplement/building-gchp-dependencies.rst deleted file mode 100644 index 4d4581d37..000000000 --- a/docs/source/supplement/building-gchp-dependencies.rst +++ /dev/null @@ -1,165 +0,0 @@ -.. _building_gchp_dependencies: - -Build Dependencies -================== - -This page has instructions for building GCHP's :term:`dependencies`. -These are the software libraries that are needed to compile and execute the GCHP program. -These instructions are meant for users that are working on a cluster where GCHP's :ref:`software_requirements` are not already available. - - -.. note:: - This is not the only way to build the GCHP dependencies. - It is possible to download and compile the source code for each library manually. - Spack automates this process, thus it is the recommended method. - -The general workflow is the following: - -#. Install Spack and perform first-time setup -#. Install the recommended compiler -#. Build GCHP's dependencies -#. Generate a load script (a script that loads the GCHP dependencies in your environment) - - -1. Install Spack and do first-time setup ----------------------------------------- - -Decide where you want to install Spack. A few details you should consider are: - -* this directory will be ~5-20 GB (keep in mind that some clusters limit :file:`$HOME` to a few GB) -* this directory cannot be moved (needs redo if you need to move it in the future) -* if other people are going to use these dependencies, this directory should be in a shared location - -Once you choose an install location, proceed with the commands below. -You can copy-paste these commands, but lookout for lines marked with a :literal:`# (modifiable) ...` comment as they might require modification. - -.. important:: - All commands in this tutorial are executed in the same directory. - -Install spack and perform the following first-time setup. - -.. code-block:: console - - $ cd $HOME # (modifiable) cd to the install location you chose - $ git clone -c feature.manyFiles=true https://github.com/spack/spack.git # download Spack - $ source spack/share/spack/setup-env.sh # load Spack - $ spack external find # find software that is already available - -Next, download a copy of the GCHP source code. -The GCHP source code has a :file:`spack/` subdirectory with important Spack settings. -The GCHP version should not matter, but it is good practice to use the latest version. - -.. code-block:: console - - $ git clone https://github.com/geoschem/GCHP.git # we need the GCHP/spack subdirectory - -2. Install the recommended compiler ------------------------------------ - -Next, install the recommended compiler, :literal:`intel-oneapi-compilers`. -Note the :literal:`-C GCHP/spack` argument---this specifies custom Spack setting for GCHP. - -.. code-block:: console - - $ spack -C GCHP/spack install intel-oneapi-compilers # install the recommended compiler - -This should take a few minutes. Once the package is installed, add it as a compiler. - -.. code-block:: console - - $ spack compiler add $(spack location -i intel-oneapi-compilers)/compiler/latest/linux/bin/intel64 # register the compiler with spack - -.. note:: - You can run the command :literal:`spack find` to list all the packages that are installed. - - You can run the command :literal:`spack compiler list` to list the registered compilers. - After the :command:`spack compiler add` command above, you should see a compiler named :literal:`intel@XXXX.XX`, where :literal:`XXXX.XX` is the compiler version. - -3. Build GCHP's dependencies ---------------------------------- - -The next step is building the GCHP dependencies. This will be done a :command:`spack install` command, which has the following syntax. - -.. code:: - - spack install - -:literal:`` is a placeholder for arguments like :literal:`-C GCHP/spack`, which configures recommended Spack settings for use with GCHP. -:literal:`` is a placeholder for arguments that specify what package to install. - -To install the GCHP dependencies, choose one of the following for :literal:``: - -* :literal:`esmf%intel ^intel-oneapi-mpi` - **(Recommended)** Default GCHP dependencies, using Intel compilers and Intel MPI. -* :literal:`esmf%intel ^openmpi` - Default GCHP dependencies, using Intel compilers and OpenMPI. - -For :literal:``, you should always include :literal:`-C GCHP/spack`. This configures settings for the -GCHP dependencies. Note that :literal:`GCHP/spack` has subdirectories with platform-specific settings for certain platforms (e.g., AWS ParallelCluster). -Check to see if any subdirectories look relevant to you. - -The remainder of these instructions use AWS ParallelCluster as an example, so the commands use :literal:`-C GCHP/spack -C GCHP/spack/aws-parallelcluster-3.0.1` for :literal:``. -If no subdirectories are relevant to you, just use :literal:`-C GCHP/spack`. - -.. note:: - You can see that packages that will be installed with the :command:`spack spec` command. For example, - - - .. code-block:: console - - $ scope_args="-C GCHP/spack -C GCHP/spack/aws-parallelcluster-3.0.1" # (modifiable) see description of - $ install_spec="esmf%intel ^intel-oneapi-mpi" # (modifiable) see description of - $ spack ${scope_args} spec -I ${install_spec} - Input spec - -------------------------------- - - esmf%intel - - Concretized - -------------------------------- - - esmf@8.0.1%intel@2021.5.0~debug~external-lapack+mpi+netcdf~pio~pnetcdf~xerces arch=linux-amzn2-x86_64 - - ^intel-oneapi-mpi@2021.5.1%gcc@7.3.1+external-libfabric~ilp64 arch=linux-amzn2-x86_64 - - ^libfabric@1.13.0%gcc@7.3.1~debug~kdreg fabrics=efa,mrail,rxd,rxm,shm,sockets,tcp,udp arch=linux-amzn2-x86_64 - - ^libxml2@2.9.12%intel@2021.5.0~python arch=linux-amzn2-x86_64 - - ^libiconv@1.16%intel@2021.5.0 libs=shared,static arch=linux-amzn2-x86_64 - - ^pkgconf@1.8.0%intel@2021.5.0 arch=linux-amzn2-x86_64 - - ^xz@5.2.5%intel@2021.5.0~pic libs=shared,static arch=linux-amzn2-x86_64 - - ^zlib@1.2.11%intel@2021.5.0+optimize+pic+shared arch=linux-amzn2-x86_64 - - ^netcdf-c@4.8.1%intel@2021.5.0~dap~fsync~hdf4~jna~mpi~parallel-netcdf+pic+shared arch=linux-amzn2-x86_64 - - ^hdf5@1.12.1%intel@2021.5.0~cxx~fortran+hl~ipo~java~mpi+shared~szip~threadsafe+tools api=default build_type=RelWithDebInfo patches=ee351eb arch=linux-amzn2-x86_64 - - ^cmake@3.22.2%intel@2021.5.0~doc~ncurses+openssl+ownlibs~qt build_type=Release arch=linux-amzn2-x86_64 - - ^openssl@1.0.2k-fips%intel@2021.5.0~docs certs=system arch=linux-amzn2-x86_64 - - ^m4@1.4.16%intel@2021.5.0+sigsegv arch=linux-amzn2-x86_64 - - ^netcdf-fortran@4.5.3%intel@2021.5.0~doc+pic+shared arch=linux-amzn2-x86_64 - - The :command:`spack spec` command is not necessary, but it can be helpful to see exactly what packages will be installed. - -The following commands build the GCHP dependencies. Note that this may take several hours. - -.. code-block:: console - - $ scope_args="-C GCHP/spack -C GCHP/spack/aws-parallelcluster-3.0.1" # (modifiable) see description of - $ install_spec="esmf%intel ^intel-oneapi-mpi" # (modifiable) see description of - $ spack ${scope_args} install ${install_spec} - - -4. Generate a load script ------------------------------- - -The last step is generating a script that loads the these dependencies. -This is a file that you will :literal:`source` before you build or run GCHP. -The following commands generate a script called :literal:`geoschem_deps-YYYY.MM` where :literal:`YYYY.MM` is the current year and month. - -.. code-block:: console - - $ load_script_name="geoschem_deps-$(date +%Y.%m)" # (modifiable) rename if you want to - $ spack ${scope_args} module tcl refresh -y # regenerate all the modulefiles - $ spack ${scope_args} module tcl loads -r -p $(pwd)/spack/share/spack/modules/linux-*-x86_64/ intel-oneapi-compilers cmake > ${load_script_name} - $ spack ${scope_args} module tcl loads -r -p $(pwd)/spack/share/spack/modules/linux-*-x86_64/ ${install_spec} >> ${load_script_name} - -For me, this generated a load script named :file:`geoschem_deps-2022.03`. -In terminals or scripts you can load the GCHP dependencies by running: - -.. code-block:: console - - $ source /YOUR_PATH_TO/geoschem_deps-2022.03 # loads the the dependencies (replace YOUR_PATH_TO) - -You can copy or move the load script to other directories. At this point, you can remove the :file:`GCHP` directory as it is not needed. -The :file:`spack` directory needs to remain. From bacb92b65951676edc65edfbdfbf4fe6bff9cfac Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 6 Apr 2023 12:20:01 -0400 Subject: [PATCH 07/54] geos-chem-shared-docs update: Add maintainer column to related-docs.rst docs/source/geos-chem-shared-docs/supplemental-guides/related-docs - Added a "Maintained by" column to the table "User manuals for GEOS-Chem and related software" to make it clear which packages are maintained by GCST and which are not. Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 968a1a480..8f430bf1e 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 968a1a48023c0785a06eff4dea962e380cc77146 +Subproject commit 8f430bf1e9e3c7be1d454a6627c871b610392f78 From 39ad4909c83c2f79cefab0111f3c9f4dafd4a2bd Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 11 Apr 2023 17:29:22 -0400 Subject: [PATCH 08/54] geos-chem-shared-docs: Updates to error, Spack, libraries Guides This commit informs the GCHP superproject about the following commits that were pushed to the geos-chem-shared-docs repository: 4082231 Updates to supplemental guides 7a4d63e Clean up more content in error-guide.rst 786fe48 Fix broken reference in spack-guide.rst 45fce7a Add supplemental-guides/error-guide.rst 9031d5f In spack-guide.rst, change ref values from "spack" to "spackguide" Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 8f430bf1e..408223105 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 8f430bf1e9e3c7be1d454a6627c871b610392f78 +Subproject commit 408223105d9703291e6da2c7d9bf7aad4307a7f2 From fb4f7ce33f66ce293cc14a92a13be3f5f92f6660 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 11 Apr 2023 17:33:37 -0400 Subject: [PATCH 09/54] Change ordering of supplemental guides in toctree, plus formatting docs/source/index.rst - Now point to renamed load-libraries-guide.rst - Add new error-guide.rst - Formatted text to fit within 80 columns (except for links) - Trimmed whitespace - Use "#" in title header Signed-off-by: Bob Yantosca --- docs/source/index.rst | 48 +++++++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 2d171fac0..ac2e5d81a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,6 @@ +########################## GEOS-Chem High Performance -========================== +########################## .. raw:: html

@@ -12,31 +13,40 @@ GEOS-Chem High Performance

-The `GEOS--Chem model `_ is a global 3-D model of atmospheric -composition driven by assimilated meteorological observations from the Goddard Earth Observing -System (GEOS) of the `NASA Global Modeling and Assimilation Office `_. -It is applied by `research groups around the world -`_ to a wide range of atmospheric composition -problems. +The `GEOS--Chem model `_ is a global 3-D model +of atmospheric composition driven by assimilated meteorological +observations from the Goddard Earth Observing System (GEOS) of the +`NASA Global Modeling and Assimilation Office +`_. It is applied by `research groups +around the world +`_ to a wide range +of atmospheric composition problems. * `GEOS-Chem Overview `_ * `Narrative description of GEOS-Chem `_ -This site provides instructions for GEOS-Chem High Performance, GEOS-Chem's multi-node variant. We provide two different -instruction sets for downloading and compiling GCHP: from a clone of the source code, or using the Spack package manager. +This site provides instructions for GEOS-Chem High Performance, +GEOS-Chem's multi-node variant. We provide two different instruction +sets for downloading and compiling GCHP: from a clone of the source +code, or using the Spack package manager. -Cloning and building from source code ensures you will have direct access to the latest available versions of GCHP, provides -additional compile-time options, and allows you to make your own modifications to GCHP's source code. Spack automates -downloading and additional parts of the compiling process while providing you with some standard togglable compile-time options. - - -Our `Quick Start Guide `__ and the `downloading `__, `compiling `__, and -`creating a run directory `__ sections of the User Guide give instructions specifically for using a clone -of the source code. Our dedicated `Spack guide `__ describes how to install GCHP and create a run directory -with Spack, as well as how to use Spack to install GCHP's dependencies if needed. +Cloning and building from source code ensures you will have direct +access to the latest available versions of GCHP, provides additional +compile-time options, and allows you to make your own modifications to +GCHP's source code. Spack automates downloading and additional parts +of the compiling process while providing you with some standard +togglable compile-time options. +Our `Quick Start Guide `__ and the +`downloading `__, `compiling +`__, and `creating a run directory +`__ sections of the User Guide give +instructions specifically for using a clone of the source code. Our +dedicated `Spack guide `__ describes how to +install GCHP and create a run directory with Spack, as well as how to +use Spack to install GCHP's dependencies if needed. .. toctree:: :maxdepth: 1 @@ -65,6 +75,7 @@ with Spack, as well as how to use Spack to install GCHP's dependencies if needed :maxdepth: 1 :caption: Supplemental Guides + geos-chem-shared-docs/supplemental-guides/load-libraries-guide.rst geos-chem-shared-docs/supplemental-guides/spack-guide.rst supplement/setting-up-aws-parallelcluster.rst supplement/caching-input-data.rst @@ -72,6 +83,7 @@ with Spack, as well as how to use Spack to install GCHP's dependencies if needed supplement/stretched-grid.rst supplement/satellite-overpass.rst geos-chem-shared-docs/supplemental-guides/bashdatacatalog.rst + geos-chem-shared-docs/supplemental-guides/error-guide.rst geos-chem-shared-docs/supplemental-guides/debug-guide.rst geos-chem-shared-docs/supplemental-guides/species-guide.rst geos-chem-shared-docs/supplemental-guides/using-kpp-with-gc.rst From 401d8f6035540875e9af7bbba4889254bbd7820e Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 24 Apr 2023 15:33:13 -0400 Subject: [PATCH 10/54] geos-chem-shared-docs update: Add Bukosa et al to geos-chem.bib This commit informs the GCHP superproject about the following updates that were committed to the geos-chem-shared-docs repository: b96e458 Add Bukosa et al 2023 + formatting updates to GC bibliography Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 408223105..b96e45868 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 408223105d9703291e6da2c7d9bf7aad4307a7f2 +Subproject commit b96e45868d41809d999264cb7a92aee3ddf77cbf From 23f62d6b14900cef69d2098c03b4ea565e3a14af Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 25 Apr 2023 09:13:56 -0400 Subject: [PATCH 11/54] Updated AUTHORS.txt for 14.2.0; Fix broken links in README.md AUTHORS.txt - Updated for GCHP 14.2.0 README.md - Web links now point to http://geos-chem.org instead of the defunct site http://acmg.seas.harvard.edu/geos/ CHANGELOG.md - Updated accordingly Signed-off-by: Bob Yantosca --- AUTHORS.txt | 710 ++++++++++++++++++++++++++------------------------- CHANGELOG.md | 4 + README.md | 4 +- 3 files changed, 366 insertions(+), 352 deletions(-) mode change 100755 => 100644 README.md diff --git a/AUTHORS.txt b/AUTHORS.txt index 3cdb77b13..0a43922ec 100644 --- a/AUTHORS.txt +++ b/AUTHORS.txt @@ -1,353 +1,363 @@ List of Developers for GEOS-Chem, GCHP, HEMCO, and Related Software -(26 Oct 2022) +(24 Apr 2023) =============================================================================== -Peter Adams -Becky Alexander -Matthew Alvarado -Helen Amos -Helene Angot -Stina Ausmeel -Marion Auvray -Sabour Baray -Michael Barkley -Steven Barret -Brice Barret -Kelvin Bates -Isabelle Bey -Liam Bindle -Folkert Boersma -Sreekanth Bojjagani -Eimy Bonilla -Benoit Bovy -Kevin Bowman -Brian Boys -Erika Brattich -Tom Breider -Jared Brewer -Ellie Browne -Benjamin Brown-Steiner -Beata Bukosa -Christopher Butenhoff -Karen Cady-Pereira -Philip Cameron-Smith -Patrick Campbell -Liangzhong Cao -Guofeng Cao -Yi Cao -Shannon Capps -Claire Carouge -Therese Carter -Maria Cazorla -Sreelekha Chaliyakunnel -Han Chen -Jing Chen -Long Chen -Qi Chen -Qianjie Chen -Xin Chen -Yang Chen -Yunsoo Choi -Kenneth Christian -Tom Clune -Matt Cooper -Bess Corbitt -Betty Croft -Xochitl Cruz -Gabriele Curci -Jordi Dachs -Yanko Davila -Feng Deng -Priyanka deSouza -Max Desservettaz -Nicholas Deutscher -Maurizio di Pierro -Aurelien Dommergue -Will Downs -Easan Drury -Bryan Duncan -Sebastian Eastham -Raluca Ellis -Joseph Enberg -Lucas Estrada -Mathew Evans -T. Duncan Fairlie -Sal Farina -Vivian Faye -Ari Feinberg -Brendan Field -Arlene Fiore -Emily Fischer -Jenny Fisher -Charley Fite -Eric Fleming -Judit Flo-Gaya -Bonne Ford -Timmy Francis -Lyssa Freese -Carey Friedman -Thibaud Fritz -Tzung-May Fu -Joshua Fu -Brett Gantt -Cui Ge -Jeffrey Geddes -Amanda Giang -Christos Giannakopoulos -Harriet Gounia -Edward Graef -Jesse Greenslade -Xiaoguang Gu -Melanie Hammer -Jessica Haskins -Cenlin He -Colette Heald -Barron Henderson -Daven Henze -Wai Ho-Lo -Myroslav Hordiichuk -Christopher Holmes -Hannah Horowitz -Zahra Hosseni -Lu Hu -Jianping Huang -Jiayue Huang -Kohei Ikeda -Daniel Jacob -Andy Jacobson -Marc Jacobson -Lyatt Jaegle -Ruud Jansen -Weiyuan Jiang -Zhe Jiang -Lixu Jin -Matthew Johnson -Dylan Jones -Jaegun Jung -Prasad Kasibhatla -Rynda Hudman Kay -Christoph Keller -Tetsuro Kikuchi -Hyeonmin Kim -Sungshik Kim -Nutthida Kitwiroon -Jack Kodros -Jamin Koo -Monika Kopacz -Shannon Koplitz -Jules Kouatchou -Stefanie Kremser -Forrest Lacey -Carmen Lamencusa -Lok Lamsal -Kateryna Lapina -Kelsey Larson -David Lary -Robyn Latimer -Philippe Le Sager -Chulkyu Lee -Colin Lee -Meemong Lee -Ralph Lehmann -Eric Leibensperger -Maud Leriche -Fok-Yan Leung -Bengang Li -Chi Li -Ke Li -Qinbin Li -Xianglan Li -Yanshun Li -K. J. Liao -Qing Liang -Hong Liao -Haipeng Lin -Jintai Lin -Shian-Jiann Lin -John Linford -Hongyu Liu -Jane Liu -Junhua Liu -Pengfei Liu -Tina Liu -Yang Liu -Ying Liu -Jennifer Logan -Mike Long -Xiao Lu -Lizzie Lundgren -Gan Luo -J.D. (Bram) Maasakkers -Helen Macintyre -Dave MacKenzie -Emmanuel Mahieu -Jingqiu Mao -Eloise Marais -Marguerite Marks -Arjen Markus -Randall Martin -Maggie Marvin -Erin McDuffie -Dana McGuffin -Chris McLinden -Hongjian Meng -Jun Meng -Nicholas Meskhidze -Natallia Miatselskaya -Loretta Mickley -Christopher Chan Miller -Dylan Millet -Kai Ming -Jonathan Moch -Neil Moore -Jessica Morena -Gabriel Morin -Eleanor Morris -Mingquan Mu -Killian Murphy -Lee Murray -Jun Nam -Ray Nassar -Brian Nathan -Athanasios Nenes -Cynthia Nevison -Eric Nielsen -Justus Notholt -Kate O'Dell -Sachiko Okamoto -Neil Page -Sidhant Pai -Paul Palmer -Nick Parazoo -Justin Parella -Rokjin Park -Mark Parrington -Fabien Paulot -Sajeev Philip -Christopher Pickett-Heaps -Jeff Pierce -Will Porter -Ryan Pound -Michael Prather -Anna Protonatariou -Bill Putman -Havala Pye -Asif Qureshi -Emily Ramnarine -James Randerson -Cynthia Randles -Francois Ravetta -Wes Reinhart -David Ridley -Umberto Rizza -Daniel Rothenberg -Sarah Safieddine -Adrian Sandu -Mauricio Santillana -Bastien Sauvage -Tia Scarpelli -Luke Schiferl -Johan Schmidt -Martin Schultz -Rebecca Schwantes -Paolo Sebastianelli -Noelle Selin -Michael Seymour -Viral Shah -Jingyuan Shao -Lu Shen -Tomas Sherwen -Sam Silva -Nicole Smith-Downey -Anne Laerke Soerensen -Eric Sofen -Shaojie Song -Yu Song -Dominick Spracklen -Ilya Stanevich -Stephen Steenrod -Rebecca Stern -Robin Stevens -David Streets -Sarah Strode -Flora Su -Melissa Sulprizio -Minmin Sun -Elsie Sunderland -Parvada Suntharalingam -Luke Surl -Bethany Sutherland -Kimito Suto -Monika Szelag -Amos Tai -Hiroshi Tanimoto -John Tannahill -Shu Tao -Colin Thackray -Matt Thompson -Thibaud Thonat -Rong Tian -Maria Tombrou -Katherine Travis -Atanas Trayanov -Win Trivitayanurak -Corey Trujillo -Paolo Tuccella -Alexander Turner -Solene Turquety -Zitely Tzompa-Sosa -Nadine Unger -Maria Val-Martin -Aaron van Donkelaar -Kostas Varotsos -Geert Vinken -Kristina Wagstrom -Thomas Walker -James Wang -Jun Wang -Qiaoqiao Wang -Xuan Wang -Xiaoli Wang -Yuhang Wang -Yuting Wang -Yuxuan Wang -Zifa Wang -Kevin Wecht -Richard Weidner -Debra Weisenstein -Kelley Wells -Hongjian Weng -Dan Westervelt -Cynthia Whaley -Christine Wiedinmyer -Oliver Wild -Ingo Wohltmann -Shiliang Wu -Shiliang Wu -Yaping Xiao -Junwei Xu -Yingying Yan -Matt Yannetti -Bob Yantosca -Jack Yatteau -Keiya Yumimoto -Karen Yu -Fangqun Yu -Xu Yue -Xuyan Yue -Maria Zatko -Shixian Zhai -Shuting Zhai -Bo Zhang -Chi Zhang -Hongliang Zhang -Jiawei Zhang -Li Zhang -Lin Zhang -Qiang Zhang -Yanxu Zhang -Lei Zhu -Liye Zhu -Jiawei Zhuang -Quanlai Zhuang -Peter Zoogman +ADAMS, Peter +ALEXANDER, Becky +ALVARADO, Matthew +AMOS, Helen +ANGOT, Helene +AUSMEEL, Stina +AUVRAY, Marion +BARAY, Sabour +BARKLEY, Michael +BARRET, Steven +BARRET, Brice +BATES, Kelvin +BEY, Isabelle +BINDLE, Liam +BOERSMA, Folkert +BOJJAGANI, Sreekanth +BONILLA, Eimy +BOVY, Benoit +BOWMAN, Kevin +BOYS, Brian +BRATTICH, Erika +BREIDER, Tom +BREWER, Jared +BROWNE, Ellie +BROWN, Benjamin-Steiner +BUKOSA, Beata +BUTENHOFF, Christopher +CADY, Karen-Pereira +CAMERON, Philip-Smith +CAMPBELL, Patrick +CAO, Guofeng +CAO, Hansen +CAO, Liangzhong +CAO, Yi +CAPPS, Shannon +CAROUGE, Claire +CARTER, Therese +CAZORLA, Maria +CHALIYAKUNNEL, Sreelekha +CHEN, Han +CHEN, Jing +CHEN, Long +CHEN, Qi +CHEN, Qianjie +CHEN, Xin +CHEN, Yang +CHOI, Yunsoo +CHRISTIAN, Kenneth +CLUNE, Tom +COOPER, Matt +CORBITT, Bess +CROFT, Betty +CRUZ, Xochitl +CURCI, Gabriele +DACHS, Jordi +DAVILA, Yanko +DELWICHE, Kyle +DENG, Feng +DESOUZA, Priyanka +DESSERVETTAZ, Max +DEUTSCHER, Nicholas +DI, Maurizio Pierro +DLAMINI, Thandolwethu +DOMMERGUE, Aurelien +DOWNS, Will +DRURY, Easan +DUNCAN, Bryan +EASTHAM, Sebastian +ELLIS, Raluca +ENBERG, Joseph +ESTRADA, Lucas +EVANS, Mathew +FAIRLIE, +FARINA, Sal +FAYE, Vivian +FEINBERG, Ari +FIELD, Brendan +FIORE, Arlene +FISCHER, Emily +FISHER, Jenny +FITE, Charley +FLEMING, Eric +FLO, Judit-Gaya +FORD, Bonne +FRANCIS, Timmy +FREESE, Lyssa +FRIEDMAN, Carey +FRITZ, Thibaud +FU, +FU, Joshua +GANTT, Brett +GE, Cui +GEDDES, Jeffrey +GIANG, Amanda +GIANNAKOPOULOS, Christos +GOUNIA, Harriet +GRAEF, Edward +GREENSLADE, Jesse +GU, Xiaoguang +HAMMER, Melanie +HASKINS, Jessica +HE, Cenlin +HE, Jourdan +HEALD, Colette +HENDERSON, Barron +HENZE, Daven +HO, Wai-Lo +HORDIICHUK, Myroslav +HOLMES, Christopher +HOROWITZ, Hannah +HOSSENI, Zahra +HU, Lu +HUANG, Jianping +HUANG, Jiayue +IKEDA, Kohei +JACOB, Daniel +JACOBSON, Andy +JACOBSON, Marc +JAEGLE, Lyatt +JANSEN, Ruud +JIANG, Weiyuan +JIANG, Zhe +JIN, Lixu +JISKRA, Martin +JOHNSON, Matthew +JONES, Dylan +JUNG, Jaegun +KASIBHATLA, Prasad +HUDMAN, Rynda Kay +KELLER, Christoph +KIKUCHI, Tetsuro +KIM, Hyeonmin +KIM, Sungshik +KITWIROON, Nutthida +KODROS, Jack +KOO, Jamin +KOPACZ, Monika +KOPLITZ, Shannon +KOUATCHOU, Jules +KREMSER, Stefanie +LACEY, Forrest +LAMENCUSA, Carmen +LAMSAL, Lok +LAPINA, Kateryna +LARSON, Kelsey +LARY, David +LATIMER, Robyn +LE, Philippe Sager +LEE, Chulkyu +LEE, Colin +LEE, Meemong +LEHMANN, Ralph +LEIBENSPERGER, Eric +LERICHE, Maud +LEUNG, +LI, Bengang +LI, Chi +LI, Ke +LI, Qinbin +LI, Xianglan +LI, Yanshun +LIAO, +LIANG, Qing +LIAO, Hong +LIN, Haipeng +LIN, Jintai +LIN, +LINFORD, John +LIU, Hongyu +LIU, Jane +LIU, Junhua +LIU, Pengfei +LIU, Tina +LIU, Yang +LIU, Ying +LOGAN, Jennifer +LONG, Mike +LU, Xiao +LUNDGREN, Lizzie +LUO, Gan +MAASAKKERS, +MACINTYRE, Helen +MACKENZIE, Dave +MAHIEU, Emmanuel +MAO, Jingqiu +MARAIS, Eloise +MARKS, Marguerite +MARKUS, Arjen +MARTIN, Randall +MARVIN, Maggie +MCDUFFIE, Erin +MCGUFFIN, Dana +MCLINDEN, Chris +MENG, Hongjian +MENG, Jun +MESKHIDZE, Nicholas +MIATSELSKAYA, Natallia +MICKLEY, Loretta +CHAN, Christopher Miller +MILLET, Dylan +MING, Kai +MOCH, Jonathan +MOORE, Neil +MOORING, Tood +MORENA, Jessica +MORIN, Gabriel +MORRIS, Eleanor +MU, Mingquan +MURPHY, Killian +MURRAY, Lee +NAM, Jun +NASSAR, Ray +NATHAN, Brian +NENES, Athanasios +NEVISON, Cynthia +NIELSEN, Eric +NOTHOLT, Justus +O, Kate'Dell +OKAMOTO, Sachiko +PAGE, Neil +PAI, Sidhant +PALMER, Paul +PARAZOO, Nick +PARELLA, Justin +PARK, Rokjin +PARRINGTON, Mark +PAULOT, Fabien +PHILIP, Sajeev +PICKETT, Christopher-Heaps +PIERCE, Jeff +PORTER, Will +POUND, Ryan +PRATHER, Michael +PROTONATARIOU, Anna +PUTMAN, Bill +PYE, Havala +QURESHI, Asif +RAMNARINE, Emily +RANDERSON, James +RANDLES, Cynthia +RAVETTA, Francois +REINHART, Wes +RIDLEY, David +RIZZA, Umberto +ROTHENBERG, Daniel +SAFIEDDINE, Sarah +SANDU, Adrian +SANTILLANA, Mauricio +SAUVAGE, Bastien +SCARPELLI, Tia +SCHIFERL, Luke +SCHMIDT, Johan +SCHULTZ, Martin +SCHWANTES, Rebecca +SEBASTIANELLI, Paolo +SELIN, Noelle +SEYMOUR, Michael +SHAH, Viral +SHAO, Jingyuan +SHEN, Lu +SHERWEN, Tomas +SHUTTER, Joshua +SILVA, Sam +SMITH, Nicole-Downey +LAERKE, Anne Soerensen +SOFEN, Eric +SONG, Shaojie +SONG, Yu +SPRACKLEN, Dominick +STANEVICH, Ilya +STEENROD, Stephen +STERN, Rebecca +STEVENS, Robin +STREETS, David +STRODE, Sarah +SU, Flora +SULPRIZIO, Melissa +SUN, Minmin +SUNDERLAND, Elsie +SUNTHARALINGAM, Parvada +SURL, Luke +SUTHERLAND, Bethany +SUTO, Kimito +SZELAG, Monika +TAI, Amos +TANIMOTO, Hiroshi +TANNAHILL, John +TAO, Shu +THACKRAY, Colin +THOMPSON, Matt +THONAT, Thibaud +TIAN, Rong +TOMBROU, Maria +TRAVIS, Katherine +TRAYANOV, Atanas +TRIVITAYANURAK, Win +TRUJILLO, Corey +TUCCELLA, Paolo +TURNER, Alexander +TURQUETY, Solene +TZOMPA, Zitely-Sosa +UNGER, Nadine +VAL, Maria-Martin +VAN, Aaron Donkelaar +VAROTSOS, Kostas +VINKEN, Geert +WAGSTROM, Kristina +WALKER, Thomas +WANG, James +WANG, Jun +WANG, Qiaoqiao +WANG, Xuan +WANG, Xiaoli +WANG, Yuhang +WANG, Yuting +WANG, Yuxuan +WANG, Zifa +WECHT, Kevin +WEIDNER, Richard +WEISENSTEIN, Debra +WELLS, Kelley +WENG, Hongjian +WESTERVELT, Dan +WHALEY, Cynthia +WIEDINMYER, Christine +WILD, Oliver +WOHLTMANN, Ingo +WU, Shiliang +WU, Shiliang +XIAO, Yaping +XU, Junwei +YAN, Yingying +YANNETTI, Matt +YANTOSCA, Bob +YATTEAU, Jack +YUMIMOTO, Keiya +YU, Karen +YU, Fangqun +YU, Xingpei +YUE, Xu +YUE, Xuyan +ZATKO, Maria +ZHAI, Shixian +ZHAI, Shuting +ZHANG, Bingqing +ZHANG, Bo +ZHANG, Chi +ZHANG, Dandan +ZHANG, Hongliang +ZHANG, Jiawei +ZHANG, Li +ZHANG, Lin +ZHANG, Qiang +ZHANG, Yanxu +ZHU, Lei +ZHU, Liye +ZHUANG, Jiawei +ZHUANG, Quanlai +ZOOGMAN, Peter diff --git a/CHANGELOG.md b/CHANGELOG.md index d8c508d08..b35402e0f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ This file documents all notable changes to the GCHP wrapper repository starting The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## Unreleased +- Updated `AUTHORS.txt` for GCHP 14.2.0 +- Updated `README.md` so that links point to http://geos-chem.org + ## [14.1.1] - 2023-03-03 ### Added - Added `EXE_FILE_NAME` and `INSTALLCOPY` to src/CMakeLists.txt (facilitates integration testing) diff --git a/README.md b/README.md old mode 100755 new mode 100644 index 95e095a48..b19b5e03e --- a/README.md +++ b/README.md @@ -17,6 +17,6 @@ The is the official repository for GEOS-Chem High Performance (GCHP). ### About GEOS-Chem -GEOS-Chem is a global 3-D model of atmospheric chemistry driven by meteorological input from the Goddard Earth Observing System (GEOS) of the [NASA Global Modeling and Assimilation Office](http://gmao.gsfc.nasa.gov/). It is applied by [research groups around the world](http://acmg.seas.harvard.edu/geos/geos_people.html) to a wide range of atmospheric composition problems. Scientific direction of the model is provided by the international [GEOS-Chem Steering Committee](http://acmg.seas.harvard.edu/geos/geos_steering_cmte.html) and by [User Working Groups](http://acmg.seas.harvard.edu/geos/geos_working_groups.html). The model is managed by the [GEOS-Chem Support Team](http://acmg.seas.harvard.edu/geos/geos_chem_support.html), based at Harvard University and Washington University with support from the US NASA Earth Science Division, the Canadian National and Engineering Research Council, and the Nanjing University of Information Sciences and Technology. +GEOS-Chem is a global 3-D model of atmospheric chemistry driven by meteorological input from the Goddard Earth Observing System (GEOS) of the [NASA Global Modeling and Assimilation Office](http://gmao.gsfc.nasa.gov/). It is applied by [research groups around the world](http://geos-chem.org/people.html) to a wide range of atmospheric composition problems. Scientific direction of the model is provided by the international [GEOS-Chem Steering Committee](http://geos-chem.org/steering-committee.html) and by [User Working Groups](http://geos-chem.org/working-groups.html). The model is managed by the [GEOS-Chem Support Team](http://geos-chem.org/support-team.html), based at Harvard University and Washington University in St. Louis with support from the US NASA Earth Science Division, the Canadian National and Engineering Research Council, and the Nanjing University of Information Sciences and Technology. -GEOS-Chem is a grass-roots open-access model owned by its [users](http://acmg.seas.harvard.edu/geos/geos_people.html), and ownership implies some responsibilities as listed in our [welcome page for new users](http://acmg.seas.harvard.edu/geos/geos_welcome.html). If you are interested in using GEOS-Chem, please contact the [GEOS-Chem Support Team](http://wiki.seas.harvard.edu/geos-chem/index.php/GEOS-Chem_Support_Team) who will send you instructions for joining the user community and accessing the code. +GEOS-Chem is a grass-roots open-access model owned by its [users](http://geos-chem.org/people.html), and ownership implies some responsibilities as listed in our [welcome page for new users](http://geos-chem.org/welcome.html). From 3a8742882f0ba659ec5a2baf24bdae8d48ab2ae2 Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Tue, 2 May 2023 14:13:53 -0400 Subject: [PATCH 12/54] Updates to stretched grid documentation (supplemental guide) Signed-off-by: Lizzie Lundgren --- docs/source/supplement/stretched-grid.rst | 111 ++++++---------------- 1 file changed, 31 insertions(+), 80 deletions(-) diff --git a/docs/source/supplement/stretched-grid.rst b/docs/source/supplement/stretched-grid.rst index 51f6c19bc..120a6e938 100644 --- a/docs/source/supplement/stretched-grid.rst +++ b/docs/source/supplement/stretched-grid.rst @@ -43,7 +43,7 @@ covers the refion that you want to refine. If the figure above is not showing up properly, please :doc:`open an issue `. Next you need to choose a cubed-sphere size. The cubed-sphere size must be an even integer (e.g., -C90, C92, C94, etc.). Remeber that the resolution of the target face is enhanced by approximately the +C90, C92, C94, etc.). Remember that the resolution of the target face is enhanced by approximately the stretch-factor. @@ -57,50 +57,15 @@ requires a restart file with a C180 grid. Likewise, a stretched-grid simulation file with the same stretched-grid (i.e., an identical cubed-sphere size, stretch-factor, target longitude, and target latitude). -You can regrid an existing restart file to a stretched-grid with GCPy's :program:`gcpy.file_regrid` -program. Below is an example of regridding a C90 cubed-sphere restart file to a C48 stretched-grid -with a stretch factor of 3, a target longitude of 260.0, and a target latitude of 40.0. See the -GCPy documentation for this program's exact usage, and for installation instructions. +You can regrid an existing restart file to a stretched-grid using the GEOS-Chem python package GCPy. +See the `Regridding `_ section of the GCPy +documentation for instructions. Once you have created a restart file for your simulation, you can move +on to updating your simulation's configuration files. -.. code-block:: console - - $ python -m gcpy.file_regrid \ - -i GEOSChem.Restart.20190701_0000z.c90.nc4 \ - --dim_format_in checkpoint \ - -o sg_restart_c48_3_260_40.nc \ - --cs_res_out 48 \ - --sg_params_out 3.0 260.0 40.0 \ - --dim_format_out checkpoint - -Description of arguments: - -.. option:: -i GEOSChem.Restart.20190701_0000z.c90.nc - - Specifies the input restart file is :file:`GEOSChem.Restart.20190701_0000z.c90.nc4` (in the current working directory). - - -.. option:: --dim_format_in checkpoint - - Specifies that the input file is in the "checkpoint" format. GCHP restart files use the "checkpoint" format. - -.. option:: -o sg_restart_c48_3_260_40.nc - - Specifies that the output file should be named :file:`sg_restart_c48_3_260_40.nc`. - -.. option:: --cs_res_out 48 - - Specifies that the output grid has a cubed-sphere size 48 (C48). - -.. option:: --sg_params_out 3.0 260.0 40.0 - - Specifies that the output grid's stretched-grid parameters in the order stretch factor (3.0), target longitude (260.0), target latitude (40.0). - -.. option:: --dim_format_out checkpoint +.. note:: - Specifies that the output file should be in the "checkpoint" format. GCHP restart files must be in the "checkpoint" format. + A stretched grid restart file is available for download if you would like to quickly get set up to run a stretched grid simulation. See the `GEOSCHEM_RESTARTS/GC_14.0.0 `_ directory in the GEOS-Chem data repository. -Once you have created a restart file for your simulation, you can move on to updating your -simulation's configuration files. Configure run directory ^^^^^^^^^^^^^^^^^^^^^^^ @@ -129,14 +94,14 @@ Modify the section of :file:`setCommonRunSettings.sh` that controls the simulati TARGET_LAT=40.0 TARGET_LON=260.0 -Execute :program:`./setCommonRunSettings.sh` to update to update your run directory's configuration files. +Execute :program:`./setCommonRunSettings.sh` to update your run directory's configuration files. .. code-block:: console $ ./setCommonRunSettings.sh You will also need to configure the run directory to use the stretched grid restart file. Update :file:`cap_restart` to match the date of your restart file. This will also be the start date of the run. -Copy or symbolically link to your restart file in the :literal:`Restarts` subdirectory with the proper filename format. The format includes global resolution but not stretched grid resolution so it is a good idea to symbolically link to the original if you want to preserve the original file's specification of stretched grid in its name. +Copy or symbolically link to your restart file in the :literal:`Restarts` subdirectory with the proper filename format. The format includes global resolution but not stretched grid resolution. To avoid confusion about what grid the file contains you can symbolically link to a file with stretched grid parameters in its filename. Run :literal:`setRestartLink.sh` to set symbolic link :file:`gchp_restart.nc4` to point to your restart file based on start date in :file:`cap_restart` and global grid resolution in :file:`setCommonRunSettings.sh`. This is also included as a pre-run step in all example run scripts provided in :file:`runScriptSamples`. Tutorial: Eastern United States @@ -187,7 +152,8 @@ Requirements Before continuing with the tutorial check that you have all pre-requisites: * You are able to run global GCHP simulations using MERRA2 data for July 2019 -* You have python packages GCPy >= 1.0.0 and cartopy >= 0.19 +* You have the latest version of GEOS-Chem python package GCPy +* You python package cartopy >= 0.19 Create run directory ^^^^^^^^^^^^^^^^^^^^^^^ @@ -201,23 +167,9 @@ Create restart file You will need to create a restart file with a horizontal resolution that matches your chosen stretched-grid resolution. Unlike other input data, GCHP ingests the restart file with no online regridding. Using a restart file with a horizontal grid that does not match the run grid will result in a run-time error. -To create a restart file for a stretched-grid simulation you can regrid a restart file with a uniform grid using GCPy. Using one of the initial restart files that comes with the GCHP run directory is handy. - -.. code-block:: console - - $ python -m gcpy.file_regrid \ - -i GEOSChem.Restart.20190701_0000z.c48.nc4 \ - --dim_format_in checkpoint \ - --dim_format_out checkpoint \ - --cs_res_out 60 \ - --sg_params_out 3.6 275 37 \ - -o initial_GEOSChem_rst.EasternUS_SG_fullchem.nc - -This creates :file:`initial_GEOSChem_rst.EasternUS_SG_fullchem.nc`, which is the -new restart file for your simulation. - -.. note:: - Regridding a C48 files using GCPy takes about a minute to run. If you regrid an even larger restart file (e.g., C180) it may take significantly longer. +To create a restart file for a stretched-grid simulation you can regrid a restart file with a uniform grid using GCPy. Follow +instructions on how to create a GCHP stretched grid restart file in the `GCPy documentation `_. +For this tutorial regrid the c48 fullchem restart file for July 1, 2019 that comes with a GCHP fullchem run directory (:file:`GEOSChem.Restart.20190701_0000z.c48.nc4`). Grid resolution is 60, stretch factor is 3.6, target longitude is 275, and target latitude is 37. Name the output file :file:`initial_GEOSChem_rst.EasternUS_SG_fullchem.c60.s3.6_37N_275E.nc`. Configure run directory ^^^^^^^^^^^^^^^^^^^^^^^ @@ -229,8 +181,8 @@ Make the following modifications to :file:`setCommonRunSettings.sh`: * Set diagnostic frequency to 24 hours (daily) * Set diagnostic duration to 24 hours (daily) * Update the compute resources as you like. This simulation's computational - demands are about :math:`1.5\times` that of a C48 or 2°x2.5° simulation. -* Change global grid resolutio to 60 + demands are about 50% more than a C48 or 2°x2.5° simulation. +* Change global grid resolution to 60 * Change :literal:`STRETCH_GRID` to :literal:`ON` * Change :literal:`STRETCH_FACTOR` to :literal:`3.6` * Change :literal:`TARGET_LAT` to :literal:`37.0` @@ -245,34 +197,33 @@ Next, execute :file:`setCommonRunSettings.sh` to apply the updates to the variou $ ./setCommonRunSettings.sh -Before running GCHP you also need to configure the model to use your stretched-grid restart file. Move or copy your restart file to the :file:`Restarts` subdirectory. Then change the symbolic link :file:`GEOSChem.Restart.20190701_0000z.c48.nc4` to point to your stretched-grid restart file while keeping the name of the link the same. You could also rename your restart file to this format but this would remove valuable information about the content of the file from the filename. Symbolically linking is a better way to preserve the information to avoid errors. You can check that you did this correctly by running :file:`setRestartLink.sh` in the run directory. +Before running GCHP you also need to configure the model to use your stretched-grid restart file. Move or copy your restart file to the :file:`Restarts` subdirectory. Then change the symbolic link :file:`GEOSChem.Restart.20190701_0000z.c48.nc4` to point to your stretched-grid restart file while keeping the name of the link the same. + +.. code-block:: console + + $ ln -nsf initial_GEOSChem_rst.EasternUS_SG_fullchem.c60.s3.6_37N_275E.nc GEOSChem.Restart.20190701_0000z.c48.nc4 + +You could also rename your restart file to this format but this would remove valuable information about the content of the file from the filename. Symbolically linking is a better way to preserve the information to avoid errors. You can check that you did this correctly by running :file:`setRestartLink.sh` in the run directory. Run GCHP ^^^^^^^^ -To run GCHP you can use the example run script for running interactively located at :file:`runScriptSamples/gchp.local.run` as long as you have enough resources available locally, e.g. 30 cores on 1 node. Copy it to the main level of your run directory and then execute it. If you want to use more resources you can submit as a batch job to your schedule. +To run GCHP you can use the example run script for running interactively located at :file:`runScriptSamples/gchp.local.run` as long as you have enough resources available locally, e.g. 30 cores on 1 node. Copy it to the main level of your run directory and then execute it. If you want to use more resources you can submit as a batch job to your scheduler. .. code-block:: console $ ./gchp.local.run -Log output of the run should be printed to both screen and log file :file:`gchp.20190701_000000z.log`. Check that your run was successful by inspecting the log and looking for output in the :file:`OutputDir` subdirectory. +Log output of the run will be sent to log file :file:`gchp.20190701_0000z.log`. Check that your run was successful by inspecting the log and looking for output in the :file:`OutputDir` subdirectory. .. _sg_plotting_example: Plot the output ^^^^^^^^^^^^^^^ -Append grid-box corners: - - -.. code-block:: console - - $ python -m gcpy.append_grid_corners \ - --sg_params 3.6 275 37 \ - OutputDir/GCHP.SpeciesConc.20190707_1200z.nc4 - -Plot ozone at model level 22: +Plotting stretched grid is simple using Python. +Below is an example plotting ozone at model level 22. +All libraries are available if using a python environment compatible with GCPy. .. code-block:: python @@ -280,11 +231,11 @@ Plot ozone at model level 22: import cartopy.crs as ccrs import xarray as xr - # Load 24-hr average concentrations for 2019-07-07 - ds = xr.open_dataset('GCHP.SpeciesConc.20190707_1200z.nc4') + # Load 24-hr average concentrations for 2019-07-01 + ds = xr.open_dataset('GCHP.DefautlCollection.20190701_0000z.nc4') # Get Ozone at level 22 - ozone_data = ds['SpeciesConc_O3'].isel(time=0, lev=22).squeeze() + ozone_data = ds['SpeciesConcVV_O3'].isel(time=0, lev=22).squeeze() # Setup axes ax = plt.axes(projection=ccrs.EqualEarth()) From c57d611b6f9f2dd11e7ee2ee60b12c293b65030b Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Wed, 3 May 2023 12:39:33 -0400 Subject: [PATCH 13/54] Update GCHP hardware and software requirements documentation Signed-off-by: Lizzie Lundgren --- docs/source/getting-started/quick-start.rst | 2 +- docs/source/getting-started/requirements.rst | 128 +++++++++++++++---- docs/source/supplement/stretched-grid.rst | 2 +- 3 files changed, 103 insertions(+), 29 deletions(-) diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index b7c3310a9..a6721dce0 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -3,7 +3,7 @@ Quickstart Guide ================ -This quickstart guide assumes your environment satisfies :ref:`GCHP's requirements `. +This quickstart guide assumes your environment satisfies the requirements described in :ref:`System Requirements `. / This means you should load a compute environment so that programs like :program:`cmake` and :program:`mpirun` are available before continuing. If you do not have some of GCHP's software dependencies, you can find instructions for installing GCHP's external dependencies in our `Spack instructions <../supplement/spack.html>`__. diff --git a/docs/source/getting-started/requirements.rst b/docs/source/getting-started/requirements.rst index 8edadd997..744f4630b 100644 --- a/docs/source/getting-started/requirements.rst +++ b/docs/source/getting-started/requirements.rst @@ -18,7 +18,7 @@ To build and run GCHP your compute :term:`environment` needs the following softw * MPI (Message Passing Interface) - * OpenMPI ≥ 3.0, or + * OpenMPI ≥ 4.0, or * IntelMPI, or * MVAPICH2, or * MPICH, or @@ -26,63 +26,137 @@ To build and run GCHP your compute :term:`environment` needs the following softw * HDF5 * NetCDF (with C, C++, and Fortran support) -* ESMF version ≥ 8.1.0 +* Earth System Modeling Framework (ESMF) version ≥ 8.1.0 Your system administrator should be able to tell you if this software is already available on your cluster, and if so, how to activate it. If it is not already available, they might be able to build it for you. +If you need to build GCHP's dependencies yourself, see the supplemental guide for building required software with Spack. -If you need to build GCHP's dependencies yourself, see :ref:`building_gchp_dependencies`. +Installing ESMF +^^^^^^^^^^^^^^^ + +If you have all of the needed libraries except ESMF then you can download and build ESMF yourself. +The ESMF git repository is available to clone from `github.com/esmf-org/esmf `_. Use :code:`git tag` to browse versions available and then :code:`git checkout tags/tag_name` to checkout the version. + +Once downloaded, browse file :file:`ESMF/README` for information about build requirements. +ESMF requires that you define environment variables :file:`ESMF_COMPILER`, :file:`ESMF_COMM`, and :file:`ESMF_DIR` (path to clone), and also export environment variables :file:`CC`, :file:`CXX`, :file:`FC`, and :file:`MPI_ROOT`. +Set up an environment file that loads the needed libraries and also defines these environment variables. +Here is an example of what the variable exports might look line in your environment file: + +.. code-block:: console + + export CC=gcc + export CXX=g++ + export FC=gfortran + export MPI_ROOT=${MPI_HOME} + export ESMF_COMPILER=gfortran + export ESMF_COMM=openmpi + export ESMF_DIR=/home/ESMF/ESMF_8_0_1 + +You can create multiple ESMF builds, for example if you want to try different compilers. To set yourself up to allow this also export environment variable :file:`ESMF_INSTALL_PREFIX` and define it as a subdirectory within :file:`ESMF_DIR`. For example: + +.. code-block:: console + + export ESMF_INSTALL_PREFIX=${ESMF_DIR}/INSTALL_gfortran10.2_openmpi4.1 + +To prepare your environment file for use with GCHP as well simply add the following: + +.. code-block:: console + + export ESMF_ROOT=${ESMF_INSTALL_PREFIX} + +Once you are ready to build execute the following commands: + +.. code-block:: console + + $ source path_to/your/env/file + $ cd $ESMF_DIR + $ make &> compile.log + +Once compilation completes check the end of :file:`compile.log` to see if compilation was successful. +If it was a success then continue as follows: + +.. code-block:: console + + $ make install &> install.log + +Check the end of file :file:`install.log`. +A message that installation was complete should be there if ESMF installation was a success. + +If all went well there should now be a folder in the top-level ESMF directory corresponding to what you defined as environment variable :file:`ESMF_INSTALL_PREFIX`. +Archive your compile and install logs to that directory. + +.. code-block:: console + + $ mv compile.log $ESMF_INSTALL_PREFIX + $ mv install.log $ESMF_INSTALL_PREFIX + +Calling make builds ESMF and calling make install places the build into your install directory. +In that folder the build files are placed within subdirectories such as bin and lib, among others. +The install directory is not deleted when you clean ESMF source code with :code:`make distclean` in the top-level ESMF directory. +Therefore you can clean and rebuild ESMF with different combinations of libraries in advance of needing them to build and run GCHP. +Just remember to clean the source code and source the environment file you intend to use prior to creating a new build. +You also must specify a different :code:`${ESMF_INSTALL_PREFIX}` for each unique build so as not to overwrite others. + +.. code-block:: console + +$ cd $ESMF_DIR +$ make distclean +$ source path_to_your_env_file_with_unique_ESMF_INSTALL_PREFIX +$ make &> compile.log +$ install $> install.log +$ mv compile.log $ESMF_INSTALL_PREFIX +$ mv install.log $ESMF_INSTALL_PREFIX .. _hardware_requirements: Hardware Requirements --------------------- -These are GCHP's hardware requirements. Note that high-end HPC infrastructure is not required to use -GCHP effectively. Gigabit Ethernet and 2 nodes is enough for returns on performance compared to +High-end HPC infrastructure is not required to use GCHP effectively. +Gigabit Ethernet and two nodes is enough for returns on performance compared to GEOS-Chem Classic. +Bare Minimum Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* 6 cores +* 32 GB of memory +* 100 GB of storage for input and output data + +Running GCHP on one node with as few as six cores is possible but we recommend this only for testing short low resolution runs such as running GCHP for the first time and for debugging. +These bare minimum requirements are sufficient for running GCHP at C24. +Please note that we recommend running at C90 or greater for scientific applications. + Recommended Minimum Requirements ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -These recommended minimums are adequate to effectively use GCHP in scientific -applications: - * 2 nodes, preferably ≥24 cores per node * Gigabit Ethernet (GbE) interconnect or better -* 100 GB memory per node +* 100+ GB memory per node * 1 TB of storage, depending on your input and output needs -Bare Minimum Requirements -^^^^^^^^^^^^^^^^^^^^^^^^^ - -These bare minimum requirements are sufficient for running GCHP at C24. They are adequate for trying GCHP out, and for learning purposes. Please note that we recommend running at C90 or greater for scientific applications. +These recommended minimums are adequate to effectively use GCHP in scientific +applications. These runs should be at grid resolutions at or above C90. -* 6 cores -* 32 GB of memory -* 100 GB of storage for input and output data Big Compute Recommendations ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -These hardware recommendations are for users that are interested in tackling large bleeding-edge computational problems: - -* A high-performance-computing cluster (or a cloud-HPC service like AWS) +* 5--50 nodes, or more if running at C720 (12 km grid) +* >24 cores per node (the more the better), preferably Intel Xeon +* High throughput and low-latency interconnect, preferably InfiniBand if using ≥500 cores +* 1 TB of storage, depending on your input and output needs - * 1--50 nodes - * >24 cores per node (the more the better), preferably Intel Xeon - * High throughput and low-latency interconnect, preferably InfiniBand if using ≥500 cores +These requirements can be met by using a high-performance-computing cluster or a cloud-HPC service like AWS. -* Lots of storage. Several TB is sufficient, but tens or hundreds of TB is better. General Hardware and Software Recommendations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * Hyper-threading may improve simulation throughput, particularly at low core counts -* MPI process should be bound sequentially across cores and nodes (e.g., a simulation with 48-processes with 24 processes per node - should bind rank 0 to CPU L#0, rank 1 to CPU L#1, etc. on the first node, and rank 24 to CPU L#0, rank 1 to CPU L#1, etc. on the - second node). This should be the default, but it's worth checking if your performance is lower than expected. With OpenMPI the +* MPI processes should be bound sequentially across cores and nodes. For example, a simulation using two nodes with 24 processes per node should bind ranks 0-23 on the first node and ranks 24-47 on the second node. This should be the default, but it's worth checking if your performance is lower than expected. With OpenMPI the `--report-bindings` argument will show you how processes are ranked and binded. * If using IntelMPI include the following your environment setup to avoid a run-time error: @@ -92,4 +166,4 @@ General Hardware and Software Recommendations export I_MPI_ADJUST_GATHERV=3 export I_MPI_ADJUST_ALLREDUCE=12 -* If using OpenMPI and a large number of cores (>1000) we recommend setting :literal:`WRITE_RESTART_BY_OSERVER: YES` in config file :file:`GCHP.rc`. This enables the MAPL o-server functionality for writing restart files, thereby speeding up the mdoel. This is set automatically when executing :file:`setCommonRunSettings.sh`. +* If using OpenMPI and a large number of cores (>1000) we recommend enabling the MAPL o-server functionality for writing restart files, thereby speeding up the model. This is set automatically when executing :file:`setCommonRunSettings.sh` if using over 1000 cores. You can also toggle whether to use it manually in that file. diff --git a/docs/source/supplement/stretched-grid.rst b/docs/source/supplement/stretched-grid.rst index 120a6e938..0fec1aa4c 100644 --- a/docs/source/supplement/stretched-grid.rst +++ b/docs/source/supplement/stretched-grid.rst @@ -153,7 +153,7 @@ Before continuing with the tutorial check that you have all pre-requisites: * You are able to run global GCHP simulations using MERRA2 data for July 2019 * You have the latest version of GEOS-Chem python package GCPy -* You python package cartopy >= 0.19 +* You have python package cartopy with version >= 0.19 Create run directory ^^^^^^^^^^^^^^^^^^^^^^^ From 3c4af5b714a9338ba9e4b50e0a2241661b7c1c27 Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Wed, 3 May 2023 13:08:33 -0400 Subject: [PATCH 14/54] GCHP run configuration docs updates Signed-off-by: Lizzie Lundgren --- docs/source/user-guide/rundir-config.rst | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/source/user-guide/rundir-config.rst b/docs/source/user-guide/rundir-config.rst index 6887de409..a907657d1 100644 --- a/docs/source/user-guide/rundir-config.rst +++ b/docs/source/user-guide/rundir-config.rst @@ -8,6 +8,10 @@ As noted earlier, the many configuration files in GCHP can be overwhelming but y --------------------------------------------------------------------------------------------------- +.. note:: + + If there is topic not covered on this page that you would like to see added please create an issue on the `GCHP issues page `_ with your request. + Compute resources ----------------- @@ -97,6 +101,15 @@ If you do not want to rename your restart file then you can create a symbolic li Please note that unlike GC-Classic, GCHP does not use a separate HEMCO restart file. All HEMCO restart variables are included in the main GCHP restart. +Enable restart file to have missing species +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Most simulations by default do not allow missing species in the restart file. +The model will exit with an error if species are not found. +However, there is a switch in :file:`setCommonRunSetting.sh` to disable this behavior. +This toggle is located in the section on infrequently changed settings under the header :file:`REQUIRE ALL SPECIES IN INITIAL RESTART FILE`. +Setting the switch to :file:`NO` will use background values set in :file:`species_database.yml` as initial values for species that are missing. + Turn on/off emissions inventories ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -157,7 +170,7 @@ Outputs Output diagnostics data on a lat-lon grid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -See documentation in the :file:`HISTORY.rc` config file for instructions on how to output diagnostic collection on lat-lon grids, as well as the configuration files section at the top of this page for more information on that file. If outputting on a lat-lon grid you may also output regional data instead of global. +See documentation in the :file:`HISTORY.rc` config file for instructions on how to output diagnostic collection on lat-lon grids, as well as the configuration files section at the top of this page for more information on that file. If outputting on a lat-lon grid you may also output regional data instead of global. Make sure that whatever grid you choose is listed under :file:`GRID_LABELS` and is not commented out in :file:`HISTORY.rc`. Output restart files at regular frequency ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -199,3 +212,10 @@ Generate monthly mean diagnostics You can toggle monthly mean diagnostics on/off from within :file:`setCommonRunSettings.sh` in the "DIAGNOSTICS" section if you also set auto-update of diagnostics it that file to on. All time-averaged diagnostic collections will then automatically be configured to compute monthly mean. Alternatively, you can edit :file:`HISTORY.rc` directly and set the "monthly" field to value 1 for each collection you wish to output monthly diagnostics for. +Prevent overwriting diagnostic files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default all GCHP run directories are configured to allow overwriting diagnostics files present in :file:`OutputDir` over the course a simulation. +You may disable this feature by setting :file:`Allow_Overwrite=.false.` at the top of configuration file :file:`HISTORY.rc`. + + From 30dfc6d4c95652a04db414b9b08e558b089eb296 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 10 May 2023 14:03:59 -0400 Subject: [PATCH 15/54] Update badge links in README.md README.md - Now use HTML for badge links (it's easier) Signed-off-by: Bob Yantosca --- README.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index b19b5e03e..4bf3df1f3 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,18 @@ ![GEOS-Chem Logo](https://github.com/geoschem/GCHP/raw/main/docs/source/_static/geos-chem-logo-wide.svg) - -[![DOI](https://zenodo.org/badge/200900441.svg)](https://zenodo.org/badge/latestdoi/200900441) - - - - - -The is the official repository for GEOS-Chem High Performance (GCHP). +

+ + + + + + + + +

+ + +The is the official repository for **GEOS-Chem High Performance (GCHP)**. :bulb: Documentation: https://gchp.readthedocs.io/en/latest/ From a8562a25aad53bf1c1a1ce2dc4c1d818fc9f3375 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 11 May 2023 11:43:24 -0400 Subject: [PATCH 16/54] Add .readthedocs.yaml to specify legacy RTD build container .readthedocs.yaml - Now use one of the legacy build containers to avoid issues with RTD builds. Signed-off-by: Bob Yantosca --- .readthedocs.yaml | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..0e3f47896 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,47 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# +# NOTE: This is now needed in order to prevent builds from failing due +# to Python package issues at the ReadTheDocs site. For more info, see: +# https://github.com/readthedocs/readthedocs.org/issues/10290 +# -- Bob Yantosca (10 May 2023) + +# Required +version: 2 + +## Set the version of Python and other tools you might need +#build: +# os: ubuntu-22.04 +# tools: +# python: "3.7" +# # You can also specify other tool versions: +# #nodejs: "19" +# #rust: "1.64" +# #golang: "1.19" + + +# Use the legacy image to avoid issues with older python packages +# -- Bob Yantosca (11 May 2023) +# Set the version of Python and other tools you might need +build: + image: latest + apt_packages: + - libclang + - cmake +python: + version: "3.7" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: html + configuration: docs/source/conf.py + +# If using Sphinx, optionally build your docs in additional formats such as PDF +#formats: +# - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt From e8284684b0177e3830f612fb0c972c856f227aec Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 11 May 2023 11:50:59 -0400 Subject: [PATCH 17/54] Use older tools in .readthedocs.yaml; Add pybtex to docs/requirements.txt .readthedocs.yaml - Specify the oldest versions of nodejs, rust, golang, to try to avoid issues with the GEOS-Chem logo not rendering docs/requirements.txt - Also add pybtex and pybtex-docutils Signed-off-by: Bob Yantosca --- .readthedocs.yaml | 25 ++++++------------------- docs/requirements.txt | 8 ++++++++ 2 files changed, 14 insertions(+), 19 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0e3f47896..fe7553173 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,26 +11,13 @@ version: 2 ## Set the version of Python and other tools you might need -#build: -# os: ubuntu-22.04 -# tools: -# python: "3.7" -# # You can also specify other tool versions: -# #nodejs: "19" -# #rust: "1.64" -# #golang: "1.19" - - -# Use the legacy image to avoid issues with older python packages -# -- Bob Yantosca (11 May 2023) -# Set the version of Python and other tools you might need build: - image: latest - apt_packages: - - libclang - - cmake -python: - version: "3.7" + os: ubuntu-22.04 + tools: + python: "3.7" + nodejs: "14" + rust: "1.55" + golang: "1.17" # Build documentation in the docs/ directory with Sphinx sphinx: diff --git a/docs/requirements.txt b/docs/requirements.txt index a9be1e6d6..050e2540c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -14,3 +14,11 @@ sphinxcontrib-bibtex==2.2.0 recommonmark docutils==0.16 jinja2==3.0.3 +# +# The updates below are needed along with the ~/.readthedocs.yaml file +# in order to prevent builds from failing due to package version +# incompatibilities. Please see this Github issue for more information: +# https://github.com/readthedocs/readthedocs.org/issues/10290 +# +pybtex==0.24.0 +pybtex-docutils==1.0.2 From eedb3524980ddc02bc3f440eda18c2e04f90f80c Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 11 May 2023 13:04:31 -0400 Subject: [PATCH 18/54] Updated GEOS-Chem logo & GitHub badge links in README.md README.md - Now point to GEOS-Chem logo at geoschem.github.io, and display at 60% height, 60% width - Updated links to GitHub badges CHANGELOG.md - Updated accordingly Signed-off-by: Bob Yantosca --- CHANGELOG.md | 1 + README.md | 12 ++++++++---- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b35402e0f..b2fc0714b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), ## Unreleased - Updated `AUTHORS.txt` for GCHP 14.2.0 - Updated `README.md` so that links point to http://geos-chem.org +- Updated logo & badge links in `README.md` ## [14.1.1] - 2023-03-03 ### Added diff --git a/README.md b/README.md index 4bf3df1f3..6ff64cddd 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ -![GEOS-Chem Logo](https://github.com/geoschem/GCHP/raw/main/docs/source/_static/geos-chem-logo-wide.svg) +GEOS-Chem Logo

- + - +
+ @@ -12,6 +14,8 @@

+## Description + The is the official repository for **GEOS-Chem High Performance (GCHP)**. :bulb: Documentation: https://gchp.readthedocs.io/en/latest/ @@ -24,4 +28,4 @@ The is the official repository for **GEOS-Chem High Performance (GCHP)**. GEOS-Chem is a global 3-D model of atmospheric chemistry driven by meteorological input from the Goddard Earth Observing System (GEOS) of the [NASA Global Modeling and Assimilation Office](http://gmao.gsfc.nasa.gov/). It is applied by [research groups around the world](http://geos-chem.org/people.html) to a wide range of atmospheric composition problems. Scientific direction of the model is provided by the international [GEOS-Chem Steering Committee](http://geos-chem.org/steering-committee.html) and by [User Working Groups](http://geos-chem.org/working-groups.html). The model is managed by the [GEOS-Chem Support Team](http://geos-chem.org/support-team.html), based at Harvard University and Washington University in St. Louis with support from the US NASA Earth Science Division, the Canadian National and Engineering Research Council, and the Nanjing University of Information Sciences and Technology. -GEOS-Chem is a grass-roots open-access model owned by its [users](http://geos-chem.org/people.html), and ownership implies some responsibilities as listed in our [welcome page for new users](http://geos-chem.org/welcome.html). +GEOS-Chem is a grass-roots open-access model owned by its [users](http://geos-chem.org/people.html), and ownership implies some responsibilities as listed in our [welcome page for new users](http://geos-chem.org/welcome.html). From 913f6a38142e4d1b8a16e14b0a5f50d869024d20 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 11 May 2023 13:23:41 -0400 Subject: [PATCH 19/54] Remove pybtex and pybtex-docutils from requirements.txt Signed-off-by: Bob Yantosca --- docs/requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 050e2540c..05d8fe8e1 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -20,5 +20,5 @@ jinja2==3.0.3 # incompatibilities. Please see this Github issue for more information: # https://github.com/readthedocs/readthedocs.org/issues/10290 # -pybtex==0.24.0 -pybtex-docutils==1.0.2 +#pybtex==0.24.0 +#pybtex-docutils==1.0.2 From c65c757b52000070d2ed83ac3191208ec0637999 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 11 May 2023 15:00:24 -0400 Subject: [PATCH 20/54] Fix typo in html_static_path in conf.py docs/source/conf.py - Fix typo in html_static_path, "_static" should be "_static/" docs/requirements.txt - Remove pybtex and pybtex-docutils CHANGELOG.md - updated accordingly Signed-off-by: Bob Yantosca --- CHANGELOG.md | 7 +++++++ docs/requirements.txt | 8 -------- docs/source/conf.py | 2 +- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b2fc0714b..369c0a36f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,10 +8,17 @@ This file documents all notable changes to the GCHP wrapper repository starting The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## Unreleased +### Added +- Added `.readthedocs.yaml` to configure ReadTheDocs builds + +### Changed - Updated `AUTHORS.txt` for GCHP 14.2.0 - Updated `README.md` so that links point to http://geos-chem.org - Updated logo & badge links in `README.md` +### Fixed +- Typo in `docs/source/conf.py`, "_static" should be "_static/" + ## [14.1.1] - 2023-03-03 ### Added - Added `EXE_FILE_NAME` and `INSTALLCOPY` to src/CMakeLists.txt (facilitates integration testing) diff --git a/docs/requirements.txt b/docs/requirements.txt index 05d8fe8e1..a9be1e6d6 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -14,11 +14,3 @@ sphinxcontrib-bibtex==2.2.0 recommonmark docutils==0.16 jinja2==3.0.3 -# -# The updates below are needed along with the ~/.readthedocs.yaml file -# in order to prevent builds from failing due to package version -# incompatibilities. Please see this Github issue for more information: -# https://github.com/readthedocs/readthedocs.org/issues/10290 -# -#pybtex==0.24.0 -#pybtex-docutils==1.0.2 diff --git a/docs/source/conf.py b/docs/source/conf.py index 3cf5aefe4..98fdb0dfb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -94,7 +94,7 @@ def format_web_refs(self, e): # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = [ - '_static', + '_static/', 'geos-chem-shared-docs/_static/', ] From d219e2493959e8fe8f6645ea407462aa059dca48 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 11 May 2023 16:16:07 -0400 Subject: [PATCH 21/54] Fix DOI link in README.md README.md - Now point to the GCHP concept DOI (10.5281/zenodo.4428926), which will always point to the latest DOI version. Signed-off-by: Bob Yantosca --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6ff64cddd..1735f2d0f 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,14 @@ -GEOS-Chem Logo +GEOS-Chem Logo

-
+
- + DOI

From 7f805412e87bbab9130379ddeb6f3528c0696634 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 11 May 2023 17:17:41 -0400 Subject: [PATCH 22/54] Now use formats:all in .readthedocs.yaml .readthedocs.yaml - This will tell Sphinx to build documentation in all formats (htmlzip, epub, pdf). Signed-off-by: Bob Yantosca --- .readthedocs.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index fe7553173..6d3e7ae46 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -25,8 +25,7 @@ sphinx: configuration: docs/source/conf.py # If using Sphinx, optionally build your docs in additional formats such as PDF -#formats: -# - pdf +formats: all # Optionally declare the Python requirements required to build your docs python: From 6ad817985c0cc69f1d4b9f9f9e732b6121c5392f Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 16 May 2023 11:27:15 -0400 Subject: [PATCH 23/54] Add submodules menu to .readthedocs.yaml .readthedocs.yaml - Added the submodules menu so that RTD will be explicitly told to clone all submodules recursively. Signed-off-by: Bob Yantosca --- .readthedocs.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6d3e7ae46..7c8d284c8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -31,3 +31,8 @@ formats: all python: install: - requirements: docs/requirements.txt + +# Tell RTD to clone all submodules +submodules: + include: all + recursive: true From c5b56d75e61a5ba8dc9d84d56abe551b3117bf85 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 30 May 2023 11:57:00 -0400 Subject: [PATCH 24/54] Update GCHP version number to 14.2.0 CMakeLists.txt docs/source/conf.py - Updated version number from 14.1.1 to 14.2.0 CHANGELOG.md - Updated accordingly Signed-off-by: Bob Yantosca --- CHANGELOG.md | 1 + CMakeLists.txt | 2 +- docs/source/conf.py | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 369c0a36f..2244b87e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Updated `AUTHORS.txt` for GCHP 14.2.0 - Updated `README.md` so that links point to http://geos-chem.org - Updated logo & badge links in `README.md` +- Updated version number to 14.2.0 ### Fixed - Typo in `docs/source/conf.py`, "_static" should be "_static/" diff --git a/CMakeLists.txt b/CMakeLists.txt index bedf2fb19..12052ab73 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required (VERSION 3.13) project (gchp_ctm - VERSION 14.1.1 + VERSION 14.2.0 LANGUAGES Fortran CXX C ) diff --git a/docs/source/conf.py b/docs/source/conf.py index 98fdb0dfb..e13a8b414 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,7 +23,7 @@ author = 'GEOS-Chem Support Team' # The full version, including alpha/beta/rc tags -release = '14.1.1' +release = '14.2.0 # -- General configuration --------------------------------------------------- From bf67ba8b43742f4ea0312b4a2ab5d5012a03eff4 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 5 Jun 2023 11:57:03 -0400 Subject: [PATCH 25/54] geos-chem-shared-docs update: Add TransportTracer species metadata docs/source/geos-chem-shared-docs - Added TransportTracers metadata to the species-guide.rst supplemental guide Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index b96e45868..bfaf452df 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit b96e45868d41809d999264cb7a92aee3ddf77cbf +Subproject commit bfaf452dfc331aa3b5b10b7ce54b2e0fafd9221a From 36eef209ba94a46ed150e33e45e349c8842a481b Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Mon, 5 Jun 2023 11:58:04 -0400 Subject: [PATCH 26/54] Fix issues with GCHP ReadTheDocs build; update badges docs/source/conf.py - Added missing ' character at the end of the version number docs/source/index.rst - Updated badges; removed badges for obsolete things Signed-off-by: Bob Yantosca --- docs/source/conf.py | 2 +- docs/source/index.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index e13a8b414..887a31d03 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,7 +23,7 @@ author = 'GEOS-Chem Support Team' # The full version, including alpha/beta/rc tags -release = '14.2.0 +release = '14.2.0' # -- General configuration --------------------------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index ac2e5d81a..def131afb 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,13 +4,13 @@ GEOS-Chem High Performance .. raw:: html

- + + +
+ - - -

The `GEOS--Chem model `_ is a global 3-D model From ade5fe8da26e9c241791a4c2fc6ca24c46f10b47 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 20 Jun 2023 15:05:57 -0400 Subject: [PATCH 27/54] geos-chem-shared-docs update: Add note about some species having MW of N docs/source/geos-chem-shared-docs/supplemental-guides/species-guide.rst - Added note about some species (MONITA, IONITA) having the MW of nitrogen, with citation. Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index bfaf452df..dd64465e4 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit bfaf452dfc331aa3b5b10b7ce54b2e0fafd9221a +Subproject commit dd64465e4556228676fb2dba65c7fe7693dc0f28 From 5a65124df504c8018a2756eab464304170011db4 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Tue, 11 Jul 2023 16:40:20 -0400 Subject: [PATCH 28/54] Update LICENSE.txt and AUTHORS.txt as of July 2023 AUTHORS.txt - Added new code contributors for GEOS-Chem 14.2.0 and 14.2.1 LICENSE.txt - Updated for better readability - Add text of GPLv3 license (used by QFYAML, FAST-JX, KPP) - Add text of Apache license (used by MAPL etc) - Add text of NASA Open Source Agreement (used by MAPL etc) - Trimmed trailing whitespace Signed-off-by: Bob Yantosca --- AUTHORS.txt | 38 +- LICENSE.txt | 1257 ++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 1226 insertions(+), 69 deletions(-) diff --git a/AUTHORS.txt b/AUTHORS.txt index 0a43922ec..bb4eebd22 100644 --- a/AUTHORS.txt +++ b/AUTHORS.txt @@ -1,5 +1,5 @@ -List of Developers for GEOS-Chem, GCHP, HEMCO, and Related Software -(24 Apr 2023) +List of Developers for GEOS-Chem, HEMCO, and Related Software +(11 Jul 2023) =============================================================================== ADAMS, Peter @@ -9,6 +9,7 @@ AMOS, Helen ANGOT, Helene AUSMEEL, Stina AUVRAY, Marion +BALASUS, Nicholas BARAY, Sabour BARKLEY, Michael BARRET, Steven @@ -26,11 +27,11 @@ BRATTICH, Erika BREIDER, Tom BREWER, Jared BROWNE, Ellie -BROWN, Benjamin-Steiner +BROWN-STEINER, Benjamin BUKOSA, Beata BUTENHOFF, Christopher -CADY, Karen-Pereira -CAMERON, Philip-Smith +CADY-PEREIRA, Karen +CAMERON-SMITH, Philip CAMPBELL, Patrick CAO, Guofeng CAO, Hansen @@ -38,7 +39,7 @@ CAO, Liangzhong CAO, Yi CAPPS, Shannon CAROUGE, Claire -CARTER, Therese +CARTER, Therese (Tess) CAZORLA, Maria CHALIYAKUNNEL, Sreelekha CHEN, Han @@ -63,7 +64,7 @@ DENG, Feng DESOUZA, Priyanka DESSERVETTAZ, Max DEUTSCHER, Nicholas -DI, Maurizio Pierro +DI PIERRO, Maurizio DLAMINI, Thandolwethu DOMMERGUE, Aurelien DOWNS, Will @@ -74,7 +75,7 @@ ELLIS, Raluca ENBERG, Joseph ESTRADA, Lucas EVANS, Mathew -FAIRLIE, +FAIRLIE, T. Duncan FARINA, Sal FAYE, Vivian FEINBERG, Ari @@ -84,13 +85,13 @@ FISCHER, Emily FISHER, Jenny FITE, Charley FLEMING, Eric -FLO, Judit-Gaya +FLO-GAYA, Judit FORD, Bonne FRANCIS, Timmy FREESE, Lyssa FRIEDMAN, Carey FRITZ, Thibaud -FU, +FU, Tzung-May FU, Joshua GANTT, Brett GE, Cui @@ -129,9 +130,10 @@ JISKRA, Martin JOHNSON, Matthew JONES, Dylan JUNG, Jaegun -KASIBHATLA, Prasad -HUDMAN, Rynda Kay +KASIBHATLA, +KAY, Rynda Hudman KELLER, Christoph +KELP, Makoto KIKUCHI, Tetsuro KIM, Hyeonmin KIM, Sungshik @@ -156,19 +158,19 @@ LEE, Meemong LEHMANN, Ralph LEIBENSPERGER, Eric LERICHE, Maud -LEUNG, +LEUNG, Fok-Yan LI, Bengang LI, Chi LI, Ke LI, Qinbin LI, Xianglan LI, Yanshun -LIAO, +LIAO, K.J. LIANG, Qing LIAO, Hong LIN, Haipeng LIN, Jintai -LIN, +LIN, Shian-Jiann LINFORD, John LIU, Hongyu LIU, Jane @@ -200,7 +202,7 @@ MENG, Jun MESKHIDZE, Nicholas MIATSELSKAYA, Natallia MICKLEY, Loretta -CHAN, Christopher Miller +MILLER, Christopher Chan MILLET, Dylan MING, Kai MOCH, Jonathan @@ -219,7 +221,7 @@ NENES, Athanasios NEVISON, Cynthia NIELSEN, Eric NOTHOLT, Justus -O, Kate'Dell +O'DELL, Kate OKAMOTO, Sachiko PAGE, Neil PAI, Sidhant @@ -247,6 +249,7 @@ REINHART, Wes RIDLEY, David RIZZA, Umberto ROTHENBERG, Daniel +ROY, Eric SAFIEDDINE, Sarah SANDU, Adrian SANTILLANA, Mauricio @@ -308,6 +311,7 @@ VAL, Maria-Martin VAN, Aaron Donkelaar VAROTSOS, Kostas VINKEN, Geert +VITT, Francis WAGSTROM, Kristina WALKER, Thomas WANG, James diff --git a/LICENSE.txt b/LICENSE.txt index fee62bda0..568f7df5e 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,8 +1,9 @@ -License Agreement for GEOS-Chem, HEMCO, and Related Software -(The MIT "Expat" License, http://opensource.org/licenses/MIT) -============================================================================== +############################################################################ +### License Agreement for GEOS-Chem, HEMCO, and Related Software ### +### (The MIT License, http://opensource.org/licenses/MIT) ### +############################################################################ -Copyright (c) 2017-2021 Developers of GEOS-Chem, HEMCO, and Related Software +Copyright (c) 2017-2023 Developers of GEOS-Chem, HEMCO, and Related Software Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -22,61 +23,35 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ------------------------------------------------------------------------------- -NOTE: Please see the AUTHORS.txt file (in this folder) for the list of -Developers of GEOS-Chem, GCPy and Related Software. This list will -be updated frequently, such as at each major GEOS-Chem or GCPy release. ------------------------------------------------------------------------------- - - -License agreements for 3rd-party code packages used by GEOS-Chem: -============================================================================== - -FAST-J, FAST-JX, and developments: - - Fast-J code, including developments such as Cloud-J, is distributed under - GNU General Public License version 3.0 (GPLv3). (A copy of the GNU public - license is here: https://www.gnu.org/licenses/gpl-3.0.en.html) - https://www.ess.uci.edu/researchgrp/prather/scholar_software - - -ISORROPIA: - - COPYRIGHT 1996-2006, UNIVERSITY OF MIAMI, CARNEGIE MELLON UNIVERSITY, - GEORGIA INSTITUTE OF TECHNOLOGY - WRITTEN BY ATHANASIOS NENES - UPDATED BY CHRISTOS FOUNTOUKIS - - -KPP chemical solver (Kinetic Pre-Processor): - - KPP - symbolic chemistry Kinetics PreProcessor, Version 2.1 - (http://www.cs.vt.edu/~asandu/Software/KPP) - KPP is distributed under GPL, the general public licence - (http://www.gnu.org/copyleft/gpl.html) - (C) 1995-1997, V. Damian & A. Sandu, CGRER, Univ. Iowa - (C) 1997-2005, A. Sandu, Michigan Tech, Virginia Tech - with contributions from: - R. Sander, Max-Planck Institute for Chemistry, Mainz, Germany + NOTE: Please see the AUTHORS.txt file (in this folder) for the list of + Developers of GEOS-Chem, HEMCO and Related Software. This list will + be updated frequently, such as at each major GEOS-Chem release. +############################################################################# +### License agreements for third-party code packages ### +### used by GEOS-Chem, HEMCO, and Related Software ### +############################################################################# Linked list code (used in v11-02 and later versions): +----------------------------------------------------------------------------- Copyright © 2005 Arjen Markus http://flibs.sourceforge.net/linked_list.html RRTM/RRTMG Copyright and Disclaimer: +----------------------------------------------------------------------------- - Copyright © 2002-2010, Atmospheric and Environmental Research, Inc. - (AER, Inc.). This software may be used, copied, or redistributed as long - as it is not sold and this copyright notice is reproduced on each copy made. + Copyright © 2002-2010, Atmospheric and Environmental Research, Inc. + (AER, Inc.). This software may be used, copied, or redistributed as long + as it is not sold and this copyright notice is reproduced on each copy made. This model is provided as is without any express or implied warranties. http://rtweb.aer.com/rrtm_frame.html Fortran hash table code (used in 12.7.0 and later): https://github.com/pdebuyl/fortran_hash_table +----------------------------------------------------------------------------- Copyright (c) 2018, Pierre de Buyl @@ -108,19 +83,1197 @@ https://github.com/pdebuyl/fortran_hash_table OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +Modular Earth Submodel System (MESSy) tools: +----------------------------------------------------------------------------- + + See https://messy-interface.org/licence/conditions/ + + +ISORROPIA (Aerosol Therymodynamical Equilibrium module): +------------------------------------------------------------------------------ + + COPYRIGHT 1996-2006, UNIVERSITY OF MIAMI, CARNEGIE MELLON UNIVERSITY, + GEORGIA INSTITUTE OF TECHNOLOGY + WRITTEN BY ATHANASIOS NENES + UPDATED BY CHRISTOS FOUNTOUKIS + +QFYAML: Quick Fortran YAML +------------------------------------------------------------------------------ + + See GPLv3 License text under The KineticPreProcessor (KPP). + + +FAST-J, FAST-JX, Cloud-J, and developments: +------------------------------------------------------------------------------ + + Fast-J code, including developments such as Cloud-J, is distributed under + GNU General Public License version 3.0 (GPLv3). + https://www.ess.uci.edu/researchgrp/prather/scholar_software + + See GPLv3 License text under the KPP section. + + +The Kinetic PreProcessor (KPP) +------------------------------------------------------------------------------ + + KPP - symbolic chemistry Kinetics PreProcessor + (http://www.cs.vt.edu/~asandu/Software/KPP) + KPP is distributed under GPL, the general public licence + (http://www.gnu.org/copyleft/gpl.html) + (C) 1995-1997, V. Damian & A. Sandu, CGRER, Univ. Iowa + (C) 1997-2005, A. Sandu, Michigan Tech, Virginia Tech + with contributions from: + R. Sander, Max-Planck Institute for Chemistry, Mainz, Germany + + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for + software and other kinds of works. + + The licenses for most software and other practical works are designed + to take away your freedom to share and change the works. By contrast, + the GNU General Public License is intended to guarantee your freedom to + share and change all versions of a program--to make sure it remains free + software for all its users. We, the Free Software Foundation, use the + GNU General Public License for most of our software; it applies also to + any other work released this way by its authors. You can apply it to + your programs, too. + + When we speak of free software, we are referring to freedom, not + price. Our General Public Licenses are designed to make sure that you + have the freedom to distribute copies of free software (and charge for + them if you wish), that you receive source code or can get it if you + want it, that you can change the software or use pieces of it in new + free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you + these rights or asking you to surrender the rights. Therefore, you have + certain responsibilities if you distribute copies of the software, or if + you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether + gratis or for a fee, you must pass on to the recipients the same + freedoms that you received. You must make sure that they, too, receive + or can get the source code. And you must show them these terms so they + know their rights. + + Developers that use the GNU GPL protect your rights with two steps: + (1) assert copyright on the software, and (2) offer you this License + giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains + that there is no warranty for this free software. For both users' and + authors' sake, the GPL requires that modified versions be marked as + changed, so that their problems will not be attributed erroneously to + authors of previous versions. + + Some devices are designed to deny users access to install or run + modified versions of the software inside them, although the manufacturer + can do so. This is fundamentally incompatible with the aim of + protecting users' freedom to change the software. The systematic + pattern of such abuse occurs in the area of products for individuals to + use, which is precisely where it is most unacceptable. Therefore, we + have designed this version of the GPL to prohibit the practice for those + products. If such problems arise substantially in other domains, we + stand ready to extend this provision to those domains in future versions + of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. + States should not allow patents to restrict development and use of + software on general-purpose computers, but in those that do, we wish to + avoid the special danger that patents applied to a free program could + make it effectively proprietary. To prevent this, the GPL assures that + patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and + modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of + works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this + License. Each licensee is addressed as "you". "Licensees" and + "recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work + in a fashion requiring copyright permission, other than the making of an + exact copy. The resulting work is called a "modified version" of the + earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based + on the Program. + + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it on a + computer or modifying a private copy. Propagation includes copying, + distribution (with or without modification), making available to the + public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other + parties to make or receive copies. Mere interaction with a user through + a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" + to the extent that it includes a convenient and prominently visible + feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to the + extent that warranties are provided), that licensees may convey the + work under this License, and how to view a copy of this License. If + the interface presents a list of user commands or options, such as a + menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work + for making modifications to it. "Object code" means any non-source + form of a work. + + A "Standard Interface" means an interface that either is an official + standard defined by a recognized standards body, or, in the case of + interfaces specified for a particular programming language, one that + is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other + than the work as a whole, that (a) is included in the normal form of + packaging a Major Component, but which is not part of that Major + Component, and (b) serves only to enable use of the work with that + Major Component, or to implement a Standard Interface for which an + implementation is available to the public in source code form. A + "Major Component", in this context, means a major essential component + (kernel, window system, and so on) of the specific operating system + (if any) on which the executable work runs, or a compiler used to + produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all + the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including scripts to + control those activities. However, it does not include the work's + System Libraries, or general-purpose tools or generally available free + programs which are used unmodified in performing those activities but + which are not part of the work. For example, Corresponding Source + includes interface definition files associated with source files for + the work, and the source code for shared libraries and dynamically + linked subprograms that the work is specifically designed to require, + such as by intimate data communication or control flow between those + subprograms and other parts of the work. + + The Corresponding Source need not include anything that users + can regenerate automatically from other parts of the Corresponding + Source. + + The Corresponding Source for a work in source code form is that + same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of + copyright on the Program, and are irrevocable provided the stated + conditions are met. This License explicitly affirms your unlimited + permission to run the unmodified Program. The output from running a + covered work is covered by this License only if the output, given its + content, constitutes a covered work. This License acknowledges your + rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise remains + in force. You may convey covered works to others for the sole purpose + of having them make modifications exclusively for you, or provide you + with facilities for running those works, provided that you comply with + the terms of this License in conveying all material for which you do + not control copyright. Those thus making or running the covered works + for you must do so exclusively on your behalf, under your direction + and control, on terms that prohibit them from making any copies of + your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under + the conditions stated below. Sublicensing is not allowed; section 10 + makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological + measure under any applicable law fulfilling obligations under article + 11 of the WIPO copyright treaty adopted on 20 December 1996, or + similar laws prohibiting or restricting circumvention of such + measures. + + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such circumvention + is effected by exercising rights under this License with respect to + the covered work, and you disclaim any intention to limit operation or + modification of the work as a means of enforcing, against the work's + users, your or third parties' legal rights to forbid circumvention of + technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you + receive it, in any medium, provided that you conspicuously and + appropriately publish on each copy an appropriate copyright notice; + keep intact all notices stating that this License and any + non-permissive terms added in accord with section 7 apply to the code; + keep intact all notices of the absence of any warranty; and give all + recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, + and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to + produce it from the Program, in the form of source code under the + terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent + works, which are not by their nature extensions of the covered work, + and which are not combined with it such as to form a larger program, + in or on a volume of a storage or distribution medium, is called an + "aggregate" if the compilation and its resulting copyright are not + used to limit the access or legal rights of the compilation's users + beyond what the individual works permit. Inclusion of a covered work + in an aggregate does not cause this License to apply to the other + parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms + of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this License, + in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded + from the Corresponding Source as a System Library, need not be + included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any + tangible personal property which is normally used for personal, family, + or household purposes, or (2) anything designed or sold for incorporation + into a dwelling. In determining whether a product is a consumer product, + doubtful cases shall be resolved in favor of coverage. For a particular + product received by a particular user, "normally used" refers to a + typical or common use of that class of product, regardless of the status + of the particular user or of the way in which the particular user + actually uses, or expects or is expected to use, the product. A product + is a consumer product regardless of whether the product has substantial + commercial, industrial or non-consumer uses, unless such uses represent + the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to install + and execute modified versions of a covered work in that User Product from + a modified version of its Corresponding Source. The information must + suffice to ensure that the continued functioning of the modified object + code is in no case prevented or interfered with solely because + modification has been made. + + If you convey an object code work under this section in, or with, or + specifically for use in, a User Product, and the conveying occurs as + part of a transaction in which the right of possession and use of the + User Product is transferred to the recipient in perpetuity or for a + fixed term (regardless of how the transaction is characterized), the + Corresponding Source conveyed under this section must be accompanied + by the Installation Information. But this requirement does not apply + if neither you nor any third party retains the ability to install + modified object code on the User Product (for example, the work has + been installed in ROM). + + The requirement to provide Installation Information does not include a + requirement to continue to provide support service, warranty, or updates + for a work that has been modified or installed by the recipient, or for + the User Product in which it has been modified or installed. Access to a + network may be denied when the modification itself materially and + adversely affects the operation of the network or violates the rules and + protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, + in accord with this section must be in a format that is publicly + documented (and with an implementation available to the public in + source code form), and must require no special password or key for + unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this + License by making exceptions from one or more of its conditions. + Additional permissions that are applicable to the entire Program shall + be treated as though they were included in this License, to the extent + that they are valid under applicable law. If additional permissions + apply only to part of the Program, that part may be used separately + under those permissions, but the entire Program remains governed by + this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any part of + it. (Additional permissions may be written to require their own + removal in certain cases when you modify the work.) You may place + additional permissions on material, added by you to a covered work, + for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you + add to a covered work, you may (if authorized by the copyright holders of + that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further + restrictions" within the meaning of section 10. If the Program as you + received it, or any part of it, contains a notice stating that it is + governed by this License along with a term that is a further + restriction, you may remove that term. If a license document contains + a further restriction but permits relicensing or conveying under this + License, you may add to a covered work material governed by the terms + of that license document, provided that the further restriction does + not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you + must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice indicating + where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the + form of a separately written license, or stated as exceptions; + the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly + provided under this License. Any attempt otherwise to propagate or + modify it is void, and will automatically terminate your rights under + this License (including any patent licenses granted under the third + paragraph of section 11). + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the copyright + holder fails to notify you of the violation by some reasonable means + prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from that + copyright holder, and you cure the violation prior to 30 days after + your receipt of the notice. + + Termination of your rights under this section does not terminate the + licenses of parties who have received copies or rights from you under + this License. If your rights have been terminated and not permanently + reinstated, you do not qualify to receive new licenses for the same + material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or + run a copy of the Program. Ancillary propagation of a covered work + occurring solely as a consequence of using peer-to-peer transmission + to receive a copy likewise does not require acceptance. However, + nothing other than this License grants you permission to propagate or + modify any covered work. These actions infringe copyright if you do + not accept this License. Therefore, by modifying or propagating a + covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify and + propagate that work, subject to this License. You are not responsible + for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an + organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a covered + work results from an entity transaction, each party to that + transaction who receives a copy of the work also receives whatever + licenses to the work the party's predecessor in interest had or could + give under the previous paragraph, plus a right to possession of the + Corresponding Source of the work from the predecessor in interest, if + the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the + rights granted or affirmed under this License. For example, you may + not impose a license fee, royalty, or other charge for exercise of + rights granted under this License, and you may not initiate litigation + (including a cross-claim or counterclaim in a lawsuit) alleging that + any patent claim is infringed by making, using, selling, offering for + sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this + License of the Program or a work on which the Program is based. The + work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, permitted + by this License, of making, using, or selling its contributor version, + but do not include claims that would be infringed only as a + consequence of further modification of the contributor version. For + purposes of this definition, "control" includes the right to grant + patent sublicenses in a manner consistent with the requirements of + this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free + patent license under the contributor's essential patent claims, to + make, use, sell, offer for sale, import and otherwise run, modify and + propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express + agreement or commitment, however denominated, not to enforce a patent + (such as an express permission to practice a patent or covenant not to + sue for patent infringement). To "grant" such a patent license to a + party means to make such an agreement or commitment not to enforce a + patent against the party. + + If you convey a covered work, knowingly relying on a patent license, + and the Corresponding Source of the work is not available for anyone + to copy, free of charge and under the terms of this License, through a + publicly available network server or other readily accessible means, + then you must either (1) cause the Corresponding Source to be so + available, or (2) arrange to deprive yourself of the benefit of the + patent license for this particular work, or (3) arrange, in a manner + consistent with the requirements of this License, to extend the patent + license to downstream recipients. "Knowingly relying" means you have + actual knowledge that, but for the patent license, your conveying the + covered work in a country, or your recipient's use of the covered work + in a country, would infringe one or more identifiable patents in that + country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance of, a + covered work, and grant a patent license to some of the parties + receiving the covered work authorizing them to use, propagate, modify + or convey a specific copy of the covered work, then the patent license + you grant is automatically extended to all recipients of the covered + work and works based on it. + + A patent license is "discriminatory" if it does not include within + the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that are + specifically granted under this License. You may not convey a covered + work if you are a party to an arrangement with a third party that is + in the business of distributing software, under which you make payment + to the third party based on the extent of your activity of conveying + the work, and under which the third party grants, to any of the + parties who would receive the covered work from you, a discriminatory + patent license (a) in connection with copies of the covered work + conveyed by you (or copies made from those copies), or (b) primarily + for and in connection with specific products or compilations that + contain the covered work, unless you entered into that arrangement, + or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting + any implied license or other defenses to infringement that may + otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or + otherwise) that contradict the conditions of this License, they do not + excuse you from the conditions of this License. If you cannot convey a + covered work so as to satisfy simultaneously your obligations under this + License and any other pertinent obligations, then as a consequence you may + not convey it at all. For example, if you agree to terms that obligate you + to collect a royalty for further conveying from those to whom you convey + the Program, the only way you could satisfy both those terms and this + License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work licensed + under version 3 of the GNU Affero General Public License into a single + combined work, and to convey the resulting work. The terms of this + License will continue to apply to the part which is the covered work, + but the special requirements of the GNU Affero General Public License, + section 13, concerning interaction through a network will apply to the + combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of + the GNU General Public License from time to time. Such new versions will + be similar in spirit to the present version, but may differ in detail to + address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU General + Public License "or any later version" applies to it, you have the + option of following the terms and conditions either of that numbered + version or of any later version published by the Free Software + Foundation. If the Program does not specify a version number of the + GNU General Public License, you may choose any version ever published + by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that proxy's + public statement of acceptance of a version permanently authorizes you + to choose that version for the Program. + + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on any + author or copyright holder as a result of your choosing to follow a + later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT + HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY + OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, + THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM + IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF + ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING + WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS + THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY + GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE + USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF + DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), + EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF + SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided + above cannot be given local legal effect according to their terms, + reviewing courts shall apply local law that most closely approximates + an absolute waiver of all civil liability in connection with the + Program, unless a warranty or assumption of liability accompanies a + copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest + possible use to the public, the best way to achieve this is to make it + free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest + to attach them to the start of each source file to most effectively + state the exclusion of warranty; and each file should have at least + the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + + Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short + notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + + The hypothetical commands `show w' and `show c' should show the appropriate + parts of the General Public License. Of course, your program's commands + might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, + if any, to sign a "copyright disclaimer" for the program, if necessary. + For more information on this, and how to apply and follow the GNU GPL, see + . + + The GNU General Public License does not permit incorporating your program + into proprietary programs. If your program is a subroutine library, you + may consider it more useful to permit linking proprietary applications with + the library. If this is what you want to do, use the GNU Lesser General + Public License instead of this License. But first, please read + . + + +MAPL (used by GCHP and the interface to the NASA-GEOS model): +----------------------------------------------------------------------------- + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, and + distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by the copyright + owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all other entities + that control, are controlled by, or are under common control with that entity. + For the purposes of this definition, "control" means (i) the power, direct or + indirect, to cause the direction or management of such entity, whether by + contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity exercising + permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, including + but not limited to software source code, documentation source, and configuration + files. + + "Object" form shall mean any form resulting from mechanical transformation or + translation of a Source form, including but not limited to compiled object code, + generated documentation, and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or Object form, made + available under the License, as indicated by a copyright notice that is included + in or attached to the work (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object form, that + is based on (or derived from) the Work and for which the editorial revisions, + annotations, elaborations, or other modifications represent, as a whole, an + original work of authorship. For the purposes of this License, Derivative Works + shall not include works that remain separable from, or merely link (or bind by + name) to the interfaces of, the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including the original version + of the Work and any modifications or additions to that Work or Derivative Works + thereof, that is intentionally submitted to Licensor for inclusion in the Work + by the copyright owner or by an individual or Legal Entity authorized to submit + on behalf of the copyright owner. For the purposes of this definition, + "submitted" means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, and + issue tracking systems that are managed by, or on behalf of, the Licensor for + the purpose of discussing and improving the Work, but excluding communication + that is conspicuously marked or otherwise designated in writing by the copyright + owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity on behalf + of whom a Contribution has been received by Licensor and subsequently + incorporated within the Work. + + 2. Grant of Copyright License. + + Subject to the terms and conditions of this License, each Contributor hereby + grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, + irrevocable copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the Work and such + Derivative Works in Source or Object form. + + 3. Grant of Patent License. + + Subject to the terms and conditions of this License, each Contributor hereby + grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, + irrevocable (except as stated in this section) patent license to make, have + made, use, offer to sell, sell, import, and otherwise transfer the Work, where + such license applies only to those patent claims licensable by such Contributor + that are necessarily infringed by their Contribution(s) alone or by combination + of their Contribution(s) with the Work to which such Contribution(s) was + submitted. If You institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work or a + Contribution incorporated within the Work constitutes direct or contributory + patent infringement, then any patent licenses granted to You under this License + for that Work shall terminate as of the date such litigation is filed. + + 4. Redistribution. + + You may reproduce and distribute copies of the Work or Derivative Works + thereof in any medium, with or without modifications, and in Source or Object + form, provided that You meet the following conditions: + + (a) You must give any other recipients of the Work or Derivative Works a + copy of this License; and + + (b) You must cause any modified files to carry prominent notices stating that + You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works that You + distribute, all copyright, patent, trademark, and attribution notices from + the Source form of the Work, excluding those notices that do not pertain + to any part of the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its distribution, + then any Derivative Works that You distribute must include a readable copy + of the attribution notices contained within such NOTICE file, excluding + those notices that do not pertain to any part of the Derivative Works, in + at least one of the following places: within a NOTICE text file + distributed as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, within a + display generated by the Derivative Works, if and wherever such + third-party notices normally appear. The contents of the NOTICE file are + for informational purposes only and do not modify the License. You may add + Your own attribution notices within Derivative Works that You distribute, + alongside or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed as modifying + the License. + + You may add Your own copyright statement to Your modifications and may + provide additional or different license terms and conditions for use, + reproduction, or distribution of Your modifications, or for any such + Derivative Works as a whole, provided Your use, reproduction, and + distribution of the Work otherwise complies with the conditions stated in + this License. + + 5. Submission of Contributions. + + Unless You explicitly state otherwise, any Contribution intentionally + submitted for inclusion in the Work by You to the Licensor shall be under the + terms and conditions of this License, without any additional terms or + conditions. Notwithstanding the above, nothing herein shall supersede or + modify the terms of any separate license agreement you may have executed with + Licensor regarding such Contributions. + + 6. Trademarks. + + This License does not grant permission to use the trade names, trademarks, + service marks, or product names of the Licensor, except as required for + reasonable and customary use in describing the origin of the Work and + reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. + + Unless required by applicable law or agreed to in writing, Licensor provides + the Work (and each Contributor provides its Contributions) on an "AS IS" + BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions of + TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR + PURPOSE. You are solely responsible for determining the appropriateness of + using or redistributing the Work and assume any risks associated with Your + exercise of permissions under this License. + + 8. Limitation of Liability. + + In no event and under no legal theory, whether in tort (including + negligence), contract, or otherwise, unless required by applicable law (such + as deliberate and grossly negligent acts) or agreed to in writing, shall any + Contributor be liable to You for damages, including any direct, indirect, + special, incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the Work + (including but not limited to damages for loss of goodwill, work stoppage, + computer failure or malfunction, or any and all other commercial damages or + losses), even if such Contributor has been advised of the possibility of such + damages. + + 9. Accepting Warranty or Additional Liability. + + While redistributing the Work or Derivative Works thereof, You may choose to + offer, and charge a fee for, acceptance of support, warranty, indemnity, or + other liability obligations and/or rights consistent with this License. + However, in accepting such obligations, You may act only on Your own behalf + and on Your sole responsibility, not on behalf of any other Contributor, and + only if You agree to indemnify, defend, and hold each Contributor harmless + for any liability incurred by, or claims asserted against, such Contributor + by reason of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work + + To apply the Apache License to your work, attach the following boilerplate + notice with the fields enclosed by brackets "[]" replaced with your own + identifying information. (Don't include the brackets!) The text should be + enclosed in the appropriate comment syntax for the file format. We also + recommend that a file or class name and description of purpose be included on + the same "printed page" as the copyright notice for easier identification within + third-party archives. + + NASA Docket No. GSC-15,354-1, and identified as "GEOS-5 GCM Modeling Software” + + “Copyright © 2008 United States Government as represented by the Administrator + of the National Aeronautics and Space Administration. All Rights Reserved.” + + Licensed under the Apache License, Version 2.0 (the "License"); you may not use + this file except in compliance with the License. You may obtain a copy of the + License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software distributed + under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR + CONDITIONS OF ANY KIND, either express or implied. See the License for the + specific language governing permissions and limitations under + the License. + + + NASA OPEN SOURCE SOFTWARE AGREEMENT + + NASA OPEN SOURCE AGREEMENT VERSION 1.3 + + THIS OPEN SOURCE AGREEMENT ("AGREEMENT") DEFINES THE RIGHTS OF USE, + REPRODUCTION, DISTRIBUTION, MODIFICATION AND REDISTRIBUTION OF CERTAIN + COMPUTER SOFTWARE ORIGINALLY RELEASED BY THE UNITED STATES GOVERNMENT AS + REPRESENTED BY THE GOVERNMENT AGENCY LISTED BELOW ("GOVERNMENT AGENCY"). + THE UNITED STATES GOVERNMENT, AS REPRESENTED BY GOVERNMENT AGENCY, IS AN + INTENDED THIRD-PARTY BENEFICIARY OF ALL SUBSEQUENT DISTRIBUTIONS OR + REDISTRIBUTIONS OF THE SUBJECT SOFTWARE. ANYONE WHO USES, REPRODUCES, + DISTRIBUTES, MODIFIES OR REDISTRIBUTES THE SUBJECT SOFTWARE, AS DEFINED + HEREIN, OR ANY PART THEREOF, IS, BY THAT ACTION, ACCEPTING IN FULL THE + RESPONSIBILITIES AND OBLIGATIONS CONTAINED IN THIS AGREEMENT. + + Government Agency: National Aeronautics and Space Administration + Government Agency Original Software Designation: GSC-15354-1 + Government Agency Original Software Title: GEOS-5 GCM Modeling Software + User Registration Requested. Please Visit http://opensource.gsfc.nasa.gov + Government Agency Point of Contact for Original Software: + Dale Hithon, SRA Assistant, (301) 286-2691 + + 1. DEFINITIONS + + A. "Contributor" means Government Agency, as the developer of the + Original Software, and any entity that makes a Modification. + + B. "Covered Patents" mean patent claims licensable by a Contributor + that are necessarily infringed by the use or sale of its Modification + alone or when combined with the Subject Software. + + C. "Display" means the showing of a copy of the Subject Software, + either directly or by means of an image, or any other device. + + D. "Distribution" means conveyance or transfer of the Subject Software, + regardless of means, to another. + + E. "Larger Work" means computer software that combines Subject + Software, or portions thereof, with software separate from the Subject + Software that is not governed by the terms of this Agreement. + + F. "Modification" means any alteration of, including addition to + or deletion from, the substance or structure of either the Original + Software or Subject Software, and includes derivative works, as that + term is defined in the Copyright Statute, 17 USC 101. However, the act + of including Subject Software as part of a Larger Work does not in and + of itself constitute a Modification. + + G. "Original Software" means the computer software first released under + this Agreement by Government Agency with Government Agency designation + GSC-15354-1 and entitled GEOS-5 GCM Modeling Software, including source + code, object code and accompanying documentation, if any. + + H. "Recipient" means anyone who acquires the Subject Software under + this Agreement, including all Contributors. + + I. "Redistribution" means Distribution of the Subject Software after a + Modification has been made. + + J. "Reproduction" means the making of a counterpart, image or copy of + the Subject Software. + + K. "Sale" means the exchange of the Subject Software for money or + equivalent value. + + L. "Subject Software" means the Original Software, Modifications, or + any respective parts thereof. + + M. "Use" means the application or employment of the Subject Software + for any purpose. + + + + 2. GRANT OF RIGHTS + + A. Under Non-Patent Rights: Subject to the terms and conditions of this + Agreement, each Contributor, with respect to its own contribution to + the Subject Software, hereby grants to each Recipient a non-exclusive, + world-wide, royalty-free license to engage in the following activities + pertaining to the Subject Software: + + 1. Use + 2. Distribution + 3. Reproduction + 4. Modification + 5. Redistribution + 6. Display + + B. Under Patent Rights: Subject to the terms and conditions of this + Agreement, each Contributor, with respect to its own contribution to + the Subject Software, hereby grants to each Recipient under Covered + Patents a non-exclusive, world-wide, royalty-free license to engage in + the following activities pertaining to the Subject Software: + + 1. Use + 2. Distribution + 3. Reproduction + 4. Sale + 5. Offer for Sale + + C. The rights granted under Paragraph B. also apply to the combination + of a Contributor's Modification and the Subject Software if, at the + time the Modification is added by the Contributor, the addition of + such Modification causes the combination to be covered by the Covered + Patents. It does not apply to any other combinations that include a + Modification. + + D. The rights granted in Paragraphs A. and B. allow the Recipient to + sublicense those same rights. Such sublicense must be under the same + terms and conditions of this Agreement. + + + 3. OBLIGATIONS OF RECIPIENT + + A. Distribution or Redistribution of the Subject Software must be made + under this Agreement except for additions covered under paragraph 3H. + + 1. Whenever a Recipient distributes or redistributes the Subject + Software, a copy of this Agreement must be included with each copy of + the Subject Software; and + + 2. If Recipient distributes or redistributes the Subject Software in + any form other than source code, Recipient must also make the source + code freely available, and must provide with each copy of the Subject + Software information on how to obtain the source code in a reasonable + manner on or through a medium customarily used for software exchange. + + B. Each Recipient must ensure that the following copyright notice + appears prominently in the Subject Software: + + Copyright © 2003-2018 United States Government as represented by the + Administrator of the National Aeronautics and Space Administration. All + Rights Reserved. + + C. Each Contributor must characterize its alteration of the Subject + Software as a Modification and must identify itself as the originator + of its Modification in a manner that reasonably allows subsequent + Recipients to identify the originator of the Modification. In + fulfillment of these requirements, Contributor must include a file + (e.g., a change log file) that describes the alterations made and + the date of the alterations, identifies Contributor as originator of + the alterations, and consents to characterization of the alterations + as a Modification, for example, by including a statement that the + Modification is derived, directly or indirectly, from Original Software + provided by Government Agency. Once consent is granted, it may not + thereafter be revoked. + + D. A Contributor may add its own copyright notice to the Subject + Software. Once a copyright notice has been added to the Subject + Software, a Recipient may not remove it without the express permission + of the Contributor who added the notice. + + E. A Recipient may not make any representation in the Subject Software + or in any promotional, advertising or other material that may be + construed as an endorsement by Government Agency or by any prior + Recipient of any product or service provided by Recipient, or that may + seek to obtain commercial advantage by the fact of Government Agency's + or a prior Recipient's participation in this Agreement. + + F. In an effort to track usage and maintain accurate records of + the Subject Software, each Recipient, upon receipt of the Subject + Software, is requested to register with Government Agency by visiting + the following website: http://opensource.gsfc.nasa.gov. Recipient's + name and personal information shall be used for statistical purposes + only. Once a Recipient makes a Modification available, it is requested + that the Recipient inform Government Agency at the web site provided + above how to access the Modification. + + G. Each Contributor represents that its Modification is believed to + be Contributor's original creation and does not violate any existing + agreements, regulations, statutes or rules, and further that Contributor + has sufficient rights to grant the rights conveyed by this Agreement. + + H. A Recipient may choose to offer, and to charge a fee for, warranty, + support, indemnity and/or liability obligations to one or more other + Recipients of the Subject Software. A Recipient may do so, however, + only on its own behalf and not on behalf of Government Agency or any + other Recipient. Such a Recipient must make it absolutely clear that + any such warranty, support, indemnity and/or liability obligation is + offered by that Recipient alone. Further, such Recipient agrees to + indemnify Government Agency and every other Recipient for any liability + incurred by them as a result of warranty, support, indemnity and/or + liability offered by such Recipient. + + I. A Recipient may create a Larger Work by combining Subject Software + with separate software not governed by the terms of this agreement + and distribute the Larger Work as a single product. In such case, the + Recipient must make sure Subject Software, or portions thereof, included + in the Larger Work is subject to this Agreement. + + J. Notwithstanding any provisions contained herein, Recipient is hereby + put on notice that export of any goods or technical data from the United + States may require some form of export license from the U.S. Government. + Failure to obtain necessary export licenses may result in criminal + liability under U.S. laws. Government Agency neither represents that a + license shall not be required nor that, if required, it shall be issued. + Nothing granted herein provides any such export license. + + 4. DISCLAIMER OF WARRANTIES AND LIABILITIES; WAIVER AND INDEMNIFICATION + + A. No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT + ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, + INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT + SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM + INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR FREE, + OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE + SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN + ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS, + RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS + RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY + DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, + IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT "AS IS." + + B. Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL + CLAIMS AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND + SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT'S USE + OF THE SUBJECT SOFTWARE RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, + EXPENSES OR LOSSES ARISING FROM SUCH USE, INCLUDING ANY DAMAGES FROM + PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT'S USE OF THE SUBJECT + SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE UNITED STATES + GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR + RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT'S SOLE REMEDY FOR + ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS + AGREEMENT. + + 5. GENERAL TERMS + + A. Termination: This Agreement and the rights granted hereunder will + terminate automatically if a Recipient fails to comply with these terms + and conditions, and fails to cure such noncompliance within thirty + (30) days of becoming aware of such noncompliance. Upon termination, + a Recipient agrees to immediately cease use and distribution of the + Subject Software. All sublicenses to the Subject Software properly + granted by the breaching Recipient shall survive any such termination of + this Agreement. + + B. Severability: If any provision of this Agreement is invalid or + unenforceable under applicable law, it shall not affect the validity or + enforceability of the remainder of the terms of this Agreement. + + C. Applicable Law: This Agreement shall be subject to United States + federal law only for all purposes, including, but not limited to, + determining the validity of this Agreement, the meaning of its + provisions and the rights, obligations and remedies of the parties. + + D. Entire Understanding: This Agreement constitutes the entire + understanding and agreement of the parties relating to release of the + Subject Software and may not be superseded, modified or amended except + by further written agreement duly executed by the parties. + + E. Binding Authority: By accepting and using the Subject Software under + this Agreement, a Recipient affirms its authority to bind the Recipient + to all terms and conditions of this Agreement and that that Recipient + hereby agrees to all terms and conditions herein. + + F. Point of Contact: Any Recipient contact with Government Agency is to + be directed to the designated representative as follows: Dale Hithon, + SRA Assistant, (301) 286-2691. + + SMVGEAR chemical solver (used in GEOS-Chem v10-01 and prior versions): - +----------------------------------------------------------------------------- + ********************************************************************* ************ WRITTEN BY MARK JACOBSON (1993) ************ *** (C) COPYRIGHT, 1993 BY MARK Z. JACOBSON *** *** U.S. COPYRIGHT OFFICE REGISTRATION NO. TXu 670-279 *** *** (650) 723-6836 *** ********************************************************************* - - -Licenses for packages used by HEMCO: -============================================================================== - -Modular Earth Submodel System (MESSy) tools: - - https://www.messy-interface.org/current/messy_licence.html From 3c2274767072b6099f9c3588fe09b3cb1a0d5d5a Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 12 Jul 2023 16:41:00 -0400 Subject: [PATCH 29/54] Restore edits in AUTHORS.txt that were clobbered Some of the prior edits in the AUTHORS.txt file have been clobbered. We have restored these edits. Signed-off-by: Bob Yantosca --- AUTHORS.txt | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/AUTHORS.txt b/AUTHORS.txt index bb4eebd22..6bb5146eb 100644 --- a/AUTHORS.txt +++ b/AUTHORS.txt @@ -42,6 +42,7 @@ CAROUGE, Claire CARTER, Therese (Tess) CAZORLA, Maria CHALIYAKUNNEL, Sreelekha +CHAN MILLER, Christopher CHEN, Han CHEN, Jing CHEN, Long @@ -85,7 +86,7 @@ FISCHER, Emily FISHER, Jenny FITE, Charley FLEMING, Eric -FLO-GAYA, Judit +FLO GAYA, Judit FORD, Bonne FRANCIS, Timmy FREESE, Lyssa @@ -130,8 +131,8 @@ JISKRA, Martin JOHNSON, Matthew JONES, Dylan JUNG, Jaegun -KASIBHATLA, -KAY, Rynda Hudman +KASIBHATLA, Prasad +HUDMAN KAY, Rynda KELLER, Christoph KELP, Makoto KIKUCHI, Tetsuro @@ -151,7 +152,7 @@ LAPINA, Kateryna LARSON, Kelsey LARY, David LATIMER, Robyn -LE, Philippe Sager +LE SAGER, Philippe LEE, Chulkyu LEE, Colin LEE, Meemong @@ -184,7 +185,7 @@ LONG, Mike LU, Xiao LUNDGREN, Lizzie LUO, Gan -MAASAKKERS, +MAASAKKERS, J. D. (Bram) MACINTYRE, Helen MACKENZIE, Dave MAHIEU, Emmanuel @@ -202,12 +203,11 @@ MENG, Jun MESKHIDZE, Nicholas MIATSELSKAYA, Natallia MICKLEY, Loretta -MILLER, Christopher Chan MILLET, Dylan MING, Kai MOCH, Jonathan MOORE, Neil -MOORING, Tood +MOORING, Todd MORENA, Jessica MORIN, Gabriel MORRIS, Eleanor @@ -232,7 +232,7 @@ PARK, Rokjin PARRINGTON, Mark PAULOT, Fabien PHILIP, Sajeev -PICKETT, Christopher-Heaps +PICKETT-HEAPS, Christopher PIERCE, Jeff PORTER, Will POUND, Ryan @@ -268,8 +268,8 @@ SHEN, Lu SHERWEN, Tomas SHUTTER, Joshua SILVA, Sam -SMITH, Nicole-Downey -LAERKE, Anne Soerensen +SMITH-DOWNEY, Nicole +SOERENSEN, Anne Laerke SOFEN, Eric SONG, Shaojie SONG, Yu @@ -305,10 +305,10 @@ TRUJILLO, Corey TUCCELLA, Paolo TURNER, Alexander TURQUETY, Solene -TZOMPA, Zitely-Sosa +TZOMPA-SOSA, Zitely UNGER, Nadine -VAL, Maria-Martin -VAN, Aaron Donkelaar +VAL MARTIN, Maria +VAN DONKELAAR, Aaron VAROTSOS, Kostas VINKEN, Geert VITT, Francis @@ -334,7 +334,6 @@ WIEDINMYER, Christine WILD, Oliver WOHLTMANN, Ingo WU, Shiliang -WU, Shiliang XIAO, Yaping XU, Junwei YAN, Yingying From dab9af27adbce49c9c0c738f3a73445057b06b20 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 13 Jul 2023 14:07:24 -0400 Subject: [PATCH 30/54] GEOS-Chem submodule update: Add several minor bug fixes Bug fixes include: 1. Fix GCClassic run directory runScriptSamples symbolic link 2. Fix bug in state_chm_mod that pritned line of equals signs to log from every core 3. Rename GCHP mid-run restart files in run scripts even if run crashes Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 0f3097d2c..7164eabd4 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 0f3097d2c99852b1668c2be3e7786aaa19f11a9a +Subproject commit 7164eabd4f5fd138c2b28df4a8da9643a2e6d881 From dbd28067d6201c898e8950f700cbb21df443c4bc Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 13 Jul 2023 14:17:49 -0400 Subject: [PATCH 31/54] GEOS-Chem submodule update: Update license and authors for 14.2.0 Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 7164eabd4..9aa18fdc8 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 7164eabd4f5fd138c2b28df4a8da9643a2e6d881 +Subproject commit 9aa18fdc89f782c535a711638812d30dea174eca From adab78265b37bc74f18b5048022d47024ba4dd9e Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 13 Jul 2023 14:36:28 -0400 Subject: [PATCH 32/54] HEMCO submodule update: Add minor bug fixes Fixes include: 1. Print HEMCO verbose status and volcano extension on root thread only 2. Change GEOS-IT meteorology constants year from 2011 to 2018 Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/HEMCO_GridComp/HEMCO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/HEMCO_GridComp/HEMCO b/src/GCHP_GridComp/HEMCO_GridComp/HEMCO index faaddbbb2..1ecfc19e8 160000 --- a/src/GCHP_GridComp/HEMCO_GridComp/HEMCO +++ b/src/GCHP_GridComp/HEMCO_GridComp/HEMCO @@ -1 +1 @@ -Subproject commit faaddbbb2b62c79028ed6b60cb2ac8575d78419f +Subproject commit 1ecfc19e8e7382912f469a5511af7e3012d2fdd8 From 9fc647eb2b3d8e354985775d34ff94727baa920c Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Mon, 24 Jul 2023 11:21:51 -0400 Subject: [PATCH 33/54] HEMCO submodule update: Add fix for volcano extension error Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/HEMCO_GridComp/HEMCO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/HEMCO_GridComp/HEMCO b/src/GCHP_GridComp/HEMCO_GridComp/HEMCO index 1ecfc19e8..4b65f1c9b 160000 --- a/src/GCHP_GridComp/HEMCO_GridComp/HEMCO +++ b/src/GCHP_GridComp/HEMCO_GridComp/HEMCO @@ -1 +1 @@ -Subproject commit 1ecfc19e8e7382912f469a5511af7e3012d2fdd8 +Subproject commit 4b65f1c9b18e6d85886c2c384d15627dc545d443 From 33dc33ae51d231c1495aa6cb18a7238ab39a5e32 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Mon, 24 Jul 2023 13:22:57 -0400 Subject: [PATCH 34/54] GEOS-Chem submodule update: Disable SpeciesConcMND diagnostic output for benchmark simulations Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 9aa18fdc8..222701f06 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 9aa18fdc89f782c535a711638812d30dea174eca +Subproject commit 222701f0666a95c9e70817d0eefa6bd08178d08e From a0c95291f1d9b98f928fb7744b8760e5063f496d Mon Sep 17 00:00:00 2001 From: Yidan Tang Date: Fri, 28 Jul 2023 12:24:54 -0500 Subject: [PATCH 35/54] Updated download comman in quick-start.rst docs/source/getting-started/quick-start.rst - Added '--recurse-submodules' to initialize and update submodules when downloading Signed-off-by: Yidan Tang --- docs/source/getting-started/quick-start.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index a6721dce0..7684b445d 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -12,11 +12,11 @@ More detailed instructions on downloading, compiling, and running GCHP can be fo 1. Clone GCHP ------------- -Download the source code: +Download the source code. :literal:`--recurse-submodules` will automatically initialize and update all the submodules: .. code-block:: console - gcuser:~$ git clone https://github.com/geoschem/GCHP.git ~/GCHP + gcuser:~$ git clone --recurse-submodules https://github.com/geoschem/GCHP.git ~/GCHP gcuser:~$ cd ~/GCHP Upon download you will have the most recently released version. You can check what this is by printing the last commit in the git log and scanning the output for tag. From 1883ee7fbaf0c4844848907c4985f86dcd34e7b5 Mon Sep 17 00:00:00 2001 From: Yidan Tang Date: Fri, 28 Jul 2023 12:30:47 -0500 Subject: [PATCH 36/54] Added sphinx-autobuild to facilitate auto build docs/requirements.txt - Added sphinx-autobuild, which is compatible with the existing environment Signed-off-by: Yidan Tang --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index a9be1e6d6..9de1af00e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,6 +9,7 @@ # The following package versions have been proven to work together: # sphinx==3.5.4 +sphinx-autobuild==2021.3.14 sphinx_rtd_theme==0.5.2 sphinxcontrib-bibtex==2.2.0 recommonmark From 87df2fcaa86df53835c59019a9e2267a71fd2056 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Mon, 31 Jul 2023 15:04:47 -0400 Subject: [PATCH 37/54] GEOS-Chem submodule update: Add fixes for transport tracer simulation Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 222701f06..112c4b66d 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 222701f0666a95c9e70817d0eefa6bd08178d08e +Subproject commit 112c4b66d0eb69a095e4a620c1fae077aa0dce4a From c398accf362dcd327ba73743fe592e79c7ab3b20 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Mon, 31 Jul 2023 15:06:51 -0400 Subject: [PATCH 38/54] GEOS-Chem submodule update: Add fix for SALAAL+SO2 and SALCAL+SO2 reactions Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 112c4b66d..55a90492b 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 112c4b66d0eb69a095e4a620c1fae077aa0dce4a +Subproject commit 55a90492b21dce46ada1e7af6e7d498fcdd3e8c0 From 30e41d43e988bcd7b88a6ff1c7de2b4b534bb460 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Tue, 1 Aug 2023 09:50:30 -0400 Subject: [PATCH 39/54] GEOS-Chem submodule update: Remove double counting of IONO2 loss Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 55a90492b..1119204b1 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 55a90492b21dce46ada1e7af6e7d498fcdd3e8c0 +Subproject commit 1119204b1ed257a26c1ba5ac4289eff1c0ef0cf8 From cfc9186480142c7c783e18de1a3511f211798bb0 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Wed, 2 Aug 2023 12:34:16 -0400 Subject: [PATCH 40/54] GEOS-Chem submodule update: Restore IONO2 uptake on tropospheric sulfate aerosols Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 1119204b1..4499ea265 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 1119204b1ed257a26c1ba5ac4289eff1c0ef0cf8 +Subproject commit 4499ea2651c228414281a2eff0c5cc8ac963c7d0 From e4530fa662a671674ff8a00ce27bf718279d3f3e Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 10 Aug 2023 13:32:50 -0400 Subject: [PATCH 41/54] GEOS-Chem submodule updates: Revert sea salt alkalinity fix from 14.2.0-alpha.5 Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 4499ea265..a4a742a5a 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 4499ea2651c228414281a2eff0c5cc8ac963c7d0 +Subproject commit a4a742a5a256f89ae637acddd39a6f352c6bd3c3 From 52217dd2b5ac3a2798276024f04048f26d5c10a3 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 23 Aug 2023 14:48:08 -0400 Subject: [PATCH 42/54] geos-chem-shared-docs update: Add AUTHORS.txt, LICENSE.txt, README.md This commit informs the GCHP repository about the following commits that were pushed to the geos-chem-shared-docs submodule: 9a6f1d Added AUTHORS.txt, LICENSE.txt, and README.md Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index dd64465e4..49a6f1d0c 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit dd64465e4556228676fb2dba65c7fe7693dc0f28 +Subproject commit 49a6f1d0caab2a8f44a79c3029bfacaaa963ed5a From 747cf42afb466bcc4604e25c4beaffd836001379 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Wed, 23 Aug 2023 15:38:17 -0400 Subject: [PATCH 43/54] RTD doc update: Add info about reverting to a prior version docs/source/user-guide/downloading.rst docs/source/getting-started/quick-start.rst - Add a "tip" box with instructions on how to check out GEOS-Chem Classic code for a prior version (actually, to any tag). - Also add info about what --recurse-submodules does Signed-off-by: Bob Yantosca --- docs/source/getting-started/quick-start.rst | 222 +++++++++++++------- docs/source/user-guide/downloading.rst | 67 +++--- 2 files changed, 192 insertions(+), 97 deletions(-) diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst index 7684b445d..9c69008a4 100644 --- a/docs/source/getting-started/quick-start.rst +++ b/docs/source/getting-started/quick-start.rst @@ -1,18 +1,26 @@ +.. _quick-start: - +################ Quickstart Guide -================ - -This quickstart guide assumes your environment satisfies the requirements described in :ref:`System Requirements `. / -This means you should load a compute environment so that programs like :program:`cmake` and :program:`mpirun` -are available before continuing. If you do not have some of GCHP's software dependencies, -you can find instructions for installing GCHP's external dependencies in our `Spack instructions <../supplement/spack.html>`__. -More detailed instructions on downloading, compiling, and running GCHP can be found in the User Guide. - +################ + +This quickstart guide assumes your environment satisfies the +requirements described in :ref:`System Requirements +`. This means you should load a compute +environment so that programs like :program:`cmake` and +:program:`mpirun` are available before continuing. If you do not have +some of GCHP's software dependencies, you can find instructions for +installing GCHP's external dependencies in our `Spack instructions +<../supplement/spack.html>`__. More detailed instructions on +downloading, compiling, and running GCHP can be found in the User +Guide. + +============= 1. Clone GCHP -------------- +============= -Download the source code. :literal:`--recurse-submodules` will automatically initialize and update all the submodules: +Download the source code. The :literal:`--recurse-submodules` option +will automatically initialize and update all the submodules: .. code-block:: console @@ -25,114 +33,148 @@ Upon download you will have the most recently released version. You can check wh gcuser:~/GCHP$ git log -n 1 -You can stay with this version or checkout an earlier version by its tag name: - -.. code-block:: console - - gcuser:~/GCHP$ git checkout tags/13.3.4 +.. tip:: -You can see a list of all possible tables using the git tag command: + To use an older GCHP version (e.g. 14.0.0), follow + these additional steps: -.. code-block:: console + .. code-block:: console - gcuser:~/GCHP$ git tag + gcuser:~/GCHP$ git checkout tags/14.0.0 # Points HEAD to the tag "14.0.0" + gcuser:~/GCHP$ git branch version_14.0.0 # Creates a new branch at tag "14.0.0" + gcuser:~/GCHP$ git checkout version_14.0.0 # Checks out the version_14.0.0 branch + gcuser:~/GCHP$ git submodule update --init --recursive # Reverts submodules to the "14.0.0" tag -When you have the version you wish to use you must initialize and update all the submodules: + You can do this for any tag in the version history. For a list of + all tags, type: -.. code-block:: console + .. code-block:: console - gcuser:~/GCHP$ git submodule update --init --recursive + gcuser:~/GCHP$ git tag -Repeat this last step every time you switch to a new version of GCHP. + If you have any unsaved changes, make sure you commit those to a + branch prior to updating versions. +========================= 2. Create a run directory -------------------------- +========================= -Navigate to the :file:`run/` subdirectory. -To create a run directory, run :file:`./createRunDir.sh` and answer the prompts: +Navigate to the :file:`run/` subdirectory. +To create a run directory, run :file:`./createRunDir.sh` and answer +the prompts: .. code-block:: console gcuser:~/GCHP$ cd run/ gcuser:~/GCHP$ ./createRunDir.sh +======================= 3. Configure your build ------------------------ +======================= -Building GCHP will require 1.4G of storage space. You may build GCHP from within the run directory or from anywhere else on your system. Building from within the run directory is convenient because it keeps all build files in close proximity to where you will run GCHP. For this purpose the GCHP run directory includes a build directory called :file:`build/`. However, you can create a build directory elsewhere, such as within the GCHP source code. In this guide we will do both, starting with building from the source code. +Building GCHP will require 1.4G of storage space. You may build GCHP +from within the run directory or from anywhere else on your +system. Building from within the run directory is convenient because +it keeps all build files in close proximity to where you will run +GCHP. For this purpose the GCHP run directory includes a build +directory called :file:`build/`. However, you can create a build +directory elsewhere, such as within the GCHP source code. In this +guide we will do both, starting with building from the source code. .. code-block:: console gcuser:~/GCHP$ mkdir ~/GCHP/build gcuser:~/GCHP$ cd ~/GCHP/build -Initialize your build directory by running :program:`cmake`, passing it the path to your source code. +Initialize your build directory by running :program:`cmake`, passing it the path to your source code. Make sure you have loaded all libraries required for GCHP prior to this step. .. code-block:: console gcuser:~/GCHP/build$ cmake ~/GCHP -Now you can configure :ref:`build options `. +Now you can configure :ref:`build options `. These are persistent settings that are saved to your build directory. -A useful build option is :literal:`-DRUNDIR`. -This option lets you specify one or more run directories that GCHP is "installed" to, meaning where the executable is copied, when you do :command:`make install`. -Configure your build so it installs GCHP to the run directory you created in Step 2. +A useful build option is :literal:`-DRUNDIR`. +This option lets you specify one or more run directories that GCHP is +"installed" to, meaning where the executable is copied, when you do +:command:`make install`. Configure your build so it installs GCHP to +the run directory you created in Step 2. .. code-block:: console gcuser:~/GCHP/build$ cmake . -DRUNDIR="/path/to/your/run/directory" .. note:: - The :literal:`.` in the :program:`cmake` command above is important. It tells CMake that your current working directory (i.e., :literal:`.`) is your build directory. + The :literal:`.` in the :program:`cmake` command above is + important. It tells CMake that your current working directory + (i.e., :literal:`.`) is your build directory. -If you decide instead to build GCHP in your run directory you can do all of the above in one step. This makes use of the :literal:`CodeDir` symbolic link in the run directory: +If you decide instead to build GCHP in your run directory you can do +all of the above in one step. This makes use of the :literal:`CodeDir` +symbolic link in the run directory: .. code-block:: console gcuser:/path/to/your/run/directory/$ cd build gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=.. -GEOS-Chem has a number of optional compiler flags you can add here. For example, to compile with RRTMG: +GEOS-Chem has a number of optional compiler flags you can add +here. For example, to compile with RRTMG: + +.. code-block:: console gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=.. -DRRTMG=y -A useful compiler option is to build in debug mode. Doing this is a good idea if you encountered a segmentation fault in a previous run and need more information about where the error happened and why. +A useful compiler option is to build in debug mode. Doing this is a +good idea if you encountered a segmentation fault in a previous run +and need more information about where the error happened and why. + +.. code-block:: console gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=.. -DCMAKE_BUILD_TYPE=Debug See the GEOS-Chem documentation for more information on compiler flags. +====================== 4. Compile and install ----------------------- +====================== -Compiling GCHP takes about 20 minutes, but it can vary depending on your system, your compiler, and your compiler flags. To maximize build speed you should compile GCHP in parallel using as many cores as are available. Do this with the -j flag: +Compiling GCHP takes about 20 minutes, but it can vary depending on +your system, your compiler, and your compiler flags. To maximize build +speed you should compile GCHP in parallel using as many cores as are +available. Do this with the :literal:`-j` flag: .. code-block:: console gcuser:~/GCHP/build$ make -j -Upon successful compilation, install the compiled executable to your run directory (or directories): +Upon successful compilation, install the compiled executable to your +run directory (or directories): .. code-block:: console gcuser:~/GCHP/build$ make install -This copies :file:`bin/gchp` and supplemental files to your run directory. +This copies :file:`bin/gchp` and supplemental files to your run directory. .. note:: You can update build settings at any time: - + 1. Navigate to your build directory. - 2. Update your build settings with :program:`cmake` (only if they differ since your last execution of cmake) - 3. Recompile with :command:`make -j`. Note that the build system automatically figures out what (if any) files need to be recompiled. + 2. Update your build settings with :program:`cmake` (only if they + differ since your last execution of cmake) + 3. Recompile with :command:`make -j`. Note that the build system + automatically figures out what (if any) files need to be + recompiled. 4. Install the rebuilt executable with :command:`make install`. -If you do not install the executable to your run directory you can always get the executable from the directory :command:`build/bin`. - +If you do not install the executable to your run directory you can +always get the executable from the directory :command:`build/bin`. +=============================== 5. Configure your run directory -------------------------------- +=============================== Now, navigate to your run directory: @@ -140,9 +182,11 @@ Now, navigate to your run directory: $ cd path/to/your/run/directory -Commonly changed simulation settings, such as grid resolution, run duration, and number of cores, are set in :file:`setCommonRunSettings.sh`. -You should review this file as it explains most settings. -Note that :file:`setCommonRunSettings.sh` is actually a helper script that updates other configuration files. +Commonly changed simulation settings, such as grid resolution, run +duration, and number of cores, are set in +:file:`setCommonRunSettings.sh`. You should review this file as it +explains most settings. Note that :file:`setCommonRunSettings.sh` is +actually a helper script that updates other configuration files. You therefore need to run it to actually apply the settings: .. code-block:: console @@ -150,47 +194,79 @@ You therefore need to run it to actually apply the settings: $ vim setCommonRunSettings.sh # edit simulation settings here $ ./setCommonRunSettings.sh # applies the updated settings -Simulation start date is set in :file:`cap_restart`. -Run directories come with this file filled in based on date of the initial restart file in subdirectory :file:`Restarts`. -You can change the start date only if you have a restart file for the new date in :file:`Restarts`. -A symbolic link called :file:`gchp_restart.nc4` points to the restart file for the date in :file:`cap_restart` and the grid resolution in :file:`setCommonRunSettings.sh`. -You need to set this symbolic link before running: +Simulation start date is set in :file:`cap_restart`. Run directories +come with this file filled in based on date of the initial restart +file in subdirectory :file:`Restarts`. You can change the start date +only if you have a restart file for the new date in :file:`Restarts`. +A symbolic link called :file:`gchp_restart.nc4` points to the restart +file for the date in :file:`cap_restart` and the grid resolution in +:file:`setCommonRunSettings.sh`. You need to set this symbolic link +before running: .. code-block:: console $ ./setRestartLink.sh # sets symbolic link to target file in Restarts -If you used an environment file to load libraries prior to building GCHP then you should load that file prior to running. A simple way to make sure you always use the correct combination of libraries is to set the GCHP environment symbolic link :file:`gchp.env` in the run directory: +If you used an environment file to load libraries prior to building +GCHP then you should load that file prior to running. A simple way to +make sure you always use the correct combination of libraries is to +set the GCHP environment symbolic link :file:`gchp.env` in the run +directory: .. code-block:: console $ ./setEnvironment.sh /path/to/env/file # sets symbolic link gchp.env $ source gchp.env # applies the environment settings - +=========== 6. Run GCHP ------------ +=========== -Running GCHP is slightly different depending on your MPI library (e.g., OpenMPI, Intel MPI, MVAPICH2, etc.) and scheduler (e.g., SLURM, LSF, etc.). -If you aren't familiar with running MPI programs on your system, see :ref:`Running GCHP ` in the user guide, or ask your system administrator. +Running GCHP is slightly different depending on your MPI library +(e.g., OpenMPI, Intel MPI, MVAPICH2, etc.) and scheduler (e.g., SLURM, +LSF, etc.). If you aren't familiar with running MPI programs on your +system, see :ref:`Running GCHP ` in the user guide, or +ask your system administrator. -Your MPI library and scheduler will have a command for launching MPI programs---it's usually something like :program:`mpirun`, :program:`mpiexec`, or :program:`srun`. -This is the command that you will use to launch the :program:`gchp` executable. -You'll have to refer to your system's documentation for specific instructions on running MPI programs, but generally it looks something like this: +Your MPI library and scheduler will have a command for launching MPI +programs---it's usually something like :program:`mpirun`, +:program:`mpiexec`, or :program:`srun`. This is the command that you +will use to launch the :program:`gchp` executable. You'll have to +refer to your system's documentation for specific instructions on +running MPI programs, but generally it looks something like this: .. code-block:: console - $ mpirun -np 6 ./gchp # example of running GCHP with 6 slots with OpenMPI + $ mpirun -np 6 ./gchp # example of running GCHP with 6 slots with OpenMPI -It's recommended you run GCHP as a batch job. -This means that you write a script (usually bash) that configures and runs your GCHP simulation, and then you submit that script to your local job scheduler (SLURM, LSF, etc.). -Example job scripts are provided in subdirectory :literal:`./runScriptSamples` in the run directory. -That folder also includes an example script for running GCHP from the command line. +It's recommended you run GCHP as a batch job. This means that you +write a script (usually bash) that configures and runs your GCHP +simulation, and then you submit that script to your local job +scheduler (SLURM, LSF, etc.). Example job scripts are provided in +subdirectory :literal:`./runScriptSamples` in the run directory. That +folder also includes an example script for running GCHP from the +command line. -Several steps beyond running GCHP are included in the example run scripts. These include loading the environment, updating commonly changed run settings, and setting the restart file based on start time and grid resolution. In addition, the output restart file is moved to the :file:`Restarts` subdirectory and renamed to include start date and grid resolution upon successful completion of the run. +Several steps beyond running GCHP are included in the example run +scripts. These include loading the environment, updating commonly +changed run settings, and setting the restart file based on start time +and grid resolution. In addition, the output restart file is moved to +the :file:`Restarts` subdirectory and renamed to include start date +and grid resolution upon successful completion of the run. .. note:: - File :file:`cap_restart` is over-written to contain the run end date upon successful completion of a GCHP run. This is done within GCHP and not by the run script. You can then easily submit a new GCHP run starting off where your last run left off. In addition, GCHP outputs a restart file to your run directory called :file:`gcchem_internal_checkpoint`. This file is moved to subdirectory :literal:`Restarts` and renamed to include the date and grid resolution. This is done by the run script and technically is optional. We recommend doing this since it is is good for archiving (restart files will contain date and grid res) and enables use of the :file:`./setRestartLink.sh` script to set the :file:`gchp_restart.nc4` symbolic link. - -Those are the basics of using GCHP! -See the user guide, step-by-step guides, and reference pages for more detailed instructions. + File :file:`cap_restart` is over-written to contain the run end + date upon successful completion of a GCHP run. This is done within + GCHP and not by the run script. You can then easily submit a new + GCHP run starting off where your last run left off. In addition, + GCHP outputs a restart file to your run directory called + :file:`gcchem_internal_checkpoint`. This file is moved to + subdirectory :literal:`Restarts` and renamed to include the + date and grid resolution. This is done by the run script and + technically is optional. We recommend doing this since it is + is good for archiving (restart files will contain date and + grid res) and enables use of the :file:`./setRestartLink.sh` + script to set the :file:`gchp_restart.nc4` symbolic link. + +Those are the basics of using GCHP! See the user guide, step-by-step +guides, and reference pages for more detailed instructions. diff --git a/docs/source/user-guide/downloading.rst b/docs/source/user-guide/downloading.rst index b58edc107..f3d3c95ad 100644 --- a/docs/source/user-guide/downloading.rst +++ b/docs/source/user-guide/downloading.rst @@ -1,48 +1,67 @@ .. _downloading_gchp: +################## Download the model -================== +################## -The GCHP source code is hosted at https://github.com/geoschem/GCHP. Clone +The GCHP source code is hosted at https://github.com/geoschem/GCHP. Clone the repository: .. code-block:: console - gcuser:~$ git clone https://github.com/geoschem/GCHP.git GCHP + gcuser:~$ git clone --recurse-submodules https://github.com/geoschem/GCHP.git GCHP -The GCHP repository has submodules (other repositories that are -nested inside the GCHP repository) that aren't automatically retrieved when -you do :command:`git clone`. To finish retrieving the GCHP source code, -initialize and update the submodules: +The GCHP repository has submodules (other repositories that are +nested inside the GCHP repository) that aren't automatically retrieved +when you do :command:`git clone`. The :literal:`--recurse-submodules` +option tells Git to finish retrieving the source code for each +submodule. It will also initialize and update each submodule's source +code to the proper place in its version history. -.. code-block:: console +By default, the source code will be on the :literal:`main` branch +which is always the last official release of GCHP. Checking out the +official release is recommended because it is a +scientifically-validated version of the code and is easily +citable. You can find the list of past and present GCHP releases `here +`_. - gcuser:~$ cd GCHP - gcuser:~/GCHP$ git submodule update --init --recursive +.. tip:: + To use an older GCHP version (e.g. 14.0.0), follow + these additional steps: -By default, the source code will be on the :literal:`main` branch which is always the last offocial release of GCHP. -Checking out the official release is recommended because it is a scientifically-validated version of the -code and is easily citable. You can find the list -of past and present GCHP releases `here `_. -Checkout the release that you want to work with, and update the submodules: + .. code-block:: console -.. code-block:: console + gcuser:~/GCHP$ git checkout tags/14.0.0 # Points HEAD to the tag "14.0.0" + gcuser:~/GCHP$ git branch version_14.0.0 # Creates a new branch at tag "14.0.0" + gcuser:~/GCHP$ git checkout version_14.0.0 # Checks out the version_14.0.0 branch + gcuser:~/GCHP$ git submodule update --init --recursive # Reverts submodules to the "14.0.0" tag + + You can do this for any tag in the version history. For a list of + all tags, type: + + .. code-block:: console - gcuser:~/GCHP$ git checkout 13.3.4 - gcuser:~/GCHP$ git submodule update --init --recursive + gcuser:~/GCHP$ git tag --------------------------------------------------------------------------------------- + If you have any unsaved changes, make sure you commit those to a + branch prior to updating versions. -Before continuing, it is worth checking that the source code was retrieved correctly. -Run :command:`git status` to check that there are no differences: +Before continuing, it is worth checking that the source code was +retrieved correctly. Run :command:`git status` to check that there are +no differences: .. code-block:: console gcuser:~/GCHP$ git status - HEAD detached at 13.3.4 + HEAD detached at 14.0.0 nothing to commit, working tree clean gcuser:~/GCHP$ -The output of :command:`git status` should confirm your GCHP version and -that there are no modifications (nothing to commit, and a clean working tree). It also says that you are are in detached HEAD state, meaning you are not in a GCHP git software branch. This is true for all submodules in the model as well. If you wish to use version control to track your changes you must checkout a new branch to work on in the directory you will be developing. +The output of :command:`git status` should confirm your GCHP version +and that there are no modifications (nothing to commit, and a clean +working tree). It also says that you are are in detached HEAD state, +meaning you are not in a GCHP git software branch. This is true for +all submodules in the model as well. If you wish to use version +control to track your changes you must checkout a new branch to work +on in the directory you will be developing. From 07f79c3304ad6619d1eb97de213e5364ccb626f8 Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Wed, 30 Aug 2023 16:43:05 -0400 Subject: [PATCH 44/54] Add warning about outputting area-dependent variables on custom grids Signed-off-by: Lizzie Lundgren --- docs/source/user-guide/config-files/HISTORY_rc.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/source/user-guide/config-files/HISTORY_rc.rst b/docs/source/user-guide/config-files/HISTORY_rc.rst index aaaee0e83..b13c5719a 100644 --- a/docs/source/user-guide/config-files/HISTORY_rc.rst +++ b/docs/source/user-guide/config-files/HISTORY_rc.rst @@ -40,13 +40,21 @@ and :ref:`\ ` sections are given belo Defining Grid Labels -------------------- -You can specify custom grids for you output. For example, a regional 0.05°x0.05° grid covering +You can specify custom grids for your output. For example, a regional 0.05°x0.05° grid covering North America. This way your collections are regridded online. There are two advantages to doing -this +this: #. It eliminates the need to regrid your simulation data in a post-processing step. #. It saves disk space if you are interested in regional output. +Beware that outputting data on a different grid assumes the data is independent of horizontal +cell size. The regridding routines are area-conserving and thus regridded values will only +make sense for data that is area-independent. Examples of data units that are area-independent +are mixing ratios (e.g. kg/kg or mol/mol) and emissions rates per area (e.g. kg/m2/s). Examples +of data units that are NOT area-independent are kg/s and m2, or any other unit that implicitly is +per grid cell area. This sort of unit is most common in the meteorology diagnostics, such as +Met_AREAM2 and Met_AD. The values of these arrays will be incorrect in non-native grid output. + You can define as many grids as you want. A collection can define :code:`grid_label` to select a custom grid. If a collection does not define :code:`grid_label` the simulation's grid is assumed. From 88703918b8b4de84701654e1b450547a975581f9 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 31 Aug 2023 16:39:08 -0400 Subject: [PATCH 45/54] GEOS-Chem submod update: Merge PR #1920 (Hotfix for dry-runs) This commit informs the GCHP superproject about the following commits that were pushed to the GitHub geoschem/geos-chem repository: 216985a5d Merge PR #1920 (Hotfix: Exit INIT_PHOTOLYSIS before SET_AER for dry runs) This fixes an issue with GEOS-Chem Classic dry-run simulations by making sure we exit the Init_Photolysis routine before doing any computations. Signed-off-by: Bob Yantosca --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index a4a742a5a..216985a5d 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit a4a742a5a256f89ae637acddd39a6f352c6bd3c3 +Subproject commit 216985a5d32d936376ebe9a7258229113bb04c12 From 979bd424dca248628f934b6ab931f10a6c7ef6fc Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Wed, 6 Sep 2023 11:05:52 -0400 Subject: [PATCH 46/54] GEOS-Chem submodule update: Merge PR #1933 (sea salt alkalinity fix) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 216985a5d..87b919af9 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 216985a5d32d936376ebe9a7258229113bb04c12 +Subproject commit 87b919af9c6138f96e7ed4c3780579d2a33dec4d From 5938a5f1a541a2bb29b939b815eeb03fbc698c25 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Thu, 7 Sep 2023 10:20:29 -0400 Subject: [PATCH 47/54] RTD update: Edit wording in offline vs. online emissions This commit informs the GCHP repository about the following commit that was pushed to the geos-chem-shared-docs repository: dcf759b Update online vs. offline emissions section for better accuracy Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index 49a6f1d0c..dcf759b94 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit 49a6f1d0caab2a8f44a79c3029bfacaaa963ed5a +Subproject commit dcf759b94de42d56ed98d28b092f864002c7d757 From 25c4389e082c6fbb6681d2e12851a778fcb06844 Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Fri, 8 Sep 2023 12:55:03 -0400 Subject: [PATCH 48/54] Update instructions for building ESMF Signed-off-by: Lizzie Lundgren --- docs/source/getting-started/requirements.rst | 110 ++++++++++++++----- 1 file changed, 84 insertions(+), 26 deletions(-) diff --git a/docs/source/getting-started/requirements.rst b/docs/source/getting-started/requirements.rst index 744f4630b..3026ea41b 100644 --- a/docs/source/getting-started/requirements.rst +++ b/docs/source/getting-started/requirements.rst @@ -38,28 +38,57 @@ Installing ESMF If you have all of the needed libraries except ESMF then you can download and build ESMF yourself. The ESMF git repository is available to clone from `github.com/esmf-org/esmf `_. Use :code:`git tag` to browse versions available and then :code:`git checkout tags/tag_name` to checkout the version. -Once downloaded, browse file :file:`ESMF/README` for information about build requirements. -ESMF requires that you define environment variables :file:`ESMF_COMPILER`, :file:`ESMF_COMM`, and :file:`ESMF_DIR` (path to clone), and also export environment variables :file:`CC`, :file:`CXX`, :file:`FC`, and :file:`MPI_ROOT`. +.. code-block:: console + + git clone https://github.com/esmf-org/esmf ESMF + cd ESMF + git tag + git checkout tags/v8.4.1 + +If you have previously downloaded ESMF you can use your same clone to checkout and build a new ESMF version. Use the same steps as above minus the first step of cloning. + +Once you have downloaded ESMF and checked out the version you would like to build, browse the file +:file:`ESMF/README.md` to familiarize yourself with ESMF documentation. You do not need to visit the documentation +for doing a basic build of ESMF following this tutorial. However, if you are interested in learning more about +ESMF and its options then you can use this guide. + +ESMF requires that you define environment variables :file:`ESMF_COMPILER`, :file:`ESMF_COMM`, and :file:`ESMF_DIR`, +and also export environment variables :file:`CC`, :file:`CXX`, :file:`FC`, and :file:`MPI_ROOT`. Set up an environment file that loads the needed libraries and also defines these environment variables. -Here is an example of what the variable exports might look line in your environment file: +If you already have a GEOS-Chem environment file set up then you can copy it or repurpose it by including +the environment variables needed for ESMF. Here is an example of what the library load and variable exports +might look line in your environment file. This example uses GNU compilers and OpenMPI, but there are notes in +the comments on how to use Intel instead. .. code-block:: console - export CC=gcc - export CXX=g++ - export FC=gfortran - export MPI_ROOT=${MPI_HOME} - export ESMF_COMPILER=gfortran - export ESMF_COMM=openmpi - export ESMF_DIR=/home/ESMF/ESMF_8_0_1 - -You can create multiple ESMF builds, for example if you want to try different compilers. To set yourself up to allow this also export environment variable :file:`ESMF_INSTALL_PREFIX` and define it as a subdirectory within :file:`ESMF_DIR`. For example: + module purge + module load gcc/10.2.0-fasrc01 # GNU compiler collection (C, C++, Fortran) + module load openmpi/4.1.0-fasrc01 # MPI + module load netcdf-c/4.8.0-fasrc01 # Netcdf-C + module load netcdf-fortran/4.5.3-fasrc01 # Netcdf-Fortran + module load cmake/3.25.2-fasrc01 # CMake + + export CC=gcc # C compiler (use icx for Intel) + export CXX=g++ # C++ compiler (se icx for Intel) + export FC=gfortran # Fortran compiler (use ifort for Intel) + export MPI_ROOT=${MPI_HOME} # Path to MPI library + export ESMF_COMPILER=gfortran # Fortran compiler (use intel for Intel) + export ESMF_COMM=openmpi # MPI (use intelmpi for IntelMPI) + export ESMF_DIR=/home/ESMF/ESMF # Path to ESMF repository within a generic directory called ESMF + +You can create multiple ESMF builds. This is useful if you want to use different libraries for the same +version of ESMF, or if you want to build different ESMF versions. To set yourself up to allow multiple builds +you should also export environment variable :file:`ESMF_INSTALL_PREFIX` and define it as a subdirectory +within :file:`ESMF_DIR`. Include details about that particular build to distinguish it from others. For example: .. code-block:: console - export ESMF_INSTALL_PREFIX=${ESMF_DIR}/INSTALL_gfortran10.2_openmpi4.1 + export ESMF_INSTALL_PREFIX=${ESMF_DIR}/INSTALL_ESMF8.4.1_gfortran10.2_openmpi4.1 -To prepare your environment file for use with GCHP as well simply add the following: +Using this install in GCHP will require setting :file:`ESMF_ROOT` to the install directory. Add the following +line to your ESMF environment file if you plan on repurposing it for use with GCHP. Otherwise remember to add +it to your GCHP environment file along with the assignment of :file:`ESMF_INSTALL_PREFIX`. .. code-block:: console @@ -69,12 +98,36 @@ Once you are ready to build execute the following commands: .. code-block:: console - $ source path_to/your/env/file + $ source path/to/your/env/file $ cd $ESMF_DIR - $ make &> compile.log + $ make -j &> compile.log Once compilation completes check the end of :file:`compile.log` to see if compilation was successful. -If it was a success then continue as follows: +You may run into known errors with compiling certain ESMF versions with GNU and Intel compilers. If you +run into a problem with GNU you can try adding this to your environment file, resourcing it, and then +rebuilding. + +.. code-block:: console + + # ESMF may not build with GCC without the following work-around + # for a type mismatch error (https://trac.macports.org/ticket/60954) + if [[ "x${ESMF_COMPILER}" == "xgfortran" ]]; then + export ESMF_F90COMPILEOPTS="-fallow-argument-mismatch -fallow-invalid-boz" + fi + +If you run into a problem with Intel compilers then try the following. + +.. code-block:: console + + # Make sure /usr/bin comes first in the search path, so that the build + # will find /usr/bin/gcc compiler, which ESMF uses for preprocessing. + # Also unset the ESMF_F90COMPILEOPTS variable, which is only needed for GNU. + if [[ "x${ESMF_COMPILER}" == "xintel" ]]; then + export PATH="/usr/bin:${PATH}" + unset ESMF_F90COMPILEOPTS + fi + +Once you have a successful run then install ESMF using this command: .. code-block:: console @@ -94,19 +147,24 @@ Archive your compile and install logs to that directory. Calling make builds ESMF and calling make install places the build into your install directory. In that folder the build files are placed within subdirectories such as bin and lib, among others. The install directory is not deleted when you clean ESMF source code with :code:`make distclean` in the top-level ESMF directory. -Therefore you can clean and rebuild ESMF with different combinations of libraries in advance of needing them to build and run GCHP. +Therefore you can clean and rebuild ESMF with different combinations of libraries and versions in advance of needing them to build and run GCHP. Just remember to clean the source code and source the environment file you intend to use prior to creating a new build. -You also must specify a different :code:`${ESMF_INSTALL_PREFIX}` for each unique build so as not to overwrite others. +Make sure you specify a different :code:`${ESMF_INSTALL_PREFIX}` for each unique build so as not to overwrite others. + +Below is a complete summary of build steps, including cleanup at the end and moving logs files and your environment +file to the install directory for archiving. This is a complete list of command line steps assuming you have a functional +environment file with correct install path and have checked out the version of ESMF you wish to build. .. code-block:: console -$ cd $ESMF_DIR -$ make distclean -$ source path_to_your_env_file_with_unique_ESMF_INSTALL_PREFIX -$ make &> compile.log -$ install $> install.log -$ mv compile.log $ESMF_INSTALL_PREFIX -$ mv install.log $ESMF_INSTALL_PREFIX + $ cd $ESMF_DIR + $ make distclean + $ source path/to/env/file/with/unique/ESMF_INSTALL_PREFIX + $ make &> compile.log + $ install $> install.log + $ mv compile.log $ESMF_INSTALL_PREFIX + $ mv install.log $ESMF_INSTALL_PREFIX + $ cp /path/to/your/env/file $ESMF_INSTALL_PREFIX .. _hardware_requirements: From d18cd00c9e4fb04e66a1e2893f23758f5ea53199 Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Fri, 8 Sep 2023 13:07:23 -0400 Subject: [PATCH 49/54] Link to supplemental guide on customizing simulations for research settings Signed-off-by: Lizzie Lundgren --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index def131afb..852d92fe7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -83,6 +83,7 @@ use Spack to install GCHP's dependencies if needed. supplement/stretched-grid.rst supplement/satellite-overpass.rst geos-chem-shared-docs/supplemental-guides/bashdatacatalog.rst + geos-chem-shared-docs/supplemental-guides/customize-guide.rst geos-chem-shared-docs/supplemental-guides/error-guide.rst geos-chem-shared-docs/supplemental-guides/debug-guide.rst geos-chem-shared-docs/supplemental-guides/species-guide.rst From c1c1062806b33db7dd16e52a3ff67c93478c591e Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Mon, 11 Sep 2023 18:14:52 -0400 Subject: [PATCH 50/54] GEOS-Chem submodule update: Merge PR #1952 (sea salt alkalinity hetchem fixes) Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/GEOSChem_GridComp/geos-chem | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem index 87b919af9..5218fe836 160000 --- a/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem +++ b/src/GCHP_GridComp/GEOSChem_GridComp/geos-chem @@ -1 +1 @@ -Subproject commit 87b919af9c6138f96e7ed4c3780579d2a33dec4d +Subproject commit 5218fe8366c2634b43f56f6f0f3e5e29267c2c36 From 4f0331ca48fb090e98f5ee2eade6d56cde2302d9 Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Fri, 29 Sep 2023 11:03:16 -0400 Subject: [PATCH 51/54] Updates to ExtData.rc section and minimum ESMF version Signed-off-by: Lizzie Lundgren --- docs/source/getting-started/requirements.rst | 2 +- .../user-guide/config-files/ExtData_rc.rst | 49 ++++++++++++------- 2 files changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/source/getting-started/requirements.rst b/docs/source/getting-started/requirements.rst index 3026ea41b..378c9046c 100644 --- a/docs/source/getting-started/requirements.rst +++ b/docs/source/getting-started/requirements.rst @@ -26,7 +26,7 @@ To build and run GCHP your compute :term:`environment` needs the following softw * HDF5 * NetCDF (with C, C++, and Fortran support) -* Earth System Modeling Framework (ESMF) version ≥ 8.1.0 +* Earth System Modeling Framework (ESMF) version 8.4.2 recommended. Problems with 8.1 and prior have been reported. Your system administrator should be able to tell you if this software is already available on your cluster, and if so, how to activate it. If it is not already available, they might be able to build it for you. diff --git a/docs/source/user-guide/config-files/ExtData_rc.rst b/docs/source/user-guide/config-files/ExtData_rc.rst index 0695333c3..9b54cce86 100644 --- a/docs/source/user-guide/config-files/ExtData_rc.rst +++ b/docs/source/user-guide/config-files/ExtData_rc.rst @@ -4,43 +4,54 @@ ExtData.rc :file:`ExtData.rc` contains input variable and file read information for GCHP. Explanatory information about the file is located at the top of the configuration file in all run directories. The file format is the same as that used in the GEOS model, and GMAO/NASA documentation for it can be found at the ExtData component page on the GEOS-5 wiki. +Note that this file will be retired in GCHP v15.0 when MAPL version 3 is integrated into GCHP. It will be replaced with a YAML format file with a +simplified and easier to understand interface. + +The ins and outs of :file:`ExtData.rc` can be hard to grasp, particular with regards to variable data +updating, time interpolation, and file read. Reach out on the GCHP GitHub Issues page if you need help. See also the GCHP ReadTheDocs page on enabling +ExtData prints for debugging. Enable ExtData debug prints is the best way to determine what MAPL is doing for file I/O per import. The following two parameters are set at the top of the file: Ext_AllowExtrat - Logical toggle to use data from nearest year available. This is set to true for GCHP. Note that GEOS-Chem Classic accomplishes the same effect but with more flexibility in :file:`HEMCO_Config.rc`. That functionality of :file:`HEMCO_Config.rc` is ignored in GCHP. - -DEBUG_LEVEL - Turns MAPL ExtData debug prints on/off. This is set to 0 in GCHP (off), but may be set to 1 to enable. Beware that turning on ExtData debug prints greatly slows down the model, and prints are only done from the root thread. Use this when debugging problems with input files. + Logical toggle to use data from nearest year available, including meteorology if files for the simulation year are not found. This is set to true for GCHP. Note that GEOS-Chem Classic accomplishes the same effect but with more flexibility in :file:`HEMCO_Config.rc`, and the entries of :file:`HEMCO_Config.rc` which do this are ignored in GCHP. -The rest of the file contains space-delimited lines, one for each variable imported to the model from an external file. -Columns are as follows in order as they appear left to right in the file: +The rest of the file contains whitespace-delimited lines. Each line describes one data variable imported to the model from an external file. +Columns are as follows in order from left to right: -Export Name - Name of imported met field (e.g. ALBD) or HEMCO emissions container name (e.g. GEIA_NH3_ANTH). +Name + Name of the field stored in the MAPL Imports container. This is independent of the name of the data field in the input file. For the case of entries that also appear in :file:`HEMCO_Config.rc` it is also the name of the HEMCO emissions container (left-most column in that file). For those fields it is used to match scaling and masking information in :file:`HEMCO_Config.rc` with file I/O information in :file:`ExtData.rc`. Units - Unit string nested within single quotes. '1' indicates there is no unit conversion from the native units in the netCDF file. + Unit string of the import. This entry is informational only. + Clim - Enter Y if the file is a 12 month climatology, otherwise enter N. If you specify it is a climatology ExtData the data can be on either one file or 12 files if they are templated appropriately with one per month. + Whether the data is climatology. Enter :file:`Y` if the data is a 12 month climatology, data year if the data is daily climatology (i.e. :file:`2019`), :file:`D` if the file is monthly day-of-week scale factors (7 values for each of 12 months), or :file:`N` for all other cases. If you specify monthly climatology then the data must be stored in either 1 or 12 files. + Conservative - Enter Y the data should be regridded in a mass conserving fashion through a tile file. :literal:`F;{VALUE}` can also be used for fractional regridding. Otherwise enter N to use the non-conervative bilinear regridding. + Method to regrid the input data to the simulation grid. Enter Y to use mass conserving regridding, :literal:`F;{VALUE}` for fractional regridding, or N to use non-conervative bilinear regridding. Refresh - Time Template Possible values include: + Time template for frequency of updating data. This tells MAPL when to look for new data values. There are several options for specifying refresh: - * -: The field will only be updated once the first time ExtData runs - * 0: Update the variable at every step. ExtData will do a linear interpolation to the current time using the available data. - * %y4-%m2-%h2T%h2:%n2:00: Set the recurring time to update the file. The file will be updated when the evaluated template changes. For example, a template in the form %y4-%m2-%d2T12:00:00 will cause the variable to be updated at the start of a new day (i.e. when the clock hits 2007-08-02T00:00:00 it will update the variable but the time it will use for reading and interpolation is 2007-08-02T12:00:00). + * :file:`-` : Update variable data only once. Use this if the data is constant in time. + * :file:`0` : Update variable data at every timestep using linear interpolation. For example, if the data is hourly then MAPL will linearly interpolate between the previous and next hour's data for every timestep. + * :file:`0:003000` (or other HHMMSS specification for hours, minutes, seconds) : Use specified time offset (i.e. 30 minutes in this example) for setting previous and next time, and interpolate every timestep between the two. This is useful if, for example, you have time-averaged hourly data and you want the previous and next times to update half-way between the hour. This format is used for meteorology fields that are interpolated every timestep, specifically temperature and surface pressure. + * :file:`F0:003000` (or other HHMMSS specification for hours, minutes, seconds) : Like the previous option except there is no time interpolation. This format is used for meteorology fields that are not time-interpolated, such as cloud fraction. + * :file:`%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Update variable data when time tokens change. Interpreting this entry gets a little tricky. The data will be updated when the time tokens change, not he hard-coded times. For example, a template in the form %y4-%m2-%d2T12:00:00 changes at the start of each day because that is when the evaluation of %y4-%m2-%d2 changes. While the variable will be updated at the start of a new day (i.e. at time 2019-01-02T00:00:00), the time used for reading and interpolation is 2007-08-02T12:00:00). + * :file:`F%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Like the previous option except that there is no time interpolation. Offset Factor - Factor the variable will be shifted by. Use none for no shifting. + Value the data will be shifted by upon read. Use :file:`none` for no shifting. Scale Factor - Factor the variable will be scaled by. Use none for no scaling. + Value the data will be scaled by upon read. Use :file:`none` for no scaling. External File Variable - The name of the variable in the netCDF data file, e.g. ALBEDO in met fields. + Name of the variable to read in the netCDF data file. External File Template - Path to the netCDF data file. If not using the data, specify :file:`/dev/null` to reduce processing time. If there are no tokens in the template name ExtData will assume that all the data is on one file. Note that if the data on file is at a different resolution that the application grid, the underlying I/O library ExtData uses will regrid the data to the application grid. + Path to the netCDF data file, including time tokens as needed (%y4 for year, %m2 for month, %d2 for day, %h2 for hour, %n2 for minutes). If there are no time tokens in the template name then ExtData will assume that all the data is on one file. If you wish to ignore an entry in :file:`ExtData.rc` (i.e. not read then data) then put :file:`/dev/null` to reduce processing time. + +Reference Time (optional) + Reference time and frequency of data. This optional entry is useful if you have data frequency that is offset from midnight. For example, 3-hourly data available for times 1:30, 4:30, 7:30, etc. The reference time could be specified as :file:`2000-01-01T01:30:00P03:00`. The first part (before :file:`P`) is the reference date (must be on or before your simulation start), and the second part (after :file:`P`) is the period of data availability (in this case 3 hours). This can be used in combination with the file template containing hours and minutes. It tells MAPL to only read the file at times that are regular 3 hr intervals from the reference date and time. Not including this would cause MAPL to read the file every minute if the file template contains the :file:`n2` time token. From 386c09f7cdbffb9a366be44aac3639154a0f3495 Mon Sep 17 00:00:00 2001 From: Lizzie Lundgren Date: Fri, 29 Sep 2023 12:15:53 -0400 Subject: [PATCH 52/54] Additional update to ExtData.rc ReadTheDocs pag Signed-off-by: Lizzie Lundgren --- .../user-guide/config-files/ExtData_rc.rst | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/source/user-guide/config-files/ExtData_rc.rst b/docs/source/user-guide/config-files/ExtData_rc.rst index 9b54cce86..88f9bbaca 100644 --- a/docs/source/user-guide/config-files/ExtData_rc.rst +++ b/docs/source/user-guide/config-files/ExtData_rc.rst @@ -9,49 +9,49 @@ simplified and easier to understand interface. The ins and outs of :file:`ExtData.rc` can be hard to grasp, particular with regards to variable data updating, time interpolation, and file read. Reach out on the GCHP GitHub Issues page if you need help. See also the GCHP ReadTheDocs page on enabling -ExtData prints for debugging. Enable ExtData debug prints is the best way to determine what MAPL is doing for file I/O per import. +ExtData prints for debugging. Enabling ExtData debug prints is the best way to determine what MAPL is doing for file I/O per import. -The following two parameters are set at the top of the file: +The following parameter is set at the top of the file: -Ext_AllowExtrat +Ext_AllowExtrap Logical toggle to use data from nearest year available, including meteorology if files for the simulation year are not found. This is set to true for GCHP. Note that GEOS-Chem Classic accomplishes the same effect but with more flexibility in :file:`HEMCO_Config.rc`, and the entries of :file:`HEMCO_Config.rc` which do this are ignored in GCHP. The rest of the file contains whitespace-delimited lines. Each line describes one data variable imported to the model from an external file. Columns are as follows in order from left to right: Name - Name of the field stored in the MAPL Imports container. This is independent of the name of the data field in the input file. For the case of entries that also appear in :file:`HEMCO_Config.rc` it is also the name of the HEMCO emissions container (left-most column in that file). For those fields it is used to match scaling and masking information in :file:`HEMCO_Config.rc` with file I/O information in :file:`ExtData.rc`. + Name of the field stored in the MAPL Imports container. This is independent of the name of the data field in the input file. For the case of entries that also appear in :file:`HEMCO_Config.rc` it is also the name of the HEMCO emissions container (left-most column in that file). For those fields it is used to match scaling and masking information in :file:`HEMCO_Config.rc` with file I/O information in :file:`ExtData.rc`. All file I/O information :file:`HEMCO_Config.rc`, including filename, units, dimensions, regridding, and read frequency are ignored by GCHP. Units Unit string of the import. This entry is informational only. Clim - Whether the data is climatology. Enter :file:`Y` if the data is a 12 month climatology, data year if the data is daily climatology (i.e. :file:`2019`), :file:`D` if the file is monthly day-of-week scale factors (7 values for each of 12 months), or :file:`N` for all other cases. If you specify monthly climatology then the data must be stored in either 1 or 12 files. + Whether the data is climatology. Enter :file:`Y` if the data is a 12 month climatology, enter year if the data is daily climatology (i.e. :file:`2019`), :file:`D` if the file is monthly day-of-week scale factors (7 values for each of 12 months), or :file:`N` for all other cases. If you specify monthly climatology then the data must be stored in either 1 or 12 files. Conservative - Method to regrid the input data to the simulation grid. Enter Y to use mass conserving regridding, :literal:`F;{VALUE}` for fractional regridding, or N to use non-conervative bilinear regridding. + Method to regrid the input data to the simulation grid. Enter :file:`Y` to use mass conserving regridding, :literal:`F;{VALUE}` for fractional regridding, or :file:`N` to use non-conervative bilinear regridding. Refresh - Time template for frequency of updating data. This tells MAPL when to look for new data values. There are several options for specifying refresh: + Time template for updating data. This tells MAPL when to look for new data values. It stores previous and next time data in what are called left and right brackets. There are several options for specifying refresh: * :file:`-` : Update variable data only once. Use this if the data is constant in time. * :file:`0` : Update variable data at every timestep using linear interpolation. For example, if the data is hourly then MAPL will linearly interpolate between the previous and next hour's data for every timestep. * :file:`0:003000` (or other HHMMSS specification for hours, minutes, seconds) : Use specified time offset (i.e. 30 minutes in this example) for setting previous and next time, and interpolate every timestep between the two. This is useful if, for example, you have time-averaged hourly data and you want the previous and next times to update half-way between the hour. This format is used for meteorology fields that are interpolated every timestep, specifically temperature and surface pressure. * :file:`F0:003000` (or other HHMMSS specification for hours, minutes, seconds) : Like the previous option except there is no time interpolation. This format is used for meteorology fields that are not time-interpolated, such as cloud fraction. - * :file:`%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Update variable data when time tokens change. Interpreting this entry gets a little tricky. The data will be updated when the time tokens change, not he hard-coded times. For example, a template in the form %y4-%m2-%d2T12:00:00 changes at the start of each day because that is when the evaluation of %y4-%m2-%d2 changes. While the variable will be updated at the start of a new day (i.e. at time 2019-01-02T00:00:00), the time used for reading and interpolation is 2007-08-02T12:00:00). + * :file:`%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Update variable data when time tokens change. Interpreting this entry gets a little tricky. The data will be updated when the time tokens change, not the hard-coded times. For example, a template in the form :file:`%y4-%m2-%d2T12:00:00` changes at the start of each day because that is when the evaluation of :file:`%y4-%m2-%d2` changes. While the variable will be updated at the start of a new day (e.g. at time 2019-01-02 00:00:00), the time used for reading and interpolation is hour 12 of that day. You can similar hard-code year, month, day, or hour if you always want to use a constant value for that field. * :file:`F%y4-%m2-%h2T%h2:%n2:00` (or other combination of time tokens) : Like the previous option except that there is no time interpolation. Offset Factor Value the data will be shifted by upon read. Use :file:`none` for no shifting. Scale Factor - Value the data will be scaled by upon read. Use :file:`none` for no scaling. + Value the data will be scaled by upon read. This is useful if you want to convert units upon read, such as from :file:`Pa` to :file:`hPa`. Use :file:`none` for no scaling. External File Variable Name of the variable to read in the netCDF data file. External File Template - Path to the netCDF data file, including time tokens as needed (%y4 for year, %m2 for month, %d2 for day, %h2 for hour, %n2 for minutes). If there are no time tokens in the template name then ExtData will assume that all the data is on one file. If you wish to ignore an entry in :file:`ExtData.rc` (i.e. not read then data) then put :file:`/dev/null` to reduce processing time. + Path to the netCDF data file, including time tokens as needed (:file:`%y4` for year, :file:`%m2` for month, :file:`%d2` for day, :file:`%h2` for hour, :file:`%n2` for minutes). If there are no time tokens in the template name then ExtData will assume that all the data is in one file. If you wish to ignore an entry in :file:`ExtData.rc` (i.e. not read the data at all since you will not use it) then put :file:`/dev/null`. This will save processing time. -Reference Time (optional) - Reference time and frequency of data. This optional entry is useful if you have data frequency that is offset from midnight. For example, 3-hourly data available for times 1:30, 4:30, 7:30, etc. The reference time could be specified as :file:`2000-01-01T01:30:00P03:00`. The first part (before :file:`P`) is the reference date (must be on or before your simulation start), and the second part (after :file:`P`) is the period of data availability (in this case 3 hours). This can be used in combination with the file template containing hours and minutes. It tells MAPL to only read the file at times that are regular 3 hr intervals from the reference date and time. Not including this would cause MAPL to read the file every minute if the file template contains the :file:`n2` time token. +Reference Time and Period (optional) + Period of data with reference time. This optional entry is useful if you have data frequency that is offset from midnight. For example, 3-hourly data available for times 1:30, 4:30, 7:30, etc. The reference time could be specified as :file:`2000-01-01T01:30:00P03:00`. The first part (before :file:`P`) is the reference date (must be on or before your simulation start), and the second part (after :file:`P`) is the period of data availability (in this case 3 hours). This can be used in combination with the file template containing hours and minutes. It tells MAPL to only read the file at times that are regular 3 hr intervals from the reference date and time. Not including this would cause MAPL to read the file every minute if the file template contains the :file:`n2` time token. From f66d9cba96fb857f0eec799c2f9779f3d88538b9 Mon Sep 17 00:00:00 2001 From: Melissa Sulprizio Date: Thu, 5 Oct 2023 12:58:47 -0400 Subject: [PATCH 53/54] Update HEMCO submodule to 3.7.0 release Signed-off-by: Melissa Sulprizio --- src/GCHP_GridComp/HEMCO_GridComp/HEMCO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/GCHP_GridComp/HEMCO_GridComp/HEMCO b/src/GCHP_GridComp/HEMCO_GridComp/HEMCO index 4b65f1c9b..d870f321e 160000 --- a/src/GCHP_GridComp/HEMCO_GridComp/HEMCO +++ b/src/GCHP_GridComp/HEMCO_GridComp/HEMCO @@ -1 +1 @@ -Subproject commit 4b65f1c9b18e6d85886c2c384d15627dc545d443 +Subproject commit d870f321e86c0f7555126c384ad265fdd6f997eb From ab0a4344a6ff234b17568e1692afaa20dcc8e5d1 Mon Sep 17 00:00:00 2001 From: Bob Yantosca Date: Fri, 6 Oct 2023 17:54:27 -0400 Subject: [PATCH 54/54] geos-chem-shared-docs update: Update supplemental guides for 14.2.1 This commit informs the GCHP superproject about the following commits that were pushed to the geos-chem-shared-docs submodule: e23eb23 Update supplemental guides for GEOS-Chem 14.2.1 release Signed-off-by: Bob Yantosca --- docs/source/geos-chem-shared-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs index dcf759b94..e23eb23dc 160000 --- a/docs/source/geos-chem-shared-docs +++ b/docs/source/geos-chem-shared-docs @@ -1 +1 @@ -Subproject commit dcf759b94de42d56ed98d28b092f864002c7d757 +Subproject commit e23eb23dcc5cd2922e62a356e2f59634817bdd95