Permute

In-place permutation kernels for vectors and matrices, dense and sparse.

permute_vector!(;
    destination::AbstractVector,
    source::AbstractVector,
    permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Fill destination such that destination[index] == source[permutation[index]] for every index . If progress is given, advance it by length(source) once after filling is complete.

The caller must pre-allocate destination with the same length as source . This function never allocates the destination.

source = [10, 20, 30, 40]
destination = similar(source)
permutation = [4, 2, 1, 3]
permute_vector!(; destination, source, permutation)
@assert destination == [40, 20, 10, 30]

# output

permute_sparse_vector!(;
    destination_nzind::AbstractVector{<:Integer},
    destination_nzval::AbstractVector,
    source::SparseVector,
    inverse_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Fill the (nzind, nzval) backing pair of a sparse vector destination such that destination[inverse_permutation[index]] == source[index] for every index . Destination indices and values are written in ascending nzind order so the result is a valid SparseVector backing pair. If progress is given, advance it by length(source) once after filling is complete.

Use permute_sparse_vector_buffers! when the source is held as raw (nzind, nzval) buffers rather than a SparseVector .

using SparseArrays

source = sparsevec([1, 3, 5], [10.0, 30.0, 50.0], 5)
inverse_permutation = [5, 4, 3, 2, 1]
destination_nzind = Vector{Int}(undef, nnz(source))
destination_nzval = Vector{Float64}(undef, nnz(source))
permute_sparse_vector!(; destination_nzind, destination_nzval, source, inverse_permutation)
destination = SparseVector(length(source), destination_nzind, destination_nzval)
@assert destination == sparsevec([1, 3, 5], [50.0, 30.0, 10.0], 5)

# output

permute_sparse_vector_buffers!(;
    destination_nzind::AbstractVector{<:Integer},
    destination_nzval::Maybe{AbstractVector},
    source_length::Integer,
    source_nzind::AbstractVector{<:Integer},
    source_nzval::Maybe{AbstractVector},
    inverse_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Like permute_sparse_vector! , but takes the source (nzind, nzval) backing pair and the dense source_length directly. Pass nothing for both source_nzval and destination_nzval to permute an all-true boolean sparse vector that stores no values.

permute_dense_matrix_rows!(;
    destination::AbstractMatrix,
    source::AbstractMatrix,
    rows_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Fill destination such that destination[destination_row, :] == source[rows_permutation[destination_row], :] for every destination_row . Parallelized per destination column. If progress is given, advance it by n_rows per destination column completed.

source = Float64[1 2; 3 4; 5 6]
destination = similar(source)
rows_permutation = [3, 1, 2]
permute_dense_matrix_rows!(; destination, source, rows_permutation)
@assert destination == [5.0 6.0; 1.0 2.0; 3.0 4.0]

# output

permute_dense_matrix_columns!(;
    destination::AbstractMatrix,
    source::AbstractMatrix,
    columns_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Fill destination such that destination[:, destination_column] == source[:, columns_permutation[destination_column]] for every destination_column . Parallelized per destination column. If progress is given, advance it by n_rows per destination column completed.

source = Float64[1 2 3; 4 5 6; 7 8 9]
destination = similar(source)
columns_permutation = [3, 1, 2]
permute_dense_matrix_columns!(; destination, source, columns_permutation)
@assert destination == [3.0 1.0 2.0; 6.0 4.0 5.0; 9.0 7.0 8.0]

# output

permute_dense_matrix_both!(;
    destination::AbstractMatrix,
    source::AbstractMatrix,
    rows_permutation::AbstractVector{<:Integer},
    columns_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Fill destination such that destination[destination_row, destination_column] == source[rows_permutation[destination_row], columns_permutation[destination_column]] for every (destination_row, destination_column) . Single-pass; parallelized per destination column. If progress is given, advance it by n_rows per destination column completed.

source = Float64[1 2 3; 4 5 6]
destination = similar(source)
rows_permutation = [2, 1]
columns_permutation = [3, 1, 2]
permute_dense_matrix_both!(; destination, source, rows_permutation, columns_permutation)
@assert destination == [6.0 4.0 5.0; 3.0 1.0 2.0]

# output

permute_sparse_matrix_rows!(;
    destination_colptr::AbstractVector{<:Integer},
    destination_rowval::AbstractVector{<:Integer},
    destination_nzval::AbstractVector,
    source::SparseMatrixCSC,
    inverse_rows_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Fill the (colptr, rowval, nzval) backing triplet of a sparse destination such that destination[inverse_rows_permutation[source_row], :] == source[source_row, :] for every source_row . The destination has the same colptr as the source. Parallelized per destination column. If progress is given, advance it by the column nnz per column completed.

Use permute_sparse_matrix_rows_buffers! when the source is held as raw (colptr, rowval, nzval) buffers rather than a SparseMatrixCSC .

using SparseArrays

source = sparse([1.0 2.0; 3.0 0.0; 0.0 4.0])
destination_colptr = Vector{Int}(undef, size(source, 2) + 1)
destination_rowval = Vector{Int}(undef, nnz(source))
destination_nzval = Vector{Float64}(undef, nnz(source))
inverse_rows_permutation = [2, 3, 1]
permute_sparse_matrix_rows!(;
    destination_colptr,
    destination_rowval,
    destination_nzval,
    source,
    inverse_rows_permutation,
)
destination = SparseMatrixCSC(
    size(source, 1),
    size(source, 2),
    destination_colptr,
    destination_rowval,
    destination_nzval,
)
@assert destination == sparse([0.0 4.0; 1.0 2.0; 3.0 0.0])

# output

permute_sparse_matrix_rows_buffers!(;
    destination_colptr::AbstractVector{<:Integer},
    destination_rowval::AbstractVector{<:Integer},
    destination_nzval::Maybe{AbstractVector},
    source_n_rows::Integer,
    source_colptr::AbstractVector{<:Integer},
    source_rowval::AbstractVector{<:Integer},
    source_nzval::Maybe{AbstractVector},
    inverse_rows_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Like permute_sparse_matrix_rows! , but takes the source (colptr, rowval, nzval) backing triplet and the source_n_rows directly. Pass nothing for both source_nzval and destination_nzval to permute an all-true boolean sparse matrix that stores no values.

permute_sparse_matrix_columns!(;
    destination_colptr::AbstractVector{<:Integer},
    destination_rowval::AbstractVector{<:Integer},
    destination_nzval::AbstractVector,
    source::SparseMatrixCSC,
    columns_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Fill the (colptr, rowval, nzval) backing triplet of a sparse destination such that destination[:, destination_column] == source[:, columns_permutation[destination_column]] for every destination_column . Parallelized per destination column. If progress is given, advance it by the column nnz per destination column completed.

Use permute_sparse_matrix_columns_buffers! when the source is held as raw (colptr, rowval, nzval) buffers rather than a SparseMatrixCSC .

using SparseArrays

source = sparse([1.0 0.0 2.0; 0.0 3.0 0.0; 4.0 5.0 0.0])
destination_colptr = Vector{Int}(undef, size(source, 2) + 1)
destination_rowval = Vector{Int}(undef, nnz(source))
destination_nzval = Vector{Float64}(undef, nnz(source))
columns_permutation = [3, 1, 2]
permute_sparse_matrix_columns!(;
    destination_colptr,
    destination_rowval,
    destination_nzval,
    source,
    columns_permutation,
)
destination = SparseMatrixCSC(
    size(source, 1),
    size(source, 2),
    destination_colptr,
    destination_rowval,
    destination_nzval,
)
@assert destination == sparse([2.0 1.0 0.0; 0.0 0.0 3.0; 0.0 4.0 5.0])

# output

permute_sparse_matrix_columns_buffers!(;
    destination_colptr::AbstractVector{<:Integer},
    destination_rowval::AbstractVector{<:Integer},
    destination_nzval::Maybe{AbstractVector},
    source_n_rows::Integer,
    source_colptr::AbstractVector{<:Integer},
    source_rowval::AbstractVector{<:Integer},
    source_nzval::Maybe{AbstractVector},
    columns_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Like permute_sparse_matrix_columns! , but takes the source (colptr, rowval, nzval) backing triplet and the source_n_rows directly. Pass nothing for both source_nzval and destination_nzval to permute an all-true boolean sparse matrix that stores no values.

permute_sparse_matrix_both!(;
    destination_colptr::AbstractVector{<:Integer},
    destination_rowval::AbstractVector{<:Integer},
    destination_nzval::AbstractVector,
    source::SparseMatrixCSC,
    inverse_rows_permutation::AbstractVector{<:Integer},
    columns_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Fill the (colptr, rowval, nzval) backing triplet of a sparse destination such that destination[inverse_rows_permutation[source_row], destination_column] == source[source_row, columns_permutation[destination_column]] for every (source_row, destination_column) . Single-pass; parallelized per destination column. If progress is given, advance it by the column nnz per destination column completed.

Use permute_sparse_matrix_both_buffers! when the source is held as raw (colptr, rowval, nzval) buffers rather than a SparseMatrixCSC .

using SparseArrays

source = sparse([1.0 2.0 0.0; 0.0 3.0 4.0])
destination_colptr = Vector{Int}(undef, size(source, 2) + 1)
destination_rowval = Vector{Int}(undef, nnz(source))
destination_nzval = Vector{Float64}(undef, nnz(source))
inverse_rows_permutation = [2, 1]
columns_permutation = [3, 1, 2]
permute_sparse_matrix_both!(;
    destination_colptr,
    destination_rowval,
    destination_nzval,
    source,
    inverse_rows_permutation,
    columns_permutation,
)
destination = SparseMatrixCSC(
    size(source, 1),
    size(source, 2),
    destination_colptr,
    destination_rowval,
    destination_nzval,
)
@assert destination == sparse([4.0 0.0 3.0; 0.0 1.0 2.0])

# output

permute_sparse_matrix_both_buffers!(;
    destination_colptr::AbstractVector{<:Integer},
    destination_rowval::AbstractVector{<:Integer},
    destination_nzval::Maybe{AbstractVector},
    source_n_rows::Integer,
    source_colptr::AbstractVector{<:Integer},
    source_rowval::AbstractVector{<:Integer},
    source_nzval::Maybe{AbstractVector},
    inverse_rows_permutation::AbstractVector{<:Integer},
    columns_permutation::AbstractVector{<:Integer},
    progress::Maybe{Progress} = nothing,
)::Nothing

Like permute_sparse_matrix_both! , but takes the source (colptr, rowval, nzval) backing triplet and the source_n_rows directly. Pass nothing for both source_nzval and destination_nzval to permute an all-true boolean sparse matrix that stores no values.