diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index a22c8d0..4827a61 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-10-07T18:58:08","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.0","generation_timestamp":"2024-10-08T13:37:45","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 3fb87c1..f6f7094 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,5 +1,5 @@ -API reference · SparseMatrixColorings.jl
GitHub

API reference

The docstrings on this page define the public API of the package.

SparseMatrixColorings.SparseMatrixColorings — Module
SparseMatrixColorings

SparseMatrixColorings.jl

Build Status Stable Documentation Dev Documentation Coverage Code Style: Blue DOI

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:

Some parts of the articles (like definitions) are thus copied verbatim in the documentation.

Alternatives

Citing

Please cite this software using the Zenodo DOI of the version you used. The link https://zenodo.org/doi/10.5281/zenodo.11314275 resolves to the latest version.

Exports

source

Main function

SparseMatrixColorings.coloring — Function
coloring(
+API reference · SparseMatrixColorings.jl
GitHub
API reference
The docstrings on this page define the public API of the package.
SparseMatrixColorings.SparseMatrixColorings — Module
SparseMatrixColorings
SparseMatrixColorings.jl
Build Status Stable Documentation Dev Documentation Coverage Code Style: Blue DOI
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:
Some parts of the articles (like definitions) are thus copied verbatim in the documentation.
Alternatives
Citing
Please cite this software using the Zenodo DOI of the version you used. The link https://zenodo.org/doi/10.5281/zenodo.11314275 resolves to the latest version.
Exports
source
Main function
SparseMatrixColorings.ColoringProblem — Type
ColoringProblem{structure,partition}
Selector type for the coloring problem to solve, enabling multiple dispatch.
It is passed as an argument to the main function coloring.
Constructors
ColoringProblem{structure,partition}()
-ColoringProblem(; structure=:nonsymmetric, partition=:column)
  • structure::Symbol: either :nonsymmetric or :symmetric
  • partition::Symbol: either :column, :row or :bidirectional
Warning
The second constructor (based on keyword arguments) is type-unstable.
Link to automatic differentiation
Matrix coloring is often used in automatic differentiation, and here is the translation guide:
matrixmodestructurepartitionimplemented
Jacobianforward:nonsymmetric:columnyes
Jacobianreverse:nonsymmetric:rowyes
Jacobianmixed:nonsymmetric:bidirectionalno
Hessian-:symmetric:columnyes
Hessian-:symmetric:rowno
source
SparseMatrixColorings.GreedyColoringAlgorithm — Type
GreedyColoringAlgorithm{decompression} <: ADTypes.AbstractColoringAlgorithm
Greedy coloring algorithm for sparse matrices which colors columns or rows one after the other, following a configurable order.
It is passed as an argument to the main function coloring.
Constructors
GreedyColoringAlgorithm{decompression}(order=NaturalOrder())
-GreedyColoringAlgorithm(order=NaturalOrder(); decompression=:direct)
  • order::AbstractOrder: the order in which the columns or rows are colored, which can impact the number of colors.
  • decompression::Symbol: either :direct or :substitution. Usually :substitution leads to fewer colors, at the cost of a more expensive coloring (and decompression). When :substitution is not applicable, it falls back on :direct decompression.
Warning
The second constructor (based on keyword arguments) is type-unstable.
ADTypes coloring interface
GreedyColoringAlgorithm is a subtype of ADTypes.AbstractColoringAlgorithm, which means the following methods are also applicable:
See their respective docstrings for details.
See also
source
SparseMatrixColorings.ConstantColoringAlgorithm — Type
ConstantColoringAlgorithm{partition}  <: ADTypes.AbstractColoringAlgorithm
Coloring algorithm which always returns the same precomputed vector of colors. Useful when the optimal coloring of a matrix can be determined a priori due to its specific structure (e.g. banded).
It is passed as an argument to the main function coloring, but will only work if the associated problem has :nonsymmetric structure. Indeed, for symmetric coloring problems, we need more than just the vector of colors to allow fast decompression.
Constructors
ConstantColoringAlgorithm{partition}(matrix_template, color)
+ [6]
See also
source
SparseMatrixColorings.ColoringProblem — Type
ColoringProblem{structure,partition}
Selector type for the coloring problem to solve, enabling multiple dispatch.
It is passed as an argument to the main function coloring.
Constructors
ColoringProblem{structure,partition}()
+ColoringProblem(; structure=:nonsymmetric, partition=:column)
  • structure::Symbol: either :nonsymmetric or :symmetric
  • partition::Symbol: either :column, :row or :bidirectional
Warning
The second constructor (based on keyword arguments) is type-unstable.
Link to automatic differentiation
Matrix coloring is often used in automatic differentiation, and here is the translation guide:
matrixmodestructurepartitionimplemented
Jacobianforward:nonsymmetric:columnyes
Jacobianreverse:nonsymmetric:rowyes
Jacobianmixed:nonsymmetric:bidirectionalno
Hessian-:symmetric:columnyes
Hessian-:symmetric:rowno
source
SparseMatrixColorings.GreedyColoringAlgorithm — Type
GreedyColoringAlgorithm{decompression} <: ADTypes.AbstractColoringAlgorithm
Greedy coloring algorithm for sparse matrices which colors columns or rows one after the other, following a configurable order.
It is passed as an argument to the main function coloring.
Constructors
GreedyColoringAlgorithm{decompression}(order=NaturalOrder())
+GreedyColoringAlgorithm(order=NaturalOrder(); decompression=:direct)
  • order::AbstractOrder: the order in which the columns or rows are colored, which can impact the number of colors.
  • decompression::Symbol: either :direct or :substitution. Usually :substitution leads to fewer colors, at the cost of a more expensive coloring (and decompression). When :substitution is not applicable, it falls back on :direct decompression.
Warning
The second constructor (based on keyword arguments) is type-unstable.
ADTypes coloring interface
GreedyColoringAlgorithm is a subtype of ADTypes.AbstractColoringAlgorithm, which means the following methods are also applicable:
See their respective docstrings for details.
See also
source
SparseMatrixColorings.ConstantColoringAlgorithm — Type
ConstantColoringAlgorithm{partition}  <: ADTypes.AbstractColoringAlgorithm
Coloring algorithm which always returns the same precomputed vector of colors. Useful when the optimal coloring of a matrix can be determined a priori due to its specific structure (e.g. banded).
It is passed as an argument to the main function coloring, but will only work if the associated problem has :nonsymmetric structure. Indeed, for symmetric coloring problems, we need more than just the vector of colors to allow fast decompression.
Constructors
ConstantColoringAlgorithm{partition}(matrix_template, color)
 ConstantColoringAlgorithm(matrix_template, color; partition=:column)
  • partition::Symbol: either :row or :column.
  • matrix_template::AbstractMatrix: matrix for which the vector of colors was precomputed (the algorithm will only accept matrices of the exact same size).
  • color::Vector{Int}: vector of integer colors, one for each row or column (depending on partition).
Warning
The second constructor (based on keyword arguments) is type-unstable.
We do not necessarily verify consistency between the matrix template and the vector of colors, this is the responsibility of the user.
Example
julia> using SparseMatrixColorings, LinearAlgebra
 
 julia> matrix_template = Diagonal(ones(Bool, 5))
@@ -65,7 +65,7 @@
  1
  1
  1
- 1
ADTypes coloring interface
ConstantColoringAlgorithm is a subtype of ADTypes.AbstractColoringAlgorithm, which means the following methods are also applicable (although they will error if the kind of coloring demanded not consistent):
source
Result analysis
SparseMatrixColorings.AbstractColoringResult — Type
AbstractColoringResult{structure,partition,decompression}
Abstract type for the result of a coloring algorithm.
It is the supertype of the object returned by the main function coloring.
Type parameters
Combination between the type parameters of ColoringProblem and GreedyColoringAlgorithm:
  • structure::Symbol: either :nonsymmetric or :symmetric
  • partition::Symbol: either :column, :row or :bidirectional
  • decompression::Symbol: either :direct or :substitution
Applicable methods
Warning
Unlike the methods above, the concrete subtypes of AbstractColoringResult are not part of the public API and may change without notice.
source
SparseMatrixColorings.column_groups — Function
column_groups(result::AbstractColoringResult)
Return a vector group such that for every color c, group[c] contains the indices of all columns that are colored with c.
source
SparseMatrixColorings.row_groups — Function
row_groups(result::AbstractColoringResult)
Return a vector group such that for every color c, group[c] contains the indices of all rows that are colored with c.
source
SparseMatrixColorings.sparsity_pattern — Function
sparsity_pattern(result::AbstractColoringResult)
Return the matrix that was initially passed to coloring, without any modifications.
Note
This matrix is not necessarily a SparseMatrixCSC, nor does it necessarily have Bool entries.
source
Decompression
SparseMatrixColorings.compress — Function
compress(A, result::AbstractColoringResult)
Compress A given a coloring result of the sparsity pattern of A.
  • If result comes from a :column (resp. :row) partition, the output is a single matrix B compressed by column (resp. by row).
  • If result comes from a :bidirectional partition, the output is a tuple of matrices (Br, Bc), where Br is compressed by row and Bc by column.
Compression means summing either the columns or the rows of A which share the same color. It is undone by calling decompress or decompress!.
Warning
At the moment, :bidirectional partitions are not implemented.
Example
julia> using SparseMatrixColorings, SparseArrays
+ 1
ADTypes coloring interface
ConstantColoringAlgorithm is a subtype of ADTypes.AbstractColoringAlgorithm, which means the following methods are also applicable (although they will error if the kind of coloring demanded not consistent):
source
Result analysis
SparseMatrixColorings.AbstractColoringResult — Type
AbstractColoringResult{structure,partition,decompression}
Abstract type for the result of a coloring algorithm.
It is the supertype of the object returned by the main function coloring.
Type parameters
Combination between the type parameters of ColoringProblem and GreedyColoringAlgorithm:
  • structure::Symbol: either :nonsymmetric or :symmetric
  • partition::Symbol: either :column, :row or :bidirectional
  • decompression::Symbol: either :direct or :substitution
Applicable methods
Warning
Unlike the methods above, the concrete subtypes of AbstractColoringResult are not part of the public API and may change without notice.
source
SparseMatrixColorings.column_groups — Function
column_groups(result::AbstractColoringResult)
Return a vector group such that for every color c, group[c] contains the indices of all columns that are colored with c.
source
SparseMatrixColorings.row_groups — Function
row_groups(result::AbstractColoringResult)
Return a vector group such that for every color c, group[c] contains the indices of all rows that are colored with c.
source
SparseMatrixColorings.sparsity_pattern — Function
sparsity_pattern(result::AbstractColoringResult)
Return the matrix that was initially passed to coloring, without any modifications.
Note
This matrix is not necessarily a SparseMatrixCSC, nor does it necessarily have Bool entries.
source
Decompression
SparseMatrixColorings.compress — Function
compress(A, result::AbstractColoringResult)
Compress A given a coloring result of the sparsity pattern of A.
  • If result comes from a :column (resp. :row) partition, the output is a single matrix B compressed by column (resp. by row).
  • If result comes from a :bidirectional partition, the output is a tuple of matrices (Br, Bc), where Br is compressed by row and Bc by column.
Compression means summing either the columns or the rows of A which share the same color. It is undone by calling decompress or decompress!.
Warning
At the moment, :bidirectional partitions are not implemented.
Example
julia> using SparseMatrixColorings, SparseArrays
 
 julia> A = sparse([
            0 0 4 6 0 9
@@ -87,7 +87,7 @@
  6  4  9
  1  7  0
  2  8  0
- 3  5  0
See also
source
SparseMatrixColorings.decompress — Function
decompress(B::AbstractMatrix, result::AbstractColoringResult)
Decompress B into a new matrix A, given a coloring result of the sparsity pattern of A. The in-place alternative is decompress!.
Compression means summing either the columns or the rows of A which share the same color. It is done by calling compress.
Example
julia> using SparseMatrixColorings, SparseArrays
 
 julia> A = sparse([
            0 0 4 6 0 9
@@ -119,7 +119,7 @@
  ⋅  3  5  ⋅  ⋅  ⋅
 
 julia> decompress(B, result) == A
-true
See also
source
SparseMatrixColorings.decompress! — Function
decompress!(
     A::AbstractMatrix, B::AbstractMatrix,
     result::AbstractColoringResult, [uplo=:F]
 )
Decompress B in-place into A, given a coloring result of the sparsity pattern of A. The out-of-place alternative is decompress.
Note
In-place decompression is faster when A isa SparseMatrixCSC.
Compression means summing either the columns or the rows of A which share the same color. It is done by calling compress.
For :symmetric coloring results (and for those only), an optional positional argument uplo in (:U, :L, :F) can be passed to specify which part of the matrix A should be updated: the Upper triangle, the Lower triangle, or the Full matrix. When A isa SparseMatrixCSC, using the uplo argument requires a target matrix which only stores the relevant triangle(s).
Example
julia> using SparseMatrixColorings, SparseArrays
@@ -156,7 +156,7 @@
  ⋅  3  5  ⋅  ⋅  ⋅
 
 julia> A2 == A
-true
See also
source
SparseMatrixColorings.decompress_single_color! — Function
decompress_single_color!(
     A::AbstractMatrix, b::AbstractVector, c::Integer,
     result::AbstractColoringResult, [uplo=:F]
 )
Decompress the vector b corresponding to color c in-place into A, given a :direct coloring result of the sparsity pattern of A (it will not work with a :substitution coloring).
  • If result comes from a :nonsymmetric structure with :column partition, this will update the columns of A that share color c (whose sum makes up b).
  • If result comes from a :nonsymmetric structure with :row partition, this will update the rows of A that share color c (whose sum makes up b).
  • If result comes from a :symmetric structure with :column partition, this will update the coefficients of A whose value is deduced from color c.
Warning
This function will only update some coefficients of A, without resetting the rest to zero.
For :symmetric coloring results (and for those only), an optional positional argument uplo in (:U, :L, :F) can be passed to specify which part of the matrix A should be updated: the Upper triangle, the Lower triangle, or the Full matrix. When A isa SparseMatrixCSC, using the uplo argument requires a target matrix which only stores the relevant triangle(s).
Example
julia> using SparseMatrixColorings, SparseArrays
@@ -193,4 +193,4 @@
  ⋅  0  5  ⋅  ⋅  ⋅
 
 julia> A2[:, [3, 5]] == A[:, [3, 5]]
-true
See also
source
Orders

+true

See also

source

Orders

diff --git a/dev/dev/index.html b/dev/dev/index.html index a602232..7563a49 100644 --- a/dev/dev/index.html +++ b/dev/dev/index.html @@ -1,16 +1,16 @@ -Dev docs · SparseMatrixColorings.jl
GitHub

Dev docs

The docstrings on this page describe internals, they are not part of the public API.

Graph storage

SparseMatrixColorings.SparsityPatternCSC — Type
SparsityPatternCSC{Ti<:Integer}

Store a sparse matrix (in CSC) without its values, keeping only the pattern of nonzeros.

Fields

Copied from SparseMatrixCSC:

  • m::Int: number of rows
  • n::Int: number of columns
  • colptr::Vector{Ti}: column j is in colptr[j]:(colptr[j+1]-1)
  • rowval::Vector{Ti}: row indices of stored values
source
SparseMatrixColorings.AdjacencyGraph — Type
AdjacencyGraph{T}

Undirected graph without self-loops 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

Constructors

AdjacencyGraph(A::SparseMatrixCSC)

Fields

  • S::SparsityPatternCSC{T}

References

What Color Is Your Jacobian? SparsityPatternCSC Coloring for Computing Derivatives, Gebremedhin et al. (2005)

source
SparseMatrixColorings.BipartiteGraph — Type
BipartiteGraph{T}

Undirected bipartite graph 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 i
  • V₂ = 1:n is the set of columns j
  • (i, j) ∈ E whenever A[i, j] ≠ 0

A BipartiteGraph has two sets of vertices, one for the rows of A (which we call side 1) and one for the columns (which we call side 2).

Constructors

BipartiteGraph(A::SparseMatrixCSC; symmetric_pattern=false)

When symmetric_pattern is true, this construction is more efficient.

Fields

  • S1::SparsityPatternCSC{T}: maps vertices on side 1 to their neighbors
  • S2::SparsityPatternCSC{T}: maps vertices on side 2 to their neighbors

References

What Color Is Your Jacobian? SparsityPatternCSC Coloring for Computing Derivatives, Gebremedhin et al. (2005)

source
SparseMatrixColorings.neighbors — Function
neighbors(bg::BipartiteGraph, Val(side), v::Integer)

Return the neighbors of v (a vertex from the specified side, 1 or 2), in the graph bg.

source

Low-level coloring

SparseMatrixColorings.partial_distance2_coloring — Function
partial_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

source
SparseMatrixColorings.symmetric_coefficient — Function
symmetric_coefficient(
+Dev docs · SparseMatrixColorings.jl
GitHub
Dev docs
The docstrings on this page describe internals, they are not part of the public API.
Graph storage
SparseMatrixColorings.SparsityPatternCSC — Type
SparsityPatternCSC{Ti<:Integer}
Store a sparse matrix (in CSC) without its values, keeping only the pattern of nonzeros.
Fields
Copied from SparseMatrixCSC:
  • m::Int: number of rows
  • n::Int: number of columns
  • colptr::Vector{Ti}: column j is in colptr[j]:(colptr[j+1]-1)
  • rowval::Vector{Ti}: row indices of stored values
source
SparseMatrixColorings.AdjacencyGraph — Type
AdjacencyGraph{T}
Undirected graph without self-loops 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
Constructors
AdjacencyGraph(A::SparseMatrixCSC)
Fields
  • S::SparsityPatternCSC{T}
References
What Color Is Your Jacobian? SparsityPatternCSC Coloring for Computing Derivatives, Gebremedhin et al. (2005)
source
SparseMatrixColorings.BipartiteGraph — Type
BipartiteGraph{T}
Undirected bipartite graph 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 i
  • V₂ = 1:n is the set of columns j
  • (i, j) ∈ E whenever A[i, j] ≠ 0
A BipartiteGraph has two sets of vertices, one for the rows of A (which we call side 1) and one for the columns (which we call side 2).
Constructors
BipartiteGraph(A::SparseMatrixCSC; symmetric_pattern=false)
When symmetric_pattern is true, this construction is more efficient.
Fields
  • S1::SparsityPatternCSC{T}: maps vertices on side 1 to their neighbors
  • S2::SparsityPatternCSC{T}: maps vertices on side 2 to their neighbors
References
What Color Is Your Jacobian? SparsityPatternCSC Coloring for Computing Derivatives, Gebremedhin et al. (2005)
source
SparseMatrixColorings.neighbors — Function
neighbors(bg::BipartiteGraph, Val(side), v::Integer)
Return the neighbors of v (a vertex from the specified side, 1 or 2), in the graph bg.
source
Low-level coloring
SparseMatrixColorings.partial_distance2_coloring — Function
partial_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
source
SparseMatrixColorings.star_coloring — Function
star_coloring(g::AdjacencyGraph, order::AbstractOrder)
Compute a star coloring of all vertices in the adjacency graph g and return a tuple (color, star_set), where
  • color is the vector of integer colors
  • star_set is a StarSet encoding the set of 2-colored stars
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
source
SparseMatrixColorings.acyclic_coloring — Function
acyclic_coloring(g::AdjacencyGraph, order::AbstractOrder)
Compute an acyclic coloring of all vertices in the adjacency graph g and return a tuple (color, tree_set), where
  • color is the vector of integer colors
  • tree_set is a TreeSet encoding the set of 2-colored trees
An acyclic coloring is a distance-1 coloring with the further restriction that every cycle 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 3.1
source
SparseMatrixColorings.group_by_color — Function
group_by_color(color::Vector{Int})
Create a color-indexed vector group such that i ∈ group[c] iff color[i] == c.
Assumes the colors are contiguously numbered from 1 to some cmax.
source
SparseMatrixColorings.StarSet — Type
StarSet
Encode a set of 2-colored stars resulting from the star_coloring algorithm.
Fields
  • star::Dict{Tuple{Int64, Int64}, Int64}: a mapping from edges (pair of vertices) to their star index
  • hub::Vector{Int64}: a mapping from star indices to their hub (undefined hubs for single-edge stars are the negative value of one of the vertices, picked arbitrarily)
  • spokes::Vector{Vector{Int64}}: a mapping from star indices to the vector of their spokes
source
Concrete coloring results
SparseMatrixColorings.ColumnColoringResult — Type
struct ColumnColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.BipartiteGraph, V} <: AbstractColoringResult{:nonsymmetric, :column, :direct}
Storage for the result of a column coloring with direct decompression.
Fields
  • A::AbstractMatrix: matrix that was colored
  • bg::SparseMatrixColorings.BipartiteGraph: bipartite graph that was used for coloring
  • color::Vector{Int64}: one integer color for each column or row (depending on partition)
  • group::Any: color groups for columns or rows (depending on partition)
  • compressed_indices::Vector{Int64}: flattened indices mapping the compressed matrix B to the uncompressed matrix A when A isa SparseMatrixCSC. They satisfy nonzeros(A)[k] = vec(B)[compressed_indices[k]]
See also
source
SparseMatrixColorings.RowColoringResult — Type
struct RowColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.BipartiteGraph, V} <: AbstractColoringResult{:nonsymmetric, :row, :direct}
Storage for the result of a row coloring with direct decompression.
Fields
See the docstring of ColumnColoringResult.
  • A::AbstractMatrix
  • bg::SparseMatrixColorings.BipartiteGraph
  • color::Vector{Int64}
  • group::Any
  • compressed_indices::Vector{Int64}
See also
source
SparseMatrixColorings.StarSetColoringResult — Type
struct StarSetColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V} <: AbstractColoringResult{:symmetric, :column, :direct}
Storage for the result of a symmetric coloring with direct decompression.
Fields
See the docstring of ColumnColoringResult.
  • A::AbstractMatrix
  • ag::SparseMatrixColorings.AdjacencyGraph
  • color::Vector{Int64}
  • group::Any
  • star_set::SparseMatrixColorings.StarSet
  • compressed_indices::Vector{Int64}
See also
source
SparseMatrixColorings.TreeSetColoringResult — Type
struct TreeSetColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V, R} <: AbstractColoringResult{:symmetric, :column, :substitution}
Storage for the result of a symmetric coloring with decompression by substitution.
Fields
See the docstring of ColumnColoringResult.
  • A::AbstractMatrix
  • ag::SparseMatrixColorings.AdjacencyGraph
  • color::Vector{Int64}
  • group::Any
  • vertices_by_tree::Vector{Vector{Int64}}
  • reverse_bfs_orders::Vector{Vector{Tuple{Int64, Int64}}}
  • buffer::Vector
See also
source
SparseMatrixColorings.LinearSystemColoringResult — Type
struct LinearSystemColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V, R, F} <: AbstractColoringResult{:symmetric, :column, :substitution}
Storage for the result of a symmetric coloring with any decompression.
Fields
See the docstring of ColumnColoringResult.
  • A::AbstractMatrix
  • ag::SparseMatrixColorings.AdjacencyGraph
  • color::Vector{Int64}
  • group::Any
  • strict_upper_nonzero_inds::Vector{Tuple{Int64, Int64}}
  • strict_upper_nonzeros_A::Vector
  • T_factorization::Any
See also
source
Testing
SparseMatrixColorings.star_coloring — Function
star_coloring(g::AdjacencyGraph, order::AbstractOrder)
Compute a star coloring of all vertices in the adjacency graph g and return a tuple (color, star_set), where
  • color is the vector of integer colors
  • star_set is a StarSet encoding the set of 2-colored stars
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
source
SparseMatrixColorings.acyclic_coloring — Function
acyclic_coloring(g::AdjacencyGraph, order::AbstractOrder)
Compute an acyclic coloring of all vertices in the adjacency graph g and return a tuple (color, tree_set), where
  • color is the vector of integer colors
  • tree_set is a TreeSet encoding the set of 2-colored trees
An acyclic coloring is a distance-1 coloring with the further restriction that every cycle 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 3.1
source
SparseMatrixColorings.group_by_color — Function
group_by_color(color::Vector{Int})
Create a color-indexed vector group such that i ∈ group[c] iff color[i] == c.
Assumes the colors are contiguously numbered from 1 to some cmax.
source
SparseMatrixColorings.StarSet — Type
StarSet
Encode a set of 2-colored stars resulting from the star_coloring algorithm.
Fields
  • star::Dict{Tuple{Int64, Int64}, Int64}: a mapping from edges (pair of vertices) to their star index
  • hub::Vector{Int64}: a mapping from star indices to their hub (undefined hubs for single-edge stars are the negative value of one of the vertices, picked arbitrarily)
  • spokes::Vector{Vector{Int64}}: a mapping from star indices to the vector of their spokes
source
Concrete coloring results
SparseMatrixColorings.ColumnColoringResult — Type
struct ColumnColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.BipartiteGraph, V} <: AbstractColoringResult{:nonsymmetric, :column, :direct}
Storage for the result of a column coloring with direct decompression.
Fields
  • A::AbstractMatrix: matrix that was colored
  • bg::SparseMatrixColorings.BipartiteGraph: bipartite graph that was used for coloring
  • color::Vector{Int64}: one integer color for each column or row (depending on partition)
  • group::Any: color groups for columns or rows (depending on partition)
  • compressed_indices::Vector{Int64}: flattened indices mapping the compressed matrix B to the uncompressed matrix A when A isa SparseMatrixCSC. They satisfy nonzeros(A)[k] = vec(B)[compressed_indices[k]]
