svn commit: r1230907 - /commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RealLinearOperator.java

[ce...@apache.org]

Author: celestin
Date: Fri Jan 13 07:11:19 2012
New Revision: 1230907

URL: http://svn.apache.org/viewvc?rev=1230907&view=rev
Log:
Javadoc
Added optional support for transposition of linear operators.

Modified:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RealLinearOperator.java

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RealLinearOperator.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RealLinearOperator.java?rev=1230907&r1=1230906&r2=1230907&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RealLinearOperator.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/linear/RealLinearOperator.java Fri Jan 13 07:11:19 2012
@@ -17,22 +17,23 @@
 
 package org.apache.commons.math.linear;
 
+import org.apache.commons.math.exception.DimensionMismatchException;
+
 /**
  * This class defines a linear operator operating on real ({@code double})
- * vector spaces.
- * No direct access to the coefficients of the underlying matrix is provided.
+ * vector spaces. No direct access to the coefficients of the underlying matrix
+ * is provided.
  *
  * The motivation for such an interface is well stated by
  * <a href="#BARR1994">Barrett et al. (1994)</a>:
  * <blockquote>
  *  We restrict ourselves to iterative methods, which work by repeatedly
  *  improving an approximate solution until it is accurate enough. These
- *  methods access the coefficient matrix {@code A} of the linear system
- *  only via the matrix-vector product {@code y = A x} (and perhaps
- *  {@code z} = {@code A}<sup>T</sup> {@code x}). Thus the user need only
- *  supply a subroutine for computing {@code y} (and perhaps {@code z})
- *  given {@code x}, which permits full exploitation of the sparsity or
- *  other special structure of A.
+ *  methods access the coefficient matrix A of the linear system only via the
+ *  matrix-vector product y = A &middot; x
+ *  (and perhaps z = A<sup>T</sup> &middot; x). Thus the user need only
+ *  supply a subroutine for computing y (and perhaps z) given x, which permits
+ *  full exploitation of the sparsity or other special structure of A.
  * </blockquote>
  * <br/>
  *
@@ -73,4 +74,36 @@ public abstract class RealLinearOperator
      * if the column dimension does not match the size of {@code x}.
      */
     public abstract RealVector operate(final RealVector x);
+
+    /**
+     * Returns the result of multiplying the transpose of {@code this} operator
+     * by the vector {@code x} (optional operation). The default implementation
+     * throws an {@link UnsupportedOperationException}. Users overriding this
+     * method must also override {@link #isTransposable()}.
+     *
+     * @param x Vector to operate on.
+     * @return the product of the transpose of {@code this} instance with
+     * {@code x}.
+     * @throws org.apache.commons.math.exception.DimensionMismatchException
+     * if the row dimension does not match the size of {@code x}.
+     * @throws UnsupportedOperationException if this operation is not supported
+     * by {@code this} operator
+     */
+    public RealVector operateTranspose(final RealVector x)
+        throws DimensionMismatchException, UnsupportedOperationException {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Returns {@code true} if this operator supports
+     * {@link #operateTranspose(RealVector)}. If {@code true} is returned,
+     * {@link #operateTranspose(RealVector)} should not throw
+     * {@code UnsupportedOperationException}. The default implementation returns
+     * {@code false}.
+     *
+     * @return {@code false}
+     */
+    public boolean isTransposable() {
+        return false;
+    }
 }