diff --git a/api/info.yaml b/api/info.yaml index 41d1e27..96e95d3 100644 --- a/api/info.yaml +++ b/api/info.yaml @@ -20,7 +20,7 @@ info: Contributions to the API and models schema can be made in the following ways: - [open an issue](https://github.com/keysight/infragraph/issues) in the models repository - [fork the models repository](https://github.com/keysight/infragraph) and submit a PR - version: 1.1.1 + version: 2.0.0 contact: url: https://github.com/keysight/infragraph/issues license: diff --git a/artifacts/infragraph.proto b/artifacts/infragraph.proto index bbfdf5d..53e666e 100644 --- a/artifacts/infragraph.proto +++ b/artifacts/infragraph.proto @@ -1,4 +1,4 @@ -/* InfraGraph 1.1.1 +/* InfraGraph 2.0.0 * ### Overview * InfraGraph or `infrastructure graph` defines a model-driven, vendor-neutral, standard * interface for capturing a system of systems suitable for use in co-designing AI/HPC diff --git a/artifacts/openapi.yaml b/artifacts/openapi.yaml index 8851519..941c745 100644 --- a/artifacts/openapi.yaml +++ b/artifacts/openapi.yaml @@ -20,7 +20,7 @@ info: Contributions to the API and models schema can be made in the following ways: - [open an issue](https://github.com/keysight/infragraph/issues) in the models repository - [fork the models repository](https://github.com/keysight/infragraph) and submit a PR - version: 1.1.1 + version: 2.0.0 contact: url: https://github.com/keysight/infragraph/issues license: diff --git a/docs/src/annotate.md b/docs/src/annotate.md index 99e948f..63ed221 100644 --- a/docs/src/annotate.md +++ b/docs/src/annotate.md @@ -2,7 +2,7 @@ # The `annotate_graph` API ## Overview -Once the infrastructure or system of systems has been defined by using the `set_graph` API the base graph can be extended by using the `annotate_graph` API to add additional data using nodes and edges as endpoints for the data. +Once the infrastructure or system of systems has been defined by using the `set_graph` API the base graph can be extended by using the `annotate_graph` API to add additional data using nodes, edges, and links as endpoints for the data. The main objective of the `annotate_graph` API is to separate the infrastructure model from specific use-case models by allowing the graph to be extended with any type of data. This ensures that `InfraGraph` does not morph into an attempt to define every nuance present in a system of systems. @@ -18,12 +18,43 @@ Some examples of additional data are: - device addresses - device routing tables +### Annotation Structure +The `annotate_graph` API accepts an `Annotation` object that targets **nodes**, **edges**, or **links** in the graph. Each target supports one or more key-value attributes: + +```python +annotation = Annotation() + +# add a node annotation +node = annotation.nodes.add(name="host.0.xpu.0") +node.attributes.add(attribute="rank", value="0") + +# add an edge annotation +edge = annotation.edges.add(ep1="host.0.xpu.0", ep2="switch.0") +edge.attributes.add(attribute="bandwidth", value="400G") + +# add a link annotation +link = annotation.links.add(name="pcie") +link.attributes.add(attribute="version", value="5.0") + +service.annotate_graph(annotation) +``` + +### Node Name Slicing +Node names support a slicing operator that expands to the fully qualified dot-separated format, making it easy to target ranges of nodes without enumerating each one individually: + +| Slice notation | Expands to | +|---|---| +| `server[0]xpu[0]` | `server.0.xpu.0` | +| `server[0:2]` | `server.0`, `server.1` | +| `server[0:2]xpu[0:3]` | `server.0.xpu.0`, `server.0.xpu.1`, `server.0.xpu.2`, `server.1.xpu.0`, ... | +| `switch` | `switch` (unchanged) | + The following code examples demonstrates how to use the `query_graph` API in conjunction with the `annotate_graph` API to extend the graph with additional user specific data. ## Adding `rank` data In the [Getting Started](create.md) example, the instances of the `Server` device were created with the name of `host` and each instance having a specific number of components with a name of `xpu`. -The following code demonstrates adding a `rank` attribute to every `host` instance that has a component with the name of `xpu`. +The following code demonstrates adding a `rank` attribute to every `host` instance that has a component with the name of `xpu`. Each matching node is added to the `Annotation` object and a `rank` attribute is attached via `attributes.add`.
Add a rank to each host xpu ```python @@ -34,7 +65,7 @@ The following code demonstrates adding a `rank` attribute to every `host` instan ## Adding `ipaddress` data In the [Getting Started](create.md) example, the instances of the `Server` device were created with the name of `host` and each instance having a `mgmt` nic component. -The following code demonstrates adding an `ipaddress` attribute to the `host` instance `mgmt` nic. +The following code demonstrates adding an `ipaddress` attribute to the `host` instance `mgmt` nic. Each matching node is added to the `Annotation` object and an `ipaddress` attribute is attached via `attributes.add`.
Add an ipaddress to each host mgmt component ```python diff --git a/docs/src/index.md b/docs/src/index.md index 882df00..f768ab3 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -24,7 +24,7 @@ The [blueprints](blueprints.md) section provides ready-made templates for common The [CLI](cli.md) provides commands for converting system descriptions into InfraGraph format and visualizing infrastructure topologies directly from the terminal. ### Extending the case study with additional data -This section provides a comprehensive guide on how a user can annotate various parts of infrastructre and add more details like DeviceType, Rank Identifier and so on. +This section provides a comprehensive guide on how a user can annotate various parts of infrastructure and add more details like DeviceType, Rank Identifier and so on. It covers the model description with examples for binding physical attributes with the logical infrastructure definition. diff --git a/docs/src/openapi.html b/docs/src/openapi.html index f1357e6..3c4e5a9 100644 --- a/docs/src/openapi.html +++ b/docs/src/openapi.html @@ -530,7 +530,7 @@ 55.627 l 55.6165,55.627 -231.245496,231.24803 c -127.185,127.1864 -231.5279,231.248 -231.873,231.248 -0.3451,0 -104.688, -104.0616 -231.873,-231.248 z - " fill="currentColor">

InfraGraph (1.1.1)

Download OpenAPI specification:Download

URL: https://github.com/keysight/infragraph/issues License: MIT

Overview

+ " fill="currentColor">

InfraGraph (2.0.0)

Download OpenAPI specification:Download

URL: https://github.com/keysight/infragraph/issues License: MIT

Overview

InfraGraph or infrastructure graph defines a model-driven, vendor-neutral, standard interface for capturing a system of systems suitable for use in co-designing AI/HPC solutions.

This model allows for defining physical infrastructure as a logical system of systems using graph like terminology. @@ -603,7 +603,7 @@

Contributions

Response samples

Content type
application/json
{
  • "api_spec_version": "",
  • "sdk_version": "",
  • "app_version": ""
}