Converter

Converters turn domain-specific objects (e.g. a pypowsybl.network.Network) into Graph instances.

A Converter is composed of one ElementsConverter per hyper-edge class (e.g. "bus", "line"), each in charge of extracting a table of addresses and features from the input object. The converter then maps string addresses to consecutive integers, casts features to bounded floats, and assembles the tables into a graph.

Converter

class Converter

Bases: object

Abstract base class for all converters.

A converter turns a domain-specific object (e.g. a pypowsybl.network.Network) into an energnn.graph.Graph. Subclasses only need to provide elements_converter_dict, which maps each hyper-edge class name (e.g. "bus", "line") to the ElementsConverter in charge of extracting its table of addresses and features.

Calling the converter runs the following pipeline:

1. each ElementsConverter extracts an (address table, feature table) pair from the input object;

2. string addresses are mapped to consecutive integers 0..n-1, in sorted order so that the mapping is reproducible across runs;

3. features are cast to floats: categorical values are hashed to a deterministic float in [0, 1), NaNs are replaced by 0, and values are clipped to [-1e6, 1e6];

4. the tables are assembled into a energnn.graph.Graph through HyperEdgeSet.from_dict() and Graph.from_dict().

The graph is always built on a numpy backend, because graph shapes vary from one input to the next and building directly in jax would trigger one XLA compilation per new shape. If backend is set, the finished graph is converted to it with Graph.to_backend().

Variables:

• elements_converter_dict – Mapping from hyper-edge class name to its ElementsConverter. Must be defined by subclasses.

• backend – Optional target backend for the returned graph. If None, the graph is returned on a NumpyBackend.

Converter.__call__	Convert an input object into a energnn.graph.Graph.
Converter.get_structure	Return the GraphStructure describing the graphs produced by this converter.

ElementsConverter

class ElementsConverter(port_list, feature_list)

Bases: ABC

Abstract base class for elements converters.

An elements converter extracts, for one class of hyper-edges (e.g. "bus", "line"), a table of addresses and a table of features from a domain-specific object. Subclasses must implement _get_table(), which returns a single pandas.DataFrame containing at least the columns listed in port_list and feature_list; __call__() then splits it into the (address table, feature table) pair consumed by Converter.

At least one of port_list and feature_list must be provided: a hyper-edge set with neither ports nor features would be empty.

Parameters:

• port_list (list[str] | None) – Names of the columns of the table returned by _get_table() that contain addresses (e.g. ["from", "to"] for a line). None if the hyper-edges have no ports (e.g. global quantities).

• feature_list (list[str] | None) – Names of the columns that contain features. None if the hyper-edges carry no feature (e.g. purely structural elements).

Variables:

attributes – All columns that must be fetched from the underlying data source, i.e. the concatenation of port_list and feature_list.

ElementsConverter.__init__
ElementsConverter.__call__	Extract the (address table, feature table) pair for this class of hyper-edges.
ElementsConverter.get_structure	Get the edge structure of the element, useful for building an EnerGNN model.