Big-Data-HPC-Platform/docs/ECLStandardLibraryReference/SLR-Mods/BLAS.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="BLAS">
  <title><emphasis>BLAS Support</emphasis></title>

  <para>This section provides support tor Basic Linear Algebra Subprogram
  support.</para>

  <para>The BLAS functions use the column major mapping for the storage of a
  matrix. This is the mapping used in Fortran, and has the entries of the
  first column followed by the entries of the second column. This is the
  transpose of the row major form commonly used in the C language where the
  entries of the first row are followed by the entries of the second
  row.</para>

  <sect1 id="BLASTypes">
    <title>Types</title>

    <para><emphasis role="bold">STD.BLAS.Types<indexterm>
        <primary>STD.BLAS.Types</primary>
      </indexterm><indexterm>
        <primary>BLAS.Types</primary>
      </indexterm><indexterm>
        <primary>Types</primary>
      </indexterm></emphasis></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <tbody>
          <row>
            <entry><emphasis>value_t</emphasis></entry>

            <entry>REAL8</entry>
          </row>

          <row>
            <entry><emphasis>dimension_t</emphasis></entry>

            <entry>UNSIGNED4</entry>
          </row>

          <row>
            <entry><emphasis>matrix_t</emphasis></entry>

            <entry>SET OF REAL8</entry>
          </row>

          <row>
            <entry><emphasis>Triangle</emphasis></entry>

            <entry>ENUM(UNSIGNED1, Upper=1, Lower=2)</entry>
          </row>

          <row>
            <entry><emphasis>Diagonal</emphasis></entry>

            <entry>ENUM(UNSIGNED1, UnitTri=1, NotUnitTri=2)</entry>
          </row>

          <row>
            <entry><emphasis>Side</emphasis></entry>

            <entry>ENUM(UNSIGNED1, Ax=1, xA=2)</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>Types for the Block Basic Linear Algebra Sub-programs support</para>

    <para></para>
  </sect1>

  <sect1 id="ICellFunc">
    <title>ICellFunc</title>

    <para><emphasis role="bold">STD.BLAS.ICellFunc<indexterm>
        <primary>STD.BLAS.ICellFunc</primary>
      </indexterm><indexterm>
        <primary>BLAS.ICellFunc</primary>
      </indexterm><indexterm>
        <primary>ICellFunc</primary>
      </indexterm>(</emphasis> <emphasis>v, r</emphasis> <emphasis
    role="bold">,</emphasis> <emphasis>c</emphasis> <emphasis>);</emphasis>
    <emphasis></emphasis></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>v</emphasis></entry>

            <entry>The value</entry>
          </row>

          <row>
            <entry><emphasis>r</emphasis></entry>

            <entry>The row ordinal</entry>
          </row>

          <row>
            <entry><emphasis>c</emphasis></entry>

            <entry>The column ordinal</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The updated value</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para><emphasis role="bold">ICellFunc </emphasis>is the function prototype
    for Apply2Cells.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
REAL8 my_func(STD.BLAS.Types.value_t v, STD.BLAS.Types.dimension_t x, STD.BLAS.Types.dimension_t y) 
              := 1/v; //set element to the reciprocal value
</programlisting>

    <para>See Also: <link linkend="Apply2Cells">Apply2Cells</link></para>
  </sect1>

  <sect1 id="Apply2Cells">
    <title>Apply2Cells</title>

    <para><emphasis role="bold">STD.BLAS.Apply2Cells<indexterm>
        <primary>STD.BLAS.Apply2Cells</primary>
      </indexterm><indexterm>
        <primary>BLAS.Apply2Cells</primary>
      </indexterm><indexterm>
        <primary>Apply2Cells</primary>
      </indexterm>(</emphasis> <emphasis>m, n</emphasis> <emphasis
    role="bold">,</emphasis> <emphasis>x, f</emphasis> <emphasis>);</emphasis>
    <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>m</emphasis></entry>

            <entry>Number of rows</entry>
          </row>

          <row>
            <entry><emphasis>n</emphasis></entry>

            <entry>Number of columns</entry>
          </row>

          <row>
            <entry><emphasis>x</emphasis></entry>

            <entry>Matrix</entry>
          </row>

          <row>
            <entry><emphasis>f</emphasis></entry>

            <entry>Function to apply</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The updated matrix</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">Apply2Cells </emphasis>function iterates a
    matrix and applies a function to each cell.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.value_t example_1(STD.BLAS.Types.value_t v, 
                                 STD.BLAS.Types.dimensiopn_t x, 
                                 STD.BLAS.Types.dimension_t y) := FUNCTION
  RETURN IF(x=y, 1.0, 1/v);
