Skip to content

Interoperability

In annnet, interoperability means preserving as much graph meaning as possible when moving between annnet and other tools, backends, or file formats.

Most external graph tools support a narrower model than annnet. Common target assumptions include:

  • only binary edges
  • one global graph context
  • no edge-entities
  • limited multilayer support
  • dictionary-style attributes rather than aligned tables

AnnNet conversions are explicit projections between models with different expressive power.

Two kinds of interoperability

annnet separates two jobs:

  • runtime backends for in-memory computation
  • IO and exchange formats for persistence or data transfer

Converting to another in-memory graph backend is separate from writing a file format.

Runtime backends

Graph-owned lazy accessors such as G.nx, G.ig, and G.gt expose the current annnet graph through external graph libraries only when needed.

# NetworkX
bc = G.nx.betweenness_centrality(G)

# Get a concrete backend graph with options
nxG = G.nx.backend(
    directed=True,
    hyperedge_mode="skip",
    slice="toy",
    simple=True,
)

Use this when annnet is the source of truth and another library provides the algorithm or workflow.

Under the hood, these accessors are attached to the AnnNet instance and use the normal backend conversion functions. For a call like G.nx.betweenness_centrality(G), annnet:

  • resolves betweenness_centrality from NetworkX
  • projects the AnnNet graph to a NetworkX graph using the selected options
  • replaces the AnnNet G argument with the projected backend graph
  • dispatches the call to NetworkX
  • returns the backend result, with vertex IDs mapped back where supported

The projected backend graph is cached and invalidated when the AnnNet graph version changes. G.nx.backend(...), G.ig.backend(...), and G.gt.backend() return the concrete backend graph when you want to inspect it or pass it around yourself.

The direct adapter functions remain available for explicit conversion: to_nx/from_nx, to_igraph/from_igraph, and to_graphtool/from_graphtool.

Conversion is always a choice of projection

When exporting from annnet, you often have to choose how to project richer structure into a simpler target:

  • keep or collapse parallel edges
  • drop, expand, or reify hyperedges
  • select one slice or flatten several contexts
  • keep only a subset of attributes
  • preserve directedness exactly or coerce to the target model

Those choices are part of interoperability. They are not incidental details.

Manifests and round-tripping

annnet uses manifests to preserve reconstruction details when a target backend cannot represent the original graph directly.

import annnet as an

nxG, manifest = an.adapters.to_nx(G, directed=True, hyperedge_mode="skip")
G2 = an.adapters.from_nx(nxG, manifest)

A manifest records reconstruction details when hyperedges, slices, or multiedges are projected into a simpler graph shape.

Relation to storage and IO

Interoperability is the broad concept of controlled conversion. Storage and IO explains the concrete persistence and exchange mechanisms, including the native .annnet format and the other supported file and table interfaces.