.. # JUBE Benchmarking Environment
# Copyright (C) 2008-2023
# Forschungszentrum Juelich GmbH, Juelich Supercomputing Centre
# http://www.fz-juelich.de/jsc/jube
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
.. index:: tutorial
JUBE tutorial
=============
.. highlight:: bash
:linenothreshold: 5
This tutorial is meant to give you an overview about the basic usage of *JUBE*.
.. index:: installation
Installation
~~~~~~~~~~~~
Requirements: *JUBE* needs **Python 3.2** (or any higher version)
If you plan to use *YAML* based *JUBE* input files, you have to add the `pyyaml` module ``_ to
your *Python* module library. Additionally the `ruamel.yaml` module ``_ is optional. If installed it is used to verify the validity of the *YAML* files.
To use the *JUBE* command line tool, the ``PYTHONPATH`` must contain the position of the *JUBE* package. This can be achieved in different ways:
* You can use the **installation script** to copy all files to the right position (preferred)::
>>> python setup.py install --user
This will install the *JUBE* package files and executables to your ``$HOME/.local`` directory. Instead of ``--user`` also a user
specific ``--prefix`` option is available. Here you might have to set the ``PYTHONPATH`` environment variable first
(this will be mentioned during the install process).
* You can utilize ``pip[3]`` to take care of the installation process (including the download) ::
>>> pip3 install http://apps.fz-juelich.de/jsc/jube/jube2/download.php?version=latest --user
# or
>>> pip3 install http://apps.fz-juelich.de/jsc/jube/jube2/download.php?version=latest --prefix=...
You might have to adjust your ``PYTHONPATH``.
* You can add the **parent folder path** of the *JUBE* package-folder (``jube2`` directory) to the ``PYTHONPATH`` environment variable::
>>> export PYTHONPATH=:$PYTHONPATH
* You can move the *JUBE* package by hand to an existing Python package folder like ``site-packages``
To use the *JUBE* command line tool like a normal command line command you can add it to the ``PATH`` environment variable::
>>> export PATH=$HOME/.local/bin:$PATH
To check your final installation, you can use
>>> jube --version
which should highlight the current version number.
.. index:: configuration
.. _configuration:
Configuration
~~~~~~~~~~~~~
The main *JUBE* configuration bases on the given input configuration file. But in addition, some
shell environment variables are available which can be used to set system specific options:
* ``JUBE_INCLUDE_PATH``: Can contain a list of paths (seperated by ``:``) pointing to directories, which contain
system relevant include configuration files. This technique can be used to store platform specific parameter
in a platform specific directory.
* ``JUBE_EXEC_SHELL``: *JUBE* normally uses ``/bin/sh`` to execute the given shell commands. This default shell can be changed
by using this environment variable.
* ``JUBE_GROUP_NAME``: *JUBE* will use the given *UNIX* groupname to share benchmarks between different users.
The group must exist and the *JUBE* user must be part of this group.
The given group will be the owner of new benchmark runs. By default (without setting the environment variable)
all file and directory permissions are defined by the normal *UNIX* rules.
*BASH* autocompletion can be enabled by using the ``eval "$(jube complete)"`` command. You can store the command in your bash profile
settings if needed.
.. index:: input format
.. _input_format:
Input format
~~~~~~~~~~~~
*JUBE* supports two different types of input formats: *XML* based files and *YAML* based files. Both formats support the same amount of *JUBE*
features and you can select your more preffered input format.
The following sections will always show all examples using both formats. However the explanations will mostly stick to the *XML* format but can be easily transfered
to the *YAML* solution.
Both formats depends on a specifc special scharacter handling. More details can be found in the following FAQ sections:
* :ref:`XML_character_handling`
* :ref:`YAML_character_handling`
Internally *JUBE* always uses the *XML* based format, by converting *YAML* based configuration files into *XML* if necessary. This is why parsing error messages might point
to *XML* errors even if the *YAML* format was used.
.. index:: hello world
Hello World
~~~~~~~~~~~
In this example we will show you the basic structure of a *JUBE* input file and the
basic command line options.
The files used for this example can be found inside ``examples/hello_world``.
The input file ``hello_world.xml``:
.. literalinclude:: ../examples/hello_world/hello_world.xml
:language: xml
The input file ``hello_world.yaml``:
.. literalinclude:: ../examples/hello_world/hello_world.yaml
:language: yaml
Every *JUBE* *XML* based input file starts (after the general *XML* header line) with the root tag ````.
This root tag must be unique. *XML* does not allow multiple root tags.
The first tag which contains benchmark specific information is ````. ``hello_world`` is
the benchmarkname which can be used to identify the benchmark (e.g. when there are multiple
benchmarks inside a single input file, or when different benchmarks use the same run directory).
The ``outpath`` describes the benchmark run directory (relative to the position of the input file).
This directory will be managed by *JUBE* and will be automatically created if it does not exist.
The directory name and position are very important, because they are the main interface to communicate
with your benchmark, after it was submitted.
Using the ```` you can store some benchmark related comments inside the benchmark directory.
You can also use normal *XML*-comments to structure your input-file:
.. code-block:: xml
In this benchmark a ```` is used to store the single ````.
The ``name`` of the parameter should contain only letters, numbers (should not be the first character) or the ``_`` (like a normal *Python* identifier).
The ``name`` of the parameterset must be unique (relative to the current benchmark). In further examples we
will see that there are more types of sets, which can be distinguished by their names. Also the ``name`` of the
parameter must be unique (relative to the parameterset).
The ```` contains the operation tasks. The ``name`` must be unique.
It can use different types of existing sets. All used sets must be given by name using the ``