gmpas 0.4.2__tar.gz

gmpas-0.4.2/.github/workflows/tests.yml

@@ -0,0 +1,68 @@
+name: tests
+
+# Pull requests and pushes to main. Not tags: a tag points at a commit that
+# has already been tested here, so re-running proves nothing new.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  # a second push to the same branch supersedes the first
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest · ubuntu · python 3.12
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}          # -l so the conda env is actually active
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # conda-forge, not pip: cartopy and netCDF4 are painful to build from
+      # source, and ESMF_RegridWeightGen is an executable pip cannot install at
+      # all. Installing the real environment.yml is what makes a green check
+      # here mean the same thing as a green run on a laptop.
+      - name: Install the conda environment
+        uses: mamba-org/setup-micromamba@v2
+        with:
+          environment-file: environment.yml
+          environment-name: gmpas
+          # environment.yml says `python >=3.10`, which would let the solver
+          # drift onto whatever is newest. Pin the version CI is meant to test.
+          create-args: python=3.12
+          cache-environment: true
+
+      - name: Install gmpas
+        # --no-deps: every dependency came from conda above. Letting pip
+        # resolve them again can shadow the conda build of a compiled package
+        # with a wheel, which is how a working environment silently breaks.
+        run: pip install -e . --no-deps
+
+      - name: Report what is actually installed
+        # a failure three steps down is much easier to read with this above it.
+        # ESMF_RegridWeightGen is *expected* to be missing here -- environment.yml
+        # deliberately does not install it (see docs/REMAPPING.md and issue 34),
+        # and every remap test that would shell out to it mocks the call instead.
+        run: |
+          python -c "import gmpas; print('gmpas', gmpas.__version__)"
+          python -c "import numpy, scipy, xarray, netCDF4, matplotlib, cartopy; print('numpy', numpy.__version__, 'scipy', scipy.__version__, 'xarray', xarray.__version__, 'netCDF4', netCDF4.__version__, 'matplotlib', matplotlib.__version__, 'cartopy', cartopy.__version__)"
+          which ESMF_RegridWeightGen ncremap || echo "remap tools NOT on PATH"
+
+      # No ruff step yet, deliberately. `ruff check src tests` currently reports
+      # 42 pre-existing violations (mostly E501 in the embedded viewer page), so
+      # gating on it would mean this workflow is red from its first run for
+      # reasons unrelated to whether the code works. Tracked separately; turn it
+      # on once the tree is clean.
+
+      - name: Run the test suite
+        # Agg: the runner is headless, and a rendering test that tries for a
+        # display fails in a way that looks nothing like the real problem
+        env:
+          MPLBACKEND: Agg
+        run: pytest -q --durations=10

gmpas-0.4.2/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Data — never commit model output or generated figures
+*.nc
+*.npz
+*.png
+
+# ESMF_RegridWeightGen writes these into its cwd on every run
+PET*.RegridWeightGen.Log
+
+# OS
+.DS_Store

