Skip to content

Obtaining and using the WRES as a standalone application

Jump to bottom
HankHerr-NOAA edited this page Jul 26, 2024 · 8 revisions

Table of Contents

When should I use the WRES standalone application?

If you have access to the Central OWP WRES (COWRES), almost never. There are many advantages of web services over locally installed programs. For example, new versions of the WRES will be distributed seamlessly and transparently to users of the COWRES without any interventions on their part (such as downloading the new version and installing it). Similarly, it is easier for us to support your use of the COWRES because we have access to all of the same information that you do and more (e.g., logs). In general, you will receive quicker and more accurate support when using the COWRES. Furthermore, the COWRES can retrieve time-series data from the Water Resources Data Service (WRDS), which cannot be used with the standalone application.

If you do not have access to the COWRES, we may be able to provide access. Failing that, you may consider using the WRES as a standalone application. You may also consider the WRES standalone application when you have a very large (e.g., multi-terabyte) dataset locally that is not available to the COWRES. However, for smaller datasets, you should consider posting the data to the COWRES using the “data direct” mechanism available to COWRES users (see Posting timeseries data directly to a WRES web‐service as inputs for a WRES job).

Where can I download the WRES standalone application?

Currently, the WRES application is available within this GitHub project. A zipped distribution for each WRES version is available from that version's "Assets" here:

https://github.com/NOAA-OWP/wres/releases

You should download the latest version of the software, which is contained in a .zip file following the naming pattern,

wres-[yyyymmdd]-[revision].zip

where [yyyymmdd] is a date and [revision] is a 7-letter revision identifier. No other files need to be downloaded to run the standalone application.

How can I validate the download?

You can find the checksum for a downloaded distribution .zip from the "Assets" for that same release in the file named sha256checksum.txt. Download the file, open it, and the checksum will be reported for the .zip you downloaded.

To validate a downloaded distribution, you will need the sha256sum program, which is pre-installed on most distributions of Linux and Cygwin (under Windows). You should compare the checksum you get locally with the checksum reported in the table for the corresponding version number. For example, to validate the artifact for v6.24, download the distribution, wres-20240701-5b07a6e.zip, from here:

https://github.com/NOAA-OWP/wres/releases/download/v6.24/wres-20240701-5b07a6e.zip

Once downloaded, navigate to the directory that contains the distribution and type this:

$ sha256sum wres-20240701-5b07a6e.zip
03e1438930dfab919158c0b426104681b3b92d058140c34e03ca8fe0539d77cf *wres-20240701-5b07a6e.zip

In the sha256checksum.txt file for that same release,

https://github.com/NOAA-OWP/wres/releases/download/v6.24/sha256checksum.txt

you will find the following checksum reported for the release .zip:

03e1438930dfab919158c0b426104681b3b92d058140c34e03ca8fe0539d77cf *wres-20240701-5b07a6e.zip

It matches, so we know we obtained the complete and correct file. If the numbers do not match, a problem likely occurred with the download and you should try again.

How do I install the WRES locally?

The distribution does not require any installation. Once downloaded, navigate to the directory that contains the zipped distribution and unzip it. Once unzipped, navigate to the bin directory where you will find two files:

wres
wres.bat

The wres file should be used to start the WRES standalone within a Unix-like operating system (e.g., Linux, Mac OS, Cygwin). The wres.bat is a Windows batch file and can be used to execute the WRES within a Windows OS.

While the WRES does not require installation, it does have one dependency. Specifically, the Java Runtime Environment (JRE) with major version 17 or higher should be installed and available locally. You can check this by typing the following at a command prompt:

$ java -version
openjdk version "11.0.17" 2022-10-18
OpenJDK Runtime Environment Temurin-11.0.17+8 (build 11.0.17+8)
OpenJDK 64-Bit Server VM Temurin-11.0.17+8 (build 11.0.17+8, mixed mode)

If the command is not found or the major version is lower than 17, as illustrated above, you will need to ask your system administrator to install the JRE 17 or higher.

What if I want to clone the repository and build the WRES for local use?

To build WRES for local use, clone the repository, and run the following commands in your preferred terminal from the root directory of the clone (use gradlew.bat on a Windows machine):

./gradlew check javadoc installDist

This is similar to unzipping the production distribution zip locally. The WRES software will be installed in build/install/wres directory, as if unzipped; specifically the same @wres@ and @wres.bat@ files will be found in the bin subdirectory.

Running an example evaluation using system testing data available in the cloned repository.

One advantage of using a clone is that a large number of system test scenarios are available as example evaluations. The simplest, and very small, example system test scenario with data in the repository is scenario500. Once the software has been installed locally, running the following command (use wres.bat on a Windows machine) will execute the scenario500 example using the executable you have created (this assumes you are running from the [WRES clone]/build/install/wres directory):

bin/wres ../../../systests/scenario500/evaluation.yml

Can I use the WRES standalone on an AWIPS machine?

No. However, the COWRES is available from RFC AWIPS machines; it has been whitelisted through the AWIPS Firewall. Hence, you should have no need to run the WRES as a standalone application within AWIPS; just use the COWRES.

How do I start the WRES?

A WRES standalone can be used to execute the WRES from the command-line, for a one-and-done evaluation, or to standup a long-running WRES local server. The instructions here are for a one-and-done evaluation. See WRES Local Server for how to run it as a local server.

From a command prompt, navigate inside the bin directory and, using the file appropriate to your operating system, simply type:

$ ./wres

(Or ./wres.bat for Windows.)

This (or equivalently wres -h or wres --help) will provide a list of the available commands and how to use them.

For example, if you want to run an existing WRES project contained in a project file, myproject.yml, type this:

$ ./wres myproject.yml

How do I increase the memory or change other settings?

You can override Java system properties by appending to the JAVA_OPTS environment variable. For example, to run an evaluation project, myproject.yml, with an increased amount of memory (e.g., 4028m), you can say this:

JAVA_OPTS="-Xmx4028m" ./wres myproject.yml

Can I run large evaluations in the WRES standalone application?

Yes, but how you do so will depend on the amount of data you need to evaluate and your machine specifications.

By default, the WRES application uses “in memory” mode, which means that the entire evaluation dataset must fit into main memory (RAM). If you need to increase the amount of memory available, see How do I increase the memory or change other settings?. If your evaluation is larger than the amount of memory you have available locally, then it is possible to configure the WRES with a database. Using a database will allow the WRES to read into memory the data required to compute a particular set of statistics only, which is generally much less than all of the data. However, configuring the WRES with a database requires significant extra effort and familiarity with installing and administering a database. You should contact the WRES Team for more information.

Can I get support for the WRES standalone application?

We will try our best. However, the WRES Team is small and we will prioritize users of the COWRES web services over users of the standalone application. The COWRES will always use the latest version of the WRES software and it is strongly preferred over the standalone, when you have access to COWRES. For support of the WRES standalone or COWRES web services, you should post a new ticket to GitHub. If possible, we would prefer that you write a short ticket describing your issue, rather than e-mailing the WRES Team.

National Weather Service (NWS) users should always post tickets to the WRES User Support VLab Project! Even if not using the COWRES, it is preferred that all NWS users use VLab to communicate issues.

The WRES Wiki

Home

Clone this wiki locally