Hysplit User Guide
Hysplit User Guide
Hysplit User Guide
http://www.arl.noaa.gov/userguide/cover.htm12/5/2005 4:49:43 AM
HYSPLIT4 User's Guide Help File Index
GUI Overview
Meteorology Help
Display Options
Utility Program
● Convert to ASCII converts the binary concentration file to an ascii format file
● Grid to Station extracts the concentrations at a station and writes to a file
● Convert to IOAPI converts the concentration binary file to IOAPI
Concentration Help
FTP Satellite Data - Direct FTP access to selected satellite data archives
Advanced Help
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.
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.
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:
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.
GUI Overview
Although the model can be configured and run manually from the command line, it is usually much
quicker to use the GUI. A summary of the main features in each of the primary GUI menus is reviewed
below.
ARL Server - Links to only the most recent forecast data for a variety of different meteorological
models available on the ARL FTP server. The data have already processed to a HYSPLIT
compatible format.
ARL ASEAN - A special Asian region extract of the global model already converted into
HYSPLIT compatible format. This is a small file designed for download over low capacity
telecommunications links.
NCEP GFS - Accesses the global GFS model forecast fields on the NCEP FTP server in their
native GRIB format. Files are decoded and interpolated to the grid specified on the user’s PC. A
running archive can be maintained by only processing the 00 and +03 forecasts every 6 hours.
NCEP NAM - Processes forecast GRIB fields from the NCEP NAM model on the AWIPS 212
grid (40 km) or the AWIPS 218 grid (12 km) into ARL format. The GRIB files are downloaded
to the user’s computer and each time period is processed to construct one file. The data on the 12
km grid can be selected for only one tile per pass.
ARL Current - Links to only the most recent data archives for a variety of different
meteorological models available on the ARL FTP server. The data have already processed to a
HYSPLIT compatible format. Current data is defined as a combination of analysis and short
forecasts (e.g. 0h and +3h appended with each new 6h cycle) that are operationally maintained as
a rolling archive valid for 48 hours prior to the most recent forecast cycle.
ARL Archive - Access to a running archive of the last 48 hours of pseudo-analysis for a variety
of different meteorological models with data already processed in a HYSPLIT compatible
format. Provides access to the long-term data archives at ARL for the GFS/GDAS (formerly
FNL) and the NAM/NDAS (formerly EDAS) archives. Unless otherwise noted, most of the
archives go back to about 1995. This period may be shortened as more data are posted on-line
due to storage limitations.
NOAA Reanalysis - The NCAR/NCEP reanalysis data archived has been reformatted for
HYSPLIT and placed on the ARL ftp server. These data are available from 1948 through 2003.
This directory is only updated once-a-year.
NCEP GDAS - Accesses the global GFS model analysis (GDAS) fields on the NCEP FTP server
in their native GRIB format. Files are decoded and interpolated to the grid specified on the user’s
PC. A running archive, similar to that maintained on the ARL server, can be created locally by
processing the 00 and +03 forecasts every 6 hours.
NOMADS GDAS - Accesses the global GFS model analysis (GDAS) fields on the NCEP
NOMADS FTP server in their native GRIB format. Files are decoded and interpolated to the grid
specified on the user’s PC. Functionality is similar to the regular NCEP server access application
except the data archive is of longer duration.
NAM forecast - Processes forecast GRIB fields from the NCEP NAM model on the AWIPS 212
or 218 grids into ARL format. The GRIB files must already been downloaded to the user’s
computer. FTP to the server is not supported through this menu tab.
NDAS Archive - Archived GRIB fields from the NCEP’s NDAS model on the AWIPS 212 or
218 grids may be processed locally into ARL format. These files must already be present on the
local computer. FTP is not supported through this menu tab. The script is designed only to work
with archive data to create a multi-day file as long as one month, where the last four digits of the
file name represent the day and hour of the analysis. Downloaded files would have to be renamed
to work with this script.
GFS forecast - Forecast GRIB fields from NCEP’s global GFS model may be processed locally
on the PC into ARL format. These files must already be present. These are the same files
downloaded from the FTP menu tab, but the GRIB decoder in this menu provides more
conversion options. This procedure is designed only to work with forecast data. The last two
digits of the file name represent the forecast hour.
GDAS Archive - Archived GRIB fields from the NCEP GDAS model may be processed locally
into ARL format. These files must already be present. FTP is not supported. The procedure is
designed only to work with archive data, where the last four digits of the file name represent the
day and hour of the analysis. Previously downloaded files will have to be renamed to work with
this script.
ECMWF Forecast - Archive GRIB fields from the global model of ECMWF may be processed
locally into ARL format. These files must already be present. FTP is not supported. The
procedure is designed only to work with archive data from their current operational model, where
the last four digits of the file name represent the day
ECMWF Archive - Archive GRIB fields from the ERA-40 reanalysis may be processed locally
into ARL format. These files must already be present. FTP is not supported. The procedure is
designed only to work with the ERA-40 data files. Three different file types must be downloaded
for this converson: 3-d fields, 2-d surface fields, and one invariant field.
MM5V3 format - Output files from MM5V3 can be converted to ARL format. The script
automatically processes all domains (MMOUT_DOMAIN{X}) found in the selected directory.
User Entered Data - This menu tab is intended to convert user entered meteorological data to the
ARL packed HYSPLIT compatible format. The conversion program will create a data file with
one or more time periods containing a uniform field in space and height but varying in time. The
grid is centered over the location specified in the main menu and covers a 50 by 50 km domain.
Meteorology Display
Contour Map - A simple postscript contouring program that can be used to view the data fields in
any ARL packed meteorological data set. The output is always written to a file called contour.ps.
Multiple time periods may be processed.
Text Profile - This program is used to extract the meteorological data profile interpolated to a
user selected latitude-longitude position. The raw data values at the surface and each level are
output on the left while temperature converted to potential temperature and winds rotated from
grid orientation to true are shown on the right. Output is shown on the screen and is also written
to a file called profile.txt.
Grid Domain - Program to generate a map showing the domain of the meteorological data grid
with marks at each selected data grid point. Output is written to the file showgrid.ps.
Utility Programs
Convert Postscript - Converts any Postscript file to another format using ImageMagick. Enter the
name of the Postscsript file and the desired name of the output file, with the file suffix indicating
the desired conversion.
GIS to Shapefile - When the GIS output option is selected in selected display programs an ascii
text file (in generate format) is created that contains the latitude-longitude values of each contour.
This GIS text file can be converted to an ERSI Arc View shapefile. This menu tab is available
from three different points. From the meteorology tab the conversion is "line", from the trajectory
tab the conversion is "points", and from the concentration tab the conversion is "polygon".
Trajectory
Quick Start - menu tab can be used to run any simulation in one-step. The last configuration will
be used for the simulation. The menu brings up a global map with the current source location
shown as a blue dot which can be moved to a new location. The Run Example menu tab resets the
control and namelist files and reruns the example case. This can be used as a starting point for
configurations that have been corrupted.
Trajectory Setup - This menu is used to write the CONTROL file that defines all the model
simulation parameters. Note that once a simulation has been defined it can be "Saved As" and
later "Retrieved." Note that the setup must be "Saved" before proceeding to the "Run Model" step.
Run Standard Model - The selection opens the window for standard output and starts the
execution of "hymodelt.exe". Incremental progress is reported on WinNT and later systems,
however on Win95/98 the display remains frozen until the calculation has completed (a beep will
sound).
Trajectory Display - Display options are available to label the time increment along the trajectory
and the amount of white space surrounding the trajectory on the map. The HIRES option limits
the domain to just fit the trajectory. Output is written to the file trajplot.ps. The plot title can be
defined in a file called labels.cfg which should be placed in the \working directory.
Special Simulations - The Ensemble option invokes a special executable that will run multiple
trajectories from the same location, with each trajectory using meteorological data slightly offset
from the origin point. The Matrix option simultaneously runs a regular grid of trajectory starting
locations. Also available are multiple trajectory options in both time and space as well as a menu
to run a series of automated daily trajectories for as long as one month per execution.
Concentration
Quick Start - menu tab can be used to run any simulation in one-step or rerun the example
simulation. It's funtionality is similar to the trajectory quick start menu.
Concentration Setup - The menu is almost identical to the Trajectory Setup menu except for the
added tab for "Pollutant, Deposition, and Grids", which is used to customize the concentration
computation. Unlike trajectories, which are terminated at the top of the model domain, pollutant
particles reflect at the model top.
Utility Programs
Convert to ASCII - Writes an ASCII file for each time period of concentration output with one
record for every grid point that has a non-zero concentration value. Each record is identified by
the ending date and time of the sample and the latitude and longitude of each grid point. The
output file name is constructed from the name of the [input file]_[julian day]_[output hour].
Some other output options are available.
Grid to Station - This program is used to extract the time- series of concentration values for a
specific location. That location may be specified by a single latitude-longitude through the GUI
or multiple stations may be defined by entering the name of a file that contains an integer station
number, latitude, and longitude on each record. The output is written to con2stn.txt which can be
read by the time series plotting program to produce the file timeplot.ps. Note that the time series
plot is always in integer units and therefore may require the specification of a units multiplication
factor.
Advanced Topics
Contains several menus for custom model configurations that can be used to change the nature of
the simulation and the way the model interprets various input parameters. These menus would be
used to configure matrix, ensemble, simple pollutant transformations, and even special model
initialization options.
Table of Contents
Meteorology / Help
Meteorological data fields to run the model are usually already available or can be created from routine
analysis archives or forecast model outputs. Archive meteorological data to run the model may be
ordered from NOAA's National Climatic Data Center for the regional EDAS or global FNL archives.
More recent data files can be copied from ARL's server ftp://gus.arlhq.noaa.gov. There are more
complete descriptions of the different data sets available on-line. The meteorological data available
through the menu system are summarized in the following three sections.
The meteorology menu is divided into four sections: forecast data, analysis data, data conversion, and
data display. The forecast section provides access to various forecast data files that may be FTP'd from
the ARL server compatible for immediate input for HYSPLIT. North America Mesoscale (NAM) or
Global Forecast System (GFS) GRIB files can also be FTP'd from the NCEP server. These files must
first be converted from GRIB, which is accomplished automatically through the GUI. In addition, the
forecast menu tab also permits the processing of either NAM or GFS GRIB files that are local to the
computer. The GRIB decoding of local files has more menu conversion options than the FTP menu tab.
The analysis menu tab is similarly divided between FTP of files and files local to the computer. The only
FTP option for the analysis archives is from the ARL server for data files that are compatible with the
ARL forecasts and the NCAR/NCEP reanalysis data, which have already been converted for HYSPLIT
applications.
The convert menu gives GRIB data processing options for GDAS (the analysis equivalent of GFS),
NDAS (the analysis equivalent of NAM), and ECMWF global data files. The local archive processing is
fundamentally different that the forecast data, in that each file contains one time period, and the GUI
script loops through all the time periods within a fixed number of days to generate one output file.
The display data menu tab provides some simple tools that can be used to examine the data already in
ARL packed format. The contour map program will display a contour plot of any variable at any one
time in the file. Multiple time periods may be processed. The profile program returns a text file of the
profile of meteorological parameters at a pre-selected point. The grid domain menu shows the extent of
the meteorological grid with a mark at each point.
More detailed information about the format of the ARL packed data is available. In addition, various
library routines and utility programs are provided to manipulate both the GRIB and ARL packed data
files.
Table of Contents
Pre-processed forecast data are available for NOAA's ETA (now called NAM) model at 40-km
resolution covering North America out to +60 h or +84 h depending upon the forecast cycle. Output
from the GFS is available at several different resolutions. The AVN run of the global aviation model, on
hemispheric projections (northern and southern) at 191-km, is available out to +72 h. The GFS is also
output on its usual global 1-degree latitude-longitude grid out to +96 h, an extended (GFSX) duration
out to +180 h, and to a much longer range (GFSLR) at a coarser resolution (2-degree) to about 12 days.
The rapid update cycle (RUC) model is updated hourly. Available from the Air Force Weather agency
are MM5 forecasts at 15-km and 45-km resolution.
Except for the GFSLR, model output files are updated every 6 h with the most recent forecast data. Note
that NOAA NCEP models are run at much higher spatial resolution than what is archived in a HYSPLIT
compatible format on the ARL server. If calculations using higher resolution data are required, then the
original NAM or GFS GRIB encoded files must be obtained and converted as described in that section's
documentation. GRIB decoding can be difficult. Although much of the software is provided, no
additional guidance except for the information contained in this report is available.
Table of Contents
http://www.arl.noaa.gov/userguide/S101.htm12/5/2005 3:52:46 AM
Meteorology / Forecast Data FTP / ARL ASEAN (S102)
Table of Contents
http://www.arl.noaa.gov/userguide/S102.htm12/5/2005 3:52:51 AM
Meteorology / Forecast Data FTP / NCEP GFS (S103)
The procedure under this menu tab accesses the NCEP server and uses the NOAA Global Forecast
Model (GFS) GRIB decoder, avn2arl, to convert the GRIB data files to the HYSPLIT compatible
format. The GRIB decoder interpolates global one-degree latitude-longitude data to a conformal map
projection. The default HYSPLIT file is a 100 x 100 grid-point domain at 100-km resolution, centered
about the point selected by the slider bars on the lower portion of the menu. GFS data consist of one
GRIB file per forecast hour (0, +3, out to +72 hours). The size of each GRIB file is about 24Mb. The
decoder is run for each downloaded file, which creates a single-time forecast-file called DATA.AVN.
This file is appended to GFS{YY}{MM}{DD} to create one file that contains all the forecast hours. The
size of the final file is about 970 Kb per forecast time.
The menu is divided into two parts. The upper portion is used to select the initialization time and the
duration of the forecast. The lower portion is used to set the output directory and center latitude-
longitude of the extracted grid. If the "Save input global GRIB files" option is checked, the downloaded
GRIB files are saved rather than deleted after each forecast hour is processed. In this way a different
regional grid can be extracted from the global files without going through the FTP process again. The
GRIB data files can be reprocessed through the "Convert to ARL" menu tab, which has more extensive
conversion options available. Note that only the forecast files from the previous 24-h are available from
the NCEP server. If archive data are required, the file can be created manually be processing only the
initialization times and +3 hour forecasts.
Table of Contents
http://www.arl.noaa.gov/userguide/S103.htm12/5/2005 3:53:06 AM
Meteorology / Forecast Data FTP / NCEP NAM (S104)
The procedure under this FTP menu tab accesses the NCEP anonymous FTP server and transfers the
NAM (North America Mesoscale) forecast GRIB files on the 40 km AWIPS 212 grid (15 Mb per file) or
the 12 km AWIPS 218 grid tiles (2 Mb per file). NAM forecast data consist of one forecast time (every 3
h) per file. The GRIB files are then converted on the same horizontal grid to a HYSPLIT compatible file
which requires 3.5 Mb (212 grid) or 1 Mb (218 grid) per time period.
The menu is used to select the forecast initialization time (cycle), the duration of the forecast, the output
directory, and file name. "Save GRIB files" option is checked, the downloaded files are saved rather
than deleted after each forecast hour is processed. The downloaded GRIB data can be reprocessed
through the "NAM forecast" menu tab. Note that only the forecast files from the previous 24-h are
available from the NCEP server If archive data are required, the file can be created manually be
processing only the initialization times and +3 hour forecasts with every 6-h initialization cycle.
Table of Contents
http://www.arl.noaa.gov/userguide/S104.htm12/5/2005 3:54:32 AM
Meteorology / Analysis Data FTP / ARL Current (S111)
Pre-processed forecast data are available for NOAA's NAM (formerly ETA) model at 40-km resolution
covering North America and the AVN run of the GFS, on hemispheric projections (northern and
southern) at 191-km. The archive consists of a series of analysis (0-hour initialization) and short-time
(+3 hr) forecast files that have been appended to each other to create a continuous data time series for
the previous 48 hours from the most recent available forecast cycle.
Note that NOAA NCEP models are run at much higher spatial resolution than what is archived in a
HYSPLIT compatible format on the ARL server. If calculations using higher resolution data are
required, then the original NDAS (formerly EDAS) or GDAS (formerly FNL) GRIB files must be
obtained and converted as described in the documentation.
Table of Contents
http://www.arl.noaa.gov/userguide/S111.htm12/5/2005 3:54:46 AM
Meteorology / Analysis Data FTP / ARL archive (S112)
The ARL analysis data archive consists of output from the Global Data Analysis System (GDAS) and
the NAM Data Analysis System (NDAS) covering much of North America. Both data archives are
available from 1997 in semi-monthly files. The NDAS (formerly EDAS) was saved at 80-km resolution
every 3-h through 2003, and then at 40-km resolution (AWIPS 212 grid) starting in 2004. The GDAS
(every 6-h) was saved on a hemispheric projection at 191-km resolution.
From the GUI it is necessary to enter the year, select the month and period (001 for the 1st through the
15th and 002 for the 16th through the end of the month). The file name will be automatically created.
Note that NOAA NCEP models are run at much higher spatial resolution than what is archived in a
HYSPLIT compatible format on the ARL server. If calculations using higher resolution data are
required, then the original NDAS or GDAS GRIB encoded files must be obtained and converted as
described in the documentation.
Table of Contents
http://www.arl.noaa.gov/userguide/S112.htm12/5/2005 3:54:52 AM
Meteorology / Analysis Data FTP / NOAA Reanalysis (S113)
The NCEP/NCAR Reanalysis Project is a joint project between the National Centers for Environmental
Prediction (NCEP, formerly "NMC") and the National Center for Atmospheric Research (NCAR). The
goal of this joint effort is to produce new atmospheric analyses using historical data (1948 onwards) and
as well to produce analyses of the current atmospheric state (Climate Data Assimilation System, CDAS).
Until recently, the meteorological community has had to use analyses that supported the real-time
weather forecasting. More information about the reanalysis project and data can be found at the NCEP
and CDC web sites.
A subset of this data (global pressure level only) is available from ARL in a format suitable for transport
and dispersion calculations using HYSPLIT through the GUI. Both the global pressure-level data and a
sigma-level regional extract over the U.S. are available through the web for on-line calculations using
READY by selecting "Reanalysis" in the meteorological data set selection pull-down menu. Each
directory contains data files with the following syntax: R{S|P}{YEAR}{MONTH}.{gbl|usa|tbd}, where
R indicates "Reanalysis", S or P indicates that the data are on Sigma or Pressure surfaces, YEAR is a
four digit year, and MONTH is a two digit month. The file suffix identifies the projection as either the
2.5 degree global latitude-longitude projection (gbl), or a regional conformal map projection (such as
over the "usa"). Other regional projections are "to be determined (tbd)" later. The projection details are
encoded in the file's index record and are processed by HYSPLIT during trajectory or dispersion
computations. Note conformal regional projections (usa) are currently available only from READY's
research directory pull-down menu.
A comparable data set is also available from ECMWF's 40 year reanalysis project. The GRIB files must
be downloaded independently from the GUI, but may be converted through the GUI to the ARL format.
Table of Contents
http://www.arl.noaa.gov/userguide/S113.htm12/5/2005 3:55:06 AM
Meteorology / Analysis Data FTP / NCEP GDAS (S114)
The procedure under this menu tab accesses the NCEP server for the GDAS to convert the GFS GRIB
data files to the HYSPLIT compatible format. The GRIB decoder (same as the AVN decoder)
interpolates global one-degree latitude-longitude data to a conformal map projection. The default
HYSPLIT file is a 100 x 100 grid-point domain at 100-km resolution, centered about the point selected
by the slider bars on the lower portion of the menu. GDAS data consist of one GRIB file per forecast
hour (0, +3, +6, and +9 hours). The size of each GRIB file is about 24Mb. The decoder is run for each
downloaded file, which creates a single-time forecast-file called DATA.AVN. This file is appended to
GDAS{YY}{MM}{DD} to create one file that contains all the forecast hours. The size of the final file
is about 970 Kb per forecast time.
The menu is divided into two parts. The upper portion is used to select the initialization time and the
duration of the forecast. The lower portion is used to set the output directory and center latitude-
longitude of the extracted grid. If the "Save input global GRIB files" option is checked, the downloaded
GRIB files are saved rather than deleted after each forecast hour is processed. In this way a different
regional grid can be extracted from the global files without going through the FTP process again. The
GRIB data files can be reprocessed through the "Convert to ARL" menu tab, which has more extensive
conversion options available. Note that only the forecast files from the previous 24-h are available from
the NCEP server. A longer-term archive file must be created manually be processing only the
initialization times and +3 hour forecasts with each new 6-h forecast cycle.
Table of Contents
http://www.arl.noaa.gov/userguide/S114.htm12/5/2005 3:55:12 AM
Meteorology / Forecast Data / Local NAM Grib (S121)
Table of Contents
http://www.arl.noaa.gov/userguide/S121.htm12/5/2005 3:55:26 AM
Meteorology / Convert to ARL / NDAS Archive (S122)
Table of Contents
http://www.arl.noaa.gov/userguide/S122.htm12/5/2005 3:55:36 AM
Meteorology / Convert to ARL / GFS Forecast (S123)
The base GRIB file is set by selecting one of the GRIB files in the "Set file name" menu tab. Subsequent
forecast file names will be constructed automatically following the NCEP convention which assumes the
GFS file names end with pgrbf{HH}.tm00, where HH is the forecast hour. GRIB conversions are only
valid for data on the one-degree global latitude-longitude grid (pgrb base name).
Four different grid conversions are available through the menu. "Extract" is identical to option available
through the FTP menu, such that the GRIB data are interpolated to a conformal map projection of
100x100 grid points at 100 km resolution at the center of the latitude and longitude selection of the
slider bar. The Northern- or Southern Hemisphere options create a 95-km resolution polar stereo-graphic
grid centered about the pole. The global check-button does no conformal interpolation, but just converts
the original one-degree latitude-longitude data to the ARL packed format.
Table of Contents
http://www.arl.noaa.gov/userguide/S123.htm12/5/2005 3:55:44 AM
Meteorology / Convert to ARL / GDAS Archive (S124)
Four different grid conversions are available through the menu. "Extract" is identical to option available
through the FTP menu, such that the GRIB data are interpolated to a conformal map projection of
100x100 grid points at 100 km resolution at the center of the latitude and longitude selection of the
slider bar. The Northern- or Southern Hemisphere options create a 95-km resolution polar stereographic
grid centered about the pole. The global options results in no conformal interpolation and just converts
the original one-degree latitude-longitude data to the ARL packed format.
Table of Contents
http://www.arl.noaa.gov/userguide/S124.htm12/5/2005 3:55:51 AM
Meteorology / Convert to ARL / ECMWF forecast (S125)
The ECMWF input data may be on pressure surfaces or its native hybrid coordinate system. The
"number of levels", counted from the surface upwards, can be used to restrict the size of the output file.
This may be particularly useful when the input file consists of 60 or more hybrid levels.
Four different grid conversions are available through the menu. The "Extract" option interpolates the
data to a conformal map projection of 100x100 grid points at 100 km resolution at the center of the
latitude and longitude selection of the slider bar. The Northern- or Southern Hemisphere options create a
95-km resolution polar stereo-graphic grid centered about the pole. The "Input" option results in no
interpolation and the program just converts the original latitude-longitude data (global or regional) to the
ARL packed format.
The conversions from this menu are intended for data sets created by the operational ECMWF forecast
model. These may be forecast or analysis data. Conversion of ECMWF reanalysis data is done through a
different menu.
Table of Contents
http://www.arl.noaa.gov/userguide/S125.htm12/5/2005 3:55:57 AM
Meteorology / Convert to ARL / ECMWF archive (S126)
The conversion menu is designed to select three different GRIB file types: upper air data, surface data,
and time invariant data. The upper air and surface data files should contain data for the same time
periods. To be able to run HYSPLIT, the upper air data file must contain at a minimum the following
variables: geopotential, temperature, u-velocity, v-velocity, w-velocity, and relative humidity. The
surface variable file should contain the 2m temperature, and the 10m u- and v- velocity components. The
invariant file should contain the surface geopotential field (terrain height). Terrain height or surface
pressure is required for HYSPLIT to be able to interpolate pressure level data to its internal terrain
following coordinate system.
The ECMWF input data may be on pressure surfaces or its native hybrid coordinate system. The
"number of levels", counted from the surface upwards, can be used to restrict the size of the output file.
This may be particularly useful when the input file consists of 60 or more hybrid levels.
Four different grid conversions are available through the menu. The "Extract" option interpolates the
data to a conformal map projection of 100x100 grid points at 100 km resolution at the center of the
latitude and longitude selection of the slider bar. The Northern- or Southern Hemisphere options create a
95-km resolution polar stereo-graphic grid centered about the pole. The "Input" option results in no
interpolation and the program just converts the original latitude-longitude data (global or regional) to the
ARL packed format. The "Input" option must be used for latitude-longitude sub-grids because
interpolation from input data sub-grids is not supported.
Table of Contents
http://www.arl.noaa.gov/userguide/S126.htm12/5/2005 3:56:05 AM
Meteorology / Convert to ARL / MM5V3 (S127)
Table of Contents
http://www.arl.noaa.gov/userguide/S127.htm12/5/2005 3:56:15 AM
Meteorology / Convert to ARL / MCIP IOAPI (S129)
There are three required MCIP input meteorological data files: METCRO3D_, METDOT3D_,
METCRO2D_, and one file, GRIDDOT2D_ that gives the grid information. All data values are
interpolated to the dot grid. In the GUI, only one input file needs to be selected and the conversion
program uses the file suffix and the standard naming convention to determine the names of the other
files to open. Due to file name character length restrictions, the directory information is removed and all
the input files should be in the local working directory.
Table of Contents
http://www.arl.noaa.gov/userguide/S129.htm12/5/2005 3:56:21 AM
Meteorology / Convert to ARL / User entered (S128)
The data entry widget contains five time fields and four data fields. The output file time interval is
computed automatically from the input data. No interpolation is performed and the input data nearest in
time to the output time are used for the conversion. The maximum output interval is one hour. Note that
the date-time field defaults to the current system clock time. The meteorological variables are wind
direction, speed (m/s), mixed layer depth (m), and Pasquill stability category (1=A to 7=G).
The conversion program computes the component turbulent velocity variances based upon the stability
category and wind speed and assumes those values are constant with height within the mixed layer.
Above the mixed layer top the variances are set to the model's minimum value. Using these data for
input the model should be configured in the Advanced menu to use the variances for the dispersion.
Otherwise the diffusion calculation will default to the "deformation" method and with a spatially
constant wind field; the dispersion will always be at its minimum value.
Table of Contents
In the example shown above, the sample meteorological data file has been selected to display the temperature
(TEMP) variable on model level #2. The time period to be shown is offset 24 hours from the first time period
in the file. No additional time periods are shown when the increment is set to zero. The map will be centered
about 40N 90W with a radius of 20 degrees latitude. The maximum contour value and the temperature
difference (Delta) between contours will be determined automatically (-1.0).
There are two additional derived display options available. Selecting the variable "VECT" will produce a
wind vector plot and selecting "DIVG" will produce a plot of the wind field divergence. Both of these options
require the U and V velocity fields at the selected level in the order of U followed by V.
The output file contour.ps is created in Postscript format. It is shown below, as displayed by the Ghostscript
viewer, and may be converted to GIF through the Convert Postscript menu tab.
Table of Contents
The output is written to a file called profile.txt and the following would be shown in the GUI's display
window. The U & V wind components shown on the left side are relative to the grid, while those on the right
side are with respect to north-south and east-west. They would be the same for a latitude-longitude grid.
Table of Contents
Table of Contents
The conversion process uses Ghostscript to read the Postscript file and ImageMagick to convert that file
to a variety of other supported graphical formats. These programs can be stand-alone, but they have been
linked with the Tcl/Tk GUI menu. Conversion to GIF is the default. Proper installation of all the
previously mentioned 3rd party software is critical in the correct operation of the conversion process.
This software is included with the HYSPLIT trial version but not with the registered installation
executable. Links to these programs are also available through the HYSPLIT utilities web page.
Depending upon the installation directories of Ghostscript and ImageMagick , for the proper operation
of the conversion within the GUI, it may be necessary to edit the upper-level Tcl/Tk file ..\guicode
\hysplit4.tcl to point to the correct directories. In more recent versions of the GUI, the directory pointers
can be edited from the "Advanced-Configuration-Directories" menu tab. Various versions of these
programs will install to different directory names. For instance the lines that might require editing would
be similar to the following:
Table of Contents
http://www.arl.noaa.gov/userguide/S134.htm12/5/2005 3:57:23 AM
ALL Utility Menus / GIS to Shapefile Conversion (S135)
Normally the fields will be blank when the menu is first invoked. Prior to creating the shapefiles it is
necessary to create the "Generate" text file which contains the latitude-longitude points of each contour as
created by the contouring programs available through the display menus. Checking the GIS box in the menu (-
a1 option on the command line) creates these files. All generate format files start with GIS and end with .txt.
The remainder of the file name depends upon the application from which it was created. However in all
applications, the two-digit string prior to the .txt identifies the frame number. There is one GIS output file per
frame. In the lower text entry box enter the base name of the output shapefiles. All output files will be created
in the \working directory. Note that depending upon the upper level menu from which the conversion was
called, the shapefile conversion will be either for lines (meteorology), points (trajectory), or polygons
(concentration).
What is a Shapefile?
If you don't know, you probably don't need this library. The Shapefile format is a new working and
interchange format promulgated by ESRI for simple vector data with attributes. It is apparently the only file
format that can be edited in ARCView 2/3, and can also be exported and imported in Arc/Info. An excellent
white paper on the shapefile format is available from ESRI, but it is .pdf format, so you will need Adobe
Acrobat to browse it. The file format actually consists of three files.
Release Notes
To get notification of new releases of Shapelib subscribe to the project at www.freshmeat.net. This
is currently the only reliable way of finding out about new releases since there is no shapelib
specific mailing list.
Release 1.2.9: Good support for reading and writing NULL fields in .dbf files, good support for
NULL shapes and addition of the DBFGetFieldIndex() functions (all contributed by Jim Matthews).
Bill Miller has contributed an upgraded shputils.c. Daniel Morissette contributed
DBFGetNativeFieldType(). Better error checking for disk errors in dbfopen.c. Various other bug
fixes and safety improvements.
Release 1.2.8: Added hacked libtool support (supplied by Jan) and "rpm ready" install logic.
Release 1.2.7: Fix record size (was 4 bytes too long). Modify SHPReadObject() to handle null
shapes properly. Use atof() instead of sscanf(). Support .DBF as well as .dbf.
Release 1.2.6: Now available under old MIT style license, or at the user's option, LGPL. Added the
contrib directory of stuff from Carl Anderson and the shptree.c API for quadtree based spatial
searches.
Release 1.2.5: SHPOpen() now forcibly uses "rb" or "r+b" access string to avoid common mistakes
on Windows. Also fixed a serious bug with .dbf files with a 'F' field type.
Release 1.2.4: DBFOpen() will now automatically translate a .shp extension to .dbf for convenience.
SHPOpen() will try datasets with lower and uppercase extension. DBFAddField() now returns the
field number, not TRUE/FALSE.
Release 1.2.3: Disable writing measures to multi-patches as ArcView seems to puke on them (as
reported by Monika Sester). Add white space trimming, and string/numeric attribute
interchangability in DBF API as suggested by Steve Lime. Dbfdump was updated to include several
reporting options.
Release 1.2.2: Added proper support for multipatch (reading and writing) - this release just for
testing purposes.
Release 1.2 is mostly a rewrite of the .shp/.shx access API to account for ArcView 3.x 3D shapes,
and to encapsulate the shapes in a structure. Existing code using the shapefile library will require
substantial changes to use release 1.2.
Release V1.1 has been built on a number of platforms, and used by a number of people
successfully. V1.1 is the first release with the xBase API documentation.
Maintainer
This library is maintained by me (Frank Warmerdam) on my own time. Please send me bug patches
and suggestions for the library. Email can be sent to [email protected].
The current status of the Shapelib code can be found somewhere off my home page at http://pobox.
com/~warmerdam.
The shputils.c module was contributed by Bill Miller (NC-DOT) who can be reached at bmiller@doh.
dot.state.nc.us. I had to modify it substantially to work with the 1.2 API, and I am not sure that it
works as well as it did when it was originally provided by Bill.
Credits
I didn't start this section anywhere near soon enough, so a lot of earlier contributors to Shapelib are
lost in pre-history.
In Memorium
I would like to dedicate Shapelib to the memory of Sol Katz. While I never met him in person, his
generous contributions to the GIS community took many forms, including free distribution of a
variety of GIS translators with source. The fact that he used this Shapelib in some of his utilities,
and thanked me was a great encouragement to me. I hope I can do his memory honour by trying to
contribute in a similar fashion.
Portability
The Shapefile C Library should port easily to 32bit systems with ANSI C compilers. It should work
on 64 bit architectures (such as the DEC AXP). Care should also be taken to pass the binary
access flag into SHPOpen() and DBFOpen() when operating on systems with special text file
translation such as MSDOS. The shputils.c module is contributed, and may not take the same
approach to portability as the rest of the package. On Linux, and most unix systems it should be
possible to build and install shapefile support as a shared library using the "lib" and "lib_install"
targets of the Makefile. Note that this Makefile doesn't use autoconf mechanisms and will generally
require some hand tailoring for your environment.
Limitations
● You can't modify the vertices of existing structures (though you can update the attributes of
existing structures, and create new structures).
● Not written in such a way as to be particularly fast. This is particularly true of the 1.2 API. For
applications more concerned with speed it may be worth using the V1.1 API
● Doesn't set the last access time properly in the .dbf files.
● There is no way to synchronize information to the file except to close it.
● Poor error checking and reporting.
● Not professionally supported (well it can be, if you want to pay).
● Some aspects of xBase files not supported, though I believe they are not used by ESRI.
● The application must keep the .dbf file in sync with the .shp/.shx files through appropriate use
of the DBF and SHP APIs.
● No support for the undocumented .sbn/.sbx spatial index files.
Copyright
The source for the Shapefile C Library is (c) 1998 Frank Warmerdam, and released under the
following conditions. The intent is that anyone can do anything with the code, but that I do not
assume any liability, nor express any warranty for this code.
As of Shapelib 1.2.6 the core portions of the library are made available under two possible licenses.
The licensee can choose to use the code under either the Library GNU Public License (LGPL)
described in LICENSE.LGPL or under the following MIT style license. Any files in the Shapelib
distribution without explicit copyright license terms (such as this documentation, the Makefile and so
forth) should be considered to have the following licensing terms. Some auxiliary portions of
Shapelib, notably some of the components in the contrib directory come under slightly different
license restrictions. Check the source files that you are actually using for conditions.
This software is available under the following "MIT Style" license, or at the option of the licensee
under the LGPL (see LICENSE.LGPL). This option is discussed in more detail in shapelib.html.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial
portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.
Shapelib Modifications
I am pleased to receive bug fixes, and improvements for Shapelib. Unless the submissions indicate
otherwise I will assume that changes submitted to me remain under the above "dual license" terms.
If changes are made to the library with the intention that those changes should be protected by the
LGPL then I should be informed upon submission. Note that I will not generally incorporate changes
into the core of Shapelib that are protected under the LGPL as this would effectively limit the whole
file and distribution to LGPL terms.
For licensee's opting to use Shapelib under LGPL as opposed to the MIT Style license above, and
wishing to redistribute the software based on Shapelib, I would ask that all "dual license" modules
be updated to indicate that only the LGPL (and not the MIT Style license) applies. This action
represents opting for the LGPL, and thereafter LGPL terms apply to any redistribution and
modification of the affected modules.
Table of Contents
Meteorology / Help
Data Format
The following sections describe the ARL packed data format in a little more detail to permit the
development of customized applications. Library routines are provided to simplify the task of creating a
model compatible data file. A meteorological data file is composed of one or more time periods. Each
time period begins with one or more ASCII index records that summarize the valid time, the grid
definition, the variables, and level information. Each subsequent record contains one horizontal data
field, consisting of 50 ASCII bytes of time, variable, and level information for that record, followed by
X times Y bytes of data, where X and Y are the number of data points in the horizontal and vertical
directions, respectively. Floating point or integer data are packed as one byte per variable. Precision is
maintained by packing the differences between adjacent grid points rather than packing the absolute
values. In any time period, although not required, the surface data precede the upper-level data fields.
All records are of the same length to permit the model to read the file in a "direct access" mode. Data
files can be read on most computing platforms without any transformation and appended to each other
using routine operating system commands such as "cat" or "type". Only binary transfers or copies are
permitted. All the routines discussed in this section can be found in the \metdata\source directory.
Meteorological variables are identified to the model by a unique four-character identification field that is
written to the first 50-byte header portion of each data record. Some of the variables that can be decoded
by the model and their units are identified below.
Temperature at 2 m K T02M
Upper-Level Parameters
Temperature K TEMP
Data may be obtained from any source, however there are certain minimum data requirements to run the
model: surface pressure or terrain height, u-v wind components, temperature, and moisture. In addition,
precipitation is required for wet removal calculations. Not required, but certainly necessary to improve
vertical mixing calculations, would be some measure of low-level stability. This may take the form of a
near-surface wind and temperature or the fluxes of heat and momentum.
It is also important to have sufficient vertical resolution in the meteorological data. Some of the NOAA
higher resolution data files have five or more levels in the boundary layer (<850 hPa) in addition to wind
and temperatures near the surface, usually at 2 and 10 m agl. These surface values are especially
important when the data are only available on absolute pressure surfaces, rather than terrain following
sigma surfaces, to avoid interpolation to the surface between data levels when the local terrain is well
above sea-level.
One may prepare meteorological data from any number of different sources to be in a suitable format for
the model using a series of routines described in this section. In general it is assumed one has access to a
meteorological data source, either the data fields are already on a grid, such as those output from a
meteorological model, or perhaps from observations that have been interpolated to a grid. Some example
conversion programs are provided within the GUI to convert from either NOAA, or ECMWF GRIB
format data files to HYSPLIT format. Other programs are also provided (see avn2arl, ncr2arl, ecm2arl,
and mm5toarlI) in directory /data2arl. The directory also contains source code for reading the direct
access of variable record length files, such as those that contain GRIB records, and special platform
independent GRIB decoding subroutines.
The meteorological data are processed in time-sequence, calling the subroutines provided, to create a
HYSPLIT compatible output file. These subroutines will pack the data and write the index record. The
index record, which precedes the data records for each time period, can only be written after the data
records are processed. The packing routines must first be initialized by setting the appropriate grid
parameters and defining all the meteorological variables that will be written to the file. Multiple output
grids may be defined and written simultaneously by invoking the PAKSET routine with a different unit
number for each grid. The grid parameters are all defined in a configuration file, which should be in the
directory from which the procedure is invoked:
Kunit is the Fortran unit number to which the data records will be written. Fname is the character string
of the name of the configuration file. It can be any name, but it will default to metdata.cfg. The file is
opened internally on kunit to read the configuration file. This routine needs to be called once for each
grid. Krec is the starting record number (of the index record) to which output will be written. It is
normally set to 1 unless you want to start writing in the middle of a file. The remaining parameters (nx,
ny, nz) are returned by the subroutine and define the horizontal and vertical grid dimensions. These
values can be used to set variable dimensions. It is your responsibility to open kunit for output after
having completed the pakset calls:
The individual data records are packed and written by a call to PAKREC, once for each variable at each
level. The routine calculates the record offset from the index record according to the variable and level
information provided in the arguments and writes the record according to the order specified in metdata.
cfg. The data can be supplied in any order. Note that although the level indicator (LL) goes from 1 to the
number of levels, one is subtracted before it is written to the 50 byte header to be consistent with the
definition of surface data to be at level "0". All the records in a time period may be initialized according
to the value of the kini flag. Initialization fills in the time variable for all records and assigns the variable
When all the data records for a time period have been written, it is necessary to close that time period by
writing its index record:
CALL PAKNDX(kunit)
At this point your program can return to PAKREC if data records for additional time periods are to be
added to the file.
The key to the process is creating the proper configuration file for the data set you want to create. Some
of the sample data decoders provided in the data2arl directory dynamically configure the packing
configuration file based upon the command line input information. A sample metdata.cfg file for
NOAA's AVN model output created dynamically by the avn2arl decoder that is automatically invoked
through the GUI using the "FTP NCEP GFS " tab of the Meteorology menu is shown below. An extract
of the global one-degree latitude-longitude GRIB AVN model data have been interpolated to a 100 km
resolution Lambert Conformal projection 100x100 point grid centered about 45N 90W. The
configuration file format is such that the first 20 characters are a dummy identification field followed by
the data.
F6.,I3,(1X,A4)
It is important that the information contained in this file is correct because it not only controls the
writing of the packed meteorological data file, but much of the information is written into the index
record of each time period. The model decodes this information to set up the internal processing of the
meteorological data. Starting with HYSPLIT V4.5, the model is also capable of using meteorological
data on a latitude-longitude grid. Previous versions were limited to data on a conformal map projection.
Data on a regular latitude-longitude grid still need to be converted to the ARL packed format.
Modifications to the packing configuration file required to support a latitude-longitude grid are noted
below. A complete description of metdata.cfg format follows:
Record 1 consists of a four-character string that identifies the source of the meteorological data. This
string will be passed through to many of the output graphics.
Record 2 is an optional integer identification of the meteorological data grid. It was used extensively in
previous meteorological data file formats. It is not used in Hysplit4 applications.
Record 3 is an integer number that identifies the vertical coordinate system. Only four coordinate types
are recognized: 1-pressure sigma; 2-pressure absolute; 3-terrain sigma; 4-hybrid sigma.
Records 4 & 5 identifies the pole position of the grid projection. Most projections will either be defined
at +90 or -90 depending upon the hemisphere. The longitude would be the point 180 degrees from which
the projection is cut. Lat-Lon Grids only: contains the latitude and longitude of the grid point with the
maximum grid point value.
Records 6 & 7 is the reference position at which the grid spacing is defined. Lat-Lon Grids only:
contains the grid spacing in degrees latitude and longitude.
Record 8 is the grid spacing in km at the reference position. Lat-Lon Grids only: a value of zero signals
that the grid is a lat-lon grid.
Record 9 is the grid orientation or the angle at the reference point made by the y-axis and the local
direction of north. Lat-Lon Grids only: value always = 0.
Record 10 is the angle between the axis and the surface of the cone. For regular projections it is equal to
the latitude at which the grid is tangent to the earth's surface. A polar stereo-graphic grid would be
tangent at either 90 or -90, while a Mercator projection is tangent at 0 latitude. A Lambert Conformal
projection would be in between the two limits. An oblique stereo-graphic projection would have a cone
angle of 90. Lat-Lon Grids only: value always = 0
Records 11 & 12 are used to equate a position on the grid with a position on the earth as given in the
following two records:
Records 13 & 14. In this example, the position indicated is the center of the grid located over the North
Pole. Any position is acceptable. It need not even be on the grid. Lat-Lon Grids only: contains the
latitude and longitude of the 1,1 position grid point.
Record 18 is the number of levels in the vertical, including the surface level.
Record 19, through the number of levels, identifies the height of each level in appropriate units
according the definition of the vertical coordinate, the number of variables at that level, and the four
character identification string for each variable. The height units are as follows for each coordinate:
1-sigma (fraction)
2-pressure (mb)
3-terrain (fraction)
4-hybrid (mb: offset.fraction)
One may want to develop other applications for HYSPLIT compatible meteorological data files. For
these situations, some lower-level routines are provided in the source code library. The key to reading
the meteorological files is decoding the index record. The format for this record is given below.
Complete descriptions are similar to the variables in the discussion above.
FORMAT DESCRIPTION
Once the index record has been read and decoded you have sufficient information to read and decode the
data records. A data un-packer is provided to convert the packed character*1 array to a real*4 array. It
can also be used to extract a sub-grid from the full domain through specification of the sub-grid lower
left corner:
If the entire grid is to be unpacked then nx0=ny0=1 and nx=lx, ny=ly. The checksum (ksum) that is
returned should be compared with the corresponding value in a table generated from reading the index
record. If you are not going to compare the checksum, set ksum = -1, this will save a little computer
time. Due to the sub-grid option the checksum cannot be computed in the regular unpacking loop, but
requires a second pass through the data. The checksum pass is enabled when ksum=0. It will then return
a non-zero value. If you don't reset it to zero, no further checksums will be computed.
If you want to create your own packed data by converting a real*4 array to the character*1 packed data
array use the following:
CALL PAKOUT(rvar,cvar,nx,ny,nxy,prec,nexp,var1,ksum)
Although the structure of the packed data may seem complex, unpacking is a very simple process, the
basic elements of which are summarized in the Fortran code shown below. The value of each element is
the sum of the initial value and the difference stored in that element location.
SUBROUTINE UNPACK(CPACK,RVAR,NX,NY,NXY,NEXP,VAR1)
CHARACTER*1 CPACK(NXY)
REAL*4 RVAR(NX,NY)
SCALE=2.0**(7-NEXP)
VOLD=VAR1
INDX=0
DO J=1,NY
DO I=1,NX
INDX=INDX+1
RVAR(I,J)=(ICHAR(CPACK(INDX))-127.)/SCALE+VOLD
VOLD=RVAR(I,J)
END DO
VOLD=RVAR(1,J)
END DO
RETURN
Table of Contents
Meteorology / Help
Sample Meteorological Programs
The source code for many different meteorological data applications can be found in the /metdata and /
data2arl directories. A summary of these programs and some others where only the executable is
provided are given below. Some of these are available for execution through the GUI, others must be run
from the command line. For a few programs, only the PC executable is available for distribution.
GRIB records
The various programs and library routines that are required to convert GRIB formatted meteorological
data files to ARL HYSPLIT compatible format can be found in the /data2arl directory. These are
summarized below:
ncr2arl - decodes NCEP/NCAR re-analysis GRIB fields on pressure surfaces. A newer program,
grib2arl, may be used instead.
rsm2arl and prsm2arl - decodes the Regional Spectral Model (RSM) GRIB output fields on sigma and
pressure surfaces to ARL packed format.
ecm2arl - decodes ECMWF global model GRIB fields on a latitude-longitude grid. Requires the
ECMWF supplied GRIBEX subroutines. A newer program, grib2arl, may be used instead.
content - decodes individual GRIB sections in a record for diagnostic purposes. This program does not
unpack the data but only lists the contents of the GRIB file.
inventory - decodes all the records within a GRIB file (without unpacking) providing file content
information.
sample - creates a packed meteorological file using dummy fields hardwired into the program. The input
meteorological data subroutines should be replaced by routines reading user supplied meteorological
data files.
grib2arl - a generic program to convert global data from ECMWF or NOAA on a global latitude
longitude grid using the ARL provided GRIB decoder. ECMWF data may be on the native hybrid sigma
or pressure surfaces. The program options are similar to avn2arl, but with some significant differences.
The grib2arl version is capable of decoding both NOAA and ECMWF GRIB files. For computational
purposes, HYSPLIT requires either surface pressure or terrain height as a surface field in the
meteorological data file. The default is that surface pressure is assumed to be available in the input
GRIB file, otherwise the terrain height is required. This option is set using the "-p" flag. ECMWF GRIB
files may contain upper-level variables in one file, surface variables in another file, and invariant data in
a third file. In this situation, the upper-level data are considered the primary file "-i" and the surface data
are the supplemental file "-s", and the invariant data are the constant file "-c".
avn2arl - a more customized program to convert global data only from NOAA's GFS on a global latitude
longitude grid. Selecting extract (-g0) interpolates the global latitude-longitude GRIB data to a
conformal map projection of 100x100 grid points (-n100) at 100 km resolution at the center of the
latitude (-y) and longitude (-x) selection of the slider bar. Checking the North (-g1) or South (-g2)
hemisphere option, automatically creates the appropriate hemispheric polar stereo-graphic projection
centered about the pole. The global check-button (-g3) does no conformal re-interpolation, but just
converts the original one-degree latitude-longitude grid data to the ARL packed format. The GRIB
converter can also be run from the command line with the following options:
afwa2arl - decodes ETA model fields on pressure surfaces and on the AWIPS-212 grid. The ETA GRIB
converter can also be run from the command line with the following options:
where file_1, etc, are all the GRIB files that contain data for the same time period. The GRIB
decoder only processes data for one time period per execution. Multiple input files may be
required as some meteorological centers split surface, upper-air, and diagnostic variables, into
different files. The decoder is identical in functionality to the eta40arl program, which also
converts GRIB data files on the AWIPS-212 grid. However, the afwa2arl program produces a
more condensed file with only the variables required for HYSPLIT simulations.
ffsubs - library routines required for direct access to variable length records
packing - library routines to read and write ARL packed data records.
w3arl - library routines of the ARL version of the NCEP w3lib GRIB record decoder.
The various programs and library routines that are required to manipulate or display meteorological data
already in the ARL packed format can be found in the /metdata directory. Note that when these
programs are run from the command line there will be a typical two line prompt, the first for the
directory and second for the file name. A directory name should always have the proper terminator (/ or
\). The following programs can be found:
chk_rec - program to dump the first 50 bytes of each meteorological data record. Those bytes contain
ASCII data describing the packing.
chk_file - program to examine header and data records of an ARL packed meteorological data file. The
program uses the same I/O subroutines common to HYSPLIT code. If this program does not work with a
data file, neither will HYSPLIT.
chk_data - a simple program that shows how to read and unpack the ARL format packed meteorological
data.
contour - creates postscript file of meteorological data contoured and color filled for a single variable at
display - creates postscript file of meteorological data contoured and color filled for a single variable at a
specified time. The output written to display.ps. This program is prompted interactive version of the
command line program contour.
profile - creates text file of the profile of meteorological variables at a specified location and time. The
output is written to the screen and to the file profile.txt.
showgrid - shows the extent of the meteorological grid domain with a "+" symbol at the intersection of
each node. The output is written to showgrid.ps
xtrct_grid - extracts a subgrid from the full grid meteorological data file. It permits selection by lat-lon
corners and number of levels from the ground. Creates output file called "extract.bin"
xtrct_time - extracts data between two selected time periods from the designated meteorological file.
Creates an output file called "extract.bin"
/source - contains remaining library routines not found in the /data2arl directories.
Table of Contents
Trajectory / Help
The trajectory menu tab is composed of five main sections: setting up the simulation, executing the
model, displaying the trajectory, converting the graphic to other formats, and configuring special
simulations. The model is configured and executed through the menu and results displayed. However for
experienced users, each component may be run independently from the command line and the
CONTROL file could be created using any text editor.
In the Trajectory Setup menu the entire purpose of the GUI is to configure the model's input CONTROL
file. This is a text file that configures the simulation parameters. Once the input parameters are set to
their desired value, the model is executed from the Run Standard Model menu tab. When complete, the
output window is closed and the Trajectory Display menu is used to draw and display the trajectory from
the endpoints output file. The Special Simulations menu is used to configure several different
customized simultaneous multiple trajectory simulations.
For inexperienced users, a review of the Quick Start Help is highly suggested, which goes through the
trajectory computation step-by-step using the example meteorological data file.
Table of Contents
http://www.arl.noaa.gov/userguide/S260.htm12/5/2005 4:08:56 AM
Trajectory / Quick Start Help (S261)
The easiest way to run the model is to use the GUI menu to create the model's input Control file. For the
purposes of this demonstration appropriate meteorological files are provided. If for some reason the
menu system is not available, perhaps because Tcl/Tk was not installed, the Control file can be created
manually
Step 1 - start the GUI menu system using \working\hysplit4.tcl or the desktop shortcut to Hysplit4. A
widget will appear with the HYSPLIT graphic and three button options: Menu, Help and Exit. On some
systems the graphic may be scrambled or the colors may be flat. Switching the PC display to VGA and
256 colors usually solves these problems. However it can be left alone as the faulty graphic will not
affect any of the other widgets or display graphics. Click on Menu tab.
Step 2 - The four main menus of the Hysplit4 GUI will appear: Meteorology , Trajectory ,
Concentration , and Advanced. An additional small widget underneath the main menu gives the current
Hysplit4 version information. Do not delete this widget as it will terminate the GUI. It provides the
reference frame for the model's standard output and messages. Click on the Trajectory tab.
Step 3 - Five options appear under this item: Trajectory Setup, Run Standard Model, Trajectory
Display , Utility Programs , and Special Simulations. Normally these are run in sequence, however any
item can be selected and run if the appropriate input files were created during a previous simulation.
Click on the Trajectory Setup tab.
Step 4 - Trajectory Setup is used to enter the basic model simulation parameters: the starting time of the
calculation; starting location in terms of latitude, longitude, and height; the run-time or duration of the
trajectory calculation; and the names and locations of all required files. When modifications to this menu
are complete, click on Save. However for this example, you will use the Retrieve option for predefined
configurations, so do nothing here and go on to Step 5.
Step 5 - The example calculation is configured by clicking on Retrieve and then entering the text:
sample_traj, which is the name of the example simulation control file that was created for this
demonstration. Then click on OK. After the data entry widget is closed, click on Save and the setup
menu will close.
Step 6 - Click on Run Standard Model, which first copies the setup configuration (default_traj) saved
in the previous step, to the model's input Control file. The model calculation is then started. A series of
messages will appear on standard output text window showing the progress of the calculation. When the
simulation is completed, the trajectory end-points output file is ready to be converted to a graphical
display. Under Windows 95/98 the standard output widget will not show any output until the end of the
calculation and the Trajectory menu items will be locked until the calculation completes.
Step 7 - Selecting Trajectory Display will run a special program that converts the text file of trajectory
end-point positions into a high quality Postscript file (trajplot.ps) suitable for printing. The conversion
widget provides options for the frequency of the labels on the trajectory, a variable zoom factor, and
color or black and white graphics options. If the Postscript viewer (Ghostscript / Ghostview) has been
installed and associated with the .ps file suffix, then it will be invoked by the GUI. If the viewer does not
automatically open, it may be necessary to manually edit ../guicode/hysplit4.tcl to change the directory
location associated with the program gsview32.exe. The Utility Programs tab contains only one option -
converting the Postscript file to other graphical formats. The format is specified by the file name suffix:
e.g. trajplot.ps to trajplot.gif. After clicking on Execute Display, the following graphic will appear in
the Ghostview window:
Table of Contents
Clicking the Setup Starting Locations tab brings up the menu shown below. If the number of starting
locations were to have been changed from the default value of one on the main menu, then there would be
that number of starting location lines set on the menu, all with the same latitude and longitude. These could
then be manually edited for different locations or starting heights. Another possibility would be to click on
the List tab, which brings up a list of pre-selected starting locations from a file called plants.txt, which can
be found in the ../hysplit4 directory. This file can be edited to reflect starting locations of interest to the user.
Another important feature of the main menu is how to select or add meteorological data files. The Clear
button will erase all file selections, then pressing the Add Meteorology Files tab brings up the file selection
dialog shown below. Select a file and click Open and the file will be added to the main menu. For each
additional file, it is necessary to click again on the Add Meteorology Files tab. With each new file the
selected files number is incremented by one.
Once the simulation is configured as required, click the Save menu tab. This causes the GUI menu to over-
write the values in default_traj. Note that the format of default_traj is identical to the CONTROL file.
Clicking on Save closes the menu and then when the Run Standard Model tab is executed, default_traj is
first copied to CONTROL, and then the trajectory model is executed.
When the GUI menu system is restarted, it loads the last values stored in default_traj. The default_traj file
may also be saved to another name to permit future similar simulations to be set up more quickly. This
option is available through the Save As and Retrieve menu tab of the setup menu.
Table of Contents
Table of Contents
http://www.arl.noaa.gov/userguide/S211.htm12/5/2005 4:10:02 AM
Trajectory / Run Standard Model (S220)
Successful completion of a simulation will show a similar message. Additional run-time diagnostic
messages and other error messages are always written to a file called MESSAGE. This file may be
viewed through one of the Advanced Menu tabs. Depending upon the nature of the error message,
perhaps a failure in the model initialization process, error messages may also appear in above window.
Once the model has completed, press Exit to close the window.
Table of Contents
http://www.arl.noaa.gov/userguide/S220.htm12/5/2005 4:10:13 AM
Trajectory / Display (S230)
Trajectory / Display
The trajectory model generates a text output file of end-point positions. The end-point position file is
processed by trajplot to produce the Postscript display file. Trajplot can be accessed through the GUI or
run directly from the command line. The display program has a variety of command line options, most
of which are available through the GUI. There is a one-to-one relationship between GUI options, an
example of which is shown below, and the command line options. There are several features particular
to the GUI. First the Trajectory Display menu will not open unless the Trajectory Setup menu was first
opened and Saved. This procedure sets all the GUI parameters to their default_traj values. These are the
values shown in the Display menu. Normally the map projection is computed automatically based upon
the location and length of the trajectory. However some trajectory combinations may give no maps or
improperly scaled maps. In these situations one would want to over-ride the default projection and try
forcing a selection.
All mapping programs use the same text map background file, arlmap, which normally would be located
in the ../graphics directory. However, all graphics programs first search the local start directory first (../
working if running the GUI), then the ../graphics directory. Customized map background files can be
read instead of the default file for specialized applications. Some higher resolution map background files
are available from the HYSPLIT download web page. These different map files may be accessed
implicitly by putting them in the "../hysplit4 (the startup directory), or explicitly through the GUI by
entering the name of the customized map background file.
The map background file format consists of three or more records per graphic line with the following
format:
The Postscript conversion program trajplot can be found in the ../trajmdl directory. The program reads
the trajectory endpoints output file, calculates the most optimum map for display, and creates the output
file - trajplot.ps. When executed from the command line, there are several Unix style command line
options. There should be no space between the option and any arguments: trajplot -[options (default)]
Selecting the GIS checkbox creates an ASCII text file for each output time period that consists of
the value and latitude-longitude points along each contour. This file can be converted to an
Arcview Shapefile or converted for other GIS applications through the utility menu "GIS to
Shapefile. The view checkbox would be disabled to do just the GIS conversion without opening
the Postscript viewer.
= {blank} - draws four distance rings about source point, automatically scaled
= {#} - draws the indicated number of rings about the source point
= {#1}:{#2} - draws the number {#1} of rings about the source point each {#2} kilometers apart.
In the special case where #1 is zero, the rings are not drawn, but the size of the plot is scaled as if
one ring of radius {#2} is to be drawn.
= latitude:longitude - forces the map center to be at the selected location instead of the source
point. In conjunction with the -g1:{km} option it is possible to create a constant map projection
for each execution.
= trajplot.ps is the default Postscript output file name, otherwise it may be {user defined}.
Many of the Postscript graphics programs have label information that can be customized to some extent.
This is accomplished by placing a file called Labels.cfg in the startup directory which contains the
following valid entries (all in single quotes terminated by &) replacing the new string with the desired
text. A sample file called Labels.bak may be found in the relevant directory. Not all label strings are
valid with every plotting program. For instance with trajplot, only the title entry would be used to
replace the top label line of the plot.
Additional supplemental text may be added at the bottom of the graphic by creating a file called
MAPTEXT.CFG, also to be located in the startup directory. This is a generic file used by all plotting
programs but each program will used different lines in its display. The file can be created and edited
through the Advanced menu tab.
Table of Contents
Table of Contents
http://www.arl.noaa.gov/userguide/S243.htm12/5/2005 4:10:43 AM
Trajectory / Special Simulations (S253)
Run Ensemble
The ensemble form of the model automatically starts multiple trajectories from the selected starting
point. Each member of the trajectory ensemble is calculated by offsetting the meteorological data by a
fixed grid factor as defined in the Advanced Trajectory Configuration tab. The default offset is one
meteorological grid point in the horizontal and 0.01 sigma units in the vertical. The results in 27
members for all-possible offsets in X, Y, and Z. After the model calculation has completed, use the
normal Trajectory Display tab to view the results. Because the offset is computed in both directions in
the vertical from the starting location, a starting location at the ground would not provide an optimal
configuration for this type of simulation. The default vertical offset is about 250 m. Therefore this
should be the minimum starting height for ensemble trajectories, unless the default offset is changed in
the namelist file. An example of the ensemble trajectory using the example meteorological data is shown
in the illustration below.
Run Matrix
The matrix calculation is a way to set up the CONTROL file for multiple starting locations that may
exceed the GUI limit of 6 under the Trajectory Setup tab. Hundreds or thousands of starting points may
be specified. The Run Matrix tab just executes the model using a CONTROL file that is dynamically
created from the default_traj file using a special program called latlon that is called from within the
GUI. The program reads a CONTROL file that is required to have three starting locations and then re-
writes the same file with multiple locations. The multiple starting locations are computed by the latlon
program based upon the number of starting points that fall in the domain between starting point 1 and
starting point 2. Each new location is offset by an amount equal to the difference between starting
locations 1 and 3. An example would be more illustrative. If the original control file has three starting
locations: #1 at 40N, 90W, #2 at 50N, 80W, and #3 at 41N, 89W; then the matrix processing results in a
CONTROL file with 121 starting locations, all one degree apart, all between 40N 90W and 50N 80W.
The reason for this approach is that only the CONTROL file is modified and not default_traj. The GUI
never reads CONTROL, therefore the file does not need to conform to the GUI limits. The final matrix
trajectory using the example meteorological data for this configuration is shown in the illustration below.
In the normal simulation configuration, all trajectories start at time that was defined in the first line of
the Trajectory Setup menu. Trajectories starting at a different time would require an independent
simulation. However, there is shortcut to permit the calculation of multiple trajectories in time from the
same starting location. Setup the simulation for a single trajectory then go to the Advanced Trajectory
configuration menu. Under the Temporal Trajectory Restart line, edit the temporal interval in hours
from the default of zero (no restarts) to the desired value. For example, if this value is set to 6 hours
(corresponding to NSTR=6 in the namelist file SETUP.CFG), then in addition to the normal trajectory
that starts at the initial time, new trajectories would be started every six hours for the duration of the
simulation. The result of this simulation, using the example meteorological data, is shown in the
illustration below.
The standard setup options of the GUI permit the calculation of multiple trajectories in space or height
by simply specifying new locations in the CONTROL file. A variation of that procedure was shown
above with respect to setting up a matrix of starting locations. The model also permits the start of new
trajectories at different locations along an existing trajectory. This can be considered a special case of
multiple trajectories-in-time because when starting a new trajectory along an existing trajectory, the new
starting location differs in time and space from the original trajectory. In this variation, new trajectories
are started at multiple levels at the temporal restart interval. The multiple restart levels are assumed to be
the same multiple starting heights specified in the original setup and therefore the number of restart
heights must equal the number of starting locations. Go the Advanced Configuration menu and setup the
example as in the previous case to restart trajectories every 6 hours. Then change the Number of Levels
parameter from its default value of zero (no new trajectories) to the number of new trajectories will be
started. For example, set the number of levels to 2 (sets the NVER=2 parameter in the SETUP.CFG
namelist file). The number of starting locations should also be set to two, at the same location, but with
release heights of 10 and 1500 m. Two trajectories, at 10 and 1500 m, will start every 6 hours. The result
is shown in the illustration below.
Table of Contents
The model should be configured and run for one simulation time through the standard run menu to insure that
the simulation is configured correctly. If part of the simulation requires meteorological data from the previous
month or the next month, these should be included in the base simulation.
Table of Contents
http://www.arl.noaa.gov/userguide/S254.htm12/5/2005 4:12:00 AM
Trajectory / Special Simulations / Run Cluster Analysis (S255)
Step 1. Inputs.
Run ID - A label to identify each run. The label ends at the first blank space. The other numeric
inputs may be part of the label. For instance if trajectories during 2004 from Ohio were clustered,
the Run_ID could be Ohio_2004. If you used 48-h trajectories, hourly endpoints, and every other
trajectory, a label of Ohio_2004_48_1_2 could be used. If you later decided to only use the first
36-h of the trajectory Ohio_2004_36_1_2 might be used.
Hours to cluster - Trajectory durations up to the given hour are used. Must be a positive number.
Time is from trajectory origin whether backward or forward. Trajectories terminating befor the
given hour will not be included in the clustering. Premature terminations commonly result from
missing meteorology data or the trajectory reaching the meteorological grid horizontal or top
edge.
Time interval - Identifies which endpoints along a trajectory to use. Typically every hourly
endpoint is used.
Trajectory skip - Identifies which trajectories in a folder to use. A value of 1 means every
trajectory will be used; 2 means every other trajectory; 5 every 5th trajectory, etc. Useful with
very large sets of trajectories.
Endpoints parent folder - With the default endpoints parent folder of ../endpts, the trajectory files
would be in the /hysplit4/endpts/Run_ID folder.
Archive parent folder - With the default of ./cluster_output, the archive folder would be /hysplit4/
working/cluster_output/Run_ID.
Step 2. Run Cluster Program. Possible solutions to the cluster analysis are available at the end of this
step.
Rename web tdumps Trajectories created on the web with autotraj have filenames of format
tdump.[Julian Day]. These can be used as is OR run this rename script to rename the files to the
format of the HYSPLIT PC- Run Daily with the year-month-day-hour in the filename.
Make INFILE. Trajectories must have been run previously, such as via TRAJECTORY / Special
Simulations / Run Daily. All the trajectory endpoints files need to be in one folder (directory) and
each must have the name tdump within its filename. In this step, a file, INFILE, listing all the
tdump files will be created in ../working.
Run Cluster The cluster analysis program is run here given the INFILE file, the manually input
number of hours from the beginning of the trajectories in which to base the trajectory clustering
on, the time interval along the trajectory at which to read the endpoints information, and using the
trajectories specified by the "skip" parameter. Typical values are 36 hours to cluster and reading
the hourly endpoints. For very long trajectories, a longer time interval may give adequate results.
The cluster process is as follows: Initially, each trajectory is defined to be a cluster. There are N
trajectories and N clusters. The cluster process is an iterative process consisting of N-1 passes through
all the clusters. In the 1st pass, the two closest clusters (trajectories) are paired, resulting in N-1 clusters.
Similarly in the 2nd pass, the two closest clusters are paired, resulting in N-2 clusters. In this case, either
the cluster having two trajectories could be paired with another trajectory or two clusters, each with one
trajectory, could be paired. This process continues until all trajectories are in 1 cluster. The cluster
program produces six output files:
CLUSTER trajectory start date/time and endpoints (tdump) filename for all the trajectories in
INFILE; then for each pass, a listing of the trajectories in each cluster.
DELPCT the change in total spatial variance of all the clusters from one pass to the next.
TNOCLUS the filenames of the endpoints files not clustered (i.e. trajectory terminates before the
hours to cluster duration given in Step 1.
CLUSTERno the filename and trajectory start date/time of trajectories, if any, not clustered; used
to create cluster results (CLUSLIST)
On a typical PC, a cluster run with 365 trajectories, 36-h duration, and using every hourly endpoint, will
take a couple minutes. Going beyond several years of trajectories will result in a run that will take a long
time and/or use much memory. A warning message is given for larger runs, but there is no simple way to
identify how large a cluster job is possible.
Display plot shows the percent change in total spatial variance (TSV) for the final 30 passes
through the cluster program. This data is from the file DELPCT. Generally there can be seen at
least one time when there is a large increase in the total spatial variance, indicating that different,
rather than similar, clusters are being paired and that the cluster process should stop before that
occurs.
View possible final number of clusters. Typically a pairing of "different" clusters is indicated by
a 30% change in the percent change in total spatial variance (see Step 2, Display plot). Run lists
the possible final cluster numbers. If the 30% criterion does not identify any, the 20% criterion
may be chosen.
Step 3 Get Results. This step may be repeated using different numbers of clusters. If you exit the GUI,
but have not archived your results, enter the Run_ID and the Archive parent folder again from Step 1,
then continue with Step 3. If you have already archived the results, but want to try a different number of
clusters, manually copy everything from the archive directory to /hysplit/working, then enter the number
of clusters, etc.
Number of clusters Enter the final number of clusters, one of the values listed in Step 2, Run. In
general, use the value where the plot from Step 2,Display plot shows a sharp upward turn.
Text creates a text file listing the trajectory start date/times and filenames in each cluster
(CLUSLIST_N, where N is the final number of clusters). Note Cluster #0 is for trajectories not
clustered.
Display Means produces one map with the mean trajectories of all the clusters for the given final
number of clusters.
Cluster produces one map for each cluster, showing the trajectories in each cluster.
Trajectories not used are those input to the cluster program, i.e. in the endpoints directory, and at
the given skip interval, that terminate before the trajectory duration equal to the Step 1, Hours to
cluster. This displays the plot showing the trajectories not used and the cluster-mean trajectories
for the trajectories not used (cluster #0) and all the other clusters. Note the plot showing the
trajectories must have been previously created in Step 3, Display Clusters.
Archive All files are moved, not copied, to the given directory. Files created in Step 3 contain the
final number of clusters in the filename so Archive can be run once after all analysis is complete.
Table of Contents
The Cluster Display window is very similar to that used for plotting individual trajectories: Trajectory
Display. To set a constant map domain, set Rings: choose the Set checkbox, number of rings: 0, Dist
(km): map radius. The plot trajectory duration defaults to the hours clustered. The postscript graphics
will be converted to GIF if the GIF checkbox is checked.
Table of Contents
Default: 0 0 0 0
Enter the two digit values for the UTC time that the calculation is to start. Use 0's to start at the
beginning (or end) of the file according to the direction of the calculation. All zero values in this
field will force the calculation to use the time of the first (or last) record of the meteorological
data file. In the special case where year and month are zero, day and hour are treated as relative
to the start or end of the file. For example, the first record of the meteorological data file usually
starts at 0000 UTC. An entry of "00 00 01 12" would start the calculation 36 hours from the start
of the data file.
Default: 1
Simultaneous trajectories can be calculated at multiple levels or starting locations. The GUI menu
can accommodate up to six simultaneous starting locations. Specification of additional locations
can be accomplished through the Special Simulations menu tab, or through manual editing of the
Control file and running the model outside of the GUI. When multiple starting locations are
specified, all trajectories start at the same time. A multiple trajectory in time option is available
through the Advanced menu through a namelist file parameter setting.
Trajectory starting position in degrees and decimal (West and South are negative). Height is
entered as meters above ground-level. An option to treat starting heights as relative to mean-sea-
level is available through the Advanced menu through a namelist file parameter setting.
Default: 48
Specifies the duration of the calculation in hours. Backward calculations are entered as negative
hours. A backward trajectory starts from the trajectory termination point and proceeds upwind.
Meteorological data are processed in reverse-time order.
5- Vertical motion option (0:data 1:isob 2:isen 3:dens 4:sigma 5:diverg 6:eta)
Default: 0
Indicates the vertical motion calculation method. The default "data" selection will use the
meteorological model's vertical velocity fields; other options include isobaric, isentropic, constant
density, constant internal sigma coordinate, computed from the velocity divergence, and a special
transformation to correct the vertical velocities when mapped from quasi-horizontal ETA
surfaces to HYSPLIT's internal terrain following sigma coordinate.
Default: 10000.0
Sets the vertical limit of the internal meteorological grid. If calculations are not required above a
certain level, fewer meteorological data are processed thus speeding up the computation.
Trajectories will terminate when they reach this level. A secondary use of this parameter is to set
the model's internal scaling height - the height at which the internal sigma surfaces go flat relative
to terrain. The default internal scaling height is set to 25 km but it is set to the top of the model
domain if the entry exceeds 25 km. Further, when meteorological data are provided on terrain
sigma surfaces it is assumed that the input data were scaled to a height of 20 km (RAMS) or 34.8
km (COAMPS). If a different height is required to decode the input data, it should be entered on
this line as the negative of the height. HYSPLIT's internal scaling height remains at 25 km unless
the absolute value of the domain top exceeds 25 km.
Default: 1
Number of simultaneous input meteorological files. The following two entries (directory and
name) will be repeated this number of times. A simulation will terminate when the computation
is off all of the grids in either space or time. Trajectory calculations will check the grid each time
step and use the finest resolution input data available at that location at that time. When multiple
meteorological grids have different resolution, there is an additional restriction that there should
be some overlap between the grids in time, otherwise it is not possible to transfer a trajectory
position from one grid to another.
Default: ( \main\sub\data\ )
Directory location of the meteorological file on the grid specified. Always terminate with the
appropriate slash (\ or /).
Default: file_name
Name of the file containing meteorological data. Located in the previous directory.
Default: ( \main\trajectory\output\ )
Directory location to which the text trajectory end-points file will be written. Always terminate
with the appropriate slash (\ or /).
Default: file_name
Table of Contents
Record #1
Record #3
Record #5
I6 - trajectory number
I6 - meteorological grid number or antecedent trajectory number
5I6 - year month day hour minute of the point
I6 - forecast hour at point
F8.1 - age of the trajectory in hours
2F8.3 - position latitude and longitude
F8.1 - position height in meters above ground
Table of Contents
Concentration / Help
The concentration menu tab is composed of six main sections: setting up the simulation, executing the
model, displaying the concentrations, various utility programs for converting the output to other formats,
configuring special simulations, and simulations in a multi-processor environment. The model can be
entirely configured and executed through the menu. However for experienced users, each component
may be run independently from the command line.
In the Concentration Setup menu, the entire purpose of the GUI is to configure the model's input
CONTROL file. This is a text file that configures the simulation parameters. Once the input parameters
are set to their desired value, the model is executed from the Run Standard Model menu tab. When
complete, the output window is closed and Display Options menu is used to draw and display the
concentration contours from the model's binary concentration output file. The Special Simulations menu
is used to configure several different customized simultaneous for ensemble applications, source-
receptor matrices, and some simple chemistry simulations. The Multi-processor tab invokes some of the
same special simulations but will only run under a multi-processor-computing environment. Normally
this is not an option available under MS Windows.
For inexperienced users, a review of the Quick Start Help menu is highly suggested, which goes through
a concentration computation step-by-step using the example meteorological data file.
Table of Contents
http://www.arl.noaa.gov/userguide/S360.htm12/5/2005 4:32:33 AM
Concentrations / Quick Start Help (S361)
The easiest way to run the model is to use the GUI menu to edit the model's input Control file. For the
purposes of this demonstration appropriate meteorological files are provided. If for some reason the
menu system is not available, the Control file can be created manually.
Step 1 - start the GUI menu system using \working\hysplit4.tcl or the desktop shortcut to Hysplit4. A
widget will appear with the HYSPLIT graphic and three button options: Menu, Help and Exit. On some
systems the graphic may be scrambled or the colors may be flat. Switching the PC display to VGA and
256 colors usually solves these problems. However it can be left alone as the faulty graphic will not
affect any of the other widgets or display graphics. Click on Menu.
Step 2 - The four main menus of Hysplit4 will appear: Meteorology, Trajectory, Concentration, and the
optional Advanced menu. An additional small widget underneath the main menu gives the current
Hysplit4 version information. Do not delete this widget as it will terminate the GUI. It provides the
reference frame for the model's standard output and messages. Click on Concentration.
Step 3 - Under the concentration menu there are also five options: concentration setup, run standard
model, concentration display, utility programs, and special simulations. In general, they should be
executed in sequential order. Click on Concentration Setup.
Step 4 - The Concentration Setup menu brings up similar starting information requirements as with the
trajectory menu. There are three additional sub-menus: Pollutant - that can be used set the emission rate,
duration, and start time of the emission; Grids - to set the location, resolution, levels, and averaging
times of the concentration output grid; and Deposition - to set the characteristics of each pollutant. Click
on Retrieve, enter name of sample pre-configured control file: sample_conc, then click on OK. After the
data entry widget is closed, click on Save and the setup menu will close.
Step 5 - From the main concentration menu tab select Run Standard Model, which copies the setup
configuration to the model's input Control file and starts the model simulation. Messages will appear on
standard output showing the progress of the calculation after the calculation has completed. Be patient as
concentration calculations may take considerably longer than trajectory calculations. Click on Exit to
close the message window. At that point the binary concentration output file is ready to be converted to
a graphical display.
Step 6 - Click on Display Options and then select Concentration to run a special program that converts
the binary concentration file to the Postscript file concplot.ps, suitable for printing. The display widget
contains multiple options for different pollutants (if defined), data grids, levels, and contour options.
These are discussed in more detail in the graphics section. For this example, accept the defaults and just
click on Execute Display. If the Ghostview Postscript viewer has been installed and properly associated
with .ps files, then it will be automatically invoked by the GUI. If the viewer does not open, it may be
necessary to manually edit the file hysplit4.tcl for the directory entry associated with the program
gsview32.exe. The output file can be printed directly on any Postscript device or printed through
Ghostscript/Ghostview. The first frame (12 hour average) of the four frame simulation (48 hour
duration) is shown in the illustration below.
Table of Contents
The entries in the Control file for air concentration simulations consist of four groups of input data. The
first data group is almost identical to the trajectory simulation and is described in the next section. The
other three groups define the pollutant emission characteristics, the concentration grid in terms of
spacing and integration interval, and the pollutant characteristics relevant to computing deposition and
removal processes. These latter three entries are accessed through the "Pollutant, Deposition, and Grids
Setup" tab. Each of the these sections contains a more detailed description of the input parameters as
well as the corresponding CONTROL file values that need to be set for command line simulations.
The concentration model input control file can be created using any text editor. However if the GUI is
not being used, it would be easier to let the model create the initial file based upon standard output
prompts. These are described in more detail below. When data entry is through the keyboard (a file
named CONTROL is not found), a Startup file is created. This contains a copy of the input, and which
later may be renamed to Control to permit direct editing and model execution without data entry. If you
are unsure as to a value required in an input field, just enter the forward slash (/) character, and the
indicated default value will be used. This default procedure is valid for all input fields except directory
and file names. An automatic default selection procedure is also available for certain input fields of the
Control file when they are set to zero. Those options are discussed in more detail below. Each input line
is numbered (only in this text) according to the order it appears in the file. A number in parenthesis after
the line number indicates that there is an input loop and multiple entry lines may be required depending
upon the value of the previous entry.
Default: 0 0 0 0
Enter the two digit values for the UTC time that the calculation is to start. Use 0's to start at the
beginning (or end) of the file according to the direction of the calculation. All zero values in this
field will force the calculation to use the time of the first (or last) record of the meteorological
data file. In the special case where year and month are zero, day and hour are treated as relative
to the start or end of the file. For example, the first record of the meteorological data file usually
starts at 0000 UTC. An entry of "00 00 01 12" would start the calculation 36 hours from the start
of the data file.
Default: 1
Single or multiple pollutant sources may be simultaneously tracked. The emission rate that is
specified in the pollutant menu is assigned to each source. If multiple sources are defined at the
same location, the emissions are distributed vertically in a layer between the current emission
height and the previous source emission height. The effective source will be a vertical line source
between the two heights. When multiple sources are in different locations, the pollutant is emitted
as a point source from each location at the height specified. Point and vertical line sources can be
mixed in the same simulation. The GUI menu can accommodate up to 6 simultaneous starting
locations. Specification of additional locations requires manual editing of the Control file. Area
source emissions can be specified from an input file: emission.txt. When this file is present in the
root directory, the emission parameters in the Control file are superceded by the emission rates
specified in the file. More information on this file structure can be found in the advanced help
section.
Position in degrees and decimal (West and South are negative). Height is entered as meters above
ground level unless the mean-sea-level flag has been set.
The optional 4th (emission rate - units per hour) and 5th (emission area - square meters) columns
on this input line can be used to supercede the value of the emission rate (line 12-2) when
multiple sources are defined, otherwise all sources have the same rate as specified on line 12-2.
The 5th column defines the virtual size of the source: point sources default to "0".
Default: 48
Sets the duration of the calculation in hours. Backward calculations are configured by setting the
run time to a negative value. See the discussion in the advanced help section on backward
"dispersion" calculations.
5- Vertical motion option (0:data 1:isob 2:isen 3:dens 4:sigma 5:diverg 6:eta)
Default: 0
Indicates the vertical motion calculation method. The default "data" selection will use the
meteorological model's vertical velocity fields; other options include isobaric, isentropic, constant
density, constant internal sigma coordinate, computed from the velocity divergence, and a special
transformation to correct the vertical velocities when mapped from quasi-horizontal ETA
surfaces to HYSPLIT's internal terrain following sigma coordinate.
Default: 10000.0
Sets the vertical limit of the internal meteorological grid. If calculations are not required above a
certain level, fewer meteorological data are processed thus speeding up the computation.
Trajectories will terminate when they reach this level. A secondary use of this parameter is to set
the model's internal scaling height - the height at which the internal sigma surfaces go flat relative
to terrain. The default internal scaling height is set to 25 km but it is set to the top of the model
domain if the entry exceeds 25 km. Further, when meteorological data are provided on terrain
sigma surfaces it is assumed that the input data were scaled to a height of 20 km (RAMS) or 34.8
km (COAMPS). If a different height is required to decode the input data, it should be entered on
this line as the negative of the height. HYSPLIT's internal scaling height remains at 25 km unless
the absolute value of the domain top exceeds 25 km.
Default: 1
Number of simultaneous input meteorological files. The following two entries (directory and
name) will be repeated this number of times. A simulation will terminate when the computation
is off all of the grids in either space or time. Calculations will check the grid each time step and
use the finest resolution input data available at that location at that time. When multiple
meteorological grids have different resolution, there is an additional restriction that there should
be some overlap between the grids in time, otherwise it is not possible to transfer a particle
position from one grid to another.
Default: ( \main\sub\data\ )
Directory location of the meteorological file on the grid specified. Always terminate with the
appropriate slash (\ or /).
Default: file_name
Name of the file containing meteorological data. Located in the previous directory.
Table of Contents
Note that up to 7 pollutant species may be defined by changing the Num parameter. However, in the
current version, the pollutant and deposition menus must both reference the same number of species.
Multiple species simulations are calculated independently, hence there is no computational benefit by
doing two different simulations or combining both species in one simulation. The multiple species
option is primarily used for chemical transformation simulations. A simple example is available from the
configuration menu checkbox of "10% per hour", which transforms species #1 to species #2 at a rate of
10% per hour. The transformation occurs on the same particle and is discussed in more detail in the
Advanced Applications section. More complex transformations require a linkage with compatible
external modules. None are available at this time for public distribution.
Table of Contents
http://www.arl.noaa.gov/userguide/S311.htm12/5/2005 4:33:18 AM
Concentration / Pollutant Definition Setup (S312)
Default: 1
Multiple pollutant species may be defined for emissions. Each pollutant is assigned to its own
particle or puff and therefore may behave differently due to deposition or other pollutant specific
characteristics. Each will be tracked on its own concentration grid. The following four entries are
repeated for each pollutant defined.
Default: TEST
Provides a four-character label that can be used to identify the pollutant. The label is written with
the concentration output grid to identify output records associated with that pollutant and will
appear in display labels. Additional user supplied deposition and chemistry calculations may be
keyed to this identification string.
Default: 1.0
Mass units released each hour. Units are arbitrary except when specific chemical transformation
subroutines are associated with the calculation. Output air concentration units will be in the same
units as specified on this line. For instance an input of kg/hr results in an output of kg/m3. When
multiple sources are defined this rate is assigned to all sources unless the optional parameters are
present on line 3(1).
Default: 1.0
The duration of emission may be defined in fractional hours. An emission duration of less than
one time-step will be emitted over one time-step with a total emission that would yield the
requested rate over the emission duration.
The previously specified hours of emission start at this time. An entry of zero's in the field, when
input is read from a file, will also result in the selection of the default values that will correspond
with the starting time of the meteorological data file. Day and hour are treated as relative to the
file start when month is set to zero.
This menu is only designed to input point source emission rates. Unless additional input values are
provided in the control file after each emission location, the same rate will apply to all defined point
sources for the duration of the emission. When more complex emission scenarios are required, emission
data can be read in from a file that defines a diurnal emission cycle for any number of pollutants at any
number of locations. If the emission rate is to vary in time beyond one diurnal cycle, there is another
input file that can be defined to set a new rate with each emission cycle. In this latter scenario the rate as
well as the location may be changed.
Table of Contents
Dispersion calculations are performed on the computational (meteorological) grid without regard to the
definition or location of any concentration grid. Therefore it is possible to complete a simulation and
have no results to view if the concentration grid was in the wrong location. In addition, very small
concentration grid spacing will reduce the model's integration time step and may result is substantially
longer simulation clock times.
Default: 1
Multiple or nested grids may be defined. The concentration output grids are treated
independently. The following 10 entries will be repeated for each grid defined.
Sets the center position of the concentration sampling grid in degrees and decimal. Input of zero's
will result in selection of the default value, the location of the emission source. Sometimes it may
be desirable to move the grid center location downwind near the center of the projected plume
position.
Sets the interval in degrees between nodes of the sampling grid. Puffs must pass over a node to
contribute concentration to that point and therefore if the spacing is too wide, they may pass
between intersection points. Particle model calculations represent grid-cell averages, where each
cell is centered on a node position, with its dimensions equal to the grid spacing. Finer resolution
concentration grids require correspondingly finer integration time-steps. This may be mitigated to
some extent by limiting fine resolution grids to only the first few hours of the simulation.
Sets the total span of the grid in each direction. For instance, a span of 10 degrees would cover 5
degrees on each side of the center grid location. A plume that goes off the grid would have cutoff
appearance, which can sometimes be mitigated by moving the grid center further downwind.
Default: ( \main\sub\output\ )
Directory to which the binary concentration output file for this grid is written. As in other
directory entries a terminating (\) slash is required.
Default: file_name
Name of the concentration output file for each grid. See Section 6 for a description of the format
Default: 1
The number of vertical levels in the concentration grid including the ground surface level if
deposition output is required.
Default: 50
Output grid levels may be defined in any order for the puff model as long as the deposition level
(0) comes first (a height of zero indicates deposition output). Air concentrations must have a non-
zero height defined. A height for the puff model indicates the concentration at that level. A height
for the particle model indicates the average concentration between that level and the previous
level (or the ground for the first level). Therefore heights for the particle model need to be
defined in ascending order. Note that the default is to treat the levels as above-ground-level
(AGL) unless the MSL (above Mean-Sea-Level) flag has been set (see advanced configuration).
Each concentration grid may have a different starting, stopping, and output averaging time. Zero
entry will result in setting the default values. "Backward" calculations require that the stop time
should come before the start time.
Default: 12 31 24 60
After this time no more concentration records are written. Early termination on a high resolution
grid (after the plume has moved away from the source) is an effective way of speeding up the
computation for high resolution output near the source because once turned-off that particular
grid resolution is no longer used for time-step computations.
Default: 0 24 0
Each grid may have its own sampling or averaging interval. The interval can be of two different
types: averaging (type=0) or snapshot (type=1). Averaging will produce output averaged over the
specified interval. Snapshot will give the instantaneous output at the output interval. For instance
you may want to define a concentration grid that produces 24-hour average air concentrations for
the duration of the simulation which for the default case of a 2-day simulation will result in 2
output maps, one for each day. Each defined grid can have a different output type and interval.
There is one special case exception when the snapshot value is less than zero, it represents the
averaging time in hours and the output interval time represents the interval at which the average
concentration is output. For instance a setting of {-1 6 0} would output a one-hour average
concentration every six hours.
Table of Contents
Deposition parameters must be defined for each pollutant species emitted. Each species may
behave differently for deposition calculations. Each will be tracked on its own concentration grid.
The following five lines are repeated for each pollutant defined. The number here must be
identical to the number on line 10. Deposition is turned off for pollutants by an entry of zero in
all fields.
These three entries are used to define the pollutant as a particle for gravitational settling and wet
removal calculations. A value of zero in any field will cause the pollutant to be treated as a gas.
All three fields must be defined (>0) for particle deposition calculations. However, these values
only need to be correct only if gravitational settling or resistance deposition is to be computed by
the model. Otherwise a nominal value of 1.0 may be assigned as the default for each entry to
define the pollutant as a particle. If a dry deposition velocity is specified as the first entry in the
next line (28), then that value is used as the particle settling velocity rather than the value
computed from the particle diameter and density.
28(2)- Deposition velocity (m/s), Pollutant molecular weight (Gram/Mole), Surface Reactivity Ratio,
Diffusivity Ratio, Effective Henry's Constant
Dry deposition calculations are performed in the lowest model layer based upon the relation that
the deposition flux equals the velocity times the ground-level air concentration. This calculation
is available for gases and particles. The dry deposition velocity can be set directly for each
pollutant by entering a non-zero value in the first field. The velocity can also be calculated by the
model using the resistance method which requires setting the remaining four parameters
(molecular weight, surface reactivity, diffusivity, and the effective Henry's constant). See the
table below for more information.
29(3)- Wet Removal: Actual Henry's constant, In-cloud (L/L), Below-cloud (1/s)
Henry's constant defines the wet removal process for soluble gases. It is defined only as a first-
order process by a non-zero value in the field. Wet removal of particles is defined by non-zero
values for the in-cloud and below-cloud parameters. In-cloud removal is defined as a ratio of the
pollutant in air (g/liter of air in the cloud layer) to that in rain (g/liter) measured at the ground.
Below-cloud removal is defined through a removal time constant.
Default: 0.0
A non-zero value in this field initiates the decay process of both airborne and deposited pollutants.
Default: 0.0
Suggested :1.0E-06
A non-zero value for the re-suspension factor causes deposited pollutants to be re-emitted based
upon soil conditions, wind velocity, and particle type. Pollutant re-suspension requires the
definition of a deposition grid, as the pollutant is re-emitted from previously deposited material.
Under most circumstances, the deposition should be accumulated on the grid for the entire
duration of the simulation. Note that the air concentration and deposition grids may be defined at
different temporal and spatial scales.
Table of Contents
Successful completion of a simulation will show a similar message. Additional run-time diagnostic
messages and other error messages are always written to a file called MESSAGE. This file may be
viewed through one of the Advanced Menu tabs. Depending upon the nature of the error message,
perhaps a failure in the model initialization process, error messages may also appear in above window.
Once the model has completed, press Exit to close the window.
Table of Contents
Normally only one input file is shown, unless multiple files have been defined in the Concentration
Setup menu. The default output file name is shown and unless the box is checked all frames (time
periods and/or levels) will be output to that one file. The program uses the map background file, arlmap,
which by default is located in the \graphics directory. Other customized map background files could be
defined. Some of these higher resolution map background files are available from the HYSPLIT
download web page. For multiple pollutant files, only one pollutant may be selected for display by
individual levels, or averaged between selected levels. These levels must have been predefined in the
Concentration Setup menu. Multipliers can be defined for deposition or air concentrations. Normally
these values would default to 1.0, unless it is desired to change the output units (for instance, g/m3 to ug/
m3 would require a multiplier of 106). Contours can be determined dynamically by the program,
changing with each map, or fixed to be the same for all maps. A user can also set a maximum value as
the base 10 exponent.
The Postscript conversion program (concplot), found in the \concmdl directory, reads the binary
concentration output file, calculates the most optimum map for display, and creates the output file
concplot.ps. Multiple pollutant species or levels can be accommodated. Most routine variations can be
invoked from the GUI. More complicated conversions should be run from the command line using the
following optional parameters:
Selecting the GIS checkbox creates an ASCII text file for each output time period that consists of
the value and latitude-longitude points along each contour. This file can be converted to an
Arcview Shapefile or converted for other GIS applications through the utility menu "GIS to
Shapefile" ". The view checkbox would be disabled to do just the GIS conversion without
opening the the Postscript viewer.
= 0 - Represents the height (meters) below which no data will be processed for display. The level
information is interpreted according to the display (-d) definition.
● -c[Contours: (0)]
= 0 - Dynamic contour values (10x intervals) are optimized for each map.
= 1 - Fixed contour values (10x intervals) are the same for all maps.
= 2 - Dynamic contour values (constant interval) are optimized for each map.
= 3 - Fixed contour values (constant intercal) are the same for all maps.
= 4 - The contours are set by the user in conjunction with -v option.
= 1 - All output levels that fall between the bottom and top display heights are shown as
individual frames. A single level will be displayed if both bottom and top heights equal the
calculation level or they bracket that level. Deposition plots are produced if level zero data are
available in the concentration file and the display height is set to 0.
= 2 - The concentrations at all levels between the specified range are averaged to produce one
output frame per time period. If deposition data is available and a plot is required in addition to
the air concentrations, then the bottom height should be set to 0. Deposition is not averaged with
air concentrations.
= 1 - A custom output format in which all the air concentrations have been converted to time-
integrated units and vertically averaged for all levels between the bottom and top heights.
= ( ) - Auto selection procedure draws four circles with the distance between them determined by
the program algorithm.
= # - Specifies the number of circles with the default (50 km) distance interval.
= number:distance - specifies the number of circles and the distance interval between circles. For
the special case of zero circles with a distance specified (e.g. -0:1500) the program will fix the
map with the top and bottom edge at that distance from the center.
= lat:lon - Forces the center of the map to be at the specific latitude-longitude point rather than
the default source location. This is normally used in conjunction with the -g option to get the
same map each time or when there are multiple source locations.
= Name of the binary concentration file for which the graphics will be produced. Default name
{cdump} or user defined}.
The program first searches the local directory, then the ..\graphics directory for the name of the
default map background file (arlmap). Set this parameter to select the directory/name of any map
background file of compatible format.
The default plot symbol over the source location is an open star. This may be changed to any
value defined in the psplot ZapfDingbats library. For instance a blank, or no source symbol
would be defined as -l32
Normally the map projection is automatically determined based upon the size and latitude of the
concentration pattern. Sometimes this procedure fails to produce an acceptable map and in these
situations it may be necessary to force a map projection.
The name of the Postscript output file defaults to concplot.ps unless it is set to a {user defined}
value.
The suffix defines the character string that replaces the default "ps" in the output file name. A
different suffix does not change the nature of the file. It remains Postscript. The suffix is used in
multi-user environments to maintain multiple independent output streams.
By defining a text file with a comma or space delimited format consisting of one or more records
of the four real numbers, identity, latitude, longitude, and value, the program will plot the values
at the given locations. The same values are plotted on all maps.
= 0 - No deposition plots are produced even if the model produced deposition output.
= 1 - One deposition plot is produced for each time period.
= 2 - The deposition is summed such that each new time period represents the total accumulation.
= 3 - Similar to =2, deposition is accumulated to the end of the simulation and but only one plot
is produced at the end.
= {Species Number} - Only one pollutant species may be displayed per plot sequence if multiple
species were created during a simulation. However, an entry of "0" will cause all species
concentrations to be summed for display.
= 99999 - Represents the height (m) above which no data will be processed for display. The level
is interpreted according to the display definition.
Defines the character string for the units label. Can also be modified using the labels.cfg file.
If the contour values are user set (-c4), then it is also possible to define the four individual
contours explicitly through this option. For instance -v4+3+2+1, would define the contours 4, 3,
2, and 1.
= 0.25 - default
= X - User selected value
= 0.0 - none
= 50 - Standard resolution.
= 100 - High resolution map (less white space around the concentration pattern)
Many of the Postscript graphics programs have label information that can be customized to some extent.
This is accomplished by placing a file called Labels.cfg in the startup directory which contains the
following valid entries (all in single quotes terminated by &) replacing the new string with the desired
text. A sample file called Labels.bak may be found in the relevant directory. Not all label strings are
valid with every plotting program.
Additional supplemental text may be added at the bottom of the graphic by creating a file called
MAPTEXT.CFG, also to be located in the startup directory. This is a generic file used by all plotting
programs but each program will used different lines in its display. The file can be created and edited
Table of Contents
The menu consists of the standard display options such as the map background file, output file name, and
zoom factor, plus the selection of the extraction method: source or receptor. A latitude and longitude point
needs to be entered for all extractions. Selection of the "source" extraction method means that the location
entered is a receptor and the output map is a contour map of how much air concentration each source
contributes to the selected receptor. The "receptor" extraction method means that the location entered is a
source location and the output map is a contour map of air concentrations from that source. The "receptor"
option is just a conventional air concentration simulation. Note that turning on the "normalization" flag
divides all concentrations by the sum of all concentrations at each grid point, resulting in a map that
represents a fractional contribution.
Table of Contents
The menu includes some of the standard display program (concplot) mapping choices, such as background
file, output file name, and zoom factor. One critical difference is that there is an option called the Number of
aggregation periods. By default this value is set to one, which means that only the ensemble members for one
time period are aggregated together to produce the probability display. Hence there would be an independent
probability map for each time period. However, multiple time periods may be combined to produce a single
probability plot. The entry represents the number of time periods, not the actual time span. For instance, if the
model output is set to produce a one-hour average and the model is run for 24 hours, then each ensemble
member will have 24 time periods of output. By default the probability output will represent the ensemble
member variation for each hour, that is 24 frames of output will be produced. However if the aggregation
period is set to 24, then all output times will be combined into one output frame and the ensemble result will
represent the hourly variations as well as the member variations.
1. The number of ensemble members at each grid point with concentrations greater than zero shows the
spatial distribution of the Number of Ensemble members.
2. The probability of concentration produces contours that give the probability of exceeding a fixed
concentration value at one of three levels: 1% of the maximum concentration, 10% of the maximum,
and the maximum concentration. The maximum is determined to be the first concentration to a power
of 10 that is less than the actual maximum value. The concentration level for the probability display is
shown on the graphic with the pollutant identification field set to something like C14, where 14
represents the Concentration to the power of 10-14.
3. The concentration at different preset percentiles shows contours of areas that concentrations will be
exceeded only at the given probability level. The probability level choices are 50, 75, and 90 percent.
The probval extraction program will always produce all the probability variations, one to each output file, for
a given aggregation period. These files may be plotted individually from the command line using concplot.
The probval output files contain the following information:
Table of Contents
The "Horizontal" option results in the conventional graphic shown below. There is one black dot for
each particle. The size of the dot varies according to the pollutant mass assigned to the particle. All
examples are 24 hours after the start of the test simulation.
The "vertical" option shows an integrated particle distribution view from the south looking north (top
panel) and from the east looking west (bottom panel). All particles in the computational domain are
shown.
The "cross-section" view is a combination of the horizontal and vertical views. The top panel shows the
horizontal particle distribution, while the bottom panel shows the vertical distribution along the red
regression line through the plume. Again all particles are shown regardless of their distance from the
regression line. The bottom panel view is from left to right in increasing longitude, regardless of the
orientation of the regression line.
Table of Contents
Table of Contents
http://www.arl.noaa.gov/userguide/S343.htm12/5/2005 4:34:49 AM
Concentration / Utility Programs / Convert to ASCII (S341)
The Concentration Setup menu determines the file name selection option on the GUI. There are some
additional checkboxes that correspond to various command line conversion options.
This option converts the entire binary input file, including all index records, to an ascii output file
with the name {input file}.txt. This option corresponds to the Single File checkbox of the GUI
menu. The output file format follows the binary file format record-by-record using the following
format conventions.
Setting this flag turns off the writing of the first output record, which is the column label field:
DAY HOUR LAT LON SPECIES-LEVEL.
The default base name for the output file is the input file name. A new output file is created for
each sampling period, where the name of the file is composed of the {base name}_{Julian day}_
{hour} of the sample ending time.
Setting the zero flag causes the program to output the concentration values all all grid points,
including the ones that are zero.
Each output record is identified by the day (Julian: 1 to 365) and hour (UTC) of the ending time of each
sample. The ASCII conversion of the first file generated by the sample calculation is shown below in the
illustration.
Table of Contents
Similar to the other menus in the utility section, the input concentration file must be defined by the
Concentration Setup menu. The menu options correspond to the command line options of the con2stn
extraction program. There are two options that can be used to define the extraction location. A station
location can be defined directly as an entry in the menu, or a list of stations can be defined in an input
file. In this example illustration, a file has been defined with three locations that are within the plume of
the example simulation. The file consists of three records, one for each station:
The extraction program is called con2stn and for these three stations produces the output file shown
below, called by default con2stn.txt. In contrast to the simulation shown in all the previous examples, in
this case the output averaging time was decreased from 12 hours to one hour, to generate a smoother
looking graphic.
The output file shows the Julian day, month, day, and hour of the sample start; day and hour of sample
ending time, and the concentrations for each station (location selected by latitude-longitude). The format
of each output record is as follows:
F8.3, 6I4 - Starting: Julian day, year, month, day, hour; Ending: day, hour
The lower section of the GUI is used to create a simple time series concentration plot of the
concentration time series. One or more stations may be plotted and the option is also available through
the command line. The option is selected from the Display Postscript Time Series checkbox. The
program, timeplot, reads the data file produced by the con2stn conversion program and plots the
concentration values to the timeplot.ps output file. The illustration for the previous text file is shown
below.
There are only two plot options supported through the GUI: linear or logarithmic ordinate scaling. In the
linear scaling case, as shown above, the ordinate units must be integer whole numbers, and the minimum
value will always be zero. Therefore it may be necessary to specify a units conversion factor, in this case
1015, to create data in the text file that can be plotted. With the log scaling option, the conversion factor
can be set to 1.0, and the ordinate scale will cover the appropriate order-of-magnitude range to plot all
the data.
The program can be run from the command line, through interactive prompts from the keyboard. The
command line argument syntax is that there should be no space between the switch and options. The
command line arguments can appear in any order.
Unspecified file names will result in a standard input prompt. The default interpolation method (-xn) is
to use the value at nearest grid point to each latitude-longitude position. The station positions can be
read from a file (space or comma delimited) with the first field being an integer that represents the
location identification, followed by the location latitude and longitude. Level and pollutant index values
can be selected for files with multiple levels and species.
Examples:
2) Read the model output file 'cdump' and write text output to file 'clist.txt' for station #517 at 53N 85W.
000
000
4) As in 1) but linear interpolate concentration to station rather than using the nearest grid point
000
● -i[input concentration file name] contains data in the same format as output from con2stn
● -n[sequential station number] for files with multiple stations select the station to plot; default for
multiple stations is to plot all stations; several stations can be selected to plot by appending
station numbers with the plus symbol: hence -n3+5+6 will plot stations 3, 5, and 6.
● -y[The default is linear ordinate scaling. The flag sets y-axis log scaling.]
Table of Contents
Run Matrix
Although the setup of the concentration matrix calculation is similar to that of the trajectory matrix
calculation, there is an additional option that can be set in the Advanced Menu configuration tab that
changes the nature of the concentration output file to produce a source-receptor matrix. This will be
discussed further below. The matrix calculation is a way to set up the CONTROL file for multiple
starting locations that may exceed the GUI limit of 6 under the Concentration Setup menu tab. Hundreds
or thousands of starting points may be specified. The Run Matrix menu tab first runs a program that
reads the CONTROL file with three starting locations and then rewrites the same CONTROL file with
multiple locations. The multiple locations are computed from the number of starting points that fall in
the domain between starting point 1 and starting point 2, where each new location is offset is the same as
that between starting locations 1 and 3. For instance, if the original control file has three starting
locations: #1 at 40N, 90W; #2 at 50N, 80W, and #3 at 41N, 89W; then the matrix processing results in a
Control file with 121 starting locations, all one degree apart, all between 40N 90W and 50N 80W.
In the normal model execution mode, the concentration contributions from multiple sources are summed
on the concentration grid, hence it is not possible to determine the fraction of the material comes from
each source location. This can be seen in the illustration below using the above configuration for the first
12 hours of the sample case.
However, if the "Matrix" conversion module is checked in the Advanced Concentration Configuration
menu tab, then the multiple source simulation maintains the identity of each source in the concentration
output file. The Display Matrix menu tab permits extraction of information for individual sources or
receptors from this special concentration output file. The results of the same simulation are shown in the
illustration below. In this case the receptor check-box was set and the receptor location was identified as
45.0, -75.0 with normalization. Therefore the graphic illustrates the fractional contribution of each
region to the first 12 hour average concentration at the designated receptor.
The following table illustrates the HYSPLIT matrix configuration. Emissions occur from each of N
source locations and the receptors represent the concentration grid of M nodes. A single concentration
output file is produced where each source contributes to its own concentration grid of M receptors.
When selecting a "source" display, the M columns from the source location (row) represent the
downwind concentration pattern for that source. When the receptor location (column) is selected, the
contours represent the concentrations (each row of that column) contributing to that receptor from each
of the source locations. Source and receptor grids should be of comparable resolution.
Run Ensemble
The ensemble form of the model, an independent executable, is similar to the trajectory version of the
ensemble. The meteorological grid is offset in either X, Y, and Z for each member of the ensemble. The
model automatically starts each member on a single processor in a multi-processor environment or
cycles through the simulations on one processor. The calculation offset for each member of the
ensemble is determined by the grid factor as defined in the Advanced Concentration Configuration Tab.
The default offset is one meteorological grid point in the horizontal and 0.01 sigma units in the vertical.
The result is 27 ensemble members for all offsets. The normal Setup Menu tab is used to configure the
CONTROL file. Note that if fewer than 27 processors are available, the ensemble configuration menu
permits starting the calculation at any ensemble member number within the valid range. Because the
ensemble calculation offsets the starting point, it is suggested that for ground-level sources, the starting
point height should be at least 0.01 sigma (about 250 m) above ground. The model simulation will result
in 27 concentration output files named according the file name setting in the control file "{cdump}.{001
to 027}" with a suffix equivalent to the ensemble member number. On a single processor system, the
calculation may take some. The menu will be locked until the simulation has completed. A message file
window will open after termination. Computational progress may be monitored by noting the generation
of new concentration output and message files with the ensemble number suffix in the /working
directory. The concentration output from each member can be displayed through the concentration
display menu tab. However, to display the probabilities associated with the multiple simulations, it is
necessary to pre-process the data through the Display Ensemble menu tab. Using the default
configurations for the sample simulation, the illustration below represents the 90th percentile
concentrations aggregating all four output time periods.
For instance the blue contour in this 90th percentile plot represents the region in which only 10% of the
ensemble members have air concentrations greater than 10-15.
A model for the emission of PM10 dust has been constructed (Draxler, R.R, Gillette, D.A., Kirkpatrick,
J.S., Heller, J., 2001, Estimating PM10 Air Concentrations from Dust Storms in Iraq, Kuwait, and Saudi
Arabia, Atmospheric Environment, Vol. 35, 4315-4330) using the concept of a threshold friction
velocity which is dependent on surface roughness. Surface roughness was correlated with
geomorphology or soil properties and a dust emission rate is computed where the local wind velocity
exceeds the threshold velocity for the soil characteristics of that emission cell. A pre-processing program
was developed that accesses the HYSPLIT land-use file over any selected domain and modify the input
CONTROL file such that each emission point entry corresponds with a "desert" (active sand sheet) land-
use grid cell. The original PM10 flux equation was replaced by a more generic relationship (Westphal, D.
L., Toon, O.B., Carlson, T.N., 1987. A two-dimensional numerical investigation of the dynamics and
microphysics of Saharan dust storms. J. Geophys. Res., 92, 3027-3029).
The dust storm simulation is configured in the same way as the matrix calculation in that it is necessary
to define three source locations, the first two representing the limits of the domain, and the third defining
the emission grid resolution. The pre-processor then finds all emission points within that domain that
have a desert category and modify the CONTROL file accordingly. The dust box must be checked in the
advanced configuration menu to compute the PM10 emission rate. As an example, we can configure the
model to run the large Mongolian dust storm of April 2001. An animation of the calculation results can
be downloaded. To run the same simulation it will be necessary to obtain the first two weeks of northern-
hemisphere meteorological analysis data (FNL.NH.APR01.001). A pre-configured CONTROL file
(dust_conc) should be retrieved from the working directory. The CONTROL file defines the emission
domain by the three starting locations: 35N-90W to 50N-120W with the grid increment to 36N-91W.
There is no point in defining an emission grid of less than one-degree resolution because the resolution
of the land-use data file is one-degree and the meteorological data is closer to two-degrees. Once the
model is setup for the simulation, including the dust check-box in the configuration menu, execute the
model from the Special Simulations / Run Dust Storm menu tab. The window shown below will open to
indicate the revision of the CONTROL file.
The message indicates that the initial 3-location CONTROL file was reconfigured by the dustbdy
program for 105 source locations. That means in the domain specified, 105 one-degree latititude-
longitude grid cells were found to have a desert land-use category. If none are found, then the
CONTROL file is deleted to prevent model execution. Click on Yes or No to continue - yes just deletes
the window. The model execution will then start. PM10 pollutant dust particles are only emitted from
those 105 cells where the wind speed exceeds the emission threshold. Therefore it is possible to have
simulations with no emissions. An example of the output after 24 hours simulation time is shown in the
illustration below.
The concentrations represent a 3-hour average from 21 to 24 hours after the start of the simulations. It is
not possible to say exactly from when or where particles are emitted except to note that the 105 potential
source locations are shown. The emission algorithm emits in units of grams, but the in configuring the
concentration display, the units were changed to ug by defining a conversion factor of 106. Maximum
concentrations are on the-order-of 100, but the layer was defined with a depth of 3 km to facilitate
comparison with satellite observations. The simulation could be rerun with a smaller layer to obtain
concentrations more representative of near-ground-level exposures.
Table of Contents
The standard concentration model can be run on multi-processor systems. As pollutant particles are
released during the simulation, they are parsed out in sequence to the available processors. The
calculation proceeds independently until the end of a concentration averaging period. At this point, the
concentrations from each processor are summed, and only one concentration output file is updated. The
MPI version can be quite effective in speeding up simulations requiring the release of many particles.
No special configuration or control file is required and output can be viewed using the standard
concentration display menu.
The multiprocessor version of the matrix calculation is configured the same way as for a single
processor system. The MPI calculation proceeds as described above for the standard MPI model
simulation.
The ensemble model automatically starts each member on a single processor in a multi-processor
environment. The multiprocessor version of the ensemble calculation is configured the same way as for
a single processor system. Note that if fewer than 27 processors are available, the ensemble
configuration menu permits starting the calculation at any ensemble member number within the valid
range of 001 to 027.
Table of Contents
http://www.arl.noaa.gov/userguide/S358.htm12/5/2005 4:36:49 AM
Concentration / File Format (S363)
Record #1
Record #3
Record #4
Record #5
Table of Contents
1. The Configuration Setup menu permits the creation and modification of the SETUP.CFG
namelist file for either Trajectory or Air Concentration calculations. The namelist file is a
variable length file that is used to set additional parameters that can be used to modify the nature
of the simulation. The namelist file is not required because all the namelist variables take on
default values when the SETUP.CFG file is not found. The same namelist file can be used for
either trajectory or air concentration simulations but only certain variables are applicable to each
simulation. Supplemental plot labeling options are available, a menu to configure a dynamic
sampler that can move in space and time for use with the concentration simulation, and a menu to
configure the default directory structure and location of executable programs used by the GUI.
2. The Particle Editor menu opens a special viewing program that will display the pollutant particle
positions and satellite data. The editor can be used to adjust the particle positions to obtain a
better correspondence with the satellite observations. The model calculation can then be restarted
with the adjusted pollutant particle positions. The particle position file, called PARDUMP by
default, is a snapshot of all the pollutant particles at a given time. Its creation is controlled
through the Configuration menu.
3. The FTP satellite data menu opens up an anonymous FTP window to access the current satellite
archives for TOMS aerosol index and today's AVHRR optical depth. These data can then be
displayed through the Particle Editor menu.
4. The View MESSAGE menu is used to display the diagnostic message file. For all trajectory or
concentration simulations, diagnostic information is written to standard output until the
initialization process has completed. At that point the MESSAGE file is opened and subsequent
diagnostic and certain error messages are written to this file. If the model does not complete
properly, some information may be obtained from this file.
Table of Contents
http://www.arl.noaa.gov/userguide/S440.htm12/5/2005 4:43:05 AM
Advanced / Configuration Setup (S413)
Table of Contents
http://www.arl.noaa.gov/userguide/S413.htm12/5/2005 4:43:44 AM
Advanced / Configuration Setup / Trajectory (S411)
When using the GUI, the namelist file will be deleted and all variables are returned to their default value
by selecting the "Reset" button. The following summarizes the namelist variables and their
corresponding section in the GUI menu. Not all variables can be set through the menu.
TRATIO (0.75) - defines the fraction of a grid cell that a particle or trajectory is permitted to transit in
one advection time step. Reducing this value will reduce the time step and increase computational times.
Smaller time steps result in less integration error. Integration errors can be estimated by computing a
backward trajectory from the forward trajectory end position and computing the ratio of the distance
between that endpoint and the original starting point divided by the total forward and backward
trajectory distance.
DELT (0.0) - is used to set the integration time step to a fixed value in minutes from 1 to 60. It should be
evenly divisible into 60. The default value of zero causes the program to compute the time step each
hour according to the maximum wind speed, meteorological and concentration grid spacing, and the
TRATIO parameter. The fixed time step option should only be used when strong winds in regions not
relevant to the dispersion simulation (perhaps the upper troposphere) are causing the model to run with
small time steps. Improper specification of the time step could cause aliasing errors in advection and
underestimation of air concentrations.
MGMIN (10) - is the minimum size in grid units of the meteorological sub-grid. The sub-grid is set
dynamically during the calculation and depends upon the horizontal distribution of end-points and the
wind speed. Larger sub-grids than necessary will slow down the calculation by forcing the processing of
meteorological data in regions where no transport or dispersion calculations are being performed. In
some situations, such as when the computation is between meteorological data files that have no
temporal overlap, the model may try to reload meteorological data with a new sub-grid. This will result
in a fatal error. One solution to this error would be to increase the minimum grid size larger than the
meteorological grid to force a full-grid data load.
KMSL (0) - sets the default for input heights to be relative to the terrain height of the meteorological
model. Hence input heights are specified as AGL. Setting this parameter to "1" forces the model to
subtract the local terrain height from source input heights before further processing. Hence input heights
should be specified as relative to Mean Sea Level (MSL). In concentration simulations, the MSL option
also forces the vertical concentration grid heights to be considered relative to mean sea level. The special
option (xBL) sets KMSL to 2 and treats the input height as a fraction of the boundary layer (or mixed
layer) depth at the trajectory starting location and time. This option is not valid with any multiple
trajectory in time configurations. Valid starting heights can be defined as any non-zero fraction less than
2.0.
NSTR (0) - Hours between trajectory starts for multiple trajectory-in-time simulations. When greater
than zero, new trajectories will be started from the original starting location every NSTR hours from the
initial trajectory starting time. See the special trajectory simulation section for more information.
NVER (0) - Number of vertical levels that trajectories are restarted when trajectories for multiple
trajectory-in-time-and-space simulations. When greater than zero, new trajectories will be started at this
number of levels from the endpoint position at the NSTR interval. The level heights are set in the
CONTROL file and must match the number of starting locations. See the special trajectory simulation
section for more information.
MHRS (9999) - Sets the maximum temporal trajectory restart period. For instance if you want to
compute one month's worth of two-day trajectories, then the run duration would be 720 hours, MHRS
would be set to 672 hours (720-48), and KHMAX (see below) would be set to 48 hours.
TOUT(60) - sets the time interval in minutes at which trajectory end-point positions will be written to
the output file. Output intervals of less than 60 minutes can be selected. This will force the internal time
step to be an even multiple of the output interval.
Sets the option to write the value of certain meteorological variables along the trajectory to the trajectory
output file. The marker variables are set to (1) to turn on the option. Multiple variables may be selected
for simultaneous output but only one variable may be plotted. If multiple variables are selected in
conjunction with the trajectory display option, then only the last variable output will be shown in the
graphic. The variable output order is fixed in the program and cannot be changed.
● TM_PRES (0) - diagnostic marker variables to output atmospheric pressure (1) along the
trajectory
● TM_TPOT (0) - potential temperature (1) in degrees Kelvin
● TM_TAMB (0) - ambient temperature (1) in degrees Kelvin
● TM_RAIN (0) - rainfall (1) in mm per hour
● TM_MIXD (0) - mixed layer depth (1) in meters.
● TM_RELH (0) - relative humidity (1) in percent.
● TM_DSWF (0) - downward solar radiation flux (1) in watts.
● TM_TERR (0) - terrain height (1) in meters required for the trajectory plot to show underlying
terrain.
Sets the dimensions at which the meteorological grid will be offset for the ensemble calculation. Only
one offset (+ or -) in either X, Y, or Z is applied per member.>/p>
DXF (1.0) - west to east grid factor for offsetting the meteorological grid in the ensemble calculation.
DYF (1.0) - south to north grid factor for offsetting the meteorological grid in the ensemble calculation
AA (30), BB (-25), CC (5) - are the polynomial parameters that control the resolution of the internal
HYSPLIT terrain following grid system. Input meteorological data are interpolated to this grid. The
polynomial relates height (AGL) to the internal vertical index number where k=1 would be the first level
above ground: Z = AA*k**2 + BB*k + CC.
KSFC (2) - defines the vertical index of the internal meteorological data level that is considered to be the
top of the surface layer. This value is used for stability scaling computations. The default index value of
2 is consistent with the default polynomial parameters that result in the height of the surface layer top to
default to 75 m AGL.
MAXLVL(35) - are the maximum number of meteorological data levels that can be input to the model.
This value exceeds all currently available meteorological data sets.
Table of Contents
When using the GUI, the namelist file will be deleted and all variables are returned to their default value
by selecting the "Reset" button. The following summarizes the namelist variables and their corresponding
section in the GUI menu. Not all variables can be set through the menu.
TRATIO (0.75) - defines the fraction of a grid cell that a particle or trajectory is permitted to transit in one
advection time step. Reducing this value will reduce the time step and increase computational times.
Smaller time steps result in less integration error. Integration errors can be estimated by computing a
backward trajectory from the forward trajectory end position and computing the ratio of the distance
between that endpoint and the original starting point divided by the total forward and backward trajectory
distance.
DELT (0.0) - is used to set the integration time step to a fixed value in minutes from 1 to 60. It should be
evenly divisible into 60. The default value of zero causes the program to compute the time step each hour
according to the maximum wind speed, meteorological and concentration grid spacing, and the TRATIO
parameter. The fixed time step option should only be used when strong winds in regions not relevant to
the dispersion simulation (perhaps the upper troposphere) are causing the model to run with small time
steps. Improper specification of the time step could cause aliasing errors in advection and underestimation
of air concentrations.
MGMIN (10) - is the minimum size in grid units of the meteorological sub-grid. The sub-grid is set
dynamically during the calculation and depends upon the horizontal distribution of end-points and the
wind speed. Larger sub-grids than necessary will slow down the calculation by forcing the processing of
meteorological data in regions where no transport or dispersion calculations are being performed. In some
situations, such as when the computation is between meteorological data files that have no temporal
overlap, the model may try to reload meteorological data with a new sub-grid. This will result in a fatal
error. One solution to this error would be to increase the minimum grid size larger than the meteorological
grid to force a full-grid data load.
KMSL (0) - sets the default for input heights to be relative to the terrain height of the meteorological
model. Hence input heights are specified as AGL. Setting this parameter to "1" forces the model to
subtract the local terrain height from source input heights before further processing. Hence input heights
should be specified as relative to Mean Sea Level (MSL). In concentration simulations, the MSL option
also forces the vertical concentration grid heights to be considered relative to mean sea level.
Model Type
INITD (4) - determines if the model is configured as a puff or particle model. Valid options are:
Introduced with the September 2004 version are mixed model calculations, but not yet available
through the GUI:
The conversions occur automatically in mixed mode when the horizontal standard deviation of the puff
(or particle equivalent) equals the concentration grid size. A use of this approach might be for a long-
range or regional puff simulation, where the concentration grid is rather coarse. In this case the puffs may
pass between concentration sampling nodes during the initial stages of the transport, a stage when the
plume is still narrow. Using mode #104 would start the simulation with particles (and concentration grid
cells) and then switch to puff mode (and concentration sampling nodes) when the particles are distributed
over a concentration grid cell.
Particle Number
NUMPAR (500) - would be the maximum number of particles or puffs released. NUMPAR has a different
meaning for puff and particle simulations. In a full puff simulation (INITD=1,2), only one puff per time
step is released, regardless of the value of NUMPAR. In a particle or mixed particle-puff simulation
(INITD=0,3,4), NUMPAR represents the total number of particles that are released during one release
cycle. Multiple release cycles cannot produce more than MAXPAR number of particles. For a mixed
simulation (particle-puff), NUMPAR should be greater than one but does not need to be anything close to
what is required for a full 3D particle simulation. In all simulation types, particle or puffs are emitted if
the particle count is less than MAXPAR.
MAXPAR (10000) - is the maximum number of particles permitted to be carried at any time during a
simulation.
QCYCLE (0.0) - are the number of hours between emission start cycles. A zero value means that the
emissions are not cycled. When non-zero, the number of emission hours is repeated again at QCYCLE
hours after the starting emission time specified in the input Control file.
KHMAX (9999) - is the maximum age (in hours) that any puff or particle is permitted to attain. All
pollutants beyond this age are deleted.
ISOT (0) - is a flag used to set the turbulence computational method. The default standard method
computes the mixing using a diffusivity approach based upon vertical stability estimates and the
horizontal wind field deformation. In shorter-range dispersion simulations (<100 km) the deformation
parameterization used in conjunction with larger scale meteorological fields will not reflect the diurnal
variations in horizontal turbulence. In this situation it is desirable to use the short-range parameterization
in which the turbulent velocities are computed directly from the stability parameters. The input tke
(turbulent kinetic energy) option replaces the model's computation of stability with the TKE field from the
input meteorological data set. Currently only the ETA forecast model data contain the TKE field. In the
variance option, the input data is assumed to contain the 3-dimensional component velocity variance
fields. Normally when turbulent fluxes (heat and momentum) are available, they are used to compute
stability. The short-range method has an additional option (#2) to force the use of the profile to compute
stability, rather than the fluxes. This may be desirable, especially if the fluxes represent averages rather
than instantaneous values.
The options available through the menu are highlighted in red. Selection of an option inconsistent with the
input meteorological data will result in the calculation using the default parameters.
TKER (0) - is the ratio of the vertical to the horizontal turbulence. A value of zero (the default) uses a
TKER value consistent with the turbulence parameterization. A non-zero value forces the vertical and
horizontal values derived from the TKE to match the ratio. This option is only valid with ISOT=4 and
ISOT=5. Currently this parameter cannot be edited through the GUI.
KPUFF (0) - is the flag to use either the linear with time (0) or the square-root with time (1) dispersion
equation for the horizontal growth rate of puffs. This parameter does not affect particle dispersion.
Concentration Packing
CPACK (1) - is the flag to turn off (set to 0) concentration output packing. The default is to write the
binary concentration file at only those grid points that have a non-zero concentration value (set to 1).
Setting the flag to zero results in output of the entire concentration grid. Due to the nature of the packing
method, if the plume covers more than 50% of the concentration grid, the default concentration packing
will result in larger output file than an unpacked concentration file.
PINPF (PARINIT) - default name for the particle dump input file.
NINIT - sets the type of initialization performed. When set to "0" no particle initialization occurs even if
the "PINPF" file is found in the root directory. A value of "1" reads the file only during the initialization
process. No initialization will occur if the time of the particle dump does not match the time of the model
initialization. A value of "2" will check the file each hour during the simulation, and if the times match,
the particles will be added to those already contained in the simulation. A value of "3" is similar to the
previous case, except the particles in the file replace all the particles in the simulation.
POUTF (PARDUMP) - default name for the particle dump output file.
NDUMP (0) - can be set to dump out all the particle/puff points at selected time intervals to a file called
PARDUMP. This file can be read from the root directory at the start of a new simulation to continue the
previous calculation. Valid NDUMP settings are [0] for no I/O or [hours] to set the number of hours from
the start of the simulation at which all the endpoint positions will be written to the file. The file must exist
in the root directory and NDUMP>0 for the model to initialize pollutant particles from the file. NDUMP is
used in conjunction with NCYCL (see below).
NCYCL (0)- sets the cycle interval at which the PARDUMP file is to be written after the first write at
hours NDUMP. Multiple outputs will overwrite the last output. For instance in a multi-day simulation, one
application would be to set NDUMP=24 and NCYCL=24 to output all points at the end of every
simulation day. If the model were to crash unexpectedly, the simulation could be restarted from the last
PARDUMP output.
Conversion Modules
Changes the model's internal configuration in how it treats the pollutants. Some conversion options
require additional modules and specific requirements in setting up the CONTROL file. See the linked
discussion under each option for more information.
● 0=none
● 1=matrix
● 2=10% / hour
● 3=PM10 dust storm simulation
● 4=Set concentration grid identical to the meteorology grid (not in GUI)
● 5=Deposition Probability method
● 6=Puff to Particle conversion (not in GUI)
● 7=Surface water pollutant transport
Sets the dimensions at which the meteorological grid will be offset for the ensemble calculation. Only one
offset (+ or -) in either X, Y, or Z is applied per member.
DXF (1.0) - west to east grid factor for offsetting the meteorological grid in the ensemble calculation.
DYF (1.0) - south to north grid factor for offsetting the meteorological grid in the ensemble calculation
KSFC (2) - defines the vertical index of the internal meteorological data level that is considered to be the
top of the surface layer. This value is used for stability scaling computations. The default index value of 2
is consistent with the default polynomial parameters that results in the height of the surface layer top to
default to 75 m AGL.
MAXDIM (1) - is the maximum number of pollutants that can be attached to one particle. Otherwise, if
multiple pollutants are defined they are released as individual particles. This feature is only required with
chemical conversion modules and is not implemented in the public distribution version.
MAXLVL (35) - are the maximum number of meteorological data levels that can be input to the model.
This value exceeds all currently available meteorological data sets.
KRND (6) - at this interval in hours, enhanced puff merging takes place. Enhanced merging is less
restrictive and will degrade the accuracy of the simulation. Puffs can be further apart and still be merged
into the same position. Less frequent merging will improve accuracy, however too many puffs may
remain and the simulation time will be substantially increased. The selection of an appropriate value
depends if the pollutant release is instantaneous or continuous. Enhanced merging only occurs when the
FRME (0.10) - is the fraction of the total mass that represents a puff mass at which all puffs with a mass
less that puff value will only account for FRME of the total mass. These "Low Mass" puffs will be subject
to enhanced merging.
FRMR (0.0) - is the fraction of the mass that is permitted to be removed at KRND intervals. The normal
situation is to permit no mass loss. However for certain simulations, such as when a pollutant has a high
ambient background relative, a small removal rate will significantly reduce the number of puffs on the
grid at no loss in accuracy.
EFILE (null) - file name that contains point-source temporal emission factors, where each record contains
the {year month day hour duration latitude longitude emission-rate} of each emission period (including
the first one defined in the CONTROL file, in the following format: (I4,2I3,2I5,F6.2,F8.2,F8.0). Note the
hour and duration fields should be four characters long (0000), representing hours | minutes.
Table of Contents
Table of Contents
Number of dynamic samplers: Due to file unit number restrictions, the current version only supports 9
simultaneous sampler definitions. The following seven lines need to be repeated for every defined
sampler.
Release location and height: The location is the latitude-longitude point at which the trajectory of the
sampler path is started. Although the subsequent vertical motion is isobaric, the initial starting height
must be defined in meters above ground-level. Note that the isobaric sampler trajectory will not be
identical to the HYSPLIT trajectory model isobaric trajectory because of differences in how the vertical
motion is computed between the two models.
Force vector: If the direction (downwind) and speed (m/s) set to zero, then the model computes the
sampler trajectory according to the meteorological input data wind velocity. If any of these values are
not zero, then the sampler trajectory is computed using these values for its entire length. To simulate a
more complex aircraft sampling path, each leg of the flight pattern requires its own sampler definition.
Release start: The release time of the sampler gives the date and time that sampler starts from the
previously defined release location. Note that in the current version, zero's for this field (relative start
time) are not supported.
Sampling start: The sampler may proceed on its trajectory for quite some time before sampling is
started. The sampler start time must be greater than or equal to the release start time.
Sample averaging (minutes): At every computational time step the model determines the sampler’s
position in the concentration grid and accumulates the concentration value in memory. When the
sampler accumulation time reaches the sample averaging time, all sums are reset to zero. A sample
averaging time of zero means that the sample is only accumulated for one model integration time step.
Disk file output interval (minutes): At the disk output interval, the sampler concentration values are
written to the output file defined on the next input line. The value written is the accumulated
concentration divided by the accumulated minutes. The disk output interval is independent from the
sample averaging time.
Sampler output file: The directory and file name should be enclosed in single quotes. If the file is
defined without a directory it is written to the model startup directory.
Note that dynamic sampling will only work if the sampler trajectory passes through a concentration grid
covering the region of interest. That means that a concentration grid of sufficient resolution, in both the
horizontal and vertical is required for a sampler to capture the pollutant. However too much resolution
(too fine a grid) may mean that there could be an insufficient number of pollutant particles to provide a
uniform distribution and therefore the sampling could provide unrepresentative results. The
concentration grid is required to be defined as a snapshot grid. In the current version, only one pollutant
species per simulation is supported.
Table of Contents
1) From the Concentration Setup menu, retrieve the standard example configuration sample_conc. Then
modify the run time from 48 hours to 16 hours. The data file starts at 16 Oct 1995 on 0000 UTC. The
first part of the simulation will end at 1600 UTC. This is close to local solar noon and approximately
corresponds with the time of the TOMS image at the longitude of the US East Coast.
2) Go to the Configuration Setup of the Advanced menu and press the bottom Reset button to bring all
values back to their default. Then change the value of 1st Particle Dump from 0 to 16 hours. This
configures the model to write the particle position file PARDUMP after 16 hours runtime. Save to exit
the menu.
4) At the end of the simulation, go back to the Advanced menu and from View MESSAGES, review the
MESSAGE file. Note that at the bottom of the listing the note that the PARDUMP file was created for
498 particles at 95 10 16 16, then Exit.
5) TOMS data for the 16th of October 1995 are not available, however a dummy file (for another date
and renamed to reflect the simulation time) has been placed in the ./working directory. Therefore no FTP
is required. For other simulation times, use the NASA TOMS tab of the FTP Satellite data menu to ftp
the daily file from the proper date. More information about TOMS data is available.
6) Open the Particle Editor from the Edit/View tab to display the particle positions given in the
PARDUMP file found in the ./working directory. In addition, the program can overlay the TOMS image
for the sample data. Various images can be displayed and the particle positions manipulated as shown in
the illustration below. More detailed instructions about this process are available.
7) Once the PARDUMP file has been adjusted to improve the comparison with the satellite data, go to
the Configuration Setup menu and write particle initialization time from 16 hours to 24 hours and then
Save. The model will be run another 24 hours and a new PARDUMP file will be written. Satellite passes
are about every 24 hours over the same longitude.
8) From the Concentration Setup menu change the run time from 16 to 24 hours, and explicitly set the
model starting time from all zeros to "95 10 16 16". Emissions need to be turned off, unless the source is
continuous. In this example turn off emissions from the Pollutant selection of the Pollutant, Deposition,
Grids Setup menu bar and set the emission duration from one hour to 0.0 hours. Then run the model.
9) At the completion of the simulation, review the MESSAGE to confirm that the model initialized with
498 particles (total mass still 1.0) and that a new PARDUMP file was created for the 17th. The point of
this exercise is to demonstrate how the model fields can be adjusted to correspond with measured data
prior to running a simulation with forecast data, times at which no measurement data are available.
Table of Contents
The Status bar is split into halves. The left half identifies the PARDUMP file currently being displayed
and/or edited, while the right half identifies the background file. When a PARDUMP file is being
displayed/edited, the file name is displayed, along with the valid date of the forecast particle positions.
The background file may be the default ARLMAP geographic background, or background observed data
from either of two sources, the TOMS file or the AVHRR data. If either of the observation data file
types is being used, the file name is displayed as well as the date for which the observation is valid.
On the right side of the Menu and Status Bar are the current status labels of the mouse pointer. The
center two labels give the instantaneous latitude and longitude, in degrees, of the mouse pointer. The
right label gives the value of the background observation at that point. The meaning of the "observation
value" depends on the type of background displayed. The left-hand label gives the valid date of the
current Particle dump file, if open. The left side of the Menu and Status Bar are menu buttons, with the
following effects:
File Menu
This menu enables the user to specify the PARDUMP file to be loaded and displayed on the current
background, and the file in which the edited results will be saved.
Edit
Zoom / Unzoom
The zoom function is provided by windowing. Click on the zoom button, move the cursor to one corner
of the area of interest, then drag to the opposite corner. A rubber-band box displays the area to be
magnified. A series of Zoom operations may be stacked; the unzoom button reverses them in sequence.
The particle shift sub-menu provides the editing of particle positions in an area-by-area fashion. When a
PARDUMP File is loaded and displayed, an area may be selected for editing, first by clicking on the
select area menu button, then moving the mouse to one corner of the area and dragging the mouse to the
opposite corner. If the desired area is not selected, the Undo Area button will allow another selection.
The New Pos button allows specification of how far the particles in the selected area will be shifted.
After clicking on the menu button, place the mouse anywhere on the geographic display and drag the
mouse. The arrow indicates the amount and direction by which the particles in the selected area will be
shifted. Particles outside the area will be shifted by an amount that tapers rapidly with distance from the
selected area. Repeated New Pos action will refine the desired shift.
When the desired particle shifts have been made, Complete Area Shift should be selected. As many
separate areas as desired may be acted on in this way. When all such areas have been completed, the
edited positions can be saved to a file.
Background
Permits the selection of background information. The ArlMap display is always available, but the
background displays for TOMS data and AVHRR data must be downloaded separately.
This button will cause the particle cloud display to appear and disappear as needed to judge how particle
shift is needed against the background.
Geographic display
The display holds one of three types of background. The base display (ArlMap) is a geographic
background of the world. The status bar observation value simply reads "0" when the mouse is over
water area and "1" when the mouse is traversing land area.
The TOMS File display provides a color coded representation of analysis of aerosols from the "Total
Ozone Mapping Spectrometer". A brown color represents missing data, white color represents negative
values (corresponding to reflective aerosols) and a range of warmer colors represents various positive
values (corresponding to absorbing aerosols. The status bar observation value reads the value itself, if
available, or "m" for missing if not available.
The AVHRR Map display provides a representation of analyzed data from the Advanced Very High
Resolution Radiometer. Since the analysis is valid only over water, the land areas are represented in
green and the status bar observation value is "m" for missing there. Otherwise, it gives a reading of the
aerosol depth. Over water, the display represents positive values in various shades of gray, with the
darkest being the highest. A red color represents negative values. The TOMS File and AVHRR Map
displays represent data valid at specific times. The valid time is presented on the right side of the File
status bar.
Table of Contents
ftp://jwocky.gsfc.nasa.gov/pub/{eptoms|nimbus7}/data/aerosol/{year}/
file = L3_aersl_{ept|n7t}_{year}{month}{day}.txt
More current information is available from the README files on the NASA server.
data/reflYYYY/gaYYMMDD.epr
Daily reflectivity data. Format similar to that of ozone data.
The vales are in 3 digit groups 111222333444555
Sample reflectivity value: _83 = 83% 999=fill value
data/a1YYYY/gaYYMMDD.epa
Daily aerosol data. Format similar to that of ozone data.
The data are an aerosol index formed directly from the measured radiances in two TOMS
channels. Positive values generally represent absorbing aerosols (dust and smoke) while negative
values represent nonabsorbing aerosols. The identification is not perfect because of geophysical
reasons (e.g., aerosol too low to the ground). There will soon be a corresponding data set of
References:
● Herman, J.R., P.K. Bhartia, O.Torres, C. Hsu, C. Seftor, E. Celarier, Global Distribution of UV-
Absorbing Aerosols From Nimbus-7/TOMS Data, J.Geophys. Res., 102, 16,911-16,922, 1997.
● Torres, O., P.K. Bhartia, J.R. Herman, Z. Ahmad, and J. Gleason, Derivation of aerosol
properties from satellite measurements of backscattered ultraviolet radiation: Theoretical basis, J.
Geophys. Res. 103, 17099-17110, 1998.
UV Erythemal Irradiance
data/uvYYYY/gaYYMMDD.epe
Daily uv data. RDGRID.FOR may be used to read these data but see 1README.UV and
erynotes.pdf for information about interpreting/decoding the uv data file format.
123 = 2.3x10^1 J/m2 -23 = 2.3 --3 = 0.3 999 = missing or bad data
data/monthly_averages/gmYYMM.ept .
This directory contains gridded monthly (gm) averages of ozone data from year YY and month
MM. At least 20 days of data must be available for monthly averages to be considered valid.
Monthly averages of aerosol, UV and reflectivity are also provided in directories located in a path
structure similar to that for ozone averages.
The Fortran statements that wrote the data records of these monthly files are:
DO 570 IL=1,180
DO 560 jj=1,288
560 OZONE(JJ)=ozav(JJ,IL)
write(21,'(1X,25I3)') (OZONE(jj),jj=1,275)
write(21,'(1X,13I3,1A17)') (OZONE(jj),jj=276,288), latlab
(IL)
570 CONTINUE
data/overpass/OVPxxx.ept
A subset (seconds UT, latitude, longitude, total ozone, surface reflectivity, solar zenith angle,
aerosol index, SOI index, etc) of EarthProbe data specific to a particular latitude-longitude
location. xxx designates a numerical site location as listed in file "1Sitelist" in this directory.
Fortran statements that can be used to read the 1st header record and the data records in the OVPxxx
files are the following:
For the header record:
CHARACTER*28 site_name
INTEGER*4 site_id, site_alt
REAL*4 site_lat, site_lon
Read(lun,2) site_name, site_id, site_lat,site_lon, site_alt
2 Format(A30,4X,I3,7X,F7.2,7X,F7.2,7X,I4)
Format(F7.1,1X,I4,1X,I3,1X,I5,2X,I2,1X,F6.2,1X,F7.2,1X,
I3,1X,I3,1X,F5.2,1X,F5.1,1X,F5.1,1X,F6.2,1X,I4)
1README, in this directory, provides more information about the OVPxxx files.
The Fortran statements that wrote the header and data records of file zm_month are the following:
CHARACTER*69 MONLAB
Data MONLAB/'Jan Feb Mar Apr May Jun Jul
Aug Sep
The Fortran statement that wrote the data records of the zmday_YY files is:
write(21,'(A12,F9.3,1X,36F6.1,3X,3F6.1)') date,yd,zmd
If these EarthProbe/TOMS data are downloaded and used in publication, please give proper credit to the
NASA/GSFC TOMS Ozone Processing Team (OPT).
Table of Contents
AVHRR Files
The Advanced Very High Resolution Radiometer, flown on a NOAA satellite, measures aerosol data
which are analyzed for aerosol optical depth and posted daily at an FTP site.
1) DATASET ABSTRACT
An aerosol optical thickness 100km analyzed field file consists of a specific set of information
pertaining to global latitude and longitude intersections. The 1° resolution file, includes the area
from -180° to +179° longitude and from -70° to +70° latitude.
The file consists of one documentation record (record number one), followed by one record for each
latitude or row of the field. Record 2 or the first latitude row is the southernmost row or the 70°
South row. Each row consists of seven words (28 bytes) of information for each longitude column
forming a grid intersection plus one seven-word unit containing the row number identification and the
date and time of the last analysis made for the field. The first grid intersection of each row is the
180° west meridian or the date line. Gridpoints proceed to the east across the record from left to
right ending with the 179° East meridian . The documentation record is created from a namelist
dataset and is displayed in namelist format, although it is stored as a binary record. The record size is
10,108 bytes.
A detailed listing of the documentation record format is provided here. This is the first record of the file,
and contains the valid time, minimum and maximum latitudes and longitudes of the area covered,
together with the grid resolution. If also contains tne number of rows (latitudes), the number of columns
(number of longitudes plus one), and information about the currency and reliability of the data.
Each data record (latitudinal row) consists of a series of grid intersection points. These points are 28
bytes in length. Each longitude (column) reflects one grid intersection. At the end of the data record (i.e.,
GRID INTERSECTION
Optical Thickness - The latest Aerosol Optical Thickness calculated based on the previous analysis
optical thickness, weighted according to its reliability, combined with a weighted average of current
observations within a surrounding area which is determined according to the grid point's gradient.
Average Gradient - The average of the gradients in all four directions (N, S, E, W) from the grid
intersection.
Gradient in X+ Direction - Change in optical thickness between the grid point and neighbor points
within the field in the positive direction along the X axis.
Gradient in X- Direction - Change in optical thickness in the negative direction along the X axis.
Gradient in Y+ Direction - Change in optical thickness in the positive direction along the Y axis.
Gradient in Y- Direction - Change in optical thickness in the negative direction along the Y axis.
Physiographic Descriptor - The land/sea tag indicating whether a grid intersection is a land or sea point.
Number of Observations - The total number of current observations used in the analysis of the new
optical thickness for the grid intersection.
Age of Most Recent Observation - The age, in hours from the time of last analysis, of the most recent
observation used to determine the new optical thickness for a grid intersection.
Reliability -
New reliability associated with the new optical thickness, based on the previous reliability combined
with the weighted reliability of all observations used in the last analysis.
Class 1 Temporal Coverage - Set of bits (0-15) of which bit 1 is set to 1 for each analysis which included
observations with a reliability greater than or equal to a specific minimum reliability considered as class
1. Bit 0 always remains a 0, and all bits are shifted right during each analysis leaving bit 1 a 0 when no
Spatial Covariance X+ - The distance in grid units from the grid intersection to the nearest land mass in
the positive direction along the X axis.
Spatial Covariance X- - The distance in grid units from the grid intersection to the nearest land mass in
the negative direction along the X axis.
Spatial Covariance Y+ - The distance in grid units from the grid intersection to the nearest land mass in
the positive direction along the Y axis.
Spatial Covariance Y- - The distance in grid units from the grid intersection to the nearest land mass in
the negative direction along the Y axis.
Independent Grid Temperature - The average sea surface temperature of a grid intersection for a
particular month over a number of years, taken from the global climatology file.
1 -- 4
2 -- 4
Spare -- Undefined --
3 -- 4
Spare -- -- Undefined
4 -- 1
4 -- 3
Spare -- Undefined --
5 -- 4
6 -- 4
7 -- 4
Year -- Years --
NOTE: All parameters are stored as integer values. Words 5 to 7 are the date and time at which analysis
was performed.
Table of Contents
1 ---- LDBGN
Record number of the first row of the field (currently 2 for all fields since the documentation
record requires only one record).
2 ---- SMGLAT
Minimum latitude included in field which is the bottom edge and first row of field.
3 ---- AXLAT
Maximum latitude included in field which is the top edge and last row of field.
4 ---- SMLONG
Minimum longitude included in field which is the left edge and first column of field.
5 ---- AXLONG
Maximum longitude included in field which is the right edge and last column of field (excluding
the I.D. column).
6 ---- RES
Number of latitude/longitude degrees between each grid point.
7 ---- SMHOUR
Youngest time, in hours of the year, of observations used during last analysis, which becomes the
oldest time allowed for the next analysis. If the difference between this time and time of next
analysis is greater than the maximum time gap allowed, SMHOUR for the beginning of the next
analysis is reduced to make the difference equal to the maximum time gap.
8 ---- HOURS
Oldest time, in hours of the year, of observations used during last analysis.
9 ---- TIMGAP
Number of hours between youngest and oldest times of observations used in analysis.
10 ---- MAXDAT
Maximum number of hours allowed in time period for observation times to be included in
analysis.
11 ---- SMREL
Minimum reliability of observations to be used in analysis.
12 ---- AXREL
Maximum reliability of observations to be used in analysis.
13-22 ---- SORC(10)
List of source codes of observations to be used in analysis.
23-32 ---- OBTYPE(10)
List of observation types allowed to be used in analysis.
33 ---- NROWS
Number of rows (latitudinal parallels) included in field, excluding documentation record.
34 ---- NCOLS
Word number, length in bits, and starting bit location of Spatial Covariance in the negative Y
direction.
84-86 ---- LWIND, LNIND, LBIND
Word number, length in bits, and starting bit location of Independent Temperature.
87-96 ---- GRDWTS(10)
Weight assigned to each grid unit, according to its distance from the grid intersection for which
gradients are being calculated.
97 ---- NP
Number of grid points to be used in calculation of gradients.
98-117 ---- KMDST(10,2)
Look up table of gradient values and corresponding distances to be used in determining the
search area for analysis.
118 ---- MKM
Number of paired entries in KMDST.
119-138 ---- H(10,2)
Look up table of gradient values and corresponding factors to be used in determining the new
weight assigned to the observation temperature for analysis.
139 ---- MH
Number of paired entries in H.
140 ---- EXP
Exponent used in temperature analysis.
141 ---- FDX
Factor used in determining new weight assigned to the optical thickness observation for analysis.
142 ---- XCLASS
Factor used to place gradients into a class for Gradient Class Summary.
143 ---- DEL
Maximum number of optical thickness units that the new analysis temperature may differ from
the previous optical thickness field value.
144 ---- MF
Factor applied to the previous optical thickness and reliability to determine the final optical
thickness and its reliability.
145 ---- MSTAR
Factor applied to the combined observations optical thickness and weight in determining the new
analysis optical thickness.
146 ---- MNSRCH
Minimum distance in kilometers to be searched for analysis observations.
147 ---- MXSRCH
Maximum distance in kilometers to be searched for analysis observations.
148 ---- BDEL
Maximum difference allowed between new analysis optical thickness and the previous one for
the Class 1 Coverage Bit to be set to 1.
149 ---- FCWT
Maximum value that can be assigned as the reliability of the new analysis optical thickness.
This floating point representation is not compatible with the IEEE floating point specification
which is used by most modern computers. The IBM360 float was native to the now obsolete IBM
360/370 series of computers, and a few others. Since documentation of this representation is
getting difficult to find, a summary is provided here.
The 4-byte floating point representation is divided into one byte (SEXP) for sign and exponent,
followed by a 3-byte MANTISSA. The mantissa should be thought of as a six digit hexadecimal
number, with a radix point preceding the first digit. The numeric value of the MANTISSA is the
value of the integer with the same hex representation, divided by 0x1000000, and ranges from 0.0
to just less than 1.0. For a non-zero, normalized float, the first hex digit will range from 0x1 to
0xf.
In the SEXP byte, the high order bit is the sign of the number, 0 for plus and 1 for minus. The
remaining seven bits are a biased exponent. After subtracting 0x40, the result is the number of
hexidecimal digits (powers of 16) to shift the radix point right (if positive) or left (if negative).
This means the range of the representation is from 16^63 to 16^(-64).
Table of Contents
The concentration model default simulation assumes a particle dispersion in the vertical direction and a
top-hat puff dispersion in the horizontal direction. Other options are set with the INITD parameter of the
SETUP.CFG namelist file defined in the advanced menu section. Normally changes to the dispersion
distribution are straightforward. However there are some considerations with regard to the initial number
of particles released. The default release is set to be 500 particles over the duration of the emission cycle
(see NUMPAR). A 3-dimensional (3D) particle simulation requires many more particles to simulate the
proper pollutant distribution, the number depending upon the maximum downwind distance of the
simulation and the duration of the release, longer in each case require more particles. Too few particles
result in noisy concentration fields. A 3D puff simulation starts with one puff as the puff-splitting
process in conjunction with the vertical dispersion quickly generates a sufficient number of puffs to
represent the complex dispersion process. The default configuration represents a compromise in
permitting particle dispersion in the vertical for greater accuracy and puff dispersion in the horizontal to
limit the particle number requirements.
Continuous Emissions
As noted above the default release is 500 particles over the duration of the emission cycle. If continuous
emissions are specified (e.g. over the duration of the simulation), then those 500 particles are spread out
over that time period. This may easily result in the release of too few particles each hour to provide
smooth temporal changes in the concentration field. Imagine a single particle passing in and out of the
vertical concentration cell due to turbulent diffusion. One solution would be to increase the NUMPAR
parameter until smoother results are obtained. Another possibility would be to cycle the emissions by
emitting 100 particles only for the first time step of each hour. Those particles would contain the total
mass for a one-hour release (see how to set QCYCLE).
Normally emissions are assumed to be point or vertical line sources. Virtual point sources (initial source
area >0) can be defined two ways: 1) through the definition of an initial area on the source location input
line of the CONTROL file or 2) by the definition of a gridded emissions file. If the model's root startup
directory contains the file Emission.txt, then the pollutants are emitted from each grid cell according to
the definitions previously set in the Control file. Two source points should be selected, which define the
lower left (1st point) and upper right (2nd point) corner of the emissions grid that will be used in the
simulation. This should be a subset of the grid defined in emission.txt. The release height represents the
height from the ground through which pollutants will be initially distributed. Note that the structure of
the "emission.txt " file has changed with the Hysplit 4.6 revision of October 2003.
The "emission.txt" file contains all the information that is required to interpret the data in the gridded
emission inventory file. The file that contains the inventory is now independent of the emission.txt file.
The file's first record contains information about the internal grid cell size that is used by the dispersion
model to accumulate the file's emissions. The emission file defines the emissions at latitude-longitude
points, which may represent the emissions from an area or from a point. The values at these points are
accumulated in an internal grid, the size of which is defined on the first record. This value can be
arbitrarily changed according to the desired resolution of the simulation. The pollutant puffs are released
with an initial size comparable to the accumulation cell size. Because the emission file data are
remapped to an internal grid, the file can consist of emissions data on a regular grid or just a collection
of individual cells. The emission rate in the Control file is used as an additional multiplication factor for
the data in the emission file. Also note that previously discussed particle number restrictions still apply.
The particles are spread out over the duration of the emission and the number of grid cells that are
defined in the emission domain. The format of the emission.txt file is given below:
Record #1
Record #2
Record #3
The actual emission data file will contain one record identifying the grid location and then two records
for each pollutant species. The first record defines emissions from GMT hours 0 to 12 and the second
record from hours 12 to 24. This pair of records is repeated for each pollutant species:
● 2I4 - I,J grid point of emission cell (arbitrary units for identification)
● 2F10.4 - Southwest corner Longitude and Latitude of this emission cell
Multiple Pollutants
The model can easily be configured to simulate more complex pollutant episodes with multiple pollutant
types on different particles or multiple pollutant species on the same particle. The former is
accomplished by defining additional pollutants in the CONTROL file. In this configuration, multiple
species are emitted, have no interaction, and may track differently. This situation may represent a
volcanic ash plume, where each pollutant, a different sized particle, settles at a different rate. An
example configuration "volc_conc" can be retrieved in the SETUP menu.
Pollutant Transformations
In the latter situation, when multiple pollutants are defined on the same particle, an external chemistry
routine is required that converts mass from one species to another, all tracking together (advecting and
dispersing). In this situation, MAXDIM should be raised to the required value. Increasing the MAXDIM
value always requires an external routine to adjust the mass between species. A simple species
conversion program is included with the standard model distribution. In the default configuration it is
only necessary to define two different pollutants in the concentration setup menu and select the 10% /hr
checkbox in the advanced configuration menu's conversion section. This option combination sets
MAXDIM=2 and calls the transformation routine every time step to convert pollutant #1 to #2 at a rate
of 10% per hour. Other conversion rates or a greater number of pollutants can be defined by creating the
CHEMRATE.TXT file in the local directory. This file would consist of one or more records, each record
defining a pollutant conversion. The data are free-format and consist of four fields, the integer "from"
and "to" pollutant index numbers, and the real hourly conversion "rate", and molecular weight
adjustment "factor". For instance, if the file were to be defined for the default case, the one data record
would have the following values: (1 2 0.10 1.0). The molecular weight adjustment factor can be used to
account for other reactions not considered in the simple conversion module. For instance, if one were to
define pollutants #1 and #2 as SO2 and SO4, respectively, then the molecular weight adjustment factor
should be 1.5 as SO2 transforms to SO4 (the conversion picks up two additional oxygen molecules).
Complex Chemistry
Although there are other more complex chemical conversion modules available for HYSPLIT, they are
not incorporated into the standard compilation. More information on these special compilations may be
found at http://www.arl.noaa.gov/ready/hyspchem
One feature, required for all these modules, is that there is a more complex interaction between the
individual pollutant plumes, requiring a close link between the concentration grid and the meteorological
data grid. This option is available in the standard model compilation. By setting the namelist file
parameter ICHEM=4, the concentration grid is redefined to be equal to the meteorological data grid in
terms of spatial resolution and extent. This simplifies the computation of the grid based chemical
reactions that are dependent upon the meteorological conditions within each concentration grid cell.
A simple particle deposition configuration (rsmc_conc) for radioactive Cs-137 can be retrieved into the
SETUP menu, which shows the default settings for radioactive decay and wet and dry deposition. In
conjunction, a list of sites can be loaded into any SETUP menu, from the "Set Starting Locations" tab by
pressing the LIST button. The site locations can be found in the file "\working\plants.txt" and could be
replaced by any user generated location file listing.
The normal deposition mode is for particles to loose mass to deposition when those particles are within
the deposition layer. An additional option was added to deposit the entire particle's mass at the surface,
that is the particle itself, when subjected to deposition. To insure the same mass removal rates between
the two methods, a probability of deposition is computed, so that only a fraction of the particles within
the deposition layer are deposited in any one time step. The probability of deposition is a function of the
deposition velocity, time step, and depth of the layer. One limitation of this method is that only one mass
species may be assigned to a particle. The probability deposition method can be invoked from the
namelist file with ICHEM=5.
Compilation Limits
With Hysplit V4.5 most compilation array limits have been eliminated through the use of dynamic array
allocation. However, one restriction remains with regard to the meteorological input data:
meteorological data files are limited to a maximum of 10 per simulation, with no more than 35 levels or
variables in each file. This restriction does not limit any computation with data files available through
the ARL web site, because all available data files meet the number of variable and levels restriction.
The use of dynamic memory allocation can result in unpredictable results if the computer's hardware
memory limits are exceeded. Although there are several memory error allocation traps that will result in
a message and execution termination, memory limits can be exceeded in a variety of different locations,
such as when opening a file. Memory usage is a primarily a function of the meteorological sub-grid size,
meteorological data grid size, concentration grid size, and the number of pollutants.
Most of the discussion in various sections of the User's Guide are tailored to individually configured
simulations. However there are several features to the model that can be used to automate the
computational environment. For instance, a sample Auto_traj.tcl script is provided in the \trajmdl
directory that can be used as a guide to automate many applications.
# Auto_traj.tcl
# the next line restarts using wish
# exec wish "$0" "$@"
set Start_hgt "10.0"
set Traj_path "../trajmdl"
set Start_time "00 00 00 00"
set Run_hours "24"
set Vert_coord "0"
set Top_model "10000.0"
set Meteo_path "../metdata/"
set Meteo_file "oct1618.BIN"
set Output_path "./"
set Output_base "tdump"
set Output_numb 1
foreach {Start_lat Start_lon} {35.0 -90.0 40.0 -90.0 45.0 -90.0} {
set Start_loc "$Start_lat $Start_lon $Start_hgt"
set Output_file "$Output_base$Output_numb"
file delete Control
set f [open Control w]
puts $f "$Start_time"
puts $f "1"
puts $f "$Start_loc"
puts $f "$Run_hours"
puts $f "$Vert_coord"
puts $f "$Top_model"
puts $f "1"
puts $f "$Meteo_path"
puts $f "$Meteo_file"
puts $f "$Output_path"
puts $f "$Output_file"
close $f
exec "$Traj_path/hymodelt.exe"
incr Output_numb}
In this particular example the test trajectory case is run for three different starting locations, each
simulation writing a new endpoints file with a unique file name. The CONTROL file is recreated for
each simulation. It would be trivial to rewrite the script to set the latitude-longitude and loop through a
different number of starting days and hours. With Tcl/Tk installed, this script can be run under Windows
or Unix. For instance, to compute new forecast trajectories each day, the process can be automated by
including a data FTP at the beginning of the script to get the most recent meteorological forecast file,
setting the starting time as "00 00 00 00" so that the trajectories will start at the beginning of the file, and
finally calling the script once-a-day though the Unix crontable or the Window's scheduler commands.
One problem with automated operations is that it is possible to generate simultaneous multiple jobs
which may interfere with each other. The executables, Hymodelc and Hymodelt have a command line
option of adding the process ID (PID): e.g. hymodelt [PID]. In this situation all standard named input
and output files [those not defined in the Control file] have the PID added as a suffix to the file name: e.
g. Control.[PID], Setup.[PID], Message.[PID].
1) From the "Meteorology" menu tab download the appropriate archive meteorological data and
the most recent forecast meteorological data (assume it is available to +48h).
2) Setup the concentration simulation to run 96 hours using two meteorological files starting with
the archive data and then switching to the forecast data.
3) Under the Advanced menu tab and Configuration Setup write the initialization file after 72
hours.
At the completion of the simulation you will have the plume projection from release (-48 h) through the
current forecast (+48 h). The PARDUMP file will contain all the endpoint positions at +24 hours,
corresponding to the initialization time of when the next forecast will be available (assume there is one
forecast per day).
The next day, when the new forecast data are available, reconfigure the model to run only with the
forecast meteorological data for a duration of 48 hours and write the initialization file after 24 hours,
then run the model to obtain the new projection. In this second part we assume that the first 24 hours of
the forecast are not much different than the analysis. In practice, this procedure can be run at the same
frequency that the new forecast data are available and typically at 4 times per day, data at the initial
forecast hour are identical to the analysis data.
A common application of atmospheric trajectory and dispersion models is to try to determine the source
of a pollution measurement. If a high value has been collected at a particular receptor, from which
pollutant source region did the air originate? One common approach is the calculate the trajectory
"backwards" from the receptor site. In the trajectory calculation this is accomplished by setting the
integration time step to a negative value. However the trajectory only represents the upwind path of a
single point, while the pollutant measurement may require of hundreds or thousands of trajectories to
represent the dispersion of the pollutant in time and space.
Another approach is the run the entire dispersion-trajectory model "backwards" which is
computationally attractive because in a 3D particle model the dispersion process is represented by a
turbulent component added to the trajectory calculation and the advection process is fully reversible. The
trajectory equation can be correctly integrated in either direction. The interpretation of the output is a bit
more complex because dispersion is an irreversible process. Although the equivalent numerical
calculation will yield a result because the integration of the dispersion equation is still in the normal
downstream mode on top of the backward upstream integration of the advection. The meaning of the
upwind dispersion result is less clear. In any event as noted in the earlier instructions it is possible to run
the dispersion model "backwards" by setting the run duration and emission hours to their equivalent
negative value. The stop time of the sampling should be set prior to the start time. All start and stop
times should be set to their exact values - relative start-stop times are not supported in the backward
mode. To simplify interpretation of the results, horizontal dispersion is "turned off" in the backward
calculation, resulting in a more reversible calculation. An example configuration (back_conc) can be
retrieved into the SETUP menu.
One way to incorporate a time varying emission rate into the existing model structure is to use the
particle dump feature to restart the model each time with a new emission rate. Another option is to
assign the name of a temporal emission input file to the "EFILE" variable in the setup.cfg namelist file.
This ascii file must consist of at least three records, the first two of which are used for identification
purposes, and the third, and all subsequent records, define the temporal sequence of emissions. Each
emission record contains the start time, duration, location, and emission rate. If the EFILE is present, the
first emission record's values replace the emission values set in the control file. Once the model
computation time has passed the emission period defined on the first emission record, the emission data
from the second record are loaded and the calculation continues with the new emission data. The format
of the emission file is given below:
● I4 - Start year
● I3 - Start month
● I3 - Start day
● I3 - Start hour
● I2 - Start minute
● I3 - Duration hours
● I2 - Duration minutes
● F6.2 - Latitude
● F8.2 - Longitude
● F8.0 - Emission rate in units/hour
The main code was modified (October 2003 Version 4.6) to permit particles deposited on water surfaces
to continue to be transported on the water surface by the wind generated drift current. The transport
output is treated as a deposition surface for display purposes. This new deposition method then creates
particles that can be transported on water surfaces. Particles can be deposited on any surface. However,
if the surface is defined as water, then the particle is assigned a unique identification code to distinguish
it from atmospheric particles or puffs. These new particles may continue to be transported along the
surface of the water contributing to deposition each time step but not air concentration. Dispersion is not
computed for these particles. When they approach a land surface they are deleted. The water surface
transport option is invoked from the namelist file with ICHEM=7. This option automatically forces the
probability deposition computation (ICHEM=5) and should only be used only with the 3D particle mode
(IN ITD=0). Surface water deposition can only be displayed if the deposition output level (0) is defined.
Although particles may deposit over land, over-land deposition values are never shown.
The wind induced surface water drift current is assumed to equal the vector atmospheric friction
velocity. The friction velocity represents the momentum transport to the surface and it is an
approximation of the surface water movement. Currently only the GFS meteorological model output file
contains the vector momentum flux components.
Table of Contents
Record #1
The "Particle" tab of the "Special File Display" menu brings up a Windows based viewer that shows the
particle positions over a map background. The display can be zoomed and otherwise adjusted using the
left and right mouse buttons in conjunction with the shift and cntl keys. Help is provided on the screen
with the left and right side comments corresponding to the respective mouse button. The particle viewer
can also be used to overlay satellite images on the particle positions. More information on this is
provided "FTP Satellite Data" help menu.
Table of Contents
http://www.arl.noaa.gov/userguide/S442.htm12/5/2005 4:45:39 AM
Advanced / Message File Format (S443)
QCYCLE = 0.0000E+00,
FRME = 0.10000000,
FRMR = 0.0000E+00,
KRND = 6,
DELT = 0.0000E+00,
ISOT = 0,
TKER = 0.50000000,
NDUMP = 0,
NCYCL = 0,
TRATIO = 0.75000000,
MGMIN = 10,
KMSL = 0,
NSTR = 0,
CPACK = 1,
ICHEM = 0,
DXF = 1.0000000,
DYF = 1.0000000,
DZF = 9.9998E-03,
NINIT = 1,
PINPF = PARINIT,
POUTF = PARDUMP
Gas pollutant - T
Number of internal model sigma levels and the polynomial parameters used to describe the
vertical grid. These are configured automatically based upon the meteorological input data files
defined for this simulation.
The value of all variables that can be defined by the SETUP.CFG namelist file are listed. If no
SETUP.CFG file was defined for this simulation, then the default values for these variables are
listed.
The settings of all internal deposition flags are shown here. In this case the simulation is for a gas.
#################################
##################################
The subroutine that determines which meteorological data are required is called for the first time.
Data for times 840 and 960 are requested. The zeros for the second field indicate no data are in
memory. Times are always in relative minutes.
The first advection entry sets sub-grid #11 to 10x10 with 19 levels.
The lower left corner of sub-grid #1 is set at position 17,9 of the main meteorological data grid.
The NGM data for the first computational hour are read starting at record #1, loaded into a 10x10
sub-grid, corner 17,9, at time [x]840 for the date: 95 10 16 0
When these data are interpolated to the internal grid, it is determined that there are no input data
records above 7159 m, therefore data for those levels are extrapolated.
Computations for the first hour require data at two time periods for interpolation (hours 0 and 2).
The initial time step was set to 20 minutes. Subsequent time steps may change.
The time, number of particles, and the total mass is shown for the three time steps of the first
hour. After one hour the emission stops.
During hour two, no further emissions (or particles) are released. The time step is now 30
minutes.
After the hour 2, new NGM data are required. The data in memory at 0 UTC (time 840) are
replaced with data at 4 UTC (time 080).
The new data are input into the same sub-grid location.
Computations proceed as before for computational hours 3 and 4. Particle number remains the same
because no particles have moved off the computational domain. The mass remains the same because
deposition is not turned on for this simulation.
At the end of hour 4, data are required for 6 UTC (time 200) to proceed with the calculation. These data
replace the 2 UTC (time 960) in memory.
Every 6 hours, the model prints out the vertical mass distribution of all the particles within the
computational domain. This is the mass distribution relative to the model's internal sigma levels and
there is no relation to the levels that may be specified for the concentration output file. Only non-zero
levels are shown. The internal levels are defined by the polynomial parameters given at the beginning of
the MESSAGE file.
At this point the computation will continue for the number of hours specified in the CONTROL file.
Vertical profiles are shown every 6 hours. As the particles move across the computational domain, the
sub-grid position may be moved (from position 17,9) or expanded larger than 10x10) to match the
spatial extent of the particle distribution. This may occur at any time during the computation or even
multiple times during the same computational hour.
Table of Contents
Verification Statistics
See the DATEM (Data Archive of Tracer Experiments and Meteorology) web page for more detailed
information on each of these tracer experiments. The model verification statistics are presented for the
unaveraged data, where each measured and calculated concentration is paired in space and time. Zero-
zero pairs are always excluded. Results are also presented after temporally averaging the measured and
calculated values over the duration of each experiment. These latter results are paired in space but not
time and hence represent the calculation's spatial performance. Statistics presented are the correlation
coefficient (R), the fractional bias (FB), the figure-of-merit in space (FMS), the KS parameter
reprsenting the departure of the measured and calculated cumulative distributions from each other, and
the normalized rank (0 to 4) which is computed from the sum of the previous four parameters.
Unless otherwise noted, all calculations used the NCAR/NCEP 2.5 degree reanlysis meteorological data
for the dispersion calculations. The main characteristics of each experimental data set are summarized as
follows:
ACURATE - Semi-continuous Kr-85 emissions from South Carolina and 12/24-hour sampling
along the US east coast at five locations from 100 to 800 km from the source for a duration of 18
months.
ANATEX - A three month duration experiment with simultaneous 3-h duration releases of
perfluorocarbon tracer from Glasgow, MT (GGW) and St. Cloud, MN (STC). Twenty-four hour
averaged samples were collected at about 70 locations over the US east coast (500 to 3000 km
downwind) for the duration of the experiment.
CAPTEX - Six 3-h duration perfluorcarbon releases from Dayton, OH or Sudbury, CA and 6-h
sampling for about three days after each tracer release.
INEL74 - Semi-continuous Kr-85 releases from Idaho for a two month period and 12-h averaged
samples collected at 12 stations along a north to south line in the midwest US about 1500 km
downwind.
OKC80 - Single 3-h perfluorocarbon release from Norman, OK with 3-h samples collected for
about 2 days along an arc 600 km downwind from the source.
ETEX - Single 12-h perfluorcarbon release from eastern France and 3-h samples collected
throughout western Europe. Calculations used the ECMWF analysis data.
ACURATE
CAPTEX
INEL74
OKC80
ETEX
ACURATE
CAPTEX
INEL74
OKC80
ETEX
Table of Contents