END;

init_mat := [1, 2, 4, 4, 5, 10, 2, 5, 2];
new_mat := STD.BLAS.Apply2Cells(3, 3, init_mat, example_1);

// The new_mat matrix will be [1, .5, .25, .25, 1, .1, .5, .2, 1]
</programlisting>

    <para>See Also: <link linkend="ICellFunc">ICellFunc</link></para>
  </sect1>

  <sect1 id="dasum">
    <title>dasum</title>

    <para><emphasis role="bold">STD.BLAS.dasum<indexterm>
        <primary>STD.BLAS.dasum</primary>
      </indexterm><indexterm>
        <primary>BLAS.dasum</primary>
      </indexterm><indexterm>
        <primary>dasum</primary>
      </indexterm>(</emphasis> <emphasis>m, </emphasis> <emphasis>x, incx,
    skipped);</emphasis> <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>m</emphasis></entry>

            <entry>Number of entries</entry>
          </row>

          <row>
            <entry><emphasis>x</emphasis></entry>

            <entry>The column major matrix holding the vector</entry>
          </row>

          <row>
            <entry><emphasis>incxx</emphasis></entry>

            <entry>The increment for x, 1 in the case of an actual
            vector</entry>
          </row>

          <row>
            <entry><emphasis>skipped</emphasis></entry>

            <entry>The number of entries stepped over. Default is
            zero.</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The sum of the absolute values</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">dasum </emphasis>function gets the
    absolute sum, the 1 norm of a vector.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.matrix_t test_data := [2, -2, -3, 3, 1, 3, -1, -1, 1];
STD.BLAS.dasum(9, test_data, 1); //sums the absolute values of the matrix, and returns 17
</programlisting>

    <para></para>
  </sect1>

  <sect1 id="daxpy">
    <title>daxpy</title>

    <para><emphasis role="bold">STD.BLAS.daxpy<indexterm>
        <primary>STD.BLAS.daxpy</primary>
      </indexterm><indexterm>
        <primary>BLAS.dasum</primary>
      </indexterm><indexterm>
        <primary>dasum</primary>
      </indexterm>(</emphasis> <emphasis>N, alpha, X, incX, Y, incY,
    x_skipped,y_skipped);</emphasis> <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>N</emphasis></entry>

            <entry>Number of entries</entry>
          </row>

          <row>
            <entry><emphasis>alpha</emphasis></entry>

            <entry>The column major matrix holding the vector</entry>
          </row>

          <row>
            <entry><emphasis>X</emphasis></entry>

            <entry>The increment for x, 1 in the case of an actual
            vector</entry>
          </row>

          <row>
            <entry><emphasis>incX</emphasis></entry>

            <entry>The column major matrix holding the vector X</entry>
          </row>

          <row>
            <entry><emphasis>Y</emphasis></entry>

            <entry>The column major matrix holding the vector Y</entry>
          </row>

          <row>
            <entry><emphasis>incY</emphasis></entry>

            <entry>The increment or stride of Y</entry>
          </row>

          <row>
            <entry><emphasis>x_skipped</emphasis></entry>

            <entry>The number of entries stepped over. to get to the first X
            .</entry>
          </row>

          <row>
            <entry><emphasis>y_skipped</emphasis></entry>

            <entry>The number of entries stepped over. to get to the first Y
            .</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The updated matrix</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">daxpy</emphasis> function is used to sum
    two vectors or matrices with a scalar multiplier applied during the sum
    operation..</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.t_matrix term_1 := [1, 2, 3];
STD.BLAS.Types.t_matrix term_2 := [3, 2, 1].
STD.BLAS.daxpy(3, 2, term_1, 1, term_2, 1); // result is [5, 6, 7]

