Dependency graph

1The graph¶

The diagram folds packages into repositories: pipekit’s seven packages are one box, so are geotoolz’s five, xrtoolz’s six and pyrox’s four. Each arrow reads “imports or depends on”.

18 repositories, 37 packages and 29 dependencies between repositories, from each submodule’s pyproject.toml and imports. Solid arrows are base dependencies or imports, dashed ones extras; an arrow a longer path implies is not drawn. Dev, docs and tutorial dependency groups are not library dependencies and are left out. Red arrows form a cycle.

What it shows:

• Every edge between layers points down. GeoModels uses GeoML, GeoNumerics and GeoStack. GeoML uses GeoNumerics and GeoStack. GeoNumerics uses nothing above it.

• gaussx is the foundation. Every repository in GeoNumerics, GeoML and GeoModels except geonnax reaches it. A breaking change in gaussx is a change to almost the whole stack.

• plumax is the one GeoModels repository that imports another. It builds on radtrax: plume physics uses radiative transfer, never the reverse (package boundaries, rule 2). somax imports no one in its layer.

• The one cycle is inside GeoStack (in red): pipekit-train imports geopatcher.time from geotoolz-patcher, and geotoolz depends on pipekit. The import is lazy and behind a try, so nothing fails at install time, but the two repositories can no longer be released, tested or reasoned about separately.

2The rules¶

Each rule is a check in scripts/dependency_graph.py. The name in brackets is the rule’s name in Table 2.

1. Layers point down (upward). A repository may depend on its own layer or a lower one: GeoStack and GeoNumerics at the bottom, GeoML above them, GeoModels on top. GeoStack and GeoNumerics never import each other.

2. Within a layer, tiers point down (tier). Each repository has a tier in its layer (Table 1) and imports only repositories of a lower tier. Two repositories of the same tier never import each other. In GeoModels, radtrax and somax share tier 0 and plumax sits above them in tier 1, because its plume-to-radiance coupling composes a plume model with radtrax’s forward model.

3. Every library edge counts. Base dependencies, extras, and imports, whether at module level, inside a function, behind a try or under TYPE_CHECKING, all go into the graph. An optional edge is still an edge, and optional edges are where cycles hide: the one cycle today is a lazy, guarded import. Dependency groups (dev, docs, tutorials) are not: they install tools for working on the repository, not the library, so a tutorial may use a library above it.

4. No cycles (cycle, package-cycle): not between repositories, and not between the packages of one workspace (pipekit’s, geotoolz’s, xrtoolz’s, pyrox’s).

5. Every import is declared (undeclared), as a base dependency or an extra. An extra suits an optional module (one the package’s __init__ does not import) or a lazy or guarded import; whatever import <package> runs needs a base dependency. A TYPE_CHECKING-only import needs no declaration but still obeys rules 1 and 2. Code the package ships never relies on a dependency group. The one way out is UNDECLARED_OK in scripts/dependency_graph.py: a guarded integration with a library that cannot be installed beside the package, listed with its reason.

6. A reverse edge is fixed by moving code, never by a shim. When a lower repository needs something from a higher one, either the primitive moves down into the lower one, or the adapter moves up into the higher one (as an integrations/ module behind an extra). A moved name leaves no re-export behind: its old path raises an ImportError naming its new home, because a re-export is a reverse edge (Package boundaries).

7. A third-party repository is a leaf (third-party). georeader belongs to spaceml-org: we depend on it and never change it, and nothing of ours moves into it.

8. A new repository arrives with its place (untiered, stale-tier). Adding a submodule means adding it to TIERS in scripts/dependency_graph.py with its layer and tier, in the same pull request, and removing or renaming one means changing its entry there too.

3Layers and tiers¶

The tiers follow what each repository is for, not only the edges it has today. filterax could sit lower, since it imports only gaussx; it sits at tier 2 so that vardax, alone at tier 3, may build on it and never the other way round. The two already overlap: each has its own observation operators (filterax’s AbstractObsOperator and LinearizableObsOperator, vardax’s LinearObs, InterpObs and MaskedIdentity), adjoint strategies and dynamics wrappers, and vardax’s ensemble posterior already defers to filterax. A hybrid ensemble–variational scheme builds vardax’s background covariance from a filterax ensemble; nothing in filterax needs a variational solver. So the shared vocabulary belongs in filterax, and vardax reuses it (open question 1).

4Where the graph breaks the rules today¶

The fixes:

1. Move pipekit-train’s window dataset into geotoolz-patcher (geopatcher.integrations.train, behind geotoolz-patcher[train]). This is Report 16’s step D2, and rule 6’s “move the adapter up”. It removes the cycle, the tier break and the two undeclared imports, which are four rows for one dataset. The imports are broken anyway: geotoolz-patcher has geopatcher.temporal, not geopatcher.time.

2. Make somax’s filterax import an extra. somax/_src/da imports filterax at module level, but somax declares filterax only in its da dependency group, so pip install somax gives a package whose da module cannot import. A [da] extra with filterax and vardax fixes it.

gauss_flows’s guarded gaussx import stays undeclared, as an exception in UNDECLARED_OK. gaussx is not on PyPI, and gauss_flows’s [interp] extra (interpax) caps lineax below what gaussx needs. Tried as a [gaussx] extra, it forked the lock and moved the plain install to a jax that its numpyro cannot import, so most of its tests could no longer be collected.

5Open questions¶

1. Do vardax’s observation operators and dynamics move to filterax, or to a smaller shared package below both? Tier order decides only which may import which. Moving the shared types into filterax is the smallest step; a separate package is worth it only if a third library (somax’s da module, a future smoother) needs them without either engine.

2. May pyrox and filterax import each other? They share tier 2. A GP-based observation model in filterax, or an ensemble likelihood in pyrox, would need one of them moved; no code asks for it today.

6Upcoming work¶

7Every edge¶