NAPI: The NeXus Application Programming Interface¶
The NeXus API consists of routines to read and write NeXus data files. It was written to provide a simple to use and consistent common interface for all supported backends (XML, HDF4 and HDF5) to scientific programmers and other users of the NeXus Data Standard.
Note
It is not necessary to use the NAPI to write or read NeXus data files. The intent of the NAPI is to simplify the programming effort to use the HDF programming interface. There are NeXus: Examples data files I/O to help you understand.
This section will provide a brief overview of the available functionality. Further documentation of the NeXus Application Programming Interface (NAPI) for bindings to specific programming language can be found in the NAPI chapter and may be downloaded from the NeXus development site. [1]
For an even more detailed description of the internal workings of NAPI see the NeXus Internals manual, copied from the NeXus code repository. That document is written for programmers who want to work on the NAPI itself. If you are new to NeXus and just want to implement basic file reading or writing you should not start by reading that.
How do I write a NeXus file?¶
The NeXus Application Program Interface (NAPI) provides a set of subroutines that make it easy to read and write NeXus files. These subroutines are available in C, Fortran 77, Fortran 90, Java, Python, C++, and IDL.
The API uses a very simple state model to navigate through a NeXus file. When you open a file, the API provides a file handle, which stores the current location, i.e. which group and/or field is currently open. Read and write operations then act on the currently open entity. Following the simple example titled Example structure of a simple data file, we walk through a schematic of NeXus program written in C (without any error checking or real data).
Writing a simple NeXus file using NAPI
Note
We assume the program can define
the arrays tth
and counts
, each length n
.
This part has been omitted from the example code.
1#include "napi.h"
2
3 int main()
4 {
5 /* we start with known arrays tth and counts, each length n */
6 NXhandle fileID;
7 NXopen ("NXfile.nxs", NXACC_CREATE, &fileID);
8 NXmakegroup (fileID, "Scan", "NXentry");
9 NXopengroup (fileID, "Scan", "NXentry");
10 NXmakegroup (fileID, "data", "NXdata");
11 NXopengroup (fileID, "data", "NXdata");
12 NXmakedata (fileID, "two_theta", NX_FLOAT32, 1, &n);
13 NXopendata (fileID, "two_theta");
14 NXputdata (fileID, tth);
15 NXputattr (fileID, "units", "degrees", 7, NX_CHAR);
16 NXclosedata (fileID); /* two_theta */
17 NXmakedata (fileID, "counts", NX_FLOAT32, 1, &n);
18 NXopendata (fileID, "counts");
19 NXputdata (fileID, counts);
20 NXclosedata (fileID); /* counts */
21 NXclosegroup (fileID); /* data */
22 NXclosegroup (fileID); /* Scan */
23 NXclose (&fileID);
24 return;
25}
program analysis
- line 7:
Open the file
NXfile.nxs
with create access (implying write access). NAPI [2] returns a file identifier of typeNXhandle
.
- line 10:
The plottable data is contained within an NXdata group, which must also be created and opened.
- line 12:
To create a field, call
NXmakedata()
, specifying the data name, type (NX_FLOAT32
), rank (in this case,1
), and length of the array (n
). Then, it can be opened for writing. [4]
- line 14:
Write the data using
NXputdata()
.
- line 16:
Then we close the field before opening another. In fact, the API will do this automatically if you attempt to open another field, but it is better style to close it yourself.
- line 17:
The remaining fields in this group are added in a similar fashion. Note that the indentation whenever a new field or group are opened is just intended to make the structure of the NeXus file more transparent.
- line 20:
Finally, close the groups (
NXdata
andNXentry
) before closing the file itself.
How do I read a NeXus file?¶
Reading a NeXus file works in the same way by traversing the tree with the handle.
This schematic C code will read the two-theta array created in the example above. (Again, compare this example with Reading a simple NeXus file using native HDF5 commands in C.)
Reading a simple NeXus file using NAPI
1 NXopen ('NXfile.nxs', NXACC_READ, &fileID);
2 NXopengroup (fileID, "Scan", "NXentry");
3 NXopengroup (fileID, "data", "NXdata");
4 NXopendata (fileID, "two_theta");
5 NXgetinfo (fileID, &rank, dims, &datatype);
6 NXmalloc ((void **) &tth, rank, dims, datatype);
7 NXgetdata (fileID, tth);
8 NXclosedata (fileID);
9 NXclosegroup (fileID);
10 NXclosegroup (fileID);
11 NXclose (fileID);
How do I browse a NeXus file?¶
NeXus files can also be viewed by a command-line browser,
nxbrowse
, which is included as a helper tool in the
NeXus API
distribution. The following
is an example session of nxbrowse
nxbrowse
to view a data file.
Using nxbrowse
1%> nxbrowse lrcs3701.nxs
2
3NXBrowse 3.0.0. Copyright (C) 2000 R. Osborn, M. Koennecke, P. Klosowski
4 NeXus_version = 1.3.3
5 file_name = lrcs3701.nxs
6 file_time = 2001-02-11 00:02:35-0600
7 user = EAG/RO
8NX> dir
9 NX Group : Histogram1 (NXentry)
10 NX Group : Histogram2 (NXentry)
11NX> open Histogram1
12NX/Histogram1> dir
13 NX Data : title[44] (NX_CHAR)
14 NX Data : analysis[7] (NX_CHAR)
15 NX Data : start_time[24] (NX_CHAR)
16 NX Data : end_time[24] (NX_CHAR)
17 NX Data : run_number (NX_INT32)
18 NX Group : sample (NXsample)
19 NX Group : LRMECS (NXinstrument)
20 NX Group : monitor1 (NXmonitor)
21 NX Group : monitor2 (NXmonitor)
22 NX Group : data (NXdata)
23NX/Histogram1> read title
24 title[44] (NX_CHAR) = MgB2 PDOS 43.37g 8K 120meV E0@240Hz T0@120Hz
25NX/Histogram1> open data
26NX/Histogram1/data> dir
27 NX Data : title[44] (NX_CHAR)
28 NX Data : data[148,750] (NX_INT32)
29 NX Data : time_of_flight[751] (NX_FLOAT32)
30 NX Data : polar_angle[148] (NX_FLOAT32)
31NX/Histogram1/data> read time_of_flight
32 time_of_flight[751] (NX_FLOAT32) = [ 1900.000000 1902.000000 1904.000000 ...]
33 units = microseconds
34 long_name = Time-of-Flight [microseconds]
35NX/Histogram1/data> read data
36 data[148,750] (NX_INT32) = [ 1 1 0 ...]
37 units = counts
38 signal = 1
39 long_name = Neutron Counts
40 axes = polar_angle:time_of_flight
41NX/Histogram1/data> close
42NX/Histogram1> close
43NX> quit
program analysis
- line 1:
Start
nxbrowse
from the UNIX command line and open filelrcs3701.nxs
from IPNS/LRMECS.
- line 8:
List the contents of the current group.
- line 11:
Open the NeXus group
Histogram1
.
- line 23:
Print the contents of the NeXus data labeled
title
.
- line 41:
Close the current group.
- line 43:
Quits
nxbrowse
.
The source code of nxbrowse
[8]
provides an example of how to write a NeXus reader.
The test programs included in the NeXus
API may also be useful to study.