See also
source
SparseMatrixColorings.RowColoringResult — Type
struct RowColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.BipartiteGraph, V} <: AbstractColoringResult{:nonsymmetric, :row, :direct}
Storage for the result of a row coloring with direct decompression.
Fields
See the docstring of ColumnColoringResult.
  • A::AbstractMatrix
  • bg::SparseMatrixColorings.BipartiteGraph
  • color::Vector{Int64}
  • group::Any
  • compressed_indices::Vector{Int64}
See also
source
SparseMatrixColorings.StarSetColoringResult — Type
struct StarSetColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V} <: AbstractColoringResult{:symmetric, :column, :direct}
Storage for the result of a symmetric coloring with direct decompression.
Fields
See the docstring of ColumnColoringResult.
  • A::AbstractMatrix
  • ag::SparseMatrixColorings.AdjacencyGraph
  • color::Vector{Int64}
  • group::Any
  • star_set::SparseMatrixColorings.StarSet
  • compressed_indices::Vector{Int64}
See also
source
SparseMatrixColorings.TreeSetColoringResult — Type
struct TreeSetColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V, R} <: AbstractColoringResult{:symmetric, :column, :substitution}
Storage for the result of a symmetric coloring with decompression by substitution.
Fields
See the docstring of ColumnColoringResult.
  • A::AbstractMatrix
  • ag::SparseMatrixColorings.AdjacencyGraph
  • color::Vector{Int64}
  • group::Any
  • vertices_by_tree::Vector{Vector{Int64}}
  • reverse_bfs_orders::Vector{Vector{Tuple{Int64, Int64}}}
  • buffer::Vector
