5. NAPI: NeXus Application Programmer Interface (frozen)

5.1. Status

This application program interface (API) was developed to support the reading and writing of NeXus files through unified function calls, regardless of the physical data format (XML, HDF4, HDF5).

In the meantime it has been decided that active development of NeXus definitions and tools will concentrate on HDF5 as the only supported physical data format. It is expected that most application developers will use standard HDF5 tools to read and write NeXus. Two examples are provided in HDF5 in C with libhdf5.

Therefore, the decision has been taken to freeze the NAPI. Maintenance is reduced to bug fixes.

5.2. Overview

The core routines have been written in C but wrappers are available for a number of other languages including C++, Fortran 77, Fortran 90, Java, Python and IDL. The API makes the reading and writing of NeXus files transparent; the user doesn’t even need to know the underlying format when reading a file since the API calls are the same.

The NeXus Application Programming Interface for the various language backends is available on-line from https://github.com/nexusformat/code/

The NeXusIntern.pdf document (https://github.com/nexusformat/code/blob/master/doc/api/NeXusIntern.pdf) describes the internal workings of the NeXus-API. You are very welcome to read it, but it will not be of much use if all you want is to read and write files using the NAPI.

The NeXus Application Program Interface call routines in the appropriate backend (HDF4, HDF5 or XML) to read and write files with the correct structure. The API serves a number of purposes:

  1. It simplifies the reading and writing of NeXus files.

  2. It ensures a certain degree of compliance with the NeXus standard.

  3. It hides the implementation details of the format. In particular, the API can read and write HDF4, HDF5, and XML files using the same routines.

5.3. Core API

The core API provides the basic routines for reading, writing and navigating NeXus files. Operations are performed using a handle that keeps a record of its current position in the file hierarchy. All are read or write requests are then implicitly performed on the currently open entity. This limits number of parameters that need to be passed to API calls, at the cost of forcing a certain mode of operation. It is very similar to navigating a directory hierarchy; NeXus groups are the directories, which can contain data sets and/or other directories.

The core API comprises the following functional groups:

  • General initialization and shutdown: opening and closing the file, creating or opening an existing group or dataset, and closing them.

  • Reading and writing data and attributes to previously opened datasets.

  • Routines to obtain meta-data and to iterate over component datasets and attributes.

  • Handling of linking and group hierarchy.

  • Routines to handle memory allocation. (Not required in all language bindings.)

5.4. Utility API

The NeXus F90 Utility API provides a number of routines that combine the operations of various core API routines in order to simplify the reading and writing of NeXus files. At present, they are only available as a Fortran 90 module but a C version is in preparation.

The utility API comprises the following functional groups:

  • Routines to read or write data.

  • Routines to find whether or not groups, data, or attributes exist, and to find data with specific signal or axis attributes, i.e. to identify valid data or axes.

  • Routines to open other groups to which NXdata items are linked, and to return again.

line required for use with F90 API

Any program using the F90 Utility API needs to put the following line near the top of the program:

use NXUmodule

Note

Do not put USE statements for both NXmodule and NXUmodule. The former is included in the latter

5.4.1. List of F90 Utility Routines

name

description

Reading and Writing

NXUwriteglobals

Writes all the valid global attributes of a file.

NXUwritegroup

Opens a group (creating it if necessary).

NXUwritedata

Opens a data item (creating it if necessary) and writes data and its units.

NXUreaddata

Opens and reads a data item and its units.

NXUwritehistogram

Opens one dimensional data item (creating it if necessary) and writes histogram centers and their units.

NXUreadhistogram

Opens and reads a one dimensional data item and converts it to histogram bin boundaries.

NXUsetcompress

Defines the compression algorithm and minimum dataset size for subsequent write operations.

Finding Groups, Data, and Attributes

NXUfindclass

Returns the name of a group of the specified class if it is contained within the currently open group.

NXUfinddata

Checks whether a data item of the specified name is contained within the currently open group.

NXUfindattr

Checks whether the currently open data item has the specified attribute.

NXUfindsignal

Searches the currently open group for a data item with the specified SIGNAL attribute.

NXUfindaxis

Searches the currently open group for a data item with the specified AXIS attribute.

Finding Linked Groups

NXUfindlink

Finds another link to the specified NeXus data item and opens the group it is in.

NXUresumelink

Reopens the original group from which NXUfindlink was used.

Currently, the F90 utility API will only write character strings, 4-byte integers and reals, and 8-byte reals. It can read other integer sizes into four-byte integers, but does not differentiate between signed and unsigned integers.

5.5. Building Programs

The install kit provides a utility call nxbuild that can be used to build simple programs:

nxbuild -o test test.c

This script links in the various libraries for you and reading its contents would provide the necessary information for creating a separate Makefile. You can also use nxbuild with the example files in the NeXus distribution kit which are installed into /usr/local/nexus/examples

Note that the executable name is important in this case as the test program uses it internally to determine the NXACC_CREATE* argument to pass to NXopen.

building and running a simple NeXus program

#  builds HDF5 specific test
nxbuild -o napi_test-hdf5 napi_test.c

# runs the test
./napi_test-hdf5

NeXus is also set up for pkg-config so the build can be done as:

gcc `pkg-config --cflags` `pkg-config --libs` -o test test.c

5.6. Reporting Bugs in the NeXus API

If you encounter any bugs in the installation or running of the NeXus API, please report them online using our Issue Reporting system. (https://www.nexusformat.org/IssueReporting.html)