</programlisting>

    <para></para>
  </sect1>

  <sect1 id="dgemm">
    <title>dgemm</title>

    <para><emphasis role="bold">STD.BLAS.dgemm<indexterm>
        <primary>STD.BLAS.dgemm</primary>
      </indexterm><indexterm>
        <primary>BLAS.dgemm</primary>
      </indexterm><indexterm>
        <primary>dgemm</primary>
      </indexterm>(</emphasis> <emphasis>transposeA, transposeB, M, N, K,
    alpha, A, B, beta, C);</emphasis> <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>transposeA</emphasis></entry>

            <entry>True when transpose of A is used</entry>
          </row>

          <row>
            <entry><emphasis>transposeB</emphasis></entry>

            <entry>True when transpose of B is used</entry>
          </row>

          <row>
            <entry><emphasis>M</emphasis></entry>

            <entry>Number of rows in product</entry>
          </row>

          <row>
            <entry><emphasis>N</emphasis></entry>

            <entry>Number of columns in product</entry>
          </row>

          <row>
            <entry><emphasis>K</emphasis></entry>

            <entry>Number of columns/rows for the
            multiplier/multiplicand</entry>
          </row>

          <row>
            <entry><emphasis>alpha</emphasis></entry>

            <entry>Scalar used on A</entry>
          </row>

          <row>
            <entry><emphasis>A</emphasis></entry>

            <entry>Matrix A</entry>
          </row>

          <row>
            <entry><emphasis>B</emphasis></entry>

            <entry>Matrix B</entry>
          </row>

          <row>
            <entry><emphasis>beta</emphasis></entry>

            <entry>Scalar for matirx C</entry>
          </row>

          <row>
            <entry><emphasis>C</emphasis></entry>

            <entry>Matrix C (or empty)</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The updated matrix</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">dgemm</emphasis> function is used to
    multiply two matrices and optionally add that product to another
    matrix.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.t_matrix term_a := [2, 4, 8];
STD.BLAS.Types.t_matrix term_c := [2, 1, 1];

STD.BLAS.dgemm(TRUE, FALSE, 3, 3, 1, 1, term_a, term_b);
                  //the outer product of the term_a and term_b vectors
                  //result is [4,8, 16, 2, 4, 8, 2, 4, 8]
</programlisting>

    <para></para>
  </sect1>

  <sect1 id="dgetf2">
    <title>dgetf2</title>

    <para><emphasis role="bold">STD.BLAS.dgetf2<indexterm>
        <primary>STD.BLAS.dgetf2</primary>
      </indexterm><indexterm>
        <primary>BLAS.dgetf2</primary>
      </indexterm><indexterm>
        <primary>dgetf2</primary>
      </indexterm>(</emphasis> <emphasis>m, n, a);</emphasis>
    <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>m</emphasis></entry>

            <entry>Number of rows of matrix a</entry>
          </row>

          <row>
            <entry><emphasis>n</emphasis></entry>

            <entry>Number of columns of matrix a</entry>
          </row>

          <row>
            <entry><emphasis>a</emphasis></entry>

            <entry>Matrix a</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>Composite matrix of factors, lower triangle has an implied
            diagonal of ones. Upper triangle has the diagonal of the
            composite.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">dgetf2</emphasis> function produces a
    combine lower and upper triangular factorization.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.t_matrix test := [2,4,6,3,10,25, 9,34,100];
STD.BLAS.dgetf2(3, 3, test); //result is [2,2,3,3,4,4,9,16,25];
</programlisting>

    <para></para>
  </sect1>

  <sect1 id="dpotf2">
    <title>dpotf2</title>

    <para><emphasis role="bold">STD.BLAS.dpotf2<indexterm>
        <primary>STD.BLAS.dpotf2</primary>
      </indexterm><indexterm>
        <primary>BLAS.dpotf2</primary>
      </indexterm><indexterm>
        <primary>dpotf2</primary>
      </indexterm>(</emphasis> <emphasis>tri,, r, A, clear);</emphasis>
    <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>tri</emphasis></entry>

            <entry>Indicates whether upper or lower triangle is used</entry>
          </row>

          <row>
            <entry><emphasis>r</emphasis></entry>

            <entry>Number of rows/columns in the square matrix</entry>
          </row>

          <row>
            <entry><emphasis>A</emphasis></entry>

            <entry>The square matrix A</entry>
          </row>

          <row>
            <entry><emphasis>clear</emphasis></entry>

            <entry>Clears the unused triangle</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The triangular matrix requested</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">dpotf2</emphasis> function computes the
    Cholesky factorization of a real symmetric positive definite matrix A. The
    factorization has the form A = U**T*U if the <emphasis>tri</emphasis>
    parameter is Triangle.Upper, or A = L * L**T if the
    <emphasis>tri</emphasis> parameter is Triangle.Lower. This is the
    unblocked version of the algorithm, calling Level 2 BLAS.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.matrix_t  symmetric_pos_def := [4, 6, 8, 6, 13, 18, 8, 18, 29];
