CompressedSparseForm - Maple Help
For the best experience, we recommend viewing online help using Google Chrome or Microsoft Edge.

# Online Help

###### All Products    Maple    MapleSim

LinearAlgebra

 CompressedSparseForm
 compute compressed sparse row and column forms

 Calling Sequence CompressedSparseForm(A, opts)

Parameters

 A - sparse Matrix with hardware data type opts - optional equations controlling the details of the computation

Options

 • form = row or form = column
 This option determines whether the compressed sparse column form or the compressed sparse row form is returned. The default is compressed sparse column form.
 • output = CB or R or X or a list of these values
 If output is set to CB, then only CB is returned. Similarly for R and X. If a list of these values is selected, then Maple returns the corresponding values in that order, as an expression sequence. The default value is [CB, R, X]: return the sequence of all three Vectors.
 • cbbase = posint
 • rbase = posint
 These options determines at what number Maple starts numbering the rows and columns. The default is 1, corresponding to the standard Maple convention. Other values, in particular 0, are mainly useful if the result is passed to external code.
 The setting of cbbase changes the values in $\mathrm{CB}$: it changes the start of indexing into $R$ and $X$. The setting of rbase changes the values in $R$: it changes the start of indexing into $A$.
 • length0 = true or length0 = false
 Maple has no problems working with Vectors of length 0, but some external tools do. If length0 is set to false, and A has no nonzero entries, then Maple returns values pretending that the [1, 1] entry is stored and has value 0. This and the includediagonal and structuralsymmetry options below are the only cases in which X contains a zero value.
 • includediagonal = true or includediagonal = false
 If the includediagonal option is set to true, then Maple includes all diagonal entries in the result, even if their value is zero. If it is set to false (the default), then Maple omits all zero entries, including if they occur on the diagonal. The former is useful when preparing input for some external tools.
 • structuralsymmetry = true or structuralsymmetry = false
 If the structuralsymmetry option is set to true, then Maple ensures that, whenever a value ${A}_{i,j}$ is included in the result, then ${A}_{j,i}$ is also included, even if it is zero. If it is set to false (the default), then Maple does not do this. The former is useful when preparing input for some external tools.
 The structuralsymmetry option can only be used if A is a square Matrix.

Description

 • The CompressedSparseForm function computes either the compressed sparse row form or the compressed sparse column form of the input Matrix $A$, which needs to have one of the hardware data types. It thus performs the opposite function to FromCompressedSparseForm.
 • The compressed sparse column form of an $n$ by $m$ Matrix $A$ with $k$ nonzero entries consists of three Vectors, $\mathrm{CB}$, $R$, and $X$. These are obtained by sorting the $k$ nonzero entries of $A$ first by column, and then within each column sorting the entries by row. Now $X$ is the $k$-element Vector of these nonzero values in $A$ in this order, and $R$ is the $k$-element Vector of row indices at which these values occur. $\mathrm{CB}$ is an $n+1$-element Vector; ${\mathrm{CB}}_{i}$ is the index in both $X$ and $R$ where the $i$th column starts. We always have ${\mathrm{CB}}_{1}=1$ and ${\mathrm{CB}}_{n+1}=k+1$, so that the entries in column $i$ have indices ${\mathrm{CB}}_{i}$ up to, but not including, ${\mathrm{CB}}_{i+1}$. (If the $\mathrm{cbbase}$ option below is used, then ${\mathrm{CB}}_{1}=\mathrm{cbbase}$ and ${\mathrm{CB}}_{n+1}=k+\mathrm{cbbase}$ and a similar statement holds.)
 • The compressed sparse row form is very similar, but with the roles of rows and columns interchanged. Specifically, we first sort $A$ by row and then within each row by column; $X$ is still the nonzero values occurring in $A$. However, $R$ is the $k$-element Vector of column indices. Similarly, ${\mathrm{CB}}_{i}$ is the index in $X$ and $R$ where the $i$th row starts.
 • The compressed sparse forms are most useful for sparse Matrices. If $A$ does not have sparse storage (as determined by $\mathrm{rtable_option}\left(X,\mathrm{storage}\right)$ being either $\mathrm{sparse}$ or ${\mathrm{sparse}}_{\mathrm{upper}}$ or ${\mathrm{sparse}}_{\mathrm{lower}}$), then a sparse storage copy is made before determining the compressed sparse form.
 • If $A$ has any indexing functions (as determined by $\mathrm{rtable_indfns}\left(A\right)$), then these are bypassed when determining the compressed sparse row or column form: since CompressedSparseForm is a low-level command, Maple returns the compressed sparse form of the stored entries only. For example, if a Matrix is defined with option $\mathrm{shape}=\mathrm{symmetric}$ and $\mathrm{storage}={\mathrm{sparse}}_{\mathrm{upper}}$, then only one of each pair of off-diagonal entries will be represented in the compressed sparse form. However, if $A$ has indexing functions but no sparse storage, then the copy made to give it sparse storage, as explained above, typically gets rid of the indexing function and stores all nonzero entries.
 • The code for CompressedSparseForm relies on $A$ being a NAG-sparse Matrix (potentially after copying it to give it sparse storage); that is, its datatype as returned by rtable_options needs to be one of these values:
 $\mathrm{sfloat},\mathrm{complex}\left(\mathrm{sfloat}\right),{\mathrm{integer}}_{1},{\mathrm{integer}}_{2},{\mathrm{integer}}_{4},{\mathrm{integer}}_{8},{\mathrm{float}}_{4},{\mathrm{float}}_{8},{\mathrm{complex}}_{8}$

