Installation

Ion Beam Simulator is a library, which means that it is not a complete program that you can just execute and use. The library is distributed as source code so it has to be compiled first and then it has to be used through a program written by the user. This brings some complication into using the software but it also enables great versatility. It also makes it possible to use the software in different kind of computers including Linux and Windows systems. You can use the software in many different ways and modify it if you need to. In this document I assume that you have nearly no experience in programming or use of libraries and therefore I will go through each part of the installation of the necessary tools, dependencies and IBSimu itself in a step-by-step fashion.

Tools

In modern Linux systems the software is bundled in packages that can be installed by using graphical package manager systems. They are very simple to use. The only thing you need to know is a list of tools needed. You will need the following software:

C++ compiler

I recommend the C++ compiler from the gcc suite.

Linker

A program for bundling together the compiled object files. Usually comes with the compiler suite (gcc).

Make

Compiler commanding system. GNU make is recommended. Usually comes with the compiler suite.

pkg-config

A metainformation system for querying installed libraries.

An editor

You can do it with notepad, but you are not going to like it. Install a decent programmers editor. I use GNU emacs.

For most of the Linux systems all of this software is already installed by default. For Windows the recipe is also quite simple, but the installation process will be hand made. Because IBSimu is developed under Linux, it uses the GNU autoconf system for compilation. Therefore you have to have to have a unix-like environment in Windows for running the automatic configuration and compilation. The system I recommend to use with IBSimu in Windows is the MSYS/MinGW, which are available at http://www.mingw.org/. I do not recommend using CygWin because I have no experience with it. So, please download and install MSYS and MinGW. I tested IBSimu with MinGW version 5.1.6 and MSYS version 1.0.11 successfully. First install MinGW. Use the "Automated MinGW intstaller" from Downloads and select both "minimal" and "g++" packages to be installed. Use the default installation directory C:\MinGW\. The MSYS should be installed from the MSYS-1.0.11.exe package or newer. Install into the default directory C:\MSYS\1.0\. Enter "C:\MinGW\" when the post-install process asks for the location of MinGW.

If the installation was successful you should have a "MSYS" icon on your desktop. Launching this will open a terminal with a unix-like command prompt with the tab-operated filename completition and all the goodies. When you start the MSYS terminal for the first time, it will create a home directory for you at C:\MSYS\1.0\home\username. Inside MSYS this directory is seen as /home/username, where username is your username on the computer. If you don't have or don't want to use Administrator on the computer (which is what is recommended nowadays) you should have write permissions to this directory. After doing that you have to configure your users path settings by editing a configuration file .profile in your home directory. This script file is automatically executed when you start the MSYS. Add the following lines to your .profile with you favourite editor:

#!/bin/sh.exe
#
# Get the aliases and functions
#
if [ -f ${HOME}/.bashrc ]
then
  . ${HOME}/.bashrc
fi

export PATH="${HOME}/bin:${HOME}/lib:${PATH}"
export LDFLAGS="-L${HOME}/lib"
export CFLAGS="-I${HOME}/include -O2 -march=native"
export CXXFLAGS="${CFLAGS}"
export PKG_CONFIG_PATH="${HOME}/lib/pkgconfig"
export LD_LIBRARY_PATH="${HOME}/lib"

Please not that here I set the compiler optimization options "-O2" and "-march=native". These will make the code much (x3) faster than what it would be without them.

Now restart your MSYS terminal and you should be ready to compile and install programs in MSYS. The MSYS terminal should give you a typical command prompt, which looks something like this:

tvkalvas@PHYS78 ~
$ 

In the prompt above, "tvkalvas" is my username, "PHYS78" is the name of the computer, "~" is the current working directory ("~" equals home). The "$" on the next line indicates that you can write commands after it.

Dependencies

In addition to the tools you will also need some libraries that provide the background functionality for graphics, mathematics and some other background features in IBSimu. In Linux you just use the package manager again and install the software. You need:

FontConfig

A library for finding system fonts.

FreeType2

A library for rendering fonts.

Cairographics

General graphics library.

libpng

PNG graphics file format library.

zlib

Data compression library.

POSIX threads

Multithreading library standard. Several implementations exist. Your Linux should already have an implementation.

GNU Scientific Library

Mathematics library. This is probably the only library which is not installed by default.

Optional software you might want:

GTK+ 3.0

The GNOME Toolkit. Windowing library. Used for interactive graphics. This library has several dependencies on its own.

Gtkglext-3.0

OpenGL library for GTK+ 3.0. Used for 3D rendering on interactive window. Fallback software rendering exists.

UMFPACK/Suitesparse

Matrix factorization/solver library. Used for fast solving in 2D and cylindrically symmetric systems.

CSG

Constructive solid geometry library by the author. One way for building 3D geometries.

