parflow-skill

"What do I need?"
|
+- First time. What is ParFlow and how do I install it?
|  -> reference/getting-started.md
|     (CMake build, Hypre/Silo/HDF5/PDI deps, MPI, OpenMP, CUDA, Docker)
|
+- I want to set up and run a simulation
|  -> reference/running-simulations.md
|     (TCL vs Python pftools, pfset keys, Solver Impes vs Richards,
|      examples/ walk-through, distributing input files, running parallel)
|
+- I want to understand what is in the source tree
|  -> reference/architecture.md
|     (pfsimulator, pftools, pf-keys, pfnuopc, examples, performance_tests,
|      AMPS, KINSOL, CLM module, modules-as-objects pattern in C)
|
+- I need to know what equations ParFlow solves
|  -> reference/physics-and-numerics.md
|     (Richards equation, OverlandKinematic vs OverlandFlow vs OverlandDiffusive,
|      hydraulic conductivity tensor, Newton-Krylov + Hypre PFMG/SMG/MGSemi)
|
+- I want to run ParFlow-CLM (integrated land surface)
|  -> reference/coupling-with-clm.md
|     (PARFLOW_HAVE_CLM=ON, Solver.LSM CLM, drv_clmin.dat, drv_vegm.dat,
|      drv_vegp.dat, NLDAS forcing, RZWaterStress option)
|
+- I have output files. How do I read or visualize them?
|  -> reference/output-formats.md
|     (pfb binary, Silo, NetCDF via PDI, VisIt/ParaView, Python pftools,
|      HydroFrame ecosystem)
|
+- I need GPU performance or scaling guidance
|  -> reference/gpu-and-performance.md
|     (PARFLOW_ACCELERATOR_BACKEND=cuda|kokkos|omp, RMM/Umpire allocator,
|      MGSemi preconditioner, GPUDirect, OMP_NUM_THREADS, MPI mapping)
|
+- The build fails / the run crashes / the mass balance is off
|  -> reference/debugging.md
|     (CMake config, Hypre version mismatch, CFL/timestep failures,
|      KINSOL convergence, mass balance check, conf.yml for PDI)
|
+- I want to submit a fix or feature upstream
   -> reference/contributing-pr.md
      (fork, branch, pfformat / Uncrustify / Black, make check, Doxygen,
      LGPL header, GitHub Actions CI)

parflow/
|-- CMakeLists.txt                  <- top-level build, version 3.14.1+
|-- README.md                       <- quick start
|-- README-GPU.md                   <- CUDA / Kokkos build instructions
|-- README-OPENMP.md                <- OpenMP build instructions
|-- README-PDI.md                   <- PDI (parallel data interface) build
|-- README-SAMRAI.md                <- legacy SAMRAI variant
|-- README-Spack.md                 <- Spack-based build
|-- RELEASE-NOTES.md                <- version-by-version changelog
|-- CONTRIBUTING.md                 <- code style, license, PR process
|-- LICENSE.txt                     <- LGPL v2.1
|-- VERSION
|-- bin/                            <- build helpers, pfformat, docker-build.sh
|-- cmake/                          <- recipes (ubuntu-18.10-CUDA, etc.), modules
|-- docker/                         <- Dockerfiles for ParFlow image
|-- Dockerfile, Dockerfile_CUDA     <- build a runnable ParFlow image
|-- docs/
|   |-- user_manual/                <- Sphinx source for parflow.readthedocs.io
|   |   |-- intro.rst, start.rst, pfsystem.rst, models.rst,
|   |   |-- files.rst, keys.rst, pftools.rst, python/, refs.bib
|   |-- design_documents/
|   |-- doxygen/                    <- code documentation
|   |-- manuals/
|   |-- software_plan.md
|-- examples/                       <- annotated TCL + Python example scripts
|   |-- example_single.tcl, example_single.py, example_richards.tcl,
|   |-- forsyth2.tcl, forsyth5.tcl, llnl.tcl, well_*.tcl, *.pfsol
|-- pf-keys/                        <- key definitions + Python/Sphinx generators
|   |-- definitions/                <- YAML files, source of truth for keys
|   |-- generators/
|-- pfnuopc/                        <- NUOPC cap (couples ParFlow to ESMF apps)
|-- pfsimulator/                    <- the simulator
|   |-- amps/                       <- "Another Message Passing System"
|   |-- clm/                        <- embedded CLM (Fortran 90)
|   |-- kinsol/                     <- embedded KINSOL nonlinear solver
|   |-- parflow_exe/                <- main() for the parflow executable
|   |-- parflow_lib/                <- the simulator library (most C/C++ code)
|   |-- third_party/                <- pdi/, etc.
|-- pftools/                        <- pre/post-processing tools
|   |-- python/                     <- Python pftools (modern interface)
|   |-- *.c, *.h, *.tcl             <- TCL pftools and helpers
|   |-- pfmask-to-pfsol.cpp, pfsol-to-vtk.c, compute_domain.c, water_balance.c,
|   |-- toposlopes.c, top.c, water_table.c, well.c
|-- performance_tests/              <- inactive_active_time, etc.
|-- test/                           <- regression tests run by `make check`
|-- misc/

# 1. Install dependencies (Ubuntu example)
sudo apt-get install -y build-essential cmake gfortran tcl tcl-dev \
    libopenmpi-dev openmpi-bin libhdf5-openmpi-dev libsilo-dev \
    libhypre-dev python3 python3-pip

# 2. Decide install location
export PARFLOW_DIR=$HOME/parflow

# 3. Get the source
git clone https://github.com/parflow/parflow.git
cd parflow

# 4. Out-of-source CMake configure
mkdir build && cd build
cmake .. \
    -DCMAKE_INSTALL_PREFIX=${PARFLOW_DIR} \
    -DPARFLOW_AMPS_LAYER=mpi1 \
    -DPARFLOW_HAVE_CLM=ON \
    -DPARFLOW_ENABLE_HYPRE=TRUE \
    -DPARFLOW_ENABLE_SILO=TRUE \
    -DPARFLOW_ENABLE_HDF5=TRUE \
    -DPARFLOW_ENABLE_TIMING=TRUE \
    -DCMAKE_BUILD_TYPE=Release

# 5. Build and install
make -j 8
make install

# 6. Run the regression suite
make check

# 7. Run a sample problem (1x1x1 process topology)
cd ../test/tcl
tclsh default_single.tcl 1 1 1

pip install pftools
cd parflow/test/python
python default_single.py 1 1 1