Examples

 > $\mathrm{with}\left(\mathrm{LinearAlgebra}\right):$

Let us examine the compressed sparse row and column form of an arbitrary matrix.

 > $m≔\mathrm{Matrix}\left(6,6,\left\{\left(1,2\right)=-81,\left(2,3\right)=-55,\left(2,4\right)=-15,\left(3,1\right)=-46,\left(3,3\right)=-17,\left(3,4\right)=99,\left(3,5\right)=-61,\left(4,2\right)=18,\left(4,5\right)=-78,\left(5,6\right)=22\right\},\mathrm{datatype}=\mathrm{integer}\left[4\right]\right)$
 ${m}{≔}\left[\begin{array}{cccccc}{0}& {-81}& {0}& {0}& {0}& {0}\\ {0}& {0}& {-55}& {-15}& {0}& {0}\\ {-46}& {0}& {-17}& {99}& {-61}& {0}\\ {0}& {18}& {0}& {0}& {-78}& {0}\\ {0}& {0}& {0}& {0}& {0}& {22}\\ {0}& {0}& {0}& {0}& {0}& {0}\end{array}\right]$ (1)
 > $\mathrm{CompressedSparseForm}\left(m\right)$
 $\left[\begin{array}{c}{1}\\ {2}\\ {4}\\ {6}\\ {8}\\ {10}\\ {11}\end{array}\right]{,}\left[\begin{array}{c}{3}\\ {1}\\ {4}\\ {2}\\ {3}\\ {2}\\ {3}\\ {3}\\ {4}\\ {5}\end{array}\right]{,}\left[\begin{array}{c}{-46}\\ {-81}\\ {18}\\ {-55}\\ {-17}\\ {-15}\\ {99}\\ {-61}\\ {-78}\\ {22}\end{array}\right]$ (2)
 > $\mathrm{CompressedSparseForm}\left(m,'\mathrm{form}=\mathrm{row}'\right)$
 $\left[\begin{array}{c}{1}\\ {2}\\ {4}\\ {8}\\ {10}\\ {11}\\ {11}\end{array}\right]{,}\left[\begin{array}{c}{2}\\ {3}\\ {4}\\ {1}\\ {3}\\ {4}\\ {5}\\ {2}\\ {5}\\ {6}\end{array}\right]{,}\left[\begin{array}{c}{-81}\\ {-55}\\ {-15}\\ {-46}\\ {-17}\\ {99}\\ {-61}\\ {18}\\ {-78}\\ {22}\end{array}\right]$ (3)

Setting $\mathrm{cbbase}=0$ causes the entries of $\mathrm{CB}$ to be reduced by 1.

 > $\mathrm{CompressedSparseForm}\left(m,'\mathrm{cbbase}'=0\right)$
 $\left[\begin{array}{c}{0}\\ {1}\\ {3}\\ {5}\\ {7}\\ {9}\\ {10}\end{array}\right]{,}\left[\begin{array}{c}{3}\\ {1}\\ {4}\\ {2}\\ {3}\\ {2}\\ {3}\\ {3}\\ {4}\\ {5}\end{array}\right]{,}\left[\begin{array}{c}{-46}\\ {-81}\\ {18}\\ {-55}\\ {-17}\\ {-15}\\ {99}\\ {-61}\\ {-78}\\ {22}\end{array}\right]$ (4)

Setting $\mathrm{rbase}=0$ causes the entries of $R$ to be reduced by 1.

 > $\mathrm{CompressedSparseForm}\left(m,'\mathrm{rbase}'=0\right)$
 $\left[\begin{array}{c}{1}\\ {2}\\ {4}\\ {6}\\ {8}\\ {10}\\ {11}\end{array}\right]{,}\left[\begin{array}{c}{2}\\ {0}\\ {3}\\ {1}\\ {2}\\ {1}\\ {2}\\ {2}\\ {3}\\ {4}\end{array}\right]{,}\left[\begin{array}{c}{-46}\\ {-81}\\ {18}\\ {-55}\\ {-17}\\ {-15}\\ {99}\\ {-61}\\ {-78}\\ {22}\end{array}\right]$ (5)

