Handling binary data

The wave-functions used by TALISES are saved as binary data files. The binaries do not only contain information of the wave-function amplitudes at every grid point, but also contextual information like the time, position space size, sampling rate and more.
The binary is comprised of a header containing this additional information and the body containing the wave-functions real and imaginary amplitude at every space point.

File structure

The header is 1380 bytes long. Its structure is described in the \include\my_structs.h file. It reads

struct generic_header
{
  long long nself;    // size of struct
  long long nDatatyp; // size of data type
  long long nself_and_data;
  long long nDims;
  long long nDimX;
  long long nDimY;
  long long nDimZ;
  int       bAtom;
  int       bComplex;
  double    t;
  double    xMin;
  double    xMax;
  double    yMin;
  double    yMax;
  double    zMin;
  double    zMax;
  double    dx;
  double    dy;
  double    dz;
  double    dkx;
  double    dky;
  double    dkz;
  double    dt;
  int       ks; // coordinate system
  int       fs; // 1 -> fourier space, 0 -> real space
  double    M;  // mass in kinetic term
  double    T_scale  //arb. scaling of time unit;
  int       nFuture[99]; // Buffer
  double    dFuture[98];
};

Much of this information is necessary for TALISES in order to calculate the wave-functions time-propagation and some information is just useful for the user. The binaries following the header represent the real and imaginary wave-function amplitudes, where each number is double float precision (8 Bytes). For example, a wave-function represented by 256x256 grid points takes memory of

As binary files are notoriously hard to read for the regular user, we provide a python package talisestools that simplifies data handling.

The talisestools package

The package can be install via

pip install talisestools

It provides the following functions:

talisestools.readbin(binary_file, save=False):

The readbin function reads a TALESIS generated binary file containing one or multiple wavefunctions. It returns a dictionary containing the binary data of wave-function amplitudes, time ect. Optionally one can save the binary file as a .mat file.
    Paramters: binary_file: string of binary file name generated by TALISES
    Optional Paramters: save: If True, saves binary file as a seperate .mat file. Default is False
    Returns: Dictionary with keys 'wavefunction', 'nDims', 'nDimX', 'xMin', 'xMax', 'dx', 'M', 'T_scale', 't'.
     In the 2D and 3D case there will also be keys for 'nDimY' ect..

talisestools.plotbin(binary_file):

plotbin is a fast way of plotting a TALISES generated binary file containing one wavefunction in 1D and 2D. It generates a .png file of the same name.
    Paramters: binary_file: string of binary file name generated by TALISES
    Optional Paramters: None
    Returns: None

talisestools.readall(n_int_state, save=False ):

The readall function generalizes the readbin function. During computation of the wave-function's time propagation TALISES generates seperated binary files for the different internal states. The files end in _1.bin, _2.bin for the first, second ect. internal state. The readall function takes an integer argument specifying this internal state and tries to find all binary file associated with it. It then returns a dictionary containing the binary data of wave-function amplitudes, time ect. of all found binary files. Optionally one can save the binary file as a .mat file.
    Paramters: n_int_state: integer specifying internal state
    Optional Paramters: save: If True, saves binary file as a seperate .mat file. Default is False
    Returns: Dictionary with keys 'wavefunction', 'nDims', 'nDimX', 'xMin', 'xMax', 'dx', 'M', 'T_scale', 't'.
     In the 2D and 3D case there will also be keys for 'nDimY' ect..