Installation procedure with Perl

 

The TELEMAC system is written in Fortran (standard Fortran 95). The mathematics, the physics, the advanced parallelisation, all in Fortran. Surrounding the scientific code, are a series of scripts to compile, prepare the input and output files and run the modules of the TELEMAC system. This note sums up the installation procedure of the TELEMAC system on Unix, Linux and Windows operating systems, when using the scripts written in Perl (standard Perl 5).

 

Important note

Perl has been the preferred scripting language for a long time, including during the commercial distribution of the TELEMAC system. While this language was suited to the expert developers and distributors of the system, the Perl language suffers a number of disadvantages when compared to newer scripting languages. For instance, Perl is not cross-platform and special cases have to be programmed to make the TELEMAC system work on Unix, Linux and MS Windows operating system. Therefore and since the open source distribution of the TELEMAC system, its surrounding scripts were re-designed in Python (standard python 2.7). The Python scripting language is cross platform and much simpler to read, so much so that it is nowadays taught as the first programming language in schools. Eventually, all scripts of the TELEMAC system will be re-written in Python. Another article on this web site details the TELEMAC installation procedure with Python. If you are a new user of the TELEMAC system it is recommended that you use that other installation procedure.

 

Prerequisites

Perl

As a minimum, this installation of the TELEMAC system requires the Perl scripting language installed on your computer (standard Perl 5). If you are not yet at a stage of using the TELEMAC system in its parallel mode and you do not need to re-write parts of the scientific Fortran code to include specificities of your own application, Perl is all you need.

You should find many resources explaining the language (mainly reported from the main site following this link: Perl 5) with tutorials and video; the following might also be of interest: "tom.carter@wiht".

Here is the free solution to dowanload and install depending on your operating system:

  • Perl comes default on many of the latest Linux and Unix operating systems. We recommend that you use Perl version 5.6.0 or above. Scripts may not work otherwise. To check this, just type the following in a terminal console:
    $> perl -v
  • On MS Windows operating system, we suggest you use the so-called "Strawberry Perl" as msi files (self install program) are provided for both 32bit and 64bit operating systems. Strawberry Perl is compatible with MS Windows XP, 2003, Vista, 2008 and MS Windows 7 and includes version 5.12.1 (note that problems have been reported with later version 5.12.3 on Windows 7). Once installed, please make sure that Perl is accessible to you. Just type the following in a DOS command windows:
    \> perl -v

Fortran

This part of the document has been transfered over to the WIKI side: Configuration of Fortran

Parallel setup

Optionally, if you wish to use the TELEMAC system in its parallel form (this is also easy to do!), the TELEMAC system will require in the first instance either the MPICH2 implementation of the Message Passing Interface standard (MPI-2) or the OpenMPI implementation of the same standard (MPI-2). Both are freely available for Linux and MS Windows operating systems supporting both 32b and 64b mode.

  • On Linux operating systems, we recommend that you use the OpenMPI implementation of the MPI-2 standard, as we found its installation to be more coherent between Linux flavours. The installation of OpenMPI can be achieved through the standard install utility (aptitude on Debian/Ubuntu, zypper on OpenSUSE, yum on Fedora, etc.). The advantage of this method is that it will check dependencies and install all required files and libraries. The disadvantage is that it is not obvious as to where the installed files are. You will need to check where the include and lib files are. To check where the main executable is, just type the following in a terminal console:
    $> which mpiexec
    You will have to update the TELEMAC configuration file and one of the makefile to complete your installation procedure with Perl (see below).
  • On MS Windows operating systems, we recommend that you use the MPICH2 implementation of the MPI-2 standard. The self-install file can be downloaded as free software. On installation, we further recommend that you install it within a directory structure without space (i.e. not within "Program Files"). To make the TELEMAC installation process easier for you later, you can install it under "c:\opentelemac\mpi\", where "mpi" replaces "MPICH2" (for instance). Once installed, please make sure that mpiexec is accessible to you. Just type the following in a DOS command windows:
    \> mpiexec
    You will have to update the TELEMAC configuration file and one of the makefile to complete your installation procedure with Perl (see below).

