Rose Suite Configurations
Note
The following documentation reflects installing and running a Cylc workflow, and assumes that you have Cylc and the Cylc Rose plugin installed.
To check:
$ cylc version --long
8.0.0 (/path/to/install)
Plugins:
cylc-rose 1.0.0 ~/cylc-rose
...
Rose application configurations can be used to encapsulate the environment and resources required by a Cylc task.
Similarly Rose suite configurations can be used to do the same for a workflow.
Configuration Format
A Rose suite configuration is a Cylc source directory containing a
rose-suite.conf
file.
The rose-suite.conf
file is written in the same
format as the
rose-app.conf
file. Its main configuration sections are:
rose-suite.conf[env]
Environment variables for use by the workflow scheduler.
rose-suite.conf[template variables]
Generic variables for use in the
flow.cylc
file.rose-suite.conf[file:NAME]
Files and resources to be installed in the run directory when the suite is run.
Note
At Rose 2/Cylc 8, using the rose-suite.conf[template variables]
section is the recommended way of working. Cylc will select a templating
language based on the hashbang line at the start of the the flow.cylc
file.
At Rose 2019/Cylc 7, these variables were instead set in sections called
rose-suite.conf[jinja2:suite.rc]
and
rose-suite.conf[empy:suite.rc]
. These are still supported
to ease the transition to Rose 2, but should not be used for new
suite configurations.
In the following example the template variable WORLD
is set in
the rose-suite.conf
file.
This can then be used in the flow.cylc
file:
[template variables]
WORLD=Earth
#!jinja2
[scheduling]
[[graph]]
R1 = hello_{{ WORLD }}
[runtime]
[[hello_{{ WORLD }}]]
script = echo "hello {{ WORLD }}"
Using a Rose workflow configuration with Cylc 8
See also
This section acts to demonstrate how Cylc 8 can be used to install Rose configurations for Cylc workflows. It is not designed to comprehensively explain the usage of Cylc.
Rose configurations are installed alongside Cylc workflows by
cylc install, if a rose-suite.conf
file is present.
# Assuming that the example above was developed in ~/cylc-src/my-workflow
cylc validate my-workflow # Checks that the workflow configuration is valid
cylc install my-workflow # Installs workflow to ~/cylc-run/my-workflow
cylc play my-workflow # Plays the workflow.
cylc config my-workflow # Look at the workflow with template vars filled in.
Practical
In this tutorial we will create a Rose Suite Configuration for the weather-forecasting workflow.
Create a new Cylc workflow
Create a copy of the weather-forecasting workflow by running:
rose tutorial rose-suite-tutorial ~/cylc-src/rose-suite-tutorial cd ~/cylc-src/rose-suite-tutorial
Tip
If you haven’t ever used Cylc 8 you may need to create the source directory. (
mkdir ~/cylc-src
)Create a Rose suite configuration
Create a blank
rose-suite.conf
file:touch rose-suite.conf
You now have a Rose suite configuration. A
rose-suite.conf
file does not need to have anything in it.There are three things defined in the
flow.cylc
file which it might be useful to be able to configure:station
The list of weather stations to gather observations from.
RESOLUTION
The spatial resolution of the forecast model.
DOMAIN
The geographical limits of the model.
Define these settings in the
rose-suite.conf
file by adding the following lines:[template variables] station="camborne", "heathrow", "shetland", "aldergrove" RESOLUTION=0.2 DOMAIN=-12,48,5,61
Note that template variable strings must be quoted.
Tell the workflow what language to use when templating
Add a hashbang line to the flow.cylc file to tell it to use Jinja2 to process template variables:
+ #!jinja2 [scheduler] UTC mode = True
Write suite metadata
Create a
meta/rose-meta.conf
file and write some metadata for the settings defined in therose-suite.conf
file.station
is a list of unlimited length.RESOLUTION
is a “real” number.DOMAIN
is a list of four integers.
Solution
[template variables=station] length=: [template variables=RESOLUTION] type=real [template variables=DOMAIN] length=4 type=integer
Validate the metadata:
rose metadata-check -C meta/
Open the rose config-edit GUI. You should see suite conf in the panel on the left-hand side of the window. This will contain the template variables we have just defined.
Use suite variables in the
flow.cylc
fileNext we need to make use of these settings in the
flow.cylc
file.We need to change the
RESOLUTION
andDOMAIN
settings in the[runtime][root][environment]
section which would otherwise override the variables we have just defined in therose-suite.conf
file, like so:[runtime] [[root]] # These environment variables will be available to all tasks. [[[environment]]] # The dimensions of each grid cell in degrees. - RESOLUTION = 0.2 + RESOLUTION = {{ RESOLUTION }} # The area to generate forecasts for (lng1, lat1, lng2, lat2). - DOMAIN = -12,48,5,61 # Do not change! + DOMAIN = {{ DOMAIN | join(", ") }}
We have written out the
DOMAIN
list using the Jinja2join
filter to write the commas between the list items. We can do the same forstation
:[scheduler] UTC mode = True [task parameters] # A list of the weather stations we will be fetching observations from. - station = camborne, heathrow, shetland, aldergrove + station = {{ station | join(", ") }} # A list of the sites we will be generating forecasts for. site = exeter
Install the workflow
This workflow is not ready to play yet but you can check that it is valid with cylc validate:
cylc validate .
You can then install the workflow with cylc install:
cylc install rose-suite-tutorial
Inspect the installed workflow, which you will find in the run directory, i.e:
~/cylc-run/rose-suite-tutorial
You should find all the files, plus the
log
directory, contained in the run directory.
Rose Applications In Rose Suite Configurations
In Cylc workflows, Rose applications are placed in an app/
directory which
is copied across to the run directory with the rest of the suite by
cylc install when the workflow configuration is installed.
When we run Rose applications from within Cylc workflows we use the rose task-run command rather than the rose app-run command.
When run, rose task-run searches for an application with the
same name as the Cylc task in the app/
directory.
The rose task-run command also interfaces with Cylc to provide a few useful environment variables (see the command-line reference for details). The application will run in the work directory, just like for a regular Cylc task.
In this example the hello
task will run the application located in
app/hello/
:
[runtime]
[[hello]]
script = rose task-run
[command]
default=echo "Hello World!"
The name of the application to run can be overridden using the --app-key
command-line option or the ROSE_TASK_APP
environment variable. For
example the greetings
task will run the hello
app in the task defined below.
[runtime]
[[greetings]]
script = rose task-run --app-key hello
Practical
In this practical we will take the forecast
Rose application
that we developed in the Metadata Tutorial
and integrate it into the weather-forecasting workflow.
Move into the workflow source directory from the previous practical:
cd ~/cylc-src/rose-suite-tutorial
You will find a copy of the forecast
application located in
app/forecast
.
Create a test configuration for the
forecast
application.The
forecast
application comes with test data (infile/test-date
), and is currently set up to work with this data.We will now adjust this configuration to make it work with real data generated by the Cylc workflow. It is useful to keep the ability to run the application using test data, so we won’t delete this configuration. Instead we will move it into an Optional Configuration so that we can run the application in “test mode” or “live mode”.
Optional configurations are covered in more detail in the Optional Configurations Tutorial. For now all we need to know is that they enable us to store alternative configurations.
Create an optional configuration called
test
inside theforecast
application:mkdir app/forecast/opt touch app/forecast/opt/rose-app-test.conf
This optional configuration is a regular Rose configuration file. Its settings will override those in the
rose-app.conf
file if requested.Tip
Take care not to confuse the
rose-app.conf
androse-app-test.conf
files used within this practical.Move the following environment variables from the
app/forecast/rose-app.conf
file into an[env]
section in theapp/forecast/opt/rose-app-test.conf
file:WEIGHTING
WIND_CYCLES
WIND_FILE_TEMPLATE
RAINFALL_FILE
MAP_FILE
CYLC_TASK_CYCLE_POINT
RESOLUTION
DOMAIN
Solution
The
rose-app-test.conf
file should look like this:[env] WEIGHTING=1 WIND_CYCLES=0 WIND_FILE_TEMPLATE=test-data/wind_{cycle}_{xy}.csv RAINFALL_FILE=test-data/rainfall.csv MAP_FILE=map.html CYLC_TASK_CYCLE_POINT=20171101T0000Z RESOLUTION=0.2 DOMAIN=-12,48,5,61
Run the application in “test mode” by providing the option
--opt-conf-key=test
to the rose app-run command:mkdir app/forecast/run cd app/forecast/run rose app-run --opt-conf-key=test -C ../ cd ../../../
You should see the stdout output of the Rose application. If there are any errors they will be marked with the
[FAIL]
prefix.Integrate the
forecast
application into the suite.We can now configure the
forecast
application to work with real data.We have moved the map template file (
map-template.html
) into theforecast
application so we can delete theMAP_TEMPLATE
environment variable from the[runtime]forecast
section of theflow.cylc
file.Copy the remaining environment variables defined in the
forecast
task within theflow.cylc
file into therose-app.conf
file of theforecast
application, replacing any values already specified if necessary. Remove the lines from theflow.cylc
file when you are done.Remember, in Rose configuration files:
Spaces are not used around the equals (
=
) operator.Ensure the environment variables are not quoted.
The
[env]
section of yourrose-app.conf
file should now look like this:[env] INTERVAL=60 N_FORECASTS=5 WEIGHTING=1 MAP_TEMPLATE=map-template.html SPLINE_LEVEL=0 WIND_FILE_TEMPLATE=$CYLC_WORKFLOW_WORK_DIR/{cycle}/consolidate_observations/wind_{xy}.csv WIND_CYCLES=0, -3, -6 RAINFALL_FILE=$CYLC_WORKFLOW_WORK_DIR/$CYLC_TASK_CYCLE_POINT/get_rainfall/rainfall.csv MAP_FILE=${CYLC_TASK_LOG_ROOT}-map.html
Finally we need to change the
forecast
task to run rose task-run. The[runtime]forecast
section of theflow.cylc
file should now look like this:[[forecast]] script = rose task-run
Make changes to the configuration.
Open the rose config-edit GUI and navigate to the suite conf > template variables panel.
Change the
RESOLUTION
variable to0.1
Navigate to the forecast > env panel.
Edit the
WEIGHTING
variable so that it is equal to the following list of values:0.7, 0.2, 0.1
Tip
Click the “Add array element” button (+) to extend the number of elements assigned to
WEIGHTING
.Finally, save these settings via File > Save in the menu.
Run the workflow.
Validate, install, run and examine the workflow (use The Cylc GUI or The Cylc TUI):
cylc validate ~/cylc-src/rose-suite-tutorial cylc install rose-suite-tutorial cylc play rose-suite-tutorial
View output in Cylc Review.
Note
cylc review
replaces the Rose Bush utility. It is a Cylc 7 command that can view Cylc 7 and Cylc 8 workflows.Either navigate to your site’s Cylc Review page if one has been set up, or start a Cylc Review server by running the following command and open the printed URL:
cylc review start
Navigate to your latest rose-suite-tutorial run and click the “task jobs list”. On this page you will see the tasks run by the suite, ordered from most to least recent. Near the top you should see an entry for the
forecast
task. On the right-hand side of the screen click job-map.html.As this file has a
.html
extension Cylc Review will render it. The raw text would be displayed otherwise.