Installation

Dependencies

qmesh relies on the following packages:

  • QGIS
  • gmsh
  • GFD_basisChange_tools
  • PyRDM
  • setuptools-qmesh

Installing from PyPI

The easiest way to install qmesh and qmesh-cli is through the Python Package Index. To install the qmesh python API type the following at the command line:

pip install qmesh

If your system has pip installed, the above command will install all dependencies themselves distributed through PyPI. The install procedure will also check for gmsh and qgis and will halt if those are not installed. In your system is missing qgis, it is best to install it through your distributions package manager as documented in the qmesh web-page. If your system is missing gmsh, the best option is to obtain a compiled binary from the gmsh web-page.

To install the qmesh cli :

pip install qmesh-cli

An advantage to installing via PyPI, is the ease to upgrade and remove. Should you wish to upgrade, type the following at a terminal:

pip install --upgrade SomePackage <qmesh-package>

To remove type the following:

pip uninstall <qmesh-package>

Docker containers

Docker containers can be thought of as virtual machines, and provide isolation and control of a working environment. It is easy to construct docker images where the operating system has all the necessary dependencies installed. The images are typically made accessible by uploading to online registries. Docker hub is a popular docker registry, where developers upload images, organised into repositories. For example, the qmesh repository houses all qmesh images, where each image is identified by a unique image tag. Some images are intended for testing and development, and the environment is set-up with a minimal set of dependencies to provide a clean “sand-box”. Other images provide a full qmesh installation and are aimed at facilitating use of qmesh when a user’s environment makes installation hard or impossible. You can see all qmesh images in the qmesh repository tags page. Note that you must have docker installed on your system, preferably thought a package manager to use docker images.

However, since docker provides a user with a bare-bone system, it puts the task of system administration onto the container user. Administering a Linux system can be demanding for users who just want to run qmesh, rather than spend time administering a system. The script qmeshContainer.py, available from the qmesh-containers repository, will set-up an appropriate container for you. The script will pull a docker image with qmesh and all dependencies pre-installed, add you as a user with the appropriate user and group IDs, and run a container.

wget https://bitbucket.org/qmesh-developers/qmesh-containers/raw/HEAD/docker/qmeshContainer.py
python qmeshContainer.py -h
python qmeshContainer.py -mwd

The first line above fetches a copy of the script from one of the qmesh code development repositories, not to be confused with the docker repositories. The former hold code and are used to orchestrate code development. The latter store docker images.

The second line will display brief documentation on the full set of options of the qmeshContainer.py script, invoked by the -h flag:

The third line will run the script, where the appropriate image is pulled, and your tailored container is built. The -mwd will mount your working directory (where you invoked the command from) in the container, so that you can access data on the host system. When mounting host volumes it is important to work in the container with attention on where the files are; any file changes and deletions in mounted volumes will obviously affect files on host system.

Docker does have the disadvantage of consuming a lot of space on hard-drives and the docker deamon is currently of little help with effective clean-up. Should you start experiencing problems, where the docker command interface is not behaving as expected, the cause might be docker files filling up space (typically the partition mounted on /var). On a Linux system you can use the df command-line utility to gather further evidence and corroborate if one of your system partitions is filling up. Assuming docker writes data to the partition mounted on /var, the following steps will clean up your space:

sudo service docker stop
sudo rm -rf /var/lib/docker
sudo service docker restart

However, this will delete all docker images on your system, so it is a good idea to save any partitions you want to keep. Look into docker save and docker load commands for saving and loading containers (start with docker help save and so on). In general it is a good idea to treat docker images as expendable and instead keep the docker-file used to build it, perhaps under version control.