How mllam/weather-model-graphs works
Key design intent from the README:
• The primary in-memory representation is networkx.DiGraph for as long as possible.
• Graph creation is modular/pipeline-oriented: “every step outputs a networkx.DiGraph”.
• Output formats are pluggable; one called out explicitly is PyTorch Geometric (optional extra).
File tree analysis (what the components likely are)
Top-level signals:
• src/weather_model_graphs/… → the core library
• docs/ + Jupyter Book config (docs/_config.yml, _toc.yml, many .ipynb) → documentation is a first-class artifact
• tests/ → strong expected behavior contracts (useful to infer module responsibilities)
• weather_model_graphs/create/
• archetype.py → “reference architectures” / canned graph recipes (e.g., Keisler)
• base.py → shared creation primitives / interfaces
• grid/grid.py → grid node generation + grid-related edges/attributes
• mesh/mesh.py → mesh node generation + mesh connectivity
• mesh/kinds/flat.py, mesh/kinds/hierarchical.py → strategy implementations for mesh construction
• weather_model_graphs/networkx_utils.py → graph manipulation utilities (README references split_graph_by_edge_attribute)
• weather_model_graphs/save.py → persistence / exporters (incl. to_pyg)
Create
• create.archetype.create_keisler_graph(...)
• internally:
• grid creation
• mesh creation (flat/hierarchical strategy)
• edge creation (grid↔mesh / component-labeled edges)
Utilities
• split_graph_by_edge_attribute(attr="component") → multiple component graphs
Persist/export
• save.to_pyg(graph, name, output_directory) → artifacts on filesystem
• (optionally show other potential exporters as extension points)
• Node attrs: coordinates, masks, types (grid/mesh), etc. (keep generic if not explicitly known)
• Edge attrs: component (explicitly in README)
Main components to include (checklist)
When drawing, explicitly include and label:
Core functional components
• Graph creation API: weather_model_graphs.create.*
• Grid builder: create.grid.grid
• Mesh builder: create.mesh.mesh
• Mesh “kinds” strategies: create.mesh.kinds.flat, create.mesh.kinds.hierarchical
• Graph utilities: networkx_utils (splitting, decoding masks, etc.)
• Persistence/export: save (to_pyg called out)
Primary data structures
• networkx.DiGraph as the canonical in-memory graph
• Exported formats:
• PyTorch Geometric Data (optional dependency group)
• Files on disk (directory of saved graph components)
Secondary (but valuable) SDLC components (optional lane)
• Docs: Jupyter Book (docs/ notebooks → static site)
• CI: tests, linting, PyPI deploy, docs deploy (.github/workflows/*)
• “constructs”, “transforms”, “splits”, “renders”, “serializes/exports”
Concrete interactions based on README example:
• User → create.archetype.create_keisler_graph → DiGraph
• DiGraph → networkx_utils.split_graph_by_edge_attribute → {component: DiGraph}
• Each DiGraph → save.to_pyg → Filesystem (PyG artifacts)
Optional feedback loop:
Architectural patterns/design principles to highlight
• Intermediate Representation (IR) pattern: networkx.DiGraph is the IR.
• Pipeline/modular stages: each stage outputs a DiGraph → easy debugging and substitution.
• Strategy pattern for mesh creation: mesh.kinds.flat vs mesh.kinds.hierarchical.
• Separation of concerns:
• create builds structure
• save exports
• networkx_utils transforms/queries
Technologies/frameworks to label
• Python package (src-layout, pyproject.toml, pdm)
• networkx (core)
• numpy (inputs/coords)
• Optional: torch, torch-geometric (export target)
• Jupyter Book for docs
• GitHub Actions for CI/CD (if diagramming delivery pipeline)
• User Code
→ Public API (weather_model_graphs.__init__)
→ Archetypes (create/archetype.py)
→ Grid Builder (create/grid/grid.py)
→ Mesh Builder (create/mesh/mesh.py)
→ Mesh Strategy (create/mesh/kinds/{flat,hierarchical}.py)
→ DiGraph (NetworkX)
→ Utils (networkx_utils.py) (split/transform)
→ Save/Export (save.py)
→ Filesystem / PyTorch Geometric artifacts