API reference
Public, exported
SparseMatrixColorings.SparseMatrixColorings — ModuleSparseMatrixColoringsSparseMatrixColorings.jl
Coloring algorithms for sparse Jacobian and Hessian matrices.
Getting started
To install this package, run the following in a Julia Pkg REPL:
pkg> add SparseMatrixColoringsBackground
The algorithms implemented in this package are taken from the following articles:
- What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
- New Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007)
- Efficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009)
- ColPack: Software for graph coloring and related problems in scientific computing, Gebremedhin et al. (2013)
Some parts of the articles (like definitions) are thus copied verbatim in the documentation.
Alternatives
- ColPack.jl: a Julia interface to the C++ library ColPack
- SparseDiffTools.jl: contains Julia implementations of some coloring algorithms
SparseMatrixColorings.GreedyColoringAlgorithm — TypeGreedyColoringAlgorithm <: ADTypes.AbstractColoringAlgorithmGreedy coloring algorithm for sparse Jacobians and Hessians, with configurable vertex order.
Compatible with the ADTypes.jl coloring framework.
Constructor
GreedyColoringAlgorithm(order::AbstractOrder=NaturalOrder())See also
ADTypes.column_coloring — Functioncolumn_coloring(A::AbstractMatrix, algo::GreedyColoringAlgorithm)Compute a partial distance-2 coloring of the columns in the bipartite graph of the matrix A.
Function defined by ADTypes, re-exported by SparseMatrixColorings.
Example
using SparseMatrixColorings, SparseArrays
+API reference · SparseMatrixColorings.jl API reference
Public, exported
SparseMatrixColorings.SparseMatrixColorings — ModuleSparseMatrixColorings
SparseMatrixColorings.jl
Coloring algorithms for sparse Jacobian and Hessian matrices.
Getting started
To install this package, run the following in a Julia Pkg REPL:
pkg> add SparseMatrixColorings
Background
The algorithms implemented in this package are taken from the following articles:
- What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
- New Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007)
- Efficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009)
- ColPack: Software for graph coloring and related problems in scientific computing, Gebremedhin et al. (2013)
Some parts of the articles (like definitions) are thus copied verbatim in the documentation.
Alternatives
- ColPack.jl: a Julia interface to the C++ library ColPack
- SparseDiffTools.jl: contains Julia implementations of some coloring algorithms
sourceSparseMatrixColorings.GreedyColoringAlgorithm — TypeGreedyColoringAlgorithm <: ADTypes.AbstractColoringAlgorithm
Greedy coloring algorithm for sparse Jacobians and Hessians, with configurable vertex order.
Compatible with the ADTypes.jl coloring framework.
Constructor
GreedyColoringAlgorithm(order::AbstractOrder=NaturalOrder())
See also
sourceADTypes.column_coloring — Functioncolumn_coloring(A::AbstractMatrix, algo::GreedyColoringAlgorithm)
Compute a partial distance-2 coloring of the columns in the bipartite graph of the matrix A.
Function defined by ADTypes, re-exported by SparseMatrixColorings.
Example
using SparseMatrixColorings, SparseArrays
algo = GreedyColoringAlgorithm(SparseMatrixColorings.LargestFirst())
@@ -19,7 +19,7 @@
2
1
2
- 3
sourceADTypes.row_coloring — Functionrow_coloring(A::AbstractMatrix, algo::GreedyColoringAlgorithm)
Compute a partial distance-2 coloring of the rows in the bipartite graph of the matrix A.
Function defined by ADTypes, re-exported by SparseMatrixColorings.
Example
using SparseMatrixColorings, SparseArrays
+ 3
sourceADTypes.row_coloring — Functionrow_coloring(A::AbstractMatrix, algo::GreedyColoringAlgorithm)
Compute a partial distance-2 coloring of the rows in the bipartite graph of the matrix A.
Function defined by ADTypes, re-exported by SparseMatrixColorings.
Example
using SparseMatrixColorings, SparseArrays
algo = GreedyColoringAlgorithm(SparseMatrixColorings.LargestFirst())
@@ -38,41 +38,41 @@
2
2
3
- 1
sourceADTypes.symmetric_coloring — Functionsymmetric_coloring(A::AbstractMatrix, algo::GreedyColoringAlgorithm)
Compute a star coloring of the columns in the adjacency graph of the symmetric matrix A.
Function defined by ADTypes, re-exported by SparseMatrixColorings.
Example
Warning Work in progress.
sourcePublic, not exported
Orders
SparseMatrixColorings.AbstractOrder — TypeAbstractOrder
Abstract supertype for vertex ordering schemes.
Subtypes
sourceSparseMatrixColorings.NaturalOrder — TypeNaturalOrder()
Order vertices as they come in the graph.
sourceSparseMatrixColorings.RandomOrder — TypeRandomOrder(rng=default_rng())
Order vertices with a random permutation.
sourceSparseMatrixColorings.LargestFirst — TypeLargestFirst()
Order vertices by decreasing degree.
sourceDecompression
SparseMatrixColorings.color_groups — Functioncolor_groups(color)
Return group::Vector{Vector{Int}} such that i ∈ group[c] iff color[i] == c.
Assumes the colors are contiguously numbered from 1 to some cmax.
sourceSparseMatrixColorings.decompress_columns — Functiondecompress_columns(
+ 1
sourceADTypes.symmetric_coloring — Functionsymmetric_coloring(A::AbstractMatrix, algo::GreedyColoringAlgorithm)
Compute a star coloring of the columns in the adjacency graph of the symmetric matrix A.
Function defined by ADTypes, re-exported by SparseMatrixColorings.
Example
Warning Work in progress.
sourcePublic, not exported
Orders
SparseMatrixColorings.AbstractOrder — TypeAbstractOrder
Abstract supertype for vertex ordering schemes.
Subtypes
sourceSparseMatrixColorings.NaturalOrder — TypeNaturalOrder()
Order vertices as they come in the graph.
sourceSparseMatrixColorings.RandomOrder — TypeRandomOrder(rng=default_rng())
Order vertices with a random permutation.
sourceSparseMatrixColorings.LargestFirst — TypeLargestFirst()
Order vertices by decreasing degree.
sourceDecompression
SparseMatrixColorings.color_groups — Functioncolor_groups(color)
Return group::Vector{Vector{Int}} such that i ∈ group[c] iff color[i] == c.
Assumes the colors are contiguously numbered from 1 to some cmax.
sourceSparseMatrixColorings.decompress_columns — Functiondecompress_columns(
S::AbstractMatrix{Bool},
B::AbstractMatrix{R},
color::AbstractVector{<:Integer}
-) where {R<:Real}
Decompress the thin matrix B into a new fat matrix A with the same sparsity pattern as S.
Here, color is a column coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
sourceSparseMatrixColorings.decompress_columns! — Functiondecompress_columns!(
+) where {R<:Real}
Decompress the thin matrix B into a new fat matrix A with the same sparsity pattern as S.
Here, color is a column coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
sourceSparseMatrixColorings.decompress_columns! — Functiondecompress_columns!(
A::AbstractMatrix{R},
S::AbstractMatrix{Bool},
B::AbstractMatrix{R},
color::AbstractVector{<:Integer}
-) where {R<:Real}
Decompress the thin matrix B into the fat matrix A which must have the same sparsity pattern as S.
Here, color is a column coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
sourceSparseMatrixColorings.decompress_rows — Functiondecompress_rows(
+) where {R<:Real}
Decompress the thin matrix B into the fat matrix A which must have the same sparsity pattern as S.
Here, color is a column coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
sourceSparseMatrixColorings.decompress_rows — Functiondecompress_rows(
S::AbstractMatrix{Bool},
B::AbstractMatrix{R},
color::AbstractVector{<:Integer}
-) where {R<:Real}
Decompress the small matrix B into a new tall matrix A with the same sparsity pattern as S.
Here, color is a row coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
sourceSparseMatrixColorings.decompress_rows! — Functiondecompress_rows!(
+) where {R<:Real}
Decompress the small matrix B into a new tall matrix A with the same sparsity pattern as S.
Here, color is a row coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
sourceSparseMatrixColorings.decompress_rows! — Functiondecompress_rows!(
A::AbstractMatrix{R},
S::AbstractMatrix{Bool},
B::AbstractMatrix{R},
color::AbstractVector{<:Integer}
-) where {R<:Real}
Decompress the small matrix B into the tall matrix A which must have the same sparsity pattern as S.
Here, color is a row coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
sourceSparseMatrixColorings.decompress_symmetric — Functiondecompress_symmetric(
+) where {R<:Real}
Decompress the small matrix B into the tall matrix A which must have the same sparsity pattern as S.
Here, color is a row coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
sourceSparseMatrixColorings.decompress_symmetric — Functiondecompress_symmetric(
S::AbstractMatrix{Bool},
B::AbstractMatrix{R},
colors::AbstractVector{<:Integer}
-) where {R<:Real}
Decompress the thin matrix B into a new symmetric matrix A with the same sparsity pattern as S.
Here, colors is a symmetric coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
References
Efficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009)
sourceSparseMatrixColorings.decompress_symmetric! — Functiondecompress_symmetric!(
+) where {R<:Real}
Decompress the thin matrix B into a new symmetric matrix A with the same sparsity pattern as S.
Here, colors is a symmetric coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
References
Efficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009)
sourceSparseMatrixColorings.decompress_symmetric! — Functiondecompress_symmetric!(
A::AbstractMatrix{R},
S::AbstractMatrix{Bool},
B::AbstractMatrix{R},
color::AbstractVector{<:Integer}
-) where {R<:Real}
Decompress the thin matrix B into the symmetric matrix A which must have the same sparsity pattern as S.
Here, color is a symmetric coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
References
Efficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009), Figure 2
sourcePrivate
Matrices
SparseMatrixColorings.matrix_versions — Functionmatrix_versions(A::AbstractMatrix)
Return various versions of the same matrix:
- dense and sparse
- transpose and adjoint
Used for internal testing.
sourceSparseMatrixColorings.respectful_similar — Functionrespectful_similar(A::AbstractMatrix)
-respectful_similar(A::AbstractMatrix, ::Type{T})
Like Base.similar but returns a transpose or adjoint when A is a transpose or adjoint.
sourceSparseMatrixColorings.same_sparsity_pattern — Functionsame_sparsity_pattern(A::AbstractMatrix, B::AbstractMatrix)
Perform a partial equality check on the sparsity patterns of A and B:
- if the return is
true, they might have the same sparsity pattern but we're not sure - if the return is
false, they definitely don't have the same sparsity pattern
sourceGraphs
SparseMatrixColorings.Graph — TypeGraph{T}
Undirected graph structure stored in Compressed Sparse Column (CSC) format.
Fields
colptr::Vector{T}: same as for SparseMatrixCSCrowval::Vector{T}: same as for SparseMatrixCSC
sourceSparseMatrixColorings.BipartiteGraph — TypeBipartiteGraph{T}
Undirected bipartite graph structure stored in bidirectional Compressed Sparse Column format (redundancy allows for faster access).
A bipartite graph has two "sides", which we number 1 and 2.
Fields
g1::Graph{T}: contains the neighbors for vertices on side 1g2::Graph{T}: contains the neighbors for vertices on side 2
sourceSparseMatrixColorings.adjacency_graph — Functionadjacency_graph(H::AbstractMatrix)
Return a Graph representing the nonzeros of a symmetric matrix (typically a Hessian matrix).
The adjacency graph of a symmetrix matric A ∈ ℝ^{n × n} is G(A) = (V, E) where
V = 1:n is the set of rows or columns i/j(i, j) ∈ E whenever A[i, j] ≠ 0 and i ≠ j
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSparseMatrixColorings.bipartite_graph — Functionbipartite_graph(J::AbstractMatrix)
Return a BipartiteGraph representing the nonzeros of a non-symmetric matrix (typically a Jacobian matrix).
The bipartite graph of a matrix A ∈ ℝ^{m × n} is Gb(A) = (V₁, V₂, E) where
V₁ = 1:m is the set of rows iV₂ = 1:n is the set of columns j(i, j) ∈ E whenever A[i, j] ≠ 0
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSparseMatrixColorings.neighbors — Functionneighbors(bg::BipartiteGraph, Val(side), v::Integer)
Return the neighbors of v (a vertex from the specified side, 1 or 2), in the graph bg.
sourceSparseMatrixColorings.vertices — Functionvertices(bg::BipartiteGraph, Val(side))
Return the list of vertices of bg from the specified side as a range 1:n.
sourceColoring
SparseMatrixColorings.partial_distance2_coloring — Functionpartial_distance2_coloring(bg::BipartiteGraph, ::Val{side}, order::AbstractOrder)
Compute a distance-2 coloring of the given side (1 or 2) in the bipartite graph bg and return a vector of integer colors.
A distance-2 coloring is such that two vertices have different colors if they are at distance at most 2.
The vertices are colored in a greedy fashion, following the order supplied.
See also
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005), Algorithm 3.2
sourceSparseMatrixColorings.star_coloring — Functionstar_coloring(g::Graph, order::AbstractOrder)
Compute a star coloring of all vertices in the adjacency graph g and return a vector of integer colors.
A star coloring is a distance-1 coloring such that every path on 4 vertices uses at least 3 colors.
The vertices are colored in a greedy fashion, following the order supplied.
See also
References
New Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007), Algorithm 4.1
sourceTesting
SparseMatrixColorings.structurally_orthogonal_columns — Functionstructurally_orthogonal_columns(
+) where {R<:Real}
Decompress the thin matrix B into the symmetric matrix A which must have the same sparsity pattern as S.
Here, color is a symmetric coloring of S, while B is a compressed representation of matrix A obtained by summing the columns that share the same color.
References
Efficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009), Figure 2
sourcePrivate
Matrices
SparseMatrixColorings.matrix_versions — Functionmatrix_versions(A::AbstractMatrix)
Return various versions of the same matrix:
- dense and sparse
- transpose and adjoint
Used for internal testing.
sourceSparseMatrixColorings.respectful_similar — Functionrespectful_similar(A::AbstractMatrix)
+respectful_similar(A::AbstractMatrix, ::Type{T})
Like Base.similar but returns a transpose or adjoint when A is a transpose or adjoint.
sourceSparseMatrixColorings.same_sparsity_pattern — Functionsame_sparsity_pattern(A::AbstractMatrix, B::AbstractMatrix)
Perform a partial equality check on the sparsity patterns of A and B:
- if the return is
true, they might have the same sparsity pattern but we're not sure - if the return is
false, they definitely don't have the same sparsity pattern
sourceGraphs
SparseMatrixColorings.Graph — TypeGraph{T}
Undirected graph structure stored in Compressed Sparse Column (CSC) format.
Fields
colptr::Vector{T}: same as for SparseMatrixCSCrowval::Vector{T}: same as for SparseMatrixCSC
sourceSparseMatrixColorings.BipartiteGraph — TypeBipartiteGraph{T}
Undirected bipartite graph structure stored in bidirectional Compressed Sparse Column format (redundancy allows for faster access).
A bipartite graph has two "sides", which we number 1 and 2.
Fields
g1::Graph{T}: contains the neighbors for vertices on side 1g2::Graph{T}: contains the neighbors for vertices on side 2
sourceSparseMatrixColorings.adjacency_graph — Functionadjacency_graph(H::AbstractMatrix)
Return a Graph representing the nonzeros of a symmetric matrix (typically a Hessian matrix).
The adjacency graph of a symmetrix matric A ∈ ℝ^{n × n} is G(A) = (V, E) where
V = 1:n is the set of rows or columns i/j(i, j) ∈ E whenever A[i, j] ≠ 0 and i ≠ j
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSparseMatrixColorings.bipartite_graph — Functionbipartite_graph(J::AbstractMatrix)
Return a BipartiteGraph representing the nonzeros of a non-symmetric matrix (typically a Jacobian matrix).
The bipartite graph of a matrix A ∈ ℝ^{m × n} is Gb(A) = (V₁, V₂, E) where
V₁ = 1:m is the set of rows iV₂ = 1:n is the set of columns j(i, j) ∈ E whenever A[i, j] ≠ 0
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSparseMatrixColorings.neighbors — Functionneighbors(bg::BipartiteGraph, Val(side), v::Integer)
Return the neighbors of v (a vertex from the specified side, 1 or 2), in the graph bg.
sourceSparseMatrixColorings.vertices — Functionvertices(bg::BipartiteGraph, Val(side))
Return the list of vertices of bg from the specified side as a range 1:n.
sourceColoring
SparseMatrixColorings.partial_distance2_coloring — Functionpartial_distance2_coloring(bg::BipartiteGraph, ::Val{side}, order::AbstractOrder)
Compute a distance-2 coloring of the given side (1 or 2) in the bipartite graph bg and return a vector of integer colors.
A distance-2 coloring is such that two vertices have different colors if they are at distance at most 2.
The vertices are colored in a greedy fashion, following the order supplied.
See also
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005), Algorithm 3.2
sourceSparseMatrixColorings.star_coloring — Functionstar_coloring(g::Graph, order::AbstractOrder)
Compute a star coloring of all vertices in the adjacency graph g and return a vector of integer colors.
A star coloring is a distance-1 coloring such that every path on 4 vertices uses at least 3 colors.
The vertices are colored in a greedy fashion, following the order supplied.
See also
References
New Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007), Algorithm 4.1
sourceTesting
SparseMatrixColorings.structurally_orthogonal_columns — Functionstructurally_orthogonal_columns(
A::AbstractMatrix, color::AbstractVector{<:Integer}
verbose=false
-)
Return true if coloring the columns of the matrix A with the vector color results in a partition that is structurally orthogonal, and false otherwise.
A partition of the columns of a matrix A is structurally orthogonal if, for every nonzero element A[i, j], the group containing column A[:, j] has no other column with a nonzero in row i.
Warning This function is not coded with efficiency in mind, it is designed for small-scale tests.
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSparseMatrixColorings.symmetrically_orthogonal_columns — Functionsymmetrically_orthogonal_columns(
+)
Return true if coloring the columns of the matrix A with the vector color results in a partition that is structurally orthogonal, and false otherwise.
A partition of the columns of a matrix A is structurally orthogonal if, for every nonzero element A[i, j], the group containing column A[:, j] has no other column with a nonzero in row i.
Warning This function is not coded with efficiency in mind, it is designed for small-scale tests.
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSparseMatrixColorings.symmetrically_orthogonal_columns — Functionsymmetrically_orthogonal_columns(
A::AbstractMatrix, color::AbstractVector{<:Integer};
verbose=false
-)
Return true if coloring the columns of the symmetric matrix A with the vector color results in a partition that is symmetrically orthogonal, and false otherwise.
A partition of the columns of a symmetrix matrix A is symmetrically orthogonal if, for every nonzero element A[i, j], either of the following statements holds:
- the group containing the column
A[:, j] has no other column with a nonzero in row i - the group containing the column
A[:, i] has no other column with a nonzero in row j
Warning This function is not coded with efficiency in mind, it is designed for small-scale tests.
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSparseMatrixColorings.directly_recoverable_columns — Functiondirectly_recoverable_columns(
+)
Return true if coloring the columns of the symmetric matrix A with the vector color results in a partition that is symmetrically orthogonal, and false otherwise.
A partition of the columns of a symmetrix matrix A is symmetrically orthogonal if, for every nonzero element A[i, j], either of the following statements holds:
- the group containing the column
A[:, j] has no other column with a nonzero in row i - the group containing the column
A[:, i] has no other column with a nonzero in row j
Warning This function is not coded with efficiency in mind, it is designed for small-scale tests.
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSparseMatrixColorings.directly_recoverable_columns — Functiondirectly_recoverable_columns(
A::AbstractMatrix, color::AbstractVector{<:Integer}
verbose=false
-)
Return true if coloring the columns of the symmetric matrix A with the vector color results in a column-compressed representation that preserves every unique value, thus making direct recovery possible.
Warning This function is not coded with efficiency in mind, it is designed for small-scale tests.
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)
sourceSettings
This document was generated with Documenter.jl version 1.4.1 on Tuesday 4 June 2024. Using Julia version 1.10.3.
Return true if coloring the columns of the symmetric matrix A with the vector color results in a column-compressed representation that preserves every unique value, thus making direct recovery possible.
This function is not coded with efficiency in mind, it is designed for small-scale tests.
References
What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)