From 3f177493c5f6513d06844c0daeb31ec0a67262d5 Mon Sep 17 00:00:00 2001 From: Luis-Varona Date: Wed, 13 Aug 2025 14:32:05 -0300 Subject: [PATCH] Standardize formatting of 'S' This PR standardizes the formatting of 'S' in docstrings, surrounding it with double backticks every time unless it is in reference to a parameter (in which case single backticks are used). It also fleshes out the docstring for the '_assert_graph_has_defined_s_bandwidth' method in utils, although that is not yet complete. --- src/eigenvector_generation.jl | 12 +++++----- src/factories/orthogonality_factory.jl | 8 +++---- src/laplacian_s_spectra.jl | 2 +- src/types.jl | 12 +++++----- src/utils.jl | 31 ++++++++++++++++++++++++-- 5 files changed, 46 insertions(+), 19 deletions(-) diff --git a/src/eigenvector_generation.jl b/src/eigenvector_generation.jl index 014579b..7968e36 100644 --- a/src/eigenvector_generation.jl +++ b/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 diff --git a/src/factories/orthogonality_factory.jl b/src/factories/orthogonality_factory.jl index 0055c98..5a62d04 100644 --- a/src/factories/orthogonality_factory.jl +++ b/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. diff --git a/src/laplacian_s_spectra.jl b/src/laplacian_s_spectra.jl index 1e9e6fe..35a3d0c 100644 --- a/src/laplacian_s_spectra.jl +++ b/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, diff --git a/src/types.jl b/src/types.jl index 2cf977a..74e6fea 100644 --- a/src/types.jl +++ b/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 diff --git a/src/utils.jl b/src/utils.jl index 77d8d61..eb170b4 100644 --- a/src/utils.jl +++ b/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