summa-skill

"What do I need?"
|
+-- First time. What is SUMMA and how do I install it?
|   Read: reference/getting-started.md
|   (clone, dependencies NetCDF/LAPACK/Sundials, Makefile vs CMake vs Docker)
|
+-- I want to understand how the source tree is organized
|   Read: reference/architecture.md
|   (driver, dshare, engine, hookup, netcdf, noah-mp; data structures, call chain)
|
+-- I want to set up and run a SUMMA simulation
|   Read: reference/running-summa.md
|   (file manager, attributes, parameters, forcing, output control, summa.exe CLI)
|
+-- I want to know which physics option to set for X
|   Read: reference/model-decisions.md
|   (the 40 numbered decisions, options table, how to mimic Noah-MP/CLM/VIC)
|
+-- I want to read or post-process SUMMA output
|   Read: reference/output-and-postprocess.md
|   (NetCDF dimensions, midToto/ifcToto layer indexing, pysumma helpers)
|
+-- I want to reproduce the published case studies
|   Read: reference/case-studies.md
|   (Reynolds Mountain East, Senatorial Snow, Wrightwood, Aspen)
|
+-- I want to use the SUNDIALS solver branch
|   Read: reference/sundials-and-solvers.md
|   (CH-Earth fork, IDA vs KINSOL, Jacobian options, build flags)
|
+-- The model won't compile, won't run, or gives implausible output
|   Read: reference/debugging.md
|   (dimension errors, missing values, snowpack instability, balance violations)
|
+-- I want to submit a pull request
    Read: reference/contributing-pr.md
    (NCAR vs CH-Earth fork choice, develop branch, testing, review)

summa/
|-- build/
|   |-- Makefile              <- traditional build (env vars: F_MASTER, FC, FC_EXE, INCLUDES, LIBRARIES)
|   |-- CMakeLists.txt        <- CMake build
|   |-- cmake/
|   |   |-- compile_script.sh
|   |   |-- FindNetCDF.cmake
|   |   `-- FindOpenBLAS.cmake
|   `-- source/
|       |-- driver/           <- top-level program (summa_driver.f90), runtime orchestration
|       |-- dshare/           <- shared data: data_types, var_lookup, multiconst, popMetadat
|       |-- engine/           <- physics + solver: coupled_em, computFlux, computJacob, snow*, soil*, vegNrgFlux, mDecisions
|       |-- hookup/           <- file/IO orchestration: summaFileManager, ascii_util
|       |-- netcdf/           <- NetCDF I/O: def_output, modelwrite, read_icond
|       |-- noah-mp/          <- inherited Noah-MP routines (module_sf_noahmplsm.F)
|       `-- lapack/           <- LAPACK shims when system lib not used
|-- case_study/
|   |-- base_settings/        <- VEGPARM.TBL, SOILPARM.TBL, GENPARM.TBL, MPTABLE.TBL, localParamInfo.txt, basinParamInfo.txt
|   `-- reynolds/             <- Reynolds Mountain East albedo decay experiment
|       |-- fileManager_reynoldsConstantDecayRate.txt
|       |-- fileManager_reynoldsVariableDecayRate.txt
|       |-- forcing/, site_settings/, output/, evaluation/
|-- ci/summa_install_utils/   <- Travis install scripts
|-- docs/                     <- mkdocs source for summa.readthedocs.io
|-- utils/convert_summa_config_v2_v3.py
|-- Dockerfile
|-- COPYING                   <- GPLv3
|-- LICENSE.txt
|-- header.license            <- file header template for new source
|-- mkdocs.yml
`-- readme.md -> docs/index.md

# 1. Get the code
git clone https://github.com/NCAR/summa.git
cd summa

# 2. Install dependencies (macOS Homebrew shown)
brew install gcc netcdf netcdf-fortran lapack

# 3. Pick a build system. CMake is the recommended modern path:
cd build/cmake
./compile_script.sh        # creates cmake_build/, builds parallel, drops summa.exe in summa/bin/

# Alternatively use the traditional Makefile
cd ../                     # back to summa/build/
export F_MASTER=$(pwd)/..
export FC=gfortran
export FC_EXE=gfortran
export INCLUDES="-I/opt/homebrew/include"
export LIBRARIES="-L/opt/homebrew/lib -lnetcdff -llapack -lblas"
make check                 # confirm variables look right
make                       # build; executable is summa/bin/summa.exe

# 4. Smoke-test the binary
../bin/summa.exe -v        # prints version banner

# 5. Run the Reynolds Mountain East case study
cd ../case_study/reynolds
../../bin/summa.exe -m fileManager_reynoldsConstantDecayRate.txt
../../bin/summa.exe -m fileManager_reynoldsVariableDecayRate.txt

# 6. Inspect output
ls output/
ncdump -h output/reynolds_constantDecayRate_*.nc | head -40