ParaTAXIS Workflow: How to create an own example

How to create an own example in ParaTAXIS

source ~/parataxis.profile
cd ~/parataxis/

Create a new directory in parataxis/examples/

mkdir examples/<newExample>

There are two options to run examples - automatically with the buildSystem and manually with the compileExampleSets.sh. The first method needs the documentation.yml inside <newExample. Copy it from an old example and change the YAML keys according to the documentation in parataxis/buildSystem/Documentation.md.

The documentation.yml will be used by the buildSystem/runTests.py to build the different cmake presets and run possible pre- and post-run commands. A minimal set of documentation looks like this:

# Description
example:
  name:        EUCALL M4.3 (Interoperable Simulations)
  author:      Marco Garten

  description: |
               Example for the EUCALL Project Milestone M4.3 that shows the interoperability of PIC, ParaTAXIS and WPG (if possible).

compile:
  - cmakeFlags:
        - 0

# Run-Time Tests
tests:
  - name: EUCALL
    description: Uses HDF5 files to interpolate the field between timesteps
    cmakeFlag: 0
    cfgFile:   0001gpusHDF5Field.cfg
    pre-run: echo "Pre"
    post-run: echo "Post"

Note that currently neither the pre-run nor post-run key can be left empty as they don't accept an empty list of commands. Just echo some output instead. The cmakeFlags key can contain a range of flags, like 0-3.

Copy the cmakeFlags to the <newExample> directory and change the flags as desired. Also add an include/simulation_defines/param/ directory with non-default parameter files if necessary. Add a submit directory if you need custom config and submit template files. Add testData if the simulation requires reading data during startup.

In order to build the example, type

python buildSystem/runTests.py -e examples/<newExample>/ -o ~/<runNewExample> -p ~/parataxis.profile --compile-only

If the compile process was successful the example can then be run by changing into the install directory and executing.

cd ~/<runNewExample>/installed/<exampleName>_cmake<number>/
tbg -s qsub -c submit/<numGPUs>gpus.cfg -t submit/hypnos-hzdr/k20_profile.tpl ~/<outPutDirectory>

(The template file here is just an example, of course)