casacore
Loading...
Searching...
No Matches
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
65namespace 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