Getting Started

To start using Lib_VTK_IO, you must import its main module:

USE Lib_VTK_IO

Now you have all the IO procedures available for saving your Fortran data into VTK compliant file. Presently, only the exporter is available. Exporting Fortran data must follow an ordered list of statements:

• Initialize the VTK file;
• eventually add auxiliary data to the VTK file;
• eventually add geometry data to the VTK file;
• eventually add data fields associated to the geometry to the VTK file;
• finalize the VTK file;

These are the main steps you must follow, but this is not a complete list of available actions neither it is mandatory to do all items. It is worth noting that the library presently provides 4 different sets of procedures for the 4 main kind of files supported:

1. VTK XML standard;
2. VTK-VTM XML standard;
3. PVTK XML standard;
4. legacy standard.

It is worthy to note that all defined procedures are functions returning the eventual error code (integer): if the error code is equal to zero no errors occur, otherwise if the code is different from zero something went wrong.

In this getting-started guide only some of the XML standard procedure are briefly described, for a more complete guide see the API documentation and the usage guide.

Let us assume that we want to save a StructuredGrid Fortran data. Let us assume Our working variables being defined as:

integer(I4P), parameter::                       nx1=0_I4P,nx2=9_I4P,ny1=0_I4P,ny2=5_I4P,nz1=0_I4P,nz2=5_I4P
integer(I4P), parameter::                       nn=(nx2-nx1+1)*(ny2-ny1+1)*(nz2-nz1+1)
real(R8P), dimension(nx1:nx2,ny1:ny2,nz1:nz2):: x,y,z
real(R8P), dimension(nx1:nx2,ny1:ny2,nz1:nz2):: v_R
integer(I4P)::                                  E_IO
integer(I4P)::                                  i,j,k

and initialized as:

do k=nz1,nz2
  do j=ny1,ny2
    do i=nx1,nx2
      x(  i,j,k) = i*1._R8P
      y(  i,j,k) = j*1._R8P
      z(  i,j,k) = k*1._R8P
      v_R(i,j,k) = real(i*j*k,R8P)
    enddo
  enddo
enddo

Saving these data in a VTK XML file is very simple, just do:

1. Initialize the file

E_IO = VTK_INI_XML(output_format='binary', filename='XML_STRG.vts', &
                   mesh_topology='StructuredGrid', nx1=nx1, nx2=nx2, ny1=ny1, ny2=ny2, nz1=nz1, nz2=nz2)

This function initializes the VTK file. For its complete signature see the API documentation. The most important parameters are the output format and the mesh topology:

• Supported output formats are (the passed specifier value is case insensitive):
  • ASCII: data are saved in ASCII format;
  • BINARY: data are saved in base64 encoded format;
  • RAW: data are saved in raw-binary format in the appended tag of the XML file;
  • BINARY-APPENDED: data are saved in base64 encoded format in the appended tag of the XML file.
• Supported topologies are (the passed specifier value is case sensitive):
  • RectilinearGrid;
  • StructuredGrid;
  • UnstructuredGrid.

It is worthy to note that nx1, nx2, ny1... indicates the whole extents contained into the file. As a matter of fact, XML file can contain more than one piece, each peace having its own geometry and associated data.

2. Adding global auxiliary data

Often it is useful to associate global auxiliary data to the file (e.g. time, step number, dataset name, etc). To this aim the library provides the VTK_FLD_XML function, being an interface to 7 different functions: there are 2 functions for real field data, 4 functions for integer one and one function for open and close field data tag. For its complete signature see the API documentation. VTK_FLD_XML must be called after VTK_INI_XML and before VTK_GEO_XML. It must always called three times at least:

2.1 Opening the FieldData tag

E_IO = VTK_FLD_XML(fld_action='open')

2.2 Saving at least one FieldData entry

E_IO = VTK_FLD_XML(fld=0._R8P,fname='TIME')
E_IO = VTK_FLD_XML(fld=1_I8P,fname='CYCLE')

2.3 Closing the FieldData tag

E_IO = VTK_FLD_XML(fld_action='close')

3. Adding a piece

A VTK XML file can contain one or more pieces. Thus for each piece the following steps are necessary.

3.1 Saving the geometry

E_IO = VTK_GEO_XML(nx1=nx1, nx2=nx2, ny1=ny1, ny2=ny2, nz1=nz1, nz2=nz2, NN=nn, &
                   X=reshape(x(nx1:nx2,:,:),(/nn/)),                            &
                   Y=reshape(y(nx1:nx2,:,:),(/nn/)),                            &
                   Z=reshape(z(nx1:nx2,:,:),(/nn/)))

It is worthy to note that nx1, nx2, ny1... indicates the piece extents that incidentally (for this example) coincide with the whole extents.

3.2 Saving the data associated to the geometry

The data associated to the geometry can be either allocated to the nodes vertices or to the cells centers.

3.2.1 Opening the Data tag

The VTK_DAT_XML initializes the saving of data variables indicating the data location (node or cell centered) of variables that will be saved. A single file can contain both cell and node centered variables.

E_IO = VTK_DAT_XML(var_location = 'node', var_block_action = 'open')

3.2.2 Saving the Data

To save your data you must use VTK_VAR_XML function, being an interface to 36 different functions: there are 6 functions for scalar variables, 6 functions for vectorial variables and 6 functions for 3D(or higher) vectorial variables. For all of types the precision can be R8P, R4P, I8P, I4P, I2P and I1P. This function saves the data variables related (cell-centered or node-centered) to geometric mesh. For its complete signature see the API documentation.

E_IO = VTK_VAR_XML(NC_NN = nn, varname = 'node_value', var = reshape(v(nx1:nx2,:,:),(/nn/)))

It is worth to note that the inputs arrays can be passed as 1D-rank or 3D-rank and the vectorial variables can be component-separated (one for each of the 3 components) or packed into one multidimensional array:

• scalar input:
  • input is 1D-rank array: var[1:NC_NN];
  • input is 3D-rank array: var[nx1:nx2,ny1:ny2,nz1:nz2];
• vectorial inputs:
  • inputs are 1D-rank arrays: varX[1:NC_NN],varY[1:NC_NN],varZ[1:NC_NN];
  • inputs are 3D-rank arrays: varX[nx1:nx2,ny1:ny2,nz1:nz2],varY[nx1:nx2,ny1:ny2,nz1:nz2],varX[nx1:nx2,ny1:ny2,nz1:nz2];
• 3D(or higher) vectorial inputs:
  • input is 1D-rank (packed API): var[1:N_COL,1:NC_NN];
  • input is 3D-rank (packed API): var[1:N_COL,nx1:nx2,ny1:ny2,nz1:nz2].

Note that the inputs that must be passed change depending on the data variables type.

3.2.3 Closing the Data tag

E_IO = VTK_DAT_XML(var_location = 'node', var_block_action = 'close')

3.3 Finalize the current piece

Calling the VTK_GEO_XML function close the current piece tag in order to be able to save a new one if any.

E_IO = VTK_GEO_XML()

4. Finalize the file

Once all pieces have been saved the file can be finalized.

E_IO = VTK_END_XML()

The steps above described are similar for any XML VTK kinds and for any topologies.