Added files for the GEOS-Chem "science codebase" GitHub repo suggested by Claude Code

.gitattributes

@@ -0,0 +1,12 @@
+# Normalize line endings to LF for text files by default.
+# This repo is built and run on Linux/HPC clusters, so CRLF endings in
+# scripts/source break shebangs, Fortran preprocessing, and compilation.
+* text=auto eol=lf
+
+# Binary assets — never diff/merge as text.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

.github/PULL_REQUEST_TEMPLATE.md

@@ -18,3 +18,7 @@ If this is a science update, please provide a literature citation.
 ### Related Github Issue
 
 Please link to the corresponding Github issue(s) here. If fixing a bug, there should be an issue describing it with steps to reproduce.
+
+### AI disclosure
+
+Please disclose if AI tools (e.g. Claude, ChatGPT) were used in the preparation of this pull request.

.release/changeVersionNumbers.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+
+#EOC
+#------------------------------------------------------------------------------
+#                  GEOS-Chem Global Chemical Transport Model                  !
+#------------------------------------------------------------------------------
+#BOP
+#
+# !MODULE: changeVersionNumbers.sh
+#
+# !DESCRIPTION: Bash script to change the version numbers in the appropriate
+#  files in the GEOS-Chem "science codebase" directory structure.  Run this
+#  before releasing a new GEOS-Chem version.
+#\\
+#\\
+# !CALLING SEQUENCE:
+#  $ ./changeVersionNumbers.sh X.Y.Z        # X.Y.Z = GCClassic version number
+#EOP
+#------------------------------------------------------------------------------
+#BOC
+
+function replace() {
+
+    #========================================================================
+    # Function to replace text in a file via sed.
+    #
+    # 1st argument: Search pattern
+    # 2nd argument: Replacement text
+    # 3rd argument: File in which to search and replace
+    #========================================================================
+
+    sed -i -e "s/${1}/${2}/" "${3}"
+}
+
+
+function exitWithError() {
+
+    #========================================================================
+    # Display and error message and exit
+    #========================================================================
+
+    echo "Could not update version numbers in ${1}... Exiting!"
+    exit 1
+}
+
+
+function main() {
+
+    #========================================================================
+    # Replaces the version number in the files listed.
+    #
+    # 1st argument: New version number to use
+    #========================================================================
+
+    # New version number
+    version="${1}"
+
+    # Current date
+    date=$(date -Idate)
+
+    # Save this directory path and change to root directory
+    thisDir=$(pwd -P)
+    cd ..
+
+    #========================================================================
+    # Update version number and date in CHANGELOG.md
+    #========================================================================
+
+    # Pattern to match: "[Unreleased] - TBD"
+    pattern='\[.*Unreleased.*\].*'
+
+    # List of files to replace
+    files=(                                  \
+        "CHANGELOG.md"                       \
+        "KPP/fullchem/CHANGELOG_fullchem.md" \
+    )
+
+    # Replace version numbers in files
+    for file in ${files[@]}; do
+	replace "${pattern}" "\[${version}\] - ${date}" "${file}"
+        [[ $? -ne 0 ]] && exitWithError "${file}"
+        echo "GCClassic version updated to ${version} in ${file}"
+    done
+
+    #========================================================================
+    # Update date and version in CITATION.cff
+    # NOTE: Only update version but not cff-version
+    #========================================================================
+
+    # Pattern to match: X.Y.Z
+    pattern='^version: .*'
+    replace "${pattern}" "version: ${version}" "CITATION.cff"
+
+    # Pattern to match: YYYY-MM-DD
+    pattern='^date-released: .*'
+    replace "${pattern}" "date-released: ${date}" "CITATION.cff"
+
+    # Return to the starting directory
+    cd "${thisDir}"
+}
+
+# ---------------------------------------------------------------------------
+
+# Expect 1 argument, or exit with error
+if [[ $# -ne 1 ]]; then
+    echo "Usage: ./changeVersionNumbers.sh VERSION"
+    exit 1
+fi
+
+# Replace version numbers
+main "${1}"
+
+# Return status
+exit $?

CHANGELOG.md

@@ -4,6 +4,48 @@ This file documents all notable changes to the GEOS-Chem repository starting in
 
 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] - TBD
+### Added
+- Added PSO4AQ and PH2SO4 as a product to certain reactions; see `KPP/fullchem/CHANGELOG_fullchem.md`
+- Added methanediol (MDL) as a transported gas-phase species and to the KPP fullchem and custom mechanisms
+- Added routine `Cloud_CH2O_MDL` in `KPP/fullchem/fullchem_SulfurChemFuncs.F90`
+- Added multiphase sulfate chemistry and cloud Hplus diagnostic for Travis et al. (2025)
+- Added `IONIC` output argument in calls to HETP driver routine `MACH_HETP_Main15Cases`
+- Added APM restart file paths to `run/shared/download_data.yml`
+- Added for TOMAS, organic and Dunne new particle formation, 3D GFAS capability, and updates for accomodation coefficients
+- Added code blocks for MAPL3 code in development
+- Added GCHP utility script extractPerformance.sh to scrape allPEs.log for timing summary in GCHP run directories
+- Added GCHP build scripts to GCHP runScriptSamples for Harvard
+- Added several additional run, build, and utility scripts to GCHP runScriptSamples for Harvard and AWS pcluster
+- Added `.gitattributes`, `CITATION.cff`, `GOVERNANCE.md`, `SECURITY.md` for GitHub
+- Added `CLAUDE.md`, which gives guidance to Claude Code AI
+- Added `.release/changeVersionNumbers.sh` to change version numbers in relevant files in this repository
+- Added AI disclosure section to `.github/PULL_REQUEST_TEMPLATE.md`
+
+### Changed
+- Renamed `State_Chm%Isorrop*` fields to `State_Chm%Ate*` (aerosol thermodynamical equilibrium), as ISORROPIA is no longer used
+- Updated routine `fullchem_SetStateHet` to accept `id_DSTbin{1..7}`, `id_pFe`, `id_SO2`, and `id_SO4` as arguments
+- Renamed `CRITRH` to `RH_35_PERCENT` and `CRITRH2` to `RH_50_PERCENT` in `KPP/fullchem/fullchem_RateLawFuncs.F90`
+- Added DSTbin{1..7}, SO2, SO4, and pFE species ID flags to the `SetStateHet` routine in `KPP/fullchem_HetStateFuncs.F90` and `KPP/stubs/stub_fullchem_HetStateFuncs.F90`
+- Updated `run/shared/download_data.py` and `run/shared/setupForRestarts.sh` to read APM restart file paths
+- Selected RODAS3.1 as the default integration method for the fullchem mechanism; Regenerated fullchem solver files with KPP 3.4.0
+- Updated the minimum version of KPP needed to build the fullchem mechanism from 3.2.0 to 3.4.0
+- Changed C-preprocessor switch `MODEL_` to `MODEL_EXTERNAL`, and `ESMF_` to `USE_ESMF`
+- Changed the order of DO loops in `GeosCore/tomas_mod.F90` from `I-J-L` to `L-J-I` and added `!$OMP COLLAPSE( 3 )` statements
+- Updated run directory configuration files for GFAS (extension number 112)
+- Changed time cycle for GFAS data in the `gc_4x5_merra2_carbon_CH4_straddle_00z` from `EFY` to `C` to avoid runtime error
+
+### Fixed
+- Fixed incorrect variable names and removed unused variables in `NcdfUtil/ncdf_mod.F90`
+- Fixed incorrect Arrhenius "A" coefficient (1.97d-12 --> 1.97d-11) in C3H8 + OH = A3O2 rxn
+- Fixed GCHP transport tracers extdata.yaml to include valid_range for CEDS
+- Fixed OpenMP parallelization error in `GeosCore/tomas_mod.F90`
+- Fixed typos (extra `:` characters) in `run/shared/kpp_standalone_interface.yml`
+
+### Removed
+- Removed obsolete code in dust_mod.F90
+- Removed unused subroutine I_Am_UnOPENed in inquireMod.F90
+
 ## [14.7.1] - 2026-04-08
 ### Added
 - Added `HTAP_SHIP` toggle in `HEMCO_Config.rc.carbon` templates for GC-Classic and GCHP
@@ -51,6 +93,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Fixed timestep mismatch between GCHP C180 and GCC 0.5x0.625
 - Fixed incorrect dust species names in `run/GCClassic/HEMCO_Diagn.rc.templates/HEMCO_Diagn.rc.fullchem.onlineE` 
 - Fixed incorrect extension number for `InvDustL23M` entries in `run/GCHP/HEMCO_Diagn.rc.templates/HEMCO_Diagn.rc.fullchem`
+- Fixed incorrect `InvAFCID` diagnostic entries `HEMCO_Diagn.rc.fullchem` and `HISTORY.rc.fullchem` template files
 
 ### Removed
 - Removed `ARCTAS_SHIP`, `CORBETT_SHIP`, `ICOADS_SHIP` from `HEMCO_Config.rc` template files
@@ -59,6 +102,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Removed `OHconcAfterChem` from GCClassic and GCHP `HISTORY.rc.carbon` templates, as OH is fixed during the simulation
 - Removed `State_Grid` argument from `Set_Prof_FJX` routine
 
+### Fixed
+- Fixed the species database entry of `DMS` to use `Is_Gas: true`, as DMS is a gas-phase species and not an aerosol
+
+### Changed
+- Changed frequency of SpeciesConcVV and SpeciesConcMND diagnostic update to every chemistry timestep (previously dynamic timestep) to avoid value oscillation for certain species when dynamic timestep is less than chemistry timestep
+
 ## [14.7.0] - 2026-02-05
 ### Added
 - Added entries for FINNv25 biomass burning emissions to template HEMCO configuration files
@@ -165,7 +214,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Changed OpenMP loop scheduling from `DYNAMIC` to `GUIDED` in routine `DO_CONVECTION`
 - Added `Diagn_APM` routine in `GeosCore/hcoi_gc_diagn_mod.F90` to restore HEMCO manual diagnostics for use w/ APM
 - Added hidden option to read GC-Classic restart file as real8 locally rather than real4 through HEMCO
-
+	
 ### Changed
 - Updated logic to include ObsPack observations that span UTC date boundaries
 - Assigned ObsPack averaging interval end times (instead of start times) to the `aveEnd` variable in routine `ObsPack_Write_Output`

CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "GEOS-Chem"
+type: software
+authors:
+  - name: "The International GEOS-Chem User Community"
+version: 14.7.1
+date-released: 2026-04-13
+doi: 10.5281/zenodo.1343546
+url: "https://geos-chem.readthedocs.io"
+repository-code: "https://github.com/geoschem/geos-chem"
+license: MIT
+keywords:
+  - atmospheric-chemistry
+  - atmospheric-composition
+  - atmospheric-modeling
+  - aws
+  - climate-modeling
+  - cloud-computing
+  - geos-chem
+  - atmospheric-computing
+  - scientific-computing

CLAUDE.md

@@ -0,0 +1,84 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repository is
+
+This is the **GEOS-Chem science codebase** (`geoschem/geos-chem`) — the Fortran source for GEOS-Chem, a global 3-D model of atmospheric chemistry. It is almost never built or tested standalone; it is consumed as a git submodule by two superproject wrapper repos:
+
+- **GCClassic** (`geoschem/GCClassic`) — builds this code as a standalone executable ("GEOS-Chem Classic")
+- **GCHP** (`geoschem/GCHP`) — builds this code as an ESMF/MAPL gridded component inside the GEOS/NASA modeling framework ("GCHP")
+
+Both superprojects vendor this repo at `src/GEOS-Chem`, and symlink `run/`, `test/`, and `spack/` from it up to their own top level. If you were pointed here from a GCClassic or GCHP checkout, you are actually editing *this* repo — commits/PRs belong here (geoschem/geos-chem), not in the wrapper repo.
+
+Preprocessor macros `MODEL_CLASSIC` / `MODEL_GCHP` (set by the superproject's CMake) gate code paths that only apply to one implementation (e.g. `Interfaces/GCClassic/main.F90` is wrapped in `#ifdef MODEL_CLASSIC`). When reading or editing shared modules, check which macros surround a block before assuming it runs in both implementations.
+
+## Repository layout
+
+Source is organized by role, not by scientific topic — a given "feature" (e.g. dry deposition) typically spans several of these:
+
+| Directory | Contents |
+|---|---|
+| `GeosCore/` | Core science drivers: chemistry, transport, convection, deposition, emissions coupling, per-simulation-type modules (`tagged_o3_mod.F90`, `mercury_mod.F90`, `tomas_mod.F90`, `carbon_mod.F90`, etc.) |
+| `Headers/` | Shared derived types and utilities used everywhere: `state_chm_mod.F90`, `state_met_mod.F90`, `state_grid_mod.F90`, `state_diag_mod.F90`, `species_database_mod.F90`, `species_mod.F90`, `precision_mod.F90` |
+| `History/` | The netCDF diagnostics framework (`history_mod.F90` and the `Hist*` container types) that HISTORY.rc/diagnostics are built on |
+| `KPP/` | Chemical mechanisms. Each subdirectory (`fullchem/`, `carbon/`, `Hg/`, `custom/`, `aciduptake/`, `stubs/`) is a KPP-generated solver plus mechanism-specific Fortran (e.g. `fullchem_RateLawFuncs.F90`, `fullchem_SulfurChemFuncs.F90`). `KPP/standalone` is a separate submodule (KPP-Standalone box model, built when `-DKPPSA=y`). Never hand-edit KPP-generated solver files (`gckpp_*`) — regenerate with `build_mechanism.sh` |
+| `Interfaces/GCClassic/` | GEOS-Chem Classic driver (`main.F90`), built only when `MODEL_CLASSIC` |
+| `Interfaces/GCHP/` | GCHP gridded-component glue (`Chem_GridCompMod.F90`, `gchp_chunk_mod.F90`), built only when `MODEL_GCHP` |
+| `GeosUtil/`, `NcdfUtil/` | Generic utilities (string parsing, netCDF I/O wrappers, YAML config parsing via `qfyaml_mod.F90`) with no science content |
+| `GTMM/`, `APM/`, `GeosRad/`, `PKUCPL/`, `ObsPack/` | Optional/pluggable components (Global Terrestrial Mercury Model, aerosol microphysics, RRTMG radiative transfer, ObsPack diagnostics) enabled by their own CMake switches |
+| `run/GCClassic/`, `run/GCHP/`, `run/shared/`, `run/CESM/`, `run/GEOS/`, `run/WRF/` | Run-directory creation scripts (`createRunDir.sh`) and config-file templates (`geoschem_config.yml`, `HEMCO_Config.rc`, `HISTORY.rc`, etc.) for each implementation |
+| `test/` | Integration/parallel/difference test drivers (see below) |
+| `CMakeScripts/` | `GC-Helpers.cmake` — shared CMake macros (`gc_pretty_print`, version detection) used by this repo's `CMakeLists.txt` |
+
+`CMakeLists.txt` at the repo root is included by the superproject's build, not invoked standalone — it expects `GEOSChemBuildProperties` and options like `MECH`, `MODEL_CLASSIC`/`MODEL_GCHP` to already be defined by the caller.
+
+## Building
+
+There is no standalone build here — always build via a superproject run directory. From a GCClassic or GCHP checkout with this repo as its `src/GEOS-Chem` submodule:
+
+```console
+cd run/GCClassic && ./createRunDir.sh      # or run/GCHP/createRunDir.sh
+cd /path/to/rundir/build
+cmake ../CodeDir -DRUNDIR=..
+make -j && make install
+```
+
+Relevant CMake options that live in *this* repo (`KPP/CMakeLists.txt`, root `CMakeLists.txt`):
+- `MECH` — `fullchem` (default), `carbon`, `custom`, `Hg` — selects which `KPP/<mech>` subdirectory is built
+- `KPPSA` — also builds `KPP/standalone` (KPP-Standalone box model) alongside `fullchem`/`custom`
+- Supported Fortran compilers are Intel and GNU only (`GEOSChem_Fortran_FLAGS_{Intel,GNU}`); anything else is a hard CMake `FATAL_ERROR`
+
+## Modifying a chemical mechanism
+
+Do not hand-edit the KPP-generated solver files under `KPP/<mechanism>/` (files prefixed `gckpp_`). Instead edit the mechanism's `.eqn`/`.spc`/`.kpp` definition files, then regenerate:
+
+```console
+cd KPP
+./build_mechanism.sh fullchem   # or Hg, custom
+```
+
+This requires KPP 3.4.0+ (see root `CHANGELOG.md` for the currently-required version) and preserves the heterogeneous-chemistry files while regenerating the solver. Hand-written mechanism support code (rate laws, heterogeneous chemistry hookups) lives alongside the generated files, e.g. `KPP/fullchem/fullchem_RateLawFuncs.F90`, `KPP/fullchem/fullchem_SulfurChemFuncs.F90`, `KPP/fullchem_HetStateFuncs.F90` / `KPP/stubs/stub_fullchem_HetStateFuncs.F90` (a stub is required for every mechanism that doesn't implement heterogeneous chemistry).
+
+## Testing
+
+Test infrastructure lives under `test/` and is symlinked to the same path in GCClassic/GCHP superprojects. All test scripts require a real (non-conda) netCDF — `conda deactivate` first, or the scripts abort immediately.
+
+- `test/integration/GCClassic/` and `test/integration/GCHP/` — compile + optionally run several out-of-the-box run-directory configurations, to catch build/run regressions:
+  ```console
+  cd test/integration/GCClassic
+  ./integrationTest.sh -d <root-dir> -t compile   # compile-only
+  ./integrationTest.sh -d <root-dir> -t all        # compile and run short sims
+  ./integrationTest.sh -d <root-dir> -t compile -q # quick subset, for local dev
+  ```
+- `test/parallel/GCClassic/` — same idea but sweeps OpenMP thread counts, to catch parallelization bugs.
+- `test/difference/` — bit-for-bit diff of output between two integration/parallel test runs (e.g. before/after a structural, non-science change).
+- `test/shared/commonFunctionsForTests.sh` — functions/settings shared by all of the above; source this rather than duplicating logic when adding new test scripts.
+
+## Versioning and changes
+
+- Root `CHANGELOG.md` follows Keep a Changelog / SemVer and documents changes to this repo specifically (GCClassic's own CHANGELOG.md separately tracks submodule-pointer bumps and wrapper-level changes).
+  Individual KPP mechanisms may keep their own changelog, e.g. `KPP/fullchem/CHANGELOG_fullchem.md` — update that too when changing fullchem's chemistry.
+- This is a community-governed, grass-roots model (see `README.md` and geos-chem.org). Substantive science/structural changes are expected to go through the GEOS-Chem Steering Committee / User Working Group process, not just a code review.
+- Any structural (non-science) change should be accompanied by a difference test (`test/difference/`) against the prior version to confirm bit-for-bit identical results.
+- Config/run-directory changes should be mirrored across `run/GCClassic/` and `run/GCHP/` (and `run/CESM`, `run/GEOS`, `run/WRF` where applicable) since they share the same underlying `geoschem_config.yml` / `HEMCO_Config.rc` / `HISTORY.rc` schema.