ecmwf · JPXKQX · Nov 22, 2024 · Jun 24, 2024 · Jun 25, 2024 · Jun 25, 2024
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -36,6 +36,8 @@ Keep it human-readable, your future self will thank you!
 - feat: Add CONTRIBUTORS.md file. (#72)
 - Fixed issue when computing area weights with scipy.Voronoi. (#79)
 
+- Create package documentation.
+
 ### Changed
 
 - ci: small fixes and updates pre-commit, downsteam-ci (#49)

diff --git a/docs/cli/inspect.rst b/docs/cli/inspect.rst
@@ -4,7 +4,8 @@
 inspect
 ========
 
-Use this command to inspect a graph stored in your filesystem.
+Use this command to inspect a graph stored in your filesystem. A set of interactive and static visualisations
+are generated to allow visual inspection of the graph design.
 
 The syntax of the recipe file is described in :doc:`building graphs <../graphs/introduction>`.
 

diff --git a/docs/graphs/edge_attributes.rst b/docs/graphs/edge_attributes.rst
@@ -20,8 +20,9 @@ coordinates.
 .. code:: yaml
 
    edges:
-     - ...
-       edge_builder: ...
+     - source_name: ...
+       target_name: ...
+       edge_builders: ...
        attributes:
          edge_length:
             _target_: anemoi.graphs.edges.attributes.EdgeLength
@@ -37,8 +38,9 @@ latitude and longitude coordinates of the source and target nodes.
 .. code:: yaml
 
    edges:
-     - ...
-       edge_builder: ...
+     - source_name: ...
+       target_name: ...
+       edge_builders: ...
        attributes:
          edge_length:
             _target_: anemoi.graphs.edges.attributes.EdgeDirection
diff --git a/docs/graphs/edges.rst b/docs/graphs/edges.rst
@@ -14,8 +14,8 @@ for each (`source name`, `target name`) pair specified.
    edges:
      - source_name: data
        target_name: hidden
-       edge_builder:
-         _target_: anemoi.graphs.edges.CutOff
+       edge_builders:
+       - _target_: anemoi.graphs.edges.CutOff
          cutoff_factor: 0.7
 
 Below are the available methods for defining the edges:
@@ -26,3 +26,19 @@ Below are the available methods for defining the edges:
    edges/cutoff
    edges/knn
    edges/multi_scale
+
+Additionally, there are 2 extra arguments (``source_mask_attr_name`` and
+``target_mask_attr_name``) that can be used in the edge configuration to
+mask source and/or target nodes. This can be useful to different use
+cases, such as Limited Area Modeling (LAM) where your decoder edges
+should only connect to the nodes in the limited area.
+
+.. code:: yaml
+
+   edges:
+     - source_name: hidden
+       target_name: data
+       edge_builders:
+       - _target_: anemoi.graphs.edges.KNNEdges
+         num_nearest_neighbours: 5
+         target_mask_attr_name: cutout
diff --git a/docs/graphs/edges/cutoff.rst b/docs/graphs/edges/cutoff.rst
@@ -39,13 +39,13 @@ YAML configuration:
    edges:
       -  source_name: source
          target_name: destination
-         edge_builder:
-            _target_: anemoi.graphs.edges.CutOffEdges
+         edge_builders:
+         -  _target_: anemoi.graphs.edges.CutOffEdges
             cutoff_factor: 0.6
 
 .. note::
 
-   The cut-off method is recommended for the encoder edges, to connect
+   The cut-off method is recommended for the encoder edge, to connect
    all data nodes to hidden nodes. The optimal ``cutoff_factor`` value
    will be the lowest value without orphan nodes. This optimal value
    depends on the node distribution, so it is recommended to tune it for

diff --git a/docs/graphs/edges/knn.rst b/docs/graphs/edges/knn.rst
@@ -1,11 +1,11 @@
-#####################
- K-Nearest Neighbors
-#####################
+######################
+ 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 destination nodes, to their ``num_nearest_neighbours``
-nearest source nodes.
+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:
@@ -14,12 +14,12 @@ YAML configuration:
 
    edges:
      -  source_name: source
-        target_name: destination
-        edge_builder:
-          _target_: anemoi.graphs.edges.KNNEdges
+        target_name: target
+        edge_builders:
+        - _target_: anemoi.graphs.edges.KNNEdges
           num_nearest_neighbours: 3
 
 .. note::
 
-   The knn method is recommended for the decoder edges, to connect all
-   data nodes with the surrounding hidden nodes.
+   The KNNEdges method is recommended for the decoder edges, to connect
+   all target nodes with the surrounding source nodes.
diff --git a/docs/graphs/edges/multi_scale.rst b/docs/graphs/edges/multi_scale.rst
@@ -5,7 +5,7 @@
 The multi-scale connections can only be defined with the same source and
 target nodes. Edges of different scales are defined based on the
 refinement level of an icosahedron. The higher the refinement level, the
-shorter the length of the edges. By default, all possible refinements
+shorther the length of the edges. By default, all possible refinements
 levels are considered.
 
 To use this method to build your connections, you can use the following
@@ -16,8 +16,8 @@ YAML configuration:
    edges:
      -  source_name: source
         target_name: source
-        edge_builder:
-          _target_: anemoi.graphs.edges.MultiScaleEdges
+        edge_builders:
+        - _target_: anemoi.graphs.edges.MultiScaleEdges
           x_hops: 1
 
 where `x_hops` is the number of hops between two nodes of the same
@@ -28,8 +28,12 @@ refinement level to be considered neighbours, and then connected.
    This method is used by data-driven weather models like GraphCast to
    process the latent/hidden state.
 
+.. csv-table:: Triangular refinements specifications (x_hops=1)
+   :file: ./tri_refined_edges.csv
+   :header-rows: 1
+
 .. warning::
 
-   This connection method is only supported for building the connections
+   This connection method is only support for building the connections
    within a set of nodes defined with the ``TriNodes`` or ``HexNodes``
    classes.
diff --git a/docs/graphs/edges/tri_refined_edges.csv b/docs/graphs/edges/tri_refined_edges.csv
@@ -0,0 +1,8 @@
+Refinement,Num Nodes,Num Edges,Num Multilevel Edges
+0,12,60,60
+1,42,240,300
+2,162,960,1260
+3,642,3840,5100
+4,2562,15360,20460
+5,10242,61440,81900
+6,40962,245760,327660
diff --git a/docs/graphs/introduction.rst b/docs/graphs/introduction.rst
@@ -65,6 +65,7 @@ following classes define different behaviour:
 
 -  :doc:`node_coordinates/zarr_dataset`
 -  :doc:`node_coordinates/npz_file`
+-  :doc:`node_coordinates/icon_mesh`
 -  :doc:`node_coordinates/tri_refined_icosahedron`
 -  :doc:`node_coordinates/hex_refined_icosahedron`
 -  :doc:`node_coordinates/healpix`

diff --git a/docs/graphs/node_attributes.rst b/docs/graphs/node_attributes.rst
@@ -21,3 +21,12 @@ nodes.
    :maxdepth: 1
 
    node_attributes/weights
+   node_attributes/zarr_attribute
+
+Additionally, different boolean operations have been implemented to
+support more complex use cases:
+
+.. toctree::
+   :maxdepth: 1
+
+   node_attributes/boolean_operations
diff --git a/docs/graphs/node_attributes/boolean_operations.rst b/docs/graphs/node_attributes/boolean_operations.rst
@@ -0,0 +1,12 @@
+####################
+ Boolean operations
+####################
+
+_anemoi-graphs_ package implements a set of boolean opearations to
+support these operations when defining node attributes. Below, an
+attribute `mask` is computed as the intersection of two other masks,
+that are generated as the non-missing values in 2 different variables in
+a Zarr dataset.
+
+.. literalinclude:: ../yaml/attributes_boolean_operation.yaml
+   :language: yaml
diff --git a/docs/graphs/node_attributes/weights.rst b/docs/graphs/node_attributes/weights.rst
@@ -2,7 +2,7 @@
  Weights
 #########
 
-The `weights` are a node attribute useful for defining the importance of
+The `weights` are node attributes useful for defining the importance of
 a node in the loss function. You can set the weights to follow an
 uniform distribution or to match the area associated with that node.
 

diff --git a/docs/graphs/node_attributes/zarr_attribute.rst b/docs/graphs/node_attributes/zarr_attribute.rst
@@ -0,0 +1,18 @@
+###################
+ From Zarr dataset
+###################
+
+Zarr datasets are the standard format to define data nodes in
+_anemoi-graphs_. The user can define node attributes based on a zarr
+dataset variable. For example, the following recipe will define an
+attribute `land_mask` based on the _lsm_ variable of the dataset.
+
+.. literalinclude:: ../yaml/attributes_nonmissingzarr.yaml
+   :language: yaml
+
+In addition, if an user is using "cutout" operation to build their
+dataset, it may be helpful to create a `cutout_mask` to track the
+provenance of the resulting nodes. An example is shown below:
+
+.. literalinclude:: ../yaml/attributes_cutout.yaml
+   :language: yaml
diff --git a/docs/graphs/node_coordinates.rst b/docs/graphs/node_coordinates.rst
@@ -24,6 +24,7 @@ a file:
 
    node_coordinates/zarr_dataset
    node_coordinates/npz_file
+   node_coordinates/icon_mesh
 
 or based on other algorithms. A commonn approach is to use an
 icosahedron to project the earth's surface, and refine it iteratively to

diff --git a/docs/graphs/node_coordinates/healpix.rst b/docs/graphs/node_coordinates/healpix.rst
@@ -10,7 +10,7 @@ to the number of refinements of the sphere.
 .. code:: yaml
 
    nodes:
-     data:
+     data:  # name of the nodes
        node_builder:
          _target_: anemoi.graphs.nodes.HEALPixNodes
          resolution: 3

diff --git a/docs/graphs/node_coordinates/hex_refined_icosahedron.rst b/docs/graphs/node_coordinates/hex_refined_icosahedron.rst
@@ -4,32 +4,56 @@
 
 This method allows us to define the nodes based on the Hexagonal
 Hierarchical Geospatial Indexing System, which uses hexagons to divide
-the sphere. Each refinement level divides each hexagon into seven
-smaller hexagons.
+the sphere. With each refinement, each hexagon into seven smaller
+hexagons.
 
 To define the `node coordinates` based on the hexagonal refinements of
 an icosahedron, you can use the following YAML configuration:
 
+***************
+ Global graphs
+***************
+
+The class `HexNodes` allows us to define the nodes over the entire
+globe.
+
 .. code:: yaml
 
    nodes:
-     data:
+     hidden: # name of the nodes
        node_builder:
          _target_: anemoi.graphs.nodes.HexNodes
          resolution: 4
        attributes: ...
 
-where resolution is the number of refinements to be applied.
+where `resolution` is the number of refinements to be applied.
+
+*********************
+ Limited Area graphs
+*********************
+
+The class `LimitedAreaHexNodes` allows us to define the nodes only for a
+specific area of interest.
+
+.. code:: yaml
+
+   nodes:
+     hidden: # name of the nodes
+       node_builder:
+         _target_: anemoi.graphs.nodes.LimitedAreaHexNodes
+         resolution: 4
+         reference_node_name: nodes_name
+         mask_attr_name: mask_name  # optional
+         margin_radius_km: 100  # optional
+       attributes: ...
+
+where `reference_node_name` is the name of the nodes to define the area
+of interest.
 
 .. csv-table:: Hexagonal Hierarchical refinements specifications
    :file: ./hex_refined.csv
    :header-rows: 1
 
-Note that the refinement level is the parameter used to control the
-resolution of the nodes, but the resolution also depends on the
-refinement method. Then, for the same refinement level, ``HexNodes``
-will have a higher resolution than ``TriNodes``.
-
 .. warning::
 
    This class will require the `h3 <https://h3.org>`_ package to be

diff --git a/docs/graphs/node_coordinates/icon_mesh.rst b/docs/graphs/node_coordinates/icon_mesh.rst
@@ -47,7 +47,6 @@ following YAML example:
        node_builder:
          _target_: anemoi.graphs.nodes.ICONCellGridNodes
          icon_mesh: "icon_mesh"
-       attributes: ${graph.attributes.nodes}
      # Hidden nodes
      hidden:
        node_builder:
@@ -56,9 +55,8 @@ following YAML example:
 
    edges:
      # Processor configuration
-     - source_name: ${graph.hidden}
-       target_name: ${graph.hidden}
-       edge_builder:
-         _target_: anemoi.graphs.edges.ICONTopologicalProcessorEdges
+     - source_name: "hidden"
+       target_name: "hidden"
+       edge_builders:
+       - _target_: anemoi.graphs.edges.ICONTopologicalProcessorEdges
          icon_mesh: "icon_mesh"
-       attributes: ${graph.attributes.edges}
diff --git a/docs/graphs/node_coordinates/npz_file.rst b/docs/graphs/node_coordinates/npz_file.rst
@@ -8,13 +8,13 @@ following YAML configuration:
 .. code:: yaml
 
    nodes:
-     data:
+     data: # name of the nodes
        node_builder:
          _target_: anemoi.graphs.nodes.NPZFileNodes
-         grids_definition_path: /path/to/folder/with/grids/
+         grid_definition_path: /path/to/folder/with/grids/
          resolution: o48
 
-where `grids_definition_path` is the path to the folder containing the
+where `grid_definition_path` is the path to the folder containing the
 grid definition files and `resolution` is the resolution of the grid to
 be used.
 

diff --git a/docs/graphs/node_coordinates/tri_nodes.csv b/docs/graphs/node_coordinates/tri_nodes.csv
@@ -0,0 +1,8 @@
+Refinement,Num Nodes,Num Faces,Avg. Area (sq km)
+0,12,20,25503600
+1,42,80,6375900
+2,162,320,1593975
+3,642,1280,398494
+4,2562,5120,99623
+5,10242,20480,24905
+6,40962,81920,6226