class HepNtuple

Ntuple of blocks of (possibly heterogeneous) columns

Last update: 20 Sept. 2001

HepNtuple provides the flexibility of defining inhomogenous blocks with
variables of different types, different packing strategies, and so
forth. Its features are motivated by the HBook column-wise Ntuple.

An HepNtuple may be stored in row-wise or column-wise order.
However, various managers may not support every storage strategy.
For example, HBook does not support row-wise storage for
inhomogeneous Ntuples.

Methods

Creating an Ntuple

The user does not directly instantiate a HepNtuple object.
Instead, a reference (a HepNtuple&) is obtained by calling
the ntuple() method in the
manager.

These methods are not methods of HepNtuple but
are documented here for convenience.

A fresh Ntuple:

HepFileManager::
ntuple(

const std::string& title,

int id = 0);

Both the title and the id must be unique within a directory.
If the id is 0 (default) then the manager assigns a new
unique id to the ntuple.

Merely creating an HepNtuple does not yet provide an object
suitable for accumulating data. Block and column definitions must
be provided before data may be accumulated.
|1|

For example, if m points to the manager, the
user might do:
tup = m->ntuple ( "Values" );
// Now use various methods of HepNtuple class to define
properties
tup.capture ();
// and when finished --
tup.release();

Create an HepNtuple refering to one existing in the manager
(for retrieval access):

Create a fresh empty HepNtuple with the same characteristics
as this HepNtuple.
The clone is created in the current directory of the manager.
The manager used in the first form is the same of the original ntuple.

In general, a tag is of the form BlockName::ColumnName. If
a block name has already been defined, the ColumnName alone may
be given and the BlockName will default to the "current" block.
A ColumnName must be unique across the entire Ntuple except as
noted in the following addendum.

As of 20 Sept. 2001, this uniqueness
condition has been relaxed, but only for the Root manager. For
the Root manager, duplicate column names may be used provided they
appear in different blocks. In addition, there is an important
consequence to the user associated with this added flexibility. Allowing
duplicate column names introduces a potentially serious ambiguity at
data capture time since column names alone no longer uniquely specify
how to store the captured data. Therefore, when using this new feature,
you must use the full tag (BlockName::ColumnName) in calls to
any of the capture methods.

ColumnData_t specifies the data type, for example
Float4_ct or Int2_ct.
|5| value is the designated value for data in this column and
capture occurrs immediately. For deferred capture, see columnAt
below.
|6|

An index variable allows the Ntuple to have a "variable-length"
column, by treating the index variable as the number of entries
in that column for this particular row.
The index variable applies to the slowest varying (first)
array index. It must be another column in the same block, and must
have a defined span (range of possible values).

Only the first argument is required. All others may be omitted and
default to zero. For a 4 by 7 array of columns, dim1 = 4, dim2 = 7
and all others are omitted. The number of arguments to dimension
must match the value of ncols in the columnArray call.

The signature provides a measure of type safety; the float
signature, for example, verifies that the
defined column type is a Float4 or Float8 or Float16.
If this method is not called, the default value will be zero
for integer and float types, and all blanks for character types.

Similarly, the current setting for the default value can be obtained via

columnDefault ( const std::string& tag, ColumnData_t* default );

Define a designated variable for a column which had been defined by
chform:
|3|

columnVariable ( const std::string& tag, void* variable );

This is used when it is conceivable that the compiler would provide
empty space in a block structure to improve word alignment.

Specifying Storage Strategies for the Ntuple

Row-wise or Column-wise storage:

bool setRowWise( );

bool setColumnWise( );

bool setBlockWise( );

Returns true if the manager handles that
choice. Default is Column-Wise on any manager that is
capable of handling Column-Wise Ntuples.

Block-wise storage is not supported by the HBook manager.

Disk or memory resident:

bool setMemResident( );

bool setDiskResident( );

bool setSharedMemory (const char* areaName);

Returns true if the manager handles that
choice.
Default is DiskResident.

Buffer sizes:

void setNwbuff (const int& nwbuff);

void setBuffLimit(const int& nbytes);

nwbuff is expressed in number of words
per column kept in the in-memory buffers.
buffLimit restricts the total buffer space used;
this may force nwbuff to be below its
stated value.
Defaults are 8K words per column up to 2 Mbytes for
column-wise or 128K bytes for row-wise Ntuples.

Buffer allocation (for memory-resident and shared memory):

void setCircularBuff( );

void setDemandBuffers( );

Specifies whether to create a circular buffer in
memory, dropping the oldest rows to make
room for the newest, or to allocate another
buffer of space any time you run out of room.
Default is DemandBuffers.

Accumulating data - Filling the Ntuple

Data in the designated variables
|11|
may be captured a block at a time or
the whole row at once.

Capture data for (all columns of) a single block of the Ntuple:

bool captureBlock ( const std::string& blockName );

This does not advance the Ntuple's row number.
The package does not track a separate row
number for each block.

Capture data for an entire a row of the Ntuple -- all blocks --
from the data in the designated variables. This does not
advance the Ntuple's row number:

bool capture ( );

Capture individual items from the data in the designated
variables. The item in question may be a single variable or a
reference to an array according to what was declared for the
corresponding column. Note that, for a column declared as an array,
it is possible to use a standard library vector container. For a
vector container named e. g., v in an ntuple object named
tupl, one would write

Retrieve one block for specified row of the Ntuple,
into designated variables for that block:

int readBlock(const int irow, const std::string& blockName);

Bulk retrieval of column data

Data in an individual column may be retrieved multiple rows
at once. The user is responsible for providing an area to
place the retrieved data; the designated variable for that column
is not applicable for these methods.