Layers

Multilayer helpers from annnet.core._Layers.

annnet.core._Layers.LayerManager

Manager for Kivela multi-layer operations.

Provides organized namespace for layer operations by delegating to AnnNet methods. All heavy lifting is done by the AnnNet class; this is just a clean API surface.

Functions

aspects()

List aspect names.

Returns:

Type	Description
list[str]	Aspect identifiers in configured order.

elementary_layers()

Return elementary layer labels per aspect.

Returns:

Type	Description
dict[str, list[str]]	Mapping of aspect name to list of elementary labels.

layer_tuples()

List all aspect-tuples (Cartesian product).

Returns:

Type	Description
list[tuple[str, ...]]	All layer tuples in configured order.

tuple_id(aa)

Canonical string id for a layer tuple.

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Aspect-tuple layer (e.g., ("t1","F")).	required

Returns:

Type	Description
str	Canonical id (single label for 1 aspect, or "×"-joined).

vertex_layers(u)

List all layer-tuples where vertex u is present.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required

Returns:

Type	Description
list[tuple[str, ...]]	Layer tuples where (u, aa) is in V_M.

has_presence(u, aa)

Check whether (u, aa) is in V_M.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
aa	Iterable[str]	Layer tuple.	required

Returns:

Type	Description
bool

set_aspect_attrs(aspect, **attrs)

Attach metadata to an aspect.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required
**attrs		Key-value metadata to store.	{}

Returns:

Type	Description
None

aspect_attrs(aspect)

Get metadata dict for an aspect.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required

Returns:

Type	Description
dict

set_layer_attrs(aa, **attrs)

Attach metadata to a Kivela layer (aspect tuple).

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple.	required
**attrs		Key-value metadata to store.	{}

Returns:

Type	Description
None

layer_attrs(aa)

Get metadata dict for a Kivela layer (aspect tuple).

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple.	required

Returns:

Type	Description
dict

set_vertex_layer_attrs(u, aa, **attrs)

Attach metadata to a vertex–layer pair.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
aa	Iterable[str]	Layer tuple.	required
**attrs		Key-value metadata to store.	{}

Returns:

Type	Description
None

vertex_layer_attrs(u, aa)

Get metadata dict for a vertex–layer pair.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
aa	Iterable[str]	Layer tuple.	required

Returns:

Type	Description
dict

elem_layer_id(aspect, label)

Canonical "{aspect}_{label}" id used in layer_attributes.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required
label	str	Elementary layer label.	required

Returns:

Type	Description
str

set_elem_layer_attrs(aspect, label, **attrs)

Upsert attributes for an elementary layer.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required
label	str	Elementary layer label.	required
**attrs		Key-value metadata to store.	{}

Returns:

Type	Description
None

elem_layer_attrs(aspect, label)

Read attributes for an elementary layer.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required
label	str	Elementary layer label.	required

Returns:

Type	Description
dict

vertex_set(aa)

Vertices present in a Kivela layer.

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple.	required

Returns:

Type	Description
set[str]

edge_set(aa, include_inter=False, include_coupling=False)

Edges associated with a Kivela layer.

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple.	required
include_inter	bool	Include inter-layer edges touching aa.	False
include_coupling	bool	Include coupling edges touching aa.	False

Returns:

Type	Description
set[str]

union(layer_tuples, include_inter=False, include_coupling=False)

Set-union over Kivela layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to union.	required
include_inter	bool	Include inter-layer edges touching any layer in the union.	False
include_coupling	bool	Include coupling edges touching any layer in the union.	False

Returns:

Type	Description
dict	{"vertices": set[str], "edges": set[str]}.

intersection(layer_tuples, include_inter=False, include_coupling=False)

Set-intersection over Kivela layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to intersect.	required
include_inter	bool	Include inter-layer edges touching any layer in the intersection.	False
include_coupling	bool	Include coupling edges touching any layer in the intersection.	False

Returns:

Type	Description
dict	{"vertices": set[str], "edges": set[str]}.

difference(layer_a, layer_b, include_inter=False, include_coupling=False)

Set-difference over two layers.

Parameters:

Name	Type	Description	Default
layer_a	Iterable[str]	Minuend layer tuple.	required
layer_b	Iterable[str]	Subtrahend layer tuple.	required
include_inter	bool	Include inter-layer edges touching layer_a.	False
include_coupling	bool	Include coupling edges touching layer_a.	False

