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.