Lower_Triangle := BLAS.dpotf2(STD.BLAS.Types.Triangle.lower, 3, symmetric_pos_def); </programlisting>

    <para></para>
  </sect1>

  <sect1 id="dscal">
    <title>dscal</title>

    <para><emphasis role="bold">STD.BLAS.dscal<indexterm>
        <primary>STD.BLAS.dscal</primary>
      </indexterm><indexterm>
        <primary>BLAS.dscal</primary>
      </indexterm><indexterm>
        <primary>dscal</primary>
      </indexterm>(</emphasis> <emphasis>N, alpha, X, incX,
    skipped);</emphasis> <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>N</emphasis></entry>

            <entry>Number of elements in the vector</entry>
          </row>

          <row>
            <entry><emphasis>alpha</emphasis></entry>

            <entry>The scaling factor</entry>
          </row>

          <row>
            <entry><emphasis>X</emphasis></entry>

            <entry>The column major matrix holding the vector</entry>
          </row>

          <row>
            <entry><emphasis>incX</emphasis></entry>

            <entry>The stride to get to the next element in the vector</entry>
          </row>

          <row>
            <entry><emphasis>skipped</emphasis></entry>

            <entry>The number of elements skipped to get to the first
            element</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The updated matrix</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">dscal </emphasis> function scales a vector
    alpha.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.matrix_t test := [1, 1, 1, 2, 2, 2, 3, 3, 3];
result := STD.BLAS.dscal(9, 2.0, test, 1); // multiply each element by 2
</programlisting>

    <para></para>

    <para></para>

    <para></para>
  </sect1>

  <sect1 id="dsyrk">
    <title>dsyrk</title>

    <para><emphasis role="bold">STD.BLAS.dsyrk<indexterm>
        <primary>STD.BLAS.dsyrk</primary>
      </indexterm><indexterm>
        <primary>BLAS.dsyrk</primary>
      </indexterm><indexterm>
        <primary>dsyrk</primary>
      </indexterm>(</emphasis> <emphasis>tri, transposeA, N, K, alpha, A,
    beta, C, clear);</emphasis> <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>tri</emphasis></entry>

            <entry>Indicates whether upper or lower triangle is used</entry>
          </row>

          <row>
            <entry><emphasis>transposeA</emphasis></entry>

            <entry>Transpose the A matrix to be NxK</entry>
          </row>

          <row>
            <entry><emphasis>N</emphasis></entry>

            <entry>Number of rows</entry>
          </row>

          <row>
            <entry><emphasis>K</emphasis></entry>

            <entry>Number of columns in the update matrix or transpose</entry>
          </row>

          <row>
            <entry><emphasis>alpha</emphasis></entry>

            <entry>The alpha scalar</entry>
          </row>

          <row>
            <entry><emphasis>A</emphasis></entry>

            <entry>The update matrix, either NxK or KxN</entry>
          </row>

          <row>
            <entry><emphasis>beta</emphasis></entry>

            <entry>The beta scalar</entry>
          </row>

          <row>
            <entry><emphasis>C</emphasis></entry>

            <entry>The matrix to update</entry>
          </row>

          <row>
            <entry><emphasis>clear</emphasis></entry>

            <entry>Clear the triangle that is not updated. BLAS assumes that
            symmetric matrices have only one of the triangles and this option
            lets you make that true.</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The updated matrix</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">dsyrk </emphasis> function implements a
    symmetric rank update C &lt;- alpha A**T A + beta C or c &lt;- alpha A
    A**T + beta C. C is N x N.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.matrix_t initC := [1, 1, 1, 2, 2, 2, 3, 3, 3];
STD.BLAS.Types.matrix_t initA := [1, 1, 1];
Test1_mat := STD.BLAS.dsyrk(STD.BLAS.Types.Triangle.upper, FALSE, 3, 1, 1, initA, 1, initC, TRUE)

