Rose Applications

The Cylc suite.rc file allows us to define environment variables for use by tasks e.g:

        script = echo "Hello ${WORLD}!"
            WORLD = Earth

As a task grows in complexity it could require:

  • More environment variables.
  • Input files.
  • Scripts and libraries.

A Rose application or “Rose app” is a runnable Rose configuration which executes a defined command.

Rose applications provide a convenient way to encapsulate all of this configuration, storing it all in one place to make it easier to handle and maintain.

Application Configuration

An application configuration is a directory containing a rose-app.conf file. Application configurations are also referred to as “applications” or “apps”.

The command to execute when the application is run is defined using the rose-app.conf[command]default setting e.g:

default=echo "Hello ${WORLD}!"

Environment variables are specified inside the rose-app.conf[env] section e.g:


Scripts and executables can be placed in a bin/ directory. They will be automatically added to the PATH environment variable when the application is run, e.g.:

echo "Hello ${WORLD}!"

Any static input files can be placed in the file/ directory.

Running Rose Applications

An application can be run using the rose app-run command:

$ rose app-run -q  # -q for quiet output
Hello Earth!

The Rose application will by default run in the current directory so it is a good idea to run it outside of the application directory to keep run files separate, using the -C option to provide the path to the application:

$ rose app-run -q -C path/to/application
Hello Earth!


In this practical we will convert the forecast task from the weather-forecasting suite into a Rose application.

Create a directory on your filesystem called rose-tutorial:

mkdir ~/rose-tutorial
cd ~/rose-tutorial
  1. Create a Rose application

    Create a new directory called application-tutorial, this is to be our application directory:

    mkdir application-tutorial
    cd application-tutorial
  2. Move the required resources into the application-tutorial application.

    The application requires three resources:

    • The bin/forecast script.
    • The lib/python/ Python library.
    • The lib/template/map.html HTML template.

    Rather than leaving these resources scattered throughout the suite directory we can encapsulate them into the application directory.

    Copy the forecast script and library into the bin/ directory where they will be automatically added to the PATH when the application is run:

    rose tutorial forecast-script bin

    Copy the HTML template into the file/ directory by running:

    rose tutorial map-template file
  3. Create the rose-app.conf file.

    The rose-app.conf file needs to define the command to run. Create a rose-app.conf file directly inside the application directory containing the following:

    default=forecast $INTERVAL $N_FORECASTS

    The INTERVAL and N_FORECASTS environment variables need to be defined. To do this add a rose-app.conf[env] section to the file:

    # The interval between forecasts.
    # The number of forecasts to run.
  4. Copy the test data.

    For now we will run the forecast application using some sample data so that we can run it outside of the weather forecasting suite.

    The test data was gathered in November 2017.

    Copy the test data files into the file/ directory by running:

    rose tutorial test-data file/test-data
  5. Move environment variables defined in the suite.rc file.

    In the [runtime][forecast][environment] section of the suite.rc file in the weather-forecasting suite we set a few environment variables:

    • MAP_FILE

    We will now move these into the application. This way, all of the configuration specific to the application live within it.

    Add the following lines to the rose-app.conf[env] section:

    # The weighting to give to the wind file from each WIND_CYCLE
    # (comma separated list, values should add up to 1).
    # Comma separated list of cycle points to get wind data from.
    # Path to the wind files. {cycle}, {xy} will get filled in by the
    # forecast script.
    # Path to the rainfall file.
    # The path to create the HTML map in.
    # The path to the HTML map template file.

    Note that the WIND_FILE_TEMPLATE and RAINFALL_FILE environment variables are pointing at files in the test-data directory.

    To make this application work outside of the weather forecasting suite we will also need to provide the DOMAIN and RESOLUTION environment variables defined in the [runtime][root][environment] section of the suite.rc file as well as the CYLC_TASK_CYCLE_POINT environment variable provided by Cylc when it runs a task.

    Add the following lines to the rose-app.conf:

    # The date when the test data was gathered.
    # The dimensions of each grid cell in degrees.
    # The area to generate forecasts for (lng1, lat1, lng2, lat2).
  6. Run the application.

    All of the scripts, libraries, files and environment variables required to make a forecast are now provided inside this application directory.

    We should now be able to run the application.

    rose app-run will run an application in the current directory so it is a good idea to move somewhere else before calling the command. Create a directory and run the application in it:

    mkdir run
    cd run
    rose app-run -C ../

    The application should run successfully, leaving behind some files. Try opening the map.html file in a web browser.