Project

General

Profile

Downloading, configuring and installing iSALE and its sub-projects

Note: Use of iSALE is currently restricted. If you do not have an iSALE account and would like to join our community, please post some short information about you and your plans to one of the main developers. Read carefully the terms of use first.

Setting up iSALE is fairly straightforward but please read each section carefully before starting to follow the instructions!

Pre-requisites

iSALE was developed primarily on a Linux and Mac OSX platform, using the GNU Fortran compiler, and a 64-bit x86-architecture. The current distribution only supports these platforms; you will need to modify certain subroutines and libraries to get iSALE working on other platforms.

The recommended platform for using iSALE is Ubuntu or Fedora.

Instructions for installing all the necessary iSALE pre-requisites for different operating systems

Under Linux, the gfortran compiler is the preferred option, but iSALE has been compiled successfully using the Intel (10.1) and Portland group compilers.

iSALE is distributed, updated and developed using SVN (Subversion ). SVN is a software package that manages version control of multi-developer software. Please ensure that you have this package installed before proceeding and that you have familiarised yourself with how to use SVN.

pySALEPlot, the visualisation software accompanying iSALE, uses the PYTHON language. This is not distributed with iSALE; for information about PYTHON, visit: https://www.python.org/. pySALEPlot can be installed using the instructions here.

The latest version of iSALE also requires several widely available additional packages to be installed prior to installing iSALE.
  1. Python, NumPy, SciPy and MatPlotLib
  2. qt (version 3)
    For Vimod on Ubuntu the package qt3-dev-tools is needed. This is NOT availiable in the Ubuntu repositories after 12.04. The package can be found at http://packages.ubuntu.com/de/precise/qt3-dev-tools

Installing iSALE-Dellen for scientific use

Note: iSALE is distributed, updated and developed using SVN. If you are unfamiliar with SVN, please see our iSALE using SVN page.

Those wishing to use iSALE as a simulation tool for science should download and use the latest stable release: iSALE-Dellen.

Downloading iSALE-Dellen

First, download a copy of the code using SVN
svn co svn://earth.naturkundemuseum-berlin.de/iSALE/tags/dellen ./iSALE-Dellen

This will create a directory named 'iSALE-Dellen' in your current directory. If a directory with this name already exists, you can
  1. remove or rename this directory (recommended), or
  2. use the following command to download iSALE to another folder:
    svn co svn://earth.naturkundemuseum-berlin.de/iSALE/tags/dellen <path/name-of-folder>
    

If your username on your local system is different to your username for the iSALE repository, you can specify your iSALE username when checking out using:

svn co  --username <user_name> svn://earth.naturkundemuseum-berlin.de/iSALE/tags/dellen <path/name-of-folder>

Replace <user_name> with the svn login name that you were assigned. At the prompt, enter your password.

Now svn should start to download iSALE-Dellen and notify you of all files and directories created. At the end you wil get a message that you "checked out revision X", where X is the revision number for iSALE-Dellen.

When the checkout has finished you should see a directory iSALE-Dellen in the directory you are in (unless you downloaded the code to a different location).

Change into this directory:

cd iSALE-Dellen

the directory you are now in is known as the iSALE-Dellen root directory. The contents of this directory is referred to as your local copy of the iSALE-Dellen repository.

Configuring iSALE-Dellen

The next step of the installation is to configure iSALE for your specific platform and compiler. If you have not already done so, change direcry into the iSALE root directory:

cd iSALE-Dellen
(or cd <path/name-of-iSALE-root-directory>)

Now you want to run the configure program. By default this will attempt to install iSALE and all its associated packages.

If all of the pre-requisite packages are properly installed and you are using a supported system, configure should require only one argument: the path where you want the iSALE programs to be installed. Typically this will be a directory on the local disk of the machine you intend to run simulations on, e.g., /data/isale_user/iSALE; this directory should be outside your copy of the iSALE repository.

However, Users will probably wish to install visualisation software for iSALE. To install pySALEPlot, a python based analysis package for use with iSALE2D, add --with-pysaleplot to the configure command. To install VIMoD a more sophisticated visualisation tool for both 2D and 3D data, with a GUI, add --with-vimod to the configure command.

./configure --prefix=</path/to/install/directory> --with-pysaleplot --with-vimod

