Installation procedure with Python

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 Python (standard Python 2.7).

 

Important note

Python was introduced with version v6p1 of the TELEMAC system, and has now become its preferred scripting language. Another article on this web site details the TELEMAC installation procedure with Perl. Nonetheless, if you are a new user of the TELEMAC system or if you know about the Python language already, it is recommended that you use this installation procedure as it is a little simpler than its Perl equivalent.

 

Prerequisites

Python

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

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, 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 to complete your installation procedure with Python (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 to complete your installation procedure with Python (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-5.1.0.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 to complete your installation procedure with Python (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 nor having to compile PARTEL.
    Again, you will have to update the TELEMAC configuration file to complete your installation procedure with Python (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). You should not have to modify your system 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.">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 'Compiled code', download the zipped file and extract its contents.
  2. A download through the SVN subversion system, with a more modern access to the source code and its various updates. The principal advantage of this method is that the sources code remains linked to the developers' main repository and that updates are just updates.
    In the download area of this website, you can choose the Sources: SVN menu, which explains 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 controlled source code management system such as SVN subversion already, it is recommended that you use the second downloading procedure as it much more practical on long term 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/v6p1 on Linux operating systems. This path will be referenced in the rest of this documentation as ~root.

 

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
 

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, a configuration file (commonly named the "systel.cfg" file) has to be modified depending on your operating system configuration.

$PATH

For the installation procedure with Python, the "pytel" directory for TELEMAC (at the ~root) should be added to 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/pytel:$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\v7p1\pytel
    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 one of the configuration files ~root/config/*.cfg present in the directory ~root/config/. 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/v7p1/config/systel.cis-ubuntu.cfg
    Please note that SYSTELCFG only supports one configuration file, altough one configuration file can include multiple configurations.

  • 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\v7p1\config\systel.cis-winxp.cfg
    Again, please note that SYSTELCFG only supports one configuration file, altough one configuration file can include multiple configurations.

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 name of the configuration can be set by the user and will be here referenced by "systel.cfg".

The file $SYSTELCFG/systel.cfg.

For the installation procedure with Python, the core of the TELEMAC configuration lies in the "systel.cfg" file (the name of the file can be defined by the user) situated at the address given by the environment variable $SYSTELCFG (see above). This file is directly interpreted by TELEMAC.

The file "systel.cfg" is made of one short section defining the list of configuration names of your computer followed by as many sections as you have configurations on your computer. Sections are separated by names in square brackets (i.e. [Configurations]) and where each section contains a number of pairs key = value, or key : value (i.e. configs : fedgfortrans fedgfopenmpi ubugfortrans ubugfopenmpi susgfortrans susgfopenmpi). The sections are as follows:

  1. [Configurations]: sets the list of names of every configurations available on your computer.

  2. [user-configuration-name]: referenced by the value of the key configs in the [Configurations] section, this section defines principally the options of your system, including the Fortran compiler, the available external libraries (such as MPI or OpenMPI), the root of your TELEMAC system, tits version number, etc.

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

1. [Configurations]

This section has only one keys

  • configs: Its value is a list of names of configurations defined by the user for a particular computer. The list is space-delimited. The names are arbitrary and chosen by the user but case-sensitive. A number of examples of configurations can be see in the many configurations files (*.cfg) available from the SVN repository in the ~root\config subdirectory.

For instance, on Windows operating systems:
configs : wintelscal wintelmpi wing95scal

For instance, on Ubuntu Linux operating systems:
configs : ubugfortrans ubugfopenmpi

For instance, on OpenSUSE Linux operating systems:
configs : susgfortrans susgfopenmpi

Again, the names in the lists above are arbitrary and could define configurations for a number of computers within an organisation. The systel-edf.cfg is such a configuration file, where most of the types of computers used at EDF-LNHE are represented.

2. [user-configuration-name]

This section has a larger number of keys necessary to configure your TELEMAC on your computer. Here [user-configurtaion-name] takes the value defined by the user, for instance [wing95scal]. That name is also used by TELEMAC to create a subdirectory within the tree structure of each module at the same level as the "source" to store the compiled object, libraries and executables created for that specific configuration. In order to help with this setup a number of pre-defined configurations have been stored in "systel-*.cfg". It is therefore recommended that you make a copy of one of these files, rename it "systel.cfg" and select the most appropriate configs' value for your own configurations.

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:

  • root: name of the directory where the TELEMAC system is, or ~root as defined above.
    For instance on MSWindows operating systems:
    root : c:\opentelemac\v7p1
    and on Linux operating systems:
    root : /home/user/opetelemac/v7p1

  • version: sets the version number for the TELEMAC system. For instance:
    version : v7p1

  • language: sets the language for the TELEMAC system (value 1 for French; value 2 for English) ... this key is not used yet.

  • modules: defines the name of the modules for which the compilation is carried out. The module names that are not recognised as part of the TELEMAC system are ignored. In v7p1, the modules availables are: telemac2d, telemac3d, sisyphe, artemis, tomowac, stbtel and postel3d. Three additonal names are however allowed:

    • system: which TELEMAC automatically replaces by the list of all available modules present on your computer
    • clean: which trigger the action (here compilation) to be carried out as if it was the first time
    • update: which trigger the action (here compilation) only to update the parts that are necessary.

    For instance, the compilation of the entire TELEMAC system, re-creating all existing objects, libraries and executables would simply write on MSWindows operating system:
    [wintel32s]
    root: c:\opentelemac\v7p1
    version: v7p1
    modules: clean system
    It is recommeneded that you just use the following by default:
    modules: update system
    Note that the order of appearance of the names of the module has no bearing on the compilation of the TELEMAC system. In addition, TELEMAC will sort out the dependencies between modules automatically, which means, for instance, that the following will compile TELEMAC-2D only:
    modules: update telemac2d

  • options: sets the switches between libraries, for instance parallel vs. paravoid, openmpi vs. mpi, mumps, XDMF, etc. For instance, when configuring for parallel use:
    options : parallel mpi

  • cmd_*: defines the commands and options of your Fortran compiler. There 3 of them: cmd_obj, cmd_lib, cmd_exe, respectively your compiler's directives to create objects, libraries and executables. These keys are commands, written in full as executed in a terminal windows. Within each command, a few tags are defined, such as <libname>, which are used by the compiler to replace by the appropriate value.

    For instance, for the Intel Fortran compiler:
    cmd_obj: ifort.exe /c /Ot /iface:cref /iface:nomixed_str_len_arg /nologo
    /names:uppercase /convert:big_endian /extend_source:132 <mods> <incs> <f95name>
    cmd_lib: xilib.exe /nologo /out: <libname> <objs>
    cmd_exe: xilink.exe /nologo /subsystem:console /stack:536870912 /out:<exename> <objs> <libs>
    (One should note the absence of space between /out: and <exename>)

    For instance, for the gfortran compiler on Linux operating systems:
    cmd_obj: gfortran -c -O3 -ffixed-line-length-132
    -fconvert=big-endian -frecord-marker=4 <mods> <incs> <f95name>
    cmd_lib: ar cru <libname> <objs>
    cmd_exe: gfortran -fconvert=big-endian -frecord-marker=4 -v -lm -lz -o <exename> <objs> <libs>
    (One should note the space between -o and <exename>)

  • For the compilation of (parts of) the TELEMAC system, the following keys are added to further fine tune the compiler directive, including linking to external libraries. These keys are built based on two words. The first 4 letters, are incs, libs, or mods and define how the compiler should link to include, library and module files. For instance, on Linux operating system, for the gfortran compiler and the MPICH2 implementation, assuming that libmetis is under /usr/lib while the XDMF library is one level up from the ~root directory of the TELEMAC system:
    mods_all: -M<config>
    libs_all: <root>
    \..\lib\XDMF\XdmfUtils.a /usr/lib/libfmpich.so
    incs_parallel: -I/usr/include/mpich2
    libs_parallel: /usr/lib/metis-5.1/libmetis.a
    While the '_all' are use commonly accross all modules, it is possible to also specify specific dependencies, such as 'libs_parallel', for which the libmetis only applies to the executables of the parallel module (partel in particular).
    At the compilation stage the key <root> is replaced by ~root of the TELEMAC system and <config> by the appropriate local directory created for a specific module and configuration (where the objects, libraries and executables are).

  • sfx_*: defines the suffixes of each type of files created through the compilation commands. There are 4 of them: sfx_lib, sfx_obj, sfx_mod, sfx_exe and sfx_zip. A library would have a '.lib' extension on windows while having a '.a' extension on Linux, for instance. The suffix can also be empty, which is appropriate for executables on Linux, for instance, as opposed to '.exe' on MSWindows operating system. Note that sfx_zip is used to define what type of ZIPPER will be called, depending on the platform. So .zip will launch a windows-like zip archive while .gztar will launch the stadard tarball and gzip tools, if installed.

  • Last but not least, some of the options defined with the key 'options' are completed with their own keys. These keys further inform how TELEMAC is launched. At this stage, only the 'mpi' option has such key, but a number of other keys will be defined in the future, for example, to put a simulation in a queue system on a cluster of computer.

    For instance on Linux operating systems with the MPICH2 implementation (where the command mpiexec completes the launch of the TELEMAC modules), the following two keys are added to the configuration:
    mpi_cmdexec: /usr/bin/mpiexec <wdir> <ncsize> <host> <exename>
    mpi_hosts: -localonly
    The field <wdir> is replaced by the absolute path of the temporary sub-directory where the simulation is launched from. The field <ncsize> is read from the keyword of your CAS file (PARALLEL PROCESSORS). The field <host> is taken from the key 'mpi_hosts' is there, or replaced by "-localonly" by default. The field <exename> is replaced by the name of the temporary executable created by TELEMAC within the temporary sub-directory.

 

Compiling the whole TELEMAC system

To complete the installation procedure with Python, there is only one more step: the compilation of the TELEMAC system based on your configuration.

Under either MS Windows or Linux operating systems this is achieved by typing the following in a terminal or DOS console:

$>,\> compileTELEMAC.py
(or also to the same effect on operating system that cannot recognise the '.py' extension:

$>,\> python compileTELEMAC.py

It should be noted that all the configuration named listed in the 'configs' key of the configuration will be compiled, one after the other, which allows the user to compile both the scalar and the parallel versions of the system, for as many Fortran compilers available in one command. The execution of the script 'compileTELEMAC.py' can be further taylored with a number of arguments taken from the execution command line. These are:

-c user-configuration-name
where 'user-configuration-name' should be one of the names listed in the 'configs' key. This allows the compilation of the TELEMAC system to be specific to only one configuration.

-f configuration-filewhere 'configuration-file' is the name (with its path). This option therefore replace the the use of the environmental variables SYSTELCFG.

Both the configuration file and the name of the configuration within defines the properties of the version of TELEMAC for your computer. Under MS Windows operating systems, the compilation of the entire TELEMAC system for parallel use can therefore also be achieved by typing the following in a terminal or DOS console:

$>,\> python compileTELEMAC.py -c wintelscal -f c:\opentelemac\v7p1\config\systel-hrw.cfg

Important notes

For the installation procedure with Python, there is no makefiles.

 

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::

$>,\> python runcode.py telemac2d -s cas-file
where cas-file is your steering file name.

A simple shell and batch script could replace the python runcode.py telemaced by just telemac2d

Just like the 'compileTELEMAC.py' script, the execution of the script 'runcode.py' can be further taylored with a number of arguments taken from the execution command line. These are:

-c user-configuration-name
where 'user-configuration-name' should be one of the names listed in the 'configs' key. This allows the compilation of the TELEMAC system to be specific to only one configuration.

-f configuration-file
where 'configuration-file' is the name (with its path). This option therefore replace the the use of the environmental variables SYSTELCFG.

-s is an option to write the screen listing into a sortie file.

-t is an option not to remove te temporary directory after the end of the simulation

-x is an option to compile the executable only, without launching the simulation.

Both the configuration file and the name of the configuration within defines the properties of the version of TELEMAC for your computer. Under MS Windows operating systems, the compilation of the entire TELEMAC system for parallel use can therefore also be achieved by typing the following in a terminal or DOS console:

$>,\> python compileTELEMAC.py -c wintelmpi -f c:\opentelemac\v7p1\config\systel-hrw.cfg

end faq

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