Returns:

Type	Description
dict	{"vertices": set[str], "edges": set[str]}.

to_slice(aa, slice_id=None, include_inter=False, include_coupling=False, **attrs)

Create a slice from a single Kivela layer.

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple.	required
slice_id	str	Slice identifier. Defaults to the canonical layer id.	None
include_inter	bool	Include inter-layer edges touching aa.	False
include_coupling	bool	Include coupling edges touching aa.	False
**attrs		Slice attributes to store.	{}

Returns:

Type	Description
str	The created slice id.

Examples:

G.layers.to_slice(("t1", "F"), slice_id="t1_F")

union_to_slice(layer_tuples, slice_id, include_inter=False, include_coupling=False, **attrs)

Create a slice from the union of several layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to union.	required
slice_id	str	Slice identifier.	required
include_inter	bool	Include inter-layer edges touching any layer in the union.	False
include_coupling	bool	Include coupling edges touching any layer in the union.	False
**attrs		Slice attributes to store.	{}

Returns:

Type	Description
str	The created slice id.

intersection_to_slice(layer_tuples, slice_id, include_inter=False, include_coupling=False, **attrs)

Create a slice from the intersection of several layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to intersect.	required
slice_id	str	Slice identifier.	required
include_inter	bool	Include inter-layer edges touching any layer in the intersection.	False
include_coupling	bool	Include coupling edges touching any layer in the intersection.	False
**attrs		Slice attributes to store.	{}

Returns:

Type	Description
str	The created slice id.

difference_to_slice(layer_a, layer_b, slice_id, include_inter=False, include_coupling=False, **attrs)

Create a slice from a set-difference of two layers.

Parameters:

Name	Type	Description	Default
layer_a	Iterable[str]	Minuend layer tuple.	required
layer_b	Iterable[str]	Subtrahend layer tuple.	required
slice_id	str	Slice identifier.	required
include_inter	bool	Include inter-layer edges touching layer_a.	False
include_coupling	bool	Include coupling edges touching layer_a.	False
**attrs		Slice attributes to store.	{}

Returns:

Type	Description
str	The created slice id.

subgraph(aa, include_inter=False, include_coupling=False)

Concrete subgraph induced by a single layer.

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple.	required
include_inter	bool	Include inter-layer edges touching aa.	False
include_coupling	bool	Include coupling edges touching aa.	False

Returns:

Type	Description
AnnNet

subgraph_union(layer_tuples, include_inter=False, include_coupling=False)

Subgraph induced by the union of several layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to union.	required
include_inter	bool	Include inter-layer edges touching any layer in the union.	False
include_coupling	bool	Include coupling edges touching any layer in the union.	False

Returns:

Type	Description
AnnNet

subgraph_intersection(layer_tuples, include_inter=False, include_coupling=False)

Subgraph induced by the intersection of several layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to intersect.	required
include_inter	bool	Include inter-layer edges touching any layer in the intersection.	False
include_coupling	bool	Include coupling edges touching any layer in the intersection.	False

Returns:

Type	Description
AnnNet

subgraph_difference(layer_a, layer_b, include_inter=False, include_coupling=False)

Subgraph induced by a set-difference of two layers.

Parameters:

Name	Type	Description	Default
layer_a	Iterable[str]	Minuend layer tuple.	required
layer_b	Iterable[str]	Subtrahend layer tuple.	required
include_inter	bool	Include inter-layer edges touching layer_a.	False
include_coupling	bool	Include coupling edges touching layer_a.	False

Returns:

Type	Description
AnnNet

intra_edges_tuple(aa)

Edge IDs of intra edges inside a layer.

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple.	required

Returns:

Type	Description
set[str]

inter_edges_between(aa, bb)

Edge IDs of inter edges between two layers.

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple A.	required
bb	Iterable[str]	Layer tuple B.	required

Returns:

Type	Description
set[str]

coupling_edges_between(aa, bb)

Edge IDs of coupling edges between two layers.

Parameters:

Name	Type	Description	Default
aa	Iterable[str]	Layer tuple A.	required
bb	Iterable[str]	Layer tuple B.	required

Returns:

Type	Description
set[str]

supra_adjacency(layers=None)

Proxy to full supra adjacency over selected layers.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Layer subset. In single-aspect mode, string IDs are accepted.	None

Returns:

