Getting started

This chapter covers installation and how to run basic simulations.

Installation

Getting up and running is relatively straightforward on linux and OsX. arb is not supported natively on windows, however you can install arb under the Windows Linux Subsystem (WLS) if you have this installed - in this case follow the ubuntu instructions.

Step 1: Get the arb source code

arb is hosted on a public github repository.

If you are comfortable using git you can download the master branch and then rename the directory arb_master using:

git clone https://github.com/daltonh/arb.git
mv arb arb_master

Alternatively you can use curl to get a zip file of the repository from github and then change its name to be consistent with that used in this manual using:

curl -L https://github.com/daltonh/arb/archive/master.zip --output master.zip
unzip master.zip
mv arb-master arb_master
rm master.zip

Either of these methods creates the arb source code directory arb_master, referred to in this manual as the ‘arb directory’. Once installation has completed, this ‘arb directory’ needs to stay put, so if the present location isn’t appropriate, move it now.

Step 2: Install software dependencies

This step is the most work, and involves downloading all of the software and packages that are required to run arb.

Install dependencies on Ubuntu linux

On recent versions of ubuntu (tested on 10.04 through to 18.04) you run an ubuntu install script which uses apt-get to install the required packages. This doesn’t take long.

> sudo arb_master/install/install_dependencies_on_ubuntu.sh

If all dependencies are installed successfully, the script will end with a SUCCESS message.

On ubuntu 8.04 some of the software versions in the standard repositories are too old to be installed via this method.

Install dependencies on Redhat linux

Similarly on redhat linux you run an redhat install script which uses yum to install the required packages.

> sudo arb_master/install/install_dependencies_on_redhat.sh

Installation on redhat linux isn’t as well tested as installation on ubuntu linux.

Install dependencies on OsX

Installation on OsX requires the macports package manager to be installed, which itself requires Apple’s (free) Xcode developer package to be installed first. Detailed instructions on installing macports are OsX version-specific and found here.

Once macports is installed installation on OsX is similar to on linux, however macports generally compiles software, so it will take some time to install all the dependencies from scratch (maybe an hour?). The install script for OsX is the macports install script.

> sudo arb_master/install/install_dependencies_on_osx_using_macports.sh

Step 3: Compile suitesparse and make `arb` available from the command line

In this step an install script is run that performs some setup steps for the source code housed in arb_master. Firstly the GPL licensed matrix solver ‘suitesparse’ is downloaded and compiled (within arb_master/src/contributed/suitesparse). Secondly shell environment variables are set so that the arb executable programs housed in the bin directory are found from the command line. This step will add lines to your shell configuration file (eg. ~/.bashrc, ~/.tcshrc, etc) by setting the shell environment variable $ARB_DIR to point to the ‘arb directory’, in this case arb_master.

> arb_master/install/install_globally.sh

Optional Step 4: Enable syntax highlighting in `vim`

If you use vim as your go-to editor, then you can enable syntax highlighting within arb input files using the following:

> ( cd arb_master/install/vim_syntax; ./install_vim_syntax_files.sh )

Step 5: Test that everything is working

Now log out of the terminal and back in again to ensure your environment variables are set correctly. Then try the follow command that will run an empty simulation, ending with a line starting with SUCCESS.

> arb

At the same time check that the progress monitoring python-based graphical tool appears via

> arb_plot

and that gmsh is found from the command line by running

> gmsh

If everything went well, congratulations, you’re ready to start simulations. You can remove the output directory that was created by arb using

> rm -r output

If you have problems with any of these steps, refer to the installation problems FAQ. You can also find information on installing individual or alternative software dependencies in Software Dependencies.

How to run `arb` simulations

In this section we cover the basics of running an arb simulation, using the first of three tutorial problems that are included with the arb distribution.

The `arb` script

Simulations are run using the arb (shell script) command. This command accepts many different types of options from the command line to control things such as where output is to written, and what compiler and compiler options to use. Running the following will give a full list of the available options and basic usage instructions:

> arb --help

At a minimum, running an arb simulation requires an arb input file. These files have the extension .arb and specify all aspects of a simulation, except for any computational domain geometries.

Generating a mesh file for the domain being simulated

If a simulation does require a computational domain, then it additionally requires a mesh file (extension .msh). Mesh files detail how the computational domain is discretised (split) into many small elements. They are written using a format that is compatible with the gmsh program. Mesh files can be created from geometry files (extension .geo, another gmsh format) using gmsh. Geometry files contain information about the geometry of the computational domain. arb does not read .geo geometry files directly, however geometry files are required to create the .msh files that arb can read.

The arb distribution comes with a whole bunch of example simulation files, contained within separate subdirectories within the examples directory, which is itself within the ‘arb directory’ (ie, $ARB_DIR). Each examples subdirectory contains an arb input file, as well as possibly geometry and mesh files.

The first simulation we are going to run is called heat_conduction_around_ellipse and is the first of three tutorial problems designed to introduce the features of arb. The problem concerns the diffusion of heat within a 2D rectangular domain that contains an elliptical hole. To run this simulation we are going to get the arb and geometry input files from the example’s directory, and place them into a new directory called tutorial_1:

> mkdir tutorial_1
> cd tutorial_1
> cp $ARB_DIR/examples/tutorial_1/*.arb .
> cp $ARB_DIR/examples/tutorial_1/*.geo .

You can visualise the geometry of the computational domain using

> gmsh rectangle_with_ellipse.geo

To view the geometry use the ‘tools’ menu, then ‘options’, ‘Geometry’, ‘visibility’ tab, and select ‘lines’ and ‘points’. You should see the outline of the 2D computational domain. The geometry also has various regions associated with it (gmsh term physical entities) which we will use within arb to specify where equations are applied. To visualise the regions go back to the ‘tools’ menu and have a look at the ‘visibility’ feature.

To use this geometry in the simulation, we first need to create a .msh mesh file from the .geo geometry file. This can be done from within gmsh by using selecting the ‘Mesh’ item under ‘Modules’ on the left of the main window, then clicking on ‘2D’. If no mesh appears, return to the ‘options’ window, but now select ‘Mesh’, ‘visibility’ tab and check ‘Surface edges’. You should see the domain split into many small triangular elements, referred to as ‘cells’ in arb. You could save this mesh for use in the simulation (‘Modules’, ‘Mesh’, ‘Save’), however a quicker way is to use the arb_create_msh script to create the mesh file directly from the geometry file without opening the gmsh GUI window (this also applies some good options for arb simulations):

> arb_create_msh rectangle_with_ellipse.geo

This will create the file rectangle_with_ellipse.msh within the tutorial_1 directory. You can visualise this mesh file directly using gmsh via

> gmsh rectangle_with_ellipse.msh

Finally, let’s see how this filename is attached to the simulation. Open the arb input file heat_conduction_around_ellipse.arb using a text editor such as ‘atom’, ‘vim’ etc, ie;

> atom heat_conduction_around_ellipse.arb

Within an arb input file, anything following the # character is a comment. Scrolling down this arb file you will see that most of the file contains comments. There are only a few actual commands. Scroll down the file and find the arb command that specifies the name of the mesh file to read:

MSH_FILE "rectangle_with_ellipse.msh"

So if you want use a different geometry within your simulation, change the geometry (eg copy and edit the .geo file), recreate the .msh file and change the above arb MSH_FILE command to reference the new .msh file.

You are now ready to run the simulation.

Running the first simulation

You should now have the two input files required to run your simulation within your local tutorial_1 directory. That is;

rectangle_with_ellipse.msh
heat_conduction_around_ellipse.arb

To run the simulation pass arb the appropriate input file:

> arb heat_conduction_around_ellipse.arb

Watching the screen output you will see that the simulation passes through the following three stages:

equation setup (using setup_equations.pl) which produces the bespoke fortran file equation_module.f90,
code compilation (using the available fortran compiler), and finally
running the produced arb executable, including reading in the mesh file and numerically solving the equations

If everything goes well the screen output will finish with SUCCESS: the simulation finished gracefully. If anything goes wrong in any of the steps, read the screen output carefully. In most instances this output will tell you what is going wrong. Otherwise the simulation problems FAQ may help to resolve the problem.

Checking the simulation output

All information/data created during a simulation is written to the specified output directory. By default this directory is named output (use the arb option --output to specify a different output directory name). Have a look at the contents of this directory using

> cd output
> ls

You should see that it contains the following files and directories, listed alphabetically:

build/: this directory contains files used internally by arb when compiling the simulation
convergence_details.txt: this directory contains files used internally by arb when compiling the simulation
input_files: this directory contains copies of the files used to run the simulation, as well as a record of the command line options passed to arb
kernel_warnings.txt: ‘kernels’ are used to discretise averaging and gradient operators. Any problems with this process are detailed in this file
latest.output.msh: a link that always points to the last written output.msh file
output.msh: a gmsh compatible file that stores the spatially dependent results (data) produced by the simulation. This file can be opened with gmsh. This file also contains details of the mesh used in the simulation, and can be used by arb to restart a simulation, reading in any previously-produced data and as well as the mesh. See Meshes for more information.
output.stat: this file gives basic statistic for every variable used in the simulation, including maximum and minimum values across the domain
output_step.csv: this file gives values for any NONE centred values for each iteration during the simulation. Data in this file can be plotted easily using arb_plot
previous: this directory contains a copy of data that was last housed in this output directory. This is mainly a safety feature for the case where a simulation was restarted accidentally
setup_data: this directory contains information produced by setup_equations.pl during the setup phase of the simulation. It contains useful files such as unwrapped_input.arb, which shows the input commands actually passed to arb (with all string replacements done), and variable_list.arb and region_list.arb, which summarise the final variable and region definitions used in the simulation.

For now the most interesting file is output.msh. Open this file using gmsh via

> gmsh output.msh

The simulation you have just run concerns the diffusion of heat throughout the 2D domain. Upon opening, gmsh should be showing how the temperature field <T> varies across this domain. (If you see a lot of grey dots instead of the temperature field, you need to turn off the geometry points via the ‘Tools’ menu, ‘Options’, ‘Geometry’, then under the ‘Visibility’ tab turn off points).

A second variable, <q_f>, is also produced by the simulation. Whereas <T> is a cell centred variable (one value for each cell element within the domain), <q_f> is face centred. Faces are the elements that separate cells - in this 2D simulation faces are lines, while most of the cells are triangles (there are also boundary cells that we’ll discuss later).

Using the ‘Post-processing’ item under the ‘Modules’ menu, uncheck the box next to <T> but leave the <q_f> flag checked. What you’re now seeing is the flux of heat that crosses each face, in a direction normal to that face.

This is interesting, but a bit hard to understand, as the flux is defined relative to a normal vector associated with each face. On boundary faces (the faces that mark the boundary of the simulation domain) these face normals always point outwards. However on domain faces (the faces that have domain cells on both sides) these normals could point one of two ways, so we don’t know which way the heat flux is directed. In the next section we’ll look at alternative ways of visualising this flux.

Delving deeper into the arb input file

In this section we’ll look further at how this heat conduction simulation is setup within the arb input file. Open the file heat_conduction_around_ellipse.arb again using your favourite text editor.

Information statements

Near the top of this file you’ll find the following information statements:

VERSION 0.62
INFO_TITLE "Steady state heat diffusion around an ellipse"
INFO_DESCRIPTION "Tutorial 1: Example problem demonstrating how to setup a Laplace equation, with associated flux (Neuman) and absolute (Dirichlet) boundary conditions on the walls.  Two dimensional, with an unstructured mesh."
INFO_AUTHOR "Dalton Harvie"
INFO_DATE "15/4/20" # interpreted as the last modification date

The VERSION statement describes the arb version that this file is compatible with. With very few exceptions current arb versions can read arb files created for older code versions. The other INFO_ statements simply provide information about the simulations. It is a good idea to keep these updated, otherwise you’ll forget what the purpose of the simulation is for.

Region statements

Regions are groups of elements, used to specify where equations, unknowns and other variables are defined and used. Each region has a specific centring, equal to the centring of all the elements that it contains. There are three types of elements in arb: cells, faces and nodes. Cells come in two types, being domain cells (<domain>) which have a dimension equal to that of the domain (2D triangles here), and boundary cells (<boundarycells>) which lie on the outside of the domain and have a dimension that is one less than that of the domain (1D lines here). Faces are the elements that separate cells, or equivalently define the faces of the cells. The region <domainfaces> specifies all of the faces that separate two domain cells, while <boundaries> defines the faces that lie on the outside of the domain (and are coincident with <boundarycells>). All faces have a dimension that is one less than that of the domain (1D lines here). Nodes are the points (0D always) that define the vertices of the cell and face elements.

Regions can be defined one of three ways in arb:

when the geometry is created (ie, within the .geo and subsequently the .msh files),
automatically by arb (eg, the system region <allcells> always refers to all cells within simulation), or alternatively
using statements within the arb input file.

As an example of the latter, further down the file you’ll find this region specification statement:

FACE_REGION <walls> "compound(+<boundaries>-<hole>)"

This statement means that a new region of face elements is to be created, called <walls>. The compound region operator is used to create this region from the existing face centred regions, <boundaries> and <hole>. The compound operator works by either adding (+) or deleting (-) elements to the new region. If the elements are being added to the new region, but are already there, no action is taken. Similarly, if the elements are being deleted from the new region, but are not already there, no action is taken. The face region <boundaries> is a ‘system region’ that is generated automatically by arb for all simulations, and consists of all face elements that bound the computational domain - in this case all of the faces on the circumference of the rectangle, as well as those on the circumference of the ellipse. Conversely the face region <hole> is a region that is defined in the .msh file, and consists of all boundary face elements that lie along the circumference of the ellipse. Hence, the compound operator in this statement takes the entire boundary of the computational domain (<boundaries>), and removes the circumference of the ellipse (<hole>), leaving the resulting <walls> region as just the circumference of the rectangular domain. The <walls> region will be used later to specify some of the boundary conditions for the heat diffusion problem.

There are number of region operators that can be used to create regions from within the arb input file. These include at, which finds a single element closest to a specified point, boundaryof which finds the elements on the edge of another region, and variable which creates a region based on the value of a variable. For more details, see Regions.

Mesh statements

The command to read a mesh has already been discussed. To note, this command accepts options such as output, nooutput, and input that control whether the file is to be read from and/or written to. Other options control what formats are written to. For example

MSH_FILE "output/output" centringvtkoutput

specifies that the output file output/output.msh is also written as a bunch of vtk files, with variables separated into files of consistent centring. This type of output is suitable for reading by the alternative visualisation software ‘paraview’. By default any file with a basename of output has the default options of noinput,output, whereas any other mesh file has the default options of input,nooutput. These defaults can be overwritten. More details are given in Meshes.

Variable statements

Most of the problem specification for a simulation is done via variable definitions.

In arb there are a number of different variable types. For now the most important are:

UNKNOWN: a variable whose value is to be found during the simulation
EQUATION: a variable that (directly or indirectly) depends on UNKNOWN variables, and whose value should be zero when the equation is satisfied
DERIVED: a variable that is function of other variables, including other DERIVED variables and UNKNOWN variables
CONSTANT: a variable that does not change during a simulation
OUTPUT: a variable that is used for output only

In addition, like regions, all variables have a specific centring. The possible centrings for variables are CELL, FACE, NODE and NONE, with NONE specifying a variable that is not associated with any particular mesh element. Except for NONE centred variables, all variables must be associated with a region that has the same centring as the variable - that is, each variable has as separate value for each element within the region that it is associated with.

Returning to the heat diffusion problem, there are a number of variable definitions used to define this problem.

The first we consider are some constants:

CONSTANT <D> [W/(K.m)] 1.d-3
CONSTANT <hole flux> [W/m^2] -1.d+1

These two constant statements define two none-centred constants, being the thermal conductivity of the material (<D>) and flux of heat out of the domain around the circumference of the ellipse (<hole flux>). In variable definition statements, the optional argument in square braces ([]) represents the units of the variable. For these particular statements, the centring of the variable has not been given. However, by default constant variables are assumed to be NONE centred. Hence an equivalent definition for <D> would be:

NONE_CONSTANT <D> [W/(K.m)] 1.d-3

In these expressions we use the fortran double precision convention (ie, 1.d+3, rather than 1.e+3) when specifying floats. Also, note that for these particular constant definitions, the definition is just a number which is not quoted. Unquoted numerical values can only be used in CONSTANT definitions. If instead we want to define a constant in terms of other constants (or other values) we need to quote the expression, as in this example that defines an increased diffusivity:

NONE_CONSTANT <D increase factor> 1.d+6
NONE_CONSTANT <D increased> "<D>*<D increase factor>"

The next statement defines the unknown variable that we are trying to find, in this case the temperature field <T>:

CELL_UNKNOWN <T> [K] "1.d0" ON <allcells>

This variable has a value for every cell within the mesh (ie, <allcells>), being both the domain cells (ie, the triangles) and boundary cells (ie, the lines on the edges of the computational domain). The expression given in this definition (ie, 1.d0) is the initial value that will be given to this variable when the simulation starts.

Derived variables are defined for convenience. In the following we define the flux of heat over each face within the domain (ie, over <allfaces>).

FACE_DERIVED <q_f> [W/m^2] "-<D>*facegrad(<T>)" ON <allfaces> output

The expression in this definition statement uses the face centred variable operator facegrad, which calculates the gradient its cell-centred contents (<T>) in a direction normal to the current face. More specifically, here facegrad calculates the gradient of <T> in the direction of the local face’s normal vector.

The next three variables specify the three equations that need to be solved. When the simulation has converged, the values of all equation variables will be zero (or, within some tolerance of zero). The three equations here specify a conservation of heat equation applied over the domain cells (ie, <T transport> defined over <domain>), a heat flux boundary condition applied over the circumference of the ellipse (ie, <T hole> defined over <hole>), and a temperature boundary condition applied over the circumference of the rectangle (ie, <T walls> over <walls>).

CELL_EQUATION <T transport> "celldiv(<q_f>)" ON <domain>
FACE_EQUATION <T hole> "<q_f>-<hole flux>" ON <hole>
FACE_EQUATION <T walls> "<T>-1.0d0" ON <walls>

Note that within <T transport> the cell centred variable operator celldiv calculates the divergence of a vector field, taking as input a face centred component of that vector field, oriented in the direction of that corresponding face. To illustrate, celldiv(facegrad(<phi>)) actually calculates the Laplacian of a scalar <phi>.

The final variable statement in the input file defines a none centred OUTPUT variable that is only calculated once the simulation has converged. In this case we are calculating the average temperature throughout the <domain>.

NONE_OUTPUT <T average> [K] "cellsum(<T>*<cellvol>,<domain>)/cellsum(<cellvol>,<domain>)"

This definition uses the cellsum variable operator that sums values across the specified cell region <domain>. The system generated variable <cellvol> specifies the volume of each cell (actually in this 2D simulation it is actually the area of each element), such that <T average> is the cell weighted averaged temperature throughout the domain.

More details regarding variables and their definition statements are given in Variables.

Moving on

Within this section we’ve looked at how to run basic simulations, how to create geometry and mesh files, and how problems can be defined using arb syntax within an arb file.

There are a few things you could do to continue learning how to use arb:

Try swapping the boundary conditions in the heat conduction problem. Do you know why the variable <hole flux> was given a negative value?
Try making the problem non-linear, by making the diffusivity a function of <T>. For example, adding the line

FACE_DERIVED <D special> "<D>+<T>/1000.d0" ON <allfaces>

to the bottom of the input file (noting that arb uses a last-read-takes-precedence philosophy throughout).

Try visualising the heat flux using a vector representation by adding this line to the bottom of the arb input file:

FACE_OUTPUT <q_f_vect[l=<<i>>]> "<q_f>*<facenorm[l=<<i>>]>" ON <allfaces>

Note that the [l=1] syntax option on a variable name refers to the first component of a vector, and that the <<i>> in the above is an index replacement string which will cause the above statement to be repeated for each dimension used in the simulation. <facenorm[l=1]> is a face centred system variable, being the first component of the unit normal to the local face.

Look at the other tutorial problems within the examples directory. Tutorial problem 2 looks at solving coupled chemical reaction ODEs, whereas tutorial problem 3 solves the Navier Stokes equations in a 2D domain.

The remainder of this manual is reference material.