Standardize formatting of 'S'

src/eigenvector_generation.jl

@@ -198,9 +198,9 @@ The number of potential kernel ``\\{-1, 0, 1\\}``-eigenvectors (unique up to spa
 
 Regrettably, the implementation here is rather clunky and unidiomatic, but it is worth
 noting that eigenvector generation is one of two major bottlenecks in the overall
-*S*-bandwidth minimization algorithm. Given how much potential there is for optimization in
-this piece of code, we thus prioritize performance over readability in this particular case,
-making every effort to include inline comments wherever clarification may be needed.
+``S``-bandwidth minimization algorithm. Given how much potential there is for optimization
+in this piece of code, we thus prioritize performance over readability in this particular
+case, making every effort to include inline comments wherever clarification may be needed.
 
 # References
 - [Slo10](@cite): N. J. Sloane, *a(n) = (3^n - 1)/2*. Entry A003462 (2010). Accessed:
@@ -329,9 +329,9 @@ humps in all Motzkin paths of length ``n``. See also the relevant OEIS sequence
 
 Regrettably, the implementation here is rather clunky and unidiomatic, but it is worth
 noting that eigenvector generation is one of two major bottlenecks in the overall
-*S*-bandwidth minimization algorithm. Given how much potential there is for optimization in
-this piece of code, we thus prioritize performance over readability in this particular case,
-making every effort to include inline comments wherever clarification may be needed.
+``S``-bandwidth minimization algorithm. Given how much potential there is for optimization
+in this piece of code, we thus prioritize performance over readability in this particular
+case, making every effort to include inline comments wherever clarification may be needed.
 
 # References
 - [Deu21](@cite): E. Deutsch. *Number of humps in all Motzkin paths of length n*. Entry

src/factories/orthogonality_factory.jl

@@ -19,9 +19,9 @@ matrix bandwidth using zero-based indexing—that is, with the condition ``|i -
 [Maf14, p. 186].)
 
 This type is used as a template for concretely defined properties corresponding to specific
-values of ``k``. In the context of the overarching *S*-bandwidth algorithm, we perform a
+values of ``k``. In the context of the overarching ``S``-bandwidth algorithm, we perform a
 different depth-first search for each family of values of ``k`` on our "tree" of
-*S*-eigenvectors to determine whether there exists a ``k``-orthogonal collection of them.
+``S``-eigenvectors to determine whether there exists a ``k``-orthogonal collection of them.
 
 # Interface
 Concrete subtypes of `KOrthogonality` **must** implement the following fields:
@@ -132,8 +132,8 @@ end
 
 Classifies the `k`-orthogonality property based on the given `k` parameter.
 
-When searching for a ``k``-orthogonal *S*-basis of a given Laplacian eigenspace, the family
-of values to which our ``k`` parameter belongs informs our choice of algorithm.
+When searching for a ``k``-orthogonal ``S``-basis of a given Laplacian eigenspace, the
+family of values to which our ``k`` parameter belongs informs our choice of algorithm.
 
 # Arguments
 - `k::Integer`: the `k`-orthogonality parameter to classify. Must be a positive integer.

src/laplacian_s_spectra.jl

@@ -117,7 +117,7 @@ OrderedCollections.OrderedDict{Int64, Int64} with 3 entries:
 If an undirected graph with integer edge weights is ``\\{-1, 0, 1\\}``-diagonalizable (or,
 more restrictively, ``\\{-1, 1\\}``-diagonalizable), then its Laplacian matrix has integer
 eigenvalues [JP25, p. 312]. Hence, validating Laplacian integrality serves as a useful
-screening step in this package's principal *S*-bandwidth minimization algorithm.
+screening step in this package's principal ``S``*-bandwidth minimization algorithm.
 
 # References
 - [Fox09](@cite): J. Fox. *Lecture 19: The Petersen graph and Moore graphs*. Lecture notes,

src/types.jl