Type	Description
csr_matrix

supra_incidence(layers=None, include_inter=True, include_coupling=True)

Build the supra-incidence matrix over selected layers.

Unlike supra_adjacency, this preserves the full hyperedge structure —
a k-ary hyperedge becomes a single column with k nonzero entries, with
stoichiometric coefficients intact. Binary intra, inter, coupling, and
hyperedges are all handled in a unified column-oriented representation.

Rows  : vertex-layer pairs (u, aa) — identical index to supra_adjacency,
        built by ensure_vertex_layer_index.
Cols  : one per selected edge, ordered as: intra edges (per layer, sorted
        by eid), then inter/coupling edges, then unassigned hyperedges last.

Column sign convention (matches _matrix):
    - Binary directed   : +w at source row, -w at target row
    - Binary undirected : +w at both rows
    - Hyperedge directed: +w at head rows, -w at tail rows (stoich-aware)
    - Hyperedge undirected: +w at all member rows (stoich-aware)
    - Inter/coupling    : +w at (u, La) row, -w at (v, Lb) row (directed)

Hyperedges MUST have a layer assignment in edge_layers (set via
set_edge_kivela_role(eid, "intra", layer_tuple) after add_hyperedge).
Hyperedges without a layer assignment are collected in the returned
skipped list and excluded from the matrix — they do NOT silently corrupt
the result.

Parameters

layers : list[str] | list[tuple[str, ...]] | None
    Optional subset of layers. None = all layers in V_M.
    Single-aspect string ids are accepted.
include_inter : bool
    Include inter-layer edges in the output columns. Default True.
include_coupling : bool
    Include coupling edges in the output columns. Default True.

Returns

B : scipy.sparse.csr_matrix
    Shape (|V_M|, |E_selected|). Rows are vertex-layer pairs in the
    order given by self._row_to_nl after ensure_vertex_layer_index.
edge_ids : list[str]
    Edge id for each column of B, in column order. Use this to map
    columns back to edges for interpretability.
skipped : list[str]
    Edge ids that were excluded because their layer assignment could
    not be resolved. Inspect these if B looks sparse.

Notes

The hypergraph random-walk diffusion operator follows directly::

    B_csr = B  (this output)
    D_v = diag(|B| @ ones)          # vertex degree (sum of |entries| per row)
    D_e = diag(|B|.T @ ones)        # edge degree (sum of |entries| per col)
    Theta = D_v_inv @ B @ D_e_inv @ B.T

Examples

    B, eids, skipped = G.supra_incidence()

blocks(layers=None)

Return supra block matrices.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Layer subset. In single-aspect mode, string IDs are accepted.	None

Returns:

Type	Description
dict	{"intra": A_intra, "inter": A_inter, "coupling": A_coupling}.

annnet.core._Layers.LayerClass

Functions

set_aspects(aspects, elem_layers)

Define multi-aspect structure.

Parameters:

Name	Type	Description	Default
aspects	list[str]	Aspect identifiers (e.g., ["time", "relation"]).	required
elem_layers	dict[str, list[str]]	Elementary labels per aspect (e.g., {"time": ["t1","t2"]}).	required

Returns:

Type	Description
None

Raises:

Type	Description
ValueError	If aspects is empty.

Examples:

G.set_aspects(["time", "relation"], {"time": ["t1", "t2"], "relation": ["F", "A"]})

add_elementary_layer(aspect, label)

Register a new elementary layer label under an existing aspect.

Parameters:

Name	Type	Description	Default
aspect	str	Existing aspect name.	required
label	str	New elementary layer label.	required

Returns:

Type	Description
None

add_presence(u, layer_tuple)

Declare that a vertex is present in a layer tuple.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required

Returns:

Type	Description
None

Raises:

Type	Description
KeyError	If u is not a vertex.
ValueError	If layer_tuple is invalid for the configured aspects.

remove_presence(u, layer_tuple)

Remove presence (u, aa) if it exists.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required

Returns:

Type	Description
None

Raises:

Type	Description
ValueError	If layer_tuple is invalid for the configured aspects.

has_presence(u, layer_tuple)

Check whether (u, aa) is in V_M.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required

Returns:

Type	Description
bool

iter_layers()

Iterate over all aspect-tuples (Cartesian product).

Yields:

Type	Description
tuple[str, ...]	Layer tuples in configured order.

iter_vertex_layers(u)

