Skip to content

CLAUDE.md

Latest commit

 

History

History
248 lines (190 loc) · 10.1 KB

CLAUDE.md

File metadata and controls

248 lines (190 loc) · 10.1 KB

Claude Code Project Configuration

Project Overview

CheMPAS-A (Chemistry for MPAS - Atmosphere) is a standalone project derived from NCAR/MPAS-Model-ACOM-dev, itself a fork of MPAS-Dev/MPAS-Model. It extends the Model for Prediction Across Scales (MPAS) with integrated MUSICA/MICM atmospheric chemistry, enabling coupled atmospheric-chemistry modeling on MPAS's unstructured mesh. CheMPAS-A is an independent project and is not intended to sync with the upstream repositories.

Key Documentation

  • docs/architecture/ARCHITECTURE.md - High-level system architecture
  • BUILD.md - Build system documentation (includes LLVM/macOS instructions)
  • RUN.md - Test case execution instructions
  • docs/guides/VISUALIZE.md - Chemistry visualization tools and workflows
  • docs/architecture/COMPONENTS.md - Detailed component descriptions
  • docs/musica/MUSICA_INTEGRATION.md - MUSICA/MICM coupling details
  • docs/musica/MUSICA_API.md - MUSICA Fortran API reference
  • AGENTS.md - Agent roles, workflow, and operational details
  • docs/results/BENCHMARKS.md - Agent model benchmark comparison
  • PURPOSE.md - Project motivation and goals
  • docs/results/TEST_RUNS.md - Test run documentation
  • docs/project/TODO.md - Development task list

Sister Project Reference

  • ~/EarthSystem/DAVINCI-MPAS/ - Sister project with prior lightning-NOx/O3 implementation work.
  • Start with:
    • PLAN.md (Phase 6 LNOx-O3 details)
    • SCIENCE.md (physics assumptions and validation framing)
    • DC3.md (observational context and targets)

Build Configuration

CheMPAS-A builds on two platforms. The preflight script auto-detects the compiler toolchain (flang or gfortran) and sets paths accordingly:

scripts/check_build_env.sh          # report mode — shows what it found
eval "$(scripts/check_build_env.sh --export)"   # export mode — sets env vars

PKG_CONFIG_PATH must be present in the same shell invocation as make. The Makefile uses $(shell pkg-config ...) during parse, so exporting it in a separate shell and then invoking make later is not sufficient.

macOS (LLVM/flang)

Resolved environment:

  • NETCDF=/opt/homebrew
  • PNETCDF=/Users/fillmore/software
  • PIO=/Users/fillmore/software
  • PKG_CONFIG_PATH=/Users/fillmore/software/lib/pkgconfig
  • Make target: llvm
eval "$(scripts/check_build_env.sh --export)" && make -j8 llvm \
  CORE=atmosphere PIO="$PIO" NETCDF="$NETCDF" PNETCDF="$PNETCDF" \
  PRECISION=double MUSICA=true

eval "$(scripts/check_build_env.sh --export)" && make -j8 llvm \
  CORE=init_atmosphere PIO="$PIO" NETCDF="$NETCDF" PNETCDF="$PNETCDF" \
  PRECISION=double

Ubuntu (GCC/gfortran via conda)

Requires the mpas conda environment (conda activate mpas).

Resolved environment:

  • NETCDF=$CONDA_PREFIX (miniconda3/envs/mpas)
  • PNETCDF=$CONDA_PREFIX
  • PIO=$HOME/software
  • PKG_CONFIG_PATH=$HOME/software/lib/pkgconfig
  • Make target: gfortran
eval "$(scripts/check_build_env.sh --export)" && make -j8 gfortran \
  CORE=atmosphere PIO="$PIO" NETCDF="$NETCDF" PNETCDF="$PNETCDF" \
  PRECISION=double MUSICA=true

eval "$(scripts/check_build_env.sh --export)" && make -j8 gfortran \
  CORE=init_atmosphere PIO="$PIO" NETCDF="$NETCDF" PNETCDF="$PNETCDF" \
  PRECISION=double

Dependencies installed via conda-forge: gcc gxx gfortran cmake openmpi libnetcdf netcdf-fortran libpnetcdf libblas liblapack pkg-config make. PIO and MUSICA built from source into ~/software.

Important (both platforms)

  • Always use -j8 for parallel compilation.
  • MUSICA-Fortran must be built with the same Fortran compiler as CheMPAS-A. Mixing flang and gfortran .mod files causes link failures.
  • PNETCDF is required for the normal top-level build.
  • A full atmosphere build may still stop later if src/core_atmosphere/physics/physics_mmm tries to git fetch MMM-physics and network access is unavailable.

Key Source Locations

Component Path
Framework src/framework/
Operators src/operators/
Atmosphere Core src/core_atmosphere/
Init Atmosphere src/core_init_atmosphere/
Dynamics src/core_atmosphere/dynamics/
Physics src/core_atmosphere/physics/
Chemistry src/core_atmosphere/chemistry/
MUSICA Integration src/core_atmosphere/chemistry/musica/
Registry (metadata) src/core_atmosphere/Registry.xml

MUSICA Integration Files

File Purpose
mpas_atm_chemistry.F Generic chemistry interface
mpas_musica.F MUSICA/MICM coupler implementation

Build Artifacts

File Description
atmosphere_model Main atmosphere executable
init_atmosphere_model Initialization/preprocessing tool
build_tables Physics lookup table generator