@@ -7,7 +7,7 @@
 """
     AbstractSDiagResult
 
-Abstract base type for all *S*-diagonalizability and *S*-bandwidth problem results.
+Abstract base type for all ``S``-diagonalizability and ``S``-bandwidth problem results.
 
 # Interface
 Concrete subtypes of `AbstractSDiagResult` *must* implement parametric types
@@ -16,10 +16,10 @@ Concrete subtypes of `AbstractSDiagResult` *must* implement parametric types
 - `C<:Union{Nothing,Eigen}`,
 
 alongside the following fields:
-- `network::A`: the network whose *S*-bandwidth is investigated;
-- `S::B`: the set *S* from whose entries we are allowed to construct eigenvectors;
-- `diagonalization::C`: an *S*-diagonalization of the matrix representation of the network,
-    if it satisfies the specified *S*-bandwidth constraints; otherwise, `nothing`.
+- `network::A`: the network whose `S`-bandwidth is investigated;
+- `S::B`: the set from whose entries we are allowed to construct eigenvectors;
+- `diagonalization::C`: an `S`-diagonalization of the matrix representation of the network,
+    if it satisfies the specified `S`-bandwidth constraints; otherwise, `nothing`.
 """
 abstract type AbstractSDiagResult end
 
@@ -174,7 +174,7 @@ eigenvalues are indeed all integers. (Otherwise, the associated field is simply
 If an undirected graph with integer edge weights is ``\\{-1, 0, 1\\}``-diagonalizable (or,
 more restrictively, ``\\{-1, 1\\}``-diagonalizable), then its Laplacian matrix has integer
 eigenvalues [JP25, p. 312]. Hence, validating Laplacian integrality serves as a useful
-screening step in this package's principal *S*-bandwidth minimization algorithm.
+screening step in this package's principal ``S``-bandwidth minimization algorithm.
 
 # References
 - [JP25](@cite): N. Johnston and S. Plosker. *Laplacian {−1,0,1}- and {−1,1}-diagonalizable

src/utils.jl

@@ -242,18 +242,45 @@ end
 """
     _assert_graph_has_defined_s_bandwidth(g) -> Nothing
 
+Validate that `g` is an undirected graph with no self-loops.
+
+The property of ``S``-bandwidth is only defined, by [JP25]'s conventions, for undirected
+graphs without self-loops, so this function checks that `g` satisfies these conditions.
+
+# Arguments
+- `g::AbstractGraph`: the graph of interest.
+
+# Returns
+- `nothing`: if the check is passed, no output is produced.
+
+# Throws
+- `DomainError`: if `g` is directed or has self-loops.
+
+# Examples
 [TODO: Write here]
+
+# Notes
+At first blush, it may seem as though the choice of `DomainError` over something like
+`ArgumentError` (or even simply the return of a boolean) constitutes poor design. However,
+this is informed by the simple *ad hoc* use of this function to validate inputs for other
+functions requiring Laplacian matrices. Certainly, this function is never meant to be
+publicly exposed on its own.
+
+# References
+- [JP25](@cite): N. Johnston and S. Plosker. *Laplacian {−1,0,1}- and {−1,1}-diagonalizable
+    graphs*. Linear Algebra and its Applications **704**, 309–39 (2025).
+    https://doi.org/10.1016/j.laa.2024.10.016.
 """
 function _assert_graph_has_defined_s_bandwidth(g::AbstractGraph)
     if is_directed(g)
-        throw(DomainError(g, "*S*-bandwidth is not defined for directed graphs"))
+        throw(DomainError(g, "S-bandwidth is not defined for directed graphs"))
     end
 
     if has_self_loops(g)
         throw(
             DomainError(
                 graph,
-                "*S*-bandwidth is not defined for multigraphs; got a graph with self-loops",
+                "S-bandwidth is not defined for multigraphs; got a graph with self-loops",
             ),
         )
     end