Parallel Ensemble Forecast Package

License: MIT Codacy Badge Build Status codecov lifecycle Binder

This document is still under development.

About

Parallel Ensemble Forecast package uses a numerical weather prediction algorithm, called Analog Ensemble (AnEn), to generate ensemble forecasts. Ensemble members, also referred to as analogs, are selected based on the similarity between the current multivariate forecasts and the historical forecasts. It has been successfully applied to forecasts of several weather variables, for example, short-term temperature and wind speed predictions.

This package contains several libraries and applications:

These packages are developed and tested on Linux and MacOS and not guaranteed on Windows.

Requirement and Dependencies

A list of requirement and dependency is provided below. Note that you don’t necessarily have to install them all before installing the CAnEn library because some of them can be automatically installed during the make process, or because you may not want to install only parts of the modules.

Dependency Description
CMake Required for the C++ program.
GCC/Clang Required for the C++ program.
NetCDF-C Optional for the C++ program. If it is not found, the project will try to build it.
Boost C++ Optional for the C++ program. It is recommended to let the project build it for the C++ program.
CppUnit Required for the C++ program when building tests.
R Required for the R library.
OpenMP Optional for both R and C++.

On Mac

It is fairly straightforward to use HomeBrew to manage packages. However, note that HomeBrew might not be working well with Port. If you already have one of the two, go with the desired one.

# Install GNU compilers to support OpenMP
#
# brew search gcc
# 
# Select version from the output of the above command, I choose gcc-7 below.
#
brwe install gcc@7

# Install CMake
# brew search cmake
brew install cmake

# Install NetCDF
brew install netcdf

On Linux

If apt-get is available, please see the following commands.

# Install NetCDF
sudo apt-get install libnetcdf-dev netcdf-bin

Installation

C Programs and Libraries

The installation process can be divided into two steps:

First, let’s create a build/ folder where it stores our automatically generated files. This is also called an out-of-source build.

cd AnalogsEnsemble
mkdir build
cd build

Then, generate the make files.

cmake ..

# If you would like to change the default compiler, specify the compilers like this
#
# CC=[full path to CC] CXX=[full path to CXX] cmake ..

Read the output messages. If you would like to make any changes and generate new make files, please delete all the files in build/ folder first. Otherwise, you will not change anything.

Some of the components are by default turned off. Please refer to CMake Tunable Parameters Look-up for instructions for how to turn them on.

After having the make files generated, please go ahead and compile the programs and the libraries.

make

# Or if you are using UNIX system, use the flag -j[number of cores] to parallelize the make process
make -j4

# Build document if desired. The /html and the /man folders will be in your build directory
make document

After the compilation, the programs and libraries should be in the folder AnalogsEnsemble/output. For example, to print out the help messages for the program analogCalculator, open up a terminal and cd into the binary folder [Where you download the repository]/AnalogsEnsemble/output/bin/ and run the following command.

./analogGenerator 
# Analog Ensemble program --- Analog Generator
# Available options:
#  -h [ --help ]             Print help information for options.
#  -c [ --config ] arg       Set the configuration file path. Command line 
#                            options overwrite options in configuration file. 
# ...

If you want to clean up the folder, please do the following.

make clean

R Package

Please use the installation guide for updating the package as well. The process is the same.

Use Released Tarball File

Generally, the following R packages are needed:

Please run the following commands in R and make sure they succeed.

install.packages('Rcpp')
install.packages('BH')

If you are using Windows, please install the following programs:

The following command installs the latest version of RAnEn. Please run the following command in R.

install.packages("https://github.com/Weiming-Hu/AnalogsEnsemble/raw/master/RAnalogs/releases/RAnEn_latest.tar.gz", repos = NULL)

If you want to install a specific version of RAnEn, you can go to the release folder, copy the full name of the tarball file, replace the following part [tarball name] (including the square bracket) with it, and run the following command in R.

install.packages("https://github.com/Weiming-Hu/AnalogsEnsemble/raw/master/RAnalogs/releases/[tarball name]", repos = NULL)

Or, you can download the latest tarball file from the release folder. That is the package file you need to install inside R later. If you have already downloaded this repository, you can also find the release package tarball file under the folder [Where you downloaded this repository]/AnalogsEnsemble/RAnalogs/releases. Then, open an R session, and run the following command.

# The quiet option is to reduce the amount of standard output. Switch the parameter
# if you prefer to see the full list of warnings
#
install.packages("[full path to the tarball file]", type = "source", repos = NULL, quiet = T)

# On Windows, please separate folder names with `//`.
# For example, the full path to the tarball file on a Windows should look similar to this
# C://Users//yourName//Downloads//RAnEn_3.0.6.tar.gz

If you want to use a different compiler, an easy workaround is to create a Makevars file under ~/.R, with the following content.

CXX1X=[C++11 compiler]

# required on Mac OS
CXX11=[C++11 compiler]

After this, you should see the same compiler in the standard output.

Compile from Source

First, let’s create a build/ folder where it stores our automatically generated files.

cd AnalogsEnsemble
mkdir build
cd build

Then, let’s generate the make files.

cmake -DINSTALL_RAnEn=ON -G "Unix Makefiles" ..

Read the output messages. If you would like to make any changes and generate new make files, please delete all the files in build/ folder first. Otherwise, you will not change anything because of the existed files.

After the make files have been generated, go ahead and install the R package.

make

The following command installs the R package.

make install

Clean up the files after the make process.

make clean-rsrc
make clean-roxygen
make clean

CMake Tunable Parameters Look-up

Parameter Explanation Default
CC The C compiler to use. [System dependent]
CXX The C++ compiler to use. [System dependent]
INSTALL_RAnEn Build and install the RAnEn library. OFF
BOOST_TYPE BUILD for building Boost library; SYSTEM for using the Boost library installed on the system. BUILD
CPPUNIT_TYPE BUILD for building CppUnit library; SYSTEM for using the CppUnit library from the system. BUILD
CMAKE_BUILD_TYPE Release for release mode; Debug for debug mode. Release
CMAKE_BUILD_TESTS Build tests. OFF
BUILD_NETCDF Build NetCDF library regardless of its existence. OFF
BUILD_HDF5 Build HDF5 library regardless of its existence. OFF
VERBOSE Print detailed messages during the compiling process. OFF
CODE_PROFILING Print time profiling information. OFF
BUILD_GRIBCONVERTER Build the GRIB Converter utility. Eccodes library required. ON

Known Issues

Please see known issues in this post. If you could not find solutions to your issue, you can consider open a ticket or comment below the post. Thank you.

Feedbacks

We appreciate collaborations and feedbacks from users. Please contact maintainer Weiming Hu through weiming@psu.edu, or create tickets if you have any problems.

Thank you!

# "`-''-/").___..--''"`-._
#  (`6_ 6  )   `-.  (     ).`-.__.`)   WE ARE ...
#  (_Y_.)'  ._   )  `._ `. ``-..-'    PENN STATE!
#    _ ..`--'_..-_/  /--'_.' ,'
#  (il),-''  (li),'  ((!.-'
# 
# Authors: 
#     Weiming Hu <weiming@psu.edu>
#     Guido Cervone
#
# Contributors: 
#     Laura Clemente-Harding
#     Martina Calovi
#         
# Geoinformatics and Earth Observation Laboratory (http://geolab.psu.edu)
# Department of Geography and Institute for CyberScience
# The Pennsylvania State University