MultiGraph ↔ NumPy adjacency arrays: what aggregation policy prevents silent semantic loss during conversion?

Direct answer

Use a fail-fast custom aggregator for multigraph_weight that raises an exception whenever more than one edge exists between a node pair, and explicitly pass nodelist and weight on both sides of the conversion. The built-in sum default is unsafe because it silently conflates edge multiplicity with summed weight attributes, and from_numpy_array cannot reconstruct multiplicity afterward. No current NetworkX release exposes a convention flag to distinguish the two cases, so caller-side enforcement is mandatory; documentation alone is insufficient because producers and consumers can interpret the same scalar differently.

Why sum is lossy

When a MultiGraph contains parallel edges, to_numpy_array must reduce them to one scalar per cell. With multigraph_weight=sum (the default), an unweighted graph with two parallel edges produces 2, while a weighted graph with edges of weight 1 and 5 also produces 6. The consumer cannot tell whether 6 represents six unweighted relationships, one edge of weight 6, or a mix. This ambiguity is the core semantic loss.

The fail-fast policy

Define an aggregator that returns the sole weight when exactly one edge exists and raises otherwise:

def strict_aggregator(weights):
    if len(weights) != 1:
        raise ValueError("parallel edges detected; multiplicity lost")
    return weights[0]

Passing this to to_numpy_array makes the conversion abort the moment parallel edges appear, forcing the caller to handle multiplicity explicitly (for example, by storing a separate count matrix or by pre-aggregating with a documented policy).

Reversibility limits

from_numpy_array creates at most one edge per ordered node pair. No aggregator can recover multiplicity after the array exists. If round-tripping is required, the caller must persist the original graph or emit a side-channel structure (such as a second integer matrix for edge counts) alongside the dense array.

Version and keyword alignment

These instructions assume NetworkX 3.x. The multigraph_weight parameter was introduced after NetworkX 2.4; earlier versions hard-code summation and cannot be configured. In 3.x, to_scipy_sparse_array accepts the same keyword, but you should verify the signature in your installed version before relying on it. Always pass nodelist explicitly so row/column order is deterministic, and set weight to the exact attribute name used by the producer. A mismatch in either silently produces incorrect values.

Can consumers detect aggregation?

Not from the array alone. A nonzero cell is indistinguishable from a single weighted edge unless the producer guarantees—via a fail-fast aggregator or external metadata—that no parallel edges were collapsed. If the producer used sum, the consumer has no reliable way to audit the cell.

Verification

1. Build a MultiGraph with two parallel edges between nodes 0 and 1: one unweighted and one with weight=5.
2. Call nx.to_numpy_array(MG, multigraph_weight=sum) and confirm the cell equals 6, demonstrating the conflation.
3. Call nx.to_numpy_array(MG, multigraph_weight=strict_aggregator) and verify a ValueError is raised.
4. Call nx.from_numpy_array(result) on a successfully converted simple graph and confirm only one edge exists per pair.
5. If using sparse output, repeat with nx.to_scipy_sparse_array(MG, multigraph_weight=strict_aggregator) to confirm identical behavior in your version.