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
38namespace 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// for (uInt i=0; i<64; i++) {
167// table.addRow();
168// image.put (i, imageValues);
169// ra.put (i, raValues);
170// dec.put (i, decValues);
171// velocity.put (i, float(i));
172// }
173// </srcblock>
174// Note that in this example the same shape is used for each row,
175// but it could have been different.
176// </example>
177
178//# <todo asof="$DATE:$">
179//# A List of bugs, limitations, extensions or planned refinements.
180//# </todo>
181
182
184{
185public:
186 // Create a TiledShapeStMan storage manager for the hypercolumn
187 // with the given name.
188 // The hypercolumn name is also the name of the storage manager.
189 // The given maximum cache size (default is unlimited) is persistent,
190 // thus will be reused when the table is read back. Note that the class
191 // <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
192 // allows one to overwrite the maximum cache size temporarily.
193 // <br>The constructor taking a Record expects fields in the record with
194 // the name of the arguments in uppercase. If not defined, their
195 // default value is used.
196 // <group>
197 TiledShapeStMan (const String& hypercolumnName,
200 TiledShapeStMan (const String& hypercolumnName,
201 const Record& spec);
202 // </group>
203
205
206 // Clone this object.
207 // It does not clone TSMColumn objects possibly used.
208 virtual DataManager* clone() const;
209
210 // Get the type name of the data manager (i.e. TiledShapeStMan).
211 virtual String dataManagerType() const;
212
213 // Return a record containing data manager specifications and info.
214 virtual Record dataManagerSpec() const;
215
216 // TiledShapeStMan can access a column if there are 2 hypercubes
217 // and the first one is empty.
218 virtual Bool canAccessColumn() const;
219
220 // Test if only one hypercube is used by this storage manager.
221 // If not, throw an exception. Otherwise return the hypercube.
223
224 // Set the shape and tile shape of the given hypercube.
225 // It is used when the first row in a new hypercube is written.
226 // If needed it adds a dimension to the shape, which reflects the
227 // row dimension. The tile shape in that dimension is by default 1.
228 virtual void setShape (rownr_t rownr, TSMCube* hypercube,
229 const IPosition& shape,
230 const IPosition& tileShape);
231
232 // Make the object from the type name string.
233 // This function gets registered in the DataManager "constructor" map.
235 const Record& spec);
236
237private:
238 // Create a TiledShapeStMan.
239 // This constructor is private, because it should only be used
240 // by makeObject.
242
243 // Forbid copy constructor.
245
246 // Forbid assignment.
248
249 // Get the default tile shape.
251
252 // Add rows to the storage manager.
253 void addRow64 (rownr_t nrrow);
254
255 // Find the hypercube for the given shape.
256 // It returns -1 when not found.
258
259 // Add a hypercube.
260 // The number of rows in the table must be large enough to
261 // accommodate this hypercube.
262 // The possible id values must be given in the record, while
263 // coordinate values are optional. The field names in the record
264 // should match the coordinate and id column names.
265 // The last dimension in the cube shape can be zero, indicating that
266 // the hypercube is extensible.
268 const IPosition& cubeShape,
269 const IPosition& tileShape);
270
271 // Extend the hypercube with the given number of elements in
272 // the last dimension.
273 // The record should contain the id values (to get the correct
274 // hypercube) and optionally coordinate values for the elements added.
275 void extendHypercube (rownr_t rownr, uInt cubeNr);
276
277 // Get the hypercube in which the given row is stored.
278 virtual TSMCube* getHypercube (rownr_t rownr);
279
280 // Get the hypercube in which the given row is stored.
281 // It also returns the position of the row in that hypercube.
282 virtual TSMCube* getHypercube (rownr_t rownr, IPosition& position);
283
284 // Check if the hypercolumn definition fits this storage manager.
285 virtual void setupCheck (const TableDesc& tableDesc,
286 const Vector<String>& dataNames) const;
287
288 // Flush and optionally fsync the data.
289 // It returns a True status if it had to flush (i.e. if data have changed).
290 virtual Bool flush (AipsIO&, Bool fsync);
291
292 // Let the storage manager create files as needed for a new table.
293 // This allows a column with an indirect array to create its file.
294 virtual void create64 (rownr_t nrrow);
295
296 // Read the header info.
297 virtual void readHeader (rownr_t nrrow, Bool firstTime);
298
299 // Update the map of row numbers to cube number plus offset.
300 void updateRowMap (uInt cubeNr, uInt pos, rownr_t rownr);
301
302 // Extend the map of row numbers to cube number plus offset
303 // will new empty entries.
305
306
307 //# Declare the data members.
308 // The default tile shape.
310 // The map of row number to cube and position in cube.
314 // The nr of elements used in the map blocks.
316 // The last hypercube found.
318};
319
320
321
322
323} //# NAMESPACE CASACORE - END
324
325#endif
Abstract base class for a data manager.
Definition: DataManager.h:221
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual String dataManagerType() const
Get the type name of the data manager (i.e.
virtual Record dataManagerSpec() const
Return a record containing data manager specifications and info.
void addHypercube(rownr_t rownr, const IPosition &cubeShape, const IPosition &tileShape)
Add a hypercube.
void extendHypercube(rownr_t rownr, uInt cubeNr)
Extend the hypercube with the given number of elements in the last dimension.
virtual TSMCube * getHypercube(rownr_t rownr)
Get the hypercube in which the given row is stored.
virtual DataManager * clone() const
Clone this object.
virtual void setShape(rownr_t rownr, TSMCube *hypercube, const IPosition &shape, const IPosition &tileShape)
Set the shape and tile shape of the given hypercube.
uInt nrUsedRowMap_p
The nr of elements used in the map blocks.
Int lastHC_p
The last hypercube found.
TiledShapeStMan & operator=(const TiledShapeStMan &)
Forbid assignment.
Block< uInt > rowMap_p
The map of row number to cube and position in cube.
virtual Bool canAccessColumn() const
TiledShapeStMan can access a column if there are 2 hypercubes and the first one is empty.
static DataManager * makeObject(const String &dataManagerType, const Record &spec)
Make the object from the type name string.
Int findHypercube(const IPosition &shape)
Find the hypercube for the given shape.
TiledShapeStMan(const String &hypercolumnName, const Record &spec)
virtual TSMCube * getHypercube(rownr_t rownr, IPosition &position)
Get the hypercube in which the given row is stored.
IPosition defaultTileShape_p
The default tile shape.
TiledShapeStMan(const String &hypercolumnName, const IPosition &defaultTileShape, uInt64 maximumCacheSize=0)
Create a TiledShapeStMan storage manager for the hypercolumn with the given name.
virtual void readHeader(rownr_t nrrow, Bool firstTime)
Read the header info.
void addRow64(rownr_t nrrow)
Add rows to the storage manager.
void extendRowMap(rownr_t nrow)
Extend the map of row numbers to cube number plus offset will new empty entries.
void updateRowMap(uInt cubeNr, uInt pos, rownr_t rownr)
Update the map of row numbers to cube number plus offset.
TiledShapeStMan(const TiledShapeStMan &)
Forbid copy constructor.
TiledShapeStMan()
Create a TiledShapeStMan.
virtual void setupCheck(const TableDesc &tableDesc, const Vector< String > &dataNames) const
Check if the hypercolumn definition fits this storage manager.
virtual Bool flush(AipsIO &, Bool fsync)
Flush and optionally fsync the data.
virtual IPosition defaultTileShape() const
Get the default tile shape.
virtual TSMCube * singleHypercube()
Test if only one hypercube is used by this storage manager.
virtual void create64(rownr_t nrrow)
Let the storage manager create files as needed for a new table.
const IPosition & tileShape(rownr_t rownr) const
Get the tile shape of the data in the given row.
rownr_t nrow() const
Get the nr of rows in this storage manager.
Definition: TiledStMan.h:538
uInt maximumCacheSize() const
Get the current maximum cache size (in MiB (MibiByte)).
Definition: TiledStMan.h:532
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1987
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46
unsigned long long uInt64
Definition: aipsxtype.h:39