casacore
LSQMatrix.h
Go to the documentation of this file.
1 //# LSQMatrix.h: Support class for the LSQ package
2 //# Copyright (C) 2004,2005,2006
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef SCIMATH_LSQMATRIX_H
29 #define SCIMATH_LSQMATRIX_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <algorithm>
34 #include <casacore/casa/Utilities/RecordTransformable.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class AipsIO;
40 
41 // <summary> Support class for the LSQ package </summary>
42 // <reviewed reviewer="Wim Brouw" date="2004/03/20" tests="tLSQFit"
43 // demos="">
44 // </reviewed>
45 
46 // <prerequisite>
47 // <li> Some knowledge of Matrix operations
48 // </prerequisite>
49 //
50 // <etymology>
51 // From Least SQuares and Matrix
52 // </etymology>
53 //
54 // <synopsis>
55 // The LSQMatrix class contains the handling of the basic container used
56 // in the <linkto class="LSQFit">LSQFit</linkto> class and its derivatives.
57 // This basic container is a triangular matrix.
58 //
59 // The basic operations provided are referencing and indexing of cells,
60 // rows, columns and diagonal of the triangular matrix.
61 // The class is a private structure, with explicit friends.
62 //
63 // The class contains a number of public methods (with _pub in name) that
64 // can be used anywhere, and which perform index range checking.
65 //
66 // The contents can be saved in a record (<src>toRecord</src>),
67 // and an object can be created from a record (<src>fromRecord</src>).
68 // The record identifier is 'tmat'.
69 // </synopsis>
70 //
71 // <example>
72 // See the <linkto class="LSQFit">LSQFit</linkto> class for its use.
73 // </example>
74 //
75 // <motivation>
76 // The class was written to isolate the handling of the normal equations
77 // used in the <src>LSQ</src> classes.
78 // </motivation>
79 //
80 // <todo asof="2004/03/20">
81 // <li> Look in possibility of an STL iterator along row, column and
82 // diagonal
83 // </todo>
84 
86  //# Friends
87  friend class LSQFit;
88 
89  public:
90  // A set of public interface functions. Checks for index ranges are made,
91  // and zero or null returned if error.
92  // <group>
93  // Get row pointer in normal equation (points to element <src>[i][0]</src>)
94  Double *row_pub(uInt i) const { return (i<n_p) ? row(i) : 0; };
95  // Get next row or previous row pointer in normal equation if the pointer
96  // <src>row</src> is at row <src>i</src>.
97  // <group>
98  void incRow_pub(Double *&row, uInt i) const { if (i<n_p-1) incRow(row,i); };
99  void decRow_pub(Double *&row, uInt i) const { if (i>0) decRow(row,i); };
100  // </group>
101  // Get diagonal element pointer <src>[i][i]</src>
102  Double *diag_pub(uInt i) const { return ((i<n_p) ? diag(i) : 0); };
103  // Get length of triangular array
104  uInt nelements_pub() const { return (len_p); };
105  // Get number of rows
106  uInt nrows_pub() const { return n_p; };
107  // Make diagonal element 1 if zero (Note that this is always called when
108  // <src>invert()</src> is called). Only n-length sub-matrix is done.
109  void doDiagonal_pub(uInt n) { if (n<n_p) doDiagonal(n); }
110  // Multiply n-length of diagonal with <src>1+fac</src>
111  void mulDiagonal_pub(uInt n, Double fac) { if (n<n_p) mulDiagonal(n,fac); };
112  // Add <src>fac</src> to n-length of diagonal
113  void addDiagonal_pub(uInt n, Double fac) { if (n<n_p) addDiagonal(n,fac); };
114  // Determine max of abs values of n-length of diagonal
115  Double maxDiagonal_pub(uInt n){ return ((n<n_p) ? maxDiagonal(n) : 0); };
116  // </group>
117 
118  private:
119  //# Constructors
120  // Default constructor (empty, only usable after a <src>set(n)</src>)
122  // Construct an object with the number of rows and columns indicated.
123  // If a <src>Bool</src> argument is present, the number
124  // will be taken as double the number given (assumes complex).
125  // <group>
126  explicit LSQMatrix(uInt n);
128  // </group>
129  // Copy constructor (deep copy)
130  LSQMatrix(const LSQMatrix &other);
131  // Assignment (deep copy)
132  LSQMatrix &operator=(const LSQMatrix &other);
133 
134  //# Destructor
136 
137  //# Operators
138  // Index an element in the triangularised matrix
139  // <group>
140  Double &operator[](uInt index) { return (trian_p[index]); };
141  Double operator[](uInt index) const { return (trian_p[index]); };
142  // </group>
143 
144  //# General Member Functions
145  // Reset all data to zero
146  void reset() { clear(); };
147  // Set new sizes (default is for Real, a Bool argument will make it complex)
148  // <group>
149  void set(uInt n);
150  void set(uInt n, Bool);
151  // </group>
152  // Get row pointer in normal equation (points to element <src>[i][0]</src>)
153  Double *row(uInt i) const { return &trian_p[((n2m1_p-i)*i)/2]; };
154  // Get next row or previous row pointer in normal equation if the pointer
155  // <src>row</src> is at row <src>i</src>.
156  // <group>
157  void incRow(Double *&row, uInt i) const { row += nm1_p-i; };
158  void decRow(Double *&row, uInt i) const { row -= n_p-i; };
159  // </group>
160  // Get diagonal element pointer <src>[i][i]</src>
161  Double *diag(uInt i) const { return &trian_p[((n2p1_p-i)*i)/2]; };
162  // Get length of triangular array
163  uInt nelements() const { return (len_p); };
164  // Get number of rows
165  uInt nrows() const { return n_p; };
166  // Copy data.
167  void copy(const LSQMatrix &other);
168  // Initialise matrix
169  void init();
170  // Clear matrix
171  void clear();
172  // De-initialise matrix
173  void deinit();
174  // Make diagonal element 1 if zero (Note that this is always called when
175  // <src>invert()</src> is called). Only n-length sub-matrix is done.
176  void doDiagonal(uInt n);
177  // Multiply n-length of diagonal with <src>1+fac</src>
178  void mulDiagonal(uInt n, Double fac);
179  // Add <src>fac</src> to n-length of diagonal
180  void addDiagonal(uInt n, Double fac);
181  // Determine max of abs values of n-length of diagonal
183  // Create a Matrix from a record. An error message is generated, and False
184  // returned if an invalid record is given. A valid record will return True.
185  // Error messages are postfixed to error.
186  // <group>
187  Bool fromRecord(String &error, const RecordInterface &in);
188  // </group>
189  // Create a record from an LSQMatrix. The return will be False and an error
190  // message generated only if the object does not contain a valid Matrix.
191  // Error messages are postfixed to error.
192  Bool toRecord(String &error, RecordInterface &out) const;
193  // Get identification of record
194  const String &ident() const;
195  // Convert a <src>carray</src> to/from a record. Field only written if
196  // non-zero length. No carray created if field does not exist on input.
197  // False returned if unexpectedly no data available for non-zero length
198  // (put), or a field has zero length vector(get).
199  // <group>
200  static Bool putCArray(String &error, RecordInterface &out,
201  const String &fname,
202  uInt len, const Double * const in);
203  static Bool getCArray(String &error, const RecordInterface &in,
204  const String &fname,
205  uInt len, Double *&out);
206  static Bool putCArray(String &error, RecordInterface &out,
207  const String &fname,
208  uInt len, const uInt * const in);
209  static Bool getCArray(String &error, const RecordInterface &in,
210  const String &fname,
211  uInt len, uInt *&out);
212  // </group>
213 
214  // Save or restore using AipsIO.
215  void fromAipsIO (AipsIO& in);
216  void toAipsIO (AipsIO& out) const;
217  static void putCArray (AipsIO& out, uInt len, const Double* const in);
218  static void getCArray (AipsIO& in, uInt len, Double*& out);
219  static void putCArray (AipsIO& out, uInt len, const uInt* const in);
220  static void getCArray (AipsIO& in, uInt len, uInt*& out);
221 
222  //# Data
223  // Matrix size (linear size)
225  // Derived sizes (all 0 if n_p equals 0)
226  // <group>
227  // Total size
229  // <src>n-1</src>
231  // <src>2n-1</src>
233  // <src>2n+1</src>
235  // </group>
236  // Matrix (triangular n_p * n_p)
238  // Record field names
239  static const String tmatsiz;
240  static const String tmatdat;
241  // <group>
242  // </group>
243  //
244 };
245 
246 
247 } //# NAMESPACE CASACORE - END
248 
249 #endif
static Bool putCArray(String &error, RecordInterface &out, const String &fname, uInt len, const uInt *const in)
void reset()
Reset all data to zero.
Definition: LSQMatrix.h:146
LSQMatrix()
Default constructor (empty, only usable after a set(n))
void addDiagonal_pub(uInt n, Double fac)
Add fac to n-length of diagonal.
Definition: LSQMatrix.h:113
static Bool putCArray(String &error, RecordInterface &out, const String &fname, uInt len, const Double *const in)
Convert a carray to/from a record.
void decRow_pub(Double *&row, uInt i) const
Definition: LSQMatrix.h:99
void addDiagonal(uInt n, Double fac)
Add fac to n-length of diagonal.
void toAipsIO(AipsIO &out) const
void clear()
Clear matrix.
static const String tmatsiz
Record field names.
Definition: LSQMatrix.h:239
Double * trian_p
Matrix (triangular n_p * n_p)
Definition: LSQMatrix.h:237
void set(uInt n, Bool)
Double operator[](uInt index) const
Definition: LSQMatrix.h:141
static void getCArray(AipsIO &in, uInt len, Double *&out)
void incRow_pub(Double *&row, uInt i) const
Get next row or previous row pointer in normal equation if the pointer row is at row i.
Definition: LSQMatrix.h:98
void decRow(Double *&row, uInt i) const
Definition: LSQMatrix.h:158
void deinit()
De-initialise matrix.
uInt nrows() const
Get number of rows.
Definition: LSQMatrix.h:165
LSQMatrix(uInt n)
Construct an object with the number of rows and columns indicated.
static void getCArray(AipsIO &in, uInt len, uInt *&out)
uInt nelements_pub() const
Get length of triangular array.
Definition: LSQMatrix.h:104
Bool toRecord(String &error, RecordInterface &out) const
Create a record from an LSQMatrix.
LSQMatrix & operator=(const LSQMatrix &other)
Assignment (deep copy)
static Bool getCArray(String &error, const RecordInterface &in, const String &fname, uInt len, Double *&out)
static void putCArray(AipsIO &out, uInt len, const Double *const in)
Double * row_pub(uInt i) const
A set of public interface functions.
Definition: LSQMatrix.h:94
void set(uInt n)
Set new sizes (default is for Real, a Bool argument will make it complex)
void fromAipsIO(AipsIO &in)
Save or restore using AipsIO.
Double * diag(uInt i) const
Get diagonal element pointer [i][i]
Definition: LSQMatrix.h:161
Double * diag_pub(uInt i) const
Get diagonal element pointer [i][i]
Definition: LSQMatrix.h:102
void incRow(Double *&row, uInt i) const
Get next row or previous row pointer in normal equation if the pointer row is at row i.
Definition: LSQMatrix.h:157
LSQMatrix(uInt n, Bool)
void doDiagonal(uInt n)
Make diagonal element 1 if zero (Note that this is always called when invert() is called).
Double maxDiagonal(uInt n)
Determine max of abs values of n-length of diagonal.
Double maxDiagonal_pub(uInt n)
Determine max of abs values of n-length of diagonal.
Definition: LSQMatrix.h:115
Double * row(uInt i) const
Get row pointer in normal equation (points to element [i][0])
Definition: LSQMatrix.h:153
uInt len_p
Derived sizes (all 0 if n_p equals 0)
Definition: LSQMatrix.h:228
uInt n_p
Matrix size (linear size)
Definition: LSQMatrix.h:224
static Bool getCArray(String &error, const RecordInterface &in, const String &fname, uInt len, uInt *&out)
void mulDiagonal(uInt n, Double fac)
Multiply n-length of diagonal with 1+fac
void init()
Initialise matrix.
void mulDiagonal_pub(uInt n, Double fac)
Multiply n-length of diagonal with 1+fac
Definition: LSQMatrix.h:111
void copy(const LSQMatrix &other)
Copy data.
void doDiagonal_pub(uInt n)
Make diagonal element 1 if zero (Note that this is always called when invert() is called).
Definition: LSQMatrix.h:109
Double & operator[](uInt index)
Index an element in the triangularised matrix.
Definition: LSQMatrix.h:140
static void putCArray(AipsIO &out, uInt len, const uInt *const in)
uInt nrows_pub() const
Get number of rows.
Definition: LSQMatrix.h:106
const String & ident() const
Get identification of record.
uInt nelements() const
Get length of triangular array.
Definition: LSQMatrix.h:163
static const String tmatdat
Definition: LSQMatrix.h:240
Bool fromRecord(String &error, const RecordInterface &in)
Create a Matrix from a record.
LSQMatrix(const LSQMatrix &other)
Copy constructor (deep copy)
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
double Double
Definition: aipstype.h:55