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 package qmeshcontainers
provides the command-line utility qmeshcontainer
, the latter is meant to facilitate creating and running qmesh containers. The package qmeshcontainers
is available from the `Python Package Index https://pypi.org/project/qmeshcontainers/`_.
A complete description of the qmeshcontainer
utility is available in the qmeshcontainers
manual, a brief outline of installation and use is presented here.
To install qmeshcontainers
issue the following at the command line:
sudo pip install qmeshcontainers
The primary usage scenario of qmesh containers, is that the user will have prepared the input files in some way and want to run qmesh.
In the commands below, it is assumed that the input files are located in the directory mesh
.
From the command line of your host (computer) navigate to the mesh
directory and enter the directory.
To create and run a qmesh container issue the following at the command line:
qmeshcontainer -mwd
The above will place you inside the qmesh container, giving you a Bash prompt.
If you see any warning messages about user or group details mismatch, pay attention to them, but you do not have to take any action.
As the qmeshcontainers
utility is preparing the container, it tries to match your user set-up (including user and group IDs) so it can access and write files that match your profile into the mesh
directory.
The warning messages are produced in case the utility cannot fully replicate your user set-up.
The above qmeshcontainer
command will also make the directory mesh
available inside the container.
Any changes or deletions you make to the mesh
directory are propagated to the host, so pay attention to any file deletions or changes you might make.
Navigate into the mesh
directory in the container bash prompt:
cd mesh
Assuming that the qmesh mesh generation script is called mesh_generation
the following command at the container bash prompt will execute the script:
python mesh_generation
Review the qmesh script output to troubleshoot any problems and rerun the script to obtain the mesh you want.
You can leave the container running, edit the input files on the host machine, and return to the terminal window with the container bash prompt to re-run the meshing script.
Similarly, you can use gmsh or qgis on the host machine to visualise the mesh you have produced.
Once you have obtained the mesh you want you can exit the container by typing exit
or with the keyboard shortcut Ctrl + d
.
For more information on the qmeshcontainer
utility, including various user options, please consult the qmesh containers manual.