diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 8d8cea3..477b05c 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-11T19:11:52","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-13T10:37:00","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 22603ac..ba13fc8 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:bidirectionalyes
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:bidirectionalyes
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.ncolors — Function
ncolors(result::AbstractColoringResult)
Return the number of different colors used to color the matrix.
For bidirectional partitions, this number is the sum of the number of row colors and the number of column colors.
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!.
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.ncolors — Function
ncolors(result::AbstractColoringResult)
Return the number of different colors used to color the matrix.
For bidirectional partitions, this number is the sum of the number of row colors and the number of column colors.
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!.
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{_,:column/:row})
 decompress(Br::AbstractMatrix, Bc::AbstractMatrix, result::AbstractColoringResult{_,:bidirectional})
Decompress B (or the tuple (Br,Bc)) 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([
@@ -120,7 +120,7 @@
  ⋅  3  5  ⋅  ⋅  ⋅
 
 julia> decompress(B, result) == 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
@@ -199,4 +199,4 @@
  ⋅  0  5  ⋅  ⋅  ⋅
 
 julia> A2[:, [3, 5]] == A[:, [3, 5]]
-true
See also
source
Orders
SparseMatrixColorings.DynamicDegreeBasedOrder — Type
DynamicDegreeBasedOrder{degtype,direction}
Instance of AbstractOrder which sorts vertices using a dynamically computed degree.
Danger
This order is still experimental and needs more tests, correctness is not yet guaranteed.
Type parameters
  • degtype::Symbol: can be :forward (for the forward degree) or :back (for the back degree)
  • direction::Symbol: can be :low2high (if the order is defined from lowest to highest, i.e. 1 to n) or :high2low (if the order is defined from highest to lowest, i.e. n to 1)
Concrete variants
References
source

+true

See also

source

Orders

SparseMatrixColorings.DynamicDegreeBasedOrder — Type
DynamicDegreeBasedOrder{degtype,direction}

Instance of AbstractOrder which sorts vertices using a dynamically computed degree.

Danger

This order is still experimental and needs more tests, correctness is not yet guaranteed.

Type parameters

  • degtype::Symbol: can be :forward (for the forward degree) or :back (for the back degree)
  • direction::Symbol: can be :low2high (if the order is defined from lowest to highest, i.e. 1 to n) or :high2low (if the order is defined from highest to lowest, i.e. n to 1)

Concrete variants

References

source
diff --git a/dev/assets/documenter.js b/dev/assets/documenter.js index 82252a1..7d68cd8 100644 --- a/dev/assets/documenter.js +++ b/dev/assets/documenter.js @@ -612,176 +612,194 @@ function worker_function(documenterSearchIndex, documenterBaseURL, filters) { }; } -// `worker = Threads.@spawn worker_function(documenterSearchIndex)`, but in JavaScript! -const filters = [ - ...new Set(documenterSearchIndex["docs"].map((x) => x.category)), -]; -const worker_str = - "(" + - worker_function.toString() + - ")(" + - JSON.stringify(documenterSearchIndex["docs"]) + - "," + - JSON.stringify(documenterBaseURL) + - "," + - JSON.stringify(filters) + - ")"; -const worker_blob = new Blob([worker_str], { type: "text/javascript" }); -const worker = new Worker(URL.createObjectURL(worker_blob)); - /////// SEARCH MAIN /////// -// Whether the worker is currently handling a search. This is a boolean -// as the worker only ever handles 1 or 0 searches at a time. -var worker_is_running = false; - -// The last search text that was sent to the worker. This is used to determine -// if the worker should be launched again when it reports back results. -var last_search_text = ""; - -// The results of the last search. This, in combination with the state of the filters -// in the DOM, is used compute the results to display on calls to update_search. -var unfiltered_results = []; - -// Which filter is currently selected -var selected_filter = ""; - -$(document).on("input", ".documenter-search-input", function (event) { - if (!worker_is_running) { - launch_search(); - } -}); - -function launch_search() { - worker_is_running = true; - last_search_text = $(".documenter-search-input").val(); - worker.postMessage(last_search_text); -} - -worker.onmessage = function (e) { - if (last_search_text !== $(".documenter-search-input").val()) { - launch_search(); - } else { - worker_is_running = false; - } - - unfiltered_results = e.data; - update_search(); -}; +function runSearchMainCode() { + // `worker = Threads.@spawn worker_function(documenterSearchIndex)`, but in JavaScript! + const filters = [ + ...new Set(documenterSearchIndex["docs"].map((x) => x.category)), + ]; + const worker_str = + "(" + + worker_function.toString() + + ")(" + + JSON.stringify(documenterSearchIndex["docs"]) + + "," + + JSON.stringify(documenterBaseURL) + + "," + + JSON.stringify(filters) + + ")"; + const worker_blob = new Blob([worker_str], { type: "text/javascript" }); + const worker = new Worker(URL.createObjectURL(worker_blob)); + + // Whether the worker is currently handling a search. This is a boolean + // as the worker only ever handles 1 or 0 searches at a time. + var worker_is_running = false; + + // The last search text that was sent to the worker. This is used to determine + // if the worker should be launched again when it reports back results. + var last_search_text = ""; + + // The results of the last search. This, in combination with the state of the filters + // in the DOM, is used compute the results to display on calls to update_search. + var unfiltered_results = []; + + // Which filter is currently selected + var selected_filter = ""; + + $(document).on("input", ".documenter-search-input", function (event) { + if (!worker_is_running) { + launch_search(); + } + }); -$(document).on("click", ".search-filter", function () { - if ($(this).hasClass("search-filter-selected")) { - selected_filter = ""; - } else { - selected_filter = $(this).text().toLowerCase(); + function launch_search() { + worker_is_running = true; + last_search_text = $(".documenter-search-input").val(); + worker.postMessage(last_search_text); } - // This updates search results and toggles classes for UI: - update_search(); -}); + worker.onmessage = function (e) { + if (last_search_text !== $(".documenter-search-input").val()) { + launch_search(); + } else { + worker_is_running = false; + } -/** - * Make/Update the search component - */ -function update_search() { - let querystring = $(".documenter-search-input").val(); + unfiltered_results = e.data; + update_search(); + }; - if (querystring.trim()) { - if (selected_filter == "") { - results = unfiltered_results; + $(document).on("click", ".search-filter", function () { + if ($(this).hasClass("search-filter-selected")) { + selected_filter = ""; } else { - results = unfiltered_results.filter((result) => { - return selected_filter == result.category.toLowerCase(); - }); + selected_filter = $(this).text().toLowerCase(); } - let search_result_container = ``; - let modal_filters = make_modal_body_filters(); - let search_divider = `
`; + // This updates search results and toggles classes for UI: + update_search(); + }); - if (results.length) { - let links = []; - let count = 0; - let search_results = ""; - - for (var i = 0, n = results.length; i < n && count < 200; ++i) { - let result = results[i]; - if (result.location && !links.includes(result.location)) { - search_results += result.div; - count++; - links.push(result.location); - } - } + /** + * Make/Update the search component + */ + function update_search() { + let querystring = $(".documenter-search-input").val(); - if (count == 1) { - count_str = "1 result"; - } else if (count == 200) { - count_str = "200+ results"; + if (querystring.trim()) { + if (selected_filter == "") { + results = unfiltered_results; } else { - count_str = count + " results"; + results = unfiltered_results.filter((result) => { + return selected_filter == result.category.toLowerCase(); + }); } - let result_count = `
${count_str}
`; - search_result_container = ` + let search_result_container = ``; + let modal_filters = make_modal_body_filters(); + let search_divider = `
`; + + if (results.length) { + let links = []; + let count = 0; + let search_results = ""; + + for (var i = 0, n = results.length; i < n && count < 200; ++i) { + let result = results[i]; + if (result.location && !links.includes(result.location)) { + search_results += result.div; + count++; + links.push(result.location); + } + } + + if (count == 1) { + count_str = "1 result"; + } else if (count == 200) { + count_str = "200+ results"; + } else { + count_str = count + " results"; + } + let result_count = `
${count_str}
`; + + search_result_container = ` +
+ ${modal_filters} + ${search_divider} + ${result_count} +
+ ${search_results} +
+
+ `; + } else { + search_result_container = `
${modal_filters} ${search_divider} - ${result_count} -
- ${search_results} -
-
+
0 result(s)
+ +
No result found!
`; - } else { - search_result_container = ` -
- ${modal_filters} - ${search_divider} -
0 result(s)
-
-
No result found!
- `; - } + } - if ($(".search-modal-card-body").hasClass("is-justify-content-center")) { - $(".search-modal-card-body").removeClass("is-justify-content-center"); - } + if ($(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").removeClass("is-justify-content-center"); + } - $(".search-modal-card-body").html(search_result_container); - } else { - if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { - $(".search-modal-card-body").addClass("is-justify-content-center"); + $(".search-modal-card-body").html(search_result_container); + } else { + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(` +
Type something to get started!
+ `); } + } - $(".search-modal-card-body").html(` -
Type something to get started!
- `); + /** + * Make the modal filter html + * + * @returns string + */ + function make_modal_body_filters() { + let str = filters + .map((val) => { + if (selected_filter == val.toLowerCase()) { + return `${val}`; + } else { + return `${val}`; + } + }) + .join(""); + + return ` +
+ Filters: + ${str} +
`; } } -/** - * Make the modal filter html - * - * @returns string - */ -function make_modal_body_filters() { - let str = filters - .map((val) => { - if (selected_filter == val.toLowerCase()) { - return `${val}`; - } else { - return `${val}`; - } - }) - .join(""); - - return ` -
- Filters: - ${str} -
`; +function waitUntilSearchIndexAvailable() { + // It is possible that the documenter.js script runs before the page + // has finished loading and documenterSearchIndex gets defined. + // So we need to wait until the search index actually loads before setting + // up all the search-related stuff. + if (typeof documenterSearchIndex !== "undefined") { + runSearchMainCode(); + } else { + console.warn("Search Index not available, waiting"); + setTimeout(waitUntilSearchIndexAvailable, 1000); + } } +// The actual entry point to the search code +waitUntilSearchIndexAvailable(); + }) //////////////////////////////////////////////////////////////////////////////// require(['jquery'], function($) { diff --git a/dev/dev/index.html b/dev/dev/index.html index 346f353..7cb015f 100644 --- a/dev/dev/index.html +++ b/dev/dev/index.html @@ -1,17 +1,20 @@ -Internals · SparseMatrixColorings.jl
GitHub

Internals

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(
+Internals · SparseMatrixColorings.jl
GitHub
Internals
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 symmetric matrix 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}}}
  • diagonal_indices::Vector{Int64}
  • diagonal_nzind::Vector{Int64}
  • lower_triangle_offsets::Vector{Int64}
  • upper_triangle_offsets::Vector{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
SparseMatrixColorings.BicoloringResult — Type
struct BicoloringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, decompression, V, SR<:AbstractColoringResult{:symmetric, :column, decompression}, R} <: AbstractColoringResult{:nonsymmetric, :bidirectional, decompression}
Storage for the result of a bidirectional coloring with direct or substitution decompression, based on the symmetric coloring of a 2x2 block matrix.
Fields
  • A::AbstractMatrix: matrix that was colored
  • abg::SparseMatrixColorings.AdjacencyGraph: adjacency graph that was used for coloring (constructed from the bipartite graph)
  • column_color::Vector{Int64}: one integer color for each column
  • row_color::Vector{Int64}: one integer color for each row
  • column_group::Any: color groups for columns
  • row_group::Any: color groups for rows
  • symmetric_result::AbstractColoringResult{:symmetric, :column}: result for the coloring of the symmetric 2x2 block matrix
  • col_color_ind::Dict{Int64, Int64}: column color to index
  • row_color_ind::Dict{Int64, Int64}: row color to index
  • Br_and_Bc::Matrix: combination of Br and Bc (almost a concatenation up to color remapping)
  • large_colptr::Vector{Int64}: CSC storage of A_and_noAᵀ -colptr`
  • large_rowval::Vector{Int64}: CSC storage of A_and_noAᵀ -rowval`
See also
source
SparseMatrixColorings.remap_colors — Function
remap_colors(color::Vector{Int})
Renumber the colors in color using their index in the vector sort(unique(color)), so that they are forced to go from 1 to some cmax contiguously.
Return a tuple (remapped_colors, color_to_ind) such that remapped_colors is a vector containing the renumbered colors and color_to_ind is a dictionary giving the translation between old and new color numberings.
For all vertex indices i we have:
remapped_color[i] = color_to_ind[color[i]]
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}}}
  • diagonal_indices::Vector{Int64}
  • diagonal_nzind::Vector{Int64}
  • lower_triangle_offsets::Vector{Int64}
  • upper_triangle_offsets::Vector{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
SparseMatrixColorings.BicoloringResult — Type
struct BicoloringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, decompression, V, SR<:AbstractColoringResult{:symmetric, :column, decompression}, R} <: AbstractColoringResult{:nonsymmetric, :bidirectional, decompression}
Storage for the result of a bidirectional coloring with direct or substitution decompression, based on the symmetric coloring of a 2x2 block matrix.
Fields
  • A::AbstractMatrix: matrix that was colored
  • abg::SparseMatrixColorings.AdjacencyGraph: adjacency graph that was used for coloring (constructed from the bipartite graph)
  • column_color::Vector{Int64}: one integer color for each column
  • row_color::Vector{Int64}: one integer color for each row
  • column_group::Any: color groups for columns
  • row_group::Any: color groups for rows
  • symmetric_result::AbstractColoringResult{:symmetric, :column}: result for the coloring of the symmetric 2x2 block matrix
  • col_color_ind::Dict{Int64, Int64}: column color to index
  • row_color_ind::Dict{Int64, Int64}: row color to index
  • Br_and_Bc::Matrix: combination of Br and Bc (almost a concatenation up to color remapping)
  • large_colptr::Vector{Int64}: CSC storage of A_and_noAᵀ -colptr`
  • large_rowval::Vector{Int64}: CSC storage of A_and_noAᵀ -rowval`
See also
source
SparseMatrixColorings.remap_colors — Function
remap_colors(color::Vector{Int})
Renumber the colors in color using their index in the vector sort(unique(color)), so that they are forced to go from 1 to some cmax contiguously.
Return a tuple (remapped_colors, color_to_ind) such that remapped_colors is a vector containing the renumbered colors and color_to_ind is a dictionary giving the translation between old and new color numberings.
For all vertex indices i we have:
remapped_color[i] = color_to_ind[color[i]]
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(
-    A::AbstractMatrix, color::AbstractVector{<:Integer}
+)
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 symmetric 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
SparseMatrixColorings.structurally_biorthogonal — Function
structurally_biorthogonal(
+    A::AbstractMatrix, row_color::AbstractVector{<:Integer}, column_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
SparseMatrixColorings.valid_dynamic_order — Function
valid_dynamic_order(g::AdjacencyGraph, π::AbstractVector{Int}, order::DynamicDegreeBasedOrder)
-valid_dynamic_order(bg::AdjacencyGraph, ::Val{side}, π::AbstractVector{Int}, order::DynamicDegreeBasedOrder)
Check that a permutation π corresponds to a valid application of a DynamicDegreeBasedOrder.
This is done by checking, for each ordered vertex, that its back- or forward-degree was the smallest or largest among the remaining vertices (the specifics depend on the order parameters).
Warning
This function is not coded with efficiency in mind, it is designed for small-scale tests.
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
Visualization
SparseMatrixColorings.show_colors — Function
show_colors(result; kwargs...)
Create a visualization for an AbstractColoringResult, with the help of the the JuliaImages ecosystem.
  • For :column or :row colorings, it returns a tuple (A_img, B_img).
  • For :bidirectional colorings, it returns a tuple (A_img, Br_img, Bc_img).
Warning
This function is implemented in a package extension, using it requires loading Colors.jl.
Keyword arguments
  • colorscheme: colors used for non-zero matrix entries. This can be a vector of Colorants or a subsampled scheme from ColorSchemes.jl.
  • background::Colorant: color used for zero matrix entries and pad. Defaults to RGBA(0,0,0,0), a transparent background.
  • scale::Int: scale the size of matrix entries to scale × scale pixels. Defaults to 1. 
  • pad::Int: set padding between matrix entries, in pixels. Defaults to 0. 
For a matrix of size (n, m), the resulting output will be of size (n * (scale + pad) + pad, m * (scale + pad) + pad).
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 bicoloring of the matrix A with the vectors row_color and column_color results in a bipartition that is structurally biorthogonal, and false otherwise.

A bipartition of the rows and columns of a matrix A is structurally biorthogonal 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 row A[i, :] has no other row with a nonzero in column j
Warning

This function is not coded with efficiency in mind, it is designed for small-scale tests.

source
SparseMatrixColorings.valid_dynamic_order — Function
valid_dynamic_order(g::AdjacencyGraph, π::AbstractVector{Int}, order::DynamicDegreeBasedOrder)
+valid_dynamic_order(bg::AdjacencyGraph, ::Val{side}, π::AbstractVector{Int}, order::DynamicDegreeBasedOrder)

Check that a permutation π corresponds to a valid application of a DynamicDegreeBasedOrder.

This is done by checking, for each ordered vertex, that its back- or forward-degree was the smallest or largest among the remaining vertices (the specifics depend on the order parameters).

Warning

This function is not coded with efficiency in mind, it is designed for small-scale tests.

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

Visualization

SparseMatrixColorings.show_colors — Function
show_colors(result; kwargs...)

Create a visualization for an AbstractColoringResult, with the help of the the JuliaImages ecosystem.

  • For :column or :row colorings, it returns a tuple (A_img, B_img).
  • For :bidirectional colorings, it returns a tuple (A_img, Br_img, Bc_img).
Warning

This function is implemented in a package extension, using it requires loading Colors.jl.

Keyword arguments

  • colorscheme: colors used for non-zero matrix entries. This can be a vector of Colorants or a subsampled scheme from ColorSchemes.jl.
  • background::Colorant: color used for zero matrix entries and pad. Defaults to RGBA(0,0,0,0), a transparent background.
  • scale::Int: scale the size of matrix entries to scale × scale pixels. Defaults to 1.
  • pad::Int: set padding between matrix entries, in pixels. Defaults to 0.

For a matrix of size (n, m), the resulting output will be of size (n * (scale + pad) + pad, m * (scale + pad) + pad).

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 66b2af5..da2391e 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.

diff --git a/dev/objects.inv b/dev/objects.inv index e6225a6..9b46102 100644 Binary files a/dev/objects.inv and b/dev/objects.inv differ diff --git a/dev/search_index.js b/dev/search_index.js index bccd30c..86e0c4c 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"vis/#Visualization","page":"Visualization","title":"Visualization","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"SparseMatrixColorings provides some internal utilities for visualization of matrix colorings via the un-exported function SparseMatrixColorings.show_colors.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"warning: Warning\nThis function makes use of the JuliaImages ecosystem. Using it requires loading at least Colors.jl. We recommend loading the full Images.jl package for convenience, which includes Colors.jl.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"using ColorSchemes\nusing Images\nusing SparseArrays\nusing SparseMatrixColorings\nusing SparseMatrixColorings: show_colors\nusing StableRNGs","category":"page"},{"location":"vis/#Basic-usage","page":"Visualization","title":"Basic usage","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"To obtain a visualization, simply call show_colors on a coloring result. It returns a tuple of outputs, corresponding to the matrix and its compression(s):","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"S = sparse([\n 0 0 1 1 0 1\n 1 0 0 0 1 0\n 0 1 0 0 1 0\n 0 1 1 0 0 0\n]);\n\nproblem = ColoringProblem(; structure=:nonsymmetric, partition=:column)\nalgo = GreedyColoringAlgorithm(; decompression=:direct)\nresult = coloring(S, problem, algo)\n\nA_img, B_img = show_colors(result; scale=3)","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"The colors on the original matrix look like this:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"A_img","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"And its column compression looks like that:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"B_img","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"tip: Terminal support\nLoading ImageInTerminal.jl will allow you to show the output of show_colors within your terminal. If you use VSCode's Julia REPL, the matrix will be displayed in the plot tab.","category":"page"},{"location":"vis/#Customization","page":"Visualization","title":"Customization","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"The visualization can be customized via keyword arguments. The size of the matrix entries is defined by scale, while gaps between them are dictated by pad. We recommend using the ColorSchemes.jl catalogue to customize the colorscheme. Finally, a background color can be passed via the background keyword argument. To obtain transparent backgrounds, use the RGBA type.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"We demonstrate this on a bidirectional coloring.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"\nS = sparse([\n 1 1 1 1 1 1 1 1 1\n 1 0 0 0 0 0 0 0 1\n 1 0 0 0 0 0 0 0 1\n 1 0 0 0 0 0 0 0 1\n 1 0 0 0 0 0 0 0 1\n 1 0 0 0 0 0 0 0 1\n 1 1 1 1 1 1 1 1 1\n])\n\nproblem_bi = ColoringProblem(; structure=:nonsymmetric, partition=:bidirectional)\nalgo_bi = GreedyColoringAlgorithm(RandomOrder(StableRNG(0)); decompression=:direct)\nresult_bi = coloring(S, problem_bi, algo_bi)\n\nA_img, Br_img, Bc_img = show_colors(\n result_bi;\n colorscheme=ColorSchemes.progress,\n background=RGB(1, 1, 1), # white\n scale=10,\n pad=2\n)","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"In the bidirectional case, columns and rows can both get colors:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"A_img","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"And there are two compression results, one by row and one by column:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Br_img","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Bc_img","category":"page"},{"location":"vis/#Working-with-large-matrices","page":"Visualization","title":"Working with large matrices","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Let's demonstrate visualization of a larger random matrix:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"S = sprand(50, 50, 0.1) # sample sparse matrix\n\nproblem = ColoringProblem(; structure=:nonsymmetric, partition=:column)\nalgo = GreedyColoringAlgorithm(; decompression=:direct)\nresult = coloring(S, problem, algo)\nshow_colors(result; scale=5, pad=1)[1]","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Instead of the default distinguishable_colors from Colors.jl, one can subsample a continuous colorscheme from ColorSchemes.jl:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"ncolors = maximum(column_colors(result)) # for partition=:column\ncolorscheme = get(ColorSchemes.rainbow, range(0.0, 1.0, length=ncolors))\nshow_colors(result; colorscheme=colorscheme, scale=5, pad=1)[1]","category":"page"},{"location":"vis/#Saving-images","page":"Visualization","title":"Saving images","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"The resulting image can be saved to a variety of formats, like PNG. The scale and pad parameters determine the number of pixels, and thus the size of the file.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"A_img, _ = show_colors(result, scale=5)\nsave(\"coloring.png\", A_img)","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Refer to the JuliaImages documentation on saving for more information.","category":"page"},{"location":"api/#API-reference","page":"API reference","title":"API reference","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"CollapsedDocStrings = true\nCurrentModule = SparseMatrixColorings","category":"page"},{"location":"api/","page":"API reference","title":"API reference","text":"The docstrings on this page define the public API of the package.","category":"page"},{"location":"api/","page":"API reference","title":"API reference","text":"SparseMatrixColorings","category":"page"},{"location":"api/#SparseMatrixColorings.SparseMatrixColorings","page":"API reference","title":"SparseMatrixColorings.SparseMatrixColorings","text":"SparseMatrixColorings\n\nSparseMatrixColorings.jl\n\n(Image: Build Status) (Image: Stable Documentation) (Image: Dev Documentation) (Image: Coverage) (Image: Code Style: Blue) (Image: DOI)\n\nColoring algorithms for sparse Jacobian and Hessian matrices.\n\nGetting started\n\nTo install this package, run the following in a Julia Pkg REPL:\n\npkg> add SparseMatrixColorings\n\nBackground\n\nThe algorithms implemented in this package are taken from the following articles:\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\nNew Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007)\nEfficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009)\nColPack: Software for graph coloring and related problems in scientific computing, Gebremedhin et al. (2013)\n\nSome parts of the articles (like definitions) are thus copied verbatim in the documentation.\n\nAlternatives\n\nColPack.jl: a Julia interface to the C++ library ColPack\nSparseDiffTools.jl: contains Julia implementations of some coloring algorithms\n\nCiting\n\nPlease 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.\n\nExports\n\nAbstractColoringResult\nColoringProblem\nConstantColoringAlgorithm\nDynamicDegreeBasedOrder\nDynamicLargestFirst\nGreedyColoringAlgorithm\nIncidenceDegree\nLargestFirst\nNaturalOrder\nRandomOrder\nSmallestLast\ncoloring\ncolumn_colors\ncolumn_groups\ncompress\ndecompress\ndecompress!\ndecompress_single_color!\nncolors\nrow_colors\nrow_groups\nsparsity_pattern\n\n\n\n\n\n","category":"module"},{"location":"api/#Main-function","page":"API reference","title":"Main function","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"coloring\nColoringProblem\nGreedyColoringAlgorithm\nConstantColoringAlgorithm","category":"page"},{"location":"api/#SparseMatrixColorings.coloring","page":"API reference","title":"SparseMatrixColorings.coloring","text":"coloring(\n S::AbstractMatrix,\n problem::ColoringProblem,\n algo::GreedyColoringAlgorithm;\n [decompression_eltype=Float64, symmetric_pattern=false]\n)\n\nSolve a ColoringProblem on the matrix S with a GreedyColoringAlgorithm and return an AbstractColoringResult.\n\nThe result can be used to compress and decompress a matrix A with the same sparsity pattern as S. If eltype(A) == decompression_eltype, decompression might be faster.\n\nFor a :nonsymmetric problem (and only then), setting symmetric_pattern=true indicates that the pattern of nonzeros is symmetric. This condition is weaker than the symmetry of actual values, so it can happen for some Jacobians. Specifying it allows faster construction of the bipartite graph.\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> S = sparse([\n 0 0 1 1 0 1\n 1 0 0 0 1 0\n 0 1 0 0 1 0\n 0 1 1 0 0 0\n ]);\n\njulia> problem = ColoringProblem(; structure=:nonsymmetric, partition=:column);\n\njulia> algo = GreedyColoringAlgorithm(; decompression=:direct);\n\njulia> result = coloring(S, problem, algo);\n\njulia> column_colors(result)\n6-element Vector{Int64}:\n 1\n 1\n 2\n 1\n 2\n 3\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\nSee also\n\nColoringProblem\nGreedyColoringAlgorithm\nAbstractColoringResult\ncompress\ndecompress\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.ColoringProblem","page":"API reference","title":"SparseMatrixColorings.ColoringProblem","text":"ColoringProblem{structure,partition}\n\nSelector type for the coloring problem to solve, enabling multiple dispatch.\n\nIt is passed as an argument to the main function coloring.\n\nConstructors\n\nColoringProblem{structure,partition}()\nColoringProblem(; structure=:nonsymmetric, partition=:column)\n\nstructure::Symbol: either :nonsymmetric or :symmetric\npartition::Symbol: either :column, :row or :bidirectional\n\nwarning: Warning\nThe second constructor (based on keyword arguments) is type-unstable.\n\nLink to automatic differentiation\n\nMatrix coloring is often used in automatic differentiation, and here is the translation guide:\n\nmatrix mode structure partition implemented\nJacobian forward :nonsymmetric :column yes\nJacobian reverse :nonsymmetric :row yes\nJacobian mixed :nonsymmetric :bidirectional yes\nHessian - :symmetric :column yes\nHessian - :symmetric :row no\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.GreedyColoringAlgorithm","page":"API reference","title":"SparseMatrixColorings.GreedyColoringAlgorithm","text":"GreedyColoringAlgorithm{decompression} <: ADTypes.AbstractColoringAlgorithm\n\nGreedy coloring algorithm for sparse matrices which colors columns or rows one after the other, following a configurable order.\n\nIt is passed as an argument to the main function coloring.\n\nConstructors\n\nGreedyColoringAlgorithm{decompression}(order=NaturalOrder())\nGreedyColoringAlgorithm(order=NaturalOrder(); decompression=:direct)\n\norder::AbstractOrder: the order in which the columns or rows are colored, which can impact the number of colors.\ndecompression::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.\n\nwarning: Warning\nThe second constructor (based on keyword arguments) is type-unstable.\n\nADTypes coloring interface\n\nGreedyColoringAlgorithm is a subtype of ADTypes.AbstractColoringAlgorithm, which means the following methods are also applicable:\n\nADTypes.column_coloring\nADTypes.row_coloring\nADTypes.symmetric_coloring\n\nSee their respective docstrings for details.\n\nSee also\n\nAbstractOrder\ndecompress\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.ConstantColoringAlgorithm","page":"API reference","title":"SparseMatrixColorings.ConstantColoringAlgorithm","text":"ConstantColoringAlgorithm{partition} <: ADTypes.AbstractColoringAlgorithm\n\nColoring 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).\n\nIt 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.\n\nConstructors\n\nConstantColoringAlgorithm{partition}(matrix_template, color)\nConstantColoringAlgorithm(matrix_template, color; partition=:column)\n\npartition::Symbol: either :row or :column.\nmatrix_template::AbstractMatrix: matrix for which the vector of colors was precomputed (the algorithm will only accept matrices of the exact same size).\ncolor::Vector{Int}: vector of integer colors, one for each row or column (depending on partition).\n\nwarning: Warning\nThe second constructor (based on keyword arguments) is type-unstable.\n\nWe do not necessarily verify consistency between the matrix template and the vector of colors, this is the responsibility of the user.\n\nExample\n\njulia> using SparseMatrixColorings, LinearAlgebra\n\njulia> matrix_template = Diagonal(ones(Bool, 5))\n5×5 Diagonal{Bool, Vector{Bool}}:\n 1 ⋅ ⋅ ⋅ ⋅\n ⋅ 1 ⋅ ⋅ ⋅\n ⋅ ⋅ 1 ⋅ ⋅\n ⋅ ⋅ ⋅ 1 ⋅\n ⋅ ⋅ ⋅ ⋅ 1\n\njulia> color = ones(Int, 5) # coloring a Diagonal is trivial\n5-element Vector{Int64}:\n 1\n 1\n 1\n 1\n 1\n\njulia> problem = ColoringProblem(; structure=:nonsymmetric, partition=:column);\n\njulia> algo = ConstantColoringAlgorithm(matrix_template, color; partition=:column);\n\njulia> result = coloring(similar(matrix_template), problem, algo);\n\njulia> column_colors(result)\n5-element Vector{Int64}:\n 1\n 1\n 1\n 1\n 1\n\nADTypes coloring interface\n\nConstantColoringAlgorithm 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):\n\nADTypes.column_coloring\nADTypes.row_coloring\n\n\n\n\n\n","category":"type"},{"location":"api/#Result-analysis","page":"API reference","title":"Result analysis","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"AbstractColoringResult\ncolumn_colors\nrow_colors\nncolors\ncolumn_groups\nrow_groups\nsparsity_pattern","category":"page"},{"location":"api/#SparseMatrixColorings.AbstractColoringResult","page":"API reference","title":"SparseMatrixColorings.AbstractColoringResult","text":"AbstractColoringResult{structure,partition,decompression}\n\nAbstract type for the result of a coloring algorithm.\n\nIt is the supertype of the object returned by the main function coloring.\n\nType parameters\n\nCombination between the type parameters of ColoringProblem and GreedyColoringAlgorithm:\n\nstructure::Symbol: either :nonsymmetric or :symmetric\npartition::Symbol: either :column, :row or :bidirectional\ndecompression::Symbol: either :direct or :substitution\n\nApplicable methods\n\ncolumn_colors and column_groups (for a :column or :bidirectional partition) \nrow_colors and row_groups (for a :row or :bidirectional partition)\nsparsity_pattern\ncompress, decompress, decompress!, decompress_single_color!\n\nwarning: Warning\nUnlike the methods above, the concrete subtypes of AbstractColoringResult are not part of the public API and may change without notice.\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.column_colors","page":"API reference","title":"SparseMatrixColorings.column_colors","text":"column_colors(result::AbstractColoringResult)\n\nReturn a vector color of integer colors, one for each column of the colored matrix.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.row_colors","page":"API reference","title":"SparseMatrixColorings.row_colors","text":"row_colors(result::AbstractColoringResult)\n\nReturn a vector color of integer colors, one for each row of the colored matrix.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.ncolors","page":"API reference","title":"SparseMatrixColorings.ncolors","text":"ncolors(result::AbstractColoringResult)\n\nReturn the number of different colors used to color the matrix.\n\nFor bidirectional partitions, this number is the sum of the number of row colors and the number of column colors.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.column_groups","page":"API reference","title":"SparseMatrixColorings.column_groups","text":"column_groups(result::AbstractColoringResult)\n\nReturn a vector group such that for every color c, group[c] contains the indices of all columns that are colored with c.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.row_groups","page":"API reference","title":"SparseMatrixColorings.row_groups","text":"row_groups(result::AbstractColoringResult)\n\nReturn a vector group such that for every color c, group[c] contains the indices of all rows that are colored with c.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.sparsity_pattern","page":"API reference","title":"SparseMatrixColorings.sparsity_pattern","text":"sparsity_pattern(result::AbstractColoringResult)\n\nReturn the matrix that was initially passed to coloring, without any modifications.\n\nnote: Note\nThis matrix is not necessarily a SparseMatrixCSC, nor does it necessarily have Bool entries.\n\n\n\n\n\n","category":"function"},{"location":"api/#Decompression","page":"API reference","title":"Decompression","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"compress\ndecompress\ndecompress!\ndecompress_single_color!","category":"page"},{"location":"api/#SparseMatrixColorings.compress","page":"API reference","title":"SparseMatrixColorings.compress","text":"compress(A, result::AbstractColoringResult)\n\nCompress A given a coloring result of the sparsity pattern of A.\n\nIf result comes from a :column (resp. :row) partition, the output is a single matrix B compressed by column (resp. by row).\nIf 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.\n\nCompression means summing either the columns or the rows of A which share the same color. It is undone by calling decompress or decompress!.\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> A = sparse([\n 0 0 4 6 0 9\n 1 0 0 0 7 0\n 0 2 0 0 8 0\n 0 3 5 0 0 0\n ]);\n\njulia> result = coloring(A, ColoringProblem(), GreedyColoringAlgorithm());\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\njulia> B = compress(A, result)\n4×3 Matrix{Int64}:\n 6 4 9\n 1 7 0\n 2 8 0\n 3 5 0\n\nSee also\n\nColoringProblem\nAbstractColoringResult\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.decompress","page":"API reference","title":"SparseMatrixColorings.decompress","text":"decompress(B::AbstractMatrix, result::AbstractColoringResult{_,:column/:row})\ndecompress(Br::AbstractMatrix, Bc::AbstractMatrix, result::AbstractColoringResult{_,:bidirectional})\n\nDecompress B (or the tuple (Br,Bc)) into a new matrix A, given a coloring result of the sparsity pattern of A. The in-place alternative is decompress!.\n\nCompression means summing either the columns or the rows of A which share the same color. It is done by calling compress.\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> A = sparse([\n 0 0 4 6 0 9\n 1 0 0 0 7 0\n 0 2 0 0 8 0\n 0 3 5 0 0 0\n ]);\n\njulia> result = coloring(A, ColoringProblem(), GreedyColoringAlgorithm());\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\njulia> B = compress(A, result)\n4×3 Matrix{Int64}:\n 6 4 9\n 1 7 0\n 2 8 0\n 3 5 0\n\njulia> decompress(B, result)\n4×6 SparseMatrixCSC{Int64, Int64} with 9 stored entries:\n ⋅ ⋅ 4 6 ⋅ 9\n 1 ⋅ ⋅ ⋅ 7 ⋅\n ⋅ 2 ⋅ ⋅ 8 ⋅\n ⋅ 3 5 ⋅ ⋅ ⋅\n\njulia> decompress(B, result) == A\ntrue\n\nSee also\n\nColoringProblem\nAbstractColoringResult\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.decompress!","page":"API reference","title":"SparseMatrixColorings.decompress!","text":"decompress!(\n A::AbstractMatrix, B::AbstractMatrix,\n result::AbstractColoringResult{_,:column/:row}, [uplo=:F]\n)\n\ndecompress!(\n A::AbstractMatrix, Br::AbstractMatrix, Bc::AbstractMatrix\n result::AbstractColoringResult{_,:bidirectional}\n)\n\nDecompress B (or the tuple (Br,Bc)) in-place into A, given a coloring result of the sparsity pattern of A. The out-of-place alternative is decompress.\n\nnote: Note\nIn-place decompression is faster when A isa SparseMatrixCSC.\n\nCompression means summing either the columns or the rows of A which share the same color. It is done by calling compress.\n\nFor :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).\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> A = sparse([\n 0 0 4 6 0 9\n 1 0 0 0 7 0\n 0 2 0 0 8 0\n 0 3 5 0 0 0\n ]);\n\njulia> result = coloring(A, ColoringProblem(), GreedyColoringAlgorithm());\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\njulia> B = compress(A, result)\n4×3 Matrix{Int64}:\n 6 4 9\n 1 7 0\n 2 8 0\n 3 5 0\n\njulia> A2 = similar(A);\n\njulia> decompress!(A2, B, result)\n4×6 SparseMatrixCSC{Int64, Int64} with 9 stored entries:\n ⋅ ⋅ 4 6 ⋅ 9\n 1 ⋅ ⋅ ⋅ 7 ⋅\n ⋅ 2 ⋅ ⋅ 8 ⋅\n ⋅ 3 5 ⋅ ⋅ ⋅\n\njulia> A2 == A\ntrue\n\nSee also\n\nColoringProblem\nAbstractColoringResult\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.decompress_single_color!","page":"API reference","title":"SparseMatrixColorings.decompress_single_color!","text":"decompress_single_color!(\n A::AbstractMatrix, b::AbstractVector, c::Integer,\n result::AbstractColoringResult, [uplo=:F]\n)\n\nDecompress 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).\n\nIf 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).\nIf 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).\nIf result comes from a :symmetric structure with :column partition, this will update the coefficients of A whose value is deduced from color c.\n\nwarning: Warning\nThis function will only update some coefficients of A, without resetting the rest to zero.\n\nFor :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).\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> A = sparse([\n 0 0 4 6 0 9\n 1 0 0 0 7 0\n 0 2 0 0 8 0\n 0 3 5 0 0 0\n ]);\n\njulia> result = coloring(A, ColoringProblem(), GreedyColoringAlgorithm());\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\njulia> B = compress(A, result)\n4×3 Matrix{Int64}:\n 6 4 9\n 1 7 0\n 2 8 0\n 3 5 0\n\njulia> A2 = similar(A); A2 .= 0;\n\njulia> decompress_single_color!(A2, B[:, 2], 2, result)\n4×6 SparseMatrixCSC{Int64, Int64} with 9 stored entries:\n ⋅ ⋅ 4 0 ⋅ 0\n 0 ⋅ ⋅ ⋅ 7 ⋅\n ⋅ 0 ⋅ ⋅ 8 ⋅\n ⋅ 0 5 ⋅ ⋅ ⋅\n\njulia> A2[:, [3, 5]] == A[:, [3, 5]]\ntrue\n\nSee also\n\nColoringProblem\nAbstractColoringResult\ndecompress!\n\n\n\n\n\n","category":"function"},{"location":"api/#Orders","page":"API reference","title":"Orders","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"AbstractOrder\nNaturalOrder\nRandomOrder\nLargestFirst\nSmallestLast\nIncidenceDegree\nDynamicLargestFirst\nDynamicDegreeBasedOrder","category":"page"},{"location":"api/#SparseMatrixColorings.AbstractOrder","page":"API reference","title":"SparseMatrixColorings.AbstractOrder","text":"AbstractOrder\n\nAbstract supertype for the vertex order used inside GreedyColoringAlgorithm.\n\nIn this algorithm, the rows and columns of a matrix form a graph, and the vertices are colored one after the other in a greedy fashion. Depending on how the vertices are ordered, the number of colors necessary may vary.\n\nOptions\n\nNaturalOrder\nRandomOrder\nLargestFirst\nIncidenceDegree (experimental)\nSmallestLast (experimental)\nDynamicLargestFirst (experimental)\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.NaturalOrder","page":"API reference","title":"SparseMatrixColorings.NaturalOrder","text":"NaturalOrder()\n\nInstance of AbstractOrder which sorts vertices using their index in the provided graph.\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.RandomOrder","page":"API reference","title":"SparseMatrixColorings.RandomOrder","text":"RandomOrder(rng=default_rng())\n\nInstance of AbstractOrder which sorts vertices using a random permutation.\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.LargestFirst","page":"API reference","title":"SparseMatrixColorings.LargestFirst","text":"LargestFirst()\n\nInstance of AbstractOrder which sorts vertices using their degree in the provided graph: the largest degree comes first.\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.SmallestLast","page":"API reference","title":"SparseMatrixColorings.SmallestLast","text":"SmallestLast()\n\nInstance of AbstractOrder which sorts vertices from highest to lowest using the dynamic back degree.\n\ndanger: Danger\nThis order is still experimental and needs more tests, correctness is not yet guaranteed.\n\nSee also\n\nDynamicDegreeBasedOrder\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.IncidenceDegree","page":"API reference","title":"SparseMatrixColorings.IncidenceDegree","text":"IncidenceDegree()\n\nInstance of AbstractOrder which sorts vertices from lowest to highest using the dynamic back degree.\n\ndanger: Danger\nThis order is still experimental and needs more tests, correctness is not yet guaranteed.\n\nSee also\n\nDynamicDegreeBasedOrder\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.DynamicLargestFirst","page":"API reference","title":"SparseMatrixColorings.DynamicLargestFirst","text":"DynamicLargestFirst()\n\nInstance of AbstractOrder which sorts vertices from lowest to highest using the dynamic forward degree.\n\ndanger: Danger\nThis order is still experimental and needs more tests, correctness is not yet guaranteed.\n\nSee also\n\nDynamicDegreeBasedOrder\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.DynamicDegreeBasedOrder","page":"API reference","title":"SparseMatrixColorings.DynamicDegreeBasedOrder","text":"DynamicDegreeBasedOrder{degtype,direction}\n\nInstance of AbstractOrder which sorts vertices using a dynamically computed degree.\n\ndanger: Danger\nThis order is still experimental and needs more tests, correctness is not yet guaranteed.\n\nType parameters\n\ndegtype::Symbol: can be :forward (for the forward degree) or :back (for the back degree)\ndirection::Symbol: can be :low2high (if the order is defined from lowest to highest, i.e. 1 to n) or :high2low (if the order is defined from highest to lowest, i.e. n to 1)\n\nConcrete variants\n\nIncidenceDegree\nSmallestLast\nDynamicLargestFirst\n\nReferences\n\nColPack: Software for graph coloring and related problems in scientific computing, Gebremedhin et al. (2013), Section 5\n\n\n\n\n\n","category":"type"},{"location":"dev/#Internals","page":"Internals","title":"Internals","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"CollapsedDocStrings = true\nCurrentModule = SparseMatrixColorings","category":"page"},{"location":"dev/","page":"Internals","title":"Internals","text":"The docstrings on this page describe internals, they are not part of the public API.","category":"page"},{"location":"dev/#Graph-storage","page":"Internals","title":"Graph storage","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.SparsityPatternCSC\nSparseMatrixColorings.AdjacencyGraph\nSparseMatrixColorings.BipartiteGraph\nSparseMatrixColorings.vertices\nSparseMatrixColorings.neighbors\ntranspose","category":"page"},{"location":"dev/#SparseMatrixColorings.SparsityPatternCSC","page":"Internals","title":"SparseMatrixColorings.SparsityPatternCSC","text":"SparsityPatternCSC{Ti<:Integer}\n\nStore a sparse matrix (in CSC) without its values, keeping only the pattern of nonzeros.\n\nFields\n\nCopied from SparseMatrixCSC:\n\nm::Int: number of rows\nn::Int: number of columns\ncolptr::Vector{Ti}: column j is in colptr[j]:(colptr[j+1]-1)\nrowval::Vector{Ti}: row indices of stored values\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.AdjacencyGraph","page":"Internals","title":"SparseMatrixColorings.AdjacencyGraph","text":"AdjacencyGraph{T}\n\nUndirected graph without self-loops representing the nonzeros of a symmetric matrix (typically a Hessian matrix).\n\nThe adjacency graph of a symmetrix matric A ∈ ℝ^{n × n} is G(A) = (V, E) where\n\nV = 1:n is the set of rows or columns i/j\n(i, j) ∈ E whenever A[i, j] ≠ 0 and i ≠ j\n\nConstructors\n\nAdjacencyGraph(A::SparseMatrixCSC)\n\nFields\n\nS::SparsityPatternCSC{T}\n\nReferences\n\nWhat Color Is Your Jacobian? SparsityPatternCSC Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.BipartiteGraph","page":"Internals","title":"SparseMatrixColorings.BipartiteGraph","text":"BipartiteGraph{T}\n\nUndirected bipartite graph representing the nonzeros of a non-symmetric matrix (typically a Jacobian matrix).\n\nThe bipartite graph of a matrix A ∈ ℝ^{m × n} is Gb(A) = (V₁, V₂, E) where\n\nV₁ = 1:m is the set of rows i\nV₂ = 1:n is the set of columns j\n(i, j) ∈ E whenever A[i, j] ≠ 0\n\nA 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).\n\nConstructors\n\nBipartiteGraph(A::SparseMatrixCSC; symmetric_pattern=false)\n\nWhen symmetric_pattern is true, this construction is more efficient.\n\nFields\n\nS1::SparsityPatternCSC{T}: maps vertices on side 1 to their neighbors\nS2::SparsityPatternCSC{T}: maps vertices on side 2 to their neighbors\n\nReferences\n\nWhat Color Is Your Jacobian? SparsityPatternCSC Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.vertices","page":"Internals","title":"SparseMatrixColorings.vertices","text":"vertices(bg::BipartiteGraph, Val(side))\n\nReturn the list of vertices of bg from the specified side as a range 1:n.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.neighbors","page":"Internals","title":"SparseMatrixColorings.neighbors","text":"neighbors(bg::BipartiteGraph, Val(side), v::Integer)\n\nReturn the neighbors of v (a vertex from the specified side, 1 or 2), in the graph bg.\n\n\n\n\n\n","category":"function"},{"location":"dev/#Base.transpose","page":"Internals","title":"Base.transpose","text":"transpose(S::SparsityPatternCSC)\n\nReturn a SparsityPatternCSC corresponding to the transpose of S.\n\n\n\n\n\n","category":"function"},{"location":"dev/#Low-level-coloring","page":"Internals","title":"Low-level coloring","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.partial_distance2_coloring\nSparseMatrixColorings.symmetric_coefficient\nSparseMatrixColorings.star_coloring\nSparseMatrixColorings.acyclic_coloring\nSparseMatrixColorings.group_by_color\nSparseMatrixColorings.StarSet\nSparseMatrixColorings.TreeSet","category":"page"},{"location":"dev/#SparseMatrixColorings.partial_distance2_coloring","page":"Internals","title":"SparseMatrixColorings.partial_distance2_coloring","text":"partial_distance2_coloring(bg::BipartiteGraph, ::Val{side}, order::AbstractOrder)\n\nCompute a distance-2 coloring of the given side (1 or 2) in the bipartite graph bg and return a vector of integer colors.\n\nA distance-2 coloring is such that two vertices have different colors if they are at distance at most 2.\n\nThe vertices are colored in a greedy fashion, following the order supplied.\n\nSee also\n\nBipartiteGraph\nAbstractOrder\n\nReferences\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005), Algorithm 3.2\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.symmetric_coefficient","page":"Internals","title":"SparseMatrixColorings.symmetric_coefficient","text":"symmetric_coefficient(\n i::Integer, j::Integer,\n color::AbstractVector{<:Integer},\n star_set::StarSet\n)\n\nReturn the indices (k, c) such that A[i, j] = B[k, c], where A is the uncompressed symmetric matrix and B is the column-compressed matrix.\n\nThis function corresponds to algorithm DirectRecover2 in the paper.\n\nReferences\n\nEfficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009), Figure 3\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.star_coloring","page":"Internals","title":"SparseMatrixColorings.star_coloring","text":"star_coloring(g::AdjacencyGraph, order::AbstractOrder)\n\nCompute a star coloring of all vertices in the adjacency graph g and return a tuple (color, star_set), where\n\ncolor is the vector of integer colors\nstar_set is a StarSet encoding the set of 2-colored stars\n\nA star coloring is a distance-1 coloring such that every path on 4 vertices uses at least 3 colors.\n\nThe vertices are colored in a greedy fashion, following the order supplied.\n\nSee also\n\nAdjacencyGraph\nAbstractOrder\n\nReferences\n\nNew Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007), Algorithm 4.1\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.acyclic_coloring","page":"Internals","title":"SparseMatrixColorings.acyclic_coloring","text":"acyclic_coloring(g::AdjacencyGraph, order::AbstractOrder)\n\nCompute an acyclic coloring of all vertices in the adjacency graph g and return a tuple (color, tree_set), where\n\ncolor is the vector of integer colors\ntree_set is a TreeSet encoding the set of 2-colored trees\n\nAn acyclic coloring is a distance-1 coloring with the further restriction that every cycle uses at least 3 colors.\n\nThe vertices are colored in a greedy fashion, following the order supplied.\n\nSee also\n\nAdjacencyGraph\nAbstractOrder\n\nReferences\n\nNew Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007), Algorithm 3.1\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.group_by_color","page":"Internals","title":"SparseMatrixColorings.group_by_color","text":"group_by_color(color::Vector{Int})\n\nCreate a color-indexed vector group such that i ∈ group[c] iff color[i] == c.\n\nAssumes the colors are contiguously numbered from 1 to some cmax.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.StarSet","page":"Internals","title":"SparseMatrixColorings.StarSet","text":"StarSet\n\nEncode a set of 2-colored stars resulting from the star_coloring algorithm.\n\nFields\n\nstar::Dict{Tuple{Int64, Int64}, Int64}: a mapping from edges (pair of vertices) to their star index\nhub::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)\nspokes::Vector{Vector{Int64}}: a mapping from star indices to the vector of their spokes\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.TreeSet","page":"Internals","title":"SparseMatrixColorings.TreeSet","text":"TreeSet\n\nEncode a set of 2-colored trees resulting from the acyclic_coloring algorithm.\n\nFields\n\nforest::DataStructures.DisjointSets{Tuple{Int64, Int64}}: a forest of two-colored trees\n\n\n\n\n\n","category":"type"},{"location":"dev/#Concrete-coloring-results","page":"Internals","title":"Concrete coloring results","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.ColumnColoringResult\nSparseMatrixColorings.RowColoringResult\nSparseMatrixColorings.StarSetColoringResult\nSparseMatrixColorings.TreeSetColoringResult\nSparseMatrixColorings.LinearSystemColoringResult\nSparseMatrixColorings.BicoloringResult\nSparseMatrixColorings.remap_colors","category":"page"},{"location":"dev/#SparseMatrixColorings.ColumnColoringResult","page":"Internals","title":"SparseMatrixColorings.ColumnColoringResult","text":"struct ColumnColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.BipartiteGraph, V} <: AbstractColoringResult{:nonsymmetric, :column, :direct}\n\nStorage for the result of a column coloring with direct decompression.\n\nFields\n\nA::AbstractMatrix: matrix that was colored\nbg::SparseMatrixColorings.BipartiteGraph: bipartite graph that was used for coloring\ncolor::Vector{Int64}: one integer color for each column or row (depending on partition)\ngroup::Any: color groups for columns or rows (depending on partition)\ncompressed_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]]\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.RowColoringResult","page":"Internals","title":"SparseMatrixColorings.RowColoringResult","text":"struct RowColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.BipartiteGraph, V} <: AbstractColoringResult{:nonsymmetric, :row, :direct}\n\nStorage for the result of a row coloring with direct decompression.\n\nFields\n\nSee the docstring of ColumnColoringResult.\n\nA::AbstractMatrix\nbg::SparseMatrixColorings.BipartiteGraph\ncolor::Vector{Int64}\ngroup::Any\ncompressed_indices::Vector{Int64}\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.StarSetColoringResult","page":"Internals","title":"SparseMatrixColorings.StarSetColoringResult","text":"struct StarSetColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V} <: AbstractColoringResult{:symmetric, :column, :direct}\n\nStorage for the result of a symmetric coloring with direct decompression.\n\nFields\n\nSee the docstring of ColumnColoringResult.\n\nA::AbstractMatrix\nag::SparseMatrixColorings.AdjacencyGraph\ncolor::Vector{Int64}\ngroup::Any\nstar_set::SparseMatrixColorings.StarSet\ncompressed_indices::Vector{Int64}\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.TreeSetColoringResult","page":"Internals","title":"SparseMatrixColorings.TreeSetColoringResult","text":"struct TreeSetColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V, R} <: AbstractColoringResult{:symmetric, :column, :substitution}\n\nStorage for the result of a symmetric coloring with decompression by substitution.\n\nFields\n\nSee the docstring of ColumnColoringResult.\n\nA::AbstractMatrix\nag::SparseMatrixColorings.AdjacencyGraph\ncolor::Vector{Int64}\ngroup::Any\nvertices_by_tree::Vector{Vector{Int64}}\nreverse_bfs_orders::Vector{Vector{Tuple{Int64, Int64}}}\ndiagonal_indices::Vector{Int64}\ndiagonal_nzind::Vector{Int64}\nlower_triangle_offsets::Vector{Int64}\nupper_triangle_offsets::Vector{Int64}\nbuffer::Vector\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.LinearSystemColoringResult","page":"Internals","title":"SparseMatrixColorings.LinearSystemColoringResult","text":"struct LinearSystemColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V, R, F} <: AbstractColoringResult{:symmetric, :column, :substitution}\n\nStorage for the result of a symmetric coloring with any decompression.\n\nFields\n\nSee the docstring of ColumnColoringResult.\n\nA::AbstractMatrix\nag::SparseMatrixColorings.AdjacencyGraph\ncolor::Vector{Int64}\ngroup::Any\nstrict_upper_nonzero_inds::Vector{Tuple{Int64, Int64}}\nstrict_upper_nonzeros_A::Vector\nT_factorization::Any\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.BicoloringResult","page":"Internals","title":"SparseMatrixColorings.BicoloringResult","text":"struct BicoloringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, decompression, V, SR<:AbstractColoringResult{:symmetric, :column, decompression}, R} <: AbstractColoringResult{:nonsymmetric, :bidirectional, decompression}\n\nStorage for the result of a bidirectional coloring with direct or substitution decompression, based on the symmetric coloring of a 2x2 block matrix.\n\nFields\n\nA::AbstractMatrix: matrix that was colored\nabg::SparseMatrixColorings.AdjacencyGraph: adjacency graph that was used for coloring (constructed from the bipartite graph)\ncolumn_color::Vector{Int64}: one integer color for each column\nrow_color::Vector{Int64}: one integer color for each row\ncolumn_group::Any: color groups for columns\nrow_group::Any: color groups for rows\nsymmetric_result::AbstractColoringResult{:symmetric, :column}: result for the coloring of the symmetric 2x2 block matrix\ncol_color_ind::Dict{Int64, Int64}: column color to index\nrow_color_ind::Dict{Int64, Int64}: row color to index\nBr_and_Bc::Matrix: combination of Br and Bc (almost a concatenation up to color remapping)\nlarge_colptr::Vector{Int64}: CSC storage of A_and_noAᵀ -colptr`\nlarge_rowval::Vector{Int64}: CSC storage of A_and_noAᵀ -rowval`\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.remap_colors","page":"Internals","title":"SparseMatrixColorings.remap_colors","text":"remap_colors(color::Vector{Int})\n\nRenumber the colors in color using their index in the vector sort(unique(color)), so that they are forced to go from 1 to some cmax contiguously.\n\nReturn a tuple (remapped_colors, color_to_ind) such that remapped_colors is a vector containing the renumbered colors and color_to_ind is a dictionary giving the translation between old and new color numberings.\n\nFor all vertex indices i we have:\n\nremapped_color[i] = color_to_ind[color[i]]\n\n\n\n\n\n","category":"function"},{"location":"dev/#Testing","page":"Internals","title":"Testing","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.directly_recoverable_columns\nSparseMatrixColorings.symmetrically_orthogonal_columns\nSparseMatrixColorings.structurally_orthogonal_columns\nSparseMatrixColorings.valid_dynamic_order","category":"page"},{"location":"dev/#SparseMatrixColorings.directly_recoverable_columns","page":"Internals","title":"SparseMatrixColorings.directly_recoverable_columns","text":"directly_recoverable_columns(\n A::AbstractMatrix, color::AbstractVector{<:Integer}\n verbose=false\n)\n\nReturn 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.\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\nReferences\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.symmetrically_orthogonal_columns","page":"Internals","title":"SparseMatrixColorings.symmetrically_orthogonal_columns","text":"symmetrically_orthogonal_columns(\n A::AbstractMatrix, color::AbstractVector{<:Integer};\n verbose=false\n)\n\nReturn 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.\n\nA 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:\n\nthe group containing the column A[:, j] has no other column with a nonzero in row i\nthe group containing the column A[:, i] has no other column with a nonzero in row j\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\nReferences\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.structurally_orthogonal_columns","page":"Internals","title":"SparseMatrixColorings.structurally_orthogonal_columns","text":"structurally_orthogonal_columns(\n A::AbstractMatrix, color::AbstractVector{<:Integer}\n verbose=false\n)\n\nReturn true if coloring the columns of the matrix A with the vector color results in a partition that is structurally orthogonal, and false otherwise.\n\nA 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.\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\nReferences\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.valid_dynamic_order","page":"Internals","title":"SparseMatrixColorings.valid_dynamic_order","text":"valid_dynamic_order(g::AdjacencyGraph, π::AbstractVector{Int}, order::DynamicDegreeBasedOrder)\nvalid_dynamic_order(bg::AdjacencyGraph, ::Val{side}, π::AbstractVector{Int}, order::DynamicDegreeBasedOrder)\n\nCheck that a permutation π corresponds to a valid application of a DynamicDegreeBasedOrder.\n\nThis is done by checking, for each ordered vertex, that its back- or forward-degree was the smallest or largest among the remaining vertices (the specifics depend on the order parameters).\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\n\n\n\n\n","category":"function"},{"location":"dev/#Matrix-handling","page":"Internals","title":"Matrix handling","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.respectful_similar\nSparseMatrixColorings.matrix_versions\nSparseMatrixColorings.same_pattern","category":"page"},{"location":"dev/#SparseMatrixColorings.respectful_similar","page":"Internals","title":"SparseMatrixColorings.respectful_similar","text":"respectful_similar(A::AbstractMatrix)\nrespectful_similar(A::AbstractMatrix, ::Type{T})\n\nLike Base.similar but returns a transpose or adjoint when A is a transpose or adjoint.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.matrix_versions","page":"Internals","title":"SparseMatrixColorings.matrix_versions","text":"matrix_versions(A::AbstractMatrix)\n\nReturn various versions of the same matrix:\n\ndense and sparse\ntranspose and adjoint\n\nUsed for internal testing.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.same_pattern","page":"Internals","title":"SparseMatrixColorings.same_pattern","text":"same_pattern(A, B)\n\nPerform a partial equality check on the sparsity patterns of A and B:\n\nif the return is true, they might have the same sparsity pattern but we're not sure\nif the return is false, they definitely don't have the same sparsity pattern\n\n\n\n\n\n","category":"function"},{"location":"dev/#Visualization","page":"Internals","title":"Visualization","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.show_colors","category":"page"},{"location":"dev/#SparseMatrixColorings.show_colors","page":"Internals","title":"SparseMatrixColorings.show_colors","text":"show_colors(result; kwargs...)\n\nCreate a visualization for an AbstractColoringResult, with the help of the the JuliaImages ecosystem.\n\nFor :column or :row colorings, it returns a tuple (A_img, B_img).\nFor :bidirectional colorings, it returns a tuple (A_img, Br_img, Bc_img).\n\nwarning: Warning\nThis function is implemented in a package extension, using it requires loading Colors.jl.\n\nKeyword arguments\n\ncolorscheme: colors used for non-zero matrix entries. This can be a vector of Colorants or a subsampled scheme from ColorSchemes.jl.\nbackground::Colorant: color used for zero matrix entries and pad. Defaults to RGBA(0,0,0,0), a transparent background.\nscale::Int: scale the size of matrix entries to scale × scale pixels. Defaults to 1. \npad::Int: set padding between matrix entries, in pixels. Defaults to 0. \n\nFor a matrix of size (n, m), the resulting output will be of size (n * (scale + pad) + pad, m * (scale + pad) + pad).\n\n\n\n\n\n","category":"function"},{"location":"dev/#Examples","page":"Internals","title":"Examples","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.Example\nSparseMatrixColorings.what_fig_41\nSparseMatrixColorings.what_fig_61\nSparseMatrixColorings.efficient_fig_1\nSparseMatrixColorings.efficient_fig_4","category":"page"},{"location":"dev/#SparseMatrixColorings.Example","page":"Internals","title":"SparseMatrixColorings.Example","text":"struct Example{TA<:(AbstractMatrix), TB<:(AbstractMatrix)}\n\nExample coloring problem from one of our reference articles.\n\nUsed for internal testing.\n\nFields\n\nA::AbstractMatrix: decompressed matrix\nB::AbstractMatrix: column-compressed matrix\ncolor::Vector{Int64}: vector of colors\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.what_fig_41","page":"Internals","title":"SparseMatrixColorings.what_fig_41","text":"what_fig_41()\n\nConstruct an Example from Figure 4.1 of \"What color is your Jacobian?\", where the nonzero entries are filled with unique values.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.what_fig_61","page":"Internals","title":"SparseMatrixColorings.what_fig_61","text":"what_fig_61()\n\nConstruct an Example from Figure 6.1 of \"What color is your Jacobian?\", where the nonzero entries are filled with unique values.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.efficient_fig_1","page":"Internals","title":"SparseMatrixColorings.efficient_fig_1","text":"efficient_fig_1()\n\nConstruct an Example from Figure 1 of \"Efficient computation of sparse hessians using coloring and AD\", where the nonzero entries are filled with unique values.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.efficient_fig_4","page":"Internals","title":"SparseMatrixColorings.efficient_fig_4","text":"efficient_fig_4()\n\nConstruct an Example from Figure 4 of \"Efficient computation of sparse hessians using coloring and AD\", where the nonzero entries are filled with unique values.\n\n\n\n\n\n","category":"function"},{"location":"#SparseMatrixColorings.jl","page":"Home","title":"SparseMatrixColorings.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"(Image: Build Status) (Image: Stable Documentation) (Image: Dev Documentation) (Image: Coverage) (Image: Code Style: Blue) (Image: DOI)","category":"page"},{"location":"","page":"Home","title":"Home","text":"Coloring algorithms for sparse Jacobian and Hessian matrices.","category":"page"},{"location":"#Getting-started","page":"Home","title":"Getting started","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"To install this package, run the following in a Julia Pkg REPL:","category":"page"},{"location":"","page":"Home","title":"Home","text":"pkg> add SparseMatrixColorings","category":"page"},{"location":"#Background","page":"Home","title":"Background","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The algorithms implemented in this package are taken from the following articles:","category":"page"},{"location":"","page":"Home","title":"Home","text":"What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\nNew Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007)\nEfficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009)\nColPack: Software for graph coloring and related problems in scientific computing, Gebremedhin et al. (2013)","category":"page"},{"location":"","page":"Home","title":"Home","text":"Some parts of the articles (like definitions) are thus copied verbatim in the documentation.","category":"page"},{"location":"#Alternatives","page":"Home","title":"Alternatives","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"ColPack.jl: a Julia interface to the C++ library ColPack\nSparseDiffTools.jl: contains Julia implementations of some coloring algorithms","category":"page"},{"location":"#Citing","page":"Home","title":"Citing","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"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.","category":"page"}] +[{"location":"vis/#Visualization","page":"Visualization","title":"Visualization","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"SparseMatrixColorings provides some internal utilities for visualization of matrix colorings via the un-exported function SparseMatrixColorings.show_colors.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"warning: Warning\nThis function makes use of the JuliaImages ecosystem. Using it requires loading at least Colors.jl. We recommend loading the full Images.jl package for convenience, which includes Colors.jl.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"using ColorSchemes\nusing Images\nusing SparseArrays\nusing SparseMatrixColorings\nusing SparseMatrixColorings: show_colors\nusing StableRNGs","category":"page"},{"location":"vis/#Basic-usage","page":"Visualization","title":"Basic usage","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"To obtain a visualization, simply call show_colors on a coloring result. It returns a tuple of outputs, corresponding to the matrix and its compression(s):","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"S = sparse([\n 0 0 1 1 0 1\n 1 0 0 0 1 0\n 0 1 0 0 1 0\n 0 1 1 0 0 0\n]);\n\nproblem = ColoringProblem(; structure=:nonsymmetric, partition=:column)\nalgo = GreedyColoringAlgorithm(; decompression=:direct)\nresult = coloring(S, problem, algo)\n\nA_img, B_img = show_colors(result; scale=3)","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"The colors on the original matrix look like this:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"A_img","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"And its column compression looks like that:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"B_img","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"tip: Terminal support\nLoading ImageInTerminal.jl will allow you to show the output of show_colors within your terminal. If you use VSCode's Julia REPL, the matrix will be displayed in the plot tab.","category":"page"},{"location":"vis/#Customization","page":"Visualization","title":"Customization","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"The visualization can be customized via keyword arguments. The size of the matrix entries is defined by scale, while gaps between them are dictated by pad. We recommend using the ColorSchemes.jl catalogue to customize the colorscheme. Finally, a background color can be passed via the background keyword argument. To obtain transparent backgrounds, use the RGBA type.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"We demonstrate this on a bidirectional coloring.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"\nS = sparse([\n 1 1 1 1 1 1 1 1 1\n 1 0 0 0 0 0 0 0 1\n 1 0 0 0 0 0 0 0 1\n 1 0 0 0 0 0 0 0 1\n 1 0 0 0 0 0 0 0 1\n 1 0 0 0 0 0 0 0 1\n 1 1 1 1 1 1 1 1 1\n])\n\nproblem_bi = ColoringProblem(; structure=:nonsymmetric, partition=:bidirectional)\nalgo_bi = GreedyColoringAlgorithm(RandomOrder(StableRNG(0)); decompression=:direct)\nresult_bi = coloring(S, problem_bi, algo_bi)\n\nA_img, Br_img, Bc_img = show_colors(\n result_bi;\n colorscheme=ColorSchemes.progress,\n background=RGB(1, 1, 1), # white\n scale=10,\n pad=2\n)","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"In the bidirectional case, columns and rows can both get colors:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"A_img","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"And there are two compression results, one by row and one by column:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Br_img","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Bc_img","category":"page"},{"location":"vis/#Working-with-large-matrices","page":"Visualization","title":"Working with large matrices","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Let's demonstrate visualization of a larger random matrix:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"S = sprand(50, 50, 0.1) # sample sparse matrix\n\nproblem = ColoringProblem(; structure=:nonsymmetric, partition=:column)\nalgo = GreedyColoringAlgorithm(; decompression=:direct)\nresult = coloring(S, problem, algo)\nshow_colors(result; scale=5, pad=1)[1]","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Instead of the default distinguishable_colors from Colors.jl, one can subsample a continuous colorscheme from ColorSchemes.jl:","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"ncolors = maximum(column_colors(result)) # for partition=:column\ncolorscheme = get(ColorSchemes.rainbow, range(0.0, 1.0, length=ncolors))\nshow_colors(result; colorscheme=colorscheme, scale=5, pad=1)[1]","category":"page"},{"location":"vis/#Saving-images","page":"Visualization","title":"Saving images","text":"","category":"section"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"The resulting image can be saved to a variety of formats, like PNG. The scale and pad parameters determine the number of pixels, and thus the size of the file.","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"A_img, _ = show_colors(result, scale=5)\nsave(\"coloring.png\", A_img)","category":"page"},{"location":"vis/","page":"Visualization","title":"Visualization","text":"Refer to the JuliaImages documentation on saving for more information.","category":"page"},{"location":"api/#API-reference","page":"API reference","title":"API reference","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"CollapsedDocStrings = true\nCurrentModule = SparseMatrixColorings","category":"page"},{"location":"api/","page":"API reference","title":"API reference","text":"The docstrings on this page define the public API of the package.","category":"page"},{"location":"api/","page":"API reference","title":"API reference","text":"SparseMatrixColorings","category":"page"},{"location":"api/#SparseMatrixColorings.SparseMatrixColorings","page":"API reference","title":"SparseMatrixColorings.SparseMatrixColorings","text":"SparseMatrixColorings\n\nSparseMatrixColorings.jl\n\n(Image: Build Status) (Image: Stable Documentation) (Image: Dev Documentation) (Image: Coverage) (Image: Code Style: Blue) (Image: DOI)\n\nColoring algorithms for sparse Jacobian and Hessian matrices.\n\nGetting started\n\nTo install this package, run the following in a Julia Pkg REPL:\n\npkg> add SparseMatrixColorings\n\nBackground\n\nThe algorithms implemented in this package are taken from the following articles:\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\nNew Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007)\nEfficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009)\nColPack: Software for graph coloring and related problems in scientific computing, Gebremedhin et al. (2013)\n\nSome parts of the articles (like definitions) are thus copied verbatim in the documentation.\n\nAlternatives\n\nColPack.jl: a Julia interface to the C++ library ColPack\nSparseDiffTools.jl: contains Julia implementations of some coloring algorithms\n\nCiting\n\nPlease 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.\n\nExports\n\nAbstractColoringResult\nColoringProblem\nConstantColoringAlgorithm\nDynamicDegreeBasedOrder\nDynamicLargestFirst\nGreedyColoringAlgorithm\nIncidenceDegree\nLargestFirst\nNaturalOrder\nRandomOrder\nSmallestLast\ncoloring\ncolumn_colors\ncolumn_groups\ncompress\ndecompress\ndecompress!\ndecompress_single_color!\nncolors\nrow_colors\nrow_groups\nsparsity_pattern\n\n\n\n\n\n","category":"module"},{"location":"api/#Main-function","page":"API reference","title":"Main function","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"coloring\nColoringProblem\nGreedyColoringAlgorithm\nConstantColoringAlgorithm","category":"page"},{"location":"api/#SparseMatrixColorings.coloring","page":"API reference","title":"SparseMatrixColorings.coloring","text":"coloring(\n S::AbstractMatrix,\n problem::ColoringProblem,\n algo::GreedyColoringAlgorithm;\n [decompression_eltype=Float64, symmetric_pattern=false]\n)\n\nSolve a ColoringProblem on the matrix S with a GreedyColoringAlgorithm and return an AbstractColoringResult.\n\nThe result can be used to compress and decompress a matrix A with the same sparsity pattern as S. If eltype(A) == decompression_eltype, decompression might be faster.\n\nFor a :nonsymmetric problem (and only then), setting symmetric_pattern=true indicates that the pattern of nonzeros is symmetric. This condition is weaker than the symmetry of actual values, so it can happen for some Jacobians. Specifying it allows faster construction of the bipartite graph.\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> S = sparse([\n 0 0 1 1 0 1\n 1 0 0 0 1 0\n 0 1 0 0 1 0\n 0 1 1 0 0 0\n ]);\n\njulia> problem = ColoringProblem(; structure=:nonsymmetric, partition=:column);\n\njulia> algo = GreedyColoringAlgorithm(; decompression=:direct);\n\njulia> result = coloring(S, problem, algo);\n\njulia> column_colors(result)\n6-element Vector{Int64}:\n 1\n 1\n 2\n 1\n 2\n 3\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\nSee also\n\nColoringProblem\nGreedyColoringAlgorithm\nAbstractColoringResult\ncompress\ndecompress\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.ColoringProblem","page":"API reference","title":"SparseMatrixColorings.ColoringProblem","text":"ColoringProblem{structure,partition}\n\nSelector type for the coloring problem to solve, enabling multiple dispatch.\n\nIt is passed as an argument to the main function coloring.\n\nConstructors\n\nColoringProblem{structure,partition}()\nColoringProblem(; structure=:nonsymmetric, partition=:column)\n\nstructure::Symbol: either :nonsymmetric or :symmetric\npartition::Symbol: either :column, :row or :bidirectional\n\nwarning: Warning\nThe second constructor (based on keyword arguments) is type-unstable.\n\nLink to automatic differentiation\n\nMatrix coloring is often used in automatic differentiation, and here is the translation guide:\n\nmatrix mode structure partition implemented\nJacobian forward :nonsymmetric :column yes\nJacobian reverse :nonsymmetric :row yes\nJacobian mixed :nonsymmetric :bidirectional yes\nHessian - :symmetric :column yes\nHessian - :symmetric :row no\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.GreedyColoringAlgorithm","page":"API reference","title":"SparseMatrixColorings.GreedyColoringAlgorithm","text":"GreedyColoringAlgorithm{decompression} <: ADTypes.AbstractColoringAlgorithm\n\nGreedy coloring algorithm for sparse matrices which colors columns or rows one after the other, following a configurable order.\n\nIt is passed as an argument to the main function coloring.\n\nConstructors\n\nGreedyColoringAlgorithm{decompression}(order=NaturalOrder())\nGreedyColoringAlgorithm(order=NaturalOrder(); decompression=:direct)\n\norder::AbstractOrder: the order in which the columns or rows are colored, which can impact the number of colors.\ndecompression::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.\n\nwarning: Warning\nThe second constructor (based on keyword arguments) is type-unstable.\n\nADTypes coloring interface\n\nGreedyColoringAlgorithm is a subtype of ADTypes.AbstractColoringAlgorithm, which means the following methods are also applicable:\n\nADTypes.column_coloring\nADTypes.row_coloring\nADTypes.symmetric_coloring\n\nSee their respective docstrings for details.\n\nSee also\n\nAbstractOrder\ndecompress\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.ConstantColoringAlgorithm","page":"API reference","title":"SparseMatrixColorings.ConstantColoringAlgorithm","text":"ConstantColoringAlgorithm{partition} <: ADTypes.AbstractColoringAlgorithm\n\nColoring 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).\n\nIt 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.\n\nConstructors\n\nConstantColoringAlgorithm{partition}(matrix_template, color)\nConstantColoringAlgorithm(matrix_template, color; partition=:column)\n\npartition::Symbol: either :row or :column.\nmatrix_template::AbstractMatrix: matrix for which the vector of colors was precomputed (the algorithm will only accept matrices of the exact same size).\ncolor::Vector{Int}: vector of integer colors, one for each row or column (depending on partition).\n\nwarning: Warning\nThe second constructor (based on keyword arguments) is type-unstable.\n\nWe do not necessarily verify consistency between the matrix template and the vector of colors, this is the responsibility of the user.\n\nExample\n\njulia> using SparseMatrixColorings, LinearAlgebra\n\njulia> matrix_template = Diagonal(ones(Bool, 5))\n5×5 Diagonal{Bool, Vector{Bool}}:\n 1 ⋅ ⋅ ⋅ ⋅\n ⋅ 1 ⋅ ⋅ ⋅\n ⋅ ⋅ 1 ⋅ ⋅\n ⋅ ⋅ ⋅ 1 ⋅\n ⋅ ⋅ ⋅ ⋅ 1\n\njulia> color = ones(Int, 5) # coloring a Diagonal is trivial\n5-element Vector{Int64}:\n 1\n 1\n 1\n 1\n 1\n\njulia> problem = ColoringProblem(; structure=:nonsymmetric, partition=:column);\n\njulia> algo = ConstantColoringAlgorithm(matrix_template, color; partition=:column);\n\njulia> result = coloring(similar(matrix_template), problem, algo);\n\njulia> column_colors(result)\n5-element Vector{Int64}:\n 1\n 1\n 1\n 1\n 1\n\nADTypes coloring interface\n\nConstantColoringAlgorithm 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):\n\nADTypes.column_coloring\nADTypes.row_coloring\n\n\n\n\n\n","category":"type"},{"location":"api/#Result-analysis","page":"API reference","title":"Result analysis","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"AbstractColoringResult\ncolumn_colors\nrow_colors\nncolors\ncolumn_groups\nrow_groups\nsparsity_pattern","category":"page"},{"location":"api/#SparseMatrixColorings.AbstractColoringResult","page":"API reference","title":"SparseMatrixColorings.AbstractColoringResult","text":"AbstractColoringResult{structure,partition,decompression}\n\nAbstract type for the result of a coloring algorithm.\n\nIt is the supertype of the object returned by the main function coloring.\n\nType parameters\n\nCombination between the type parameters of ColoringProblem and GreedyColoringAlgorithm:\n\nstructure::Symbol: either :nonsymmetric or :symmetric\npartition::Symbol: either :column, :row or :bidirectional\ndecompression::Symbol: either :direct or :substitution\n\nApplicable methods\n\ncolumn_colors and column_groups (for a :column or :bidirectional partition) \nrow_colors and row_groups (for a :row or :bidirectional partition)\nsparsity_pattern\ncompress, decompress, decompress!, decompress_single_color!\n\nwarning: Warning\nUnlike the methods above, the concrete subtypes of AbstractColoringResult are not part of the public API and may change without notice.\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.column_colors","page":"API reference","title":"SparseMatrixColorings.column_colors","text":"column_colors(result::AbstractColoringResult)\n\nReturn a vector color of integer colors, one for each column of the colored matrix.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.row_colors","page":"API reference","title":"SparseMatrixColorings.row_colors","text":"row_colors(result::AbstractColoringResult)\n\nReturn a vector color of integer colors, one for each row of the colored matrix.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.ncolors","page":"API reference","title":"SparseMatrixColorings.ncolors","text":"ncolors(result::AbstractColoringResult)\n\nReturn the number of different colors used to color the matrix.\n\nFor bidirectional partitions, this number is the sum of the number of row colors and the number of column colors.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.column_groups","page":"API reference","title":"SparseMatrixColorings.column_groups","text":"column_groups(result::AbstractColoringResult)\n\nReturn a vector group such that for every color c, group[c] contains the indices of all columns that are colored with c.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.row_groups","page":"API reference","title":"SparseMatrixColorings.row_groups","text":"row_groups(result::AbstractColoringResult)\n\nReturn a vector group such that for every color c, group[c] contains the indices of all rows that are colored with c.\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.sparsity_pattern","page":"API reference","title":"SparseMatrixColorings.sparsity_pattern","text":"sparsity_pattern(result::AbstractColoringResult)\n\nReturn the matrix that was initially passed to coloring, without any modifications.\n\nnote: Note\nThis matrix is not necessarily a SparseMatrixCSC, nor does it necessarily have Bool entries.\n\n\n\n\n\n","category":"function"},{"location":"api/#Decompression","page":"API reference","title":"Decompression","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"compress\ndecompress\ndecompress!\ndecompress_single_color!","category":"page"},{"location":"api/#SparseMatrixColorings.compress","page":"API reference","title":"SparseMatrixColorings.compress","text":"compress(A, result::AbstractColoringResult)\n\nCompress A given a coloring result of the sparsity pattern of A.\n\nIf result comes from a :column (resp. :row) partition, the output is a single matrix B compressed by column (resp. by row).\nIf 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.\n\nCompression means summing either the columns or the rows of A which share the same color. It is undone by calling decompress or decompress!.\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> A = sparse([\n 0 0 4 6 0 9\n 1 0 0 0 7 0\n 0 2 0 0 8 0\n 0 3 5 0 0 0\n ]);\n\njulia> result = coloring(A, ColoringProblem(), GreedyColoringAlgorithm());\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\njulia> B = compress(A, result)\n4×3 Matrix{Int64}:\n 6 4 9\n 1 7 0\n 2 8 0\n 3 5 0\n\nSee also\n\nColoringProblem\nAbstractColoringResult\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.decompress","page":"API reference","title":"SparseMatrixColorings.decompress","text":"decompress(B::AbstractMatrix, result::AbstractColoringResult{_,:column/:row})\ndecompress(Br::AbstractMatrix, Bc::AbstractMatrix, result::AbstractColoringResult{_,:bidirectional})\n\nDecompress B (or the tuple (Br,Bc)) into a new matrix A, given a coloring result of the sparsity pattern of A. The in-place alternative is decompress!.\n\nCompression means summing either the columns or the rows of A which share the same color. It is done by calling compress.\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> A = sparse([\n 0 0 4 6 0 9\n 1 0 0 0 7 0\n 0 2 0 0 8 0\n 0 3 5 0 0 0\n ]);\n\njulia> result = coloring(A, ColoringProblem(), GreedyColoringAlgorithm());\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\njulia> B = compress(A, result)\n4×3 Matrix{Int64}:\n 6 4 9\n 1 7 0\n 2 8 0\n 3 5 0\n\njulia> decompress(B, result)\n4×6 SparseMatrixCSC{Int64, Int64} with 9 stored entries:\n ⋅ ⋅ 4 6 ⋅ 9\n 1 ⋅ ⋅ ⋅ 7 ⋅\n ⋅ 2 ⋅ ⋅ 8 ⋅\n ⋅ 3 5 ⋅ ⋅ ⋅\n\njulia> decompress(B, result) == A\ntrue\n\nSee also\n\nColoringProblem\nAbstractColoringResult\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.decompress!","page":"API reference","title":"SparseMatrixColorings.decompress!","text":"decompress!(\n A::AbstractMatrix, B::AbstractMatrix,\n result::AbstractColoringResult{_,:column/:row}, [uplo=:F]\n)\n\ndecompress!(\n A::AbstractMatrix, Br::AbstractMatrix, Bc::AbstractMatrix\n result::AbstractColoringResult{_,:bidirectional}\n)\n\nDecompress B (or the tuple (Br,Bc)) in-place into A, given a coloring result of the sparsity pattern of A. The out-of-place alternative is decompress.\n\nnote: Note\nIn-place decompression is faster when A isa SparseMatrixCSC.\n\nCompression means summing either the columns or the rows of A which share the same color. It is done by calling compress.\n\nFor :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).\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> A = sparse([\n 0 0 4 6 0 9\n 1 0 0 0 7 0\n 0 2 0 0 8 0\n 0 3 5 0 0 0\n ]);\n\njulia> result = coloring(A, ColoringProblem(), GreedyColoringAlgorithm());\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\njulia> B = compress(A, result)\n4×3 Matrix{Int64}:\n 6 4 9\n 1 7 0\n 2 8 0\n 3 5 0\n\njulia> A2 = similar(A);\n\njulia> decompress!(A2, B, result)\n4×6 SparseMatrixCSC{Int64, Int64} with 9 stored entries:\n ⋅ ⋅ 4 6 ⋅ 9\n 1 ⋅ ⋅ ⋅ 7 ⋅\n ⋅ 2 ⋅ ⋅ 8 ⋅\n ⋅ 3 5 ⋅ ⋅ ⋅\n\njulia> A2 == A\ntrue\n\nSee also\n\nColoringProblem\nAbstractColoringResult\n\n\n\n\n\n","category":"function"},{"location":"api/#SparseMatrixColorings.decompress_single_color!","page":"API reference","title":"SparseMatrixColorings.decompress_single_color!","text":"decompress_single_color!(\n A::AbstractMatrix, b::AbstractVector, c::Integer,\n result::AbstractColoringResult, [uplo=:F]\n)\n\nDecompress 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).\n\nIf 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).\nIf 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).\nIf result comes from a :symmetric structure with :column partition, this will update the coefficients of A whose value is deduced from color c.\n\nwarning: Warning\nThis function will only update some coefficients of A, without resetting the rest to zero.\n\nFor :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).\n\nExample\n\njulia> using SparseMatrixColorings, SparseArrays\n\njulia> A = sparse([\n 0 0 4 6 0 9\n 1 0 0 0 7 0\n 0 2 0 0 8 0\n 0 3 5 0 0 0\n ]);\n\njulia> result = coloring(A, ColoringProblem(), GreedyColoringAlgorithm());\n\njulia> collect.(column_groups(result))\n3-element Vector{Vector{Int64}}:\n [1, 2, 4]\n [3, 5]\n [6]\n\njulia> B = compress(A, result)\n4×3 Matrix{Int64}:\n 6 4 9\n 1 7 0\n 2 8 0\n 3 5 0\n\njulia> A2 = similar(A); A2 .= 0;\n\njulia> decompress_single_color!(A2, B[:, 2], 2, result)\n4×6 SparseMatrixCSC{Int64, Int64} with 9 stored entries:\n ⋅ ⋅ 4 0 ⋅ 0\n 0 ⋅ ⋅ ⋅ 7 ⋅\n ⋅ 0 ⋅ ⋅ 8 ⋅\n ⋅ 0 5 ⋅ ⋅ ⋅\n\njulia> A2[:, [3, 5]] == A[:, [3, 5]]\ntrue\n\nSee also\n\nColoringProblem\nAbstractColoringResult\ndecompress!\n\n\n\n\n\n","category":"function"},{"location":"api/#Orders","page":"API reference","title":"Orders","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"AbstractOrder\nNaturalOrder\nRandomOrder\nLargestFirst\nSmallestLast\nIncidenceDegree\nDynamicLargestFirst\nDynamicDegreeBasedOrder","category":"page"},{"location":"api/#SparseMatrixColorings.AbstractOrder","page":"API reference","title":"SparseMatrixColorings.AbstractOrder","text":"AbstractOrder\n\nAbstract supertype for the vertex order used inside GreedyColoringAlgorithm.\n\nIn this algorithm, the rows and columns of a matrix form a graph, and the vertices are colored one after the other in a greedy fashion. Depending on how the vertices are ordered, the number of colors necessary may vary.\n\nOptions\n\nNaturalOrder\nRandomOrder\nLargestFirst\nIncidenceDegree (experimental)\nSmallestLast (experimental)\nDynamicLargestFirst (experimental)\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.NaturalOrder","page":"API reference","title":"SparseMatrixColorings.NaturalOrder","text":"NaturalOrder()\n\nInstance of AbstractOrder which sorts vertices using their index in the provided graph.\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.RandomOrder","page":"API reference","title":"SparseMatrixColorings.RandomOrder","text":"RandomOrder(rng=default_rng())\n\nInstance of AbstractOrder which sorts vertices using a random permutation.\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.LargestFirst","page":"API reference","title":"SparseMatrixColorings.LargestFirst","text":"LargestFirst()\n\nInstance of AbstractOrder which sorts vertices using their degree in the provided graph: the largest degree comes first.\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.SmallestLast","page":"API reference","title":"SparseMatrixColorings.SmallestLast","text":"SmallestLast()\n\nInstance of AbstractOrder which sorts vertices from highest to lowest using the dynamic back degree.\n\ndanger: Danger\nThis order is still experimental and needs more tests, correctness is not yet guaranteed.\n\nSee also\n\nDynamicDegreeBasedOrder\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.IncidenceDegree","page":"API reference","title":"SparseMatrixColorings.IncidenceDegree","text":"IncidenceDegree()\n\nInstance of AbstractOrder which sorts vertices from lowest to highest using the dynamic back degree.\n\ndanger: Danger\nThis order is still experimental and needs more tests, correctness is not yet guaranteed.\n\nSee also\n\nDynamicDegreeBasedOrder\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.DynamicLargestFirst","page":"API reference","title":"SparseMatrixColorings.DynamicLargestFirst","text":"DynamicLargestFirst()\n\nInstance of AbstractOrder which sorts vertices from lowest to highest using the dynamic forward degree.\n\ndanger: Danger\nThis order is still experimental and needs more tests, correctness is not yet guaranteed.\n\nSee also\n\nDynamicDegreeBasedOrder\n\n\n\n\n\n","category":"type"},{"location":"api/#SparseMatrixColorings.DynamicDegreeBasedOrder","page":"API reference","title":"SparseMatrixColorings.DynamicDegreeBasedOrder","text":"DynamicDegreeBasedOrder{degtype,direction}\n\nInstance of AbstractOrder which sorts vertices using a dynamically computed degree.\n\ndanger: Danger\nThis order is still experimental and needs more tests, correctness is not yet guaranteed.\n\nType parameters\n\ndegtype::Symbol: can be :forward (for the forward degree) or :back (for the back degree)\ndirection::Symbol: can be :low2high (if the order is defined from lowest to highest, i.e. 1 to n) or :high2low (if the order is defined from highest to lowest, i.e. n to 1)\n\nConcrete variants\n\nIncidenceDegree\nSmallestLast\nDynamicLargestFirst\n\nReferences\n\nColPack: Software for graph coloring and related problems in scientific computing, Gebremedhin et al. (2013), Section 5\n\n\n\n\n\n","category":"type"},{"location":"dev/#Internals","page":"Internals","title":"Internals","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"CollapsedDocStrings = true\nCurrentModule = SparseMatrixColorings","category":"page"},{"location":"dev/","page":"Internals","title":"Internals","text":"The docstrings on this page describe internals, they are not part of the public API.","category":"page"},{"location":"dev/#Graph-storage","page":"Internals","title":"Graph storage","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.SparsityPatternCSC\nSparseMatrixColorings.AdjacencyGraph\nSparseMatrixColorings.BipartiteGraph\nSparseMatrixColorings.vertices\nSparseMatrixColorings.neighbors\ntranspose","category":"page"},{"location":"dev/#SparseMatrixColorings.SparsityPatternCSC","page":"Internals","title":"SparseMatrixColorings.SparsityPatternCSC","text":"SparsityPatternCSC{Ti<:Integer}\n\nStore a sparse matrix (in CSC) without its values, keeping only the pattern of nonzeros.\n\nFields\n\nCopied from SparseMatrixCSC:\n\nm::Int: number of rows\nn::Int: number of columns\ncolptr::Vector{Ti}: column j is in colptr[j]:(colptr[j+1]-1)\nrowval::Vector{Ti}: row indices of stored values\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.AdjacencyGraph","page":"Internals","title":"SparseMatrixColorings.AdjacencyGraph","text":"AdjacencyGraph{T}\n\nUndirected graph without self-loops representing the nonzeros of a symmetric matrix (typically a Hessian matrix).\n\nThe adjacency graph of a symmetric matrix A ∈ ℝ^{n × n} is G(A) = (V, E) where\n\nV = 1:n is the set of rows or columns i/j\n(i, j) ∈ E whenever A[i, j] ≠ 0 and i ≠ j\n\nConstructors\n\nAdjacencyGraph(A::SparseMatrixCSC)\n\nFields\n\nS::SparsityPatternCSC{T}\n\nReferences\n\nWhat Color Is Your Jacobian? SparsityPatternCSC Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.BipartiteGraph","page":"Internals","title":"SparseMatrixColorings.BipartiteGraph","text":"BipartiteGraph{T}\n\nUndirected bipartite graph representing the nonzeros of a non-symmetric matrix (typically a Jacobian matrix).\n\nThe bipartite graph of a matrix A ∈ ℝ^{m × n} is Gb(A) = (V₁, V₂, E) where\n\nV₁ = 1:m is the set of rows i\nV₂ = 1:n is the set of columns j\n(i, j) ∈ E whenever A[i, j] ≠ 0\n\nA 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).\n\nConstructors\n\nBipartiteGraph(A::SparseMatrixCSC; symmetric_pattern=false)\n\nWhen symmetric_pattern is true, this construction is more efficient.\n\nFields\n\nS1::SparsityPatternCSC{T}: maps vertices on side 1 to their neighbors\nS2::SparsityPatternCSC{T}: maps vertices on side 2 to their neighbors\n\nReferences\n\nWhat Color Is Your Jacobian? SparsityPatternCSC Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.vertices","page":"Internals","title":"SparseMatrixColorings.vertices","text":"vertices(bg::BipartiteGraph, Val(side))\n\nReturn the list of vertices of bg from the specified side as a range 1:n.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.neighbors","page":"Internals","title":"SparseMatrixColorings.neighbors","text":"neighbors(bg::BipartiteGraph, Val(side), v::Integer)\n\nReturn the neighbors of v (a vertex from the specified side, 1 or 2), in the graph bg.\n\n\n\n\n\n","category":"function"},{"location":"dev/#Base.transpose","page":"Internals","title":"Base.transpose","text":"transpose(S::SparsityPatternCSC)\n\nReturn a SparsityPatternCSC corresponding to the transpose of S.\n\n\n\n\n\n","category":"function"},{"location":"dev/#Low-level-coloring","page":"Internals","title":"Low-level coloring","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.partial_distance2_coloring\nSparseMatrixColorings.symmetric_coefficient\nSparseMatrixColorings.star_coloring\nSparseMatrixColorings.acyclic_coloring\nSparseMatrixColorings.group_by_color\nSparseMatrixColorings.StarSet\nSparseMatrixColorings.TreeSet","category":"page"},{"location":"dev/#SparseMatrixColorings.partial_distance2_coloring","page":"Internals","title":"SparseMatrixColorings.partial_distance2_coloring","text":"partial_distance2_coloring(bg::BipartiteGraph, ::Val{side}, order::AbstractOrder)\n\nCompute a distance-2 coloring of the given side (1 or 2) in the bipartite graph bg and return a vector of integer colors.\n\nA distance-2 coloring is such that two vertices have different colors if they are at distance at most 2.\n\nThe vertices are colored in a greedy fashion, following the order supplied.\n\nSee also\n\nBipartiteGraph\nAbstractOrder\n\nReferences\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005), Algorithm 3.2\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.symmetric_coefficient","page":"Internals","title":"SparseMatrixColorings.symmetric_coefficient","text":"symmetric_coefficient(\n i::Integer, j::Integer,\n color::AbstractVector{<:Integer},\n star_set::StarSet\n)\n\nReturn the indices (k, c) such that A[i, j] = B[k, c], where A is the uncompressed symmetric matrix and B is the column-compressed matrix.\n\nThis function corresponds to algorithm DirectRecover2 in the paper.\n\nReferences\n\nEfficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009), Figure 3\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.star_coloring","page":"Internals","title":"SparseMatrixColorings.star_coloring","text":"star_coloring(g::AdjacencyGraph, order::AbstractOrder)\n\nCompute a star coloring of all vertices in the adjacency graph g and return a tuple (color, star_set), where\n\ncolor is the vector of integer colors\nstar_set is a StarSet encoding the set of 2-colored stars\n\nA star coloring is a distance-1 coloring such that every path on 4 vertices uses at least 3 colors.\n\nThe vertices are colored in a greedy fashion, following the order supplied.\n\nSee also\n\nAdjacencyGraph\nAbstractOrder\n\nReferences\n\nNew Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007), Algorithm 4.1\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.acyclic_coloring","page":"Internals","title":"SparseMatrixColorings.acyclic_coloring","text":"acyclic_coloring(g::AdjacencyGraph, order::AbstractOrder)\n\nCompute an acyclic coloring of all vertices in the adjacency graph g and return a tuple (color, tree_set), where\n\ncolor is the vector of integer colors\ntree_set is a TreeSet encoding the set of 2-colored trees\n\nAn acyclic coloring is a distance-1 coloring with the further restriction that every cycle uses at least 3 colors.\n\nThe vertices are colored in a greedy fashion, following the order supplied.\n\nSee also\n\nAdjacencyGraph\nAbstractOrder\n\nReferences\n\nNew Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007), Algorithm 3.1\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.group_by_color","page":"Internals","title":"SparseMatrixColorings.group_by_color","text":"group_by_color(color::Vector{Int})\n\nCreate a color-indexed vector group such that i ∈ group[c] iff color[i] == c.\n\nAssumes the colors are contiguously numbered from 1 to some cmax.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.StarSet","page":"Internals","title":"SparseMatrixColorings.StarSet","text":"StarSet\n\nEncode a set of 2-colored stars resulting from the star_coloring algorithm.\n\nFields\n\nstar::Dict{Tuple{Int64, Int64}, Int64}: a mapping from edges (pair of vertices) to their star index\nhub::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)\nspokes::Vector{Vector{Int64}}: a mapping from star indices to the vector of their spokes\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.TreeSet","page":"Internals","title":"SparseMatrixColorings.TreeSet","text":"TreeSet\n\nEncode a set of 2-colored trees resulting from the acyclic_coloring algorithm.\n\nFields\n\nforest::DataStructures.DisjointSets{Tuple{Int64, Int64}}: a forest of two-colored trees\n\n\n\n\n\n","category":"type"},{"location":"dev/#Concrete-coloring-results","page":"Internals","title":"Concrete coloring results","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.ColumnColoringResult\nSparseMatrixColorings.RowColoringResult\nSparseMatrixColorings.StarSetColoringResult\nSparseMatrixColorings.TreeSetColoringResult\nSparseMatrixColorings.LinearSystemColoringResult\nSparseMatrixColorings.BicoloringResult\nSparseMatrixColorings.remap_colors","category":"page"},{"location":"dev/#SparseMatrixColorings.ColumnColoringResult","page":"Internals","title":"SparseMatrixColorings.ColumnColoringResult","text":"struct ColumnColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.BipartiteGraph, V} <: AbstractColoringResult{:nonsymmetric, :column, :direct}\n\nStorage for the result of a column coloring with direct decompression.\n\nFields\n\nA::AbstractMatrix: matrix that was colored\nbg::SparseMatrixColorings.BipartiteGraph: bipartite graph that was used for coloring\ncolor::Vector{Int64}: one integer color for each column or row (depending on partition)\ngroup::Any: color groups for columns or rows (depending on partition)\ncompressed_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]]\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.RowColoringResult","page":"Internals","title":"SparseMatrixColorings.RowColoringResult","text":"struct RowColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.BipartiteGraph, V} <: AbstractColoringResult{:nonsymmetric, :row, :direct}\n\nStorage for the result of a row coloring with direct decompression.\n\nFields\n\nSee the docstring of ColumnColoringResult.\n\nA::AbstractMatrix\nbg::SparseMatrixColorings.BipartiteGraph\ncolor::Vector{Int64}\ngroup::Any\ncompressed_indices::Vector{Int64}\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.StarSetColoringResult","page":"Internals","title":"SparseMatrixColorings.StarSetColoringResult","text":"struct StarSetColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V} <: AbstractColoringResult{:symmetric, :column, :direct}\n\nStorage for the result of a symmetric coloring with direct decompression.\n\nFields\n\nSee the docstring of ColumnColoringResult.\n\nA::AbstractMatrix\nag::SparseMatrixColorings.AdjacencyGraph\ncolor::Vector{Int64}\ngroup::Any\nstar_set::SparseMatrixColorings.StarSet\ncompressed_indices::Vector{Int64}\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.TreeSetColoringResult","page":"Internals","title":"SparseMatrixColorings.TreeSetColoringResult","text":"struct TreeSetColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V, R} <: AbstractColoringResult{:symmetric, :column, :substitution}\n\nStorage for the result of a symmetric coloring with decompression by substitution.\n\nFields\n\nSee the docstring of ColumnColoringResult.\n\nA::AbstractMatrix\nag::SparseMatrixColorings.AdjacencyGraph\ncolor::Vector{Int64}\ngroup::Any\nvertices_by_tree::Vector{Vector{Int64}}\nreverse_bfs_orders::Vector{Vector{Tuple{Int64, Int64}}}\ndiagonal_indices::Vector{Int64}\ndiagonal_nzind::Vector{Int64}\nlower_triangle_offsets::Vector{Int64}\nupper_triangle_offsets::Vector{Int64}\nbuffer::Vector\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.LinearSystemColoringResult","page":"Internals","title":"SparseMatrixColorings.LinearSystemColoringResult","text":"struct LinearSystemColoringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, V, R, F} <: AbstractColoringResult{:symmetric, :column, :substitution}\n\nStorage for the result of a symmetric coloring with any decompression.\n\nFields\n\nSee the docstring of ColumnColoringResult.\n\nA::AbstractMatrix\nag::SparseMatrixColorings.AdjacencyGraph\ncolor::Vector{Int64}\ngroup::Any\nstrict_upper_nonzero_inds::Vector{Tuple{Int64, Int64}}\nstrict_upper_nonzeros_A::Vector\nT_factorization::Any\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.BicoloringResult","page":"Internals","title":"SparseMatrixColorings.BicoloringResult","text":"struct BicoloringResult{M<:(AbstractMatrix), G<:SparseMatrixColorings.AdjacencyGraph, decompression, V, SR<:AbstractColoringResult{:symmetric, :column, decompression}, R} <: AbstractColoringResult{:nonsymmetric, :bidirectional, decompression}\n\nStorage for the result of a bidirectional coloring with direct or substitution decompression, based on the symmetric coloring of a 2x2 block matrix.\n\nFields\n\nA::AbstractMatrix: matrix that was colored\nabg::SparseMatrixColorings.AdjacencyGraph: adjacency graph that was used for coloring (constructed from the bipartite graph)\ncolumn_color::Vector{Int64}: one integer color for each column\nrow_color::Vector{Int64}: one integer color for each row\ncolumn_group::Any: color groups for columns\nrow_group::Any: color groups for rows\nsymmetric_result::AbstractColoringResult{:symmetric, :column}: result for the coloring of the symmetric 2x2 block matrix\ncol_color_ind::Dict{Int64, Int64}: column color to index\nrow_color_ind::Dict{Int64, Int64}: row color to index\nBr_and_Bc::Matrix: combination of Br and Bc (almost a concatenation up to color remapping)\nlarge_colptr::Vector{Int64}: CSC storage of A_and_noAᵀ -colptr`\nlarge_rowval::Vector{Int64}: CSC storage of A_and_noAᵀ -rowval`\n\nSee also\n\nAbstractColoringResult\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.remap_colors","page":"Internals","title":"SparseMatrixColorings.remap_colors","text":"remap_colors(color::Vector{Int})\n\nRenumber the colors in color using their index in the vector sort(unique(color)), so that they are forced to go from 1 to some cmax contiguously.\n\nReturn a tuple (remapped_colors, color_to_ind) such that remapped_colors is a vector containing the renumbered colors and color_to_ind is a dictionary giving the translation between old and new color numberings.\n\nFor all vertex indices i we have:\n\nremapped_color[i] = color_to_ind[color[i]]\n\n\n\n\n\n","category":"function"},{"location":"dev/#Testing","page":"Internals","title":"Testing","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.directly_recoverable_columns\nSparseMatrixColorings.symmetrically_orthogonal_columns\nSparseMatrixColorings.structurally_orthogonal_columns\nSparseMatrixColorings.structurally_biorthogonal\nSparseMatrixColorings.valid_dynamic_order","category":"page"},{"location":"dev/#SparseMatrixColorings.directly_recoverable_columns","page":"Internals","title":"SparseMatrixColorings.directly_recoverable_columns","text":"directly_recoverable_columns(\n A::AbstractMatrix, color::AbstractVector{<:Integer}\n verbose=false\n)\n\nReturn 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.\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\nReferences\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.symmetrically_orthogonal_columns","page":"Internals","title":"SparseMatrixColorings.symmetrically_orthogonal_columns","text":"symmetrically_orthogonal_columns(\n A::AbstractMatrix, color::AbstractVector{<:Integer};\n verbose=false\n)\n\nReturn 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.\n\nA partition of the columns of a symmetric matrix A is symmetrically orthogonal if, for every nonzero element A[i, j], either of the following statements holds:\n\nthe group containing the column A[:, j] has no other column with a nonzero in row i\nthe group containing the column A[:, i] has no other column with a nonzero in row j\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\nReferences\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.structurally_orthogonal_columns","page":"Internals","title":"SparseMatrixColorings.structurally_orthogonal_columns","text":"structurally_orthogonal_columns(\n A::AbstractMatrix, color::AbstractVector{<:Integer};\n verbose=false\n)\n\nReturn true if coloring the columns of the matrix A with the vector color results in a partition that is structurally orthogonal, and false otherwise.\n\nA 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.\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\nReferences\n\nWhat Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.structurally_biorthogonal","page":"Internals","title":"SparseMatrixColorings.structurally_biorthogonal","text":"structurally_biorthogonal(\n A::AbstractMatrix, row_color::AbstractVector{<:Integer}, column_color::AbstractVector{<:Integer};\n verbose=false\n)\n\nReturn true if bicoloring of the matrix A with the vectors row_color and column_color results in a bipartition that is structurally biorthogonal, and false otherwise.\n\nA bipartition of the rows and columns of a matrix A is structurally biorthogonal if, for every nonzero element A[i, j], either of the following statements holds:\n\nthe group containing the column A[:, j] has no other column with a nonzero in row i\nthe group containing the row A[i, :] has no other row with a nonzero in column j\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.valid_dynamic_order","page":"Internals","title":"SparseMatrixColorings.valid_dynamic_order","text":"valid_dynamic_order(g::AdjacencyGraph, π::AbstractVector{Int}, order::DynamicDegreeBasedOrder)\nvalid_dynamic_order(bg::AdjacencyGraph, ::Val{side}, π::AbstractVector{Int}, order::DynamicDegreeBasedOrder)\n\nCheck that a permutation π corresponds to a valid application of a DynamicDegreeBasedOrder.\n\nThis is done by checking, for each ordered vertex, that its back- or forward-degree was the smallest or largest among the remaining vertices (the specifics depend on the order parameters).\n\nwarning: Warning\nThis function is not coded with efficiency in mind, it is designed for small-scale tests.\n\n\n\n\n\n","category":"function"},{"location":"dev/#Matrix-handling","page":"Internals","title":"Matrix handling","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.respectful_similar\nSparseMatrixColorings.matrix_versions\nSparseMatrixColorings.same_pattern","category":"page"},{"location":"dev/#SparseMatrixColorings.respectful_similar","page":"Internals","title":"SparseMatrixColorings.respectful_similar","text":"respectful_similar(A::AbstractMatrix)\nrespectful_similar(A::AbstractMatrix, ::Type{T})\n\nLike Base.similar but returns a transpose or adjoint when A is a transpose or adjoint.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.matrix_versions","page":"Internals","title":"SparseMatrixColorings.matrix_versions","text":"matrix_versions(A::AbstractMatrix)\n\nReturn various versions of the same matrix:\n\ndense and sparse\ntranspose and adjoint\n\nUsed for internal testing.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.same_pattern","page":"Internals","title":"SparseMatrixColorings.same_pattern","text":"same_pattern(A, B)\n\nPerform a partial equality check on the sparsity patterns of A and B:\n\nif the return is true, they might have the same sparsity pattern but we're not sure\nif the return is false, they definitely don't have the same sparsity pattern\n\n\n\n\n\n","category":"function"},{"location":"dev/#Visualization","page":"Internals","title":"Visualization","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.show_colors","category":"page"},{"location":"dev/#SparseMatrixColorings.show_colors","page":"Internals","title":"SparseMatrixColorings.show_colors","text":"show_colors(result; kwargs...)\n\nCreate a visualization for an AbstractColoringResult, with the help of the the JuliaImages ecosystem.\n\nFor :column or :row colorings, it returns a tuple (A_img, B_img).\nFor :bidirectional colorings, it returns a tuple (A_img, Br_img, Bc_img).\n\nwarning: Warning\nThis function is implemented in a package extension, using it requires loading Colors.jl.\n\nKeyword arguments\n\ncolorscheme: colors used for non-zero matrix entries. This can be a vector of Colorants or a subsampled scheme from ColorSchemes.jl.\nbackground::Colorant: color used for zero matrix entries and pad. Defaults to RGBA(0,0,0,0), a transparent background.\nscale::Int: scale the size of matrix entries to scale × scale pixels. Defaults to 1. \npad::Int: set padding between matrix entries, in pixels. Defaults to 0. \n\nFor a matrix of size (n, m), the resulting output will be of size (n * (scale + pad) + pad, m * (scale + pad) + pad).\n\n\n\n\n\n","category":"function"},{"location":"dev/#Examples","page":"Internals","title":"Examples","text":"","category":"section"},{"location":"dev/","page":"Internals","title":"Internals","text":"SparseMatrixColorings.Example\nSparseMatrixColorings.what_fig_41\nSparseMatrixColorings.what_fig_61\nSparseMatrixColorings.efficient_fig_1\nSparseMatrixColorings.efficient_fig_4","category":"page"},{"location":"dev/#SparseMatrixColorings.Example","page":"Internals","title":"SparseMatrixColorings.Example","text":"struct Example{TA<:(AbstractMatrix), TB<:(AbstractMatrix)}\n\nExample coloring problem from one of our reference articles.\n\nUsed for internal testing.\n\nFields\n\nA::AbstractMatrix: decompressed matrix\nB::AbstractMatrix: column-compressed matrix\ncolor::Vector{Int64}: vector of colors\n\n\n\n\n\n","category":"type"},{"location":"dev/#SparseMatrixColorings.what_fig_41","page":"Internals","title":"SparseMatrixColorings.what_fig_41","text":"what_fig_41()\n\nConstruct an Example from Figure 4.1 of \"What color is your Jacobian?\", where the nonzero entries are filled with unique values.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.what_fig_61","page":"Internals","title":"SparseMatrixColorings.what_fig_61","text":"what_fig_61()\n\nConstruct an Example from Figure 6.1 of \"What color is your Jacobian?\", where the nonzero entries are filled with unique values.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.efficient_fig_1","page":"Internals","title":"SparseMatrixColorings.efficient_fig_1","text":"efficient_fig_1()\n\nConstruct an Example from Figure 1 of \"Efficient computation of sparse hessians using coloring and AD\", where the nonzero entries are filled with unique values.\n\n\n\n\n\n","category":"function"},{"location":"dev/#SparseMatrixColorings.efficient_fig_4","page":"Internals","title":"SparseMatrixColorings.efficient_fig_4","text":"efficient_fig_4()\n\nConstruct an Example from Figure 4 of \"Efficient computation of sparse hessians using coloring and AD\", where the nonzero entries are filled with unique values.\n\n\n\n\n\n","category":"function"},{"location":"#SparseMatrixColorings.jl","page":"Home","title":"SparseMatrixColorings.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"(Image: Build Status) (Image: Stable Documentation) (Image: Dev Documentation) (Image: Coverage) (Image: Code Style: Blue) (Image: DOI)","category":"page"},{"location":"","page":"Home","title":"Home","text":"Coloring algorithms for sparse Jacobian and Hessian matrices.","category":"page"},{"location":"#Getting-started","page":"Home","title":"Getting started","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"To install this package, run the following in a Julia Pkg REPL:","category":"page"},{"location":"","page":"Home","title":"Home","text":"pkg> add SparseMatrixColorings","category":"page"},{"location":"#Background","page":"Home","title":"Background","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The algorithms implemented in this package are taken from the following articles:","category":"page"},{"location":"","page":"Home","title":"Home","text":"What Color Is Your Jacobian? Graph Coloring for Computing Derivatives, Gebremedhin et al. (2005)\nNew Acyclic and Star Coloring Algorithms with Application to Computing Hessians, Gebremedhin et al. (2007)\nEfficient Computation of Sparse Hessians Using Coloring and Automatic Differentiation, Gebremedhin et al. (2009)\nColPack: Software for graph coloring and related problems in scientific computing, Gebremedhin et al. (2013)","category":"page"},{"location":"","page":"Home","title":"Home","text":"Some parts of the articles (like definitions) are thus copied verbatim in the documentation.","category":"page"},{"location":"#Alternatives","page":"Home","title":"Alternatives","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"ColPack.jl: a Julia interface to the C++ library ColPack\nSparseDiffTools.jl: contains Julia implementations of some coloring algorithms","category":"page"},{"location":"#Citing","page":"Home","title":"Citing","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"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.","category":"page"}] } diff --git a/dev/vis/index.html b/dev/vis/index.html index 4c433cf..44f269b 100644 --- a/dev/vis/index.html +++ b/dev/vis/index.html @@ -40,7 +40,7 @@ problem = ColoringProblem(; structure=:nonsymmetric, partition=:column) algo = GreedyColoringAlgorithm(; decompression=:direct) result = coloring(S, problem, algo) -show_colors(result; scale=5, pad=1)[1]

Instead of the default distinguishable_colors from Colors.jl, one can subsample a continuous colorscheme from ColorSchemes.jl:

ncolors = maximum(column_colors(result)) # for partition=:column
+show_colors(result; scale=5, pad=1)[1]

Instead of the default distinguishable_colors from Colors.jl, one can subsample a continuous colorscheme from ColorSchemes.jl:

ncolors = maximum(column_colors(result)) # for partition=:column
 colorscheme = get(ColorSchemes.rainbow, range(0.0, 1.0, length=ncolors))
-show_colors(result; colorscheme=colorscheme, scale=5, pad=1)[1]

Saving images

The resulting image can be saved to a variety of formats, like PNG. The scale and pad parameters determine the number of pixels, and thus the size of the file.

A_img, _ = show_colors(result, scale=5)
-save("coloring.png", A_img)

Refer to the JuliaImages documentation on saving for more information.

+show_colors(result; colorscheme=colorscheme, scale=5, pad=1)[1]

Saving images

The resulting image can be saved to a variety of formats, like PNG. The scale and pad parameters determine the number of pixels, and thus the size of the file.

A_img, _ = show_colors(result, scale=5)
+save("coloring.png", A_img)

Refer to the JuliaImages documentation on saving for more information.