For Windows you can get most of these libraries and the dependencies of GTK+ bundled in one package at http://www.gtk.org/download/win32.php. Download the newest stable release "all-in-one bundle". At the time of writing the newest version was 2.22. Uncompress the package contents into a temporary location and copy the contents into C:\MSYS\1.0\ in such a way that the contents of the bin directory in the gtk package will go into C:\MSYS\1.0\bin, lib into C:\MSYS\1.0\lib, et cetera. This needs to be done as the Administrator. The GTK+ in Windows seems to be now distributed through a system called MSYS2 Installer. Please see the website for installation instructions.

The only libraries which are not in the bundle are the POSIX threads and the GNU Scientific Library.

For POSIX Threads you can find a Windows implementation at http://sourceware.org/pthreads-win32/. Download the most recent self-extracting release and uncompress it to a temporary location. At the time of writing this is pthreads-w32-2-8-0-release.exe. From inside the archive (folder Pre-built.2) you need to copy the contents of the include directory into /home/username/include and from the lib directory you need to copy the file libpthreadGC2.a into /home/username/lib/pthread.a (note the rename) and pthreadGC2.dll into /home/username/lib/pthreadGC2.dll (no rename here). In Linux, POSIX Threads should be included in the distribution by default.

The GNU Scientific Library can be fetched from http://www.gnu.org/software/gsl/. Go to the download section and choose the most recent package (gsl-1.14.tar.gz at the time of writing). Save the archive into /home/username/src (I like to keep my files in order and therefore I put sources into a subdirectory src). The GSL will have to be compiled in the MSYS/MinGW environment. Open the MSYS terminal and uncompress the gsl in the src subdirectory:

tvkalvas@PHYS78 ~
$ cd src

tvkalvas@PHYS78 ~/src
$ tar zxvf gsl-1.14.tar.gz

The GSL will be uncompressed into a directory gsl-1.14. go into the directory with cd and run the configure script indicating the desired installation location:

tvkalvas@PHYS78 ~/src
$ cd gsl-1.14

tvkalvas@PHYS78 ~/src/gsl-1.14
$ ./configure --prefix=/home/tvkalvas

If everything goes well the configure script shouldn't complain about anything and it should be ready to compile the GSL. Compilation, checks and installation follow:

tvkalvas@PHYS78 ~/src/gsl-1.14
$ make

tvkalvas@PHYS78 ~/src/gsl-1.14
$ make check

tvkalvas@PHYS78 ~/src/gsl-1.14
$ make install

This is everything you have to have to be able to start compiling IBSimu. You might want to install Constructive Solid Geometry library CSG and SuiteSparse libraries from the IBSimu website for additional features, but I won't cover those in this document. Read the README files which come with the packages for information.

Compilation

The compilation of IBSimu is pretty much similar to compilation of GSL. You should download the most recent version of IBSimu into your src directory, which is then uncompressed and configured. This has to be done manually also in Linux:

tvkalvas@PHYS78 ~/src
$ tar zxvf libibsimu-1.0.6.tar.gz

tvkalvas@PHYS78 ~/src
$ cd libibsimu-1.0.6

tvkalvas@PHYS78 ~/src/libibsimu-1.0.6
$ ./configure --prefix=/home/tvkalvas

The configuration script works mostly automatically, but it also has several options that you can tune to de-select some optional features, for example --without-opengl to compile without OpenGL renderer (requires GtkGLExt), --without-umfpack to compile without the UMFPACK solver (requires SuiteSparse) and --without-csg to compile without CSG solids (requires Constructive Solid Geometry library). The requirements for these three options are automatically detected. You can also do --disable-sigsegv_stack to disable stack printing on segmentation faults, etc. This is necessary for example on non-x86 computers. After successful configuration you can compile, run the checks and install:

tvkalvas@PHYS78 ~/src/libibsimu-1.0.6
$ make

tvkalvas@PHYS78 ~/src/libibsimu-1.0.6
$ make check

tvkalvas@PHYS78 ~/src/libibsimu-1.0.6
$ make install

That finishes the installation.

Usage

As a first test for the library, a quick test of using the library should be done. You should make a new directory for your simulations and a directory for this first test within:

tvkalvas@PHYS78 ~/src/libibsimu-1.0.6
$ cd

tvkalvas@PHYS78 ~
$ mkdir simulations

tvkalvas@PHYS78 ~
$ cd simulations

tvkalvas@PHYS78 ~/simulations
$ mkdir first_test

tvkalvas@PHYS78 ~/simulations
$ cd first_test

tvkalvas@PHYS78 ~/simulations/first_test
$

Then you should copy a tutorial file (and a Makefile) into this directory and try to compile:

tvkalvas@PHYS78 ~/simulations/first_test
$ make

and run it:

tvkalvas@PHYS78 ~/simulations/first_test
$ ./vlasov2d

Please read more instructions from the tutorial.