JuliaClimate · gaelforget · Jul 12, 2026 · Jul 11, 2026 · Jul 12, 2026 · Jul 12, 2026
diff --git a/docs/make.jl b/docs/make.jl
@@ -29,10 +29,11 @@ makedocs(;
     authors="gaelforget <gforget@mit.edu>",
 )
 
-lst=("basics.jl","geography.jl","vectors.jl",
-	"dev/MeshArrays_to_Polygons.jl","dev/GeometryOps_exploration.jl")
-pth=("tutorials","tutorials","tutorials",
-	"dev","dev")
+lst=("basics.jl","geography.jl","vectors.jl","dev/exchange_methods.jl",
+	"dev/MeshArrays_to_Polygons.jl","dev/GeometryOps_exploration.jl",
+	"dev/grid_layouts.jl","dev/ocean_polygons.jl",
+    "dev/NEMO_MeridionalTransports.jl")
+pth=("tutorials","tutorials","tutorials","dev","dev","dev","dev","dev","dev")
 
 for ii in 1:length(lst)
     i=lst[ii]

diff --git a/docs/src/API.md b/docs/src/API.md
@@ -13,6 +13,13 @@ gridpath
 gridmask
 ```
 
+### Internals
+
+```@docs
+MeshArrays.InnerArray
+MeshArrays.OuterArray
+```
+
 ### More
 
 ```@docs
@@ -31,6 +38,14 @@ MeshArrays.GridSpec_MITgcm
 MeshArrays.GridSpec_ones
 ```
 
+Read / write methods :
+
+```@docs
+MeshArrays.read
+MeshArrays.read!
+MeshArrays.write
+```
+
 Loading grids :
 
 ```@docs
@@ -46,9 +61,6 @@ GridLoadVar
 Tiles
 Tiles!
 exchange
-MeshArrays.read
-MeshArrays.read!
-MeshArrays.write
 ```
 
 ## 3. Interpolation
@@ -57,8 +69,8 @@ MeshArrays.write
 interpolation_setup
 Interpolate
 InterpolationFactors
-StereographicProjection
 knn
+StereographicProjection
 ```
 
 ## 4. Vector Fields
@@ -72,39 +84,67 @@ VectorPotential
 ThroughFlow
 UVtoTransport
 UVtoUEVN
+MeshArrays.EkmanTrsp
+MeshArrays.calc_bolus
+```
+
+### Integration Paths
+
+```@docs
+LatitudeCircles
+MeshArrays.LatitudeCircle
+Transect
+edge_path
+MeshArrays.edge_mask
 ```
 
-## 5. Integration
+## 5. Integration Loop
 
 ```@docs
 Integration.loops
+Integration.streamlined_loop
+Integration.define_regions
+Integration.define_sums
 ```
 
 ## 6. Grid Data Sets
 
 ```@docs
 MeshArrays.Dataset
+```
+
+### Internals
+
+```@docs
 MeshArrays.mydatadep
 ```
 
 ## 7. Polygons
 
 ```@docs
+MeshArrays.within_pol
+MeshArrays.read_json
+MeshArrays.read_shp
 MeshArrays.NamedPolygon
 MeshArrays.polyarray
 MeshArrays.to_Polygon
 MeshArrays.to_polyarray
-MeshArrays.within_pol
-MeshArrays.read_json
-MeshArrays.read_shp
 ```
 
 ## 8. Other
 
 ```@docs
-LatitudeCircles
-Transect
+isosurface
+land_mask
 demo.ocean_basins
 demo.extended_basin
