io_nemo(filename, param, ....)
char * filename;/* input/output file name */
char * param; /* parameters list */
Descriptionio_nemo is a high level C function which allows the user to
perform I/O operations on NEMO snapshot files from a C program. It works
quite like C printf function. The use of this function is very simple and
require only some basic knowledge of how to program in NEMO.
Parameters
filename=character variable Input/Output file name of the NEMO snapshot
that you want to read/save. param=character Param is a string in which you
specify what you want to do with the NEMO file. Each choice is defined with
a flag separated with ’,’. There are two kind of flags. (1) Information flags
allow to specify some actions during the I/O. (2) Variables flags allow
to specify what you want to get/put from/into the NEMO file. The FLAGS list
is described below.
(1) Information flagss | save Specify that you want to
save data to a NEMO file. r | read Specify that you want to read data from
a NEMO file. float|single Specify that the variables that you use to get/put
data from/into NEMO files have been declared in single precision. (float).
double Specify that the variables you use to get/put data from/into NEMO
files have been declared in double precision. (double). info | diag Gives
some informations during the runtime execution. close Specify that you want
to close the NEMO file.
(2) Variables flags n|nbody Match to the number
of bodies. t|time Match to the snapshot time. m|mass Match to the particle
masses. x|pos Match to the particle positions. v|vel Match to the particle
velocities. p|pot Match to the particle potentials. a|acc Match to the particle
accelerations. aux Match to the auxiliary array. k|keys Match to the keys
array. d|dens Match to the particle density. e|eps Match to the particle softening.
h|history Match to the NEMO file name that you want to keep track about
the history. st Select snapshot’s times. You have to put the selected time
in a string. Example "100:150" select the time beween 100 and 150. The string
is fully compatible with the expression usually given to nemoinpi (Cf man
nemoinpi). sp Select snapshot’s particles. You have to put the selected particles
in a string. Example "0:299999" select the particles beween 0 and 299999.
The returned nbody corresponds to the selected nbody. In the example above
it would thus be 300000. The string is fully compatible with the expression
usually given to nemoinpi (Cf man nemoinpi). b Integer variable to store
input/output bit flags (see $NEMOINC/snapshot/snapshot.h). During read operation,
this variable is filled up with OR bit operation according to the components
requested and the existing components in the file. Example: if you ask for
positons and potentials and no potentials exist on the snapshot, then bit
flags will contain only PosBit. During write operation, if it is used, io_nemo
engine will only save components, which have their bits positionned on
it, AND requested to be saved. (see a complete example here: $NEMOSRC/nbody/io_nemo/test_src/io_nemo_test.c).
ArgumentsThe variable flags specify which data you will get/put from/into
the NEMO file, hence after the selection string param, you must insert
all the selected variables (arguments) in the same order with which they
have been declared in param. For each of the following requested flags:
n,t,m,x,v,a,p,b,k,e you **must** give as argument an address of pointer.
During read opreation, io_nemo check NULL pointer for each arguments. In
case of NULL pointer the memory is automatically allocated to fill up with
the requested component. If not NULL, io_nemo supposed that the pointer
is already allocated. For the flags sp,st,h you just have to give the pointer
as argument. Return ValueThe function return 1 if successfull, 0 if the
end of snapshot has been reached, -2 if there is no ParticlesTag, or -1 if
at least one of the components requested does not exist (in that case you
should use ’b’ parameter to filter existing components). ExampleHere is a
simple NEMO C program to illustrate the use of the function io_nemo(). The
program reads all the time steps into a NEMO a file, and saves the data
in another NEMO file. (See a more complete example here: $NEMOSRC/nbody/io_nemo/test_src/io_nemo_test.c).
/* ----------------------------------------------------- *\
|* NEMO program test using ’io_nemo()’ function
\* ----------------------------------------------------- */
#include <stdinc.h>
#include <getparam.h>
#include <io_nemo.h>
string defv[]=
{ "in=???\n input snapshot",
"out=???\n output snapshot",
"VERSION=1.0\n 16-April-97 jcl",
NULL
};
string usage="NEMO program test using ’io_nemo()’ function";
/* ----------------------------------------------------- *\
|* Main program
\* ----------------------------------------------------- */
nemo_main()
{
float * pos=NULL, * vel=NULL, * mass=NULL;
float * time=NULL;
int * nbody=NULL;
string in,out;
int i,j;
in = getparam("in");
out = getparam("out");
i = 1;
while (i!=0) {
/* read the NEMO snapshot */
i=io_nemo(in,"float,n,t,x,v,m,read,info",
&nbody,&time,&pos,&vel,&mass);
/* save the NEMO snapshot */
if (i != 0)
j=io_nemo(out,"float,n,t,x,v,m,h,save,info",
&nbody,&time,&pos,&vel,&mass,in);
}
/* close the output NEMO snapshot */
io_nemo(out,"close");
}
/* ----------------------------------------------------- *\
|* END
\* ----------------------------------------------------- */
Important Thingsa) Notice in the example above, that in the parameter list,
’n’ matches ’nbody’, ’m’ matches ’mass’, ’x’ matches ’pos’, ’v’ matches ’vel’, ’t’ matches
’ts’. All the variables are in the same order that they have been declared
in the param list. b) All the NEMO variables (nbody, time, mass, pos, vel,
acc, pot) must be declared as a pointer equal to NULL. During the io_nemo()
call, theses pointers will be allocated according the number of bodies
in the snapshot, so you must give the adress of the pointer ( ie : &pos,
&vel, ...etc). c) All the floating arrays must be declared in the same floating
type. d) During a "read" operation, the function io_nemo() return ’0’ if
it is the end of the NEMO file. That means that no new values have been
read.
# ----------------------------------------
# MAKEFILE to use IO_NEMO
#
# ----------------------------------------
# path for NEMO Library and IO_NEMO library
LIBS = -L$(NEMOLIB) -L/usr/local/lib
#
CFLAGS = -I$(NEMOINC) -I$(NEMOLIB)
io_nemo_test : io_nemo_test.o
$(CC) -o $@ io_nemo_test.o $(LIBS) \
-lnemo -lm
# ----------------------------------------
nemo(1NEMO), snapshot(5NEMO).
Jean-Charles.Lambert@oamp.fr
15-Nov-96 V1.0 : created JCL 21-Feb-97 V1.1 : memory optimisation JCL 16-Apr-97 V1.11: manual created JCL 19-Jul-02 V1.2 : io_nemo and io_nemo_f unified JCL 18-Mar-04 V1.21: bugs fixed, softening added JCL 03-Mar-05 V1.30: memory bugs fixed, keybits added JCL valgrind mem/leak safe 24-Apr-06 V1.31: memory leak fixed JCL 19-Jun-06 V1.32: happy gfortran JCL 29-May-07 V1.42: handle snapshot with different JCL nbodies 29-Feb-08 V1.50: add Aux and Dens array JCL