From da35db638c3e85fff8690790028daf78db019041 Mon Sep 17 00:00:00 2001 From: Leif Denby Date: Tue, 21 May 2024 17:31:38 +0200 Subject: [PATCH] remove duplicate text in design section of doc (#14) * remove duplicate text in design section of doc * fix links in readme * more readme links --- README.md | 5 ++--- docs/design.ipynb | 33 ++------------------------------- 2 files changed, 4 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 7542076..1bad217 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ `weather-model-graphs` is a package for creating, visualising and storing message-passing graphs for data-driven weather models. The package is designed to use `networkx.DiGraph` objects as the primary data structure for the graph representation right until the graph is to be stored on disk into a specific format. -This makes the graph generation process modular (every step outputs a `networkx.DiGraph`), easy to debug (visualise the graph at any step) and allows output to different file-formats and file-structures to be easily implemented. More details are given in the [background and design](#background-and-design) section below. +This makes the graph generation process modular (every step outputs a `networkx.DiGraph`), easy to debug (visualise the graph at any step) and allows output to different file-formats and file-structures to be easily implemented. More details are given in the [background](https://mllam.github.io/weather-model-graphs/background.html) and [design](https://mllam.github.io/weather-model-graphs/design.html) section of the online [documentation](https://mllam.github.io/weather-model-graphs/). ## Installation @@ -31,8 +31,7 @@ pdm install --group pytorch # Usage -The best way to understand how to use `weather-model-graphs` is to look at the [notebooks/constructing_the_graph.ipynb](notebooks/constructing_the_graph.ipynb) notebook, to have look at the tests in [tests/](tests/) or simply to read through the source code. -In addition you can read the [background and design](#background-and-design) section below to understand the design principles of `weather-model-graphs`. +The best way to understand how to use `weather-model-graphs` is to look at the [documentation](https://mllam.github.io/weather-model-graphs) (which are executable Jupyter notebooks!), to have look at the tests in [tests/](tests/) or simply to read through the source code. ## Example, Keisler 2021 flat graph architecture diff --git a/docs/design.ipynb b/docs/design.ipynb index fea6498..7ff8b12 100644 --- a/docs/design.ipynb +++ b/docs/design.ipynb @@ -4,36 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Design\n", - "\n", - "The only input the graph generation in `weather-model-graphs` requires is the static `(x,y)` *grid* coordinates of the atmospheric state as the state changes over time. These coordinates are used to create the **grid nodes** nodes of the graph, with a node for each `(x,y)` coordinate.\n", - "In addition to grid nodes the graph also contains **mesh nodes** that represent the latent space of the model at a set of `(x,y)` coordinates (this is in general a different set of coordinates to the **grid nodes** coordinates).\n", - "\n", - "In summary, there are two sets of nodes in the graph:\n", - "\n", - "- **grid nodes**: representing the physical variables of the atmospheric state at a specific `(x,y)` coordinate\n", - "\n", - "- **mesh nodes**: representing the latent space of the model at specific `(x,y)` coordinate\n", - "\n", - "With these two sets of nodes, the graph is constructed by connecting the **grid nodes** to the **mesh nodes** and the **mesh nodes** to each other.\n", - "The edges between the **grid nodes** and the **mesh nodes** represent the encoding of the physical variables into the latent space of the model, while the edges between the **mesh nodes** represent the processing of the latent space through the time evolution of the atmospheric state.\n", - "\n", - "In summary, the complete message-passing graph consists of three components:\n", - "\n", - "- **grid-to-mesh** (`g2m`): the encoding compenent, where edges represent the encoding of physical variables into the latent space of the model\n", - "\n", - "- **mesh-to-mesh** (`m2m`): the processing component, where edges represent information flow between nodes updating the latent presentation at mesh nodes through the time evolution of the atmospheric state\n", - "\n", - "- **mesh-to-grid** (`m2g`): the decoding component, where edges represent the decoding of the latent space back into physical variables\n", - "\n", - "Practically, the **mesh-to-grid** and **grid-to-mesh** updates can probably also encode some of the time evolution processing, in addition to the latent space encoding/decoding, unless the GNN is trained specifically as an auto-encoder using the same graph as input and output.\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Design principles\n", + "# Design principles\n", "\n", "The key design principle of `weather-model-graphs` is to work with `networkx.DiGraph` objects as the primary data structure for the graph representation right until the graph is to be stored on disk into a specific format.\n", "Using only `networkx.DiGraph` objects as the intermediate representations makes it possible to\n", @@ -69,7 +40,7 @@ } }, "source": [ - "### Diagram of the graph generation process:\n", + "## Diagram of the graph generation process:\n", "\n", "Below, the graph generation process is visualised in `weather-model-graphs` for the example given above:\n", "\n",