Skip to main content

Getting started

Getting the tool​

The raytracer is not part of the PICMC installation and is not published for download. Fraunhofer IST provides it as a source archive or as a ready installation for the project environment; the version described here is 0.2.0.

If you are not sure which files you have, look for the directory containing the Makefile (source archive) or for an installed tree with build/libs/SRT.so next to the helper scripts init_venv and run_parallel (installation).

Requirements​

Building from the source archive needs:

  • Linux. The build scripts are Bash; there is no Windows build out of the box.
  • Python 3 with development headers and python3-config.
  • g++ with C++17 support.
  • GNU Make.
  • Optionally TBB (libtbb-dev). Recommended: without it the run is noticeably slower, but the results are identical.

Building​

cd substrate-ray-tracer # directory of the unpacked archive
make

The build produces build/libs/SRT.so and build/libs/SRTHelper.py. Then install into a directory of your choice:

INSTALLDIR=~/raytracer make install

make install also copies the two helper scripts init_venv and run_parallel.

If the build stops early, the two flags that resolve most cases:

# TBB not available — build without parallel execution (slower, same results)
NO_PARALLEL=1 make

# Python headers not found — point make at the right python-config
PYTHON_CONFIG_PATH=/usr/bin/python3.11-config make

For a fitting workflow you also need SciPy in the Python environment that runs the script. init_venv creates a virtual environment and installs it:

~/raytracer/init_venv ~/rtenv

Making the module importable​

The script has to find SRT.so. Either place it in a subdirectory of the working directory and import it by path, or put it on PYTHONPATH and import it by name:

# SRT.so sits in path/to/, relative to the script
import path.to.SRT as SRT

# SRT.so is in the working directory or on PYTHONPATH
import SRT as SRT
import SRTHelper as SRTHelper

Without one of these lines nothing in the raytracer is available, and the error message is a plain ModuleNotFoundError, not a raytracer message.

A minimal script that only checks that the module is alive:

import SRT as SRT

rt = SRT.Raytracer()
s = rt.get_substrate()
t = rt.get_trajectory()

print("Raytracer version:", rt.get_version())

Checking an installation you did not build​

Ask for the version before trusting a feature that is described here:

import SRT

print("Raytracer version:", SRT.Raytracer().get_version())

It has to read 0.2.0 or newer. An older number although a new installation was announced usually means that another SRT.so sits earlier in the load path (PYTHONPATH, working directory). If loading fails with failed to map segment from shared object, the library lies on a partition mounted noexec; move it to a normal filesystem.

Running on a cluster​

run_parallel writes a SLURM batch file and submits it. Only the path to the installation, the Python environment and the number of processes are needed:

~/raytracer/run_parallel -raytracerpath ~/raytracer -env ~/rtenv -n 32 myscript.py

The job writes its output files, a log and an error file into the directory it was submitted from. Nothing else has to be configured — the raytracer itself parallelises over substrate patches, so the process count is the only tuning knob on that side.