00001 //# Arrays.h: A module implementing multidimensional arrays and operations 00002 //# Copyright (C) 1995,1999,2000 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef CASA_ARRAYS_H 00029 #define CASA_ARRAYS_H 00030 00031 #include <casacore/casa/aips.h> 00032 00033 #include <casacore/casa/Arrays/IPosition.h> 00034 #include <casacore/casa/Arrays/Slicer.h> 00035 #include <casacore/casa/Arrays/Slice.h> 00036 00037 #include <casacore/casa/Arrays/Array.h> 00038 #include <casacore/casa/Arrays/Vector.h> 00039 #include <casacore/casa/Arrays/Matrix.h> 00040 #include <casacore/casa/Arrays/Cube.h> 00041 00042 #include <casacore/casa/Arrays/ArrayIter.h> 00043 #include <casacore/casa/Arrays/MatrixIter.h> 00044 #include <casacore/casa/Arrays/VectorIter.h> 00045 00046 #include <casacore/casa/Arrays/ArrayMath.h> 00047 #include <casacore/casa/Arrays/ArrayPartMath.h> 00048 #include <casacore/casa/Arrays/MatrixMath.h> 00049 #include <casacore/casa/Arrays/ArrayLogical.h> 00050 #include <casacore/casa/Arrays/ArrayIO.h> 00051 #include <casacore/casa/Arrays/ArrayError.h> 00052 00053 #include <casacore/casa/Arrays/LogiArray.h> 00054 #include <casacore/casa/Arrays/LogiVector.h> 00055 #include <casacore/casa/Arrays/LogiMatrix.h> 00056 #include <casacore/casa/Arrays/LogiCube.h> 00057 00058 #include <casacore/casa/Arrays/MaskedArray.h> 00059 #include <casacore/casa/Arrays/MaskArrMath.h> 00060 #include <casacore/casa/Arrays/MaskArrLogi.h> 00061 #include <casacore/casa/Arrays/MaskArrIO.h> 00062 #include <casacore/casa/Arrays/MaskLogiArr.h> 00063 00064 00065 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00066 00067 // <module> 00068 // 00069 // <summary> 00070 // A module implementing multidimensional arrays and operations. 00071 // </summary> 00072 00073 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" demos=""> 00074 // </reviewed> 00075 00076 // <etymology> 00077 // This module provides classes and global functions for multidimensional 00078 // arrays. 00079 // </etymology> 00080 // 00081 // <synopsis> 00082 // Arrays have traditionally played an important role in scientific 00083 // computation. While it is certainly true that some of the reliance on 00084 // arrays was due to the paucity of other data structures in FORTRAN, it 00085 // is also true that computation on arrays reflects the common occurrence 00086 // of regularly sampled multi-dimensioned data in science. 00087 // 00088 // The <linkto module=Lattices>Lattices</linkto> are a generalization 00089 // of Arrays. They can handle memory- and disk-based arrays as well 00090 // as other types of arrays (eg. expressions). 00091 // 00092 // The module consists of various parts: 00093 // <ul> 00094 00095 // <li> 00096 // <linkto class=Array>Array</linkto> is the basic array class. It is 00097 // only templated on data type, not on dimensionality like the array 00098 // classes in Blitz and boost. 00099 // It has a non-templated base class ArrayBase. 00100 // 00101 // <linkto class=Vector>Vector</linkto>, 00102 // <linkto class=Matrix>Matrix</linkto>, and 00103 // <linkto class=Cube>Cube</linkto> 00104 // are the one, two, and three dimensional specializations respectively of 00105 // Array. 00106 // 00107 // <li> 00108 // <linkto class=MaskedArray>MaskedArray</linkto> is the class used to mask 00109 // an Array for operations on that Array. 00110 // 00111 // <li> 00112 // <linkto class=ArrayError>ArrayError</linkto> is the base class for all 00113 // Array exception classes. 00114 // 00115 // <li> 00116 // There are several ways o iterate through an array: 00117 // <ul> 00118 // <li> The STL-style Array iterators can be used to iterate 00119 // element by element through an array. This is the fastest way. 00120 // They also make it possible to virtually extend an array (called 00121 // shape broadcasting in numpy) and to reorder the iteration axes. 00122 // <li> <linkto class=ArrayIterator>ArrayIterator</linkto> can be used to 00123 // iterate line by line, plane by plane, etc. through an array. 00124 // Each subset is an array in itself, thus can be iterated again. 00125 // <li> The Array function operators () can be used to get a subset from 00126 // an array. They can be used for iteration, but that is slower than 00127 // the ways mentioned above. 00128 // <li> The array operator[] can be used to get the i-th subset. It can 00129 // be used for iteration, but ArrayIterator does the same and is faster. 00130 // <li> ArrayAccessor is useful when neighbours of an array element have 00131 // to be visited. 00132 // <li> <linkto class=LatticeIterator>LatticeIterator</linkto> can be used on 00133 // a <linkto class=ArrayLattice>ArrayLattice</linkto> object for more 00134 // advanced iteration. However, they are part of the lattices packages. 00135 // </ul> 00136 // 00137 // <li> 00138 // <linkto group="ArrayMath.h#Array mathematical operations">Mathematical</linkto>, 00139 // <linkto group="ArrayLogical.h#Array logical operations">logical</linkto>, 00140 // <linkto group="ArrayPartMath.h#Array partial operations">chunked mathematical and logical</linkto>, 00141 // <linkto group="ArrayIO.h#Array IO">IO</linkto>, 00142 // and other useful operations are provided for 00143 // Arrays and MaskedArrays. 00144 // 00145 // ArrayMath also defines various STL-style transform functions that use the 00146 // Array iterators and functors like Plus to apply the mathematical and logical 00147 // operations. They can, however, also be used directly on arrays of 00148 // different types making it possible to, say, add a Complex and double array 00149 // with a DComplex result. 00150 // <br>It also has a <src>transformInPlace</src> to avoid needless incrementing 00151 // of iterators which have to be done when using <src>std::transform</src> 00152 // for in-place operations. 00153 // 00154 // <li> 00155 // Orthogonal n-space descriptors - useful when a shape of an Array is 00156 // needed or when a sub-region within an Array is required. 00157 // <ul> 00158 // <li> The <linkto class="IPosition">IPosition</linkto> class name is a 00159 // concatenation of "Integer Position." IPosition objects are normally 00160 // used to index into, and define the shapes of, Arrays and Lattices. For 00161 // example, if you have a 5-dimensional array, you need an IPosition of 00162 // length 5 to index into the array (or to define its shape, etc.). It is 00163 // essentially a vector of integers. The IPosition vector may point to 00164 // the "top right corner" of some shape, or it may be an indicator of a 00165 // specific position in n-space. The interpretation is context dependent. 00166 // The constructor consists of an initial argument which specifies the 00167 // number of axes, followed by the appropriate number of respective axis 00168 // lengths. Thus the constructor needs N+1 arguments for an IPosition 00169 // of length N. IPositions have the standard integer math relationships 00170 // defined. The dimensionality of the operator arguments must be the 00171 // same. 00172 //<srcblock> 00173 // // Make a shape with three axes, x = 24, y = 48, z = 16; 00174 // IPosition threeSpace(3, 24, 48, 16); 00175 // 00176 // // get the value of the ith axis (note: C++ is zero based!) 00177 // Int xShape = threeSpace(0); 00178 // Int zShape = threeSpace(2); 00179 // 00180 // // construct another with all three axes values equal to 666; 00181 // IPosition threeSpaceAlso(3,666); 00182 // 00183 // // do math with the IPositions... 00184 // threeSpace += threeSpaceAlso; 00185 // AlwaysAssert(threeSpace(1) == 714, AipsError); 00186 // </srcblock> 00187 // 00188 // <li> The <linkto class="Slicer">Slicer</linkto> class name may be 00189 // thought of as a short form of "n-Dimensional Slice Specifier." 00190 // This object is used to bundle into one place all the information 00191 // necessary to specify a regular subregion within an Array or Lattice. 00192 // In other words, Slicer holds the location of a "slice" of a 00193 // greater whole. Construction is with up to 3 IPositions: the start 00194 // location of the subspace within the greater space; the shape or end 00195 // location of the subspace within the greater space; and the stride, 00196 // or multiplier to be used for each axis. The stride gives the user 00197 // the chance to use every i-th piece of data, rather than every 00198 // position on the axis. 00199 // <br> 00200 // It is possible to leave some values in the given start or end/length 00201 // unspecified. Such unspecified values default to the boundaries of the 00202 // array to which the slicer will be applied. 00203 // It is also possible to use a non-zero origin when applying the slicer 00204 // to an array. 00205 // 00206 // <srcblock> 00207 // // Define the shape of an array. 00208 // IPosition shape(2,20,30); 00209 // 00210 // // Also define an origin. 00211 // IPosition origin(2,-5,15); 00212 // 00213 // // Now define some Slicers, initially only specify the start 00214 // // Its length and stride will be 1. 00215 // Slicer ns0(IPosition(2,0,24)); 00216 // 00217 // // make some IPositions as holders for the rest of the information 00218 // IPosition blc,trc,inc; 00219 // 00220 // // Use the shape and origin to fill our holders assuming we want to use 00221 // // as much of the Array as possible. 00222 // ns0.inferShapeFromSource (shape, origin, blc,trc,inc); 00223 // 00224 // // print out the new info ie. blc=[5,9],trc=[5,9],inc=[1,1] 00225 // cout << blc << trc << inc << endl; 00226 // 00227 // // Build a slicer with temporaries for arguments. The arguments are: 00228 // // start position, end position and step increment. The Slicer::endIsLast 00229 // // argument specifies that the end position is the trc. The alternative 00230 // // is Slicer::endIsLength which specifies that the end argument is the 00231 // // shape of the resulting subregion. 00232 // // 00233 // Slicer ns1(IPosition(2,3,5), IPosition(2,13,21), IPosition(2,3,2), 00234 // Slicer::endIsLast); 00235 // IPosition shp = ns1.inferShapeFromSource (shape, blc,trc,inc); 00236 // // 00237 // // print out the new info ie. shp=[4,9],blc=[3,5],trc=[12,21],inc=[3,2] 00238 // cout << shp << blc << trc << inc << endl; 00239 // </srcblock> 00240 // </ul> 00241 // </ul> 00242 00243 // The <linkto module=Arrays:classes>detailed discussions</linkto> for the 00244 // classes and global functions will describe how to use them. 00245 // </synopsis> 00246 // 00247 // </module> 00248 00249 00250 } //# NAMESPACE CASACORE - END 00251 00252 #endif