Iterate layer tuples where (u, aa) is in V_M.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required

Yields:

Type	Description
tuple[str, ...]	Layer tuples for u.

ensure_vertex_layer_index(restrict_layers=None)

Build stable mapping between vertex–layer tuples and row indices.

Parameters:

Name	Type	Description	Default
restrict_layers	list[tuple[str, ...]] | None	If provided, index only these layers.	None

Returns:

Type	Description
int	Number of indexed vertex–layer pairs.

Notes

Ordering is lexicographic by vertex id, then by layer tuple.

nl_to_row(u, layer_tuple)

Map (u, aa) to row index.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required

Returns:

Type	Description
int

Raises:

Type	Description
KeyError	If the vertex–layer pair is not indexed.

row_to_nl(row)

Map row index to (u, aa).

Parameters:

Name	Type	Description	Default
row	int	Row index.	required

Returns:

Type	Description
tuple[str, tuple[str, ...]]

Raises:

Type	Description
KeyError	If the row is not indexed.

layer_id_to_tuple(layer_id)

Map legacy string layer id to aspect tuple.

Parameters:

Name	Type	Description	Default
layer_id	str	Layer identifier (single-aspect only).	required

Returns:

Type	Description
tuple[str, ...]

Raises:

Type	Description
ValueError	If not in single-aspect mode.

layer_tuple_to_id(aa)

Canonical string id for a layer tuple.

Parameters:

Name	Type	Description	Default
aa	tuple[str, ...]	Aspect tuple layer.	required

Returns:

Type	Description
str	Canonical id (single label for 1 aspect, or "×"-joined).

set_elementary_layer_attrs(aspect, label, **attrs)

Attach attributes to an elementary Kivela layer.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required
label	str	Elementary layer label.	required
**attrs		Key-value metadata to store.	{}

Returns:

Type	Description
None

get_elementary_layer_attrs(aspect, label)

Get attributes for an elementary Kivela layer.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required
label	str	Elementary layer label.	required

Returns:

Type	Description
dict	Attributes dict; empty if not set.

set_aspect_attrs(aspect, **attrs)

Attach metadata to a Kivela aspect.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required
**attrs		Key-value metadata to store.	{}

Returns:

Type	Description
None

get_aspect_attrs(aspect)

Return a shallow copy of metadata for a Kivela aspect.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect identifier.	required

Returns:

Type	Description
dict

set_layer_attrs(layer_tuple, **attrs)

Attach metadata to a Kivela layer.

Parameters:

Name	Type	Description	Default
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required
**attrs		Key-value metadata to store.	{}

Returns:

Type	Description
None

get_layer_attrs(layer_tuple)

Get metadata dict for a Kivela layer.

Parameters:

Name	Type	Description	Default
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required

Returns:

Type	Description
dict	Shallow copy; empty if not set.

set_vertex_layer_attrs(u, layer_tuple, **attrs)

Attach metadata to a vertex–layer pair.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required
**attrs		Key-value metadata to store.	{}

Returns:

Type	Description
None

Raises:

Type	Description
KeyError	If (u, layer_tuple) is not present in V_M.

get_vertex_layer_attrs(u, layer_tuple)

Get metadata dict for a vertex–layer pair.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required

Returns:

Type	Description
dict	Shallow copy; empty if not set.

set_edge_kivela_role(eid, role, layers)

Annotate an existing structural edge with Kivela semantics.

Parameters:

Name	Type	Description	Default
eid	str	Edge identifier.	required
role	str	One of "intra", "inter", or "coupling".	required
layers	tuple | list	aa for "intra"; (aa, bb) for "inter"/"coupling".	required

Returns:

Type	Description
None

Raises:

Type	Description
KeyError	If eid does not exist.
ValueError	If role is invalid.

add_intra_edge(u, v, layer, *, weight=1.0, eid=None)

Add an intra-layer edge in legacy single-aspect mode.

Parameters:

Name	Type	Description	Default
u	str	Source vertex.	required
v	str	Target vertex.	required
layer	str	Layer id (single-aspect only).	required
weight	float	Edge weight.	1.0
eid	str | None	Edge id override.	None

Returns:

Type	Description
str	Edge id.

add_intra_edge_nl(u, v, layer_tuple, *, weight=1.0, eid=None)

Add an intra-layer edge for a multi-aspect layer.

Parameters:

