aigverse.networks¶

Provides logic network data structures and derived views.

This module includes network types, edge and index list utilities, and helper objects for structural manipulation.

Module Contents¶

class NodeTensorEncoding(*args, **kwds)¶

Bases: enum.Enum

Node encoding mode for exported graph tensors.

All node features use float32; only the categorical encoding scheme changes. - INTEGER: Node classes are scalar labels in the first feature column. - ONE_HOT: Node classes are one-hot vectors in [constant, pi, gate, po] order.

INTEGER = 0¶

0=constant, 1=pi, 2=gate, 3=po.

Type:: Scalar node labels in the first feature column

ONE_HOT = 1¶: One-hot node labels in [constant, pi, gate, po] order.

class EdgeTensorEncoding(*args, **kwds)¶

Bases: enum.Enum

Edge encoding mode for exported graph tensors.

All edge features use float32; only the categorical encoding scheme changes. - BINARY: Edge polarity is binary (regular=0.0, inverted=1.0). - SIGNED: Edge polarity is signed (regular=+1.0, inverted=-1.0). - ONE_HOT: Edge polarity is one-hot in [regular, inverted] order.

BINARY = 0¶: Labels are encoded as 0.0 (regular) and 1.0 (inverted).

SIGNED = 1¶: Labels are encoded as +1.0 (regular) and -1.0 (inverted).

ONE_HOT = 2¶: One-hot edge labels in [regular, inverted] order.

class AigSignal(index: int, complement: bool)¶

Represents a signal in an AIG.

Signals point to nodes and may be complemented.

property index: int¶: Node index referenced by the signal.

property complement: bool¶: Whether this signal is complemented.

property data: int¶: Raw packed signal representation.

__hash__() → int¶: Returns a hash value for dictionary/set usage.

__eq__(other: object) → bool¶

Returns whether two signals are equal.

Parameters:: other – Object to compare.
Returns:: True if equal, otherwise False.

__ne__(other: object) → bool¶

Returns whether two signals are not equal.

Parameters:: other – Object to compare.
Returns:: True if not equal, otherwise False.

__lt__(other: AigSignal) → bool¶: Returns whether this signal is ordered before another signal.

__invert__() → AigSignal¶: Returns the complemented signal.

__pos__() → AigSignal¶: Returns a normalized positive-phase signal.

__neg__() → AigSignal¶: Returns a normalized negative-phase signal.

__xor__(complement: bool) → AigSignal¶

XORs the signal phase with a Boolean complement bit.

Parameters:: complement – Complement bit to XOR with the current signal phase.
Returns:: A phase-adjusted signal.

class Aig¶

class Aig(ntk: Aig)

Represents an AIG and its structural operations.

Note

to_index_list() keeps combinational structure only. Augmented view metadata is not preserved.

clone() → Aig¶: Creates a structural copy of the network.

property size: int¶: Number of nodes in the network.

property num_gates: int¶: Number of logic gates in the network.

property num_pis: int¶: Number of primary inputs.

property num_pos: int¶: Number of primary outputs.

get_node(s: AigSignal) → int¶: Returns the node referenced by a signal.

make_signal(n: int) → AigSignal¶: Creates a signal from a node.

is_complemented(s: AigSignal) → bool¶: Returns whether a signal is complemented.

node_to_index(n: int) → int¶: Returns the integer index of a node.

index_to_node(index: int) → int¶: Returns the node for an index.

pi_index(n: int) → int¶: Returns the primary-input position of a node.

pi_at(index: int) → int¶: Returns the primary input node at index.

po_index(s: AigSignal) → int¶: Returns the primary-output position of a signal.

po_at(index: int) → AigSignal¶: Returns the primary output signal at index.

get_constant(value: bool) → AigSignal¶: Returns the constant signal for a Boolean value.

create_pi() → AigSignal¶: Creates and returns a new primary input signal.

create_po(f: AigSignal) → int¶: Creates a primary output from signal f.

property is_combinational: bool¶: Whether the network is combinational.

