Array ordering and centering conventions

The convention we assume for indexing arrays is that used in C language (``row-major'' order). For a real array of dimensions $[n_{x},n_{y},n_{z}]$, array values are to be stored in "/adi" and "/spt" groups in the index order

[0,0,0], [1,0,0], $\ldots$, [($n_{x}$-1),0,0], [0,1,0], $\ldots$.

Therefore if one were to make a triple-indexed 3D array in C, it would be indexed as array_3d[iz][iy][ix], but in fact most of the code uses a single array index of array_3d[i] which should be indexed as

 for (iz=0; iz<local_nz; iz++)
   for (iy=0; iy<ny; iy++)
     for (ix=0; ix<nx; ix++)
       i = ix+iy*nx+iz*nx*ny;
       array_3d[i] = ...

The case of complex arrays such as used in the "/itn" group in HDF 5 files has a bit more to it, as described in Sec. 1.4.4.

Fast Fourier transform or FFT algorithms rearrange the data from input to output. It is important to agree on a convention for how the data is to be arranged; the convention we have adopted is as follows:

Data centering refers to having the center pixel at array location $[n_{x}/2,n_{y}/2,n_{z}/2]$. This is usually used in real or image space, and thus is the convention used for "/spt" and "/itn" groups.

FFT centering refers to having the zero frequency pixel (which would normally be in the center of a diffraction pattern) at array location $[0,0,0]$. This is usually used in reciprocal (or Fourier or diffraction) space, and thus is the convention used by the "/adi" group in files. The data must be arranged in this manner before routines such as dm_fileio_write_adi are called, and routines such as dm_fileio_read_adi will return an array that is FFT centered.

These conventions are illustrated in Fig. 1.1. The .nc raw data files violate this convention, in that the are recording data in reciprocal space but the CCD chip is meant to be positioned so that the center, zero-spatial-frequency pixel is at the array location $[n_{x}/2,n_{y}/2]$ for array indices starting from $[0,0]$ (more on this in Sec. 3.5.2).

Figure 1.1: Schematic of the centering of arrays. Data in real space is meant to have the center of the image at pixel $[n_{x}/2,n_{y}/2]$, while data in reciprocal (or Fourier or diffraction) space has the zero spatial frequency pixel at array location $[0,0]$.