Derived Parameters in Unidata AWIPS on macOS

I have a really big post in the works about how I’m using Unidata’s fork of AWIPS II for weather stuff these days on my Macs. It has come a long way in a year, and I’m really digging it. (In fact, I have it up on a monitor at virtually all times at home these days as a situational awareness display.) In the meantime, I wanted to share an important finding on its own that may help a lot of struggling AWIPS users out there.

Why derived parameters are broken in Unidata AWIPS

One big shortcoming of the default AWIPS II install is that, at least on macOS and Windows, is that it cannot show things like wind barbs and vectors as well as many other computed parameters such as CAPE and even relative humidity. Attempts to do so are often met with a cryptic “Error executing Derived Parameter” message and a long Java stack trace. This error is due to the fact that a package called Jep is missing. A vast majority of people won’t have this installed as it’s a special package for running Python code within a Java application (which AWIPS II’s CAVE is).

Fortunately, this is fixable on macOS with the latest AWIPS II CAVE build (16.2.2 as of this writing), but it requires a few hoops.

The Fix

The steps below roughly mirror my configuration. It may not be for everyone, and there may be a more minimal way of going about this fix, but I had good success with this approach. May you have similar results!

Familiarity with the terminal and terminal commands is really helpful when working on this fix. The fix has been tested with OS X El Capitan and macOS Sierra.

What You Need

  • Latest AWIPS CAVE from Unidata. You really want to be running the latest AWIPS CAVE from Unidata — not only to fix this issue, but because the 16.2.2 build is far more stable and usable than anything that has preceded it.
  • Xcode. You will need Xcode installed from the Mac App Store to run the build tools that are needed to compile the module. This is a big download, but appears to be necessary based on my tests.
  • Homebrew and its version of Python. After installing Xcode, you’ll want to install Homebrew — it is a very useful tool for bringing in additional components quickly. Once Homebrew is installed, run brew install python numpy to pull in the prerequisites. Note: I am not 100% sure that the homebrew version of Python is absolutely needed. However, this is how I successfully resolved the issue, so I’m going to recommend it. It won’t touch your system Python, and it is perfectly easy to remove if it causes issues.
  • The Java Development Kit (JDK)This provides the Java compiler so that jep can be properly built. (Thanks, Kiel, for the heads up!)
  • Administrative access to your Mac. If this is your home machine, this is probably not an issue, but it may be one if you’re trying to do this on a machine that is managed by your organization. Seek assistance from your resident IT guru if needed.

Building jep

Now we’re ready to build jep. This is fairly painless. Take note, though: We must build jep version 3.4.1. Later versions of jep seem to crash CAVE completely when running derived parameters, which is suboptimal.

To get jep 3.4.1 installed, run this within a Terminal session:

pip install -I jep==3.4.1

This will produce the needed libjep.jnilib file in /usr/local/lib/python-2.7/site-packages/jep/. Change to that directory, then copy the file into the globally-available Java extensions directory. You’ll need to be root to do this, so use sudo:

sudo cp libjep.jnilib /Library/Java/Extensions

Hooray! One step down. Don’t open CAVE yet, though — there is one more thing to do.

Flipping the execute bit on jspawnhelper

The other piece of this puzzle was somewhat maddening but easy to fix once it became clear what was happening: CAVE 16.2.2 shipped with the execute bit turned off on jspawnhelper within its application bundle. This was causing any attempt to point CAVE to the local Python installation to go haywire — it was rejecting perfectly good Python interpreters because it couldn’t spin up the process to verify. Fortunately, this is an easy fix:

  • Go back to your Terminal.
  • Change into the directory for the CAVE application bundle’s JRE: cd /Applications/CAVE/cave.app/Contents/jre/lib
  • Then change the execute bit on jspawnhelper: chmod +x jspawnhelper

With any luck, subsequent releases of CAVE for macOS won’t have this problem. I’ve filed an issue with Unidata and it is being looked into.

Now, we’re ready to fire up CAVE and get it configured to talk to Python.

Configure CAVE for Python

After getting CAVE up and running, go to CAVE->Preferences to bring up the preferences window. Navigate to PyDev->Interpreters->Python Interpreter, then simply click the “Quick Auto-Config” button. With any luck, it will find and automatically configure Python for you with no additional intervention; once this is done, click Apply and then OK; CAVE will finish configuring Python.

Give it a shot!

With any luck, you’ll be able to plot wind barbs, vectors, and other fairly important meteorological data. Try it by loading the Sfc Temperature and Wind product from the GFS; you should see vectors show up nicely along with a temperature graphic, isotherms, and isobars.

GFS surface winds, temperatures, and pressures plotted in AWIPS II

GFS surface wind vectors, temperatures, and pressures plotted in AWIPS II.

This doesn’t fix all of it, though…

You’ll have much smoother sailing overall with CAVE now, but note that this doesn’t solve all of our woes. There are still issues loading the isentropic products from the models, for instance, as jep is looking for a module called gridslice which appears to be proprietary and not available. I’ve filed an issue with Unidata on GitHub that you can watch — with any luck, this will be fixed in the next CAVE release and you’ll be able to do isentropic analysis as well.

I’ll be interested to know how this fix works for everyone else in the community. Hopefully it helps make this very fascinating tool more usable — indeed, I’m having a harder and harder time going back to using model sites these days because I can load a smorgasbord of gridded data right into my local machine. If you run into trouble, reach out in the comments!