Using the $\mathrm{includediagonal}$ option ensures that all 6 diagonal entries are included, even though most of them are 0.

 > $\mathrm{CompressedSparseForm}\left(m,'\mathrm{includediagonal}'\right)$
 > $\mathrm{m2}≔\mathrm{Matrix}\left(\left[\left[0,1,0\right],\left[2,0,0\right],\left[3,0,4\right],\left[5,6,7\right]\right],'\mathrm{datatype}=\mathrm{float}'\right)$
 ${\mathrm{m2}}{≔}\left[\begin{array}{ccc}{0.}& {1.}& {0.}\\ {2.}& {0.}& {0.}\\ {3.}& {0.}& {4.}\\ {5.}& {6.}& {7.}\end{array}\right]$ (6)
 > $\mathrm{cb},r,x≔\mathrm{CompressedSparseForm}\left(\mathrm{m2}\right)$
 ${\mathrm{cb}}{,}{r}{,}{x}{≔}\left[\begin{array}{c}{1}\\ {4}\\ {6}\\ {8}\end{array}\right]{,}\left[\begin{array}{c}{2}\\ {3}\\ {4}\\ {1}\\ {4}\\ {3}\\ {4}\end{array}\right]{,}\left[\begin{array}{c}{2.}\\ {3.}\\ {5.}\\ {1.}\\ {6.}\\ {4.}\\ {7.}\end{array}\right]$ (7)

We can obtain the entries of $r$ corresponding to the second column as follows.

 > $\mathrm{column}≔2$
 ${\mathrm{column}}{≔}{2}$ (8)
 > $r\left[\mathrm{cb}\left[\mathrm{column}\right]..\mathrm{cb}\left[\mathrm{column}+1\right]-1\right]$
 $\left[\begin{array}{c}{1}\\ {4}\end{array}\right]$ (9)

Similarly for the entries of $x$.

 > $x\left[\mathrm{cb}\left[\mathrm{column}\right]..\mathrm{cb}\left[\mathrm{column}+1\right]-1\right]$
 $\left[\begin{array}{c}{1.}\\ {6.}\end{array}\right]$ (10)

We will omit the last row of $\mathrm{m2}$ and illustrate the includediagonal and structuralsymmetry options. First, this is what the result looks like without these options.

 > $\mathrm{m3}≔\mathrm{m2}\left[1..3\right]$
 ${\mathrm{m3}}{≔}\left[\begin{array}{ccc}{0.}& {1.}& {0.}\\ {2.}& {0.}& {0.}\\ {3.}& {0.}& {4.}\end{array}\right]$ (11)
 > $\mathrm{CompressedSparseForm}\left(\mathrm{m3}\right)$
 $\left[\begin{array}{c}{1}\\ {3}\\ {4}\\ {5}\end{array}\right]{,}\left[\begin{array}{c}{2}\\ {3}\\ {1}\\ {3}\end{array}\right]{,}\left[\begin{array}{c}{2.}\\ {3.}\\ {1.}\\ {4.}\end{array}\right]$ (12)

Adding the structuralsymmetry option makes Maple include the entry for ${\mathrm{m3}}_{1,3}$, even though it is 0, because ${\mathrm{m3}}_{3,1}$ is nonzero.

 > $\mathrm{CompressedSparseForm}\left(\mathrm{m3},\mathrm{structuralsymmetry}\right)$
 $\left[\begin{array}{c}{1}\\ {3}\\ {4}\\ {6}\end{array}\right]{,}\left[\begin{array}{c}{2}\\ {3}\\ {1}\\ {1}\\ {3}\end{array}\right]{,}\left[\begin{array}{c}{2.}\\ {3.}\\ {1.}\\ {0.}\\ {4.}\end{array}\right]$ (13)

Adding the includediagonal option makes Maple include the entries for ${\mathrm{m3}}_{1,1}$ and ${\mathrm{m3}}_{2,2}$, even though they are 0.

 > $\mathrm{CompressedSparseForm}\left(\mathrm{m3},\mathrm{includediagonal}\right)$
 $\left[\begin{array}{c}{1}\\ {4}\\ {6}\\ {7}\end{array}\right]{,}\left[\begin{array}{c}{1}\\ {2}\\ {3}\\ {1}\\ {2}\\ {3}\end{array}\right]{,}\left[\begin{array}{c}{0.}\\ {2.}\\ {3.}\\ {1.}\\ {0.}\\ {4.}\end{array}\right]$ (14)

