5. Configuring a new platform

5.1. Software/Operating System Prerequisites

The following are the external system and software requirements for installing and running MR Weather Application.

  • UNIX style operating system such as CNL, AIX, Linux, Mac
  • Python = 2.7
  • Perl 5
  • Git client (1.8 or greater)
  • Fortran compiler with support for Fortran 2003
  • C compiler
  • MPI
  • NCEPLIBS-external (includes ESMF)
  • NCEPLIBS
  • CMake 3.15 or newer

Note that NCEPLIBS-external and NCEPLIBS reside in separate GitHub repositories. NCEPLIBS-external is a collection of third-party libraries required to build NCEPLIBS, which contains the NCEP library source code and utilities required for chgres_cube, the UFS Weather Model, and UPP. NCEPLIBS-external must be installed before building the NCEPLIBS, and both are a prerequesite for porting CIME to a new platform. The NCEPLIBS-external and NCEPLIBS repositories each contain a wiki page with instructions. More details are in Section 5.2.

5.2. Generic MacOS or Linux platforms

CIME defines a generic build for MacOS using homebrewi and generic Linux machines. You must first install NCEPLIBS-external and NCEPLIBS following the instructions here.. Then you will need to set the environment variable NCEPLIBS_DIR pointing to the install location (/usr/local/ufs-release-v1). You will also need to define a root location for the model input and output data, again using environment variables. The following are suggestions:

  • UFS_INPUT    $HOME/projects
  • UFS_SCRATCH  $HOME/projects/scratch

Create these directories:

  • mkdir -p $HOME/projects/scratch
  • mkdir -p $HOME/projects/ufs_inputdata

You are now ready to build the ufs-mrweather-app as documented in the Workflow Quick Start. Use the optional –machine argument to create_newcase and create_test with value macos or linux.

5.3. Porting CIME to a new machine

This section describes the steps needed to port the CIME workflow to a new platform.

5.3.1. Add the new machine description to config_machines.xml

Edit the file $CIMEROOT/config/ufs/machines/config_machines.xml and add a new <machine/> entry under the root XML element. A good approach to this is to copy an existing <machine/> description and modify it to match the new machine to which you are porting CIME. An example entry looks like this:

Many of the XML elements above are self-explanatory. For details about individual elements see the config_machines.xml file section in the CIME documentation.

The value of CCSM_CPRNC will be set in the step below after the “cprnc” is installed on the system.

When finished, verify that your config_machines.xml file conforms to its schema definition:

cd $CIMEROOT
xmllint --noout --schema config/xml_schemas/config_machines.xsd config/ufs/machines/config_machines.xml

5.3.2. Add the batch system to config_batch.xml

Edit file $CIMEROOT/config/ufs/machines/config_batch.xml and add a <batch_system/> element describing the batch system on the new machine. Again, this can be done by copying an existing element and making any needed modifications. Here is an example batch description:

For more details see the config_batch.xml file description in the CIME documentation.

To verify correctness of the config_batch.xml file, use the command:

cd $CIMEROOT
xmllint --noout --schema config/xml_schemas/config_batch.xsd config/ufs/machines/config_batch.xml

5.3.3. (Optional) Build and install the “cprnc” tool

The CIME testing system uses a tool called cprnc to compare NetCDF files. This tool can either be built one time on a system and referenced from the config_machines.xml file or it will be built automatically by CIME if not found.

If you choose to build cprnc use these steps:

cd $CIMEROOT/tools/cprnc
CIMEROOT=../.. ../configure --macros-format=Makefile --mpilib=mpi-serial
CIMEROOT=../.. source ./.env_mach_specific.sh && make

You should now have a cprnc executable. Ideally, this executable will be moved to a shared location so that all users on the platform have access to the tool. Update $CIMEROOT/config/ufs/machines/config_machines.xml and set CCSM_CPRNC to the path of the cprnc executable.

5.3.4. Verify that the port is working by running a simple test

Once you have completed the above steps, run the following test to see if you are able to build and run a basic workflow with the UFS MR Weather App.

cd $CIMEROOT/scripts
./create_test SMS_Lh5.C96.GFSv15p2 --workflow ufs-mrweather --machine $MACHINE

The $MACHINE is the name of the machine that you added to the config_machines.xml.

This will attempt to run the full end-to-end workflow including pre-processing, model forecast, and post-processing.