Programming Interface

XDI Programming Interface

This page describes the programming interface (API: Application Programming Interface) for the XDI File Library. The XDI File library provides methods and structured data for the XAFS Data Interchange File Format. Here, you will find a full listing of the functions and data avaliable for dealing with XDI formatted files.

XDI Files are plain-text files, and so should be readable by a large number of existing Applications and programming languages. The library described here should be viewed as the standard interface to XDI Files, and offers data structured in a way that is meant to be more useful than simply as plain text. Though XDI Files can be read in a variety of languages, the discussion here focuses on usage from the C programming language. Other languages will have similar APIs, typically derived from the C API, and will be discussed as > comments for each function.

Basic usage, XDIFile data structure

To use the XDI interface, include the line

  #include "xdifile.h"

In your C program. Principly, this defines the data structure for an XDIFile, which contains all the data from an XDI File.

The structure looks like this:

typedef struct {
  long nmetadata;       /* number of metadata key/val pairs */
  long narrays;         /* number of arrays */
  long npts;            /* number of data points for all arrays */
  long narray_labels;   /* number of labeled arrays (may be < narrays) */
  double dspacing;      /* monochromator d spacing */
  char *xdi_version;    /* XDI version string */
  char *extra_version;  /* Extra version strings from first line of file */ 
  char *filename;       /* name of file */
  char *element;        /* atomic symbol for element */
  char *edge;           /* name of absorption edge: "K", "L1", ... */
  char *comments;       /* multi-line, user-supplied comment */
  mapping *metadata;    /* key/value pairs for metadata from file header */
  double **array;       /* 2D array of all array data */
  char **array_labels;  /* labels for arrays */
  char **array_units;   /* units for arrays */
} XDIFile;

The mapping defined for the metadata is a simple structure:

typedef struct { char *key;  char *val;}  mapping;

so that each piece of metadata has a key holding the name of the metadata, and a val holding the string values.

readxdi

The principle way to read an XDI File is with the readxdi() function. This function has a signature of

int readxdi(char *filename, XDIFile *xdifile);

and so takes the name of the XDI file as its first object, and a pointer to an allocated XDIFile structure (defined in xdifile.h) as its second argument. The function return value is one of

 0   success.
-7   could not open file.
-6   out of memory to read file.
-5   file contains more than 16384 lines, and so cannot be valid.
-1   file does not begin with '# XDI/', and so cannot be valid.

The XDIFile structure will be filled with the data read and parsed from the XDI file.

Example Usage:

XDIFile *xdifile;
int ret;
char *filename;

xdifile = calloc(1, sizeof(XDIFile));
ret = readxdi(filename, xdifile);
if (ret < 0) {
   printf("Error reading %s: error code=%ld\n", filename, ret);
}
printf("Read XDI File!\nXDI version = %s\n", xdifile->xdi_version);
printf("Read %ld arrays, each with %ld data points\n", xdifile->narrays, xdifile->npts);

get_array_index

get array by column number

get_array_name

get array by name

get_energy

get the array of energy values, in eV.

get_angle

get the array of monochromator angles, in degress.

get_element

get the atomic symbol for the absorbing element.

get_edge

get the absorption edge.

get_metadata

get a value from the metadata table given its key.

write_file

write an XDI file from the supplied XDIFile structure.