Name	Type	Description	Default
u	str	Source vertex.	required
v	str	Target vertex.	required
layer_tuple	tuple[str, ...]	Aspect tuple layer aa.	required
weight	float	Edge weight.	1.0
eid	str | None	Edge id override.	None

Returns:

Type	Description
str	Edge id.

Raises:

Type	Description
KeyError	If required vertex–layer presence is missing.
ValueError	If layer_tuple is invalid.

Examples:

G.add_intra_edge_nl("u1", "u2", ("t1", "F"))

add_intra_edges_bulk(edges, layer_tuple, weight=1.0, fast_mode=True)

Bulk add intra-layer edges with direct matrix updates.

Parameters:

Name	Type	Description	Default
edges	Iterable	[(u, v), ...] or [(u, v, w), ...].	required
layer_tuple	tuple[str, ...]	Aspect tuple layer.	required
weight	float	Default weight when w is not provided.	1.0
fast_mode	bool	If True, skip validation/presence checks.	True

Returns:

Type	Description
list[str]	Edge ids added.

add_inter_edge_nl(u, layer_a, v, layer_b, *, weight=1.0, eid=None)

Add an inter-layer edge between two layer tuples.

Parameters:

Name	Type	Description	Default
u	str	Vertex in layer aa.	required
layer_a	tuple[str, ...]	Source layer tuple.	required
v	str	Vertex in layer bb.	required
layer_b	tuple[str, ...]	Target layer tuple.	required
weight	float	Edge weight.	1.0
eid	str | None	Edge id override.	None

Returns:

Type	Description
str	Edge id.

Raises:

Type	Description
KeyError	If required vertex–layer presence is missing.
ValueError	If layer tuples are invalid.

Examples:

G.add_inter_edge_nl("u1", ("t1",), "u2", ("t2",))

add_coupling_edge_nl(u, layer_a, layer_b, *, weight=1.0, eid=None)

Add a diagonal coupling edge between two layers for the same vertex.

Parameters:

Name	Type	Description	Default
u	str	Vertex identifier.	required
layer_a	tuple[str, ...]	Layer tuple A.	required
layer_b	tuple[str, ...]	Layer tuple B.	required
weight	float	Edge weight.	1.0
eid	str | None	Edge id override.	None

Returns:

Type	Description
str	Edge id.

layer_vertex_set(layer_tuple)

Vertices present in a Kivela layer.

Parameters:

Name	Type	Description	Default
layer_tuple	Iterable[str]	Aspect tuple layer.	required

Returns:

Type	Description
set[str]

layer_edge_set(layer_tuple, *, include_inter=False, include_coupling=False)

Edges associated with a Kivela layer.

Parameters:

Name	Type	Description	Default
layer_tuple	Iterable[str]	Aspect tuple layer.	required
include_inter	bool	Include inter-layer edges touching layer_tuple.	False
include_coupling	bool	Include coupling edges touching layer_tuple.	False

Returns:

Type	Description
set[str]

add_inter_edge(u, v, layer_a, layer_b, *, weight=1.0, eid=None)

Add an inter-layer edge in legacy single-aspect mode.

Parameters:

Name	Type	Description	Default
u	str	Source vertex.	required
v	str	Target vertex.	required
layer_a	str	Layer id (single-aspect only).	required
layer_b	str	Layer id (single-aspect only).	required
weight	float	Edge weight.	1.0
eid	str | None	Edge id override.	None

Returns:

Type	Description
str	Edge id.

layer_union(layer_tuples, *, include_inter=False, include_coupling=False)

Union of several Kivela layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to union.	required
include_inter	bool	Include inter-layer edges touching any layer in the union.	False
include_coupling	bool	Include coupling edges touching any layer in the union.	False

Returns:

Type	Description
dict	{"vertices": set[str], "edges": set[str]}.

layer_intersection(layer_tuples, *, include_inter=False, include_coupling=False)

Intersection of several Kivela layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to intersect.	required
include_inter	bool	Include inter-layer edges touching any layer in the intersection.	False
include_coupling	bool	Include coupling edges touching any layer in the intersection.	False

Returns:

Type	Description
dict	{"vertices": set[str], "edges": set[str]}.

layer_difference(layer_a, layer_b, *, include_inter=False, include_coupling=False)

Set difference: elements in layer_a but not in layer_b.

Parameters:

