Changes between Version 13 and Version 14 of QuickStart

Author:

Anonymous (IP: 134.109.40.151)

Timestamp:

04/30/09 10:21:47 (15 years ago)

Comment:

--

QuickStart

@@ -416 +416 @@
-
-== Operations ==
+
+LYLA support many matrix operations.  For example, adding two matrices B and C and storing the result in a matrix A is done by
+{{{
+#!d
+// A = B + C
+add(A, B, C);
+}}}
+As a general rule, the result of an operation is always stored in the '''first''' argument of the function.  Furthermore, for many operations it is possible to call the function as method call of the result matrix.  Therefore, the above example is equivalent to
+{{{
+#!d
+// A = B + C
+A.add(B, C);
+}}}
+Many functions may store the result in one of the operands:
+{{{
+#!d
+// A = A + B
+add(A, B);
+A.add(B);
+}}}
+The same is true for unary matrix functions, i.e. functions that work on a single matrix:
+{{{
+#!d
+// A[i,j] = sqrt(B[i,j])
+sqrt(A, B);
+A.sqrt(B);
+
+// A[i,j] = sqrt(A[i,j]);
+sqrt(A);
+A.sqrt();
+}}}
+
+This table lists some of the binary operations for matrices:
+||{{{add(A,B,C)}}}||{{{A = B + C}}}||
+||{{{sub(A,B,C)}}}||{{{A = B - C}}}||
+||{{{div(A,B,C)}}}||{{{A[i,j] = B[i,j] / C[i,j]}}}||
+||{{{pmul(A,B,C)}}}||{{{A[i,j] = B[i,j] * C[i,j]}}}||
+||{{{mul(A,B,C)}}}||{{{A = B * C}}}||
+
+This table lists some of the binary operations for matrices with scalars:
+||{{{add(A,x,C)}}}||{{{A[i,j] = x + C[i,j]}}}||
+||{{{add(A,B,x)}}}||{{{A[i,j] = B[i,j] + x}}}||
+||{{{sub(A,x,C)}}}||{{{A[i,j] = x - C[i,j]}}}||
+||{{{sub(A,B,x)}}}||{{{A[i,j] = B[i,j] - x}}}||
+||{{{div(A,x,C)}}}||{{{A[i,j] = x / C[i,j]}}}||
+||{{{div(A,B,x)}}}||{{{A[i,j] = B[i,j] / x}}}||
+||{{{pmul(A,x,C)}}}||{{{A[i,j] = x * C[i,j]}}}||
+||{{{pmul(A,B,x)}}}||{{{A[i,j] = B[i,j] * x}}}||
+
+Unary operations:
+||{{{abs(A,B)}}}||{{{A[i,j] = |B[i,j]|}}}||
+||{{{neg(A,B)}}}||{{{A[i,j] = -B[i,j]}}}||
+||{{{sqrt(A,B)}}}||{{{A[i,j] = sqrt(B[i,j])}}}||
+||{{{sin(A,B)}}}||{{{A[i,j] = sin(B[i,j])}}}||
+||{{{cos(A,B)}}}||{{{A[i,j] = cos(B[i,j])}}}||
+
+=== Operators ===
+Common matrix operators are overloaded:
+{{{#!d
+auto A = new DMatrix, B = new DMatrix;
+double x;
+...
+A += B;  // same as A.add(B);
+A += x;  // same as A.add(x);
+A -= B;  // same as A.sub(B);
+A -= x;  // same as A.sub(x);
+A *= B;  // same as A.mul(B);
+A *= x;  // same as A.mul(x);
+A /= B;  // same as A.div(B);
+A /= x;  // same as A.div(x);
+}}}
+
+Binary operators are overloaded, too, but there is one important difference to the explicit functions above.  Since operators return a value instead of modifying their arguments, calling for example {{{A + B}}} always creates a new matrix:
+{{{
+#!d
+auto A = new DMatrix, B = new DMatrix;
+...
+auto C = A + B; // creates a new matrix C
+}}}
+The resulting matrix has usually the same orientation as the first operand and is sparse if and only if both operands are sparse.  This means, if you use only one matrix type, the result of the operations will always have the same type as both operands:
+{{{
+#!d
+auto A = new DMatrix, B = new DMatrix;
+DMatrix C;
+...
+C = A * B; // works
+}}}
+
+=== BLAS like operations ===
+LYLA support some BLAS-like functions.  If BLAS-support is compiled in, the arithmetic for dense matrices call the BLAS-functions to perform the operations.  Since the rule in LYLA is to store the result in the first argument (in contrast to BLAS where the result is usually stored in the last argument), must functions have another order of parameters than their BLAS counterparts:
+
+  * compute the inner product of two vectors {{{x}}} and {{{y}}}
+{{{
+#!d
+value_t dot(Vector!(value_t) x, Vector!(value_t) y)
+}}}
+
+  * scale a vector y by factor alpha: x = x * alpha
+{{{
+#!d
+void scal( Vector!(value_t) x, value_t alpha )
+}}}
+
+  * compute x = x + alpha * y
+{{{
+#!d
+void xepay( Vector!(value_t) x, value_t alpha, Vector!(value_t) y)
+}}}
+
+  * Multiply a matrix and a vector: x = x * alpha + A * y * beta
+{{{
+#!d
+void vmul( Vector!(value_t) x, value_t alpha, Matrix!(value_t) A, Vector!(value_t) y, value_t beta )
+}}}
+
+  * Multiply two matrices: A = A * alpha + B * C * beta
+{{{
+#!d
+void mmul( Matrix!(value_t) A, value_t alpha, Matrix!(value_t) B, Matrix!(value_t) C, value_t beta )
+}}}
+
+'''Remark:''' BLAS functions may be called as methods of the destination matrix, too:
+{{{
+#!d
+/// A = A * alpha + B * C * beta
+A.mmul( alpha, B, C, beta )
+}}}
+