usp-utils: add MPAS install/build pipeline + guided setup documentation by daniloceano · Pull Request #12 · CGFD-USP/MPAS-Research

daniloceano · 2026-06-20T16:15:12Z

Summary

Adds a complete, documented installation and build pipeline for MPAS under
usp-utils/install/. develop currently has no build toolchain and no build
documentation; this PR introduces a lean, reproducible one plus step-by-step
guides.

What this PR adds

Build pipeline (new usp-utils/install/):

mpas_lib_install.sh — builds the library dependencies. It is lean by
design: MPAS v8 uses its bundled SMIOL I/O layer when PIO is unset, so the
only external I/O dependency is PnetCDF. MPI comes from the system / HPC
module stack; MPICH can optionally be built from the official mpich.org source
with BUILD_MPICH=1.
mpas_build_env.sh — the environment to source before make and before
running the model (sets PNETCDF, puts the MPI wrappers and runtime libraries
on PATH / LD_LIBRARY_PATH).

Guided documentation:

install/README.md — step by step: detect whether you already have MPI →
build the libraries → compile → run the model. Includes a make gnu vs
make gfortran note and a common-errors section.
install/environment_setup.md — sets up the Python (conda) + Julia
pre/post-processing toolbox and explains setup_environment.sh.

Reorganization:

Move install_conda_environment.sh and install_julia_environment.jl from the
usp-utils/ root into install/ (all installers grouped together);
setup_environment.sh stays at the root as the per-session activation script.
usp-utils/README.md rewritten as a general overview: install-first ordering,
folder map, and where runs/data go (runs/, grids/, met_data/ — git-ignored).
gitignore machine-specific *.local.sh copies.

Design notes

The lean PnetCDF-only / system-MPI / make gnu choices follow @favba's
recommendations. The Julia environment installs directly from @favba's upstream
packages (no temporary Zeros compat workaround needed).

Scope

Installation / environment setup only. Pre-processing (GFS/ERA5/OISST, static
fields) and post-processing (plotting) ship as separate PRs.

Testing

Built and ran init_atmosphere_model / atmosphere_model (MPAS v8.4.1) on a
plain workstation with BUILD_MPICH=1 + system GCC 13, following
install/README.md.