In the second instance, the system will require the presence of a pre-compiled library, the so-called METIS library developed at the Karypis Lab of the University of Minnesota. This library is used by the TELEMAC utility program called PARTEL, written in Fortran, which split your model domain into a number of optimised and balanced pieces of puzzles.

  • On Linux operating systems, you can download the file metis-4.0.3.tar.gz (or later version) from the website above and then compile the library. Just type the following in a terminal console:
    $> gunzip metis-5.1.0.tar.gz
    $> tar -xvf metis-5.1.0.tar
    $> cd metis-5.1.0/
    $> make
    This will create a file called libmetis.a. You will have to update the TELEMAC configuration file and one of the makefile to complete your installation procedure with Perl (see below).
  • On MS Windows operating systems, unfortunately we have not yet found an easy way to compile the METIS library locally. Therefore, you have to download the pre-compiled library from the website above, which is only valid for the Intel Fortran compiler.
    Should you have any question with this, we could provide you with the pre-compiled PARTEL utility, so you would not need to worry about METIS not having to compile PARTEL.
    You will have to update the TELEMAC configuration file and one of the makefile to complete your installation procedure with Perl (see below).

Finally, we are working hard at the paralellisation of ARTEMIS, one of the wave module of the TELEMAC system, and we are now linking it to an existing linear algebra library called MUMPS (a MUltifrontal Massively Parallel sparse direct Solver written in Fortran) from the French school of engineering, ENSEEIHT. This library offers sequential or parallel direct solver. It is probable that the same solver be used in the rest of the TELEMAC system (for instance for 3D tracers). With version v6p1 of the TELEMAC system, you will see references to MUMPS appearing in the configuration file and the makefiles. You should not have to modify these at this stage.

Once the above programs and libraries are installed, the rest of the configuration is set in the TELEMAC configuration file (see below). Should you have any question on the parallelism, you can either post questions on the forum or write to This email address is being protected from spambots. You need JavaScript enabled to view it. or to the appropriate contact of the list on this website.

 

Downloading the TELEMAC system for your computer

Since the release v6p1 of the TELEMAC system we are confronting users and developers with two choices:

  1. A download of a zipped file, including the source code and the TELEMAC tree structure. This is the way it has always been done in the past. The principal disadvantage of this method is that updates have to be re-packaged, re-downloaded and re-installed in full.
    In the download area of this website, you can choose the Sources: Zip menu, download the zipped file and extract its contents.
  2. A download through the SVN subversion system, with a more mordern access to the source code and its various updates. The principal advantage of this method is that the sources code remains linked to the developpers' main repository and that updates are just updates.
    In the download area of this website, you can choose the Sources: SVN menu, which explain how to link to the newly extract its contents.

If you are a new user of the TELEMAC system or if you know about professional quality controled source code management system such as SVN subversion already, it is recommended that you use the second downloading procedure as it much simpler than its zipped equivalent.

Important note

It is critical that the TELEMAC system be stored within a directory path with no spaces (i.e. not in "Program Files" for instance). For instance, under c:\opentelemac\v6p2 on MS Windows operating system or /home/user/opentelemac/v6p2 on Linux operating systems. This path will be referenced as "~root" in the rest of this documentation.

Once copied, zipped or untarred, or just checked out from the SVN repository, your TELEMAC directory (referenced here as ~root, see important note above) should contain a number of sub-directories. These are now described on the WIKI side: Structure of the TELEMAC-MASCARET system

 

Installing and configuring the TELEMAC system on your computer

A (small) number of environment variables must be set in your user profile. Namely you have to modify the variable $PATH and to create a new variable called $SYSTELCFG. Once these are setup, one configuration file (the "systel.ini" file) has to be modified depending on your operating system configuration.

$PATH

