2
* ADIOS is freely available under the terms of the BSD license described
3
* in the COPYING file in the top level directory of this source distribution.
5
* Copyright (c) 2008 - 2009. UT-BATTELLE, LLC. All rights reserved.
9
* Streaming/Chunking/Selection Read API in C for ADIOS BP format
11
* A SELECTION is the data ranges resulting from a QUERY over a file and variable(s).
13
* A SELECTION can be a list of bounding boxes and point-sets. Other data structures
14
* are not supported. Any query will result in such a selection.
15
* Other selections are the write-block and auto.
17
* Write block is a block of data written
18
* by a writer process, it is identified by an index. If each writer outputs one block
19
* then the index equals to the rank of the write process. With multi-var writing and
20
* multiple steps in a file, index runs from 0 as rank 0 process' first block.
22
* Auto selection lets the read method to automatically choose what to return. It will
23
* be a block / blocks of selected writers.
25
* If a query is a simple bounding box, the selection is the bounding box itself, so
26
* the application does not need to retrieve the selection to work on the read data.
28
#ifndef __ADIOS_SELECTION_H__
29
#define __ADIOS_SELECTION_H__
37
/*************************/
38
/* Types used in the API */
39
/*************************/
41
/* Type of selection */
42
enum ADIOS_SELECTION_TYPE {
43
ADIOS_SELECTION_BOUNDINGBOX = 0, /* Contiguous block of data defined by offsets and counts in each dimension */
44
ADIOS_SELECTION_POINTS = 1, /* List of individual points */
45
ADIOS_SELECTION_WRITEBLOCK = 2, /* Selection of an individual block written by a writer process */
46
ADIOS_SELECTION_AUTO = 3 /* Let the method decide what to return */
55
} ADIOS_SELECTION_BOUNDINGBOX_STRUCT;
58
* It is a 1D array of indices, linearized for all dimension
59
* (e.g. [i1,j1,k1,i2,j2,k2,...,in,jn,kn] for n points in a 3D space.
65
} ADIOS_SELECTION_POINTS_STRUCT;
67
/* A selected block produced by a writer
68
* Identified with an index in current versions.
72
} ADIOS_SELECTION_WRITEBLOCK_STRUCT;
74
/* Let the read method decide what to return to each reading client.
75
* Hints are method-dependent parameters to influence what and how to
76
* return (e.g. the ordering of returned chunks, decomposition among
77
* read processes, etc.)
81
} ADIOS_SELECTION_AUTO_STRUCT;
83
/** Selection for reading a subset of a variable.
84
* // A selection is an additive list of bounding boxes and point-sets
86
//typedef struct ADIOS_SELECTION_STRUCT ADIOS_SELECTION;
88
enum ADIOS_SELECTION_TYPE type; /* Type of selection */
90
ADIOS_SELECTION_BOUNDINGBOX_STRUCT bb;
91
ADIOS_SELECTION_POINTS_STRUCT points;
92
ADIOS_SELECTION_WRITEBLOCK_STRUCT block;
93
ADIOS_SELECTION_AUTO_STRUCT autosel;
95
/*ADIOS_SELECTION *next;*/
98
#ifndef __INCLUDED_FROM_FORTRAN_API__
100
/** Boundingbox selection to read a subset of a non-scalar variable.
102
* ndim Number of dimensions
103
* start array of offsets to start reading in each dimension
104
* count number of data elements to read in each dimension
105
* RETURN: A selection which can be used to read variables
107
ADIOS_SELECTION * adios_selection_boundingbox (int ndim, const uint64_t *start, const uint64_t *count);
110
/** Selection for a selection of an enumeration of positions.
112
* ndim Number of dimensions
113
* npoints Number of points of the selection
114
* points 1D array of indices, compacted for all dimension
115
* (e.g. [i1,j1,k1,i2,j2,k2,...,in,jn,kn] for
116
* n points in a 3D space.
118
ADIOS_SELECTION* adios_selection_points (int ndim, uint64_t npoints, const uint64_t *points);
120
/** Selection for a block of data coming from a certain producer.
123
* index Identifier of the written block, starting from 0 for the first block
124
* written by producer rank 0. If each writer outputs one block
125
* then the index equals to the rank of the write process.
126
* With multi-var writing and multiple steps in a file, index should be
127
* calculated by the reading application using outside information beyond
128
* what is provided by the ADIOS Read API.
130
ADIOS_SELECTION* adios_selection_writeblock (int index);
132
/** Let the method decide what data gets to what reader process.
133
* This selection enables each reading method to provide an 'optimal'
134
* data transfer from writers to readers. It depends on the method and the
135
* circumstances, what this selection actually means.
137
* E.g. in situ processing: readers on a compute node will receive all data
138
* from the writers on the same compute node.
141
* hints Method dependent parameters to influence what and how to
142
* return (e.g. decomposition; ordering of returned chunks)
144
ADIOS_SELECTION* adios_selection_auto (char * hints);
146
/** Make a strided hyperslab selection the same way as in HDF5.
148
* ndim Number of dimentsions
149
* start array of offsets to start reading in each dimension
150
* strides striding steps, NULL=1 in all dimensions (= boundingbox)
151
* count number of data elements to read in each dimension
152
* blocks block size at each stride, NULL=1 in all dimensions
155
No support: Klasky, Podhorszki
158
ADIOS_SELECTION* adios_selection_hyperslab (uint64_t ndim, uint64_t *start, uint64_t *strides,
159
uint64_t *count, uint64_t *blocks);
163
/** Delete a selection and free up memory used by the selection.
166
* The ADIOS_SELECTION object can be simply freed by free(), too.
168
void adios_selection_delete (ADIOS_SELECTION *selection);
171
#endif /*__INCLUDED_FROM_FORTRAN_API__*/
177
#endif /*__ADIOS_SELECTION_H__*/
added
removed
src/public/adios_selection.h
