Version 4.7 - Last Revision: November 20051
Abstract The HYSPLIT_4 (Hybrid Single-Particle Lagrangian Integrated Trajectory) Model installation, configuration, and operating procedures are reviewed. Examples are given for setting up the model for trajectory and concentration simulations, graphical displays, and creating publication quality illustrations. The model requires specially preformatted meteorological data. Programs that can be used to create the model's meteorological input data are described. The User's Guide has been restructured so that the section titles match the GUI help menu tabs. Although this guide is designed to support the PC and Unix versions of the program, the executable of the on-line web version is identical. The only differences are the options available through the interface.
Features
The HYsplit_4 (HYbrid Single-Particle Lagrangian Integrated Trajectory) model is a complete system for computing trajectories complex dispersion and deposition simulations using either puff or particle approaches.2 It consists of a modular library structure with main programs for each primary application: trajectories and air concentrations.
Gridded meteorological data, on one of three conformal (Polar, Lambert, Mercator) map projections, are required at regular time intervals. Versions 4.5 and higher also support computations on a regular latitude-longitude grid. The input data are interpolated to an internal sub-grid centered to reduce memory requirements and increase computational speed. Calculations may be performed sequentially or concurrently on multiple meteorological grids, usually specified from fine to coarse resolution.
Air concentration calculations require the definition of the pollutant's emissions and physical characteristics (if deposition is required). When multiple pollutant species are defined, an emission would consist of one particle or puff associated with each pollutant type. Alternately, the mass associated with a single puff may contain several species. The latter approach is used for calculation of chemical transformations when all the species follow the same transport pathway. Some simple chemical transformation routines are provided with the standard model distribution.
The dispersion of a pollutant is calculated by assuming either a Gaussian or Top-Hat horizontal distribution within a puff or from the dispersal of a fixed number of particles. A single released puff will expand until its size exceeds the meteorological grid cell spacing and then it will split into several puffs. An alternate approach combines both puff and particle methods by assuming a puff distribution in the horizontal and particle dispersion in the vertical direction. The resulting calculation may be started with a single particle. As its horizontal distribution expands beyond the meteorological grid size, it will split into multiple particle-puffs, each with their respective fraction of the pollutant mass. In this way, the greater accuracy of the vertical dispersion parameterization of the particle model is combined with the advantage of having an expanding number of particles represent the pollutant distribution as the spatial coverage of the pollutant increases and therefore a single particle can represent increasingly lower concentrations.
Air concentrations are calculated at a specific grid point for puffs and as cell-average concentrations for particles. A concentration grid is defined by latitude-longitude intersections. Simultaneous multiple grids with different horizontal resolutions and temporal averaging periods can be defined for each simulation. Each pollutant species is summed independently on each grid.
The routine meteorological data fields required for the calculations may be obtained from existing archives or from forecast model outputs already formatted for input to HYSPLIT. In addition, several different pre-processor programs are provided to convert NOAA, NCAR (National Center for Atmospheric Research) re-analysis, or ECMWF (European Centre for Medium-range Weather Forecasts) model output fields to a format compatible for direct input to the model. The model's meteorological data structure is compressed and in "direct-access" format. Each time period within the data file contains an index record that includes grid definitions to locate the spatial domain, check-sums for each record to ensure data integrity, variable identification, and level information. These data files require no conversion between computing platforms.
The modeling system includes a Graphical User Interface (GUI) to set up a trajectory, air concentration, or deposition simulation. The post-processing part of the model package incorporates graphical programs to generate multi-color or black and white publication quality Postscript printer graphics.
A complete description of all the equations and model calculation methods for trajectories and air concentrations has been published3 and it is also available on-line. The on-line and the version included with the PC installation contains all the most recent corrections and updates.
Pre-Installation Preparation
There are two installation programs that can be downloaded. The trial version (setup47U.exe - 25 Mb) available to anyone and a fully functional version (setup47R.exe - 15 Mb) that requires a user registration through the web site. Both versions identical, except the trial version will not work with forecast meteorological data files. In addition, several supplemental programs (Ghostview and Tcl/Tk) are packaged with the trial version for convenience. It is assumed that these would have already been installed when the registered version is installed on top of the trial version.
The self-installing executable contains only HYSPLIT related programs. No additional software is required to run a simulation if the command line interface is sufficient. To enable the model's GUI, the computer should have Tcl/Tk script language installed. The most recent version can be obtained over the Internet from or an older version is packaged with the trial version. The installation of Tcl/Tk will result in the association of the .tcl suffix with the Wish executable and all Hysplit GUI scripts will then show the Tk icon. The HYSPLIT GUI has been tested with Tcl/Tk version 8.3.2.
The primary HYSPLIT graphical display programs convert the trajectory and concentration model output files to Postscript format. The Postscript files can also be viewed directly through the GUI if Ghostscript and Ghostview have been installed. See for more information on the Postscript file viewer. The HYSPLIT code and GUI have been tested with Ghostscript 6.5 and Ghostview 3.6. Installation to different default drives, directories, or other versions might require editing the main GUI script's directory pointers (edit file: /guicode/hysplit4.tcl or the directory entry in the Advanced-Configuration-Directories menu tab.
The third optional GUI feature is the ability to convert the Postscript output file to a different graphical formats using ImageMagick. More information on this software can be found at The HYSPLIT code and GUI have been tested with ImageMagick 5.3. Similar to Ghostscript, installation to a different default drives or directories as suggested by the installation process may require editing the main GUI script's directory pointers. Proper functioning of the conversion software with Postscript files requires the installation of Ghostscript. Although the setup script tests for the default language, it is possible that installation to non-English default windows operating systems might require additional editing of the directory pointers.
Windows Installation (all operating systems)
HYSPLIT installation to a computer running Windows is provided through a self-installing file. Executables are installed in various directories for trajectories, dispersion, display and manipulation of results, and the creation of input meteorological data files. The trajectory and dispersion model source code is not provided. However all the Fortran source code to create meteorological data files in a format that the model can read are provided in the /source directory. Each subdirectory contains a @readme.txt file with more complete information about the contents of that directory.
During the installation you will be prompted as to the directory location. It is suggested you select a simple default location (such as C:/hysplit4). The installation program installs all code and executables to your selected directory, and creates a shortcut on the desktop to /guicode/hysplit4.tcl with the "Start In" directory as your selected default. You may have one of two versions of the installation program, setup46R, or setup46U. The suffixes R and U refer to the Registered or Unregistered versions. The two versions are almost identical, except that the unregistered (trial) version does not permit calculations with forecast meteorological data and certain archive data that just consist of a series of forecasts (such as the NGM). Further the trial version comes packaged with Tcl/Tk and Ghostscript/Ghostview. If these are already installed on your system, then just "Cancel" that installation step. Installing on top of an old version will bring up a "Continue" or "Cancel" prompt. It is not possible to rename the installation directory at this stage. Rename your old installation prior to installing the new code if you wish to keep the original version.
The following subdirectories will be created after the installation has completed:
arcview - Contains information about the program ascii2shp that converts a text file in generate format and produces an ArcView Shapefile that can be displayed by ArcExplorer.
bdyfiles - This directory contains an ASCII version of gridded land use, roughness length, and terrain data. The current file resolution is 360 x 180 at 1 degree. The upper left corner starts at 180W 90N. The files are read by both HYSPLIT executables, hymodelt (trajectory model) and hymodelc (concentration model), from this directory. If not found, the model uses default constant values for land‑use and roughness length. The data structure of these files is defined in the file ASCDATA.CFG, which should be located in either the model's startup directory or the /bdyfiles directory. This file defines the grid system and gives an optional directory location for the land‑use and roughness length files. These files may be replaced by higher resolution customized user-created files. However, regardless of their resolution, the model will only apply the data from these files at the same resolution as the input meteorological data grid. More information on the structure of these files can be found in the local @readme.txt file.
browser - Contains the Tcl/Tk source code required to run the HTML help browser through the GUI.
csource - Contains the dll files required to run the HELP browser and the Particle Viewer / Editor.
data2arl - Current forecast or archive meteorological data can be obtained from the ARL ftp server: ftp://gus.arlhq.noaa.gov /pub/archives (or /forecasts). Older archive data can be ordered from the NCDC (National Climatic Data Center). However if you have access to your own meteorological data or data formatted as GRIB (Gridded Binary), this directory contains various example decoder programs to convert meteorological data in various formats to the format (ARL packed) that HYSPLIT can read. Sample programs include GRIB decoders for ECMWF model fields, NCAR/NCEP (National Centers for Environmental Prediction) re-analysis data, and NOAA Aviation, ETA, and Regional Spectral Model files. All the required packing and unpacking subroutines can be found in the /source subdirectories. Sample compilation scripts for Compaq Visual Fortran 6.6 are in some of the decoder directories. More information on how to run these programs can be found in the Meteorology section.
concmdl - The directory contains the HYSPLIT air concentration prediction model scripts and sample control and configuration files. Although the model can be run through the GUI, at times it may be desirable to run the model from the command line (e.g. using automated scripts). The example Control file should produce some results for viewing. The sequence of commands would be ../exec/hymodelc to execute the model, and ../exec/concplot to create a Postscript file called concplot.ps. Command line arguments are required for concplot. See run_conc.bat for more detailed information. Normally the GUI is used to create the Control file for the simulation. If the file is missing, the model will prompt you for input from the keyboard. Your inputs are copied to a file called Startup. That file may then be edited and renamed to Control for subsequent simulations. .Conread and con2asc are provided as examples of how to read concentration files for users to develop other applications.
html - Contains all the HELP files in HTML format. These files can be displayed with any browser or interactively through the GUI. The files that are opened in the GUI depend upon the context from which HELP is invoked.
document - This directory contains PDF (Adobe Portable Document Format) versions of the User's Guide (all the HTML help files put together in one document) and other documentation such as ARL-224, the principal ARL Technical Memorandum describing the model and equations. This User's Guide (this document) provides detailed instructions in setting up the model, modifications to the Control file to perform various simulations and output interpretation. The @readme.txt file contains additional information about compilation, typical CPU times, and a summary of recent model updates.
exec - Is the directory that contains all the executable programs. The GUI looks for all programs in this directory. When running examples from the command prompt in certain directories, the relative path should be included prior to the executable: "../exec/program.exe"
grads - Contains source code and instructions for programs to convert meteorological data, concentration files, and trajectory files to a grads compatible format. Note that all executables reside in ../exec.
graphics - There are two types of graphical plotting programs provided in the ../exec directory. Publication quality graphics can be created using the postscript conversion programs, concplot and trajplot, which use a Fortran Postscript library created by Kevin Kohler4. All graphical routines use the map background file arlmap in this directory. The map background file uses a simple ASCII format and contains the world's coastal and political boundaries at relatively coarse resolution. Other higher resolution map background files are available in the /graphics/mapfiles directory or from the HYSPLIT download web page. All graphical programs search the startup directory first for arlmap before going to /graphics, therefore customized maps can be created without changing the HYSPLIT installation structure.
guicode - This directory contains a Tcl/Tk GUI interface source code script for HYSPLIT. The interface is used to set up the input Control file as well as run the graphical output display programs. To use the interface you must first install Tcl/Tk. The upper-level Tcl script is called hysplit4.tcl, which calls all other Tcl scripts. Executing this script starts the HYSPLIT GUI. The Desktop shortcut as well as the Start Menu options should point to this script. If the installation program did not properly setup the Desktop, you can manually create a shortcut to the script and edit its properties such that the "Start In" directory is /hysplit4. You should also select the HYSPLIT icon from the /icons directory.
metdata - This directory contains the sample meteorological data file: oct1618.BIN. It is an extract of the NGM (NOAA's Nested Grid Model) over the US from 0000 UTC 10/16/95 through 0000 UTC of 10/18/95. The file is used for all calculations shown in the User's Guide. Source code and compilation instructions are provided for the simple diagnostics program: chk_file. In addition, several additional executable programs are provided in /exec. These can be used to examine and display the meteorological data files. More information on these programs can be found in the " Meteorology" section.
source Contains the Fortran source code, and makefiles, to compile and create the subroutine library need for the example source code given in the various other directories.
trajmdlThis directory contains scripts, sample control and configuration files, for the HYSPLIT trajectory model (hymodelt). Although the model can be run through the GUI, at times it may be desirable to run the model from the command line (e.g. automated scripts). The example Control file should produce some results for viewing. The sequence of commands would be ../exec/hymodelt to execute the model, and ../exec/trajplot to create a Postscript file called trajplot.ps. See run_traj.bat for more detailed information. Normally the GUI is used to create the Control file for the simulation. If the file is missing, the model will prompt you for input from the keyboard. Your inputs are copied to a file called Startup. That file may then be edited and renamed to Control for subsequent simulations. A sample tcl script, Auto_traj.tcl, is provided as an example of how one might automate multiple trajectory calculations. The script creates the Control file and executes the model in a loop, varying specific parameters with each simulation.
utilities - Installation programs for Tcl/Tk, Ghostscript, and Ghostview may be found in this directory for the unregistered distribution. Otherwise this directory will be empty.
vis5d - Source code is supplied to convert Hysplit concentration files output for input to VIS5D.
working - This is the Hysplit4 root directory, which contains sample CONTROL files that can be used for initial guidance to set up more complex simulations. These should be loaded into the GUI from the approprate "Retrieve" menu tab. Examples include:
sample_conc - concentration simulation example from users guide
sample_traj - trajectory simulation example from users guide
back_conc - backward dispersion simulation for concentration
back_traj - backward trajectory simulation
volc_conc - particle settling simulation for a volcanic eruption
The "plants.txt" file contains a sample listing of starting locations that can be opened in the GUI to select from a list of previously determined starting locations. This file can easily be customized. The "tilelist.txt" file contains the approximate coordinates of NCEP's NAM (North America Mesoscale model) tile domains.
Problems
If Tcl/Tk does not exist on your system or there are other problems with the GUI interface, it is very easy to run the sample cases directly in either the /trajmdl or /concmdl sub-directories by running the batch file "run_{model}.bat" If the sample simulation works well, then it is only necessary to manually edit the Control file to try out different simulation variations. The Control file options are explained in more detail in the individual Trajectory and Concentration Setup sections.
In general, premature termination during the model initialization phase will result in messages to standard output. However after the model has started, fatal, diagnostic, and progress notification messages are written to a file called Message. If the model output is not what you expected, first check the Control file to determine if the input setup is what is desired, then check the Message file for indication of abnormal performance. These files are always written to the model's startup directory - /Hysplit4 if the model is run from the GUI. At times error messages may be lost in the display buffer after premature termination. In this case the model should be rerun from the command line window for proper display of all standard output messages. The "Advanced" menu contains a "Special File Display tab that can be used to select the Message file for viewing. Other features of the advanced menu are used to modify the model's configuration file and are explained in more detail in that section. Modifications to these parameters require a complete understanding of the model's design and operation.
References
[1]Draxler, R.R., 1999, HYSPLIT_4 User's Guide, NOAA Technical Memorandum ERL ARL-230, June, 35 pp.
[2]Draxler, R.R., and G.D. Hess, 1998, An overview of the Hysplit_4 modelling system for trajectories, dispersion, and deposition, Australian Meteorological Magazine, 47, 295-308.
[3]Draxler, R.R., and G.D. Hess, 1997, Description of the Hysplit_4 modeling system, NOAA Technical Memorandum ERL ARL-224, December, 24p.
[4]PSPLOT libraries can be found at www.nova.edu/ocean/psplot.html and were created by Kevin Kohler (kevin@ocean.nova.edu).