</programlisting>

    <para></para>
  </sect1>

  <sect1 id="dtrsm">
    <title>dtrsm</title>

    <para><emphasis role="bold">STD.BLAS.dtrsm<indexterm>
        <primary>STD.BLAS.dtrsm</primary>
      </indexterm><indexterm>
        <primary>BLAS.dsyrk</primary>
      </indexterm><indexterm>
        <primary>dtrsm</primary>
      </indexterm>(</emphasis> <emphasis>side, tri, transposeA, diag, M, N,
    lda, alpha, A, B);</emphasis> <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>side</emphasis></entry>

            <entry>Side for A, Side.Ax is op(A) X = alpha B</entry>
          </row>

          <row>
            <entry><emphasis>tri</emphasis></entry>

            <entry>Indicates whether upper or lower triangle is used</entry>
          </row>

          <row>
            <entry><emphasis>transposeA</emphasis></entry>

            <entry>Is op(A) the transpose of A</entry>
          </row>

          <row>
            <entry><emphasis>diag</emphasis></entry>

            <entry>The diagonal (an implied unit diagonal or supplied)</entry>
          </row>

          <row>
            <entry><emphasis>M</emphasis></entry>

            <entry>Number of rows</entry>
          </row>

          <row>
            <entry><emphasis>N</emphasis></entry>

            <entry>Number of columns</entry>
          </row>

          <row>
            <entry><emphasis>lda </emphasis></entry>

            <entry>The leading dimension of the A matrix, either M or
            N</entry>
          </row>

          <row>
            <entry><emphasis>alpha</emphasis></entry>

            <entry>The scalar multiplier for B</entry>
          </row>

          <row>
            <entry><emphasis>A</emphasis></entry>

            <entry>A triangular matrix</entry>
          </row>

          <row>
            <entry><emphasis>B</emphasis></entry>

            <entry>The matrix of values for the solve</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The matrix of coefficients to get B</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">dtrsm </emphasis> function is a triangular
    matrix solver. op(A) X = alpha B or X op(A) = alpha B * where op is
    Transpose, X and B is MxN</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
Side := STD.BLAS.Types.Side;
Diagonal := STD.BLAS.Types.Diagonal;
Triangle := STD.BLAS.Types.Triangle;
STD.BLAS.Types.matrix_t left_a0 := [2, 3, 4, 0, 2, 3, 0, 0, 2];
STD.BLAS.Types.matrix_t mat_b := [4, 6, 8, 6, 13, 18, 8, 18, 29];

Test1_mat := STD.BLAS.dtrsm(Side.Ax, Triangle.Lower, FALSE, Diagonal.NotUnitTri,
                            3, 3, 3, 1.0, left_a0, mat_b);
</programlisting>

    <para></para>

    <para></para>

    <para></para>
  </sect1>

  <sect1 id="extract_diag">
    <title>extract_diag</title>

    <para><emphasis role="bold">STD.BLAS.extract_diag <indexterm>
        <primary>STD.BLAS.extract_diag</primary>
      </indexterm><indexterm>
        <primary>BLAS.extract_diag</primary>
      </indexterm><indexterm>
        <primary>extract_diag</primary>
      </indexterm>(</emphasis> <emphasis>m.n.x);</emphasis>
    <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>m</emphasis></entry>

            <entry>Number of rows</entry>
          </row>

          <row>
            <entry><emphasis>n</emphasis></entry>

            <entry>Number of columns</entry>
          </row>

          <row>
            <entry><emphasis>x</emphasis></entry>

            <entry>The matrix from which to extract the diagonal</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>Diagonal matrix</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">extract_diag </emphasis> function extracts
    the diagonal of he matrix</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.matrix_t x := [1.0, 2.0, 3.0, 2.0, 2.0, 2.0, 4.0, 4.0, 4.0];
diagonal_only := := STD.BLAS.extract_diag(3, 3, x);
</programlisting>

    <para></para>

    <para></para>

    <para></para>
  </sect1>

  <sect1 id="extract_tri">
    <title>extract_tri</title>

    <para><emphasis role="bold">STD.BLAS.extract_tri <indexterm>
        <primary>STD.BLAS.extract_tri</primary>
      </indexterm><indexterm>
        <primary>BLAS.extract_tri</primary>
      </indexterm><indexterm>
        <primary>extract_tri</primary>
      </indexterm>(</emphasis> <emphasis>m, n, tri, dt, a );</emphasis>
    <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>m</emphasis></entry>

            <entry>Number of rows</entry>
          </row>

          <row>
            <entry><emphasis>n</emphasis></entry>

            <entry>Number of columns</entry>
          </row>

          <row>
            <entry><emphasis>tri</emphasis></entry>

            <entry>Indicates whether upper or lower triangle is used</entry>
          </row>

          <row>
            <entry><emphasis>dt</emphasis></entry>

            <entry>Use Diagonal.NotUnitTri or Diagonal.UnitTri</entry>
          </row>

          <row>
            <entry><emphasis>a</emphasis></entry>

            <entry>The matrix, usually a composite from factoring</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>Triangle</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">extract_tri </emphasis> function extracts
    the upper or lower triangle. The diagonal can be the actual or implied
    unit diagonal.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
