- start-line:
1
Rose Stem Tutorial
Warning
Before proceeding you should already be familiar with the Rose Stem section.

This tutorial will walk you through creating a simple example of the Rose Stem testing system which will involve piloting a spaceship through space.
Getting Started
We will start the Rose Stem tutorial by setting up an FCM repository
called SPACESHIP
to store the code and test suite in.
Usually you would add a Rose Stem suite to an existing repository with the keyword already set up to test the accompanying source code. For the purposes of this tutorial we will create a new one.
Type the follow to create a temporary repository (you can safely delete it after finishing this tutorial):
mkdir -p ~/rose-tutorial
svnadmin create ~/rose-tutorial/spaceship_repos
(cd $(mktemp -d); mkdir -p trunk/src; svn import -m "" . file://$HOME/rose-tutorial/spaceship_repos)
We then need to link the project name SPACESHIP
with this project.
Creating the file and directory if they do not exist
add the following line to the file $HOME/.metomi/fcm/keyword.cfg
:
location{primary}[spaceship] = file:///home/user/rose-tutorial/spaceship_repos
Make sure the path on the right-hand side matches the location you
specified in the svnadmin
command.
Now you can checkout a working copy of your repository by typing:
mkdir -p ~/rose-tutorial/spaceship_working_copy
cd ~/rose-tutorial/spaceship_working_copy
fcm checkout fcm:spaceship_tr .
Finally populate your working copy by running (answering y
to the prompt):
rose tutorial rose-stem .
spaceship_command.f90
Our Fortran program is spaceship_command.f90
, which reads in an
initial position and spaceship mass from one namelist, and a series
of commands to apply thrust in three-dimensional space. It then uses
Newtonian mechanics to calculate a final position.
You will find it in the src
directory. Have a look at it and see
what it does.
The spaceship
app
Create a new Rose app called spaceship
:
mkdir -p rose-stem/app/spaceship
Paste the following configuration into a rose-app.conf
file within
that directory:
[command]
default=spaceship_command.exe
[file:spaceship.NL]
source=namelist:spaceship
[file:command.NL]
source=namelist:command
[namelist:spaceship]
mass=2.0
position=0.0,0.0,0.0
[namelist:command]
thrust(1,:) = 1.0, 0.0, 0.0, 1.0, 0.0, -1.0, -1.0, 0.0, 0.0, 0.0
thrust(2,:) = 0.0, -2.0, 0.0, 1.0, 1.0, 0.5, -1.0, 1.5, 0.0, -1.0
thrust(3,:) = 0.0, 1.0, 0.0, 1.0, -1.0, 1.0, -1.5, 0.0, 0.0, -0.5
The fcm-make
app
We now need to provide the instructions for fcm_make
to build the
Fortran executable.
Create a new app called fcm_make_spaceship
with an empty
rose-app.conf
file.
Inside this app create a subdirectory called file
and paste the following
into the fcm-make.cfg
file within that directory:
steps = build
build.source = $SOURCE_SPACESHIP/src
build.target{task} = link
The $SOURCE_SPACESHIP
environment variable will be set using the
Jinja2 variable of the same name which is provided by Rose Stem.
The flow.cylc
file
Next we will look at the rose-stem/flow.cylc
file.
The flow.cylc
file starts off with UTC mode = True
, which you
should already be familiar with.
The next part is a Jinja2 block which links the group names the user
can specify with the graph for that group. In this
case, the group command_spaceship
gives you the graph:
This variable name_graphs
is used later to generate the graph when
the suite is run. The Jinja2 variable groups
is next. This enables you
to set shortcuts to a list of groups, in this case specifying all
on the
command line will run the tasks associated with both command_spaceship
and fire_lasers
.
The scheduling section contains the Jinja2 code to use the information we have already set to generate the graph based on what the user requested on the command line.
The runtime section should be familiar. Note, however, that the
fcm_make_spaceship
task sets the environment variable
SOURCE_SPACESHIP
from the Jinja2 variable of the same name. This
is how the variables passed with --source
on the command line are
passed to fcm-make
, which then uses these environment variables in
its own configuration files.
The rose-suite.conf
file
The suites associated with Rose Stem require a version number
indicating the version of the rose stem
command with which they
are compatible. This is specified in the rose-suite.conf
file,
together with the default values of RUN_NAMES
and SOURCE_SPACESHIP
.
Paste the following into your rose-suite.conf
file:
ROSE_STEM_VERSION=1
[jinja2:suite.rc]
RUN_NAMES=[]
SOURCE_SPACESHIP='fcm:spaceship_tr@head'
Both of the Jinja2 variables will be overridden by the user when they
execute rose stem
on the command line.
The rose_ana_position
app
The final component is a rose_ana
app to test whether the position
of our spaceship matches the correct output.
Create an app named rose_ana_position
and paste the following into its
rose-app.conf
file.
[ana:grepper.FilePattern(Check X position at each timestep)]
pattern='^\s*Position:\s*(.*?)\s*,'
files=/home/user/spaceship/kgo.txt
=../spaceship/output.txt
[ana:grepper.FilePattern(Check Y position at each timestep)]
pattern='^\s*Position:.*?,\s*(.*?)\s*,'
files=/home/user/spaceship/kgo.txt
=../spaceship/output.txt
[ana:grepper.FilePattern(Check Z position at each timestep)]
pattern='^\s*Position:.*,\s*(.*)\s*$'
files=/home/user/spaceship/kgo.txt
=../spaceship/output.txt
This will check that the positions reported by the program match those within the known good output file.
Known Good Output
In the root of the working copy is a file called kgo.txt
.
The known good output should be the result of a control run. Rose Ana
will compare the answers from this file (obtained using the extract and
comparison methods in the rose-app.conf
file) with the results
from the user’s code change.
Replace the /home/user/spaceship
paths in the rose_ana_position
app with the path to this file.
Adding the suite to version control
Before running the suite we need to make sure that all the files and directories we have created are known to the version control system.
Add all the new files you’ve created using fcm add -c
(answer yes
to the prompts).
Running the test suite
We should now be able to install the test suite. Simply type:
rose stem --group=command_spaceship
anywhere in your working copy (the --source
argument defaults to .
so it should automatically pick up your working copy as the source).
We use --group
in preference to --task
in this suite (both are
synonymous) as we specify a group of tasks set up in the Jinja2 variable
name_graphs
.
Change from Rose 2019
Previously, the rose stem
command ran the suite. At Cylc 8, it simply
installs it.
We must now use cylc play
to start the workflow:
cylc play spaceship_working_copy
This can be inspected as running successfully by opening Cylc Review in a browser and checking the jobs. Alternatively, use the Cylc GUI or Cylc TUI to view the result of the run.
A failing test
Now edit the file:
rose-stem/app/spaceship/rose-app.conf
and change one of the thrusts, then rerun rose stem
and
cylc play spaceship_working_copy/run2
.
You will find the rose_ana_position
task fails, as the results have changed.
Inspecting the job.err
file:
cat $HOME/cylc-run/spaceship_working_copy/run2/log/job/1/rose_ana_position/01/job.err
explains the reason for the failed task: 1 test did not pass.
Try modifying the Fortran source code - for example, changing the direction
in which thrust is applied (by changing the acceleration to be subtracted
from the velocity rather than added). Again, rerun rose stem
, and
cylc play spaceship_working_copy/run3
and see the failure.
This time our job.err
file will indicate 3 failed tests.
In this way, you can monitor whether the behaviour of code is changed by any of the code alterations you have made.
Further Exercises
If you wish, you can try extending the suite to include the fire_lasers
group of tasks which was in the list of groups in the flow.cylc
file.
Using the same technique as we’ve just demonstrated for piloting the
spaceship, you should be able to aim and fire the ship’s weapons.
Automatic Options
It is possible to automatically add options to rose stem
using the
rose.conf[rose-stem]automatic-options
variable in the
Site And User Configuration file.
This takes the syntax of key-value pairs on a single
line, and is functionally equivalent to adding them using the -S
option on the rose stem
command line. For example:
[rose-stem]
automatic-options=GRAVITY=newtonian PLANET=jupiter
sets the variable GRAVITY
to have the value newtonian
, and
PLANET
to be jupiter
. These can then be used in the flow.cylc
file as Jinja2 variables.