1. Introduction

The bop (bricks of particles) format is a simple file format for cloud data. The name is inspired from the bov (bricks of values) format for grid data in visit.

It consists in two files:

  • a header file (extension: .bop), in ascii format, containing a description of the data

  • a data file (extension: .values), in binary or ascii, containing the data

The header file has the following format, for <N> particles:

<N>
DATA_FILE: <file.values>
DATA_FORMAT: <float|ascii|double|int|iascii>
VARIABLES: <x> <y> <z> <vx> <vy> <vz> <id> ...
NRANK: <m>
<n1>
<n2>
<n3>
...
<nm>

where <n1>, <n2>, …​ are the number of particles per mpi rank. NRANK and these fields are optional.

file.values format:

x[0] y[0] z[0] vx[0] vy[0] vz[0] id[0]
...

x[N-1] y[N-1] ...

The ascii format is assumed to be single precision floating points data. Th iascii format is the ascii version for integer data. Other formats are binary.

2. Installation

The following will install the binaries into ${HOME}/bin. This folder needs to be in the PATH variable. Furthermore, it installs the headers and library into PREFIX/bop/include and PREFIX/bop/lib, respectively. PREFIX is set to ${HOME}/prefix by default.

./configure --prefix PREFIX
make

After installation, it is recommended to run tests (uses atest framework):

make -s test

3. Common Interface

3.1. memory management

The BopData data structure is hidden from user and can be allocated/deallocated using the following functions:

BopStatus bop_ini(BopData **d);  (1)
BopStatus bop_alloc(BopData *d); (2)
BopStatus bop_fin(BopData *d);   (3)
1 allocate hidden structure BopData
2 allocate space for the data based on the set variables n, nvars and type
3 deallocate the hidden structure and, if needed, the internal buffer for data

3.2. setters

A description of the data can be set using the following functions:

BopStatus bop_set_n(long n, BopData *d);                     (1)
BopStatus bop_set_vars(int n, const char *vars, BopData *d); (2)
BopStatus bop_set_type(BopType type, BopData *d);            (3)
void* bop_get_data(BopData *d);                              (4)
1 set the number of particles
2 set the number of variables and their names separated by space in a sigle string
3 set the type of the data
4 get a pointer of the internal data buffer (read, write)

The type is defined in the enumeration type:

enum BopType {BopFLOAT, BopDOUBLE, BopINT, BopFASCII, BopIASCII};

3.3. getters

The informations stored in the BopData descriptor can be retrieved by using the following getter functions:

BopStatus bop_get_n(const BopData *d, long *n);              (1)
BopStatus bop_get_nvars(const BopData *d, int *n);           (2)
BopStatus bop_get_vars(const BopData *d, Cbuf *vars);        (3)
BopStatus bop_get_vars(const BopData *d, const char **vars); (4)
BopStatus bop_get_type(const BopData *d, BopType *type);     (5)
const void* bop_get_data(const BopData *d);                  (6)
1 get the number of particles
2 get the number of fields
3 get the variable names in Cbuf array
4 get variable names in const char** format
5 get the type of the data
6 get a pointer on the internal buffer (read only)

3.4. Error handling

Any function from the library returns an error status encoded in the BopStatus type. The status can be interpreted by calling the functions:

bool         bop_success(BopStatus status);           (1)
const char * bop_report_error_desc(BopStatus status); (2)
char *       bop_report_error_mesg();                 (3)
1 returns true on success and false if an error occured
2 returns a description of the status
3 report additional informations on the error

3.5. Convenient tools

BopStatus bop_summary(const BopData *d);                                    (1)
BopStatus bop_concatenate(const int nd, const BopData **dd, BopData *dall); (2)
1 output summary in stdout stream
2 cancatenate nd BopData structures into one

4. serial interface

Interface specific to sequential version

4.1. write

BopStatus bop_write_header(const char *name, const BopData *d); (1)
BopStatus bop_write_values(const char *name, const BopData *d); (2)
1 write the header file from BopData
2 write the data file from BopData

Note that name is the basename of the file, without the extension. This results in the header file name.bop and int the data file name.values.

4.2. read

BopStatus bop_read_header(const char *hfname, BopData *d, char *dfname); (1)
BopStatus bop_read_values(const char *dfname, BopData *d);               (2)
1 read and parse the header file. returns the name of the data file in the (user provided) buffer dfname
2 read data file and store it inside the internal buffer of the BopData structure

5. mpi interface

Interface specific to mpi version

5.1. write

BopStatus bop_write_header(MPI_Comm comm, const char *name, const BopData *d); (1)
BopStatus bop_write_values(MPI_Comm comm, const char *name, const BopData *d); (2)
1 write the header file from BopData. Must be called by all ranks of the communicator comm.
2 write the data file from BopData. Must be called by all ranks of the communicator comm.

Note that name is the basename of the file, without the extension. This results in the header file name.bop and int the data file name.values.

The header file will contain the total number of particles, it is reduced internally.

5.2. read

BopStatus bop_read_header(MPI_Comm comm, const char *hfname, BopData *d, char *dfname);  (1)
BopStatus bop_read_values(MPI_Comm comm, const char *dfname, BopData *d);                (2)
1 read and parse the header file. returns the name of the data file in the (user provided) buffer dfname.
2 read data file and store it inside the internal buffer of the BopData structure. This is a collective operation.

Note: The collective read for ascii values is not supported. The user must use the serial implementation.

6. Tools

6.1. Converters

Convert bop files in1.bop, in2.bop, …​, inN.bop into a single vtk file out.vtk:

bop2vtk out.vtk in1.bop in2.bop ... inN.bop

Dump ascii data from bop files in1.bop, in2.bop, …​, inN.bop into out.txt:

bop2txt in1.bop in2.bop ... inN.bop > out.txt