Please verify that configure was able to set-up iSALE for all sub-projects. A successful configure will produce output similar to:

----------------------------------------------------------------
--------- CONFIGURATION PROCESS SUMMARY ------------------------
----------------------------------------------------------------
Version flag........................................... -DREV=1802
Make command for external packages..................... make --silent
Make flags............................................. --no-print-directory --silent
Debugging kernel enabled............................... no
Debugging libraries enabled............................ no
Profiling enabled...................................... no
Kinematic description of motion........................ EULER
Advection mode......................................... MAS
ANEOS library.......................................... ../../../ANEOS/src/libaneos.a

Fortran compiler....................................... gfortran
Fortran flags.......................................... -O3 -DREV=1802 -ffree-form
Fortran77 compiler..................................... gfortran
Fortran77 flags........................................ -O3 -DREV=1802
Fortran additional flags............................... -Dlinux -Dgfortran -DARCH_x86_64
Fortran flags for iSALE3D.............................. -DEULER -DADV_MAS -DFRONTFIX
Fortran compiler for parallel compilation.............. mpif90
Fortran compiler for iSALE-2D.......................... gfortran
Fortran flag for invocation of CPP..................... -x f95-cpp-input

C compiler............................................. gcc
C flags (debugging and optimization) .................. -O3 -DREV=1802
C++ compiler........................................... g++
C++ flags (debugging and optimization) ................ -O3 -DREV=1802
VIMoD-path............................................. ${datarootdir}/vimod

qt3 support required................................... yes
qt3 support available.................................. yes
qt3 includes........................................... -I/opt/local/include/qt3
qt3 libraries.......................................... -L/opt/local/lib -lqt-mt

OpenGL support required................................ yes
OpenGL support available............................... yes
OpenGL includes........................................ -I/usr/X11/include -I/opt/local/include
OpenGL libraries....................................... -L/opt/local/lib -lGL -lGLU

pgplot support required................................ no

f2py required.......................................... yes 
f2py available......................................... yes 
f2py compiler.......................................... f2py2.7 
f2py flags............................................. --quiet -c --fcompiler=gnu95

LaTeX required......................................... no
----------------------------------------------------------------

--------------------------------------------- DESIRED / AVAILABLE / ENABLED
iSALE-2D..................................... yes  /  yes  /  yes
iSALE-3D..................................... yes  /  no  /  no
iSALE-tests.................................. yes  /  yes  /  yes
docsrc....................................... no  /  yes  /  no
compression libraries (libjc)................ yes  /  yes  /  yes
vimod........................................ yes  /  yes  /  yes
jtools....................................... no  /  yes  /  no
tools........................................ yes  /  no  /  no
iSALEPlot.................................... no  /  yes  /  no
pySALEPlot................................... yes  /  yes  /  yes
ANEOS........................................ yes  /  yes  /  yes

everything seems to be OK - installation into.......... /Users/isale_user/iSALE/Dellen

----------------------------------------------------------------

See the configure options for more details on the configure process. For example, if configure reports that iSALE2D/3D or any of the associated tools (pySALEPlot, vimod, jtools) are not available to install, you may need to set certain configure options to manually locate required libraries.

Additional configuration options are explained here. See also the configure-section in our FAQ for help.

Compiling and installing iSALE-Dellen

If configuration succeeded, use following command to compile iSALE-Dellen

make

This command will create all the programs (subprograms and libraries) needed to run iSALE.

Note that if you are reconfiguring (e.g., after an update or with different configure options) it is prudent to make clean before recompiling:

make clean
make

To complete the installation of iSALE it is useful to copy all the files needed to run iSALE to a separate directory. This is done using the command:

make install

This installs the binaries, libraries, manpages and documentations, example-files and much more in the path chosen by --prefix=<...> when starting configure.

At this point, you should add the location of the installed pySALEPlot libraries to your PYTHONPATH, so that they are accessible from wherever you run a pySALEPlot script from. To do this, add the following line to your ~/.bashrc file:

export PYTHONPATH="<prefix>/lib:\${PYTHONPATH}" 

Where <prefix> is whatever you entered as the installation directory for iSALE-Dellen using the --prefix option (e.g., /data/isale_user/iSALE). For shells other than bash, this syntax may vary.

