001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018 package org.apache.commons.math3.linear; 019 020 import org.apache.commons.math3.exception.DimensionMismatchException; 021 022 /** 023 * This class defines a linear operator operating on real ({@code double}) 024 * vector spaces. No direct access to the coefficients of the underlying matrix 025 * is provided. 026 * 027 * The motivation for such an interface is well stated by 028 * <a href="#BARR1994">Barrett et al. (1994)</a>: 029 * <blockquote> 030 * We restrict ourselves to iterative methods, which work by repeatedly 031 * improving an approximate solution until it is accurate enough. These 032 * methods access the coefficient matrix A of the linear system only via the 033 * matrix-vector product y = A · x 034 * (and perhaps z = A<sup>T</sup> · x). Thus the user need only 035 * supply a subroutine for computing y (and perhaps z) given x, which permits 036 * full exploitation of the sparsity or other special structure of A. 037 * </blockquote> 038 * <br/> 039 * 040 * <dl> 041 * <dt><a name="BARR1994">Barret et al. (1994)</a></dt> 042 * <dd> 043 * R. Barrett, M. Berry, T. F. Chan, J. Demmel, J. M. Donato, J. Dongarra, 044 * V. Eijkhout, R. Pozo, C. Romine and H. Van der Vorst, 045 * <em>Templates for the Solution of Linear Systems: Building Blocks for 046 * Iterative Methods</em>, SIAM 047 * </dd> 048 * </dl> 049 * 050 * @version $Id: RealLinearOperator.java 1416643 2012-12-03 19:37:14Z tn $ 051 * @since 3.0 052 */ 053 public abstract class RealLinearOperator { 054 /** 055 * Returns the dimension of the codomain of this operator. 056 * 057 * @return the number of rows of the underlying matrix 058 */ 059 public abstract int getRowDimension(); 060 061 /** 062 * Returns the dimension of the domain of this operator. 063 * 064 * @return the number of columns of the underlying matrix 065 */ 066 public abstract int getColumnDimension(); 067 068 /** 069 * Returns the result of multiplying {@code this} by the vector {@code x}. 070 * 071 * @param x the vector to operate on 072 * @return the product of {@code this} instance with {@code x} 073 * @throws DimensionMismatchException if the column dimension does not match 074 * the size of {@code x} 075 */ 076 public abstract RealVector operate(final RealVector x) 077 throws DimensionMismatchException; 078 079 /** 080 * Returns the result of multiplying the transpose of {@code this} operator 081 * by the vector {@code x} (optional operation). The default implementation 082 * throws an {@link UnsupportedOperationException}. Users overriding this 083 * method must also override {@link #isTransposable()}. 084 * 085 * @param x the vector to operate on 086 * @return the product of the transpose of {@code this} instance with 087 * {@code x} 088 * @throws org.apache.commons.math3.exception.DimensionMismatchException 089 * if the row dimension does not match the size of {@code x} 090 * @throws UnsupportedOperationException if this operation is not supported 091 * by {@code this} operator 092 */ 093 public RealVector operateTranspose(final RealVector x) 094 throws DimensionMismatchException, UnsupportedOperationException { 095 throw new UnsupportedOperationException(); 096 } 097 098 /** 099 * Returns {@code true} if this operator supports 100 * {@link #operateTranspose(RealVector)}. If {@code true} is returned, 101 * {@link #operateTranspose(RealVector)} should not throw 102 * {@code UnsupportedOperationException}. The default implementation returns 103 * {@code false}. 104 * 105 * @return {@code false} 106 */ 107 public boolean isTransposable() { 108 return false; 109 } 110 }