Name	Type	Description	Default
layer_a	Iterable[str]	Minuend layer tuple.	required
layer_b	Iterable[str]	Subtrahend layer tuple.	required
include_inter	bool	Include inter-layer edges touching layer_a.	False
include_coupling	bool	Include coupling edges touching layer_a.	False

Returns:

Type	Description
dict	{"vertices": set[str], "edges": set[str]}.

create_slice_from_layer(slice_id, layer_tuple, *, include_inter=False, include_coupling=False, **attributes)

Create a slice induced by a single Kivela layer.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
layer_tuple	Iterable[str]	Layer tuple.	required
include_inter	bool	Include inter-layer edges touching layer_tuple.	False
include_coupling	bool	Include coupling edges touching layer_tuple.	False
**attributes		Slice attributes to store.	{}

Returns:

Type	Description
str	The created slice id.

Examples:

G.create_slice_from_layer("t1_F", ("t1", "F"))

create_slice_from_layer_union(slice_id, layer_tuples, *, include_inter=False, include_coupling=False, **attributes)

Create a slice as the union of several layers.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
layer_tuples	Iterable[Iterable[str]]	Layer tuples to union.	required
include_inter	bool	Include inter-layer edges touching any layer in the union.	False
include_coupling	bool	Include coupling edges touching any layer in the union.	False
**attributes		Slice attributes to store.	{}

Returns:

Type	Description
str	The created slice id.

create_slice_from_layer_intersection(slice_id, layer_tuples, *, include_inter=False, include_coupling=False, **attributes)

Create a slice as the intersection of several layers.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
layer_tuples	Iterable[Iterable[str]]	Layer tuples to intersect.	required
include_inter	bool	Include inter-layer edges touching any layer in the intersection.	False
include_coupling	bool	Include coupling edges touching any layer in the intersection.	False
**attributes		Slice attributes to store.	{}

Returns:

Type	Description
str	The created slice id.

create_slice_from_layer_difference(slice_id, layer_a, layer_b, *, include_inter=False, include_coupling=False, **attributes)

Create a slice as the difference of two layers.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
layer_a	Iterable[str]	Minuend layer tuple.	required
layer_b	Iterable[str]	Subtrahend layer tuple.	required
include_inter	bool	Include inter-layer edges touching layer_a.	False
include_coupling	bool	Include coupling edges touching layer_a.	False
**attributes		Slice attributes to store.	{}

Returns:

Type	Description
str	The created slice id.

subgraph_from_layer_tuple(layer_tuple, *, include_inter=False, include_coupling=False)

Concrete subgraph induced by a single Kivela layer.

Parameters:

Name	Type	Description	Default
layer_tuple	Iterable[str]	Layer tuple.	required
include_inter	bool	Include inter-layer edges touching layer_tuple.	False
include_coupling	bool	Include coupling edges touching layer_tuple.	False

Returns:

Type	Description
AnnNet

subgraph_from_layer_union(layer_tuples, *, include_inter=False, include_coupling=False)

Concrete subgraph induced by the union of several layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to union.	required
include_inter	bool	Include inter-layer edges touching any layer in the union.	False
include_coupling	bool	Include coupling edges touching any layer in the union.	False

Returns:

Type	Description
AnnNet

subgraph_from_layer_intersection(layer_tuples, *, include_inter=False, include_coupling=False)

Concrete subgraph induced by the intersection of several layers.

Parameters:

Name	Type	Description	Default
layer_tuples	Iterable[Iterable[str]]	Layer tuples to intersect.	required
include_inter	bool	Include inter-layer edges touching any layer in the intersection.	False
include_coupling	bool	Include coupling edges touching any layer in the intersection.	False

Returns:

Type	Description
AnnNet

subgraph_from_layer_difference(layer_a, layer_b, *, include_inter=False, include_coupling=False)

Concrete subgraph induced by a set-difference of two layers.

Parameters:

Name	Type	Description	Default
layer_a	Iterable[str]	Minuend layer tuple.	required
layer_b	Iterable[str]	Subtrahend layer tuple.	required
include_inter	bool	Include inter-layer edges touching layer_a.	False
include_coupling	bool	Include coupling edges touching layer_a.	False

Returns:

Type	Description
AnnNet

supra_adjacency(layers=None)

Build the supra adjacency matrix.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers. In single-aspect mode, string ids are accepted.	None

Returns:

Type	Description
csr_matrix	Supra adjacency over the chosen vertex–layer index.