-isosurface
+```
+
+### Masked Array Utilities
+
+```@docs
+nansum
+nanmean
+nanmax
+nanmin
 ```
diff --git a/docs/src/detail.md b/docs/src/detail.md
@@ -8,6 +8,49 @@ Within a `MeshArray`, a whole Earth System Model grid is represented as an array
 
 The [basics tutorial](@ref id_Basics) illustrates how standard operations apply to `MeshArray` like as they do to common `Array`. More specialized functions and distinctive features, such as domain decomposition or plotting maps, are demo'ed in the [geography tutorial](@ref id_Geography) and [vector tutorial](@ref id_Vectors).
 
+## Exchange Methods
+
+Two families of methods connect grid cells across subdomain boundaries:
+
+**Finding neighbors** — given a position `(i, j, face)`, locate the corresponding cell in an adjacent subdomain. The top-level entry point is `update_location!`, which dispatches to grid-specific implementations:
+- `update_location_cs!` — cubed-sphere and LLC grids, via `RelocationFunctions_cs`
+- `update_location_PeriodicDomain!` — periodic tiled grids, via `NeighborTileIndices_PeriodicDomain`
+
+**Adding halo rows/columns** — `exchange` (public API) calls `exchange_main`, which wraps each face with extra rows/columns copied from neighboring subdomains, returning a `MeshArray_wh` (with halo). The per-topology implementations are:
+- `exch_T_N_cs` — cubed-sphere / LLC, using `exch_cs_target` and `exch_cs_sources` to compute source/target index ranges for each face
+- `exch_T_N_PeriodicChannel`, `exch_T_N_PeriodicDomain` — periodic topologies
+
+The [Finding and Adding Neighbors](dev/exchange_methods.html) developer notebook demonstrates these methods interactively across several grid configurations.
+
 # Background
 
 The origin of `MeshArrays.jl` is rooted in a [Matlab / Octave package](https://gcmfaces.readthedocs.io/en/latest/) called `gcmfaces`, which was introduced in [Forget et al., 2015](http://www.geosci-model-dev.net/8/3071/2015/) (`doi:10.5194/gmd-8-3071-2015`). `GCM` is an acronym for [General Circulation Model](https://en.wikipedia.org/wiki/General_circulation_model), or Global Climate Model, and `faces` can be equivalent to meshes, arrays, facets, or subdomains (these are the elements of `x.f` in a `MeshArray ` instance `x`).
+
+# Testing
+
+The test suite lives in `test/` and is split into per-topic files under `test/testsets/`. The shared setup (package imports, dataset downloads, `Demos.jl`) is in `test/setup.jl`. The top-level `test/runtests.jl` runs all testsets and is used by `Pkg.test`.
+
+The `JULIA_TESTSETS` environment variable selects a subset when running `runtests.jl` directly:
+
+```
+JULIA_TESTSETS=mesharray_basic,transport julia --project=test test/runtests.jl
+```
+
+Currently available testset names (roughly in order of importance): `mesharray_basic`, `transport`, `regional_integration`, `interpolation`, `vertical_dim`, `polygon_ops`, `plotting_makie`, `plotting_basemap`, `unitgrid`, `gridspec`, `nemo_grid`, `nanmath`, `datasets`, `doctests`.
+
+A convenience script (not part of the package) can also be used from the repository root. It activates the test environment and forwards command-line arguments as the testset filter:
+
+```julia
+import Pkg
+Pkg.activate(joinpath(@__DIR__, "MeshArrays.jl", "test"))
+
+!isempty(ARGS) && (ENV["JULIA_TESTSETS"] = join(ARGS, ","))
+
+include(joinpath(@__DIR__, "MeshArrays.jl", "test", "runtests.jl"))
+```
+
+```
+julia run_tests.jl                              # all testsets
+julia run_tests.jl transport                    # one testset
+julia run_tests.jl mesharray_basic transport    # subset
+```
diff --git a/docs/src/dev.md b/docs/src/dev.md
@@ -1,9 +1,11 @@
 
 # Developer Notebooks
 
-## [JuliaGeo](@id id_JuliaGeo)
+- [Finding and Adding Neighbors](exchange_methods.html) ([code link](https://raw.githubusercontent.com/JuliaClimate/MeshArrays.jl/master/examples/dev/exchange_methods.jl)) : methods that connect neighboring points across subdomain edges.
+- [Regular Grid Layouts](grid_layouts.html) ([code link](https://raw.githubusercontent.com/JuliaClimate/MeshArrays.jl/master/examples/dev/grid_layouts.jl)) : different ways to split a rectangular array into subdomains.
+- [NEMO Ocean Model Grid](NEMO_MeridionalTransports.html) ([code link](https://raw.githubusercontent.com/JuliaClimate/MeshArrays.jl/master/examples/dev/NEMO_MeridionalTransports.jl)) : illustrate support and vector operations on this grid (**requires data**).
 
-[The Polygons notebook](MeshArrays_to_Polygons.html) ([code link](https://raw.githubusercontent.com/JuliaClimate/MeshArrays.jl/master/examples/dev/MeshArrays_to_Polygons.jl)) illustrates how grids in `MeshArrays.jl` can be represented as sets of Polygons (2D) or LineStrings (3D) using [GeoInterface.jl](https://github.com/JuliaGeo/GeoInterface.jl).
-
-[The GeometryOps notebook](GeometryOps_exploration.html) ([code link](https://raw.githubusercontent.com/JuliaClimate/MeshArrays.jl/master/examples/dev/GeometryOps_exploration.jl)) has a few more tests with [GeometryOps.jl](https://github.com/JuliaGeo/GeometryOps.jl).
+- [Ocean Polygons](ocean_polygons.html) ([code link](https://raw.githubusercontent.com/JuliaClimate/MeshArrays.jl/master/examples/dev/ocean_polygons.jl)) ; split the global ocean using polygons (**requires data**).
+- [The Polygons notebook](MeshArrays_to_Polygons.html) ([code link](https://raw.githubusercontent.com/JuliaClimate/MeshArrays.jl/master/examples/dev/MeshArrays_to_Polygons.jl)) illustrates how grids in `MeshArrays.jl` can be represented as sets of Polygons (2D) or LineStrings (3D) using [GeoInterface.jl](https://github.com/JuliaGeo/GeoInterface.jl).
+- [The GeometryOps notebook](GeometryOps_exploration.html) ([code link](https://raw.githubusercontent.com/JuliaClimate/MeshArrays.jl/master/examples/dev/GeometryOps_exploration.jl)) has a few more tests with [GeometryOps.jl](https://github.com/JuliaGeo/GeometryOps.jl).
 
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -3,5 +3,7 @@
 `MeshArrays.jl` defines an array type that can contain / organize / distribute collections of inter-connected arrays as generally done in climate models (see [Global Grids](@ref)). Data structures defined in `MeshArrays.jl` can be used to simulate and analyze key variables of the climate system such as [particles](https://doi.org/10.21105/joss.02813) and [transports](https://doi.org/10.1038/s41561-019-0333-7).
 
 !!! note
-    [The basics tutorial](tutorials/basics.html) provides a walk through of core features. [The geography tutorial](tutorials/geography.html) deals with interpolation and mapping. [The vectors tutorial](tutorials/vectors.html) demonstrates functionalities related to vector fields and transport processes. [The JuliaClimate Notebooks](https://juliaclimate.github.io/GlobalOceanNotebooks/) link to a collection of use cases.
-
+    [The basics tutorial](tutorials/basics.html) provides a walk through of core features. [The geography tutorial](tutorials/geography.html) deals with interpolation and mapping. [The vectors tutorial](tutorials/vectors.html) demonstrates functionalities related to vector fields and transport processes. For more examples see [dev notebooks](dev/).
+
+!!! note
+    [The JuliaClimate Notebooks](https://juliaclimate.github.io/GlobalOceanNotebooks/) link to a broader collection of use cases.
diff --git a/docs/src/main.md b/docs/src/main.md
@@ -31,9 +31,9 @@ The underlying, `MeshArray`, data structure is:
 struct gcmarray{T, N} <: AbstractMeshArray{T, N}
    grid::gcmgrid
    meta::varmeta
-   f::Array{Array{T,2},N}
-   fSize::Array{NTuple{2, Int}}
-   fIndex::Array{Int,1}
+   f::OuterArray{InnerArray{T,2},N}
+   fSize::OuterArray{NTuple{2, Int}}
+   fIndex::OuterArray{Int,1}
    version::String
 end
 ```