Arrays.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1