Quick Start Guide for LFRic

The LFRic repository includes some small applications for testing and training purposes. In particular, the simple_diffusion app is used in LFRic training courses and the skeleton app is designed to be an extremely simple and minimal LFRic app.

A separate lfric_apps repository holds key science applications, such as lfric_atm. The lfric_apps repository has a different set of instructions for building and testing apps, but largely they do the same thing.

Check-out a working copy

To checkout a working copy of the code to a new directory, named trunk in this example, run this command:

fcm co https://code.metoffice.gov.uk/svn/lfric/LFRic/trunk trunk

FCM Keywords

Users of FCM may take advantage of its support for keywords to shorten this.

Met Office developers should find they can use a site-wide keyword lfric.x

fcm co fcm:lfric.x-tr lfric_core_trunk

Those without these site-wide keywords can set up their own locally. In ~/.metomi/fcm/keyword.cfg just add the following lines:

# LFRic repository
location{primary}[lfric] = https://code.metoffice.gov.uk/svn/lfric/LFRic

You may now use the shortened URL:

fcm co fcm:lfric-tr

If keywords are set up, to create a branch and check it out, run the following:

fcm bc MyBranchName fcm:lfric.x-tr

The command will create a branch with your chosen name prefixed by the revision number of the head of trunk. Assuming the current trunk revision is 1234, the branch will be called r1234_MyBranchName. The following checks the code out and puts it into a directory called a working copy.

fcm co r1234_MyBranchName [working_copy_name]

If the working copy name is not specified, it defaults to the name of the branch.

Building an application

The applications can be found in directories within the application directory. An application can be built by running the make command from within its directory.

cd r1234_MyBranchName/applications/simple_diffusion
make

The make command will build the simple_diffusion executable and place it in the simple_diffusion/bin directory. It will also build and run any integration and unit tests that the application has. The make command uses the Makefile in the same directory as the application. The Makefile has a number of optional arguments:

• make build builds just the application executable.

• make unit-tests builds and runs any the unit tests.

• make integration-tests builds and runs any integration tests.

Warning

Instructions for command-line building of an application from the lfric_apps repository, such as the lfric_atm atmosphere model, are different:

https://code.metoffice.gov.uk/trac/lfric_apps/wiki/local_builds

The method is different because it needs to include steps to import external code, including the LFRic core code.

The Makefile has a number of optional variable settings that can be overridden. To see these, look in the file. More than one option can be supplied in a given invokation of make.

A few of the more commonly used variables are:

• make PROFILE=full-debug applies the set of full-debug compile flags rather than the default fast-debug settings.

• make PSYCLONE_TRANSFORMATION=my_transforms applies the my_transforms transformations to PSyclone-generated code instead of the default settings (which are, typically, either minimum or none). The my_transforms transformation scripts must be defined in the applications/[app-name]/optimisations directory. See PSyclone documentation for an explanation.

• make VERBOSE=1: The verbose option causes output of information from the dependency analyser, the compile command for each compilation process, and timings of these processes.

In addition to the bin directory that is created to hold the application executable, the build process creates a working directory to hold the products of an executable build and a test directory to hold products of a build of the unit and integration tests.

Running make clean will remove the working, test and bin directories.

After building an application from the command line, it can be useful to do a quick test to ensure it can run. Most applications in the lfric and lfric_apps repository hold a simple example configuration in their example directory.

After building, go into to the example directory and run the application, as follows:

../bin/simple_diffusion configuration.nml

The configuration.nml file contains a set of namelist configurations. Depending on the application, the example directory may contain other files required to run it such as a mesh definition file, a start dump or other input files.

Running the Cylc test suite

To run the test suites, Cylc and Rose need to be installed.

The rose stem command selects the group of tests to run. Then cylc play starts the suite running. For example, to run the developer tests for all the applications and components within an LFRic working copy, run the following from the top-level of the working copy:

rose stem --group=developer
cylc play <working_copy_name>