create_buf(a: AigSignal) → AigSignal¶: Creates a buffer.

create_not(a: AigSignal) → AigSignal¶: Creates an inversion.

create_and(a: AigSignal, b: AigSignal) → AigSignal¶: Creates an AND.

create_nand(a: AigSignal, b: AigSignal) → AigSignal¶: Creates a NAND.

create_or(a: AigSignal, b: AigSignal) → AigSignal¶: Creates an OR.

create_nor(a: AigSignal, b: AigSignal) → AigSignal¶: Creates a NOR.

create_xor(a: AigSignal, b: AigSignal) → AigSignal¶: Creates an XOR.

create_xnor(a: AigSignal, b: AigSignal) → AigSignal¶: Creates an XNOR.

create_lt(a: AigSignal, b: AigSignal) → AigSignal¶: Creates a less-than comparator.

create_le(a: AigSignal, b: AigSignal) → AigSignal¶: Creates a less-or-equal comparator.

create_maj(a: AigSignal, b: AigSignal, c: AigSignal) → AigSignal¶: Creates a majority.

create_ite(cond: AigSignal, f_then: AigSignal, f_else: AigSignal) → AigSignal¶: Creates an if-then-else.

create_xor3(a: AigSignal, b: AigSignal, c: AigSignal) → AigSignal¶: Creates a 3-input XOR.

create_nary_and(fs: Sequence[AigSignal]) → AigSignal¶: Creates an n-ary AND.

create_nary_or(fs: Sequence[AigSignal]) → AigSignal¶: Creates an n-ary OR.

create_nary_xor(fs: Sequence[AigSignal]) → AigSignal¶: Creates an n-ary XOR.

clone_node(other: Aig, source: int, children: Sequence[AigSignal]) → AigSignal¶: Clones one node from other into this network.

nodes() → list[int]¶: Returns a list of all nodes in order of creation.

gates() → list[int]¶: Returns a list of all non-constant and non-PI nodes in order of creation.

pis() → list[int]¶: Returns a list of all primary input nodes in order of creation.

pos() → list[AigSignal]¶: Returns a list of all primary output signals in order of creation.

fanins(n: int) → list[AigSignal]¶: Returns fanin signals of node n.

fanin_size(n: int) → int¶: Returns the number of fanins of node n.

fanout_size(n: int) → int¶: Returns the number of fanouts of node n.

is_constant(n: int) → bool¶: Returns whether n is a constant node.

is_pi(n: int) → bool¶: Returns whether n is a primary input.

has_and(a: AigSignal, b: AigSignal) → AigSignal | None¶: Returns whether an AND with fanins a and b already exists.

is_and(n: int) → bool¶: Returns whether n is an AND node.

is_or(n: int) → bool¶: Returns whether n is an OR node.

is_xor(n: int) → bool¶: Returns whether n is an XOR node.

is_maj(n: int) → bool¶: Returns whether n is a majority node.

is_ite(n: int) → bool¶: Returns whether n is an if-then-else node.

is_xor3(n: int) → bool¶: Returns whether n is a 3-input XOR node.

is_nary_and(n: int) → bool¶: Returns whether n is an n-ary AND node.

is_nary_or(n: int) → bool¶: Returns whether n is an n-ary OR node.

to_edge_list(regular_weight: int = 0, inverted_weight: int = 1) → AigEdgeList¶

Converts the network to an edge list.

Emits one edge per structural fanin connection, plus one edge per primary output pointing to a synthetic target index beyond the last node. Useful for feeding the network’s structure into graph algorithms, GNN frameworks, or other tooling that consumes edge-list-style graphs.

Parameters:

regular_weight – Weight assigned to non-inverted edges.
inverted_weight – Weight assigned to inverted edges.

Returns:

The corresponding edge-list representation.

to_index_list() → AigIndexList¶

Converts the network to an index-list encoding.

Returns:: The corresponding index-list representation.