Available Skills

Skills are defined in .claude/commands/ and can be invoked with /skillname:

Skill Command Description
Build MPAS /build-mpas Build atmosphere or init_atmosphere
Test MPAS /test-mpas Run a test case and verify output
Plot Chemistry /plot-chemistry Generate and open chemistry visualization plots
MUSICA Dev /musica-dev Work on MUSICA/MICM chemistry integration

Development Approach

CheMPAS-A uses a coding-agent-assisted development model. Agents are used for implementation, review support, and verification, while humans retain responsibility for scientific judgment and final technical direction. See AGENTS.md for the full workflow, agent roles, and human review gates.

Multi-Agent Workflow

CheMPAS-A uses three agents from three vendors (see AGENTS.md). Codex 5.4 reviews Claude's work and may push doc edits or review findings directly to the repo, but that review remains part of a human-directed workflow rather than a fully automated merge path.

Convention for cross-agent communication:

  • Codex writes review findings to CODEX_REVIEW.md and pushes to develop
  • When the user says "check the review", pull and read CODEX_REVIEW.md
  • Implement fixes, then remove CODEX_REVIEW.md (it's a transient artifact, not a permanent doc)
  • Codex may also edit .md documentation files directly — always git pull before committing if Codex has been active
  • Before merging to main, ensure no concurrent Codex edits are in flight

Notes for AI Assistants

  1. Fortran Standards: This is a Fortran 2008 codebase using MPI for parallelism
  2. Build System: Uses legacy Makefile (not CMake) with make llvm (macOS) or make gfortran (Ubuntu)
  3. Module Files: flang and gfortran .mod files are incompatible - don't mix compilers
  4. MPI: macOS/LLVM uses include 'mpif.h' via NOMPIMOD flag; Ubuntu/gfortran uses mpi_f08 module natively
  5. Registry System: Most variable definitions are in Registry.xml (build-time), but MUSICA chemistry tracers are injected at runtime from the MICM config
  6. Physics: Many physics schemes from WRF, NoahMP, and other sources
  7. MUSICA: Use scripts/check_build_env.sh before MUSICA builds. The working pkg-config file is ~/software/lib/pkgconfig/musica-fortran.pc on both platforms.
  8. Build Environment: PKG_CONFIG_PATH must be present in the same shell invocation as make; otherwise the Makefile's parse-time pkg-config checks fail.
  9. Testing: Always run with 8 MPI ranks (mpiexec -n 8). A mismatched rank count with no matching partition file causes segfaults in the dynamics solver. See RUN.md for details.

Common Tasks

Full Rebuild

The preflight script auto-detects the make target (llvm or gfortran):

make clean CORE=atmosphere
find . -name "*.mod" -delete
find . -name "*.o" -delete
eval "$(scripts/check_build_env.sh --export)" && make -j8 TARGET CORE=atmosphere PIO="$PIO" NETCDF="$NETCDF" PNETCDF="$PNETCDF" PRECISION=double

Replace TARGET with llvm (macOS) or gfortran (Ubuntu), or read it from the preflight output.

Build with MUSICA

eval "$(scripts/check_build_env.sh --export)" && make -j8 TARGET \
  CORE=atmosphere \
  PIO="$PIO" \
  NETCDF="$NETCDF" \
  PNETCDF="$PNETCDF" \
  PRECISION=double \
  MUSICA=true

Notes:

  • Keep the eval ... && make ... in a single shell command.
  • If the build fails after chemistry compiles, check whether physics_mmm attempted a network fetch.

Check Build Status

ls -la atmosphere_model init_atmosphere_model build_tables

Python Environment and Scripts

Conda Environment

A conda environment mpas is available for visualization and analysis:

~/miniconda3/envs/mpas/bin/python  # Direct path
# Or activate: conda activate mpas

Packages: numpy, matplotlib, netcdf4

Visualization Scripts (scripts/)

Script Purpose
plot_chemistry.py Visualize chemistry tracer output (qA, qB, qAB)
init_tracer_sine.py Initialize tracers with sine wave patterns

plot_chemistry.py usage:

cd ~/Data/CheMPAS/supercell
~/miniconda3/envs/mpas/bin/python plot_chemistry.py -o output.png
~/miniconda3/envs/mpas/bin/python plot_chemistry.py --time-series  # Spatial evolution
~/miniconda3/envs/mpas/bin/python plot_chemistry.py --diff          # Difference from t=0

init_tracer_sine.py usage:

# Apply horizontal sine wave to qAB (for advection studies)
python init_tracer_sine.py -i supercell_init.nc -t qAB --waves-x 2 --amplitude 0.4 --offset 0.6

Test Run Directory

Idealized test cases are in ~/Data/CheMPAS/:

Case Directory Duration Mesh
Supercell ~/Data/CheMPAS/supercell/ 2 hours 60 stretched levels to 50 km (~300 m surface → ~1 km top)
Mountain wave ~/Data/CheMPAS/mountain_wave/ 5 hours ~577 m, 70 levels
Baroclinic wave ~/Data/CheMPAS/jw_baroclinic_wave/ 16 days 120 km, 26 levels

Reference namelists and streams files are tracked in test_cases/ in the repo. See RUN.md for execution instructions and test_cases/README.md for data download and setup.

Important: All streams files use io_type="netcdf" to avoid PnetCDF compatibility issues.