Command line tool

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:

% anemoi-graphs --help

To create a graph, use the create command:

$ 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 the following section.

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:

$ 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:

┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
📦 Path          : graph.pt
🔢 Format version: 0.0.1

💽 Size       : 3.1 MiB (3,283,650)

   Nodes name  │ Num. nodes | Attribute dim | Min. latitude | Max. latitude | Min. longitude | Max. longitude
  ─────────────┼────────────┼───────────────┼───────────────┼───────────────┼────────────────┼────────────────
    data       |     10,840 |             4 |        -3.135 |         3.140 |           0.02 |          6.13
    hidden     |      6,200 |             4 |        -3.141 |         3.137 |           0.01 |          6.14
  ─────────────┴────────────┴───────────────┴───────────────┴───────────────┴────────────────┴────────────────


   Source      │ Destination  │ Num. edges  │ Attribute dim | Min. length │ Max. length │ Mean length │ Std dev
  ─────────────┼──────────────┼─────────────┼───────────────┼─────────────┼─────────────┼─────────────┼─────────
    data       │ hidden       │       13508 │             1 |      0.3116 │       25.79 │   11.059531 │   5.5856
    hidden     │ data         │       40910 │             1 |      0.2397 │      21.851 │   12.270924 │   4.2347
  ─────────────┴──────────────┴─────────────┴───────────────|─────────────┴─────────────┴─────────────┴─────────
🔋 Graph ready, last update 17 seconds ago.
📊 Statistics ready.

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:

$ anemoi-graphs inspect graph.pt output_folder/

Here is an example of an interactive plot of the processor generated by inspect. These processor edges are defined with anemoi.graphs.edges.MultiScaleEdges edge builder.

Command line usage

Create Command

Create a graph.

usage: anemoi-graphs create [-h] [--overwrite]
                            [--description | --no-description]
                            config save_path

Positional Arguments

config: Configuration yaml file path defining the recipe to create the graph.
save_path: Path to store the created graph.

Named Arguments

--overwrite

Overwrite existing files. This will delete the target graph if it already exists.

Default: False

--description, --no-description

Show the description of the graph.

Default: True

Describe Command

Describe a graph.

usage: anemoi-graphs describe [-h] graph_file

Positional Arguments

graph_file: Path to the graph (a .PT file).

Inspect Command

Command not available.

usage: anemoi-graphs inspect [-h] ...

Positional Arguments

x

Export To Sparse Command

Export a graph edges to a sparse format.

Example usage specifying an edge attribute: ` anemoi-graphs export-to-sparse graph.pt output_path --edge-attribute-name edge_attr `

Example usage specifying a subset of edges: ` anemoi-graphs export-to-sparse graph.pt output_path --edges-name data down --edges-name down data `

usage: anemoi-graphs export_to_sparse [-h]
                                      [--edge-attribute-name EDGE_ATTRIBUTE_NAME]
                                      [--edges-name NODE1 NODE2]
                                      graph output_path

Positional Arguments

graph: Path to the graph (a .PT file) or a config file defining the graph.
output_path: Path to store the inspection results.

Named Arguments

--edge-attribute-name: Name of the edge attribute to export.
--edges-name: Specify an edge by its two node names. Can be used multiple times.