Introduction

This tutorial walks you through combining Jinja2 and task parameterization in your suites. It assumes you are already familiar with using Jinja2. If not, see the Jinja2 tutorial.

By combining Jinja2 with task parameterization you can make use of further flexibility in generating your suite.rc.

Purpose

The purpose of this tutorial is to demonstrate some of the flexibility for suite design you can obtain by combining Jinja2 with parameterization. Using parameterization allows you to minimise the amount of graphing in your suite while using Jinja2 allows you some further flexibility and configurability on top of that.

Example

Here, we'll build on the "hello world" example suite from the parameterization section of the Suites I part of the user guide.

To start with, we will extend the suite so that a user can pass through a set of worlds to say hello to via an entry in the rose-suite.conf file.

Example (2)

To begin, create a new directory somewhere containing a suite.rc file that looks like this and an empty rose-suite.conf file.

This suite works through a list of parameters under world to run a hello_<world> task for each of them. Run the suite now to make sure you are happy you understand what it is doing. You may wish to alter the set of parameters to see what happens.

rose-suite.conf

To begin with, we'll alter our suite so that the user can change the list of suites to say "hello" to via the rose-app.conf file.

Add the following lines to your rose-suite.conf file:

[jinja2:suite.rc]
WORLDS=['eris', 'pluto', 'makemake', 'haumea']

rose-suite.conf (2)

Now, update the suite.rc's parameters section so it reads as:

    [[parameters]]
        world = {{ WORLDS | join(',') }}

This allows us to control the list of worlds to iterate over via the rose-suite.conf file. You should run your suite to confirm this has worked correctly, changing the entry in the rose-suite.conf to alter the list of worlds to say "hello" to.

Further Jinja2

Now we have access to a Jinja2 variable containing the parameters we'll be creating tasks for, we can make use of it to build some more functionality into our suite.

Further Jinja2 (2)

To begin with, update the runtime section so it looks like this:

[runtime]
    [[HELLO_FAMILY]]
        script = sleep 5; echo hello $WORLD
{% for world in WORLDS %}
    [[hello_{{ world }}]]
        inherit = HELLO_FAMILY
        [[[environment]]]
            WORLD = {{ world }}
{% endfor %}

Note the addition of an underscore between "hello" and {{ world }}. Tasks parameterisation had previously been automatically inserting it for us but because we're now using Jinja2 we have to specify it ourselves.

Further Jinja2 (3)

This change has Jinja2 handling our runtime settings while task parameterization is handling the graphing. Run your suite to confirm that the suite still runs the same as before.

Further Jinja2 (4)

We will now make use of a Jinja2 if statement to change the runtime behaviour of one of our tasks.

Update the Jinja2 loop in your suite.rc so it reads as:

{% for world in WORLDS %}
    [[hello_{{ world }}]]
        inherit = HELLO_FAMILY
        [[[environment]]]
        {% if world == 'pluto' %}
            WORLD = my favourite planet!
        {% else %}
            WORLD = {{ world }}
        {% endif %}
{% endfor %}

Further Jinja2 (5)

This change will make it so that the suite prints the message "Hello my favorite planet!" when it runs the hello_pluto task and print "Hello <world>" for all others. Run your suite now and examine the task job.out files to confirm this.

Summary

While this is a simple example, it demonstrates the sort of thing you can achieve by combining Jinja2 with task parameterization, allowing you to keep the graphing simple while making more complex changes in the runtime settings. Real world usage might relate to where you have settings which you want to change on a task-by-task basis that are dependent on, but not equal to, the parameter, for example changing walltime settings for different tasks.