See also
source
SparseMatrixColorings.LinearSystemColoringResult — Type
struct LinearSystemColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V, R, F} <: AbstractColoringResult{:symmetric, :column, :substitution}
Storage for the result of a symmetric coloring with any decompression.
Fields
See the docstring of ColumnColoringResult.
  • A::AbstractMatrix
  • ag::SparseMatrixColorings.AdjacencyGraph
  • color::Vector{Int64}
  • group::Any
  • strict_upper_nonzero_inds::Vector{Tuple{Int64, Int64}}
  • strict_upper_nonzeros_A::Vector
  • T_factorization::Any
See also
source
Testing
SparseMatrixColorings.directly_recoverable_columns — Function
directly_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)
source
SparseMatrixColorings.symmetrically_orthogonal_columns — Function
symmetrically_orthogonal_columns(
+)
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)
source
SparseMatrixColorings.symmetrically_orthogonal_columns — Function
symmetrically_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:
  1. the group containing the column A[:, j] has no other column with a nonzero in row i
  2. 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)
source
SparseMatrixColorings.structurally_orthogonal_columns — Function
structurally_orthogonal_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:
  1. the group containing the column A[:, j] has no other column with a nonzero in row i
  2. 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)
source
SparseMatrixColorings.structurally_orthogonal_columns — Function
structurally_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)
source
Matrix handling
SparseMatrixColorings.respectful_similar — Function
respectful_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.
source
SparseMatrixColorings.same_pattern — Function
same_pattern(A, B)
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
source
Examples
SparseMatrixColorings.Example — Type
struct Example{TA<:(AbstractMatrix), TB<:(AbstractMatrix)}
Example coloring problem from one of our reference articles.
Used for internal testing.
Fields
  • A::AbstractMatrix: decompressed matrix
  • B::AbstractMatrix: column-compressed matrix
  • color::Vector{Int64}: vector of colors
