You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Guidance for Claude Code when working with this repository.
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
4
5
5
## Project Overview
6
6
7
-
ConservativeRegridding.jl performs area-weighted conservative regridding between polygon grids. "Conservative" means the area-weighted mean is preserved. The package computes intersection areas between source/destination grid cell pairs to create averaging weights.
7
+
ConservativeRegridding.jl performs area-weighted conservative regridding between polygon grids on planes or spheres. "Conservative" means the area-weighted mean is preserved during regridding. The package computes intersection areas between source/destination grid cell pairs, stores them as a sparse matrix, and uses that matrix for fast forward and backward regridding.
8
8
9
9
## Common Commands
10
10
11
-
**Important**: Always use `julia --project=docs` when running scripts to access all dependencies.
11
+
**Important**: Always use `julia --project=docs` when running scripts and investigating — the docs environment has diagnostic packages not available in test.
12
12
13
13
```bash
14
14
# Run all tests
@@ -22,89 +22,92 @@ julia --project=test -e 'include("test/usecases/simple.jl")'
22
22
julia --project=test -e 'include("test/trees/grids.jl")'
23
23
julia --project=test -e 'include("test/trees/quadtree_cursors.jl")'
24
24
25
-
# Start Julia REPL with the package loaded
25
+
# Run examples/scripts or load the package interactively
26
+
julia --project=docs examples/speedy_to_speedy.jl
26
27
julia --project=docs -e 'using ConservativeRegridding'
27
28
```
28
29
29
-
The project uses separate Project.toml files in `test/`, `docs/`, and `examples/`.
30
+
The repo uses Julia's workspace feature (`[workspace]` in Project.toml) with separate environments in `test/`, `docs/`, and `examples/`.
30
31
31
32
## Architecture
32
33
33
-
### Core Types and Functions
34
+
### Three-Layer Design
34
35
35
-
**`Regridder`** (`src/regridder/regridder.jl`): Main type storing intersection areas as a sparse matrix, grid cell areas, and work arrays.
36
+
```
37
+
Regridder (sparse matrix + area vectors)
38
+
↓ constructed by
39
+
Intersection Areas (dual DFS candidate search + parallel intersection computation)
40
+
↓ operates on
41
+
Trees Module (grid representations + quadtree cursors for spatial indexing)
42
+
```
36
43
37
-
-`transpose(regridder)` returns a regridder for the reverse direction (shares underlying data)
38
-
-`normalize!` scales the intersection matrix by its maximum value
**`regrid!`** (`regrid.jl`): `dst = (A * src) / dst_areas`. Handles dense and non-contiguous arrays, copies to temporary arrays when needed for BLAS performance.
47
52
48
-
**`DefaultIntersectionOperator(manifold)`**: Dispatches to the appropriate intersection algorithm:
-`QuadtreeCursor`: Cursor with explicit index ranges
74
-
-`TopDownQuadtreeCursor`: Top-level cursor wrapping a grid
75
-
Sit on top of `AbstractCurvilinearGrid`s to provide quadtree descent.
78
+
**Wrappers** (`wrappers.jl`):
79
+
-`KnownFullSphereExtentWrapper`: Returns full-sphere extent to skip expensive extent computation
80
+
-`CubedSphereToplevelTree`: Vector of per-face cursors with global indexing
76
81
77
-
**Wrappers** (`src/trees/wrappers.jl`):
78
-
-`KnownFullSphereExtentWrapper`: Avoids expensive extent computation for full-sphere trees
82
+
**`treeify(manifold, grid)`** (`interfaces.jl`): Dispatches input to the right tree type:
83
+
- Matrices of polygons → `TopDownQuadtreeCursor(ExplicitPolygonGrid(...))`
84
+
- Matrices of points → `TopDownQuadtreeCursor(CellBasedGrid(...))`
85
+
- Iterables of polygons → `FlatNoTree`
86
+
- Tuple of vectors → `TopDownQuadtreeCursor(RegularGrid(...))`
87
+
- Existing spatial trees → pass-through
79
88
80
89
### Manifold Support
81
90
82
91
Grids operate on manifolds from GeometryOps:
83
92
-`Planar()`: Cartesian 2D, uses `Extents.Extent` for bounding boxes
84
93
-`Spherical()`: Unit sphere (lon/lat), uses `SphericalCap` for bounding regions
85
94
86
-
The manifold affects extent computation, intersection algorithms, and area calculations.
95
+
The manifold affects extent computation, intersection algorithms, and area calculations. If source and destination have different manifolds, it promotes to Spherical.
87
96
88
97
### Multithreading
89
98
90
-
`multithreaded_dual_depth_first_search` (`src/utils/MultithreadedDualDepthFirstSearch.jl`) provides parallel tree traversal, spawning tasks when nodes satisfy an area criterion.
`multithreaded_dual_query` (`src/utils/MultithreadedDualDepthFirstSearch.jl`): Parallel dual-tree traversal. Spawns tasks when both nodes are leaves or when nodes satisfy an area criterion (avoids spawning excessive tasks for small regions). Intersection area computation is separately parallelized via ChunkSplitters partitioning.
97
100
98
-
### Key Dependencies
101
+
### Package Extensions (`ext/`)
99
102
100
-
-**GeometryOps**: Polygon intersection, area calculations, `SpatialTreeInterface`
101
-
-**GeoInterface**: Geometry type wrappers
102
-
-**SparseArrays**: Sparse matrix storage for intersection weights
All follow the same pattern: implement `Trees.treeify()` for domain-specific grid types.
104
104
105
-
### Mathematical Model
105
+
-**OceananigansExt**: LatitudeLongitudeGrid, RectilinearGrid, TripolarGrid → vertex matrices wrapped in KnownFullSphereExtentWrapper
106
+
-**ClimaCoreExt**: Cubed sphere topologies → per-face cursors with index remapping
107
+
-**HealpixExt**, **RingGridsExt**: HEALPix and SpeedyWeather grids
108
+
-**SpeedyWeatherExt**: Requires *both* RingGrids and SpeedyWeather loaded (dual weak dependency)
109
+
-**InterfacesExt**: Interfaces.jl contracts
106
110
107
-
Given intersection matrix A, source field s, destination field d, and area vectors a_d, a_s:
108
-
- Forward: `d = (A * s) / a_d`
111
+
### API Surface
109
112
110
-
Grid cell areas are derived from row/column sums of A when grids fully overlap.
113
+
The package uses `@public`from SciMLPublic for API visibility: `Regridder`, `regrid`, `regrid!`, `areas` are public. Grid types and tree types are exported.
0 commit comments