For the installation procedure with Perl, the "bin" directory for TELEMAC (at the ~root) should be added to your PATH. In addition, you should make sure that the "bin" directory for Perl is also in your PATH. Here is the instruction to do so depending on your operating system:

  • On Linux and Unix operating system, you can add the following line to your .profile or .bashrc files, depending on your preferences and on the shell script used:
    export PATH=/home/user/opentelemac/v6p2/bin:$PATH
    Please note that the symbol ":" is used as separator on Linux and Unix operating systems.

  • On MS Windows operating systems, you need to open your Control Panel's System windows, access your Environment Variables from the Advanced tab and then click New/Edit in the top "user" part for the PATH variable to add:
    c:\opentelemac\v6p2\bin
    Please note that the symbol ";" is used as separator on MS Windows operating systems.

Optionally, if you are using a Fortran Compiler, you should make sure that it is accessible to you within a command line windows or terminal, and if you are using TELEMAC in parallel, you should make sure that MPI utilities such as mpiexec and mpif90 depending on operating system are also within your PATH.

$SYSTELCFG

The variable SYSTELCFG provides TELEMAC with the path to the directory ~root/config, the directory including all configuration files. For the installation procedure with Perl, the directory should include the file "systel.ini", which defines your computer configuration for TELEMAC. In the same way it was done for the PATH, here is the instruction to do so depending on your operating system:

  • On Linux and Unix operating system, you can add the following line to your .profile or .bashrc files, depending on your preferences and on the shell script used:
    export SYSTELCFG=/home/user/opentelemac/v6p2/config
    Please note that SYSTELCFG only supports one path.

  • On MS Windows operating systems, you need to open your Control Panel's System windows, access your Environment Variables from the Advanced tab and then click New/Edit in the top "user" part for the SYSTELCFG variable to add:
    c:\opentelemac\v6p2\config
    Again, please note that SYSTELCFG only supports one path.

Important note

For the installation procedure with Perl, ...

  • ... the environment variable SYSTELCFG sets the directory where TELEMAC will find the file "systel.ini".
    For the installation procedure with Python, the environment variable SYSTELCFG sets the configuration file and its path, without assuming that the name of the file would be "systel.ini". The Python scripts will recognise the Perl's setup as long as a file named "systel.cfg" co-exists in the configuration directory
    .
  • ... the "systel.ini" file is used by the TELEMAC script "cfgmak.pl" to build other files and therefore, any modification to the "systel.ini" must be followed by the command: cfgmak (which is in ~root/bin).
    It could be noted that for the installation procedure with Python, the equivalent configuration file is directly interpreted by TELEMAC.

The systel.ini file

For the installation procedure with Perl, the core of the TELEMAC configuration lies in the "systel.ini" file (this file name is required by TELEMAC and can not therefore be renamed) situated at the address given by the environment variable $SYSTELCFG (see above). Again, because this file is used by the TELEMAC script "cfgmak.pl" to build other files, ny modification to it must be followed by the command: cfgmak (which is in ~root/bin).

The file "systel.ini" is made of 4 sections, where sections are separated by names in square brackets (i.e. [GENERAL]) and where each section contains a number of pairs key = value (i.e. PROJECT = c:\opentelemac\v6p2). The sections are as follows:

  1. [GENERAL]: is there to set the user defined version numbers and language.

  2. [INSTALLATION]: is there to set the ~root directory for TELEMAC -- key PROJECT -- and the name of the configuration -- key HOSTTYPE -- which itself is used to refer to a user defined section.

  3. [PERL]: is there to set the installation directories for the Perl scripting language, subdirectories bin lib.

  4. [user-configuration-name]: referenced by the value of the key HOSTTYPE in the [INSTALLATION] section, this section defines principally the options of the Fortran compiler and of the linking to the external libraries (such as MPI).

The details of the keys and values for each sections is as follows:

1. [GENERAL]

This section has two types of keys:

  • LNG*: sets the language for a module of the TELEMAC system (value 1  for French; value 2 for English)
  • VERS*: sets the version number for a module of the TELEMAC system, which nowadays must be the same for all module (to ensure compatibility beetwen modules)

For instance for TELEMAC-2D and TELEMAC-3D, version v6p2, in English:

#---TELEMAC2D
LNGTEL=2
VERSTEL=v6p2
#---TELEMAC3D
LNGTEL3D=2
VERSTEL3D=v6p2