Adding both of these options makes Maple include the entries for ${\mathrm{m3}}_{1,1}$, ${\mathrm{m3}}_{2,2}$, and ${\mathrm{m3}}_{1,3}$.

 > $\mathrm{CompressedSparseForm}\left(\mathrm{m3},\mathrm{includediagonal},\mathrm{structuralsymmetry}\right)$
 $\left[\begin{array}{c}{1}\\ {4}\\ {6}\\ {8}\end{array}\right]{,}\left[\begin{array}{c}{1}\\ {2}\\ {3}\\ {1}\\ {2}\\ {1}\\ {3}\end{array}\right]{,}\left[\begin{array}{c}{0.}\\ {2.}\\ {3.}\\ {1.}\\ {0.}\\ {0.}\\ {4.}\end{array}\right]$ (15)

CompressedSparseForm does not work with Matrices that are not of a hardware data type.

 > $\mathrm{m4}≔\mathrm{Matrix}\left(3,3,\left(i,j\right)↦i-j\right)$
 ${\mathrm{m4}}{≔}\left[\begin{array}{ccc}{0}& {-1}& {-2}\\ {1}& {0}& {-1}\\ {2}& {1}& {0}\end{array}\right]$ (16)
 > $\mathrm{CompressedSparseForm}\left(\mathrm{m4}\right)$

To make this work, we need to recreate $\mathrm{m4}$ with, for example, option $\mathrm{datatype}={\mathrm{integer}}_{4}$.

 > $\mathrm{m4}≔\mathrm{Matrix}\left(\mathrm{m4},\mathrm{datatype}=\mathrm{integer}\left[4\right]\right)$
 ${\mathrm{m4}}{≔}\left[\begin{array}{ccc}{0}& {-1}& {-2}\\ {1}& {0}& {-1}\\ {2}& {1}& {0}\end{array}\right]$ (17)
 > $\mathrm{cb},r,x≔\mathrm{CompressedSparseForm}\left(\mathrm{m4}\right)$
 ${\mathrm{cb}}{,}{r}{,}{x}{≔}\left[\begin{array}{c}{1}\\ {3}\\ {5}\\ {7}\end{array}\right]{,}\left[\begin{array}{c}{2}\\ {3}\\ {1}\\ {3}\\ {1}\\ {2}\end{array}\right]{,}\left[\begin{array}{c}{1}\\ {2}\\ {-1}\\ {1}\\ {-2}\\ {-1}\end{array}\right]$ (18)

Here is an example of the antisymmetric indexing function being ignored.

 > $\mathrm{m5}≔\mathrm{Matrix}\left(6,\mathrm{datatype}=\mathrm{integer}\left[4\right],\mathrm{shape}=\mathrm{antisymmetric},\mathrm{storage}=\mathrm{sparse}\left[\mathrm{lower}\right],\left(i,j\right)↦\mathrm{if}\left(\mathrm{irem}\left(i+j,2\right)=1,i-j,0\right)\right)$
 ${\mathrm{m5}}{≔}\left[\begin{array}{cccccc}{0}& {-1}& {0}& {-3}& {0}& {-5}\\ {1}& {0}& {-1}& {0}& {-3}& {0}\\ {0}& {1}& {0}& {-1}& {0}& {-3}\\ {3}& {0}& {1}& {0}& {-1}& {0}\\ {0}& {3}& {0}& {1}& {0}& {-1}\\ {5}& {0}& {3}& {0}& {1}& {0}\end{array}\right]$ (19)
 > $\mathrm{CompressedSparseForm}\left(\mathrm{m5}\right)$
 $\left[\begin{array}{c}{1}\\ {4}\\ {6}\\ {8}\\ {9}\\ {10}\\ {10}\end{array}\right]{,}\left[\begin{array}{c}{2}\\ {4}\\ {6}\\ {3}\\ {5}\\ {4}\\ {6}\\ {5}\\ {6}\end{array}\right]{,}\left[\begin{array}{c}{1}\\ {3}\\ {5}\\ {1}\\ {3}\\ {1}\\ {3}\\ {1}\\ {1}\end{array}\right]$ (20)

Compatibility

 • The LinearAlgebra[CompressedSparseForm] command was introduced in Maple 17.
 • For more information on Maple 17 changes, see Updates in Maple 17.
 • The LinearAlgebra[CompressedSparseForm] command was updated in Maple 2022.
 • The length0, includediagonal and structuralsymmetry options were introduced in Maple 2022.
 • For more information on Maple 2022 changes, see Updates in Maple 2022.

 See Also