Diagonal := STD.BLAS.Types.Diagonal;
Triangle := STD.BLAS.Types.Triangle;
STD.BLAS.Types.matrix_t x := [1.0, 2.0, 3.0, 2.0, 2.0, 2.0, 4.0, 4.0, 4.0];
triangle := STD.BLAS.extract_tri(3, 3, Triangle.upper, Diagonal.NotUnitTri, x);
</programlisting>

    <para></para>
  </sect1>

  <sect1 id="make_diag">
    <title>make_diag</title>

    <para><emphasis role="bold">STD.BLAS.make_diag <indexterm>
        <primary>STD.BLAS.make_diag</primary>
      </indexterm><indexterm>
        <primary>BLAS.make_diag</primary>
      </indexterm><indexterm>
        <primary>make_diag</primary>
      </indexterm>(</emphasis> <emphasis>m, v, X );</emphasis>
    <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>m</emphasis></entry>

            <entry>Number of diagonal entries</entry>
          </row>

          <row>
            <entry><emphasis>v</emphasis></entry>

            <entry>Option value, default is 1</entry>
          </row>

          <row>
            <entry><emphasis>X</emphasis></entry>

            <entry>Optional input of diagonal values, multiplied by v</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>A diagonal matrix</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">make_diag </emphasis> function generates a
    diagonal matrix.</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.matrix_t init1 := [1.0, 2.0, 3.0, 4.0];
Square := STD.BLAS.make_diag(4, 1, init1); //4x4 with diagonal 1, 2, 3, 4
</programlisting>

    <para></para>
  </sect1>

  <sect1 id="make_vector">
    <title>make_vector</title>

    <para><emphasis role="bold">STD.BLAS.make_vector <indexterm>
        <primary>STD.BLAS.make_vector</primary>
      </indexterm><indexterm>
        <primary>BLAS.make_vector</primary>
      </indexterm><indexterm>
        <primary>make_vector</primary>
      </indexterm>(</emphasis> <emphasis>m, v );</emphasis>
    <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>m</emphasis></entry>

            <entry>Number of elements</entry>
          </row>

          <row>
            <entry><emphasis>v</emphasis></entry>

            <entry>The values, default is 1</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The vector</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">make_vector</emphasis> function generates
    a vector of dimension n</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
twos_vector := STD.BLAS.make_vector(4, 2); // a vector of [2, 2, 2, 2]
</programlisting>

    <para></para>

    <para></para>
  </sect1>

  <sect1 id="BLASTrace">
    <title>trace</title>

    <para><emphasis role="bold">STD.BLAS.trace <indexterm>
        <primary>STD.BLAS.tracer</primary>
      </indexterm><indexterm>
        <primary>BLAS.trace</primary>
      </indexterm><indexterm>
        <primary>trace</primary>
      </indexterm>(</emphasis> <emphasis>m, n, x );</emphasis>
    <emphasis></emphasis></para>

    <para></para>

    <informaltable colsep="1" frame="all" rowsep="1">
      <tgroup cols="2">
        <colspec colwidth="80.50pt" />

        <colspec />

        <tbody>
          <row>
            <entry><emphasis>m</emphasis></entry>

            <entry>Number of rows</entry>
          </row>

          <row>
            <entry><emphasis>n</emphasis></entry>

            <entry>Number of columns</entry>
          </row>

          <row>
            <entry><emphasis>x</emphasis></entry>

            <entry>The matrix</entry>
          </row>

          <row>
            <entry>Return:<emphasis></emphasis></entry>

            <entry>The trace (sum of the diagonal entries)</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The <emphasis role="bold">trace</emphasis> function computes the
    trace of the input matrix</para>

    <para>Example:</para>

    <programlisting format="linespecific">IMPORT STD;
STD.BLAS.Types.matrix_t x := [1.0, 2.0, 3.0, 2.0, 2.0, 2.0, 4.0, 4.0, 4.0];
trace_of_x := STD.BLAS.trace(3,3,x); // the trace is 7
</programlisting>

    <para></para>
  </sect1>
</chapter>