Installing pyFormex¶

Note

If you are an experienced Linux and pyFormex user, you may directly go to the Quick installation guide.

Introduction¶

This installation manual is for the pyFormex 3.4 version only. Methods and tools for packaging and installing Python applications are currently evolving quickly. For a complex application like pyFormex, with a long legacy and many involved external packages, a nonstandard installation procedure is required. This installation manual is therefore limited to some typical use cases. It describes the requirements for pyFormex, how to download the pyFormex-3.4 source and how to install that source so you can run it.

pyFormex is being developed on GNU/Linux systems and currently only runs on Linux. On other systems your best option is to run Linux in a virtual machine or boot your machine from a USB stick with a Linux Live system.

pyFormex is software under continuous development. It can be run directly from the development sources and some users are indeed doing that. It holds a certain risk however, because the development version may at times be unstable or highhly incompatible with previous versions and thus break your applications. At regular times we therefore create official releases, which provide a more stable and better documented and supported version, together with an easy install procedure.

If you can meet the requirements for using an officially packed release, that is the recommended way to install pyFormex. All the software packages needed to run pyFormex are open source and are freely available

Requirements¶

To install an official pyFormex release, you need a working GNU/Linux system. First, make sure that the Dependencies listed below are installed on the system. If you need to install some of them, you will need to have root privileges to the system (whether through su or sudo) or to ask your system manager to install them dfor you. Then preceed to Install an official pyFormex release.

If you need to install a new GNU/Linux system from scratch, and have the choice to pick any distribution, we highly recommend Debian GNU/Linux or derivatives. This is because most of the pyFormex development is done on Debian systems, and below you’ll find precise instructions to install dependencies on Debian. Also, the Debian software repositories are amongst the most comprehensive to be found on the Internet. We recommend Debian 11, Debian 12, Ubuntu 22.04, or similar derivatives.

Dependencies¶

Note

If your Linux system is Debian 11, Debian 12, Ubuntu 22.04 or derived from these, you may opt to directly go to install dependencies on Debian.

Most popular GNU/Linux distributions provide appropriately packed recent versions of the dependencies, so that you can install them easily from the pacakge manager of your system. In case a package or version is not available for your system, you can always install it from source. We provide the websites where you can find the source packages.

Whether you install an official release package of pyFormex, or you run pyFormex from the development source tree, you need to have the following installed (and working) on your computer:

Python

Version 3.8 or higher, 3.9 or higher is recommended. Nearly all GNU/Linux distributions come with Python installed. Some old installations may however still have Python2.x installed as the default Python, so you may have to install the Python3 version. Usually, the Python 3.x executable is named ‘python3’, and pyFormex expects it that way. To check your version, do:

python3 --version

Python setuptools

Python wheel

NumPy: Version 1.16 or higher, 1.19 recommended. NumPy is the package used for efficient numerical array operations in Python and is essential for pyFormex.
PIL: The Python Imaging Library from the pillow fork, used for loading and saving images in lots of formats.
Qt5 or Qt6: Qt is the widget toolkit on which the pyFormex Graphical User Interface (GUI) is built. We recommended Qt5, but the newer Qt6 version should also work if you have the proper Python3 bindings
PySide2 or PyQt5 or PyQt6 or PySide6: These are Python bindings for the Qt5 (or Qt6) libraries. We recommend Pyside2 if the licensing suits your use case.
PyOpenGL: Python bindings for OpenGL, used for drawing and manipulating the 3D-structures.
admesh: Used to check and fix STL files. We need the binary, not the Python library.
libgts-0.7-5: A library for operating on triangulated surfaces.

To compile the acceleration library (highly recommended!), you will also need the appropriate Python and OpenGL header files, GNU make and the GNU compiler gcc:

make
gcc
python3-dev
libglu1-mesa-dev

Furthermore, we recommend to install the following for extended functionality:

python3-gnuplot or python3-matplotlib
python3-pydicom
python3-docutils
python3-scipy
units
imagemagick
tetgen
libdxflib3

Installing dependencies on Debian and alikes¶

On Debian GNU/Linux systems (and Debian-derivatives like Ubuntu) you can install all basic prerequisites and recommended packages and all their dependencies with the following command (executed in the unpacked pyFormex source, see Install an official pyFormex release):

sudo ./apt_install_deps

Install an official pyFormex release¶

Download pyFormex¶

Official releases of pyFormex are distributed in .tar.gz (tarball) format. They can be downloaded from Releases. As of the writing of this manual, the latest release is 3.4. You can download the latest version with the command:

wget https://download.savannah.nongnu.org/releases/pyformex/pyformex-latest.tar.gz

Alternatively, you can use the specific version filename: pyformex-3.4.tar.gz. After downloading, you have to unpack the tarball with the command:

tar xf pyformex-VERSION.tar.gz

where you replace VERSION to match the downloaded file. This will create a subdirectory pyformex-VERSION containing all the source files.

Build pyFormex¶

Go into the directory where you unpacked the pyFormex source:

cd pyformex-VERSION

and execute the following command:

./install.sh build

