casacore
Arrays.h
Go to the documentation of this file.
1 //# Arrays.h: A module implementing multidimensional arrays and operations
2 //# Copyright (C) 1995,1999,2000
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 CASA_ARRAYS_H
29 #define CASA_ARRAYS_H
30 
31 #include <casacore/casa/aips.h>
32 
33 #include <casacore/casa/Arrays/IPosition.h>
34 #include <casacore/casa/Arrays/Slicer.h>
35 #include <casacore/casa/Arrays/Slice.h>
36 
37 #include <casacore/casa/Arrays/Array.h>
38 #include <casacore/casa/Arrays/Vector.h>
39 #include <casacore/casa/Arrays/Matrix.h>
40 #include <casacore/casa/Arrays/Cube.h>
41 
42 #include <casacore/casa/Arrays/ArrayIter.h>
43 #include <casacore/casa/Arrays/MatrixIter.h>
44 #include <casacore/casa/Arrays/VectorIter.h>
45 
46 #include <casacore/casa/Arrays/ArrayMath.h>
47 #include <casacore/casa/Arrays/ArrayPartMath.h>
48 #include <casacore/casa/Arrays/MatrixMath.h>
49 #include <casacore/casa/Arrays/ArrayLogical.h>
50 #include <casacore/casa/IO/ArrayIO.h>
51 #include <casacore/casa/Arrays/ArrayError.h>
52 
53 #include <casacore/casa/Arrays/LogiArray.h>
54 #include <casacore/casa/Arrays/LogiVector.h>
55 #include <casacore/casa/Arrays/LogiMatrix.h>
56 #include <casacore/casa/Arrays/LogiCube.h>
57 
58 #include <casacore/casa/Arrays/MaskedArray.h>
59 #include <casacore/casa/Arrays/MaskArrMath.h>
60 #include <casacore/casa/Arrays/MaskArrLogi.h>
61 #include <casacore/casa/Arrays/MaskArrIO.h>
62 #include <casacore/casa/Arrays/MaskLogiArr.h>
63 
64 
65 namespace casacore { //# NAMESPACE CASACORE - BEGIN
66 
67 // <module>
68 //
69 // <summary>
70 // A module implementing multidimensional arrays and operations.
71 // </summary>
72 
73 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" demos="">
74 // </reviewed>
75 
76 // <etymology>
77 // This module provides classes and global functions for multidimensional
78 // arrays.
79 // </etymology>
80 //
81 // <synopsis>
82 // Arrays have traditionally played an important role in scientific
83 // computation. While it is certainly true that some of the reliance on
84 // arrays was due to the paucity of other data structures in FORTRAN, it
85 // is also true that computation on arrays reflects the common occurrence
86 // of regularly sampled multi-dimensioned data in science.
87 //
88 // The <linkto module=Lattices>Lattices</linkto> are a generalization
89 // of Arrays. They can handle memory- and disk-based arrays as well
90 // as other types of arrays (eg. expressions).
91 //
92 // The module consists of various parts:
93 // <ul>
94 
95 // <li>
96 // <linkto class=Array>Array</linkto> is the basic array class. It is
97 // only templated on data type, not on dimensionality like the array
98 // classes in Blitz and boost.
99 // It has a non-templated base class ArrayBase.
100 //
101 // <linkto class=Vector>Vector</linkto>,
102 // <linkto class=Matrix>Matrix</linkto>, and
103 // <linkto class=Cube>Cube</linkto>
104 // are the one, two, and three dimensional specializations respectively of
105 // Array.
106 //
107 // <li>
108 // <linkto class=MaskedArray>MaskedArray</linkto> is the class used to mask
109 // an Array for operations on that Array.
110 //
111 // <li>
112 // <linkto class=ArrayError>ArrayError</linkto> is the base class for all
113 // Array exception classes.
114 //
115 // <li>
116 // There are several ways o iterate through an array:
117 // <ul>
118 // <li> The STL-style Array iterators can be used to iterate
119 // element by element through an array. This is the fastest way.
120 // They also make it possible to virtually extend an array (called
121 // shape broadcasting in numpy) and to reorder the iteration axes.
122 // <li> <linkto class=ArrayIterator>ArrayIterator</linkto> can be used to
123 // iterate line by line, plane by plane, etc. through an array.
124 // Each subset is an array in itself, thus can be iterated again.
125 // <li> The Array function operators () can be used to get a subset from
126 // an array. They can be used for iteration, but that is slower than
127 // the ways mentioned above.
128 // <li> The array operator[] can be used to get the i-th subset. It can
129 // be used for iteration, but ArrayIterator does the same and is faster.
130 // <li> ArrayAccessor is useful when neighbours of an array element have
131 // to be visited.
132 // <li> <linkto class=LatticeIterator>LatticeIterator</linkto> can be used on
133 // a <linkto class=ArrayLattice>ArrayLattice</linkto> object for more
134 // advanced iteration. However, they are part of the lattices packages.
135 // </ul>
136 //
137 // <li>
138 // <linkto group="ArrayMath.h#Array mathematical operations">Mathematical</linkto>,
139 // <linkto group="ArrayLogical.h#Array logical operations">logical</linkto>,
140 // <linkto group="ArrayPartMath.h#Array partial operations">chunked mathematical and logical</linkto>,
141 // <linkto group="ArrayIO.h#Array IO">IO</linkto>,
142 // and other useful operations are provided for
143 // Arrays and MaskedArrays.
144 //
145 // ArrayMath also defines various STL-style transform functions that use the
146 // Array iterators and functors like Plus to apply the mathematical and logical
147 // operations. They can, however, also be used directly on arrays of
148 // different types making it possible to, say, add a Complex and double array
149 // with a DComplex result.
150 // <br>It also has a <src>transformInPlace</src> to avoid needless incrementing
151 // of iterators which have to be done when using <src>std::transform</src>
152 // for in-place operations.
153 //
154 // <li>
155 // Orthogonal n-space descriptors - useful when a shape of an Array is
156 // needed or when a sub-region within an Array is required.
157 // <ul>
158 // <li> The <linkto class="IPosition">IPosition</linkto> class name is a
159 // concatenation of "Integer Position." IPosition objects are normally
160 // used to index into, and define the shapes of, Arrays and Lattices. For
161 // example, if you have a 5-dimensional array, you need an IPosition of
162 // length 5 to index into the array (or to define its shape, etc.). It is
163 // essentially a vector of integers. The IPosition vector may point to
164 // the "top right corner" of some shape, or it may be an indicator of a
165 // specific position in n-space. The interpretation is context dependent.
166 // The constructor consists of an initial argument which specifies the
167 // number of axes, followed by the appropriate number of respective axis
168 // lengths. Thus the constructor needs N+1 arguments for an IPosition
169 // of length N. IPositions have the standard integer math relationships
170 // defined. The dimensionality of the operator arguments must be the
171 // same.
172 //<srcblock>
173 // // Make a shape with three axes, x = 24, y = 48, z = 16;
174 // IPosition threeSpace(3, 24, 48, 16);
175 //
176 // // get the value of the ith axis (note: C++ is zero based!)
177 // Int xShape = threeSpace(0);
178 // Int zShape = threeSpace(2);
179 //
180 // // construct another with all three axes values equal to 666;
181 // IPosition threeSpaceAlso(3,666);
182 //
183 // // do math with the IPositions...
184 // threeSpace += threeSpaceAlso;
185 // AlwaysAssert(threeSpace(1) == 714, AipsError);
186 // </srcblock>
187 //
188 // <li> The <linkto class="Slicer">Slicer</linkto> class name may be
189 // thought of as a short form of "n-Dimensional Slice Specifier."
190 // This object is used to bundle into one place all the information
191 // necessary to specify a regular subregion within an Array or Lattice.
192 // In other words, Slicer holds the location of a "slice" of a
193 // greater whole. Construction is with up to 3 IPositions: the start
194 // location of the subspace within the greater space; the shape or end
195 // location of the subspace within the greater space; and the stride,
196 // or multiplier to be used for each axis. The stride gives the user
197 // the chance to use every i-th piece of data, rather than every
198 // position on the axis.
199 // <br>
200 // It is possible to leave some values in the given start or end/length
201 // unspecified. Such unspecified values default to the boundaries of the
202 // array to which the slicer will be applied.
203 // It is also possible to use a non-zero origin when applying the slicer
204 // to an array.
205 //
206 // <srcblock>
207 // // Define the shape of an array.
208 // IPosition shape(2,20,30);
209 //
210 // // Also define an origin.
211 // IPosition origin(2,-5,15);
212 //
213 // // Now define some Slicers, initially only specify the start
214 // // Its length and stride will be 1.
215 // Slicer ns0(IPosition(2,0,24));
216 //
217 // // make some IPositions as holders for the rest of the information
218 // IPosition blc,trc,inc;
219 //
220 // // Use the shape and origin to fill our holders assuming we want to use
221 // // as much of the Array as possible.
222 // ns0.inferShapeFromSource (shape, origin, blc,trc,inc);
223 //
224 // // print out the new info ie. blc=[5,9],trc=[5,9],inc=[1,1]
225 // cout << blc << trc << inc << endl;
226 //
227 // // Build a slicer with temporaries for arguments. The arguments are:
228 // // start position, end position and step increment. The Slicer::endIsLast
229 // // argument specifies that the end position is the trc. The alternative
230 // // is Slicer::endIsLength which specifies that the end argument is the
231 // // shape of the resulting subregion.
232 // //
233 // Slicer ns1(IPosition(2,3,5), IPosition(2,13,21), IPosition(2,3,2),
234 // Slicer::endIsLast);
235 // IPosition shp = ns1.inferShapeFromSource (shape, blc,trc,inc);
236 // //
237 // // print out the new info ie. shp=[4,9],blc=[3,5],trc=[12,21],inc=[3,2]
238 // cout << shp << blc << trc << inc << endl;
239 // </srcblock>
240 // </ul>
241 // </ul>
242 
243 // The <linkto module=Arrays:classes>detailed discussions</linkto> for the
244 // classes and global functions will describe how to use them.
245 // </synopsis>
246 //
247 // </module>
248 
249 
250 } //# NAMESPACE CASACORE - END
251 
252 #endif
this file contains all the compiler specific defines
Definition: mainpage.dox:28