1 /* linbox/blackbox/archetype.h 2 * Copyright (C) 1999-2005 William J Turner, 3 * 2001 Bradford Hovinen 4 * 5 * Written by W. J. Turner <wjturner@acm.org>, 6 * Bradford Hovinen <hovinen@cis.udel.edu> 7 * and bds. 8 * 9 * 10 * ========LICENCE======== 11 * This file is part of the library LinBox. 12 * 13 * LinBox is free software: you can redistribute it and/or modify 14 * it under the terms of the GNU Lesser General Public 15 * License as published by the Free Software Foundation; either 16 * version 2.1 of the License, or (at your option) any later version. 17 * 18 * This library is distributed in the hope that it will be useful, 19 * but WITHOUT ANY WARRANTY; without even the implied warranty of 20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 * Lesser General Public License for more details. 22 * 23 * You should have received a copy of the GNU Lesser General Public 24 * License along with this library; if not, write to the Free Software 25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 26 * ========LICENCE======== 27 *. 28 */ 29 30 /*!@file blackbox/archetype.h 31 * @ingroup blackbox 32 * @brief NO DOC 33 * @see \ref Archetypes 34 */ 35 36 #ifndef __LINBOX_blackbox_archetype_H 37 #define __LINBOX_blackbox_archetype_H 38 39 namespace LinBox 40 { 41 42 /*- Note the original archetype concept has been given 43 * up in favor of supporting template members. 44 45 46 * Found in file \URL{linbox/blackbox/archetype.h}. 47 * Base class from which derived concrete blackbox classes. 48 * Unlike the LinBox field common object interface, 49 * the common object interface for LinBox BlackBoxes does not require 50 * the copy constructor. All object management routines are given 51 * through virtual clone and killclone methods. This allows the base 52 * object to be the archetype, which is not possible for LinBox fields. 53 * 54 * In general, there are three uses of archetypes: 55 * \begin{enumerate} 56 * \item To define the interface, i.e., document what an 57 * explicitly designed field class must have. This is 58 * useful, for instance, in building a wrapper or adaptor 59 * to an existing library. 60 * \item To distribute compiled code and ease the testing of 61 * library components. 62 * \item To control code bloat. 63 * \end{enumerate} 64 * Because of their use of virtual member funtions, these archetypes can be 65 * inefficient. 66 * 67 * @param Vector \ref LinBox dense or sparse vector of field elements 68 */ 69 70 /*- 71 @brief BlackBox base class and archetype 72 73 This archetype is an abstract base class for blackbox matrix classes. 74 The key member functions are \c apply, \c applyTranspose, \c rowdim, \c coldim}. 75 They are pure virtual, and hence are implemented in each child class. 76 77 Concrete classes inheriting from the archetype 78 use a variety of representation schemes for matrices internally. 79 All provide the blackbox interface described here and can be used 80 interchangably in blackbox algorithms. 81 Some also implement a dense matrix or sparse matrix interface to support elimination 82 techniques. Each has unique constructor(s) reflecting it's specific scheme for representing 83 a linear operator. 84 85 Algorithms written with a Blackbox template parameter 86 may be compiled against any of these classes specifically or may be separately compiled 87 against the archetype. Algorithms may also be written with a BlackboxArchetype parameter 88 and then called with an instance of a concrete blackbox class. 89 In contrast with the situation for \ref Field s there is 90 negligible performance cost for separate compilation here. 91 92 {\bf Template Parameter:} Vector - A type meeting the LinBox \ref VectorArchetype interface. 93 Vectors of this type are the normal arguments to \c apply and \c applyTranspose. 94 95 @see \ref ../archetypes for general discussion of LinBox archetypes. 96 */ 97 98 /** \brief showing the member functions provided by all blackbox matrix classes. 99 100 This simple interface is all that is needed for the blackbox 101 algorithms. Alternatively, the matrix archetype provides individual 102 matrix entry access, as needed by some algorithms, such as elimination 103 methods. 104 105 \ingroup blackbox 106 */ 107 // template <class Field> 108 class BlackboxArchetype { //: public BlackboxInterface 109 public: 110 111 /*- Serves in place of copy constructor. 112 * Required because constructors cannot be virtual. 113 * Make a copy of the BlackboxArchetype object. 114 * @return pointer to new blackbox object 115 */ 116 // clone no longer needed, since no archetype 117 // virtual BlackboxArchetype* clone () const = 0; 118 // Should we have clone conform more to copy construction? 119 // clone(A) = make this a copy of A. -bds 120 121 // apply variants // 122 123 /** \brief y := Ax, matrix-vector product. 124 125 The vector x must be of size A.coldim(), where A is this blackbox. 126 On entry to apply, the vector y must be of size A.rowdim(). 127 Neither vector has it's size or capacity modified by apply. Apply is not 128 responsible for the validity of the sizes, which may or may not be checked. 129 The two vectors may not overlap in memory. 130 @param y it's entries are overwritten and a reference to it is also returned to allow for 131 use in nested expressions. 132 @param x it's entries are the input data. 133 */ 134 template <class InVector, class OutVector> 135 OutVector &apply (OutVector &y, const InVector &x) const; 136 137 /** \brief y := Ax, matrix-vector product using a handle for ... 138 139 The handle serves as "protection from the future". The idea is that the handle 140 could allow the blackbox to operate more as a pure container, with the field 141 (or other functionality such as dot product) provided through the handle. 142 143 However, there are no known current uses (2003 june). 144 */ 145 template <class InVector, class OutVector> 146 OutVector &apply (OutVector &y, const InVector &x, void *handle) const; 147 148 // applyTranspose variants // 149 150 /** \brief y := xA, vector-matrix product. 151 152 (Or from a column vector viewpoint: y := A<sup>T</sup> x, 153 matrix transpose times vector product. ) 154 155 The vector x must be of size A.rowdim(), where A is this blackbox. 156 On entry to apply, the vector y must be of size A.coldim(). 157 Neither vector has it's size or capacity modified by applyTranspose. ApplyTranspose is not 158 responsible for the validity of the sizes, which may or may not be checked. 159 The two vectors may not overlap in memory. 160 @param y it's entries are overwritten and a reference to it is also returned to allow for 161 use in nested expressions. 162 @param x it's entries are the input data. 163 */ 164 template <class InVector, class OutVector> 165 OutVector &applyTranspose (OutVector &y, const InVector &x) const; 166 167 /** \brief y := xA, vector-matrix product using a handle for ... 168 169 The handle serves as "protection from the future". The idea is that the handle 170 could allow the blackbox to operate more as a pure container, with the field 171 (or other functionality such as dot product) provided through the handle. 172 173 However, there are no known current uses (2003 june). 174 */ 175 template <class InVector, class OutVector> 176 OutVector &applyTranspose (OutVector &y, const InVector &x, void *handle) const; 177 178 /** \brief Returns the number of rows of the matrix. 179 180 This may be zero or greater. Currently matrix size beyond size_t is not supported. 181 */ 182 size_t rowdim () const; 183 184 /** \brief Returns the number of columns of the matrix. 185 186 This may be zero or greater. Currently matrix size beyond size_t is not supported. 187 */ 188 size_t coldim () const; 189 190 #if 0 191 /** \brief default constructor. 192 * Note: Most blacbbox classes will have a constructor that takes 193 * the field and size as parameters. 194 195 * Developer: It is expected that each blackbox class will 196 have constructors from appropriate arguments as well. 197 Make a point to document these. 198 */ 199 BlackboxArchetype (); 200 201 /** \brief copy constructor 202 203 Subsequent modification of either source or copy does not affect the other. 204 */ 205 BlackboxArchetype (const BlackboxArchetype& B); 206 207 ///\brief assignment 208 BlackboxArchetype& operator=(const BlackboxArchetype& B); 209 210 /** \brief destructor 211 212 Releases all associated memory. 213 */ 214 215 ~BlackboxArchetype(); 216 217 #endif 218 219 }; // BlackBox Archetype 220 221 } // namespace LinBox 222 223 #endif // __LINBOX_blackbox_archetype_H 224 225 // Local Variables: 226 // mode: C++ 227 // tab-width: 4 228 // indent-tabs-mode: nil 229 // c-basic-offset: 4 230 // End: 231 // vim:sts=4:sw=4:ts=4:et:sr:cino=>s,f0,{0,g0,(0,\:0,t0,+0,=s 232