Information about the installed files and the structure of the installation directory can be found here.

Running the demonstration simulation

iSALE is distributed with input files for a simple demonstration simulation and a number of more complex examples.

To run the demonstration problem after installing iSALE, go into the install directory <prefix> (e.g., /data/isale_user/iSALE) and list the contents.

cd <prefix>

If you explore this directory, you will find the following useful directories:

  • bin/ contains all of the iSALE executables
  • share/doc contains iSALE documentation, including the manual (iSALE_manual.pdf)
  • share/eos contains equation of state input files for iSALE
  • share/examples contains input files for a number of examples

The best example to run first is demo2D. To run this, go into its directory

cd share/examples/demo2D

And then run the iSALE2D program:

./iSALE2D

You should see a lot of information (about the set-up of the simulation you are running) printed to the terminal, before the following is printed:

         SETTINGS FINISHED, START JOB
         ****************************

The terminal will remain inactive for a few minutes while the simulation runs (unless you run iSALE in the background: iSALE2D &).

When the simulation ends you can visualise output of the simulation using pySALEPlot or VIMoD and compare your results with those described here.

For advanced instructions how to use iSALE or how to setup new simulations please read the iSALE documentation

Compiling latest version of the iSALE manual

As mentioned earlier, a pdf of the manual can be found in the share/doc subdirectory of an iSALE installation, but this is not necessarily up-to-date. To re-compile the manual, use the flag --with-docsrc during the configure step above, before compiling.

Installing iSALE for developers

Those wishing to develop iSALE need to download the development "trunk". This provides access to the most recent version of iSALE, but as this version is constantly changing and has experimental features it is NOT SUITABLE FOR SCIENTIFIC USE. Developers wishing to use iSALE for science as well as developing the code are recommended to install BOTH iSALE-Dellen and the iSALE trunk.

The installation instructions for the iSALE trunk are similar to those for iSALE-Dellen. First, download a copy of the code using SVN
svn co svn://earth.naturkundemuseum-berlin.de/iSALE/trunk ./iSALE-trunk

This will create a directory named 'iSALE-trunk' in your current directory. If a directory with this name already exists, you can
  1. remove or rename this directory (recommended), or
  2. use the following command to download iSALE to another folder:
    svn co svn://earth.naturkundemuseum-berlin.de/iSALE/trunk <path/name-of-folder>
    

If your username on your local system is different to your username for the iSALE repository, you can specify your iSALE username when checking out using:

svn co  --username <user_name> svn://earth.naturkundemuseum-berlin.de/iSALE/trunk <path/name-of-folder>

Replace <user_name> with the svn login name that you were assigned. At the prompt, enter your password. Now svn should start to download iSALE and notify you of all files and directories created.

At the end you will get a message that you "checked out revision X", where X is the current latest revision number for iSALE. This revision number changes each time a modification is made to iSALE.

When the checkout has finished you should see a directory iSALE-trunk in the directory you are in (unless you downloaded the code to a different location). Change into this directory:

cd iSALE-trunk

the directory you are now in is known as the iSALE root directory. The contents of this directory is referred to as your local copy of the iSALE repository.

The next step of the installation is to configure iSALE, which will attempt to install iSALE and all its associated packages.

To install the iSALE trunk along side iSALE-Dellen, make sure that you specify a different install directory when you configure iSALE. For example, if iSALE-Dellen was installed to /data/username/iSALE-Dellen, you might install iSALE-trunk in /data/username/iSALE-trunk:

./configure --prefix=/data/username/iSALE-trunk --with-isaleplot --with-vimod --with-pysaleplot --with-docsrc

Note that --with-docsrc is added to the configure command to allow developers to modify the iSALE documentation as well as the source code.

Please verify that configure was able to set-up iSALE for all sub-projects. A successful configure will produce the output:

----------------------------------------------------------------
--------- CONFIGURATION PROCESS SUMMARY ------------------------
----------------------------------------------------------------
Version flag........................................... -DREV=1802
Make command for external packages..................... make --silent
Make flags............................................. --no-print-directory --silent
Debugging kernel enabled............................... no
Debugging libraries enabled............................ no
Profiling enabled...................................... no
Kinematic description of motion........................ EULER
Advection mode......................................... MAS
ANEOS library.......................................... ../../../ANEOS/src/libaneos.a