This will build pyFormex, compile its acceleration libraries and some external utility programs, and collect all needed files into a wheel format archive placed under the build subdirectory. If the command

ls build

shows a file name like pyformex-3.4-cp311-cp311-linux_x86_64.whl, you are ready to install its contents.

Install pyFormex¶

Installing pyFormex is done with a command like:

[ sudo ] ./install.sh [-s] [-S] [-d] install

Before doing the install, you have to make a few decisions on how and where the program should be installed.

Install as user or as root¶

Running the installation procedure as a normal (non-root) user will install pyFormex under the user’s home directory. The user will have access to all the files with the ability to change these as he wishes. Other users on the same system will normally not be able to run the installed pyFormex.

Running the installation procedure as root (e.g. using sudo), will install pyFormex under /usr/local and it will become available to all users on the system, but they will not be able to modify the program (as normal user).

Install as multiversion or single version¶

By default the installation procedure allows multiple pyFormex versions to be installed in parallel. The pyformex package is then installed in a folder pyformex-VERSION in the installation path and the pyFormex executable is also called pyformex-VERSION. One of the installed versions can be made the default: that version will then be executed if you simply enter pyformex. That will also be the imported package if you do import pyformex in Python. The -d option of the install.sh procedure will set the version being installed as the default.

If you prefer to allways install just a single version, use the -s option on the install procedure. If existing pyFormex installations are detected, you will be asked if they may be deleted before installation of the new one. An option -S will force such deletion without asking (use with care). The -s/-S option installs pyFormex just like in a multiple versions system. It implies the -d option, making this single version the default. You can later add other versions if you wish to do so.

Common installation examples¶

As user:

./install.sh install

As user, making the new version the default:

./install.sh -d install

Systemwide, making the new version default:

sudo ./install.sh -d install

Systemwide, single version install:

sudo ./install.sh -s install

Systemwide, single version install, silently remove other versions:

sudo ./install.sh -S install

Check installation¶

If the installation succeeded, you can find out where pyFormex is installed with the command

pyformex --whereami

Use pyformex-VERSION if you didn’t make it the default. Next you can run

pyformex --detect

to give you a list of installed and detected software that pyFormex is able to use as helpers. Check under ‘Installed System’ that you have pyFormex_installtype (R) or (U) and pyFormex_libraries (pyformex.lib.misc_c, pyformex.lib.nurbs_c). The gts, gts-bin and gts-extra packages do not have a version, and just display ‘gts’ if they are installed.

You can find out what pyFormex versions are installed in the target install path with:

pyformex -V

Cleanup installation files¶

After installation you may want to cleanup the temporary files generated during the build/install:

./install.sh clean

Use sudo if you also did the build with sudo.

You can also safely remove the unpacked source directory and even the downloaded targz:

cd ..
rm -rf pyformex-VERSION
rm pyformex-VERSION.tar.gz

Uninstall pyFormex¶

When pyFormex is installed by the procedure above, it can be removed by executing the command

pyformex --remove

and answering ‘yes’ to the question. You may want to do this before installing a new version if you do not want to remove all the existing versions.

Quick installation guide¶

Quick installation from official .tar.gz release or from git clone:

Install dependencies. On recent Debian/Ubuntu you can just run:
```
sudo ./apt_install_deps
```
Install pyFormex. This can be done either in user space, or system-wide (as root):
```
./install.sh all
```
or
```
sudo ./install.sh all
```
In the first case, the executable is installed under $HOME/.local/bin. For the system-wide installation, the executable is in /usr/local/bin.

As of version 2.7 of pyFormex, the default installation allows for multiple versions being installed in parallel, and the executable is named pyformex-VERSION, where VERSION is the version designator.

Add a ‘-d’ to the install.sh options to make the installed version the default by linking this executable under the generic name ‘pyformex’.

Add a ‘-s’ or ‘-S’ to the install.sh options to create a single version installation. Older versions are removed after user acknowledgment (with -s) or silently (with -S). This option implies ‘-d’.
(Optional) Remove the temporary build directory with:
```
./install.sh clean
```
Add ‘sudo’ if you also used it to build.

Running pyFormex from sources¶

If the officially released pyFormex packages are not suitable for your needs, and you can not find proper packages for your distribution, you can try running pyFormex directly from the source in the git repository. Besides the Dependencies for the official release, you will also need to have git installed.

The source code can be downloaded anonymously from the Git repository or the Development repository. Any of these commands:

git clone https://git.savannah.nongnu.org/git/pyformex.git MYDIR
git clone https://gitlab.com/bverheg/pyformex.git MYDIR

will checkout the source to a local directory MYDIR. The first repository contains more stable versions.

Provided you have all the prerequisites installed, pyFormex can then be run directly from the checked out source with the command:

MYDIR/pyformex/pyformex

If you want to use the compiled accelerator library however, you will have to create it first:

cd MYDIR
make lib

Once you have a checked-out source tree, you can easily sync it to the latest repository version by just issuing the following command from your checkout directory:

git pull

Table of Contents

Previous topic

Next topic