Binary files

There are several input deck blocks which can read conditions directly from a user-specified file. These include the , and . In all such cases, the files specified must be in a simple binary format, often referred to as “raw” binary files.

Binary files are machine readable, but not human readable. If you try opening a binary file in a text editor then you will see incomprehensible characters and some text editors might even crash. Most languages can write binary files, see “writeu” (in IDL/GDL), “fwrite” in MatLab, the “b” parameter to “open” in Python and “form=‘UNFORMATTED’ " in Fortran, so please see the documentation for those languages. Note that standard unformatted output in Fortran also writes some additional hidden output to the file that alters the offset of the actual binary array data within the file. It is therefore recommended that you always use the “access=‘STREAM’ " modifier whenever writing such files from Fortran programs.

For illustration purposes, here is a simple example of writing a 2D array to file using Fortran:

PROGRAM output_array

INTEGER :: iu, istat 
INTEGER, PARAMETER :: nx = 10, ny = 20 
DOUBLE PRECISION :: array(nx,ny) 
CHARACTER(LEN=*), PARAMETER :: filename = ’array.dat’

array = 2.0d0

OPEN(newunit=iu, file=filename, status=’NEW’, form=’UNFORMATTED’, & access=’STREAM’, iostat=istat)

IF (istat == 0) THEN WRITE(iu) array CLOSE(iu, iostat=istat) ELSE PRINT*, ’ERROR: failed to open file ’, ’“’ // filename // ’”’, & ’ for writing’ END IF

END PROGRAM output_array

In this example, there are 200 array elements written to file (10 * 20). Each element is a double-precision number which is 8 bytes. Therefore, the total file size will be 1600 bytes. Note that for Fortran, arrays are indexed using “column-major order”. This means that in the file, the first array element “array(1,1)” will be followed by “array(2,1)” and so on up to “array(10,1)”. After this, the second index will be incremented and the array element “array(1,2)” will be output, followed by “array(2,2)”, etc. In contrast, languages such as C and C++ use row-major order. For these languages the array output is transposed, so the array elements are output in the order: “array[0][0], array[0][1], .. array[0][19], array[1][0], ..”

Simple binary files merely contain a long sequence of real numbers and do not contain any information about the shape of the arrays that have been written. This information must be supplied using the input deck. These should correspond to the values of “nx”, “ny”, etc. For example, to use the array generated by the Fortran code shown above, the input deck must specify “nx = 10” and “ny = 20”.

It is possible to write multiple arrays into the same binary file and use the “offset” comand in the input deck to specify where the next array in the file is to be located. This can be tricky to work with and it is therefore recommended to write each separate array to its own file.