ESTEL:Configure Tecplot for ESTEL-3D

We decided a while ago to standardise on binary Tecplot output for ESTEL-3D. Tecplot is a very nice visualisation tool and works rather well for 3D data. Our results files tend to be large and supporting a binary format made sense to reduce file size. Conveniently, tecplot provide a library that called be accessed by Fortran routines to export directly in Tecplot format. Importantly, this library can be distributed with a commercial software such as ESTEL-3D (see below).

This page summarise the set-up required to get binary Tecplot output working with ESTEL-3D on your machine.

= Preparation of the Tecplot tree = Tecplot provides the library tecio.a (on 32-bits machines) and tecio64.a (on 64-bits machines). The version of the library depends on the version of Tecplot. Instead of using Tecplot's fancy version numbers, we version the libraries as:


 * tecplot10.a -> provided by Tecplot 10 release 6
 * tecplot110.a -> provided by tecplot 360 (release 1 or 2)

The relevant Tecplot library has to be copied and renamed to a tecplot/ folder organised in a similar way to that of the other modules of the TELEMAC system except that there are no sources. So if the root of the TELEMAC systel is systel90, you should have one of the following.

/path/to/systel90/tecplot/tecplot_10/library_version/tecplot10.a /path/to/systel90/tecplot/tecplot_110/library_version/tecplot110.a

For ESTEL-3D v5p6, only tecplot10.a is supported. Both versions are supported in ESTEL-3D v5p7. In any case, it is possible to have all these Tecplot libraries installed in parallel and to choose a specific one at compile time.

= ESTEL-3D v5p6 = Only tecplot10.a (from Tecplot 10r6) is supported in v5p6.

ASCII output is configured by default in ESTEL-3D-v5p6 as  stored on the subversion server, both in the makefile and the dictionary so manual editing will be required to set-up binary Tecplot support.

Compilation
In the makefile</tt>, there is a heading called "TECPLOT SUPPORT</tt>". You need to uncomment the relevant section under this heading. Note that no editing as such is required, merely uncomment the section you require and comment out the other one. Then compile ESTEL-3D as usual ("maktel cleanall install</tt>").

Dictionnary
The dictionary also need to be amended if Tecplot binary support is included. In the lib/</tt> folder, there are two templates:
 * estel3dv5p6.dico-notecplot</tt>: only ASCII output is supported
 * estel3dv5p6.dico-std</tt>: ASCII and binary output supported (binary default)

You need to create symbolic link called estel3dv5p6.dico</tt> which points to the required template. For instance if you want Tecplot support: $ ln -s estel3dv5p6.dico-std estel3dv5p6.dico $ ls -l total 156k lrwxrwxrwx 1 jp jp 26 Nov 24 12:37 estel3dv5p6.dico -> estel3dv5p6.dico-std -rw-r--r-- 1 jp jp 63K Dec 3 18:31 estel3dv5p6.dico-notecplot -rw-r--r-- 1 jp jp 63K Jan 16 17:11 estel3dv5p6.dico-std -rw-r--r-- 1 jp jp 286 Nov 24 07:25 README

If the symbolic link already exists, you will need to delete it first.

= ESTEL-3D v5p7 = in ESTEL-3D v5p7, the support for Tecplot output is greatly improved; the libraries from Tecplot10r6, Tecplot360 and Tecplot360r2 are all fully supported.

Choice of the library is done at compilation time. Modify the variable FORMAT_OUT</tt> in the makefile</tt> as necessary:

FORMAT_OUT = 110


 * 1) Key:
 * 2) - 110 : compilation using the tecio library from Tecplot 360r1 or Tecplot 360r2
 * 3) - 10 : compilation using the tecio library from Tecplot 10r6
 * 4) - ONLYASCII : compilation *without* binary Tecplot support

Then compile ESTEL-3D:
 * "maktel all</tt>" will compile the code against the chosen Tecplot library
 * "maktel install</tt>" will install the ESTEL-3D library and create a dictionnary lib/estel3dv5p7.dico</tt> matching the option chosen in the makefile</tt>
 * "maktel dico</tt>" only creates a dictionary lib/estel3dv5p7.dico</tt> matching the option chosen in the makefile</tt>

So basically, the manual steps required for ESTEL-3D v5p6 are all done automatically now.

To remember:
 * this new structure means that the dictionary in <tt>lib/</tt> might be overwritten when you recompile ESTEL-3D. So if you need to modify something in the dictionary, modify the template <tt>sources/estel3d.dico</tt> and run "<tt>maktel install</tt>" again.
 * if you only modify <tt>FORMAT_OUT</tt> in the <tt>makefile</tt> but leave the dictionary template untouched, the dictionary will not be recreated automatically. In that case you have to issue a "<tt>maktel cleanall</tt>" first and then "<tt>maktel install</tt>".
 * if you only modified the dictionary template and some source files but only want to rebuild the dictionary, use "<tt>maktel dico</tt>".

= Getting the Tecplot library = The Tecplot library can be found in the lib/ folder of the Tecplot installation root. It will be called tecio.a for a 32-bits machine and tecio64.a for a 64-bits machine. Recently, Tecplot Inc created a specific TecIO page on the website: http://www.tecplottalk.com/tecio.

Just to make sure we could find them all the time, we backed up some of the files. Choose the i386 link for a 32-bits machine and x86_64 link for a 64-bit machine. Note that only Linux binaries are listed so far. The src link gives you access to the sources. The "pdf" link is the relevant section of the Tecplot documentation describing the library:


 * <tt>tecplot110.a</tt> (Tecplot 360r1): i386 | x86_64 | pdf
 * <tt>tecplot10.a</tt> (Tecplot 10r6): i386 | x86_64 | pdf

= Limitations of the Tecplot library =

Although everything works rather well so far, it is important to remember the limitations inherent to using the proprietary library from Tecplot Inc.

No backward compatibility!
The Tecplot libraries are forward compatible and not backward compatible. Therefore, if you compile ESTEL-3D to use tecplot110.a (the library in Tecplot360r1 or Tecplot360r2), the resulting binary files will not be readable by Tecplot10r6. Furthermore, if you copied the tecio.a from Tecplot360r2, your files won't even be readable with Tecplot360r1!!

This is a very clear limitation as it means that you cannot exchange files with people using older versions of Tecplot!

Future access to data
Relying on Tecplot's internal format is potentially dangerous. We have no real assurance that we will still be able to read this format in 10 years time for instance. Therefore, it is advised to backup important data using the ASCII output option. The datafiles will be larger but will but at least human readable. Note that in practise, Tecplot 360r2 supports datafiles down to version 7.5 (1998).

The future
For the reasons mentioned above, we should probably re-think out Tecplot strategy. In particular, it could be better to support our own internal binary format (or an open format) and write data loaders for Tecplot to be able to manipulate directly our files. It also means that we could use other visualisation platforms easily.

= Redistribution of the Tecplot TecIO library = Redistribution of the Tecplot library within the TELEMAC system is allowed. The Tecplot license (at least for Tecplot 10r6, 360 and 360r2) states:

Utilities/Other Executables. Licensee is permitted to redistribute the included FRAMER executable to others provided that Licensee does not charge a fee for such distribution and the distribution is solely for the purpose of displaying movie files generated by Software. Licensee is permitted to redistribute the included TECIO libraries and the PREPLOT executable for the sole purpose of generating binary files compatible with the Software.

This has also been cleared with Jim Carson, (Tecplot Inc.'s Technical Product Manager): http://www.tecplottalk.com/viewtopic.php?t=62.