to_networkx(*, levels: bool = False, fanouts: bool = False, node_tts: bool = False, graph_tts: bool = False, dtype: type[generic] = ...) → DiGraph¶

Converts an Aig to a DiGraph.

This function transforms the AIG into a directed graph representation using the NetworkX library. It allows for the inclusion of various attributes for the graph, its nodes, and edges, making it suitable for graph-based machine learning tasks.

Note that the constant-0 node is always included in the graph, as index 0, even if it is not referenced by any edges.

Parameters:

self – The AIG object to convert.
levels – If True, computes and adds level information for each node and the total number of levels to the graph, as attributes level and levels, respectively. Defaults to False.
fanouts – If True, adds the fanout count for each node as an integer fanouts attribute (0 for synthetic PO nodes). Defaults to False.
node_tts – If True, computes and adds a truth table for each node as a function attribute. Defaults to False.
graph_tts – If True, computes and adds the graph’s overall truth table as a function attribute to the graph. Defaults to False.
dtype – The data type for truth tables and all one-hot encodings. Defaults to int8. For machine learning tasks, a floating-point type such as float32 or float64 may be more appropriate, as it allows for gradient-based optimization.

Returns:

A DiGraph representing the AIG.

Graph Attributes:

type (str): "AIG".
num_pis (int): Number of primary inputs.
num_pos (int): Number of primary outputs.
num_gates (int): Number of AND gates.
levels (int, optional): Total number of levels in the AIG.
function (list[ndarray], optional): Graph’s truth tables.
name (str, optional): Network name (only for NamedAig).

Node Attributes:

index (int): The node’s identifier.
level (int, optional): The level of the node in the AIG.
fanouts (int, optional): Fanout count of the node.
Included when fanouts=True.
function (ndarray, optional): The node’s truth table.
type (ndarray): A one-hot encoded vector representing
the node type ([const, pi, gate, po]). The data type is determined by the dtype argument, defaulting to int8.

Edge Attributes:

type (ndarray): A one-hot encoded vector representing the edge
type ([regular, inverted]). The data type is determined by the dtype argument, defaulting to int8.
name (str, optional): Signal name or primary output name for edges to synthetic
PO nodes (only for NamedAig).

to_graph_tensors(node_encoding: NodeTensorEncoding = ..., edge_encoding: EdgeTensorEncoding = ..., *, levels: bool = True, fanouts: bool = False, node_tts: bool = False) → dict¶

Exports graph tensors for machine-learning workflows.

Returns sparse graph topology and features as DLPack-compatible arrays.

Edge encoding mapping:

BINARY: regular=0.0, inverted=1.0
SIGNED: regular=+1.0, inverted=-1.0
ONE_HOT: regular=[1.0, 0.0], inverted=[0.0, 1.0]

Node encoding mapping:

INTEGER: constant=0, pi=1, gate=2, po=3
ONE_HOT: [constant, pi, gate, po]

Parameters:

node_encoding – Node encoding mode as NodeTensorEncoding.
edge_encoding – Edge encoding mode as EdgeTensorEncoding.
levels – Appends logic level as a node feature.
fanouts – Appends fanout size as a node feature.
node_tts – Appends simulated node/output truth-table bits.

Returns:

A dictionary with edge_index (shape (2, E), dtype int64), edge_attr (shape (E, D_edge), dtype float32), and node_attr (shape (N, D_node), dtype float32).

__len__() → int¶: Returns the number of nodes.

__iter__() → Iterator[int]¶: Returns an iterator over all nodes.

__contains__(value: object) → bool¶: Returns whether a node index is contained in the network.

__bool__() → bool¶: Returns True for non-trivial networks.

__copy__() → Aig¶: Returns a shallow structural copy.

__deepcopy__(memo: dict) → Aig¶: Returns a deep structural copy.

__setstate__(state: object) → None¶

Restores a network from a pickled state tuple.

Parameters:: state – Tuple containing one index-list payload.
Raises:: ValueError – If the state shape or payload is invalid.

