feat/migrate-graph-creation-to-torch

graphs/CHANGELOG.md

@@ -21,8 +21,15 @@ Keep it human-readable, your future self will thank you!
 
 ### Changed
 
+### Changed
+
+- docs: Documentation structure (#84)
 - fix: faster edge builder for tri icosahedron. (#92)
 
+### Added
+
+- feat: Support for multi-dimensional node attributes in plots (#86)
+
 ## [0.4.1 - ICON graphs, multiple edge builders and post processors](https://github.com/ecmwf/anemoi-graphs/compare/0.4.0...0.4.1) - 2024-11-26
 
 ### Added
@@ -33,7 +40,7 @@ Keep it human-readable, your future self will thank you!
 - feat: Define node sets and edges based on an ICON icosahedral mesh (#53)
 - feat: Support for multiple edge builders between two sets of nodes (#70)
 
-# Changed
+### Changed
 
 - fix: bug when computing area weights with scipy.Voronoi. (#79)
 
@@ -46,6 +53,7 @@ Keep it human-readable, your future self will thank you!
 - feat: New class, KNNAreaMaskBuilder, to specify Area of Interest (AOI) based on a set of nodes. (#30)
 - feat: New node builder classes, LimitedAreaXXXXXNodes, to create nodes within an Area of Interest (AOI). (#30)
 - feat: Expanded MultiScaleEdges to support multi-scale connections in limited area graphs. (#30)
+- feat: New edge attribute, Azimuth. (#54)
 - feat: New method update_graph(graph) in the GraphCreator class. (#60)
 - feat: New class StretchedTriNodes to create a stretched mesh. (#51)
 - feat: Expanded MultiScaleEdges to support multi-scale connections in stretched graphs. (#51)
@@ -59,6 +67,8 @@ Keep it human-readable, your future self will thank you!
 ### Changed
 
 - ci: small fixes and updates pre-commit, downsteam-ci (#49)
+- feat: Implementing KNNEdges and CutOffEdges with torch-cluster (#54)
+- feat: Migrate edge attributes to inherit from MessagePassing (#54)
 - Update CODEOWNERS (#61)
 - ci: extened python versions to include 3.11 and 3.12 (#66)
 - Update copyright notice (#67)

graphs/docs/cli/introduction.rst

@@ -1,29 +1,78 @@
 .. _cli-introduction:
 
-=============
-Introduction
-=============
+=================
+Command line tool
+=================
 
-When you install the `anemoi-graphs` package, this will also install command line tool
-called ``anemoi-graphs`` which can be used to design and inspect weather graphs.
+When you install the `anemoi-graphs` package, a command line tool will also be installed
+called ``anemoi-graphs``, which can be used to build graphs based on YAML recipe files,
+and inspect existing graphs.
 
 The tool can provide help with the ``--help`` options:
 
 .. code-block:: bash
 
     % anemoi-graphs --help
 
-The commands are:
+To **create** a graph, use the ``create`` command:
 
-.. toctree::
-    :maxdepth: 1
+.. code:: console
 
-    create
-    describe
-    inspect
+   $ anemoi-graphs create recipe.yaml graph.pt
 
+The ``.yaml`` recipe file consists of high-level specifications for generating the graphs at each
+layer. An example of a simple recipe file is given in the :ref:`the following section <usage-getting-started>`.
+
+The ``create`` command will read the specifications in the ``recipe.yaml`` recipe file, and write to a PyTorch
+``.pt`` file.
+
+To **describe** an existing graph stored as a ``.pt`` file, use the ``describe`` command:
+
+.. code:: console
+
+   $ anemoi-graphs describe graph.pt
+
+This will generate a text summary of the graph, including the number of nodes and edges
+at each layer, the geographic boundaries, and statistics about the edge lengths:
+
+.. literalinclude:: ../usage/yaml/global_wo-proc.txt
+   :language: console
+
+A set of interactive and static visualisations are generated to allow visual inspection
+of the graph design.
+
+Finally, the ``inspect`` command will generate a set of interactive and static visualisations
+for visual inspection of the graph design:
+
+.. code:: console
+
+   $ anemoi-graphs inspect graph.pt output_folder/
+
+===================
+Command line usage
+===================
+
+Create Command
+--------------
+
+.. argparse::
+    :module: anemoi.graphs.__main__
+    :func: create_parser
+    :prog: anemoi-graphs
+    :path: create
+
+Describe Command
+----------------
+.. argparse::
+    :module: anemoi.graphs.__main__
+    :func: create_parser
+    :prog: anemoi-graphs
+    :path: describe
+
+Inspect Command
+---------------
 .. argparse::
     :module: anemoi.graphs.__main__
     :func: create_parser
     :prog: anemoi-graphs
-    :nosubcommands:
+    :path: inspect

graphs/docs/graphs/edge_attributes.rst

@@ -4,8 +4,8 @@
  Edges - Attributes
 ####################
 
-There are 2 main edge attributes implemented in the `anemoi-graphs`
-package:
+There are two main edge attributes implemented in the
+:ref:`anemoi-graphs <anemoi-graphs:index-page>` package:
 
 *************
  Edge length

graphs/docs/graphs/edges/cutoff.rst

@@ -1,9 +1,11 @@
+.. _cutoff_radius:
+
 ################
  Cut-off radius
 ################
 
-The cut-off method is a method for establishing connections between two
-sets of nodes. Given two sets of nodes, (`source`, `target`), the
+The *cut-off method* is a method for establishing connections between
+two sets of nodes. Given two sets of nodes, (`source`, `target`), the
 cut-off method connects all source nodes, :math:`V_{source}`, in a
 neighbourhood of the target nodes, :math:`V_{target}`.
 
@@ -16,20 +18,20 @@ as,
 
 .. math::
 
-   cutoff\_radius = cuttoff\_factor \times nodes\_reference\_dist
+   \text{cutoff_radius} = \text{cutoff_factor} \times \text{nodes_reference_dist}
 
-where :math:`nodes\_reference\_dist` is the maximum distance between a
-target node and its nearest source node.
+where :math:`\text{nodes_reference_dist}` is the maximum distance
+between a target node and its nearest source node.
 
 .. math::
 
-   nodes\_reference\_dist = \max_{x \in V_{target}} \left\{  \min_{y \in V_{source}, y \neq x} \left\{ d(x, y) \right\} \right\}
+   \text{nodes_reference_dist} = \max_{x \in V_{target}} \left\{  \min_{y \in V_{source}, y \neq x} \left\{ d(x, y) \right\} \right\}
 
 where :math:`d(x, y)` is the `Haversine distance
 <https://en.wikipedia.org/wiki/Haversine_formula>`_ between nodes
-:math:`x` and :math:`y`. The ``cutoff_factor`` is a parameter that can
-be adjusted to increase or decrease the size of the neighbourhood, and
-consequently the number of connections in the graph.
+:math:`x` and :math:`y`. The :math:`\text{cutoff_factor}` is a parameter
+that can be adjusted to increase or decrease the size of the
+neighbourhood, and consequently the number of connections in the graph.
 
 To use this method to create your connections, you can use the following
 YAML configuration:

graphs/docs/graphs/edges/knn.rst

@@ -1,11 +1,13 @@
+.. _knn:
+
 ######################
  K-Nearest Neighbours
 ######################
 
-The knn method is a method for establishing connections between two sets
-of nodes. Given two sets of nodes, (`source`, `target`), the knn method
-connects all target nodes, to their ``num_nearest_neighbours`` nearest
-source nodes.
+The k-nearest neighbours (KNN) method is a method for establishing
+connections between two sets of nodes. Given two sets of nodes,
+(`source`, `target`), the KNN method connects all target nodes to their
+``num_nearest_neighbours`` nearest source nodes.
 
 To use this method to build your connections, you can use the following
 YAML configuration:
@@ -21,5 +23,5 @@ YAML configuration:
 
 .. note::
 
-   The KNNEdges method is recommended for the decoder edges, to connect
-   all target nodes with the surrounding source nodes.
+   The ``KNNEdges`` method is recommended for the decoder edges, to
+   connect all target nodes with the surrounding source nodes.

graphs/docs/graphs/edges/multi_scale.rst

@@ -1,3 +1,5 @@
+.. _multi_scale:
+
 ################################################
  Multi-scale connections at refined icosahedron
 ################################################