Installation

Installing from PyPi

The easiest way to install pyg4ometry is to install from PyPi. Pyg4ometry has many external requirements which need to be provided by a package manager on your system. To install using PyPi:

pip install pyg4ometry

If installing for MacOS you will need to install (opencascade, cgal, gmp, mpfr, boost, vtk):

brew install opencascade cgal gmp mpfr boost vtk

If installing for Windows you will need to install (opencascade, cgal):

conda install occt cgal-cpp

Building from source

Requirements

pyg4ometry is developed exclusively for Python 3 (Python2 is deprecated). It is developed on Python 3.9 and 3.10.

Packages that are required but will be found through PIP automatically:

Note

A full list can be found in pyg4ometry/pyproject.toml.

Note

if you are choosing a python version, it is worth choosing according to which version VTK provides a python build of through PIP if you use that. See https://pypi.org/project/vtk/#files For example, there are limited builds for M1 Mac (ARM64).

Building

To install pyg4ometry, simply run make install from the root pyg4ometry directory:

cd /my/path/to/repositories/
git clone https://github.com/g4edge/pyg4ometry
cd pyg4ometry

pip install .

If you wish to develop an extension or modify pyg4ometry then run:

pip install -e .

as this will not install pyg4ometry, but the git repository directory will be used for the package. To confirm the install location run:

pip list | grep pyg4ometry

Note

The building uses skikit-build which required cmake. Build errors or warnings are typically from cmake and can help determining the missing dependency

Note

If you are building for windows you are going to need Visual Studio and the appropriate command line tools

Docker image (needs updating)

  1. Download and install Docker desktop

  2. open a terminal (linux) or cmd (windows)

  3. (windows) Start Xming or Vxsrv

  4. Download the pyg4ometry docker file

  5. docker build -t ubuntu-pyg4ometry -f Dockerfile-ubuntu-pyg4ometry .

If you need to update increment the variable ARG PYG4OMETRY_VER=1

To start the container

  1. open a terminal (linux/mac) or cmd (windows)

  2. get your IP address ifconfig (linux/mac) or ipconfig /all (windows)

  3. Start XQuartz (mac) or Xming/Vxsrv (windows). For Xming/Vxsrv (might need to play with the settings when launching)

  4. docker run -ti -v /tmp/.X11-unix:/tmp/.X11-unix -v YOURWORKDIR:/tmp/Physics -e DISPLAY=YOUR_IP ubuntu-pyg4ometry (the -v /tmp/.X11-unix:/tmp/.X11-unix is only required for mac/linux)

Test the installation

  1. docker> cd pyg4ometry/pyg4ometry/test/pythonGeant4/

  2. docker> ipython

  3. python> import pyg4ometry

  4. python> import T001_Box

  5. python> T001_Box.Test(True,True)

Linux installation

There are docker files for Centos 7 and Ubuntu 20. The docker files can be used as list of instructions for installation for each of these OSes.

Python 3.9

At the time of writing, there are limited VTK distributions for Python 3.9 on pypi (what PIP uses when finding packages). However, you can have VTK with Python 3.9 through say MacPorts or by compiling it yourself. In this case, you can comment out the VTK requirement from the setup.py around line 86, as long as you know you can import vtk ok in your Python installation.

Warning

ANTLR will create an unbelievable amount of warnings when using a different ANRLR version that the one the parser was generated with. It should work though. We are trying to include multiple versions of the ANTLR parser to avoid this in future.

Developer notes

Building the manual

To build the documentation

pip install '.[docs]' # to install docs building dependencies
cd pyg4ometry/docs
make
<your browser> build/html/index.html` # to view the docs

Running tests

Running tests

pip install '.[test]' # to install test running dependencies
pytest

Git

pre-commit:

pre-commit install  # to setup pre-commit in source dir (only once)
pre-commit run --all-files # run pre-commit locally
pre-commit run --all-files black  #run only black

Start commit message with the submodule or area changes:

submodule : (type of change) detailed notes

for example:

pycgal : (extra functionality) more 2d mesh processing

Pull requests. PR messages should just explain the change in a concise way as they will form part of the change log e.g:

FLUKA region viewer