__getstate__() → tuple¶

Returns pickle state as an index-list tuple.

Preserves only combinational structure and does not capture augmented view metadata.

class NamedAig¶

class NamedAig(ntk: NamedAig)

class NamedAig(ntk: Aig)

Bases: Aig

Extends a network with input/output and node names.

clone() → NamedAig¶: Creates a structural copy including names.

__copy__() → NamedAig¶: Returns a shallow copy of the named view.

__deepcopy__(memo: dict) → NamedAig¶: Returns a deep copy of the named view.

create_pi(name: str = '') → AigSignal¶: Creates a primary input with an optional name.

create_po(f: AigSignal, name: str = '') → int¶: Creates a primary output with an optional name.

set_network_name(name: str) → None¶: Sets the network name.

get_network_name() → str¶: Returns the network name.

has_name(s: AigSignal) → bool¶: Returns whether signal s has a name.

set_name(s: AigSignal, name: str) → None¶: Assigns a name to signal s.

get_name(s: AigSignal) → str¶: Returns the name of signal s.

has_output_name(index: int) → bool¶: Returns whether output index has a name.

set_output_name(index: int, name: str) → None¶: Sets the name of output index.

get_output_name(index: int) → str¶: Returns the name of output index.

class DepthAig¶

class DepthAig(ntk: DepthAig)

class DepthAig(ntk: Aig)

Bases: Aig

Extends a network with depth information.

clone() → DepthAig¶: Creates a copy of the depth view.

__copy__() → DepthAig¶: Returns a shallow copy of the depth view.

__deepcopy__(memo: dict) → DepthAig¶: Returns a deep copy of the depth view.

property num_levels: int¶: Current network depth in levels.

level(n: int) → int¶: Returns the level of node n.

is_on_critical_path(n: int) → bool¶: Returns whether node n is on at least one critical path.

update_levels() → None¶: Recomputes level information.

create_po(f: AigSignal) → int¶: Creates an output and updates depth information.

class FanoutAig¶

class FanoutAig(ntk: Aig)

class FanoutAig(ntk: FanoutAig)

Bases: Aig

Extends a network with fanout information.

clone() → FanoutAig¶: Creates a structural copy of the fanout view.

__copy__() → FanoutAig¶: Returns a shallow copy of the fanout view.

__deepcopy__(memo: dict) → FanoutAig¶: Returns a deep copy of the fanout view.

fanouts(n: int) → list[int]¶: Returns fanout nodes of node n.

class AigCut(ntk: Aig, leaves: Sequence[int], root: AigSignal)¶

class AigCut(ntk: Aig, leaves: Sequence[AigSignal], root: AigSignal)

Implements an isolated view on a single cut in a network.

This view creates a network from a single cut with a single output root and a set of leaves. This is a standalone structural descriptor; it does not inherit from the network type and only exposes read-only inspection methods.

Note

This view clears all nodes’ visited flags before construction to ensure the cut is constructed correctly. The view guarantees that all nodes in the view will have a 0 visited flag after construction.

clone() → AigCut¶: Creates a structural copy of the cut view.

__copy__() → AigCut¶: Returns a shallow copy of the cut view.

__deepcopy__(memo: dict) → AigCut¶: Returns a deep copy of the cut view.

nodes() → list[int]¶: Returns a list of all nodes in the cut view.

gates() → list[int]¶: Returns a list of all gate nodes in the cut view.

pis() → list[int]¶: Returns a list of all primary input (leaf) nodes in the cut view.

pos() → list[AigSignal]¶: Returns a list containing the root signal of the cut view.

is_pi(n: int) → bool¶: Returns whether n is a primary input (leaf) in the cut view.

property size: int¶: Number of nodes in the cut view.

property num_pis: int¶: Number of primary inputs (leaves) in the cut view.

property num_pos: int¶: Number of primary outputs (always 1 for cut view).

property num_gates: int¶: Number of logic gates in the cut view.

node_to_index(n: int) → int¶: Returns the integer index of a node.

