Rose Applications

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

[runtime]
    [[hello_world]]
        script = echo "Hello ${WORLD}!"
        [[[environment]]]
            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:

[command]
default=echo "Hello ${WORLD}!"

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

[env]
WORLD=Earth

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.:

bin/hello

echo "Hello ${WORLD}!"

rose-app.conf

[command]
default=hello

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!

Practical

In this practical we will convert the forecast task from the weather-forecasting workflow in the Cylc tutorials into a standalone Rose application. By the end you will be able to run the application standalone (running it as a task in the workflow will come later).

Create a directory on your filesystem called rose-tutorial:

mkdir ~/rose-tutorial
cd ~/rose-tutorial

Create a Rose application

Create a new directory called application-tutorial, this is to be our application directory:
```
mkdir application-tutorial
cd application-tutorial
```
Provide the required resources in the application-tutorial application.

The application gets three resources from different places:
- The bin/forecast script.
- The lib/python/util.py Python library.
- The lib/template/map.html HTML template.
We will move all these resources into a single application directory.

This makes a rose application easier to maintain by keeping all the files required in the same place.

Install the forecast script and util.py library into the bin/ directory by running this command:
```
rose tutorial forecast-script bin
```
The bin/ directory will be automatically added to the PATH when the application is run.

Copy the HTML template into the file/ directory by running:
```
rose tutorial map-template file
```
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:
```
[command]
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:
```
[env]
# The interval between forecasts.
INTERVAL=60
# The number of forecasts to run.
N_FORECASTS=5
```
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 workflow.

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
```
Move environment variables defined in the flow.cylc file.

In the [runtime][forecast][environment] section of the flow.cylc file in the weather-forecasting workflow we set a few environment variables:
- WIND_FILE_TEMPLATE
- WIND_CYCLES
- RAINFALL_FILE
- MAP_FILE
- MAP_TEMPLATE
We will now add 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).
WEIGHTING=1
# Comma separated list of cycle points to get wind data from.
WIND_CYCLES=0
# Path to the wind files. {cycle}, {xy} will get filled in by the
# forecast script.
WIND_FILE_TEMPLATE=test-data/wind_{cycle}_{xy}.csv
# Path to the rainfall file.
RAINFALL_FILE=test-data/rainfall.csv
# The path to create the HTML map in.
MAP_FILE=map.html
# The path to the HTML map template file.
MAP_TEMPLATE=map-template.html
```
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 workflow we will also need to provide the DOMAIN and RESOLUTION environment variables that were defined in the [runtime][root][environment] section of the flow.cylc 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.
CYLC_TASK_CYCLE_POINT=20171101T0000Z
# The dimensions of each grid cell in degrees.
RESOLUTION=0.2
# The area to generate forecasts for (lng1, lat1, lng2, lat2).
DOMAIN=-12,48,5,61
```
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.