Difference between revisions of "Install the TELEMAC system"

From SourceWiki
Jump to navigation Jump to search
 
(108 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
It is possible to install the TELEMAC system in one go with subversion by checking out the meta project <tt>systel90-meta</tt>. This will pull from the server the full dependencies for ESTEL-3D and ESTEL-2D.
+
[[Category:Estel]]
−
= Checking out the TELEMAC system =
 
  
 +
This article describes how to download, configure and compile a full installation of the TELEMAC system to be used with '''ESTEL-2D''' and '''ESTEL-3D'''.
 +
 +
= Downloading the TELEMAC system =
 +
 +
To download the code, it is recommended to use "[[ Introduction to Subversion | subversion]]" and the meta project <code>systel90-meta</code>. This will download from the server the most of the dependencies for '''ESTEL-3D''' and '''ESTEL-2D'''. This assumes (a) that you have a subversion client on your machine and (b) that you have access rights to the relevant modules of the TELEMAC system under subversion. If not, please contact [[User:Jprenaud|JP Renaud]] who might be able to help.
 +
 +
From now on, we assume that the user wants to install the TELEMAC system into the <code>systel90</code> folder located at <code>/path/to/systel90/</code>. Starting from the directory <code>/path/to</code>, the subversion command to use is:
 
<code><pre>
 
<code><pre>
−
svn checkout http://source.ggy.bris.ac.uk/subversion/systel90-meta systel90
+
$ svn checkout http://source.ggy.bris.ac.uk/subversion/systel90-meta/trunk systel90
 
</pre></code>
 
</pre></code>
 +
 +
This will create a systel90 folder containing all necessary source files for the TELEMAC system. The typical folder tree obtained after downloading is shown at the [[Install_the_TELEMAC_system_with_subversion#Final_TELEMAC_tree | bottom of this page]].
  
 
= Configuration =
 
= Configuration =
−
Config is just a template.
+
Before being able to compile the TELEMAC system, a few configuration steps are necessary.
−
== Path ==
+
== Paths ==
 +
The executable files for the TELEMAC system are located in the <code>bin/</code> directory of the <code>systel90</code>tree. The directory needs to be added to the <code>PATH</code> variable of the user. Moreover, the TELEMAC launching scripts require the current directory (<code>./</code>) to be in the <code>PATH</code> as well. A typical entry in a user login file (for instance [[ Typical .bashrc for ESTEL| <code>.bashrc</code>]]) would be:
 +
 
 +
<code><pre>
 +
PATH=./:/path/to/systel90/bin:$PATH
 +
export PATH
 +
</pre></code>
 +
 
 
== systel.ini ==
 
== systel.ini ==
−
== Multiple configuration ==
+
The folder <code>config-template/</code> contains an example configuration file. By default, the TELEMAC system looks for configuration files in the <code>config/</code> directory of the <code>systel90</code> tree. To get started, one can simply copy <code>config-template/</code> to <code>configv5p9/</code>. The "v5p9" suffix is used as this article uses examples for version v5p9 of the TELEMAC system.
−
SYSTELCFG=
+
 
 +
<code><pre>
 +
$ cp -r config-template configv5p9
 +
$ rm -rf configv5p9/.svn
 +
</pre></code>
 +
 
 +
Note that deleting the <code>.svn</code> folder in <code>configv5p9/</code> is optional but will make sure that you configuration changes cannot be overwritten by subversion when updating the TELEMAC system.
 +
 
 +
It is possible to have several configuration folders, all of them tailored for a particular version of the TELEMAC system. This is described in the article entitled "[[How to swap between versions of the TELEMAC system]]". Start with one configuration folder first though.
 +
 
 +
Then, the file <code>systel.ini</code> in <code>/path/to/systel90/configv5p9</code> needs editing. This files contains a number of sections.
 +
 
 +
=== The [GENERAL] section===
 +
The '''[GENERAL]''' section starts with the default language and version number for each modules in the TELEMAC system. This consists of a long list of <code>LNGcode</code> (use for the default language) and <code>VERScode</code> (used for the version) lines. By default, this file is setup for the English language (value2, French is value 1) and version "v5p9". For instance, for ESTEL-3D, the entries are:
 +
 
 +
<code><pre>
 +
#---ESTEL3D
 +
LNGESTEL3=2
 +
VERSESTEL3=v5p9
 +
</pre></code>
 +
 
 +
This section finish with the location of the <code>systel90</code> tree (variable <code>PROJECT</code>)and the type of machine (variable <code>HOSTTYPE</code>).
 +
 
 +
If the <code>systel90</code> tree is installed in <code>/path/to/systel90</code>, then the <code>PROJECT</code> variable should be set <code>/path/to/systel90</code>.
 +
 
 +
There is no predefined value to enter for the <code>HOSTTYPE</code> variable, the user is free to set the <code>HOSTTYPE</code> freely but it is usual to use a string which can be used to identify a combination of the type computer, the operating system and the Fortran compiler. For instance, if the machine is a 32-bit Linux machine (x86 type) using the Portland Group compiler, one could use "linux-x86-pgf90". For a 64-bit machine (x86_64 type) using the Intel Fortran compiler, one could use "linux-x86_64-ifort", this is the string used in the example <code>systel.ini</code> but is merely an example.
 +
 
 +
<code><pre>
 +
PROJECT=/path/to/systel90
 +
HOSTTYPE=linux-x86_64-ifort
 +
</pre></code>
 +
 
 +
These values are used at a later stage to recognise which compiler option and which pre-compiled versions of the libraries to use at runtime, see [[Install_the_TELEMAC_system_with_subversion#The_hosttype_configurations | below]].
 +
 
 +
===The [PERL] section===
 +
The '''[PERL]''' section is used to give the location of the perl executable (<code>PERLPATH</code>) and the location of the perl library (<code>PERL5LIB</code>). On a typical Linux system, these two locations can be easily found by looking into the file system:
 +
<code><pre>
 +
$ which perl
 +
/usr/bin/perl
 +
 
 +
$ ls /usr/lib/perl*
 +
5.8.5  5.8.6  5.8.7  5.8.8
 +
</pre></code>
 +
 
 +
Note that Linux systems sometimes include several versions of the perl library, the highest number of the perl '''5''' library is appropriate. Therefore, on this particular system, the '''[PERL]''' section would be:
 +
 
 +
<code><pre>
 +
[PERL]
 +
PERLPATH=/usr/bin
 +
PERL5LIB=/usr/lib/perl5/5.8.8
 +
</pre></code>
 +
 
 +
===The hosttype configurations===
 +
The final section of the <code>systel.ini</code> file is a list of configuration options for a given <code>HOSTTYPE</code>. There can be several lists, they are identified by an entry inside square brackets. One of these entries must match the <code>HOSTTYPE</code> variable defined in the '''[GENERAL]''' section of the file. This is a convenient way of changing configuration options by editing one single line in the <code>systel.ini</code> file.
 +
 
 +
A list of configuration options consists of series of a set of keywords related to the compiler, the linker, the archiver (and the MPI library if installed). For instance when using the Intel Fortran compiler of a 64-bit Linux machine, one could have:
 +
 
 +
<code><pre>
 +
[linux-x86_64-ifort]
 +
DIRLIB=linux-x86_64-ifort
 +
FC_NAM="ifort"
 +
FC_OPT_OBJEXT= "o"
 +
FC_OPT_COMPIL= " -O3 -c "
 +
FC_OPT_DEBUG=  " -g -DD -debug extended -debug-parameters "
 +
FC_OPT_PROFILE=" -O3 "
 +
FC_OPT_INCLUDE=" -I "
 +
FC_OPT_OTHERS= " -warn all -implicitnone -traceback "
 +
 
 +
LK_NAM="ifort"
 +
LK_OPT_NORMAL=" -lm -lstdc++ "
 +
LK_OPT_DEBUG=  " -g -DD -debug extended -debug-parameters "
 +
LK_OPT_PROFILE=" -pg "
 +
LK_OPT_OUTNAME=" -o "
 +
LK_OPT_OTHERS="  "
 +
 
 +
LIB_NAM=ar
 +
LIB_OPT_LIBEXT="a"
 +
LIB_OPT_OUTNAME=" cru"
 +
LIB_OPT_OTHERS=
 +
LIB_RANLIB=
 +
LIBS_MPI=" "
 +
 
 +
RUN_DEBUG=" idb -gui "
 +
RUN_PROFILE=
 +
 
 +
FC_MPI="mpif90 -c "
 +
LK_MPI="mpif90 -lm -lstdc++ -o <EXE>  <OBJS>  <LIBS> "
 +
LIBS_MPI="-L/path/to/mpi/lib "
 +
RUN_MPI="mpirun -machinefile mpirun.txt -np <N> <EXE>"
 +
</pre></code>
 +
 
 +
'''Give more detail!'''
 +
 
 +
Refer to the documentation about the compiler to understand these options.
 +
 
 +
The section with the variables ending in "_MPI" is required when the TELEMAC system will be run in parallel on a cluster or network of computers. This is described [[Install_the_TELEMAC_system#parallel | below]].
 +
 
 +
==cfgmak.mak==
 +
When the configuration of <code>systel.ini</code> is done, one must create a configuration file for the compilation. This is done automatically when issuing the command:
 +
<code><pre>$ cfgmak
 +
File '/path/to/systel90/configv5p7/cfgmak.mak' updated.
 +
</pre></code>
 +
 
 +
This will create a file called <code>cfgmak.mak</code> in the same directory as <code>systel.ini</code>. <code>cfgmak.mak</code> should '''not''' be edited manually, any configuration change should be done in <code>systel.ini</code> and the command <code>cfgmak</code> will update <code>cfgmak.mak</code> accordingly.
  
 
= Compilation =
 
= Compilation =
 +
After the <code>cfgmak.mak</code> file has been created, it is possible to start to compile the TELEMAC system. This is a simple but long operation unless a [[ ESTEL:Compilation script for the TELEMAC system | compilation script]] is used to automate the process, and even so, the manual steps for parallel and estel3d are still required. The modules in the TELEMAC system need to be compiled, in a particular order. Furthermore, some modules (parallel and estel3d have external dependencies which need to be dealt with before the compilation.
 +
 +
== The maktel command ==
 +
The standard way to compile a module of the TELEMAC system consist of going into the <code>sources/</code> directory of the module and using the command:
 +
<code><pre>
 +
maktel Menage install
 +
</pre></code>
 +
 +
This will delete all existing objects in the <code>sources/</code> directory, recompile the module and install the module library in a folder called after the <code>DIRLIB</code> entry in the <code>systel.ini</code> file. For instance using the linux-x86_64-ifort example the library for estel3d v5p7 would go in <code>/path/to/systel90/estel3d/estel3d_v5p7/linux-x86_64-ifort/</code>.
 +
 +
If only some source files are updated, <code>maktel all</code> will recompile the source files and <code>maktel install</code> will install the library into its destination.
 +
 +
== Compilation order ==
 +
The modules need to be compiled in the following order:
 +
# damocles
 +
# paravoid
 +
# '''parallel''' (optional, requires extra operations)
 +
# bief
 +
# special
 +
# sisyphe
 +
# telemac2d
 +
# estel2d
 +
# '''estel3d''' (attention, requires extra operations)
 +
 +
For each module, navigate into the <code>sources/</code> directory of the version of the module defined in the <code>systel.ini</code> file and issue the command:
 +
<code><pre>
 +
$ maktel Menage install
 +
</pre></code>
 +
 +
Note that '''parallel''' and '''estel3d''' require some extra steps, see below.
 +
 +
== parallel ==
 +
parallel is an '''optional''' library. The TELEMAC system can be compiled and used without it. The parallel module is used to run the TELEMAC system on a parallel computer or network of computers. It requires the "metis" and "MPI" libraries to be installed.
 +
 +
=== metis===
 +
metis is a mesh partitionning library. Although not developed as part of the TELEMAC project, it is distributed with parallel for convenience. The compilation of metis is simple on Linux but requires some manual steps. It requires a C compiler to be installed. In particular, the destination library needs to be created by hand:
 +
 +
<code><pre>
 +
$ cd /path/to/systel90/parallel/parallel_v5p7
 +
$ cd metis_distrib
 +
$ cd metis-4.0
 +
$ make realclean
 +
$ make
 +
$ cd /path/to/systel90/parallel/parallel_v5p7
 +
$ mkdir linux-x86_64-ifort
 +
$ cp metis_distrib/metis-4.0/libmetis.a linux-x86_64-ifort/.
 +
</pre></code>
 +
 +
=== MPI ===
 +
 +
The "MPI" message parsing interface is also required to compile parallel and use the TELEMAC system in parallel. Some instructions exist on this wiki on how to [[ Install and configure MPI | install and configure MPI ]] for a network of machines.
 +
 +
From now on, we assume that MPI is installed in the directory <code>/path/to/mpi</code> which contains the <code>bin/</code>, <code>lib/</code> and <code>include/</code> directories. Furthermore, the MPI Fortran 90 compiler <code>mpif90</code> needs to be in the user's <code>PATH</code>; which often requires the following entry in the user's <code>.bashrc</code> file:
 +
 +
<code><pre>
 +
PATH=/path/to/mpi/bin:$PATH
 +
export PATH
 +
</pre></code>
 +
 +
When MPI is installed and configured, the <code>systel.ini</code> can be adjusted if necessary. It contains 4 lines related to the MPI configuration at the end of each [[Install_the_TELEMAC_system#The_hosttype_configurations | hosttype section]]. Usually, only the <code>LIBS_MPI</code> variable needs adjusting:
 +
<code><pre>
 +
FC_MPI="mpif90 -c "
 +
LK_MPI="mpif90 -lm -lstdc++ -o <EXE>  <OBJS>  <LIBS> "
 +
LIBS_MPI="-L/path/to/mpi/lib "
 +
RUN_MPI="mpirun -machinefile mpirun.txt -np <N> <EXE>"
 +
</pre></code>
 +
 +
Sometimes, it is advantageous to create a symbolic link from <code>/path/to/mpi</code> to <code>/path/to/systel90/mpi/linux-x86_64-ifort</code>:
 +
<code><pre>
 +
$ mkdir /path/to/systel90/mpi
 +
$ ln -s /path/to/mpi/ /path/to/systel90/mpi/linux-x86_64-ifort
 +
</pre></code>
 +
 +
This way, the <code>LIBS_MPI</code> variable in <code>systel.ini</code> can stay constant, even if MPI changes location; you merely need to re-create the symbolic link. In that case, you would have:
 +
 +
<code><pre>
 +
FC_MPI="mpif90 -c "
 +
LK_MPI="mpif90 -lm -lstdc++ -o <EXE>  <OBJS>  <LIBS> "
 +
LIBS_MPI="-L/path/to/systel90/mpi/linux-x86_64-ifort/lib "
 +
RUN_MPI="mpirun -machinefile mpirun.txt -np <N> <EXE>"
 +
</pre></code>
 +
 +
You will also need to run the <code>cfgmak</code> command again to regenerate <code>cfgmak.mak</code> file.
 +
 +
=== Compilation ===
 +
Before being able to compile parallel, the makefile in the <code>sources/</code> directory might need to be edited to point to the relevant MPI <code>include/</code> folder:
 +
<code><pre>
 +
INCMPI        = /path/to/mpi/include
 +
</pre></code>
 +
 +
It is said that this line ''might need editing'' as on some systems, it is apparently not required.
 +
 +
Furthermore, if you used the symbolic link trick described above for the location of the MPI directory, the ''default'' INCMPI line in the makefile of parallel is correct:
 +
 +
<code><pre>
 +
INCMPI        = $(PROJECT)/mpi/$(DIRLIB)/include
 +
</pre></code>
 +
 +
It will effectively point to <code>/path/to/systel90/mpi/linux-x86_64-ifort/include</code>.
 +
 +
Then, parallel can be compiled as any other module with the commands:
 +
 +
<code><pre>
 +
$ maktel Menage install
 +
</pre></code>
 +
 +
== estel3d ==
 +
It is recommended to activate the Tecplot binary output for '''ESTEL-3D''' to increase performance and reduce results file size. A few manual steps are required for this purpose.
 +
 +
'''If you don't have access to tecplot, go directly to the [[ Install_the_TELEMAC_system#Modify_the_makefile | makefile section]].'''
 +
 +
=== Install the Tecplot library ===
 +
Your installation of Tecplot provides the Tecplot TecIO library called <code>tecio.a</code> (32-bit machines) or <code>tecio64.a</code> (64-bit machines) and located in the <code>lib</code> directory of the Tecplot install. These libraries are also provided by the manufacturer of Tecplot, Tecplot Inc., at http://www.tecplottalk.com/tecio/.
 +
More information is provided for the developers of ESTEL [[ESTEL:Configure_Tecplot_for_ESTEL-3D | here]].
 +
 +
It is necessary to copy the library file into the <code>systel90</code> tree. To do this, a tecplot tree under the <code>systel90/</code> directory needs to be created. This new tree needs to be organised in a similar way to that of all TELEMAC modules, the only difference being the version numbers: instead of "v5p7" or "v5p8", Tecplot requires version "10" (for Tecplot 10r6) or "110" (for Tecplot 360, 360r1 and 360r2). For instance to create the tree for Tecplot 10, one would do:
 +
 +
<code><pre>
 +
$ mkdir -p /path/to/systel90/tecplot/tecplot_10/linux-x86_64-ifort
 +
</pre></code>
 +
 +
When directory has been created, the Tecplot library file has to be copied into it and renamed to <code>tecplotversion</code> where "version" is "10" or "110". For Tecplot 10:
 +
<code><pre>
 +
$ cp /path/to/tecplot/lib/tecio64.a /path/to/systel90/tecplot/tecplot_10/linux-x86_64-ifort/tecplot10.a
 +
</pre></code>
 +
 +
=== Modify the makefile ===
 +
 +
The <code>FORMAT_OUT</code> line in the makefile of '''ESTEL-3D''' needs to be adjusted according to the version of Tecplot installed on the system:
 +
* Tecplot 10: <code>FORMAT_OUT = 10 </code>
 +
* Tecplot 11 (360): <code>FORMAT_OUT = 110</code>
 +
* No Tecplot library: <code>FORMAT_OUT = ONLY_ASCII</code>
 +
 +
=== Compile estel3d ===
 +
To compile '''ESTEL-3D''', simply issue the command:
 +
<code><pre>
 +
$ maktel cleanall install
 +
</pre></code>
  
 
= Final TELEMAC tree =
 
= Final TELEMAC tree =
 +
This is the TELEMAC tree as it looks after the first subversion checkout. Note that the example below is illustrative only and is meant to show the latest development version (here v5p8) and the latest stable version (here v5p7). Obviously, this will vary through time.
 
* systel90
 
* systel90
 
** bief
 
** bief
 
*** bief_v5p7
 
*** bief_v5p7
 +
**** sources
 
*** bief_v5p8
 
*** bief_v5p8
 +
**** sources
 
** bin
 
** bin
 
** config-template
 
** config-template
 
** damocles
 
** damocles
 
*** damo_v5p7
 
*** damo_v5p7
 +
**** sources
 
*** damo_v5p8
 
*** damo_v5p8
 +
**** sources
 
** estel2d
 
** estel2d
 
*** estel2d_v5p7
 
*** estel2d_v5p7
 +
**** lib
 +
**** sources
 +
**** test.gb
 
*** estel2d_v5p8
 
*** estel2d_v5p8
 +
**** lib
 +
**** sources
 +
**** test.gb
 
** estel3d
 
** estel3d
 
*** estel2d_v5p7
 
*** estel2d_v5p7
 +
**** sources
 +
**** test.gb
 
*** estel2d_v5p8
 
*** estel2d_v5p8
 +
**** sources
 +
**** test.gb
 
** parallel
 
** parallel
 +
*** parallel_v5p7
 +
**** metis_distrib
 +
**** sources
 +
*** parallel_v5p8
 +
**** metis_distrib
 +
**** sources
 
** paravoid
 
** paravoid
 +
*** paravoid_v5p7
 +
**** sources
 +
*** paravoid_v5p8
 +
**** sources
 
** special
 
** special
 +
*** special_v5p7
 +
**** sources
 +
*** special_v5p8
 +
**** sources
 
** sisyphe
 
** sisyphe
 +
*** sisyphe_v5p7
 +
**** lib
 +
**** sources
 +
**** sources_util
 +
*** sisyphe_v5p8
 +
**** lib
 +
**** sources
 +
**** sources_util
 
** telemac2d
 
** telemac2d
 +
*** tel2d_v5p7
 +
**** lib
 +
**** sources
 +
*** tel2d_v5p8
 +
**** lib
 +
**** sources

Latest revision as of 17:52, 13 February 2008


This article describes how to download, configure and compile a full installation of the TELEMAC system to be used with ESTEL-2D and ESTEL-3D.

Downloading the TELEMAC system

To download the code, it is recommended to use " subversion" and the meta project systel90-meta. This will download from the server the most of the dependencies for ESTEL-3D and ESTEL-2D. This assumes (a) that you have a subversion client on your machine and (b) that you have access rights to the relevant modules of the TELEMAC system under subversion. If not, please contact JP Renaud who might be able to help.

From now on, we assume that the user wants to install the TELEMAC system into the systel90 folder located at /path/to/systel90/. Starting from the directory /path/to, the subversion command to use is: 

$ svn checkout http://source.ggy.bris.ac.uk/subversion/systel90-meta/trunk systel90

This will create a systel90 folder containing all necessary source files for the TELEMAC system. The typical folder tree obtained after downloading is shown at the bottom of this page.

Configuration

Before being able to compile the TELEMAC system, a few configuration steps are necessary.

Paths

The executable files for the TELEMAC system are located in the bin/ directory of the systel90tree. The directory needs to be added to the PATH variable of the user. Moreover, the TELEMAC launching scripts require the current directory (./) to be in the PATH as well. A typical entry in a user login file (for instance .bashrc) would be: 

PATH=./:/path/to/systel90/bin:$PATH
export PATH

systel.ini

The folder config-template/ contains an example configuration file. By default, the TELEMAC system looks for configuration files in the config/ directory of the systel90 tree. To get started, one can simply copy config-template/ to configv5p9/. The "v5p9" suffix is used as this article uses examples for version v5p9 of the TELEMAC system. 

$ cp -r config-template configv5p9
$ rm -rf configv5p9/.svn

Note that deleting the .svn folder in configv5p9/ is optional but will make sure that you configuration changes cannot be overwritten by subversion when updating the TELEMAC system.

It is possible to have several configuration folders, all of them tailored for a particular version of the TELEMAC system. This is described in the article entitled "How to swap between versions of the TELEMAC system". Start with one configuration folder first though.

Then, the file systel.ini in /path/to/systel90/configv5p9 needs editing. This files contains a number of sections.

The [GENERAL] section

The [GENERAL] section starts with the default language and version number for each modules in the TELEMAC system. This consists of a long list of LNGcode (use for the default language) and VERScode (used for the version) lines. By default, this file is setup for the English language (value2, French is value 1) and version "v5p9". For instance, for ESTEL-3D, the entries are: 

#---ESTEL3D
LNGESTEL3=2
VERSESTEL3=v5p9

This section finish with the location of the systel90 tree (variable PROJECT)and the type of machine (variable HOSTTYPE).

If the systel90 tree is installed in /path/to/systel90, then the PROJECT variable should be set /path/to/systel90.

There is no predefined value to enter for the HOSTTYPE variable, the user is free to set the HOSTTYPE freely but it is usual to use a string which can be used to identify a combination of the type computer, the operating system and the Fortran compiler. For instance, if the machine is a 32-bit Linux machine (x86 type) using the Portland Group compiler, one could use "linux-x86-pgf90". For a 64-bit machine (x86_64 type) using the Intel Fortran compiler, one could use "linux-x86_64-ifort", this is the string used in the example systel.ini but is merely an example. 

PROJECT=/path/to/systel90
HOSTTYPE=linux-x86_64-ifort

These values are used at a later stage to recognise which compiler option and which pre-compiled versions of the libraries to use at runtime, see below.

The [PERL] section

The [PERL] section is used to give the location of the perl executable (PERLPATH) and the location of the perl library (PERL5LIB). On a typical Linux system, these two locations can be easily found by looking into the file system: 

$ which perl
/usr/bin/perl

$ ls /usr/lib/perl*
5.8.5  5.8.6  5.8.7  5.8.8

Note that Linux systems sometimes include several versions of the perl library, the highest number of the perl 5 library is appropriate. Therefore, on this particular system, the [PERL] section would be: 

[PERL]
PERLPATH=/usr/bin
PERL5LIB=/usr/lib/perl5/5.8.8

The hosttype configurations

The final section of the systel.ini file is a list of configuration options for a given HOSTTYPE. There can be several lists, they are identified by an entry inside square brackets. One of these entries must match the HOSTTYPE variable defined in the [GENERAL] section of the file. This is a convenient way of changing configuration options by editing one single line in the systel.ini file.

A list of configuration options consists of series of a set of keywords related to the compiler, the linker, the archiver (and the MPI library if installed). For instance when using the Intel Fortran compiler of a 64-bit Linux machine, one could have: 

[linux-x86_64-ifort]
DIRLIB=linux-x86_64-ifort
FC_NAM="ifort"
FC_OPT_OBJEXT= "o"
FC_OPT_COMPIL= " -O3 -c "
FC_OPT_DEBUG=  " -g -DD -debug extended -debug-parameters "
FC_OPT_PROFILE=" -O3 "
FC_OPT_INCLUDE=" -I "
FC_OPT_OTHERS= " -warn all -implicitnone -traceback "

LK_NAM="ifort"
LK_OPT_NORMAL=" -lm -lstdc++ "
LK_OPT_DEBUG=  " -g -DD -debug extended -debug-parameters "
LK_OPT_PROFILE=" -pg "
LK_OPT_OUTNAME=" -o "
LK_OPT_OTHERS="  "

LIB_NAM=ar
LIB_OPT_LIBEXT="a"
LIB_OPT_OUTNAME=" cru"
LIB_OPT_OTHERS=
LIB_RANLIB=
LIBS_MPI=" "

RUN_DEBUG=" idb -gui "
RUN_PROFILE=

FC_MPI="mpif90 -c "
LK_MPI="mpif90 -lm -lstdc++ -o <EXE>  <OBJS>  <LIBS> "
LIBS_MPI="-L/path/to/mpi/lib "
RUN_MPI="mpirun -machinefile mpirun.txt -np <N> <EXE>"

Give more detail!

Refer to the documentation about the compiler to understand these options.

The section with the variables ending in "_MPI" is required when the TELEMAC system will be run in parallel on a cluster or network of computers. This is described below.

cfgmak.mak

When the configuration of systel.ini is done, one must create a configuration file for the compilation. This is done automatically when issuing the command: 

$ cfgmak
File '/path/to/systel90/configv5p7/cfgmak.mak' updated.

This will create a file called cfgmak.mak in the same directory as systel.ini. cfgmak.mak should not be edited manually, any configuration change should be done in systel.ini and the command cfgmak will update cfgmak.mak accordingly.

Compilation

After the cfgmak.mak file has been created, it is possible to start to compile the TELEMAC system. This is a simple but long operation unless a compilation script is used to automate the process, and even so, the manual steps for parallel and estel3d are still required. The modules in the TELEMAC system need to be compiled, in a particular order. Furthermore, some modules (parallel and estel3d have external dependencies which need to be dealt with before the compilation.

The maktel command

The standard way to compile a module of the TELEMAC system consist of going into the sources/ directory of the module and using the command: 

maktel Menage install

This will delete all existing objects in the sources/ directory, recompile the module and install the module library in a folder called after the DIRLIB entry in the systel.ini file. For instance using the linux-x86_64-ifort example the library for estel3d v5p7 would go in /path/to/systel90/estel3d/estel3d_v5p7/linux-x86_64-ifort/.

If only some source files are updated, maktel all will recompile the source files and maktel install will install the library into its destination.

Compilation order

The modules need to be compiled in the following order:

  1. damocles
  2. paravoid
  3. parallel (optional, requires extra operations)
  4. bief
  5. special
  6. sisyphe
  7. telemac2d
  8. estel2d
  9. estel3d (attention, requires extra operations)

For each module, navigate into the sources/ directory of the version of the module defined in the systel.ini file and issue the command: 

$ maktel Menage install

Note that parallel and estel3d require some extra steps, see below.

parallel

parallel is an optional library. The TELEMAC system can be compiled and used without it. The parallel module is used to run the TELEMAC system on a parallel computer or network of computers. It requires the "metis" and "MPI" libraries to be installed.

metis

metis is a mesh partitionning library. Although not developed as part of the TELEMAC project, it is distributed with parallel for convenience. The compilation of metis is simple on Linux but requires some manual steps. It requires a C compiler to be installed. In particular, the destination library needs to be created by hand: 

$ cd /path/to/systel90/parallel/parallel_v5p7
$ cd metis_distrib
$ cd metis-4.0
$ make realclean
$ make
$ cd /path/to/systel90/parallel/parallel_v5p7
$ mkdir linux-x86_64-ifort
$ cp metis_distrib/metis-4.0/libmetis.a linux-x86_64-ifort/.

MPI

The "MPI" message parsing interface is also required to compile parallel and use the TELEMAC system in parallel. Some instructions exist on this wiki on how to install and configure MPI for a network of machines.

From now on, we assume that MPI is installed in the directory /path/to/mpi which contains the bin/, lib/ and include/ directories. Furthermore, the MPI Fortran 90 compiler mpif90 needs to be in the user's PATH; which often requires the following entry in the user's .bashrc file: 

PATH=/path/to/mpi/bin:$PATH
export PATH

When MPI is installed and configured, the systel.ini can be adjusted if necessary. It contains 4 lines related to the MPI configuration at the end of each hosttype section. Usually, only the LIBS_MPI variable needs adjusting: 

FC_MPI="mpif90 -c "
LK_MPI="mpif90 -lm -lstdc++ -o <EXE>  <OBJS>  <LIBS> "
LIBS_MPI="-L/path/to/mpi/lib "
RUN_MPI="mpirun -machinefile mpirun.txt -np <N> <EXE>"

Sometimes, it is advantageous to create a symbolic link from /path/to/mpi to /path/to/systel90/mpi/linux-x86_64-ifort: 

$ mkdir /path/to/systel90/mpi
$ ln -s /path/to/mpi/ /path/to/systel90/mpi/linux-x86_64-ifort

This way, the LIBS_MPI variable in systel.ini can stay constant, even if MPI changes location; you merely need to re-create the symbolic link. In that case, you would have: 

FC_MPI="mpif90 -c "
LK_MPI="mpif90 -lm -lstdc++ -o <EXE>  <OBJS>  <LIBS> "
LIBS_MPI="-L/path/to/systel90/mpi/linux-x86_64-ifort/lib "
RUN_MPI="mpirun -machinefile mpirun.txt -np <N> <EXE>"

You will also need to run the cfgmak command again to regenerate cfgmak.mak file.

Compilation

Before being able to compile parallel, the makefile in the sources/ directory might need to be edited to point to the relevant MPI include/ folder: 

INCMPI        = /path/to/mpi/include

It is said that this line might need editing as on some systems, it is apparently not required.

Furthermore, if you used the symbolic link trick described above for the location of the MPI directory, the default INCMPI line in the makefile of parallel is correct: 

INCMPI        = $(PROJECT)/mpi/$(DIRLIB)/include

It will effectively point to /path/to/systel90/mpi/linux-x86_64-ifort/include.

Then, parallel can be compiled as any other module with the commands: 

$ maktel Menage install

estel3d

It is recommended to activate the Tecplot binary output for ESTEL-3D to increase performance and reduce results file size. A few manual steps are required for this purpose.

If you don't have access to tecplot, go directly to the makefile section.

Install the Tecplot library

Your installation of Tecplot provides the Tecplot TecIO library called tecio.a (32-bit machines) or tecio64.a (64-bit machines) and located in the lib directory of the Tecplot install. These libraries are also provided by the manufacturer of Tecplot, Tecplot Inc., at http://www.tecplottalk.com/tecio/. More information is provided for the developers of ESTEL here.

It is necessary to copy the library file into the systel90 tree. To do this, a tecplot tree under the systel90/ directory needs to be created. This new tree needs to be organised in a similar way to that of all TELEMAC modules, the only difference being the version numbers: instead of "v5p7" or "v5p8", Tecplot requires version "10" (for Tecplot 10r6) or "110" (for Tecplot 360, 360r1 and 360r2). For instance to create the tree for Tecplot 10, one would do: 

$ mkdir -p /path/to/systel90/tecplot/tecplot_10/linux-x86_64-ifort

When directory has been created, the Tecplot library file has to be copied into it and renamed to tecplotversion where "version" is "10" or "110". For Tecplot 10: 

$ cp /path/to/tecplot/lib/tecio64.a /path/to/systel90/tecplot/tecplot_10/linux-x86_64-ifort/tecplot10.a

Modify the makefile

The FORMAT_OUT line in the makefile of ESTEL-3D needs to be adjusted according to the version of Tecplot installed on the system:

  • Tecplot 10: FORMAT_OUT = 10
  • Tecplot 11 (360): FORMAT_OUT = 110
  • No Tecplot library: FORMAT_OUT = ONLY_ASCII

Compile estel3d

To compile ESTEL-3D, simply issue the command: 

$ maktel cleanall install

Final TELEMAC tree

This is the TELEMAC tree as it looks after the first subversion checkout. Note that the example below is illustrative only and is meant to show the latest development version (here v5p8) and the latest stable version (here v5p7). Obviously, this will vary through time.

  • systel90
    • bief
      • bief_v5p7
        • sources
      • bief_v5p8
        • sources
    • bin
    • config-template
    • damocles
      • damo_v5p7
        • sources
      • damo_v5p8
        • sources
    • estel2d
      • estel2d_v5p7
        • lib
        • sources
        • test.gb
      • estel2d_v5p8
        • lib
        • sources
        • test.gb
    • estel3d
      • estel2d_v5p7
        • sources
        • test.gb
      • estel2d_v5p8
        • sources
        • test.gb
    • parallel
      • parallel_v5p7
        • metis_distrib
        • sources
      • parallel_v5p8
        • metis_distrib
        • sources
    • paravoid
      • paravoid_v5p7
        • sources
      • paravoid_v5p8
        • sources
    • special
      • special_v5p7
        • sources
      • special_v5p8
        • sources
    • sisyphe
      • sisyphe_v5p7
        • lib
        • sources
        • sources_util
      • sisyphe_v5p8
        • lib
        • sources
        • sources_util
    • telemac2d
      • tel2d_v5p7
        • lib
        • sources
      • tel2d_v5p8
        • lib
        • sources
Retrieved from "https://source.geography.bristol.ac.uk/mediawiki/index.php?title=Install_the_TELEMAC_system&oldid=4722"