Spectral layout docstring

src/pixelator/common/graph/backends/implementations/_networkx.py

@@ -1190,7 +1190,45 @@ def spectral_layout(
     seed: Optional[int] = None,
     method: Literal["eigen", "psvd"] = "psvd",
 ):
-    """Use a spectral layout algorithm to compute coordinates from a graph."""
+    """Use a spectral layout algorithm to compute coordinates from a graph.
+
+    The spectral layout algorithm computes ``dim`` eigenvectors of the graph Laplacian
+    corresponding to the smallest non-zero eigenvalues. The layout coordinates
+    are derived from the vectors by using each eigenvector as an embedding axis.
+    Resulting coordinates are normalized (centered at origin and scaled by median
+    radius) before return.
+
+    Args:
+        g: A connected NetworkX graph.
+        dim: Number of output dimension (3 by default).
+        normalize: If the symmetrically normalized Laplacian should be used in the
+        computations. Note that ``normalize=False`` is incompatible with
+        ``method='psvd'``. Defaults to ``True``.
+        seed: Optional random seed.
+        method: Which computational method to use. ``'eigen'`` uses an eigensolver to
+        compute the eigenvectors, while ``'psvd'`` solves an equivalent partial singular
+        value decomposition problem. Solutions generated by the different approaches are
+        equivalent, but ``'psvd'``is generally faster.
+
+    Returns:
+        Dictionary mapping each node in ``g`` to its normalized layout coordinates as a
+        one-dimensional array with length ``dim``.
+
+    Raises:
+        ValueError: If the graph (``g``) does not have more than 1 node.
+        ValueError: If the graph is directed.
+        ValueError: If the graph is not connected.
+        ValueError: If ``dim`` is not 2 or 3.
+        ValueError: If ``method`` is not 'eigen' or 'psvd'.
+        ValueError: If ``method`` is ``'psvd'`` and ``normalize`` is ``False``.
+        ValueError: If using ``'eigen'`` and the number ``dim + 1`` is not less than the
+        number of nodes in the input graph.
+        ValueError: If using the ``'psvd'`` method and ``g`` isn't a bipartite graph whose
+        nodes are partitioned exactly into 'A' and 'B' via the 'pixel_type' attribute.
+        ValueError: If using ``'psvd'`` and ``g`` is not a bipartite graph whose partition
+        sizes ``M``, ``N`` satisfy ``dim + 1 <= min(M, N) - 1``.
+
+    """
     # Validate inputs
     if g.number_of_nodes() in (0, 1):
         raise ValueError("g must have more than 1 node.")