1.3 UNIX - LINUX HYSPLIT install

Previous

HOME


Next

The Windows and Mac distributions come with all executables pre-compiled. However, for installation on a UNIX or LINUX system, the code must be compiled locally or pre-compiled binaries installed. See the HYSPLIT web page for more information about how to obtain either LINUX version. The remainder of this section discusses how to obtain and compile the source code from the repository.

  1. Similar to all pre-compiled versions, Windows, Mac, and LINUX, the prerequisite software should be installed prior to installing HYSPLIT. The graphical user interface requires Tcl/Tk. The native graphical format for HYSPLIT is Postscript, which can be viewed using Ghostscript. Postscript graphics are converted to other formats using ImageMagick. If not already available on your system, they may be easily installed using yum, apt, or brew. For some systems, just entering one of the commands, for instance wish for Tcl, gs for Ghostscript, or convert for ImageMagick will prompt the system to download and install the required libraries and software.

  2. After your registration has been accepted, you will have been sent access instructions to the source code with a username and password. In all cases, access is through a secure connection through port 8443. Passwords may be changed from time to time. Also you may need to install either SVN or WGET on your system to obtain the code. The first step is to decide which version of the code to install. The naming convention is hysplit.vX.Y.Z. In most circumstances this will be the most recent, which at the date this page was last edited was hysplit.v5.1.0. To see which versions are available:

  3. To download the source code and its directory structure in one command, use one of the following options with your assigned username (abc) and password (123):
    • svn --username abc --password 123 export https://svn.arl.noaa.gov:8443/svn/hysplit/tags/hysplit.vX.Y.Z
    • wget -r --reject "index.html" -nH --cut-dirs=1 --secure-protocol=auto --no-parent --no-check-certificate --user=abc --password=123 https://svn.arl.noaa.gov:8443/svn/hysplit/tags/hysplit.vX.Y.Z

  4. The download will copy all files into the hysplit.vX.Y.Z directory and then cd hysplit.vX.Y.Z to continue. The default distribution assumes the gfortran and gcc compilers are available and the NetCDF library is installed in the /usr/lib64 directory. NetCDF is only required if you are converting WRF-ARW data fields. All these defaults are assigned in the pre-edited versions of the Makefile.inc.{gfortran|intel} files. Copy the appropriate compiler version include file to Makefile.inc. Compilation settings for many other compilers can also be found in the file. After customizing Makefile.inc for your system, simply enter make and then make install to complete the installation.

  5. If your compilation fails during the initial make step, you will need to examine the log file to determine the nature of the failure. If the failure is due to the lack of one or more libraries, and you are only interested in the standard HYSPLIT compilation, that is a single processor trajectory (exec=hyts_std) or concentration (exec=hycs_std) calculation, then most of the failures can be bypassed by commenting out the offending sections in the individual Makefiles in one of the library or exec directories. Note the most common failure point will be in the /data2arl directory, which contains a variety of programs to convert meteorological data to the HYSPLIT compatible format. These programs require pre-installed libraries for NetCDF, GRIB2, ECCODES, or IOAPI. Other failures may be related to multi-processor applications, which can be disabled by commenting out any MPI related compilations.

  6. If you installed the MPICH libraries and compiled the MPI versions of HYSPLIT, make sure that you edit the script exec/conc_mpi.sh to insure that the path to mpirun is defined in the MPIPATH variable.

  7. To insure that the model has compiled correctly, go to the ./testing directory and execute ./xrun.scr. This script will sequence through a variety of simulations and the output graphics from each will be appended to a file called results.ps. These graphics can then be compared, frame-by-frame, with results.pdf. The script can also be used as a prototype to configure other simulations.

  8. Once the code is correctly installed, open a terminal window and change directory to ../hysplit/working. Then just execute the softlink ./hysplit.tcl and the GUI should open if Tcl/Tk has been installed. If the softlink does not exist (from the make install step), one should be created in the working directory using the command ln -s ../guicode/hysplit.tcl hysplit.tcl.

  9. Never run the model from the guicode directory. If using an X-window, insure that the X-directory location (usually /usr/X11/bin) in file default_exec points to the location of xterm, which can be determined from the command which xterm. Even if you are not planning on running the model through the GUI, create this step and open and then exit the GUI. Opening the GUI the first time will create all the basic control files required to run HYSPLIT. These can then be copied to other directories if desired. If the GUI fails to open the Postscript files, you may need to edit default_exec and change the Ghostview command from gs to display, or evince.

  10. As an alternative, instead of opening a terminal window to run HYSPLIT, a desktop icon can be created by running the script icon2desk.sh. Edit as appropriate for your system.

  11. Optional Python Emulator - A new class of display programs for trajectories and air concentration contours using the Python language has been developed. These programs are still undergoing modifications to their capabilities and interface requirements. To use them a Python emulator is required. If the Python display programs are provided with your HYSPLIT distribution, you will find detailed installation instructions in the python directory (e.g. install_linux.txt). More information about these displays can be found in the Python section. A system reboot may be required after installation.