molscope 0.6.0__py3-none-any.whl

molscope/descriptors.py

@@ -0,0 +1,232 @@
+"""Fixed-size molecular descriptors for quick ML feature tables."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Optional
+
+import numpy as np
+
+from .io import read
+
+DEFAULT_ELEMENTS = (
+    "H", "C", "N", "O", "S", "P", "F", "CL", "BR", "I", "NA", "MG", "CA", "FE", "ZN",
+)
+
+
+def descriptors(
+    molecule,
+    *,
+    elements_to_count=DEFAULT_ELEMENTS,
+    distance_bins: int = 10,
+    distance_range: tuple[float, float] = (0.0, 20.0),
+    contact_cutoff: float = 5.0,
+    residue_contact_cutoff: float = 8.0,
+) -> dict:
+    """Return a flat descriptor dictionary for a molecule.
+
+    The defaults are fixed-size and suitable for small ML tables. Matrix-valued
+    features such as contact maps remain available through ``mol.contact_map()``;
+    this function records table-friendly summaries of them.
+    """
+    coords = np.asarray(molecule.coords, dtype=float)
+    n_atoms = len(molecule)
+    masses = molecule.masses if n_atoms else np.empty(0, dtype=float)
+    desc = {
+        "n_atoms": float(n_atoms),
+        "n_residues": float(_n_residues(molecule)),
+        "molecular_mass": float(masses.sum()) if n_atoms else 0.0,
+    }
+
+    counts = Counter(e.upper() for e in molecule.elements if e)
+    for symbol in elements_to_count:
+        desc[f"count_{symbol.upper()}"] = float(counts.get(symbol.upper(), 0))
+
+    if n_atoms == 0:
+        return _empty_descriptors(desc, distance_bins)
+
+    dims = molecule.dimensions
+    centroid = molecule.centroid
+    center_of_mass = molecule.center_of_mass
+    desc.update({
+        "centroid_x": float(centroid[0]),
+        "centroid_y": float(centroid[1]),
+        "centroid_z": float(centroid[2]),
+        "center_of_mass_x": float(center_of_mass[0]),
+        "center_of_mass_y": float(center_of_mass[1]),
+        "center_of_mass_z": float(center_of_mass[2]),
+        "radius_of_gyration": molecule.radius_of_gyration,
+        "dim_x": float(dims[0]),
+        "dim_y": float(dims[1]),
+        "dim_z": float(dims[2]),
+        "bbox_volume": float(np.prod(dims)),
+        "compactness": _compactness(n_atoms, dims),
+    })
+
+    inertia = inertia_tensor(molecule)
+    principal_moments, principal_axes = np.linalg.eigh(inertia)
+    order = np.argsort(principal_moments)
+    principal_moments = principal_moments[order]
+    principal_axes = principal_axes[:, order]
+    desc["inertia_tensor"] = inertia.reshape(-1).astype(float).tolist()
+    desc["principal_moments"] = principal_moments.astype(float).tolist()
+    desc["principal_axes"] = principal_axes.reshape(-1).astype(float).tolist()
+    desc["shape_anisotropy"] = shape_anisotropy(principal_moments)
+
+    distances = _pairwise_distances(coords)
+    hist, _ = np.histogram(distances, bins=distance_bins, range=distance_range)
+    desc["distance_histogram"] = hist.astype(float).tolist()
+    desc.update(_bond_length_summary(molecule))
+    desc.update(_contact_summary(molecule, contact_cutoff))
+    desc.update(_residue_contact_summary(molecule, residue_contact_cutoff))
+    return desc
+
+
+def inertia_tensor(molecule) -> np.ndarray:
+    """Mass-weighted inertia tensor around the centre of mass."""
+    coords = np.asarray(molecule.coords, dtype=float)
+    if len(molecule) == 0:
+        return np.zeros((3, 3), dtype=float)
+    centered = coords - molecule.center_of_mass
+    masses = molecule.masses
+    r2 = (centered ** 2).sum(axis=1)
+    tensor = np.eye(3) * np.sum(masses * r2)
+    tensor -= centered.T @ (centered * masses[:, None])
+    return tensor
+
+
+def shape_anisotropy(principal_moments) -> float:
+    """Dimensionless anisotropy from principal moments of inertia."""
+    moments = np.asarray(principal_moments, dtype=float)
+    denom = float(np.sum(moments ** 2))
+    if denom == 0.0:
+        return 0.0
+    mean = float(moments.mean())
+    return float(1.5 * np.sum((moments - mean) ** 2) / denom)
+
+
+def featurize_many(
+    paths,
+    *,
+    feature_names: Optional[list[str]] = None,
+    return_names: bool = False,
+    **descriptor_kwargs,
+):
+    """Read structures and return a numeric descriptor matrix.
+
+    By default columns are the union of descriptor keys found across the input
+    molecules. Pass ``feature_names`` to force a stable column order, or
+    ``return_names=True`` to receive ``(X, names)``.
+    """
+    rows = [flatten_descriptors(descriptors(read(path), **descriptor_kwargs)) for path in paths]
+    names = feature_names or sorted({key for row in rows for key in row})
+    matrix = np.array([[row.get(name, 0.0) for name in names] for row in rows], dtype=float)
+    return (matrix, names) if return_names else matrix
+
+
+def flatten_descriptors(desc: dict) -> dict[str, float]:
+    """Expand list-valued descriptors into scalar columns."""
+    flat = {}
+    for key, value in desc.items():
+        if isinstance(value, (list, tuple, np.ndarray)):
+            for i, item in enumerate(value):
+                flat[f"{key}_{i}"] = float(item)
+        else:
+            flat[key] = float(value)
+    return flat
+
+
+def _empty_descriptors(desc: dict, distance_bins: int) -> dict:
+    desc.update({
+        "centroid_x": 0.0,
+        "centroid_y": 0.0,
+        "centroid_z": 0.0,
+        "center_of_mass_x": 0.0,
+        "center_of_mass_y": 0.0,
+        "center_of_mass_z": 0.0,
+        "radius_of_gyration": 0.0,
+        "dim_x": 0.0,
+        "dim_y": 0.0,
+        "dim_z": 0.0,
+        "bbox_volume": 0.0,
+        "compactness": 0.0,
+        "inertia_tensor": [0.0] * 9,
+        "principal_moments": [0.0] * 3,
+        "principal_axes": [0.0] * 9,
+        "shape_anisotropy": 0.0,
+        "distance_histogram": [0.0] * distance_bins,
+        "bond_count": 0.0,
+        "bond_length_mean": 0.0,
+        "bond_length_std": 0.0,
+        "bond_length_min": 0.0,
+        "bond_length_max": 0.0,
+        "atom_contact_count": 0.0,
+        "atom_contact_density": 0.0,
+        "residue_contact_count": 0.0,
+        "residue_contact_density": 0.0,
+    })
+    return desc
+
+
+def _pairwise_distances(coords: np.ndarray) -> np.ndarray:
+    n = len(coords)
+    if n < 2:
+        return np.empty(0, dtype=float)
+    i, j = np.triu_indices(n, k=1)
+    return np.linalg.norm(coords[i] - coords[j], axis=1)
+
+
+def _bond_length_summary(molecule) -> dict[str, float]:
+    bonds = molecule.bonds()
+    if len(bonds) == 0:
+        return {
+            "bond_count": 0.0,
+            "bond_length_mean": 0.0,
+            "bond_length_std": 0.0,
+            "bond_length_min": 0.0,
+            "bond_length_max": 0.0,
+        }
+    lengths = np.linalg.norm(molecule.coords[bonds[:, 0]] - molecule.coords[bonds[:, 1]], axis=1)
+    return {
+        "bond_count": float(len(lengths)),
+        "bond_length_mean": float(lengths.mean()),
+        "bond_length_std": float(lengths.std()),
+        "bond_length_min": float(lengths.min()),
+        "bond_length_max": float(lengths.max()),
+    }
+
+
+def _contact_summary(molecule, cutoff: float) -> dict[str, float]:
+    contacts = molecule.contacts(cutoff=cutoff)
+    possible = len(molecule) * (len(molecule) - 1) / 2
+    return {
+        "atom_contact_count": float(len(contacts)),
+        "atom_contact_density": float(len(contacts) / possible) if possible else 0.0,
+    }
+
+
+def _residue_contact_summary(molecule, cutoff: float) -> dict[str, float]:
+    if len(molecule.resids) == 0:
+        return {"residue_contact_count": 0.0, "residue_contact_density": 0.0}
+    try:
+        matrix = molecule.contact_map(cutoff=cutoff, level="residue").matrix
+    except ValueError:
+        return {"residue_contact_count": 0.0, "residue_contact_density": 0.0}
+    n = len(matrix)
+    possible = n * (n - 1) / 2
+    count = float(np.triu(matrix.astype(bool), k=1).sum())
+    return {
+        "residue_contact_count": count,
+        "residue_contact_density": float(count / possible) if possible else 0.0,
+    }
+
+
+def _n_residues(molecule) -> int:
+    if len(molecule.resids) == 0:
+        return 0
+    return sum(1 for _ in molecule.residue_groups())
+
+
+def _compactness(n_atoms: int, dims: np.ndarray) -> float:
+    volume = float(np.prod(dims))
+    return float(n_atoms / volume) if volume > 0.0 else 0.0

molscope/elements.py

@@ -0,0 +1,75 @@
+"""Per-element reference data: CPK colours and covalent radii.
+
+Values cover the elements common in the sample structures; anything missing
+falls back to a neutral default so unknown atoms still render and bond.
+"""
+
+# CPK colours (normalised RGB), the convention most molecular viewers use.
+CPK_COLORS = {
+    "H": (1.00, 1.00, 1.00),
+    "C": (0.30, 0.30, 0.30),
+    "N": (0.10, 0.10, 0.85),
+    "O": (0.85, 0.10, 0.10),
+    "S": (0.90, 0.80, 0.20),
+    "P": (1.00, 0.50, 0.00),
+    "F": (0.30, 0.80, 0.30),
+    "CL": (0.20, 0.80, 0.20),
+    "BR": (0.60, 0.20, 0.10),
+    "I": (0.50, 0.10, 0.60),
+    "FE": (0.80, 0.40, 0.10),
+    "CA": (0.30, 0.70, 0.70),
+    "NA": (0.50, 0.20, 0.80),
+    "MG": (0.20, 0.60, 0.20),
+    "ZN": (0.50, 0.50, 0.60),
+}
+DEFAULT_COLOR = (0.50, 0.50, 0.50)
+
+# Covalent radii in angstrom (Cordero et al. 2008, rounded). Used to infer bonds.
+COVALENT_RADII = {
+    "H": 0.31, "C": 0.76, "N": 0.71, "O": 0.66, "S": 1.05,
+    "P": 1.07, "F": 0.57, "CL": 1.02, "BR": 1.20, "I": 1.39,
+    "FE": 1.32, "CA": 1.76, "NA": 1.66, "MG": 1.41, "ZN": 1.22,
+}
+DEFAULT_RADIUS = 0.75
+
+
+# Standard atomic weights (g/mol). Unknown atoms fall back to 1.0 so that a
+# mass-weighted centre over all-unknown elements reduces to the geometric mean.
+ATOMIC_MASSES = {
+    "H": 1.008, "C": 12.011, "N": 14.007, "O": 15.999, "S": 32.06,
+    "P": 30.974, "F": 18.998, "CL": 35.45, "BR": 79.904, "I": 126.904,
+    "FE": 55.845, "CA": 40.078, "NA": 22.990, "MG": 24.305, "ZN": 65.38,
+}
+DEFAULT_MASS = 1.0
+
+
+def color(element: str):
+    """CPK colour for an element symbol (case-insensitive)."""
+    return CPK_COLORS.get(element.upper(), DEFAULT_COLOR)
+
+
+def covalent_radius(element: str) -> float:
+    """Covalent radius in angstrom for an element symbol (case-insensitive)."""
+    return COVALENT_RADII.get(element.upper(), DEFAULT_RADIUS)
+
+
+def mass(element: str) -> float:
+    """Atomic weight in g/mol for an element symbol (case-insensitive)."""
+    return ATOMIC_MASSES.get(element.upper(), DEFAULT_MASS)
+
+
+# Atomic numbers for the first four periods (enough for biomolecules and most
+# small molecules); unknown symbols map to 0 so graph code never crashes.
+ATOMIC_NUMBERS = {
+    "H": 1, "HE": 2, "LI": 3, "BE": 4, "B": 5, "C": 6, "N": 7, "O": 8,
+    "F": 9, "NE": 10, "NA": 11, "MG": 12, "AL": 13, "SI": 14, "P": 15,
+    "S": 16, "CL": 17, "AR": 18, "K": 19, "CA": 20, "SC": 21, "TI": 22,
+    "V": 23, "CR": 24, "MN": 25, "FE": 26, "CO": 27, "NI": 28, "CU": 29,
+    "ZN": 30, "GA": 31, "GE": 32, "AS": 33, "SE": 34, "BR": 35, "KR": 36,
+    "I": 53,
+}
+
+
+def atomic_number(element: str) -> int:
+    """Atomic number (Z) for an element symbol (case-insensitive); 0 if unknown."""
+    return ATOMIC_NUMBERS.get(element.upper(), 0)

molscope/ensemble.py

@@ -0,0 +1,143 @@
+"""Analysis across a set of structures, e.g. the models of an NMR ensemble."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Optional
+
+import numpy as np
+
+from .molecule import Molecule
+
+
+def align_all(models: list[Molecule], reference: Optional[Molecule] = None) -> list[Molecule]:
+    """Kabsch-superpose every model onto ``reference`` (default: the first model)."""
+    ref = reference if reference is not None else models[0]
+    return [m.superpose(ref) for m in models]
+
+
+def average(models: list[Molecule], align: bool = True) -> Molecule:
+    """Average structure over the ensemble (atoms matched by index)."""
+    _check_consistent(models)
+    aligned = align_all(models) if align else models
+    coords = np.mean([m.coords for m in aligned], axis=0)
+    return replace(models[0], coords=coords, name=f"{models[0].name} (average)")
+
+
+def rmsf(models: list[Molecule], align: bool = True) -> np.ndarray:
+    """Per-atom root-mean-square fluctuation about the mean position."""
+    _check_consistent(models)
+    aligned = align_all(models) if align else models
+    stack = np.array([m.coords for m in aligned])      # (n_models, n_atoms, 3)
+    mean = stack.mean(axis=0)
+    return np.sqrt(((stack - mean) ** 2).sum(axis=2).mean(axis=0))
+
+
+def contact_frequency(models: list[Molecule], cutoff: float = 8.0,
+                      level: str = "residue", method: str = "ca"):
+    """Fraction of models in which each pair is in contact (an ensemble map).
+
+    Returns a :class:`~molscope.contactmap.ContactMap` whose matrix holds
+    values in ``[0, 1]`` — the contact probability for each residue (or atom)
+    pair across the ensemble. Useful for NMR variability and folding analysis.
+    """
+    from .contactmap import ContactMap, contact_map
+
+    _check_consistent(models)
+    maps = [contact_map(m, cutoff=cutoff, level=level, method=method) for m in models]
+    freq = np.mean([cm.matrix for cm in maps], axis=0)
+    first = maps[0]
+    return ContactMap(freq, level=level, cutoff=cutoff,
+                      labels=first.labels, resids=first.resids)
+
+
+def rmsd_matrix(models: list[Molecule], align: bool = True) -> np.ndarray:
+    """Symmetric ``(M, M)`` matrix of pairwise RMSDs between models."""
+    _check_consistent(models)
+    n = len(models)
+    mat = np.zeros((n, n))
+    for i in range(n):
+        for j in range(i + 1, n):
+            mat[i, j] = mat[j, i] = models[i].rmsd(models[j], align=align)
+    return mat
+
+
+def _check_consistent(models: list[Molecule]) -> None:
+    if not models:
+        raise ValueError("no models given")
+    sizes = {len(m) for m in models}
+    if len(sizes) != 1:
+        raise ValueError(f"models have differing atom counts: {sorted(sizes)}")
+
+
+@dataclass
+class Clustering:
+    """Result of clustering structures by RMSD.
+
+    ``labels`` gives the 1-based cluster id of each model (same order as the
+    input). ``matrix`` is the RMSD matrix used and ``linkage`` the scipy linkage.
+    """
+
+    labels: np.ndarray
+    matrix: np.ndarray
+    linkage: Optional[np.ndarray] = field(default=None)
+
+    @property
+    def n_clusters(self) -> int:
+        return int(len(np.unique(self.labels)))
+
+    @property
+    def order(self) -> np.ndarray:
+        """Model indices sorted by cluster (for a block-diagonal heatmap)."""
+        return np.argsort(self.labels, kind="stable")
+
+    def groups(self) -> dict[int, list[int]]:
+        """Map each cluster id to the list of model indices it contains."""
+        return {int(c): np.where(self.labels == c)[0].tolist()
+                for c in np.unique(self.labels)}
+
+    def medoid(self, cluster_id: int) -> int:
+        """Index of the most central model of a cluster (min total RMSD)."""
+        members = np.where(self.labels == cluster_id)[0]
+        sub = self.matrix[np.ix_(members, members)]
+        return int(members[sub.sum(axis=1).argmin()])
+
+    def representatives(self) -> dict[int, int]:
+        """Map each cluster id to its medoid model index."""
+        return {int(c): self.medoid(int(c)) for c in np.unique(self.labels)}
+
+
+def cluster(models, method: str = "hierarchical", cutoff: Optional[float] = None,
+            n_clusters: Optional[int] = None, linkage: str = "average",
+            align: bool = True, matrix=None) -> Clustering:
+    """Cluster structures by pairwise RMSD.
+
+    Pass ``n_clusters`` to cut the tree into a fixed number of clusters, or
+    ``cutoff`` (an RMSD threshold in angstrom). With neither, a data-driven
+    cutoff (the mean pairwise RMSD) is used. Reuses ``matrix`` if given, else
+    computes :func:`rmsd_matrix`. Requires scipy.
+    """
+    if method != "hierarchical":
+        raise ValueError(f"unknown method {method!r}; only 'hierarchical' is supported")
+
+    dm = np.asarray(matrix, dtype=float) if matrix is not None else rmsd_matrix(models, align=align)
+    if len(dm) < 2:
+        return Clustering(labels=np.ones(len(dm), dtype=int), matrix=dm)
+
+    try:
+        from scipy.cluster.hierarchy import fcluster
+        from scipy.cluster.hierarchy import linkage as _linkage
+        from scipy.spatial.distance import squareform
+    except ImportError as exc:  # pragma: no cover - exercised only without scipy
+        raise ImportError(
+            "clustering needs scipy; install it with: pip install 'molscope[fast]'"
+        ) from exc
+
+    z = _linkage(squareform(dm, checks=False), method=linkage)
+    if n_clusters is not None:
+        labels = fcluster(z, t=n_clusters, criterion="maxclust")
+    else:
+        if cutoff is None:
+            cutoff = float(dm[np.triu_indices_from(dm, k=1)].mean())
+        labels = fcluster(z, t=cutoff, criterion="distance")
+    return Clustering(labels=labels, matrix=dm, linkage=z)

