PyUtils

PyUtils is a small Python library of command line utilities for building GridTools on the CSCS machines (and elsewhere) and running tests. The main entrypoint is ./pyutils/driver.py. For help use ./pyutils/driver.py --help.

If you want to have console output, use ./pyutils/driver.py -v for basic info messages or ./pyutils/driver.py -vv for full verbose output. ./pyutils/driver.py --logfile /path/to/logfile enables full verbose logging to a file.

PyUtils require Python 3.6 or higher.

Use PyUtils Manually

Building GridTools with PyUtils

Simple build:

./pyutils/driver.py build --precision float --grid structured --build-type release --build-dir /path/to/build

Build with predefined environment for CSCS machines (here for Piz Daint + NVCC + GCC):

./pyutils/driver.py build -p float -g structured -b release -o /path/to/build --environment ./jenkins/envs/daint_nvcc_gcc.sh

If you pass an environment file using --environment, the path to this file is saved in the configured build and the environment will be automatically re-used when executing tests using the utilities described below.

Use ./pyutils/driver.py build --help for more command line options.

Running Tests with PyUtils

Use ./pyutils/driver.py test. This only works inside the build directory and requires GridTools built with PyUtils (using the GT_ENABLE_PYUTILS CMake variable).

MPI tests must be explicitly enabled with the --run-mpi-tests flag if desired. Further, building of the GridTools examples can also be enabled using --build-examples.

Check ./pyutils/driver.py test --help for all options.

Running Performance Tests with PyUtils

Use ./pyutils/driver.py perftest run --domain-size 128 128 80 --output /path/to/result. This only works inside the build directory and requires GridTools built with PyUtils (using the GT_ENABLE_PYUTILS CMake variable). This will generate one result file per enabled backend with a name like /path/to/result.BACKEND.json.

Plotting Performance Test Results with PyUtils

Use for example ./pyutils/driver.py perftest plot compare --input result.mc.json result.cuda.json --output comparison.png.

For details, see ./pyutils/driver.py perftest plot compare --help and ./pyutils/driver.py perftest plot history --help.

Run PyUtils-based Jenkins Scripts on CSCS machines

Instead of calling PyUtils manually, it is also possible to use the Jenkins execution scripts directly. They allow for less flexibility and run building and execution steps (and possibly plotting) in one go.

If you want to run Jenkins-equivalent tests on a CSCS machine, run the following (with adapted parameters):

label=daint real_type=float env=nvcc_gcc grid_type=structured build_type=release ./jenkins/run_tests.sh

If you want to run Jenkins-equivalent performance tests on a CSCS machine, run the following (with adapted parameters):

label=tave real_type=double env=gcc ./jenkins/run_perftests_PR.sh

PyUtils Environment Variables

To work around limitations of environment-based options in CMake and SLURM, PyUtils understands specially prefixed environment variables and will forward their values properly to CMake or SLURM.

• All environment variables starting with GTCMAKE_VAR=value will be forwarded to CMake with -DVAR=value.
• All environment variables starting with GTRUN_SBATCH_VAR=value will be forwarded to sbatch as --var=value.
• All environment variables starting with GTRUNMPI_SBATCH_VAR=value will override variables declared with GTRUN_SBATCH_VAR=value when running MPI tests.
• The command defined using GTRUN_BUILD_COMMAND=command will be called instead of make if set (for example to build on compute nodes).

Example:

export GTCMAKE_GT_ENABLE_BACKEND_CUDA=ON  # force compilation of CUDA backend
export GTRUN_SBATCH_PARTITION=debug       # run sbatch jobs on debug partition
export GTRUNMPI_SBATCH_PARTITION=normal   # override partition for MPI tests

See the predefined CSCS machine environments in ./jenkins/envs for more examples.

Python Virtual Environments for Testing on CSCS Machines

The Python virtual environments are located at /project/c14/jenkins/python-venvs. To update the virtual environment, first delete the directory of the machine (e.g. for Daint /project/c14/jenkins/python-venvs/daint). Then use:

python3 -m venv --copies /project/c14/jenkins/python-venvs/daint

To install the required packages in the venv, use:

source /project/c14/jenkins/python-venvs/daint/bin/activate
pip install -r pyutils/requirements.txt