2.3. Installing GATE

Table of Contents

Installing OpenGATE

To install GATE for Python you will use the OpenGATE project, which provides a pure Python interface on top of Geant4. By this point you should already have a working Python environment as described in the earlier chapters on requirements and environments. Here, the focus is on how to get OpenGATE itself into that environment.

OpenGATE is distributed as a regular Python package that you install with pip. You do not need to compile Geant4 manually, because OpenGATE comes with prebuilt components for common platforms that include the Geant4 engine. This is one of the main advantages of the Python based interface for beginners.

The basic installation command, executed inside your chosen environment, is

bash

pip install opengate

This command downloads the latest released version from the Python Package Index and installs it together with its Python dependencies. If you need a specific version for compatibility with an existing project or a tutorial, you can specify it explicitly, for example

bash

pip install "opengate==1.4.0"

You can also upgrade an existing installation to the latest version by adding the --upgrade flag:

bash

pip install --upgrade opengate

On some systems you may have both Python 2 and Python 3 installed. In that case be sure that the pip command refers to the same Python version as the one you plan to use in your simulations. If needed, call python -m pip instead, from within your virtual or conda environment:

bash

python -m pip install opengate

Keep OpenGATE, your Python environment, and Geant4 support consistent. Installing opengate into the wrong environment or mixing system wide packages with environment packages is a common source of hard to debug problems.

If your platform is not supported by the prebuilt wheels, pip might attempt a source build. Compiling Geant4 and its dependencies is a more advanced topic and is typically not required for standard OpenGATE use. As a beginner, if you see compilation errors during pip install opengate, first verify that you are using a standard 64 bit Linux, macOS, or Windows system with a recent Python 3 version. If the problem persists, it is usually better to adjust your environment to a supported configuration than to attempt manual compilation.

Installing required packages

OpenGATE brings in several core dependencies automatically, but for practical work you also need a small scientific Python stack for scripting, analysis, and plotting. Installing these packages inside the same environment as OpenGATE keeps your simulations and analysis tightly integrated.

At minimum you will want NumPy for numerical arrays and Matplotlib for basic plots:

bash

pip install numpy matplotlib

For reading ROOT files produced by GATE and for more advanced analysis you will typically install Uproot, Pandas, and SciPy:

bash

pip install uproot pandas scipy

If you plan to work with medical image formats such as NIfTI or MHD, or to manipulate images in Python, SimpleITK is also very useful:

bash

pip install SimpleITK

These packages are independent of OpenGATE itself, but they are used throughout the examples and later chapters for reading simulation outputs, building spectra, creating dose profiles, and visualizing results.

A typical minimal environment for GATE simulations and data analysis might therefore be installed with a single command like

bash

pip install opengate numpy matplotlib uproot pandas scipy SimpleITK

You can check which packages are present in your environment and their versions with

bash

pip list

This helps when you need to reproduce a simulation environment or report the versions used in a publication or project report.

Keep all required packages inside the same virtual or conda environment as OpenGATE. Avoid using sudo pip install or mixing system packages with environment packages, since this often leads to version conflicts and broken installations.

If you later discover a missing package while running examples, you can install it on demand. Use the same pip command from within the active environment, rather than creating a new environment each time.

Checking the installation

After installing OpenGATE and the required Python packages, you should verify that everything is correctly set up before attempting larger simulations. The basic idea is to confirm that Python can import the package, that the reported version is what you expect, and that a simple simulation can run to completion.

Open a terminal, activate your Python environment, and start the Python interpreter:

bash

python

Inside Python, try importing OpenGATE:

python

import opengate

If this line executes without any error, the core installation is visible to Python. Now check the version that is installed:

python

import opengate
print(opengate.__version__)

You should see a version string such as 1.4.0. Comparing this value with your course material or project documentation tells you whether you are on a compatible version.

To perform a slightly deeper test, you can create a minimal simulation. This will be explored in detail in later chapters, but a very short script is enough to confirm the run time environment:

python

import opengate as gate
# create an empty simulation
sim = gate.Simulation()
# set a very small number of events
sim.number_of_threads = 1
sim.run(1)

Save this in a file called test_gate.py and run it from the terminal:

bash

python test_gate.py

If the installation is correct, the program should start, run a tiny simulation, print some basic information in the terminal, and exit without errors. The exact messages are not important at this stage, only that the run completes.

Once you are comfortable that importing works and a trivial simulation can run, you can move on to the dedicated chapter on verifying the installation, where you will run and explore a more structured example.

Always test your GATE installation with a small simulation before starting a long or complex run. If there is an installation or environment problem, it is much better to discover it in a one event test than after hours of computation.

2.3. Installing GATE

Installing OpenGATE

Installing required packages

Checking the installation

Comments

Where to Move