Examples:

A = G.supra_adjacency()

supra_incidence(layers=None, include_inter=True, include_coupling=True)

Build the supra-incidence matrix over selected layers.

Unlike supra_adjacency, this preserves the full hyperedge structure —
a k-ary hyperedge becomes a single column with k nonzero entries, with
stoichiometric coefficients intact. Binary intra, inter, coupling, and
hyperedges are all handled in a unified column-oriented representation.

Rows  : vertex-layer pairs (u, aa) — identical index to supra_adjacency,
        built by ensure_vertex_layer_index.
Cols  : one per selected edge, ordered as: intra edges (per layer, sorted
        by eid), then inter/coupling edges, then unassigned hyperedges last.

Column sign convention (matches _matrix):
    - Binary directed   : +w at source row, -w at target row
    - Binary undirected : +w at both rows
    - Hyperedge directed: +w at head rows, -w at tail rows (stoich-aware)
    - Hyperedge undirected: +w at all member rows (stoich-aware)
    - Inter/coupling    : +w at (u, La) row, -w at (v, Lb) row (directed)

Hyperedges MUST have a layer assignment in edge_layers (set via
set_edge_kivela_role(eid, "intra", layer_tuple) after add_hyperedge).
Hyperedges without a layer assignment are collected in the returned
skipped list and excluded from the matrix — they do NOT silently corrupt
the result.

Parameters

layers : list[str] | list[tuple[str, ...]] | None
    Optional subset of layers. None = all layers in V_M.
    Single-aspect string ids are accepted.
include_inter : bool
    Include inter-layer edges in the output columns. Default True.
include_coupling : bool
    Include coupling edges in the output columns. Default True.

Returns

B : scipy.sparse.csr_matrix
    Shape (|V_M|, |E_selected|). Rows are vertex-layer pairs in the
    order given by self._row_to_nl after ensure_vertex_layer_index.
edge_ids : list[str]
    Edge id for each column of B, in column order. Use this to map
    columns back to edges for interpretability.
skipped : list[str]
    Edge ids that were excluded because their layer assignment could
    not be resolved. Inspect these if B looks sparse.

Notes

The hypergraph random-walk diffusion operator follows directly::

    B_csr = B  (this output)
    D_v = diag(|B| @ ones)          # vertex degree (sum of |entries| per row)
    D_e = diag(|B|.T @ ones)        # edge degree (sum of |entries| per col)
    Theta = D_v_inv @ B @ D_e_inv @ B.T

Examples

    B, eids, skipped = G.supra_incidence()

build_intra_block(layers=None)

Supra matrix containing only intra-layer edges (diagonal blocks).

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
csr_matrix

build_inter_block(layers=None)

Supra matrix containing only inter-layer (non-diagonal) edges.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
csr_matrix

build_coupling_block(layers=None)

Supra matrix containing only coupling edges.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
csr_matrix

supra_degree(layers=None)

Degree vector over the supra-graph.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
ndarray

supra_laplacian(kind='comb', layers=None)

Build supra-Laplacian.

Parameters:

Name	Type	Description	Default
kind	str	"comb" for combinatorial L = D - A or "norm" for normalized L = I - D^{-1/2} A D^{-1/2}.	'comb'
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
csr_matrix

add_layer_coupling_pairs(layer_pairs, *, weight=1.0)

Add diagonal couplings for explicit layer pairs.

Parameters:

Name	Type	Description	Default
layer_pairs	list[tuple[tuple[str, ...], tuple[str, ...]]]	Layer tuple pairs (aa, bb).	required
weight	float	Edge weight.	1.0

Returns:

Type	Description
int	Number of edges added.

add_categorical_coupling(aspect, groups, *, weight=1.0)

Add categorical couplings along one aspect.

Parameters:

Name	Type	Description	Default
aspect	str	Aspect name to couple over.	required
groups	list[list[str]]	Groups of elementary labels to fully connect per vertex.	required
weight	float	Edge weight.	1.0

Returns:

Type	Description
int	Number of edges added.

add_diagonal_coupling_filter(layer_filter, *, weight=1.0)

Add diagonal couplings within a filtered layer subspace.

Parameters:

Name	Type	Description	Default
layer_filter	dict[str, set]	Aspect filters (e.g., {"time": {"t1","t2"}}).	required
weight	float	Edge weight.	1.0

Returns:

Type	Description
int	Number of edges added.

tensor_index(layers=None)

Build indices for tensor view.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
tuple	(vertices, layers_t, vertex_to_i, layer_to_i).

Examples:

vertices, layers_t, v2i, l2i = G.tensor_index()

adjacency_tensor_view(layers=None)

Sparse 4-index adjacency view.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
dict	{"vertices","layers","vertex_to_i","layer_to_i","ui","ai","vi","bi","w"}.

Notes

Symmetric entries are emitted twice: (ui, ai, vi, bi) and (vi, bi, ui, ai).

flatten_to_supra(tensor_view)

Flatten a tensor view into a supra adjacency matrix.

Parameters:

Name	Type	Description	Default
tensor_view	dict	Output of :meth:adjacency_tensor_view or :meth:unflatten_from_supra.	required

Returns:

Type	Description
csr_matrix

unflatten_from_supra(A, layers=None)

Unflatten a supra adjacency matrix into a tensor view.

Parameters:

Name	Type	Description	Default
A	spmatrix	Supra adjacency matrix.	required
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
dict	Tensor view with the same schema as :meth:adjacency_tensor_view.

supra_adjacency_scaled(*, coupling_scale=1.0, include_inter=True, layers=None)

Build scaled supra adjacency.

Parameters:

Name	Type	Description	Default
coupling_scale	float	Scaling factor for coupling edges.	1.0
include_inter	bool	Whether to include inter-layer edges.	True
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
csr_matrix

transition_matrix(layers=None)

Row-stochastic transition matrix P = D^{-1} A.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
csr_matrix

random_walk_step(p, layers=None)

One random-walk step p' = p P.

Parameters:

Name	Type	Description	Default
p	array - like	Row vector of length |V_M|.	required
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
ndarray

diffusion_step(x, tau=1.0, kind='comb', layers=None)

One explicit Euler step of diffusion on the supra-graph.

Parameters:

Name	Type	Description	Default
x	array - like	State vector of length |V_M|.	required
tau	float	Time step.	1.0
kind	str	"comb" or "norm".	'comb'
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
ndarray

algebraic_connectivity(layers=None)

Algebraic connectivity of the supra-graph.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
tuple[float, ndarray | None]	(lambda_2, fiedler_vector) or (0.0, None) if too small.

k_smallest_laplacian_eigs(k=6, kind='comb', layers=None)

Return k smallest eigenvalues/eigenvectors of the supra-Laplacian.

Parameters:

Name	Type	Description	Default
k	int	Number of eigenpairs to compute.	6
kind	str	"comb" or "norm".	'comb'
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
tuple[ndarray, ndarray]	(eigenvalues, eigenvectors).

dominant_rw_eigenpair(layers=None)

Dominant eigenpair of the random-walk operator.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
tuple[float, ndarray | None]	(lambda_max, v).

sweep_coupling_regime(scales, metric='algebraic_connectivity', layers=None)

Scan coupling scales and evaluate a metric.

Parameters:

Name	Type	Description	Default
scales	Iterable[float]	Coupling scales to evaluate.	required
metric	str | callable	"algebraic_connectivity" or a callable metric(A)->float.	'algebraic_connectivity'
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
list[float]	Metric values aligned with scales.

layer_degree_vectors(layers=None)

Per-layer degree vectors (intra-layer only).

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
dict	{layer_tuple: (rows_idx_list, deg_vector_np)}.

participation_coefficient(layers=None)

Participation coefficient per vertex.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
dict[str, float]

versatility(layers=None)

Versatility proxy based on dominant eigenvector of supra adjacency.

Parameters:

Name	Type	Description	Default
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers.	None

Returns:

Type	Description
dict[str, float]

multislice_modularity(partition, *, gamma=1.0, omega=1.0, include_inter=False, layers=None)

Mucha et al. multislice modularity (scorer only).

Parameters:

Name	Type	Description	Default
partition	array - like	Community ids, length |V_M| in the current index.	required
gamma	float	Resolution parameter.	1.0
omega	float	Coupling strength (binary coupling structure scaled by omega).	1.0
include_inter	bool	Whether to include inter-layer (non-diagonal) edges.	False
layers	list[str] | list[tuple[str, ...]] | None	Optional subset of layers to score on.	None

Returns:

Type	Description
float	Modularity score Q.

Examples:

Q = G.multislice_modularity(partition)