index_to_node(index: int) → int¶: Returns the node for an index.

to_index_list() → AigIndexList¶

Converts the cut view to an index-list encoding.

Only the cut’s restricted node set is encoded. The resulting index list can be decoded into a standalone Aig via AigIndexList.to_aig().

Returns:: The corresponding index-list representation.

class AigRegister¶

class AigRegister(register: AigRegister)

Represents metadata for one sequential register.

property control: str¶: Optional control signal.

property init: int¶: Initial value of the register.

property type: str¶: Register type/category.

class SequentialAig¶

Bases: Aig

Represents a sequential network with register interfaces.

clone() → SequentialAig¶: Creates a structural copy of the sequential network.

__copy__() → SequentialAig¶: Returns a shallow copy of the sequential network.

__deepcopy__(memo: dict) → SequentialAig¶: Returns a deep copy of the sequential network.

create_pi() → AigSignal¶: Creates a primary input.

create_po(f: AigSignal) → int¶: Creates a primary output.

create_ro() → AigSignal¶: Creates a register output node.

create_ri(f: AigSignal) → int¶: Creates a register input signal.

property is_combinational: bool¶: Whether the network is combinational.

is_ci(n: int) → bool¶: Returns whether n is a combinational input.

is_pi(n: int) → bool¶: Returns whether n is a primary input.

is_ro(n: int) → bool¶: Returns whether n is a register output.

property num_pis: int¶: Number of primary inputs.

property num_pos: int¶: Number of primary outputs.

property num_cis: int¶: Number of combinational inputs.

property num_cos: int¶: Number of combinational outputs.

property num_registers: int¶: Number of registers.

pi_at(index: int) → int¶: Returns primary input at index.

po_at(index: int) → AigSignal¶: Returns primary output at index.

ci_at(index: int) → int¶: Returns combinational input at index.

co_at(index: int) → AigSignal¶: Returns combinational output at index.

ro_at(index: int) → int¶: Returns register output at index.

ri_at(index: int) → AigSignal¶: Returns register input at index.

set_register(index: int, reg: AigRegister) → None¶: Sets metadata for register index.

register_at(index: int) → AigRegister¶: Returns metadata for register index.

pi_index(n: int) → int¶: Returns PI index of node n.

ci_index(n: int) → int¶: Returns CI index of node n.

co_index(s: AigSignal) → int¶: Returns CO index of signal s.

ro_index(n: int) → int¶: Returns RO index of node n.

ri_index(s: AigSignal) → int¶: Returns RI index of signal s.

ro_to_ri(s: AigSignal) → AigSignal¶: Maps a register output signal to its input.

ri_to_ro(s: AigSignal) → int¶: Maps a register input signal to its output.

to_index_list() → NoReturn¶: Sequential networks cannot be encoded as combinational index lists.

to_graph_tensors(node_encoding: NodeTensorEncoding = ..., edge_encoding: EdgeTensorEncoding = ..., *, levels: bool = True, fanouts: bool = False, node_tts: bool = False) → NoReturn¶: Sequential networks cannot be exported as combinational graph tensors.

__getstate__() → NoReturn¶: Sequential networks are not pickleable via combinational index-list state.

__setstate__(state: object) → NoReturn¶: Sequential networks cannot be restored from combinational index-list state.

to_edge_list(regular_weight: int = 0, inverted_weight: int = 1) → AigEdgeList¶

Converts the sequential network to an edge list.

In addition to the fanin and primary-output edges emitted for combinational networks, one feedback edge per register is added, connecting a register input to its register output.

Parameters:

regular_weight – Weight assigned to non-inverted edges.
inverted_weight – Weight assigned to inverted edges.

Returns:

The corresponding edge-list representation.

pis() → list[int]¶: Returns all primary input nodes.

pos() → list[AigSignal]¶: Returns all primary output signals.

cis() → list[int]¶: Returns all combinational input nodes.

cos() → list[AigSignal]¶: Returns all combinational output signals.