The version names can be lower or upper case but must represent a version of the TELEMAC system that is installed on your computer.

2. [INSTALLATION]

This section has two keys:

  • PROJECT: path to the installation directory (~root)
  • HOSTTYPE : historically the type of machine, or the name of a couple machine-compiler. This key should be used to switch between configurations and options for instance to support multiple compiler configuration for a single computer.

For instance, with ~root defined as c:\opentelemac\v6p2 and a user defined name for a configuration based on MS Windows, the Intel Fortran compiler, coded 32bit and used in scalar mode:

PROJECT = c:\opentelemac\v6p2
HOSTTYPE = wintel32s

Again, the value above -- "wintel32s" -- is arbitrary and user defined, but must appear as its own section header. It can be lower or upper case.

3. [PERL]

This section has two keys:

  • PERLPATH: the path to the "bin" directory of your Perl installation
  • PERL5LIB: the path to the "lib" dirctory of your Perl installation

For instance on most Linux operating systems:

PERLPATH = /usr/bin
PERLLIB = /usr/lib

 4. [user-configuration-name]

This section has a larger number of keys necessary to configure your Fortran compiler and your libraries. Here [user-configurtaion-name] takes the value defined by the user, for instance [wintel32s]. In order to help with this setup a number of pre-defined configurations have been stored in "systel-all.ini". It is therefore recommended that you make a copy of this file, rename it "systel-ini" and select the most appropriate HOSTTYPE value for your own configuration.