Fortran compiler....................................... gfortran
Fortran flags.......................................... -O3 -DREV=1802 -ffree-form
Fortran77 compiler..................................... gfortran
Fortran77 flags........................................ -O3 -DREV=1802
Fortran additional flags............................... -Dlinux -Dgfortran -DARCH_x86_64
Fortran flags for iSALE3D.............................. -DEULER -DADV_MAS -DFRONTFIX
Fortran compiler for parallel compilation.............. mpif90
Fortran compiler for iSALE-2D.......................... gfortran
Fortran flag for invocation of CPP..................... -x f95-cpp-input

C compiler............................................. gcc
C flags (debugging and optimization) .................. -O3 -DREV=1802
C++ compiler........................................... g++
C++ flags (debugging and optimization) ................ -O3 -DREV=1802
VIMoD-path............................................. ${datarootdir}/vimod

qt3 support required................................... yes
qt3 support available.................................. yes
qt3 includes........................................... -I/usr/include/qt3
qt3 libraries.......................................... -L/usr/lib/qt3 -lqt-mt

OpenGL support required................................ yes
OpenGL support available............................... yes
OpenGL includes........................................ -I/usr/include -I/usr/include
OpenGL libraries....................................... -L/lib -lGL -lGLU

pgplot support required................................ yes
pgplot support available............................... yes
pgplot libraries....................................... /usr/lib/libpgplot.a -L/usr/lib/x86_64-linux-gnu -lpng -lz -L/usr/lib/x86_64-linux-gnu -lX11

f2py required.......................................... yes 
f2py available......................................... yes 
f2py compiler.......................................... f2py2.7 
f2py flags............................................. --quiet -c --fcompiler=gnu95

LaTeX required......................................... yes
LaTeX available........................................ yes
----------------------------------------------------------------

--------------------------------------------- DESIRED / AVAILABLE / ENABLED
iSALE-2D..................................... yes  /  yes  /  yes
iSALE-3D..................................... yes  /  yes  /  yes
iSALE-tests.................................. yes  /  yes  /  yes
docsrc....................................... yes  /  yes  /  yes
compression libraries (libjc)................ yes  /  yes  /  yes
vimod........................................ yes  /  yes  /  yes
jtools....................................... no  /  yes  /  no
tools........................................ yes  /  no  /  no
iSALEPlot.................................... yes  /  yes  /  yes
pySALEPlot................................... yes  /  yes  /  yes
ANEOS........................................ yes  /  yes  /  yes

everything seems to be OK - installation into.......... /data/username/iSALE-trunk

----------------------------------------------------------------
----------------------------------------------------------------
----------------------------------------------------------------

As with iSALE-Dellen, please see the configure options for more details on the configure process.

If configuration succeeded, use following command to compile iSALE-trunk

make

This command will create all the programs (subprograms and libraries) needed to run iSALE.

Note that if you are reconfiguring (e.g., after an update or with different configure options) it is prudent to make clean before recompiling:

make clean
make

If iSALE has been installed on a new platform, it is prudent to run iSALE's test suite to verify that the software is working correctly. More information about the test suite can be found here. Run all the tests with the command:

make tests

The testing process may take several minutes. At the end those tests that passed and failed will be reported. If any tests fail, some feature of iSALE was not installed correctly, please seek support by signing in and raising a "New Issue" on this web site. However, note that if you do not install iSALE2D, iSALE3D, ANEOS, iSALEPlot and VIMoD then tests using the uninstalled software will fail. In this case, please run only those tests that apply to the software installed (see the test suite page for more details).

To complete the installation of iSALE it is useful to copy all the files needed to run iSALE to a separate directory. This is done using the command:

make install

This installs the binaries, libraries, manpages and documentations, example-files and much more in the path chosen by --prefix=<...> when starting configure.

Information about the installed files and the structure of the installation directory can be found here.

The iSALE trunk is distributed with the same input files as iSALE-Dellen (see examples), plus any additional examples that have been added since this release. Please follow the instructions as above for running the demonstration simulation, noting that the install directory for iSALE-trunk and iSALE-Dellen will be different.