Add a friendly, end-to-end install path under usp-utils/install/: - download_mpas_lib_sources.sh: fetch & verify the 6 library source tarballs (MPICH, zlib, HDF5, PnetCDF, NetCDF-C/Fortran) in the versions the build script expects; PnetCDF from the official Argonne mirror. - mpas_lib_install.sh: fix the build for gfortran >= 10 by adding -fallow-argument-mismatch to FFLAGS (MPICH's F77 check uses FFLAGS; without it MPICH never builds, cascading into "C compiler cannot create executables" in later libs that use the missing mpicc). - INSTALL_GUIDE.md: full recommended flow (conda -> julia -> source env -> build libs -> compile MPAS -> setup run dir), with the Julia LD_LIBRARY_PATH and Zeros caveats and a troubleshooting section. - .gitignore: keep machine-specific *.local.sh copies out of the repo. README.md: document the install/build flow and the copy-to-.local.sh pattern. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- Use mpas_build_env.local.sh (git-ignored) consistently, sourced for both building and running. - Add mpirun launch commands for the cores and note that running atmosphere_model with no inputs aborts via MPI_Abort (expected). - Complete prerequisites: make, bzip2, tar/gzip. - Clarify that steps 4-6 (build/compile) don't require the conda/Julia envs. - Note the template is already patched for gfortran >= 10. - Document that PIO is optional (SMIOL fallback); NETCDF/PNETCDF always needed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…s optional Revert the -fallow-argument-mismatch change in the versioned template so it stays identical to the upstream NCAR script — users should try the original first. Document the fix instead, in a new "Known build issues (optional fixes)" section of INSTALL_GUIDE, to be applied in the user's .local.sh copy only if the MPICH build fails on gfortran >= 10. The note is explicit that the fix is compiler/OS-dependent and invites others to document alternative solutions. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The install/build docs no longer hard-reference the workaround installer or UPSTREAM_ISSUE_zeros_compat.md (which live on the separate julia/zeros-compat-workaround branch). The Julia Step 2 now keeps the universal LD_LIBRARY_PATH guidance and points to that branch for the temporary Zeros resolve conflict, so this PR is self-contained. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- setup_environment.sh: stop inferring env existence from 'conda activate's exit code (which gives a misleading "Couldn't find the environment" when the env exists but a transient activate returns non-zero). Now: ensure the 'conda' shell function is loaded (source conda.sh if only the binary is on PATH), check the env in 'conda env list', then activate. Clearer not-found message. - install_conda_environment.sh: add '#!/usr/bin/env bash' shebang. It uses bash-only features (BASH_SOURCE, '[ == ]'); running it with sh/dash failed with "Bad substitution" / "unexpected operator" and left SCRIPT_DIR empty. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

When a tool runs with HOME pointing at the repo, conda (cache+envs), shell history, and other per-user files get created here (.conda, .cache, .local, .config, .claude, .viminfo, ...). Ignore them so they don't pollute git status; the real ones live in $HOME and these copies are safe to delete. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- setup_environment.sh: stop inferring env existence from 'conda activate's exit code (which gives a misleading "Couldn't find the environment" when the env exists but a transient activate returns non-zero). Now: ensure the 'conda' shell function is loaded (source conda.sh if only the binary is on PATH), check the env in 'conda env list', then activate. Clearer not-found message. - install_conda_environment.sh: add '#!/usr/bin/env bash' shebang. It uses bash-only features (BASH_SOURCE, '[ == ]'); running it with sh/dash failed with "Bad substitution" / "unexpected operator" and left SCRIPT_DIR empty. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

MPAS v8.4 miscompiles with gfortran 13 (builds, crashes at run time); gfortran 12 (the NCAR tutorial's version) produces a working model. Add mpas_lib_install_gcc12.sh — a gfortran-12 variant of the lib-install template (conda-forge gcc12 wrappers, separate libs-gcc12 prefix, generic $HOME paths) — and document the gcc12 toolchain in INSTALL_GUIDE (conda env, build steps, and the gcc12 build-environment block). Personal *.local.sh copies stay git-ignored. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Rework the MPAS dependency install per F. Barbosa's review of the install PR: MPAS v8 uses its bundled SMIOL I/O layer whenever PIO is unset, so PnetCDF is the only required external I/O dependency. Drop PIO, NetCDF-C/Fortran, HDF5 and zlib entirely. - mpas_lib_install.sh: build PnetCDF only; MPICH is now optional (BUILD_MPICH=1), fetched from the official mpich.org source instead of the NCAR mirror. Prefer the system / HPC module MPI. - mpas_build_env.sh: new; sets PNETCDF and unsets PIO/NETCDF so the SMIOL path is selected. Replaces the old NETCDF/PIO/HDF5 build env. - README.md: rationale, quick start, config table, and a note that `make gnu` vs `make gfortran` differ only in two compile-time diagnostic flags (-std=f2008 -fimplicit-none) and produce numerically identical binaries. - Remove the obsolete heavy-stack scripts (download_mpas_lib_sources.sh, mpas_lib_install_gcc12.sh) and INSTALL_GUIDE.md. - gitignore *.local.sh at the repo root too. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…compile) The README only covered sourcing mpas_build_env.sh before 'make' (compile). It never stated the same env must be sourced to RUN init_atmosphere_model / atmosphere_model — without it mpiexec/mpirun aren't on PATH and the runtime libs aren't on LD_LIBRARY_PATH. Add a 'Step 4 — run the model' section with the mpiexec invocation, the 'command not found' symptom, and a branch caveat: this script lives only on setup/installation, so keep a branch-independent copy at ~/mpas-build/mpas_build_env.sh and source that regardless of checked-out branch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

# Conflicts: # .gitignore

Bring the install + environment work to a single coherent state on top of the current develop (8.4.1): - Move install_conda_environment.sh and install_julia_environment.jl into install/ (conda yml path -> ../libs); setup_environment.sh stays at the usp-utils root as the per-session activation script. - install/README.md: keep the "run the model" step, add an environment_setup.md pointer at the top, and drop the now-obsolete branch caveat. - install/environment_setup.md: Python (conda) + Julia toolbox setup guide, with the env -u LD_LIBRARY_PATH note. The Julia env now installs straight from favba's upstream packages (the Zeros compat workaround is no longer needed). - usp-utils/README.md: general overview with install-first ordering and a folder map; drop the broken pre_proc/static_fields link (that belongs to the preproc PR). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

favba

@daniloceano , after my comments are addressed I'll merge this PR!
So comments are just suggestions and you can choose to keep things as is or not.
From the top of my head: the one regarding whether to suggest using PRECISION=double or not when compiling MPAS.

The "where do I run these" note opened with "works from any directory" and only then said to start at the repo root, which read as a contradiction. Lead with the instruction (run from the MPAS repo root) and keep the absolute-paths caveat as a parenthetical. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@favba

…trade-off Per @favba's review: - Add AUTOCLEAN=true to the build commands. It re-cleans a tree that still holds objects from an earlier build with different options, instead of aborting with "previously compiled with incompatible options". - Document precision. MPAS has defaulted to SINGLE-precision reals since v8.1/8.2 (Makefile: "Default is to use single-precision"; PRECISION=double is what adds FFLAGS_PROMOTION). Single stays the default here: it is faster, lighter on RAM and disk, and NCAR reports no accuracy/stability degradation for typical runs. The note explains the trade-off (~2e-7 vs ~2e-16 smallest relative error) and shows how to switch to PRECISION=double -- passing it to BOTH cores -- for analyses built on small residuals of large terms (energy budgets, energetics). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@favba

Per @favba's review: these changes were unrelated to this PR. The `.local.sh` convention is a leftover from the earlier heavy-stack workflow, where you copied the install template and hand-edited LIBSRC/LIBBASE in the copy. The lean scripts are driven entirely by environment variables (MPAS_LIBS, MPAS_SRC, BUILD_MPICH), so no `.local.sh` copy is ever created. - Restore the root .gitignore to its develop state (this also reverts a stray comment-wording change introduced while resolving a merge conflict). - Remove usp-utils/install/.gitignore, whose own comment documented the dead copy-the-template workflow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@favba

…tion - PNETCDF_VERSION now defaults to 1.14.1 (suggested by @favba), in both the script and the Configuration table in the README, which had drifted apart. - Drop the "make gnu vs make gfortran" section from the README: the comparison belongs in the PR discussion, not in the build guide. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@favba

…" needed @favba questioned the claim that Julia always needs `env -u LD_LIBRARY_PATH`. He was right: verified empirically (Julia 1.12.6, `import Pkg`). Julia bundles its own libcurl.so.4, libcrypto.so.3, libgcc_s.so.1, libgfortran.so.5, libgomp.so.1, libgmp.so.10 ... in <julia>/lib/julia. A segfault happens only when LD_LIBRARY_PATH points at a directory holding different builds of those same SONAMEs, so the loader shadows Julia's own. Measured: LD_LIBRARY_PATH empty -> works ~/mpas-build/libs/lib (MPICH/PnetCDF only) -> works (no SONAME overlap) conda env lib/ -> SIGSEGV /usr/lib/x86_64-linux-gnu -> SIGSEGV So the MPAS build environment is NOT the culprit, and on a machine with an empty LD_LIBRARY_PATH (the common case) plain `julia` is fine. Replace the "always needed" note with the measured conditions, a `echo $LD_LIBRARY_PATH` check, and the reason `env -u` is still used in the commands (harmless when unnecessary). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

daniloceano · 2026-07-13T22:51:28Z

@favba I have addressed all points raised by you, please see now if it's ok now.

Copilot

Pull request overview

This PR introduces a new usp-utils/install/ area that provides a reproducible MPAS v8 build/install pipeline (lean PnetCDF-only + optional MPICH) along with guided setup documentation, and reorganizes existing environment installers/docs accordingly.

Changes:

Adds MPAS build dependency installer (mpas_lib_install.sh) and a build/run environment script (mpas_build_env.sh) under usp-utils/install/.
Adds guided installation documentation for both model build/run and Python/Julia pre/post-processing environments.
Reorganizes installers into usp-utils/install/, updates usp-utils/README.md, and expands .gitignore to avoid committing large/user-specific artifacts.

Reviewed changes

Copilot reviewed 8 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`usp-utils/setup_environment.sh`	Improves conda detection/activation behavior for pre/post-processing toolbox activation.
`usp-utils/README.md`	Rewrites usp-utils overview with install-first flow, directory map, and data/run locations.
`usp-utils/install/README.md`	New step-by-step guide for MPAS build/run with the lean dependency approach.
`usp-utils/install/mpas_lib_install.sh`	New script to build PnetCDF (and optionally MPICH) for MPAS v8.
`usp-utils/install/mpas_build_env.sh`	New environment script to set PNETCDF/MPI paths and ensure PIO stays unset for SMIOL.
`usp-utils/install/install_julia_environment.jl`	New installer for shared Julia environment used by Julia tooling scripts.
`usp-utils/install/install_conda_environment.sh`	New/relocated conda environment installer script (idempotent create/update).
`usp-utils/install/environment_setup.md`	New guide for Python+Julia pre/post-processing environment setup and activation.
`usp-utils/install_conda_environment.sh`	Removed old top-level conda installer in favor of `usp-utils/install/`.
`.gitignore`	Adds ignores for large WPS geog downloads and common stray per-user HOME artifacts.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+# 'conda activate' needs the 'conda' shell function; load it if only the binary
+# is on PATH (e.g. in a shell where 'conda init' hasn't run).
+if ! type conda 2> /dev/null | grep -q 'function'; then
+    __conda_sh="$(conda info --base 2> /dev/null)/etc/profile.d/conda.sh"
+    [ -f "$__conda_sh" ] && source "$__conda_sh"


+N=$(conda info --envs | grep '^cgfd-usp-mpas ' | wc -l)
+if [ $N == 0 ]; then
+    echo -e "${INFO} Creating 'cgfd-usp-mpas' conda environment"
+    conda env create --name cgfd-usp-mpas --file=$SCRIPT_DIR/../libs/cgfd-usp-mpas.yml
+else
+    echo -e "${INFO} 'cgfd-usp-mpas' conda environment already exists, updating it instead"
+    conda env update --name cgfd-usp-mpas --file=$SCRIPT_DIR/../libs/cgfd-usp-mpas.yml --prune
+fi


+export PATH="$LIBBASE/bin:$PATH"
+export LD_LIBRARY_PATH="$LIBBASE/lib:${LD_LIBRARY_PATH:-}"


+echo "=== Done. Lean MPAS dependencies installed under: $LIBBASE ==="
+echo "Next steps:"
+echo "  source \"\$(dirname \"\$0\")/mpas_build_env.sh\""
+echo "  cd \"\$MPAS_ROOT\""


+# mpas_lib_install.sh (PnetCDF only). Source this before running `make`:
+#
+#   source usp-utils/install/mpas_build_env.sh
+#   cd "$MPAS_ROOT"


+export PATH="$MPAS_LIBS/bin:$PATH"
+if [ -n "$MPI_HOME" ]; then
+    export PATH="$MPI_HOME/bin:$PATH"
+    export LD_LIBRARY_PATH="$MPI_HOME/lib:${LD_LIBRARY_PATH:-}"
+fi
+
+export PNETCDF="$MPAS_LIBS"
+unset PIO NETCDF                          # -> SMIOL path, no stray NetCDF linkage
+export LD_LIBRARY_PATH="$MPAS_LIBS/lib:${LD_LIBRARY_PATH:-}"


+```bash
+# Python environment 'cgfd-usp-mpas' (built from ../libs/cgfd-usp-mpas.yml):
+bash install_conda_environment.sh
+
+# Julia shared environment 'cgfd-usp-mpas'.
+# `env -u LD_LIBRARY_PATH` is a safety net, not always required -- see the note
+# on LD_LIBRARY_PATH below. It is harmless when unnecessary:
+env -u LD_LIBRARY_PATH julia install_julia_environment.jl
+```


daniloceano and others added 16 commits June 9, 2026 18:11

gitignore: ignore WPS_GEOG and geog downloads

e9a2349

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

gitignore: ignore WPS_GEOG and geog downloads

740fc3a

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

gitignore: ignore stray HOME/per-user dirs created in the repo

c24534c

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/develop' into develop

32b18b6

Merge branch 'develop' into setup/installation

27678ea

# Conflicts: # .gitignore

daniloceano requested a review from favba June 20, 2026 16:17

favba requested changes Jul 10, 2026

View reviewed changes

daniloceano and others added 5 commits July 13, 2026 22:10

Copilot AI review requested due to automatic review settings July 13, 2026 22:50

Copilot started reviewing on behalf of daniloceano July 13, 2026 22:50 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

usp-utils: add MPAS install/build pipeline + guided setup documentation#12

usp-utils: add MPAS install/build pipeline + guided setup documentation#12
daniloceano wants to merge 21 commits into
developfrom
setup/installation

daniloceano commented Jun 20, 2026

Uh oh!

favba left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

daniloceano commented Jul 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		export PATH="$LIBBASE/bin:$PATH"
		export LD_LIBRARY_PATH="$LIBBASE/lib:${LD_LIBRARY_PATH:-}"

Uh oh!

Conversation

daniloceano commented Jun 20, 2026

Summary

What this PR adds

Design notes

Scope

Testing

Uh oh!

favba left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

daniloceano commented Jul 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants