Installing Waiwera¶

Waiwera can be run on most operating systems (e.g. Linux, Windows, macOS) using Docker, and for many users this is likely to be the easiest option. Linux users also have the option of building a native Waiwera executable (see Native Linux build).

Using Docker¶

Docker is a “containerisation” technology, in which a software application is deployed in a standard unit containing not only the code itself but all its dependencies as well. Because a container isolates the software from its environment, it should always run the same way, regardless of which kind of operating system it is run on.

Installing Docker¶

To run Waiwera this way, first Docker must be installed on your system. You will need administrator privileges to install Docker.

Linux¶

On Linux systems, Docker may be installed directly from your package manager. Alternatively (e.g. if you need a newer version than your package manager is able to provide) you can install it from the Docker repositories. The Docker website has instructions on how to do that for various Linux distributions (e.g. Ubuntu, Debian). It is also important to follow the post-install instructions, particularly to add your user account to the docker group (so you can run Docker containers without root privileges).

Windows¶

For running Waiwera on Windows using Docker, the Windows 10 Pro, Enterprise or Education versions are recommended. Users of these versions can install Docker Desktop for Windows, which provides the best performance and also an easy-to-use graphical interface for configuring Docker.

Users of the Windows 7, 8 or 10 Home versions cannot use Docker Desktop, but can use the older Docker Toolbox for Windows instead. This has a higher performance overhead than Docker Desktop, so Waiwera will run more slowly. Installing and configuring it are also not as convenient.

macOS¶

For running Waiwera on macOS using Docker, macOS version 10.13 or newer is recommended, in which case Docker Desktop for macOS can be installed. This provides the best performance and also an easy-to-use graphical interface for configuring Docker.

Users of older versions of macOS cannot install Docker Desktop, but can use the older Docker Toolbox for macOS instead. This has a higher performance overhead than Docker Desktop, so Waiwera will run more slowly. Installing and configuring it are also not as convenient.

Configuring Docker¶

Once Docker is installed, by default it should have access to all the processors on your system, a sensible amount of RAM, and the directories you are likely to want to run it in. However, it is possible to configure these settings if needed, for example if you have other drives you want to make available to Docker.

The Docker Desktop application on Windows and Mac OS provides a graphical interface for doing this.

Installing the PyWaiwera Python library¶

The simplest way to run Waiwera via Docker is to use the waiwera-dkr executable script which is part of PyWaiwera, a Python library for simplifying tasks related to working with Waiwera. To use this, you will need to:

have the Python scripting language installed on your machine
install the PyWaiwera library

The easiest way to install PyWaiwera is using pip, Python’s package manager:

pip install pywaiwera

or if you don’t have permissions for installing system-wide Python packages, you can just install it locally inside your own user account:

pip install --user pywaiwera

This will download and install PyWaiwera from the Python Package Index (PyPI). During the installation it may warn you that executable scripts are being installed to a directory that is not listed in your system’s PATH environment variable. This means that you need to add this directory to your PATH if you want to be able to run it from anywhere on your machine.

You can also upgrade PyWaiwera to the latest version at any time by running:

pip install --upgrade pywaiwera

Running the Waiwera Docker container¶

The waiwera-dkr script will check if the Waiwera Docker container image is already installed on your system, and if not, it will automatically install it before running your Waiwera model. It also handles the sharing of files between the Docker container and your system. For more details, see Running Waiwera using Docker.

Native Linux build¶

For building a native Waiwera executable on Linux, Waiwera uses the Ansible deployment system, which automates the build process. This includes checking if the necessary tools (e.g. compilers, build tools) are present on your system, installing them if they are not, building Waiwera’s dependency libraries (e.g. PETSc), and building Waiwera itself (which is carried out using the Meson build system).

Install Ansible¶

First, Ansible itself must be installed. Ansible is Python-based, so it can be installed either via your system package manager (e.g. sudo apt install ansible on Debian-based systems), or via PyPI and pip. For more details, consult the Ansible documentation.

Note that the Waiwera build requires Ansible version 2.4 or later.

Download the Waiwera source code¶

The Waiwera source code is version-controlled using Git and hosted on GitHub. The easiest way to download the code is by cloning the Waiwera Git repository. You will need Git installed on your system first. To clone the Waiwera repository, make a new directory for the Waiwera code, and in it execute the following command:

git clone https://github.com/waiwera/waiwera.git .

Alternatively, you can download a ZIP archive of the code here.

Build Waiwera¶

In the downloaded Waiwera source code repository, navigate to the install directory:

cd install

To build and install Waiwera (and its various dependencies, if needed), execute the command:

ansible-playbook ansible/install_local.yml

Root privileges are often required if, for example, additional software packages (e.g. compilers) need to be installed as part of the build process. This can be done by using the --ask-become-pass option:

ansible-playbook ansible/install_local.yml --ask-become-pass

in which case you will be prompted for the sudo password at the start of the build.

Waiwera will be installed into the user’s home directory (~/bin/waiwera) by default. Additional command line parameters can be used to customise the installation. For example:

ansible-playbook ansible/install_local.yml -e "base_dir=/home/fred/waiwera/"

where base_dir is the desired Waiwera installation directory (in this example, /home/fred/waiwera/).

Other example variables include :

petsc_update=true will build a new version of PETSc even if an installed version is detected
- defaults to false meaning PETSc will only be built if an installed version isn’t detected
waiwera_update=true will build Waiwera every time even a new version isn’t pulled by git
- defaults to false
zofu_build=true
- defaults to false and uses meson to build zofu
fson_build=true
- defaults to false and uses meson to build zofu
ninja_build=true
- defaults to false and only builds locally if no ninja install is detected

The following command builds Waiwera (and dependencies), but does not install it.

ansible-playbook ansible/build.yml

Linking to your own PETSc library¶

The build system will download and build its own version of the PETSc library, if it does not detect one already present on your computer. Note that Waiwera currently requires PETSc version 3.15.2 or newer.

If you do have a suitably up-to-date version of PETSc on your machine, and want to link to it rather than having Waiwera build its own, you need to make sure your PETSc is discoverable by the pkg-config tool, before you start the build.

This means that you need a pkg-config file called PETSc.pc somewhere on your system. You can generally find such a file in the lib/pkgconfig subdirectory of your PETSc build directory. You also need to have the directory containing this file included in your PKG_CONFIG_PATH environment variable.

You can check the location of the PETSc library that pkg-config is going to detect using the command:

pkg-config --libs PETSc

It is also possible to check the PETSc version using:

pkg-config --modversion PETSc

Linking to other libraries¶

Similar considerations apply to the other two libraries that Waiwera links to (FSON and Zofu). If you have pre-existing versions already built on your system that you want to link to, just make sure there are pkg-config files for them in locations on your PKG_CONFIG_PATH. Otherwise, the Waiwera build system will build its own versions.

Setting the path¶

To ensure Waiwera can be run from any directory, the Waiwera installation directory should be on the user’s PATH. If this is not the case then it can be added by editing the PATH environment variable. To make this change persistent, add the path modification to your login script (e.g. ~/.profile).

Running the unit tests¶

You can check the Waiwera build by running the unit tests. The unit tests (which test individual routines in the Waiwera code) are created using the Zofu framework for Fortran unit testing, and run using Meson. In the Waiwera base directory, execute:

python unit_tests.py

This will run the Waiwera unit tests on 1, 2, 3 and 4 processes (or up to the number of processes available, if that is less than 4).

It is also possible to run subsets of the unit tests by specifying the module names, e.g.:

python unit_tests.py IAPWS

which tests only the IAPWS module, or:

python unit_tests.py face cell

which tests only the face and cell modules.

If the tests have successfully passed, the unit test output will appear something like this:

Ok:                   32
Expected Fail:         0
Fail:                  0
Unexpected Pass:       0
Skipped:               0
Timeout:               0

The precise numbers of asserts and cases will vary, depending on how many modules are being tested (and how many tests are included for the version of Waiwera you are running). If any tests fail, there will be output regarding which tests are not passing.