In this section of the file or in any of these sections (should you define multiple configurations for your computer) the following keys are required:

  • DIRLIB: name of the directory where the libraries and executables for each module will be stored -- the name is used to create a subdirectory within the tree structure of each module at the same level as the "source". In practice, this name is often chosen by users as the value of the HOSTTYPE itself.
  • FC_NAM: defines the executable name of your Fortran compiler command (for instance, FC_NAM="ifort", FC_NAM="f90", FC_NAM="g95" or FC_NAM="gfortran-4.5")
  • FC_OPT_OBJTEXT: defines the name of the extension of the object files (for instance FC_OPT_OBJTEXT=“o”, or FC_OPT_OBJTEXT="obj")
  • FC_OPT_COMPIL: defines the Fortran compilation options (for instance "–c –O2 –convert big_endian”)
  • LK_NAM: defines the name of the linker on your operating system (for instance "xilink")
  • LK_OPT_NORMAL: defines the linker options (for instance " -lf2c -lm -lz -lstdc++ ")
  • FC_OPT_INCLUDE: defines the compiler command for including file. (for instance “/include:”)
  • LK_OPT_OUTNAME=" /out:" : extension for object files
  • LK_LIB_SPECIAL: extra libraries, here example of libraries MED and HDF5 " /home/MED/libmed.a /home/MED/libhdf5.a"
  • LIB_NAM: defines the name of the library linker (for instance "xilink -lib")
  • LIB_OPT_LIBEXT: defines the extension name of the static archives and library files (for instance "lib" or "a")


    Other options includes:
  • FC_OPT_PROFILE: defines profiler options (for instance “-c -O2 -pg -convert big_endian”
  • FC_OPT_OTHERS: defines extra options
  • LK_OPT_DEBUG, LK_OPT_PROFILE and LK_OPT_OTHERS for similar settings of your linker
  • LIB_OPT_OTHERS for similar settings of your library archiving

Optionally, the following options relates to the parallelism:

  • FC_MPI: defines the name for the MPI wrapper (for instance "/mpi//bin/mpif90" for the Intel Fortran compiler)
  • LK_MPI: defines the compilations options (for instance "/mpi//bin/mpif90 -o ")
  • LIBS_MPI: defines the options of the MPI linker (for instance "-L /mpi//lib –lmpich -lf2c -lm -lz -lstdc++ "
  • RUN_MPI: the command to run mpiexec and its options (for instance "/mpi//bin/mpirun -machinefile mpirun.txt)

 

Important note

There is also a dependency in the makefiles of the parallel module, ... 

  • ... where INCMPI should point to the include subdirectory of your MPI-2 implementation. By default it is set to $(PROJECT)/mpi/$(DIRLIB)/include, where $(PROJECT) is replaced by ~root.
  • ... and where LKLIB should include a reference to the pre-compiled METIS library. By default it is set to $(PROJECT)/parallel/parallel_$(VERSION)/$(DIRLIB)/libmetis.a

 

Compiling the whole TELEMAC system

To complete the installation procedure with Perl, there are two methods for compiling the TELEMAC system:

  1. The global approach, here recommended, with only one command compiling all modules and automatically organising dependencies between modules of the system. This process takes between 10 and 40 minutes depending on compilers and operating systems;
  2. The step by step approach, with the individual compilation of modules by the user, following the appropriate order of compilation for inter-dependencies between modules.

The global approach - compiling the TELEMAC system at once

There are two commands for compiling the TELEMAC system under the global approach, one for a compilation in a standard (or scalar) mode, and one for a compilation in a parallel mode. Dependencies to external libaries in the parallel mode makes the compilation of the TELEMAC system slightly more complicated in that mode.

  • Under either MS Windows or Linux operating systems, the compilation of the entire TELEMAC system in a standard (or scalar) mode is achieved by typing the following in a terminal or DOS console:
    $>,\> makeall90
  • Under either MS Windows or Linux operating systems, the compilation of the entire TELEMAC system for parallel use is achieved by typing the following in a terminal or DOS console:
    $>,\> makepar90

These commands compiles all libraries, modules, executables and put them in relevant directories. They are based on scripts included under the bin directory (at the ~root), the main Perl scripts being makeall90.pl and makepar90.py.

Finally, an other command (called makeallclean, refering to the Perl script makeallclean.pl) is also available for removing all previous compiled files, which could be usefull, for instance, when recompiling for a new version of the Fortran compiler.

Important notes

For the installation procedure with Perl, a series of makefiles are used by the compilation scripts. These makefiles are stored with the Fortran source code, within the "sources" sub-directory of each module.

  • The files named "makefile" are meant for the Linux operating systems.
  • The files named "makefile.wnt" and "makefile.gfo" are meant for the MS Windows operating, for the Intel and GNU Fortran compilers respectively. In the later case, it is important to select the appropriate compiler avaliable on your MS Windows operating system by editing the "maktel.bat" batch file found under the bin directory (at the ~root).
  • For the compilation of the TELEMAC system for parallel use, the "makefile" also references:

    • a path to the "include" subdirectory of your MPI installation. The makefile in ~root/parallel/parallel_v6p2/sources/ should therefore be edited to refere to the correct location, defined by the key DIRINC_MPI. It is set by default to $(PROJECT)\..\mpi\include, where $(PROJECT) is the absolute path to the ~root.
    • a reference to the file and path of the METIS library. Again the same makefile should be edited to refer to the correct file, defined by the key LKLIB. It is set by default to $(PROJECT)/parallel/parallel_$(VERSION)/$(DIRLIB)/libmetis.a

It be should noted that the installation procedure with Python does not require makefile. The above modifications are therefore not necessary.

The step by step approach - compiling the TELEMAC system manually

This approach is a little more compilcated as implies knowledge of the order by which the interdependent modules must be compiled. For this reason, we recommend that use the global approach or that you post questions on the forum or write to This email address is being protected from spambots. You need JavaScript enabled to view it. or to the appropriate contact of the list on this website.

 

Running TELEMAC from the command line

You are ready for running a simulation, starting with some of the example provided in the validation dossier. You can either launch a TELEMAC module from the graphical user interface FUDAA or run it by typing the following in a terminal or DOS console:

$>,\>    telemac2d   SteerringFile.cas

The above shows telemac2d runing a simulation defined by its steering file SteeringFile.cas. The listing on screen follows with details of the execution.

Using the -h option will display the other available options. More details on this command and on the keywords of the steering file can be found in the user manuals

 

end faq

The open TELEMAC-MASCARET template for Joomla!2.5, the HTML 4 version.