molscope/graph.py

@@ -0,0 +1,151 @@
+"""Molecular graph layer.
+
+``Molecule.to_graph()`` turns 3D coordinates plus inferred bonds into a
+:class:`MolecularGraph` — a small, dependency-free container of node and edge
+data. From there it exports to the common ML graph formats:
+
+    G   = mol.to_graph()
+    nxg = mol.to_networkx()     # networkx.Graph
+    data = mol.to_pyg_data()    # torch_geometric.data.Data
+    dglg = mol.to_dgl_graph()   # dgl.DGLGraph
+
+The exporters import their backend lazily, so networkx / PyTorch Geometric / DGL
+are only required if you actually call the matching method.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+from . import elements
+
+
+@dataclass
+class MolecularGraph:
+    """Atoms as nodes, bonds as edges, with attributes attached to both.
+
+    Nodes carry element, atomic number, mass, coordinates and (when available)
+    atom name, residue name/id and chain. Edges carry the bonded atom pair, the
+    interatomic distance, and a bond order (``1.0`` for geometrically inferred
+    bonds, whose order is unknown).
+    """
+
+    coords: np.ndarray              # (N, 3)
+    elements: list[str]
+    edges: np.ndarray               # (E, 2), i < j
+    edge_distances: np.ndarray      # (E,)
+    edge_types: np.ndarray          # (E,) bond order; 1.0 when inferred/unknown
+    atom_names: list[str] = field(default_factory=list)
+    resnames: list[str] = field(default_factory=list)
+    resids: np.ndarray = field(default_factory=lambda: np.empty(0, dtype=int))
+    chains: list[str] = field(default_factory=list)
+    name: str = ""
+
+    @property
+    def n_atoms(self) -> int:
+        return len(self.coords)
+
+    @property
+    def n_bonds(self) -> int:
+        return len(self.edges)
+
+    @property
+    def atomic_numbers(self) -> np.ndarray:
+        return np.array([elements.atomic_number(e) for e in self.elements])
+
+    @property
+    def masses(self) -> np.ndarray:
+        return np.array([elements.mass(e) for e in self.elements])
+
+    def node_features(self) -> np.ndarray:
+        """Default ``(N, 2)`` node feature matrix: ``[atomic_number, mass]``."""
+        return np.stack([self.atomic_numbers, self.masses], axis=1).astype(float)
+
+    # -- exporters ----------------------------------------------------------
+
+    def to_networkx(self):
+        """Return a ``networkx.Graph`` with node and edge attributes."""
+        nx = _require("networkx", "networkx", "pip install networkx")
+        g = nx.Graph(name=self.name)
+        z, m = self.atomic_numbers, self.masses
+        for i in range(self.n_atoms):
+            attrs = {
+                "element": self.elements[i],
+                "atomic_number": int(z[i]),
+                "mass": float(m[i]),
+                "pos": tuple(float(c) for c in self.coords[i]),
+            }
+            if self.atom_names:
+                attrs["atom_name"] = self.atom_names[i]
+            if self.resnames:
+                attrs["resname"] = self.resnames[i]
+            if len(self.resids):
+                attrs["resid"] = int(self.resids[i])
+            if self.chains:
+                attrs["chain"] = self.chains[i]
+            g.add_node(i, **attrs)
+        for (i, j), dist, btype in zip(self.edges, self.edge_distances, self.edge_types):
+            g.add_edge(int(i), int(j), distance=float(dist), bond_type=float(btype))
+        return g
+
+    def to_pyg_data(self):
+        """Return a ``torch_geometric.data.Data`` object.
+
+        Populates ``x`` (node features), ``z`` (atomic numbers), ``pos`` (3D
+        coordinates), ``edge_index`` and ``edge_attr`` (distances). Edges are
+        made bidirectional for message passing.
+        """
+        torch = _require("torch", "PyTorch Geometric", "pip install torch torch_geometric")
+        Data = _require(
+            "torch_geometric.data", "PyTorch Geometric",
+            "pip install torch torch_geometric", attr="Data",
+        )
+        src, dst, dist = self._directed_edges()
+        return Data(
+            x=torch.tensor(self.node_features(), dtype=torch.float),
+            z=torch.tensor(self.atomic_numbers, dtype=torch.long),
+            pos=torch.tensor(self.coords, dtype=torch.float),
+            edge_index=torch.tensor(np.stack([src, dst]), dtype=torch.long),
+            edge_attr=torch.tensor(dist[:, None], dtype=torch.float),
+            num_nodes=self.n_atoms,
+        )
+
+    def to_dgl_graph(self):
+        """Return a ``dgl.DGLGraph`` with node/edge feature tensors."""
+        dgl = _require("dgl", "DGL", "pip install dgl")
+        torch = _require("torch", "DGL", "pip install dgl torch")
+        src, dst, dist = self._directed_edges()
+        g = dgl.graph(
+            (torch.tensor(src, dtype=torch.long), torch.tensor(dst, dtype=torch.long)),
+            num_nodes=self.n_atoms,
+        )
+        g.ndata["feat"] = torch.tensor(self.node_features(), dtype=torch.float)
+        g.ndata["z"] = torch.tensor(self.atomic_numbers, dtype=torch.long)
+        g.ndata["pos"] = torch.tensor(self.coords, dtype=torch.float)
+        g.edata["distance"] = torch.tensor(dist, dtype=torch.float)
+        return g
+
+    def _directed_edges(self):
+        """Edges in both directions: (src, dst, distance) for message passing."""
+        if self.n_bonds == 0:
+            empty_i = np.empty(0, dtype=int)
+            return empty_i, empty_i, np.empty(0, dtype=float)
+        i, j = self.edges[:, 0], self.edges[:, 1]
+        src = np.concatenate([i, j])
+        dst = np.concatenate([j, i])
+        dist = np.concatenate([self.edge_distances, self.edge_distances])
+        return src, dst, dist
+
+
+def _require(module: str, feature: str, hint: str, attr: Optional[str] = None):
+    """Import a backend module (or attribute), raising a friendly error if absent."""
+    import importlib
+
+    try:
+        mod = importlib.import_module(module)
+    except ImportError as exc:  # pragma: no cover - exercised only when missing
+        raise ImportError(f"{feature} is required for this export; {hint}") from exc
+    return getattr(mod, attr) if attr else mod