ros() → list[int]¶: Returns all register output nodes.

ris() → list[AigSignal]¶: Returns all register input signals.

registers() → list[tuple[AigSignal, int]]¶: Returns all register pairs as (ri_signal, ro_node) tuples.

class AigEdge¶

class AigEdge(source: int, target: int, weight: int = 0)

Represents a directed edge in a logic network graph. A weight attribute may encode inversion.

property source: int¶: Source node identifier.

property target: int¶: Target node identifier.

property weight: int¶: Edge weight value.

__eq__(other: object) → bool¶

Checks whether two edges are equal.

Parameters:: other – Object to compare.
Returns:: True if other is an edge with equal fields, otherwise False.

__ne__(other: object) → bool¶

Checks whether two edges are not equal.

Parameters:: other – Object to compare.
Returns:: True if other is not equal to this edge.

class AigEdgeList¶

class AigEdgeList(ntk: Aig)

class AigEdgeList(edges: Sequence[AigEdge])

class AigEdgeList(ntk: Aig, edges: Sequence[AigEdge])

Represents a list of edges associated with a network.

property ntk: Aig¶: Underlying network associated with this list.

property edges: list[AigEdge]¶: Stored edges in insertion order.

append(edge: AigEdge) → None¶

Appends an edge to the list.

Parameters:: edge – Edge to append.

clear() → None¶: Removes all edges from the list.

__iter__() → Iterator[AigEdge]¶: Returns an iterator over stored edges.

__len__() → int¶: Returns the number of edges.

__getitem__(index: int) → AigEdge¶

Returns the edge at a given position.

Parameters:: index – Edge index. Negative indices are supported.
Returns:: The edge at the requested position.
Raises:: IndexError – If index is out of bounds.

__setitem__(index: int, edge: AigEdge) → None¶

Replaces the edge at a given position.

Parameters:

index – Edge index. Negative indices are supported.
edge – Replacement edge.

Raises:

IndexError – If index is out of bounds.

class AigIndexList(num_pis: int = 0)¶

class AigIndexList(values: Sequence[int])

Represents an index-list encoding of an AIG network.

raw() → list[int]¶

Returns the raw integer encoding.

Returns:: A list of encoded index-list values.

property size: int¶: Number of raw entries in the encoding.

property num_gates: int¶: Number of encoded gates.

property num_pis: int¶: Number of encoded primary inputs.

property num_pos: int¶: Number of encoded primary outputs.

add_inputs(n: int = 1) → None¶

Appends primary inputs to the encoding.

Parameters:: n – Number of inputs to append.

add_and(lit0: int, lit1: int) → int¶

Appends an AND gate to the encoding.

Parameters:

lit0 – First fanin literal.
lit1 – Second fanin literal.

add_xor(lit0: int, lit1: int) → int¶

Appends an XOR gate to the encoding.

Parameters:

lit0 – First fanin literal.
lit1 – Second fanin literal.

add_output(lit: int) → None¶

Appends a primary output literal.

Parameters:: lit – Output literal.

clear() → None¶: Clears all encoded data.

to_aig() → Aig¶

Decodes the index list into an AIG network.

Returns:: A decoded AIG network.

gates() → list[tuple[int, int]]¶

Returns encoded gate fanins as literal pairs.

Returns:: A list of (lit0, lit1) tuples for each gate.

pos() → list[int]¶

Returns encoded primary output literals.

Returns:: A list of output literals.

__iter__() → Iterator[int]¶: Returns an iterator over the raw encoding values.

__getitem__(index: int) → int¶

Returns one raw encoding value by index.

Parameters:: index – Position in the raw encoding.
Returns:: The raw value at index.
Raises:: IndexError – If index is out of range.

__setitem__(index: int, value: int) → None¶

Sets one raw encoding value by index.

Parameters:

index – Position in the raw encoding.
value – Replacement raw value.

Raises:

IndexError – If index is out of range.

__len__() → int¶: Returns the number of raw encoding entries.