Input/Output in the Open FUSION Toolkit

Table of Contents

• Visualization and Plotting
  • Field Representation
• Restart Files
• Miscellaneous I/O

User and program I/O in the Open FUSION Toolkit (OFT) is supported by the use of native FORTRAN input/output routines as well as the HDF5 library. General input and output operations fall into one of three catagories:

• Visualization and plotting: HDF5 one file per domain
• Solver restart files: HDF5 one file for the entire mesh
• History files and other I/O: Native FORTRAN serial input and output

Visualization and Plotting

OFT includes subroutines and supporting infrastructure to export plot files for the VisIt visualization package. During a run subroutines are used to output the plotting mesh hdf5_mesh, add time steps hdf5_create_timestep, and output solution fields ex. hdf5_spdata. Mesh and field information created during these calls are stored in *.h5 files in the run directory along with a text file dump.dat which contains metadata describing the fields. After a run has completed the script build_xdmf.py can be used to build XML descriptor files which can be read by VisIt to produce visualization.

Field Representation

Plotting fields are represented using a Lagrange representation for the fields. A "plotting" mesh is generated by hdf5_mesh, which is produced by tessellating the high order node points into a collection of linear tetrahedra. Fields can be output using the routines hdf5_spdata and hdf5_vpdata for scalar and vector data respectively.

Restart Files

Restart files are handled in a different manner than plotting files, as it is desirable to save fields in their native format. A single common restart file is created for the entire mesh and written to using calls to the parallel HDF5 library. Fields are saved by first converting the native vector representation to a restart structure using vector_slice_push and then writing the data using hdf5_rst_write. Additional scalar values may also be added to the restart files using the hdf5_rst_write_scalar subroutine.

To read in fields from a restart file a similar process is used. The restart structure must first be created using a call to vector_slice_push with the destination vector. A call to hdf5_rst_read may then be used to read the field from the desired data file. The field is the retrieved from the restart structure using vector_slice_pop. Additional scalar values may also be read using hdf5_rst_read_scalar.

Warning

Fields must be in native format when passed to vector_slice_push and vector_slice_pop

Miscellaneous I/O

Small I/O should be conducted using the native READ/WRITE routines provided within FORTRAN. If formatted time series or similar data is being output, as with history files in xMHD, OFT includes a Python module oft_io to aide in structured output. This module parses FORTRAN binary files with a specific structure to facilitate plotting and transfer to MATLAB. In order to use this library files must be structured with a set of header lines, followed by a sequence of data lines. An example is provided below.

INTEGER(i4) :: i,n
REAL(r8) :: t,tflux,tcurr
!---History file variables
TYPE(oft_bin_file) :: hist_file
INTEGER(i4) :: hist_i4(1)
REAL(r4) :: hist_r4(3)
!---Setup history file
IF(psi%head_proc)THEN
  CALL hist_file%setup('example.hist', desc="Example history file")
  !---Add fields (always in order "i4", "i8", "r4", "r8")
  CALL hist_file%add_field('ts',   'i4', desc="Time step index")
  CALL hist_file%add_field('time', 'r4', desc="Simulation time [s]")
  CALL hist_file%add_field('tflux','r4', desc="Toroidal flux [Wb]")
  CALL hist_file%add_field('tcurr','r4', desc="Toroidal current [A*mu0]")
  !---Add additional comments
  CALL hist_file%add_comm("Test comment")
  !---Write header
  CALL hist_file%write_header
END IF
!
! Do some work
!
!---Produce and output data
IF(psi%head_proc)CALL hist_file%open ! Open history file
DO i=1,n
  !
  ! Do some work
  !
  IF(psi%head_proc)THEN
    hist_i4 = (/i/)
    hist_r4 = (/t,tflux,tcurr/)
    CALL hist_file%write(data_i4=hist_i4, data_r4=hist_r4)
    IF(mod(i,10)==0)CALL hist_file%flush ! Periodically flush buffered I/O
  END IF
END DO
IF(psi%head_proc)CALL hist_file%close ! Close history file

For the example above the header lines will contain the following. Binary data starts after the --- BEGIN DATA --- marker and can be read using the oft_io python module.

# OFT binary output
# Description: Example history file
# Created: XX:XX:XX on  X-XX-20XX
#
# Comments:
#  Test comment

nfields:      4
fields: ts time tflux tcurr
field_types: i4 r4 r4 r4
field_sizes:      1      1      1      1
descriptions:
  - ts: Time step index
  - time: Simulation time [s]
  - tflux: Toroidal flux [Wb]
  - tcurr: Toroidal current [A*mu0]


--- BEGIN DATA ---