casacore
TiledShapeStMan.h
Go to the documentation of this file.
1 //# TiledShapeStMan.h: Tiled Data Storage Manager using the shape as id
2 //# Copyright (C) 1998,2000,2001,2002
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 TABLES_TILEDSHAPESTMAN_H
29 #define TABLES_TILEDSHAPESTMAN_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/DataMan/TiledStMan.h>
35 #include <casacore/casa/Containers/Block.h>
36 #include <casacore/casa/BasicSL/String.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 
42 
43 // <summary>
44 // Tiled Data Storage Manager using the shape as id.
45 // </summary>
46 
47 // <use visibility=export>
48 
49 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="">
50 // </reviewed>
51 
52 // <prerequisite>
53 //# Classes you should understand before using this one.
54 // <li> <linkto class=TiledStMan>TiledStMan</linkto>
55 // <li> <linkto class=TSMCube>TSMCube</linkto>
56 // <li> <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
57 // for a discussion of the maximum cache size
58 // </prerequisite>
59 
60 // <etymology>
61 // TiledShapeStMan is the Tiled Storage Manager where the shape is used as id
62 // to support variable shaped arrays.
63 // </etymology>
64 
65 // <synopsis>
66 // TiledShapeStMan is a derivation from TiledStMan, the abstract
67 // tiled storage manager class. A description of the basics
68 // of tiled storage managers is given in the
69 // <linkto module=Tables:TiledStMan>Tables module</linkto> description.
70 // <p>
71 // TiledShapeStMan creates a hypercube for each different shape of
72 // the data arrays. For example, if a table contains line and continuum
73 // data of an observation, it results in 2 hypercubes.
74 // TiledShapeStMan does it all automatically, so it is much easier to use
75 // than class <linkto class=TiledDataStMan>TiledDataStMan</linkto>.
76 // <br>TiledShapeStMan is meant for columns with not too many different
77 // shapes, otherwise looking for a matching hypercube may take too long.
78 // When many different shapes are used, class
79 // <linkto class=TiledCellStMan>TiledCellStMan</linkto>
80 // should be used instead.
81 //
82 // TiledShapeStMan has the following (extra) properties:
83 // <ul>
84 // <li> It can only handle columns containing arrays, thus not scalars.
85 // <li> Addition of a row sets the appropriate data arrays
86 // in that row temporarily to an empty hypercube.
87 // However, if the data arrays have a fixed shape, the
88 // shape is known and the hypercube can be generated immediately.
89 // Note that for a fixed shape column, one can as well use class
90 // <linkto class=TiledColumnStMan>TiledColumnStMan</linkto>.
91 // <li> When the shape of the data array in a row is set for the
92 // first time, it is known which hypercube should be used or
93 // if a new hypercube has to be created.
94 // <br>Note that is is not possible to change the shape of an array.
95 // If that is needed, TiledCellStMan should be used instead.
96 // <br>Note that a hypercolumn has a given dimensionality, so each
97 // data cell in the hypercolumn has to match that dimensionality.
98 // <li> Although there are multiple hypercubes, an id value is not needed.
99 // The shape serves as the id value.
100 // <li> Coordinates for the hypercubes can be defined and (of course)
101 // their shapes have to match the hypercube shape.
102 // Their values have to be put explicitly (so it is not possible
103 // to define them via an addHypercube call like in
104 // <linkto class=TiledDataStMan>TiledDataStMan</linkto>).
105 // It is possible to put the coordinate values before or after
106 // the shape of the data array in that row is defined.
107 // <li> It is possible to define a (default) tile shape in the
108 // TiledShapeStMan constructor. When setting the shape of the
109 // array in a row (using <linkto class=ArrayColumn>
110 // ArrayColumn::setShape</linkto>), it is possible to override
111 // that default for the hypercube in this particular row.
112 // However, since the tile shape is only used when creating
113 // a hypercube, using an overriding tile shape makes only
114 // sense when a given array shape is used for the first time.
115 // Note that the dimensionality of the hypercube is one higher
116 // than the dimensionality of the data arrays (since the hypercube
117 // contains multiple rows). It means that the number of values in
118 // tile shape can be one more than the number of axes in the data
119 // array. The last tile shape value defaults to 1; the other
120 // tile shape values have to be defined.
121 // </ul>
122 // </synopsis>
123 
124 // <motivation>
125 // TiledDataStMan proved to be very powerful, but also a bit cumbersome
126 // to use because a few special functions need to be called.
127 // TiledShapeStMan alleviates that problem.
128 // </motivation>
129 
130 // <example>
131 // <srcblock>
132 // // Define the table description and the columns in it.
133 // TableDesc td ("", "1", TableDesc::Scratch);
134 // td.addColumn (ArrayColumnDesc<float> ("RA", 1));
135 // td.addColumn (ArrayColumnDesc<float> ("Dec", 1));
136 // td.addColumn (ScalarColumnDesc<float> ("Velocity"));
137 // td.addColumn (ArrayColumnDesc<float> ("Image", 2));
138 // // Define the 3-dim hypercolumn with its data and coordinate columns.
139 // // Note that its dimensionality must be one higher than the dimensionality
140 // // of the data cells.
141 // td.defineHypercolumn ("TSMExample",
142 // 3,
143 // stringToVector ("Image"),
144 // stringToVector ("RA,Dec,Velocity"));
145 // // Now create a new table from the description.
146 // SetupNewTable newtab("tTiledShapeStMan_tmp.data", td, Table::New);
147 // // Create a TiledShapeStMan storage manager for the hypercolumn
148 // // and bind the columns to it.
149 // // The (default) tile shape has to be specified for the storage manager.
150 // TiledShapeStMan sm1 ("TSMExample", IPosition(3,16,32,32));
151 // newtab.bindAll (sm1);
152 // // Create the table.
153 // Table table(newtab);
154 // // Define the values for the coordinates of the hypercube.
155 // Vector<float> raValues(512);
156 // Vector<float> DecValues(512);
157 // indgen (raValues);
158 // indgen (decValues, float(100));
159 // ArrayColumn<float> ra (table, "RA");
160 // ArrayColumn<float> dec (table, "Dec");
161 // ScalarColumn<float> velocity (table, "Velocity");
162 // ArrayColumn<float> image (table, "Image");
163 // Cube<float> imageValues(IPosition(2,512,512));
164 // indgen (imageValues);
165 // // Write some data into the data columns.
166 // uInt i;
167 // for (i=0; i<64; i++) {
168 // table.addRow();
169 // image.put (i, imageValues);
170 // ra.put (i, raValues);
171 // dec.put (i, decValues);
172 // velocity.put (i, float(i));
173 // }
174 // </srcblock>
175 // Note that in this example the same shape is used for each row,
176 // but it could have been different.
177 // </example>
178 
179 //# <todo asof="$DATE:$">
180 //# A List of bugs, limitations, extensions or planned refinements.
181 //# </todo>
182 
183 
185 {
186 public:
187  // Create a TiledShapeStMan storage manager for the hypercolumn
188  // with the given name.
189  // The hypercolumn name is also the name of the storage manager.
190  // The given maximum cache size (default is unlimited) is persistent,
191  // thus will be reused when the table is read back. Note that the class
192  // <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
193  // allows one to overwrite the maximum cache size temporarily.
194  // <br>The constructor taking a Record expects fields in the record with
195  // the name of the arguments in uppercase. If not defined, their
196  // default value is used.
197  // <group>
198  TiledShapeStMan (const String& hypercolumnName,
200  uInt maximumCacheSize = 0);
201  TiledShapeStMan (const String& hypercolumnName,
202  const Record& spec);
203  // </group>
204 
206 
207  // Clone this object.
208  // It does not clone TSMColumn objects possibly used.
209  virtual DataManager* clone() const;
210 
211  // Get the type name of the data manager (i.e. TiledShapeStMan).
212  virtual String dataManagerType() const;
213 
214  // Return a record containing data manager specifications and info.
215  virtual Record dataManagerSpec() const;
216 
217  // TiledShapeStMan can access a column if there are 2 hypercubes
218  // and the first one is empty.
219  // reask is set to True (because next time things might be different).
220  virtual Bool canAccessColumn (Bool& reask) const;
221 
222  // Test if only one hypercube is used by this storage manager.
223  // If not, throw an exception. Otherwise return the hypercube.
224  virtual TSMCube* singleHypercube();
225 
226  // Set the shape and tile shape of the given hypercube.
227  // It is used when the first row in a new hypercube is written.
228  // If needed it adds a dimension to the shape, which reflects the
229  // row dimension. The tile shape in that dimension is by default 1.
230  virtual void setShape (uInt rownr, TSMCube* hypercube,
231  const IPosition& shape,
232  const IPosition& tileShape);
233 
234  // Make the object from the type name string.
235  // This function gets registered in the DataManager "constructor" map.
236  static DataManager* makeObject (const String& dataManagerType,
237  const Record& spec);
238 
239 private:
240  // Create a TiledShapeStMan.
241  // This constructor is private, because it should only be used
242  // by makeObject.
243  TiledShapeStMan();
244 
245  // Forbid copy constructor.
247 
248  // Forbid assignment.
250 
251  // Get the default tile shape.
252  virtual IPosition defaultTileShape() const;
253 
254  // Add rows to the storage manager.
255  void addRow (uInt nrrow);
256 
257  // Find the hypercube for the given shape.
258  // It returns -1 when not found.
259  Int findHypercube (const IPosition& shape);
260 
261  // Add a hypercube.
262  // The number of rows in the table must be large enough to
263  // accommodate this hypercube.
264  // The possible id values must be given in the record, while
265  // coordinate values are optional. The field names in the record
266  // should match the coordinate and id column names.
267  // The last dimension in the cube shape can be zero, indicating that
268  // the hypercube is extensible.
269  void addHypercube (uInt rownr,
270  const IPosition& cubeShape,
271  const IPosition& tileShape);
272 
273  // Extend the hypercube with the given number of elements in
274  // the last dimension.
275  // The record should contain the id values (to get the correct
276  // hypercube) and optionally coordinate values for the elements added.
277  void extendHypercube (uInt rownr, uInt cubeNr);
278 
279  // Get the hypercube in which the given row is stored.
280  virtual TSMCube* getHypercube (uInt rownr);
281 
282  // Get the hypercube in which the given row is stored.
283  // It also returns the position of the row in that hypercube.
284  virtual TSMCube* getHypercube (uInt rownr, IPosition& position);
285 
286  // Check if the hypercolumn definition fits this storage manager.
287  virtual void setupCheck (const TableDesc& tableDesc,
288  const Vector<String>& dataNames) const;
289 
290  // Flush and optionally fsync the data.
291  // It returns a True status if it had to flush (i.e. if data have changed).
292  virtual Bool flush (AipsIO&, Bool fsync);
293 
294  // Let the storage manager create files as needed for a new table.
295  // This allows a column with an indirect array to create its file.
296  virtual void create (uInt nrrow);
297 
298  // Read the header info.
299  virtual void readHeader (uInt nrrow, Bool firstTime);
300 
301  // Update the map of row numbers to cube number plus offset.
302  void updateRowMap (uInt cubeNr, uInt pos, uInt rownr);
303 
304  // Extend the map of row numbers to cube number plus offset
305  // will new empty entries.
306  void extendRowMap (uInt nrow);
307 
308 
309  //# Declare the data members.
310  // The default tile shape.
312  // The map of row number to cube and position in cube.
316  // The nr of elements used in the map blocks.
318  // The last hypercube found.
320 };
321 
322 
323 
324 
325 } //# NAMESPACE CASACORE - END
326 
327 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
void extendRowMap(uInt nrow)
Extend the map of row numbers to cube number plus offset will new empty entries.
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
int Int
Definition: aipstype.h:50
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
Make the object from the type name string.
virtual TSMCube * getHypercube(uInt rownr)
Get the hypercube in which the given row is stored.
virtual Record dataManagerSpec() const
Return a record containing data manager specifications and info.
void extendHypercube(uInt rownr, uInt cubeNr)
Extend the hypercube with the given number of elements in the last dimension.
Tiled hypercube in a table.
Definition: TSMCube.h:105
AipsIO is the object persistency mechanism of Casacore.
Definition: AipsIO.h:168
virtual IPosition defaultTileShape() const
Get the default tile shape.
Base class for Tiled Storage Manager classes.
Definition: TiledStMan.h:107
TiledShapeStMan()
Create a TiledShapeStMan.
uInt nrUsedRowMap_p
The nr of elements used in the map blocks.
virtual void readHeader(uInt nrrow, Bool firstTime)
Read the header info.
virtual Bool flush(AipsIO &, Bool fsync)
Flush and optionally fsync the data.
Int findHypercube(const IPosition &shape)
Find the hypercube for the given shape.
const IPosition & tileShape(uInt rownr) const
Get the tile shape of the data in the given row.
void addRow(uInt nrrow)
Add rows to the storage manager.
IPosition defaultTileShape_p
The default tile shape.
virtual void create(uInt nrrow)
Let the storage manager create files as needed for a new table.
void updateRowMap(uInt cubeNr, uInt pos, uInt rownr)
Update the map of row numbers to cube number plus offset.
virtual TSMCube * singleHypercube()
Test if only one hypercube is used by this storage manager.
Tiled Data Storage Manager using the shape as id.
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual void setupCheck(const TableDesc &tableDesc, const Vector< String > &dataNames) const
Check if the hypercolumn definition fits this storage manager.
virtual DataManager * clone() const
Clone this object.
virtual void setShape(uInt rownr, TSMCube *hypercube, const IPosition &shape, const IPosition &tileShape)
Set the shape and tile shape of the given hypercube.
virtual Bool canAccessColumn(Bool &reask) const
TiledShapeStMan can access a column if there are 2 hypercubes and the first one is empty...
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:1944
Int lastHC_p
The last hypercube found.
void addHypercube(uInt rownr, const IPosition &cubeShape, const IPosition &tileShape)
Add a hypercube.
Abstract base class for a data manager.
Definition: DataManager.h:224
uInt nrow() const
Get the nr of rows in this storage manager.
Definition: TiledStMan.h:539
TiledShapeStMan & operator=(const TiledShapeStMan &)
Forbid assignment.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
virtual String dataManagerType() const
Get the type name of the data manager (i.e.
Define the structure of a Casacore table.
Definition: TableDesc.h:187
Block< uInt > rowMap_p
The map of row number to cube and position in cube.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
uInt maximumCacheSize() const
Get the current maximum cache size (in MiB (MibiByte)).
Definition: TiledStMan.h:533