source

+)

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)

source

Matrix handling

SparseMatrixColorings.respectful_similar — Function
respectful_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.

source
SparseMatrixColorings.same_pattern — Function
same_pattern(A, B)

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
source

Examples

SparseMatrixColorings.Example — Type
struct Example{TA<:(AbstractMatrix), TB<:(AbstractMatrix)}

Example coloring problem from one of our reference articles.

Used for internal testing.

Fields

  • A::AbstractMatrix: decompressed matrix

  • B::AbstractMatrix: column-compressed matrix

  • color::Vector{Int64}: vector of colors

source
diff --git a/dev/index.html b/dev/index.html index 0ea82aa..13871d4 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · SparseMatrixColorings.jl
GitHub

SparseMatrixColorings.jl

Build Status Stable Documentation Dev Documentation Coverage Code Style: Blue DOI

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:

Some parts of the articles (like definitions) are thus copied verbatim in the documentation.

Alternatives

Citing

Please cite this software using the Zenodo DOI of the version you used. The link https://zenodo.org/doi/10.5281/zenodo.11314275 resolves to the latest version.

+Home · SparseMatrixColorings.jl
GitHub

SparseMatrixColorings.jl

Build Status Stable Documentation Dev Documentation Coverage Code Style: Blue DOI

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:

Some parts of the articles (like definitions) are thus copied verbatim in the documentation.

Alternatives

Citing

Please cite this software using the Zenodo DOI of the version you used. The link https://zenodo.org/doi/10.5281/zenodo.11314275 resolves to the latest version.