gmpas-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nmathewa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gmpas-0.4.2/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: gmpas
+Version: 0.4.2
+Summary: Fast plotting of MPAS output on its own native variable-resolution mesh
+Project-URL: Homepage, https://github.com/nmathewa/gmpas-lib
+Project-URL: Issues, https://github.com/nmathewa/gmpas-lib/issues
+License: MIT
+License-File: LICENSE
+Keywords: atmosphere,mpas,unstructured,visualization,voronoi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: netcdf4>=1.6
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: xarray>=2023.1
+Provides-Extra: dev
+Requires-Dist: cartopy>=0.22; extra == 'dev'
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: pillow>=9.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: cartopy>=0.22; extra == 'plot'
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Requires-Dist: pillow>=9.0; extra == 'plot'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# gmpas
+
+[![tests](https://github.com/nmathewa/gmpas-lib/actions/workflows/tests.yml/badge.svg)](https://github.com/nmathewa/gmpas-lib/actions/workflows/tests.yml)
+[![version](https://img.shields.io/badge/version-0.4.1-blue)](docs/status.md)
+[![python](https://img.shields.io/badge/python-3.10%2B-blue)](docs/installation.md)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Fast plotting of MPAS output **on its own native mesh** — no regridding, so
+variable resolution is preserved exactly as the model carries it. Plus the
+other end of the pipeline: designing a mesh, building it with JIGSAW, and
+looking at either before or after it exists.
+
+```python
+import gmpas
+
+ds = gmpas.open_mpas("diag.2019-09-01_00.00.00.nc", mesh="maritime.region.nc")
+
+ds.mpas.plot("mslp")        # cell field, filled Voronoi polygons
+ds.mpas.plot("u")           # edge field, drawn on the cell faces themselves
+ds.mpas.plot_mesh()         # where the mesh actually refines, in km
+```
+
+`mesh=` may be omitted when the file carries its own mesh information, or when
+a mesh file with a matching cell count sits beside it.
+
+## Installation
+
+```bash
+conda env create -f environment.yml && conda activate gmpas && pip install -e . --no-deps
+```
+
+Pure pip works too where wheels exist:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Two workflows need external programs, which pip cannot provide. Conservative
+remapping needs ESMF (`conda install -c conda-forge esmf nco`); mesh generation
+needs [JIGSAW](https://github.com/dengwirda/jigsaw) and, for the final step,
+MPI and PnetCDF. Skip both if you only plot and view.
+
+Check it landed:
+
+```bash
+gmpas --version && pytest -q
+```
+
+Full detail, including the extras and what each one pulls in:
+[docs/installation.md](docs/installation.md).
+
+## Usage
+
+```bash
+gmpas info          history.2012-02-25_12.00.00.nc
+gmpas plot          history.2012-02-25_12.00.00.nc precipw -o pw.png
+gmpas view          /path/to/run/
+gmpas remap         history.*.nc -o out/
+gmpas prep view     mesh.nc
+gmpas prep hfun     hfun.py --check
+gmpas prep generate hfun.py -o mesh/     # needs $JIGSAWDIR and $MKGRIDFILE
+```
+
+Any path may be a file, a directory, or a glob; a directory or glob is read as
+one time series across files, which is how MPAS writes output. Running `gmpas`
+with no arguments prints the whole list with examples.
+
+Everything except `prep` is **postprocessing** — it opens a run and renders,
+remaps or exports it. `prep` is the other end, for work that happens before
+there is any output.
+
+## Documentation
+
+| | |
+|---|---|
+| [Why gmpas exists](docs/why.md) | the problem with lat-lon tooling, and why this is fast |
+| [Installation](docs/installation.md) | conda, pip, extras, and the external programs |
+| [Command line](docs/command-line.md) | every command and its flags |
+| [In a notebook](docs/notebook.md) | the accessor, and using the pieces directly |
+| [Preprocessing](docs/preprocessing.md) | `prep view`, `prep hfun`, `prep generate` — mesh design and JIGSAW |
+| [Conservative remapping](docs/REMAPPING.md) | the whole terminal workflow, and two MPAS traps |
+| [On a cluster](docs/cluster.md) | port forwarding, and the two variables that matter |
+| [Configuration](docs/configuration.md) | `GMPAS_CACHE_DIR` and `GMPAS_DATA_DIR` |
+| [Examples](examples/) | ready-to-edit `hfun.py` templates |
+| [Tests](docs/testing.md) | what the suite covers |
+| [Layout](docs/layout.md) | what lives in which module |
+| [Differences from the MCP server](docs/mcp-server.md) | what changed on the way to a package |
+| [Status](docs/status.md) | what is implemented and what is not |

gmpas-0.4.2/README.md

@@ -0,0 +1,88 @@
+# gmpas
+
+[![tests](https://github.com/nmathewa/gmpas-lib/actions/workflows/tests.yml/badge.svg)](https://github.com/nmathewa/gmpas-lib/actions/workflows/tests.yml)
+[![version](https://img.shields.io/badge/version-0.4.1-blue)](docs/status.md)
+[![python](https://img.shields.io/badge/python-3.10%2B-blue)](docs/installation.md)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Fast plotting of MPAS output **on its own native mesh** — no regridding, so
+variable resolution is preserved exactly as the model carries it. Plus the
+other end of the pipeline: designing a mesh, building it with JIGSAW, and
+looking at either before or after it exists.
+
+```python
+import gmpas
+
+ds = gmpas.open_mpas("diag.2019-09-01_00.00.00.nc", mesh="maritime.region.nc")
+
+ds.mpas.plot("mslp")        # cell field, filled Voronoi polygons
+ds.mpas.plot("u")           # edge field, drawn on the cell faces themselves
+ds.mpas.plot_mesh()         # where the mesh actually refines, in km
+```
+
+`mesh=` may be omitted when the file carries its own mesh information, or when
+a mesh file with a matching cell count sits beside it.
+
+## Installation
+
+```bash
+conda env create -f environment.yml && conda activate gmpas && pip install -e . --no-deps
+```
+
+Pure pip works too where wheels exist:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Two workflows need external programs, which pip cannot provide. Conservative
+remapping needs ESMF (`conda install -c conda-forge esmf nco`); mesh generation
+needs [JIGSAW](https://github.com/dengwirda/jigsaw) and, for the final step,
+MPI and PnetCDF. Skip both if you only plot and view.
+
+Check it landed:
+
+```bash
+gmpas --version && pytest -q
+```
+
+Full detail, including the extras and what each one pulls in:
+[docs/installation.md](docs/installation.md).
+
+## Usage
+
+```bash
+gmpas info          history.2012-02-25_12.00.00.nc
+gmpas plot          history.2012-02-25_12.00.00.nc precipw -o pw.png
+gmpas view          /path/to/run/
+gmpas remap         history.*.nc -o out/
+gmpas prep view     mesh.nc
+gmpas prep hfun     hfun.py --check
+gmpas prep generate hfun.py -o mesh/     # needs $JIGSAWDIR and $MKGRIDFILE
+```
+
+Any path may be a file, a directory, or a glob; a directory or glob is read as
+one time series across files, which is how MPAS writes output. Running `gmpas`
+with no arguments prints the whole list with examples.
+
+Everything except `prep` is **postprocessing** — it opens a run and renders,
+remaps or exports it. `prep` is the other end, for work that happens before
+there is any output.
+
+## Documentation
+
+| | |
+|---|---|
+| [Why gmpas exists](docs/why.md) | the problem with lat-lon tooling, and why this is fast |
+| [Installation](docs/installation.md) | conda, pip, extras, and the external programs |
+| [Command line](docs/command-line.md) | every command and its flags |
+| [In a notebook](docs/notebook.md) | the accessor, and using the pieces directly |
+| [Preprocessing](docs/preprocessing.md) | `prep view`, `prep hfun`, `prep generate` — mesh design and JIGSAW |
+| [Conservative remapping](docs/REMAPPING.md) | the whole terminal workflow, and two MPAS traps |
+| [On a cluster](docs/cluster.md) | port forwarding, and the two variables that matter |
+| [Configuration](docs/configuration.md) | `GMPAS_CACHE_DIR` and `GMPAS_DATA_DIR` |
+| [Examples](examples/) | ready-to-edit `hfun.py` templates |
+| [Tests](docs/testing.md) | what the suite covers |
+| [Layout](docs/layout.md) | what lives in which module |
+| [Differences from the MCP server](docs/mcp-server.md) | what changed on the way to a package |
+| [Status](docs/status.md) | what is implemented and what is not |

gmpas-0.4.2/docs/REMAPPING.md

@@ -0,0 +1,354 @@
+# Conservative remapping
+
+A terminal workflow. gmpas writes the grid file and checks the answer; a real
+remapper computes the weights.
+
+## What you need installed
+
+`ESMF_RegridWeightGen` (from `esmf`) and, optionally, `ncremap` (from `nco`).
+Both are executables rather than Python packages, so they cannot come from pip
+and are not declared in `pyproject.toml`.
+
+**gmpas does not install either itself, on purpose.** `environment.yml` brings
+in only gmpas's own Python dependencies. On an HPC site, load the site's own
+builds instead — `module load esmf`, `module load nco` — rather than adding
+conda-forge copies to this environment: a site build is tuned for the local
+MPI/interconnect, and a second copy here would compete with it on
+`PATH`/`LD_LIBRARY_PATH` rather than help, whether gmpas shells out to it
+(ESMF) or you run it yourself (`ncremap`) — see
+[issue 34](https://github.com/nmathewa/gmpas-lib/issues/34). On a machine with
+no module system, `conda install -c conda-forge esmf nco` into a separate
+environment works fine — just don't add it to the one gmpas itself runs in. A
+`command not found: ESMF_RegridWeightGen` means neither is loaded.
+
+![conservative remapping workflow](remapping-workflow.svg)
+
+```mermaid
+flowchart TD
+    M["MPAS mesh file"] -->|gmpas scrip| S["src.scrip.nc"]
+    T["target grid"] -->|write dst SCRIP| D["dst.scrip.nc"]
+    S --> W["ESMF_RegridWeightGen -m conserve"]
+    D --> W
+    W --> MAP["map.nc<br/><i>reuse for every field and step</i>"]
+    MAP --> A["apply: dst = S · src"]
+    H["history.nc"] --> A
+    A --> C["check the integral"]
+```
+
+## Why gmpas does not compute the weights
+
+Spherical polygon intersection — great-circle edges, degenerate cells, poles,
+the antimeridian — is hard to get right, and ESMF and TempestRemap have both
+been doing it correctly for years.
+
+And the obvious shortcut does not work. Supersampling a target cell and
+counting which source cells the samples land in **converges towards**
+conservation as the sample count grows, with error falling as `1/sqrt(N)`, but
+never actually preserves the cell integral. That is not conservation, and
+shipping it under that name would be worse than not offering it.
+
+## One command
+
+Put `target_domain` next to the run, optionally `include_fields`,
+`exclude_fields` and `mesh_file`, then:
+
+```bash
+gmpas remap 'history.*.nc' -o out/
+```
+
+It reads the configuration, builds the weights once (reusing `map_*.nc` if it
+is already there), and writes **one output file per input file** — a few
+hundred history files concatenated into a single netCDF would be unwieldy, and
+one-in-one-out keeps the valid time in the filename.
+
+```
+[1/3] configuration from /scratch/run
+        found   target_domain
+        found   include_fields
+        absent  exclude_fields
+        found   mesh_file
+  input : 193 file(s)
+  mesh  : init.nc  (from mesh_file)
+  target: 534 x 267 cells, lon 80.0 .. 160.0, lat -20.0 .. 20.0, 0.149813 deg
+  fields: 20 selected of 119 available
+
+[2/3] weights
+  writing src.scrip.nc and dst.scrip.nc
+    normalised 12,774 longitudes onto [0, 2pi)
+  weights ready in 18.2 s (77 MB)
+
+[3/3] remapping 193 file(s) -> out/
+        not remapped — u: on nEdges — needs edge weights
+        conservation error 0.0e+00 (0 is exact)
+  [  1/193] history.2012-02-25_00.00.00.remap.nc  18 fields, 347 slabs, 5.7s, eta 18m
+```
+
+### Where the mesh comes from
+
+MPAS output streams are user-configured, so a history file need not carry
+`verticesOnCell` at all. The mesh is resolved in this order:
+
+1. `--mesh` on the command line
+2. a `mesh_file` in the config directory, holding one line: the path
+3. the data file itself, if it is self-describing
+4. a mesh sitting beside the data with a matching cell count
+
+`mesh_file` is usually the right answer for a real run — set once, not passed
+on every command.
+
+### What cannot be remapped by cell weights
+
+Cell weights carry cell fields. MPAS keeps velocity as `u` on edges and
+vorticity on vertices, and those need their own weight files, so they are
+reported rather than silently dropped:
+
+```
+        not remapped — u: on nEdges — needs edge weights
+        not remapped — vorticity: on nVertices — needs vertex weights
+```
+
+For winds, `uReconstructZonal` / `uReconstructMeridional` are already at cell
+centres and remap normally.
+
+### Running it in parallel
+
+Files are independent, so they convert in parallel:
+
+```bash
+gmpas remap 'history.*.nc' -o out/ -j 64
+```
+
+**Give `-j` explicitly.** Without it the worker count is detected — from
+`SLURM_CPUS_PER_TASK`, the other schedulers' variables, then the process
+affinity mask, and only then `os.cpu_count()` — which beats using the size of
+the machine, but is still only as reliable as what the site sets. The command
+always reports which source it used, and that line is worth reading:
+
+```
+  64 worker(s) (of 64 from SLURM_CPUS_PER_TASK)     detection worked
+  1 worker(s) (of 1 from NCPUS)                     detection was misled
+```
+
+`NCPUS` in particular is set to `1` by some login profiles regardless of the
+allocation, which silently pins a large job to one worker. `-j` overrides
+whatever was detected:
+
+```
+  64 worker(s) (asked for 64; 1 available from NCPUS)
+```
+
+Measured on 8 files, 936 slabs, on a 10-core laptop:
+
+| workers | wall | per file |
+|---|---|---|
+| 1 | 14 s | 1.73 s |
+| 2 | 8 s | 1.01 s |
+| 4 | 5 s | 0.65 s |
+| 8 | 5 s | 0.58 s |
+
+It flattens past the core count because the work is largely netCDF reads. On a
+parallel filesystem the ceiling is I/O bandwidth rather than cores, so very
+high `-j` will not keep scaling — worth measuring on a subset before
+committing a whole run.
+
+Under `fork` the weights are inherited copy-on-write rather than re-read, which
+matters at high core counts: ~15 MB of index arrays re-loaded in 256 workers
+would be several gigabytes of duplication for read-only data.
+
+A file that fails is reported and the run continues; the exit status is
+non-zero if any failed.
+
+### A caveat on ESMF
+
+ESMF 8.9.1 on macOS segfaults intermittently — measured at roughly **one run
+in five** on byte-identical inputs that succeed the other four times. Weight
+generation is a one-off, so `gmpas remap` retries up to four times and says so
+when it does. A reproducible crash is different and usually means the padded
+`grid_corners` problem below.
+
+## The steps, individually
+
+### 1. Write the source grid
+
+```bash
+gmpas scrip history.2012-02-25_12.00.00.nc -o src.scrip.nc
+```
+
+Works on any file carrying mesh information — an `init.nc`, a `*.grid.nc`, or
+a history file that carries its own mesh. It reports the coverage as a sanity
+check (a global mesh should say 100%) and tells you if any longitudes had to be
+normalised.
+
+### 2. Write the target grid
+
+Describe it in a `target_domain` file beside the run:
+
+```
+nlat     = 267
+nlon     = 534
+startlat = -20.0
+endlat   =  20.0
+startlon =  80.0
+endlon   = 160.0
+```
+
+`startlat`/`endlat` are the **domain edges** and `nlat` counts cells across
+them, so the spacing is `(endlat - startlat) / nlat` and centres sit half a
+cell inside each edge — the grid then covers exactly the box you asked for.
+
+The extent is not fussy beyond that. Target cells falling outside the source
+mesh come back unmapped, and a target narrower than the mesh simply crops;
+both are expected. `gmpas target` prints the covered extent next to the
+requested one so any shift is visible rather than assumed.
+
+Then, from that directory:
+
+```bash
+gmpas target -o dst.scrip.nc
+```
+
+`gmpas target` reads the file from the working directory — no path needed —
+reports the resulting grid, and writes the SCRIP. Pass a data file too and it
+lists which fields would be remapped:
+
+```bash
+gmpas target history.2012-02-25_12.00.00.nc -o dst.scrip.nc
+```
+
+Cell areas are written as exact solid angles, `dlon x (sin(north) -
+sin(south))`, not the `dlon x dlat x cos(lat)` approximation — a remapper
+compares them against its own and the difference shows up as conservation
+error.
+
+`ncremap -g dst.scrip.nc -G latlon=180,360` will also generate a target, and
+a SCRIP file is only six arrays if you would rather write one directly.
+
+### Choosing fields
+
+Two more optional files in the same directory, one variable name per line:
+
+```
+include_fields    remap only these
+exclude_fields    remap everything but these
+```
+
+Blank lines, `#` comments and stray trailing spaces are all fine — these get
+hand-edited. A name in **both** files is contradictory: **include wins**, and
+a warning names the fields, because silently dropping something explicitly
+asked for leaves output missing with nothing to explain it.
+
+### 3. Generate the weights — once per mesh pair
+
+```bash
+ESMF_RegridWeightGen -s src.scrip.nc -d dst.scrip.nc -w map.nc \
+    -m conserve --src_regional --dst_regional --ignore_unmapped
+```
+
+`--src_regional` / `--dst_regional` matter for a mesh that does not cover the
+sphere; `--ignore_unmapped` lets destination cells outside the source domain
+pass through unmapped rather than aborting.
+
+Alternatives, all producing a SCRIP-format weight file:
+
+```bash
+ncremap -s src.scrip.nc -g dst.nc -m map.nc -a aave    # first-order, the E3SM route
+GenerateOfflineMap --in_mesh a.g --out_mesh b.g --ov_mesh ov.g --out_map map.nc
+```
+
+`-m conserve` is first-order; `-m conserve2nd` is second-order and less
+diffusive. TempestRemap adds higher order and `--mono` monotonicity.
+
+**Weights depend only on the two grids.** Generate once, then reuse for every
+variable, level and timestep of that run.
+
+### 4. Apply them
+
+A weight file carries `row`, `col`, `S`, plus `area_a`, `area_b`, `frac_a`,
+`frac_b`. Applying it is a sparse matrix multiply:
+
+```python
+import numpy as np, xarray as xr
+
+w = xr.open_dataset("map.nc")
+dst = np.zeros(w.sizes["n_b"])
+np.add.at(dst, w.row.values - 1, w.S.values * src[w.col.values - 1])
+```
+
+The `- 1` is not optional: SCRIP indices are 1-based.
+
+`ncremap` will also do this for you:
+
+```bash
+ncremap -m map.nc history.nc remapped.nc
+```
+
+### 5. Check that it conserved
+
+The step worth never skipping, because every failure mode here produces a
+plausible-looking wrong answer rather than an error:
+
+```python
+I_src = (src * w.area_a.values * w.frac_a.values).sum()
+I_dst = (dst * w.area_b.values).sum()
+assert abs(I_dst - I_src) / abs(I_src) < 1e-12
+```
+
+**Do not multiply the destination by `frac_b`.** With ESMF's default
+`norm_type=dstarea` the weights already carry the destination coverage
+fraction, so multiplying again double counts it — that mistake reported a 0.2%
+error on weights that were exact.
+
+Measured on a 413,788-cell regional mesh to a 0.25° lat-lon grid:
+
+| field | relative error |
+|---|---|
+| constant 1.0 | 1.1e-16 |
+| smooth analytic (float64) | 0.0 |
+| `precipw`, `t2m` | 0.0 |
+| nearest-neighbour, for contrast | 2.1e-05 |
+
+For partially covered destination cells, the raw `dst` is what conserves;
+`dst / frac_b` is what you plot.
+
+## Two traps specific to MPAS
+
+Both were found by testing, and both break `mpas_tools` output as readily as
+anything else. `gmpas scrip` handles both.
+
+### Files mix longitude conventions
+
+A real history file stored `lonCell` on `[0, 2π)` reaching 3.23 rad (185°E)
+while storing `lonVertex` on `[-π, π)` — so 12,774 vertices near the dateline
+were negative. A cell's centre and its own corners then sit on different
+branches, and the polygon handed to a remapper is nonsense.
+`mpas_tools.scrip.from_mpas` refuses such a file outright:
+
+```
+ValueError: lonVertex is not in the desired range (0, 2pi)
+```
+
+`gmpas scrip` normalises onto `[0, 2π)` and reports how many values it moved.
+
+### grid_corners must be trimmed
+
+MPAS declares `maxEdges` generously — one mesh declares 10 and uses at most 6.
+Written at the declared width, every unused column becomes a degenerate corner
+repeated on every cell, and **ESMF 8.9.1 segfaults on `-m conserve`**:
+
+```
+exit 139, no weight file, nothing useful in the log
+```
+
+Confirmed at 2°, 1° and 0.25° targets; nearest-neighbour works either way, so
+it is specific to the conservative path. Trimmed to 6 it completes. `gmpas
+scrip` writes `grid_corners = max(nEdgesOnCell)`.
+
+## What is not here
+
+Applying weights from the command line is not implemented — see
+[issue 2](https://github.com/nmathewa/gmpas-lib/issues/2). The snippet above is
+what it would do.
+
+`uxarray` is not yet an option: its remapping is nearest-neighbour, inverse
+distance and bilinear only. Conservative exists through its YAC backend, but
+that integration is still in progress.