The Shared Procedure Archive (SPA) was originally developed at McGill University, starting in about 1999. The intention of the archive was to reduce create an easy-to-use diagnostics package for meteorological applications. It began as a set of portable FORTRAN77 functions and subroutines, and has since then grown into an evolving FORTRAN90 library with a Graphical User Interface (GUI, MetCal) and perl scripts which enable the developer's interface.
As noted in the licensing and copying agreement (see section Copying Conditions) we encourage all users of this software to become developers and to contribute to the evolution of the SPA. Please share the library entries that you develop so that others may benefit from your efforts.
The SPA is a collection of FORTRAN90 modules, subroutines, and functions that create a working environment for standard meteorological calculations. The include data access routines (generally subroutines), setup and formatting routines (again, mostly subroutines), and calculation subprograms (generally generic functions). It is this latter set of routines that will be of primary interest to the user or developer who wishes to access or extend the SPA without introducing a new data format capability (which is, of course, much appreciated).
These subprograms are intended to abstract the user (and even the end-product developer) from the particulars of the data format supplied, and to make interfacing with existing routines as painless as possible. Inevitably, there will be small bugs in some of the calculations which will be caught and corrected over time -- the end result will be a package which is as error-free as possible and meets the needs of users in the meteorological community.
MetCal (the "Meteorological Calculator") is the GUI for the SPA as described in section The SPA. It is the interface that most new users of this package should become familiar with before they begin to work with the developer's interface (see section Developer's Interface). The interface contains a notebook with three tabs, each of which is described in detail, See section Metcal. The end-user simply has to define input and output files, along with the data type, and then request outputs from MetCal. The GUI driver, written in perl/Tk (a modular Tcl/Tk addon to basic perl), accesses a pre-compiled FORTRAN90 executable which handles the program flow at run-time. The result is a very simple interface for the user, who needs to know only basic information to access the computational routines of the SPA.
Version 1.0.0 of the archive accepts input data files in the following formats:
Rech`erche en Pr'evision Numerique (RPN) is a division of the Meteorological
Service of Canada on whose in-house data storage format the original
inception of the SPA was based. The data access routines
stored in the RPN library (librmn.a) are backwards compatible
between the 1989 and 1998 I/O subprograms, but the file structures themselves
are significantly different, and must be distinguished for proper
operation of the SPA. Note that the ARMNLIB environment
variable must be correctly set during the installation of the SPA
for the RPN data format access routines to be loaded.
The GEneral Meteorological PAcKage (GEMPAK) is an open-source
distribution made available by the University Center for Atmospheric
Research. The GEMLIB environment variable (usually set by the
Gemenviron script distributed with the package) must be correctly set
during the installation of the SPA for the GEMPAK
data format access routines to be loaded.
As much as possible, all of the data to be used as input should be contained in a single input file, unless regridding is required.
The SPA is a set of FORTRAN90 subprograms stored in a series of source directories beneath the SPA root. All interactions between the driving program and each of the subprograms are strictly controlled trough interface blocks stored in modules which are use-associated as needed in the code. This interfacing scheme allows for explicit error checking as well as making the subprogram interactions easily-understandable for the developer.
There are no common blocks or global variables in the SPA, although some common variables are declared within the lower-level modules responsible for file functions. These variables, however, are scoped only within the module and the subprogram by which it is associated. We are very insistent on the explicit passing of values between routines, since the data flow becomes rapidly untraceable once common blocks and global variables dominate in an extendible archive such as the SPA.
The subroutines contained in the SPA are primarily responsible for interactions with the datafiles and configuration scripts. Functions are generally used for calculation of diagnostics (the essence of the SPA) and are mostly generic, accepting either single value or array inputs for each argument, and producing single value or array output, respectively. Interfacing with array-valued functions is advisable, since they run many times faster than a nested single-valued function call.
The SPA is intended to provide an easy means by which to create, store, and access meteorological diagnostics routines in a non data-format-specific sense. The layer of abstraction between the user (and the tools developer) and the data file allows for enhanced focus on the extension of the diagnostics database.
The premise for the SPA is that of an extendible community library of meteorological functions. Accordingly, contributions from as many sources as possible are encouraged. The SPA allows meteorological programmers to focus on the development and enhancement of the package, rather than on the development of lower-level interfacing software and basic functions.
The SPA source is arranged in a set of subdirectories in this distribution. The naming of the source for the routines follows strict guidelines that are required for some of the automated build processes of the SPA. The routines are easily accessible through a series of developer's utilities described in See section Developer's Interface, although most development work will occur in a local directory belonging to the developer (much like an RCS or CVS modification). The source subdirectories of the archive are:
sub_ prefix, followed by the name of the subroutine with
a .f90 extension.
func_ prefix, followed by the name of the function with
a .f90 extension.
mod_ prefix, followed by the name of the module with a
.f90 extension.
Interface_MRG.f90. This is the only
source in the SPA whose name violates the rules described
in the remainder of this table -- and believe me I regret that
every time I work with the code. A series of modules consisting of
interface blocks are contained in the Mesoscale Research Group
(MRG) primary interface, with subprogram access for each
depends on broad groupings of functionality.
std subdirectory. Most of
the files in this set of subdirectories are subroutines, although
a few functions are also present for the GEMPAK interface.
opt/gemlib subdirectory filled with stub
routines which warn the user about the library's unavailability
and exit smoothly. For users with the RPN, GEMPAK,
and NCAR Graphics libraries installed
see section Sounding
will see no opt directory in their distribution since all
of the necessary routines are held below the std subdirectory.
template.f90 program is intended for standard development
tasks, while the template_gui.f90 source allows for
GUI driven development.
The easily-extendible nature of the SPA is one of the package's unique attributes. The SPA was originally designed by a devoted synoptician, and contained mostly large-scale atmospheric diagnostics. Other users have since requested (and often provided) very useful computational subprograms that have extended the utility of the package immensely. For example, you may want to calculate storm-relative helicity, a variable not currently supported in the SPA. The developer's interface provides a means by which you can build a helicity calculator with only a few read statements in the driver (template) program. Our hope, of course, is that any computational routine that you create (or, any set of interface routines developed by the very brave) will be incorporated into the next release of the SPA.
A series of utilities are provided as the developer's interface as described in section Developer's Interface. Following the steps described with the utilities will make development of the archive an almost enjoyable process.
The METeorological CALculator (METCAL) is a GUI between the end user and the SPA. It consists of a set of three notebook pages on which the user sets File I/O characteristics, operation mode requirements, and desired outputs. Each of these pages is described in detail in the following sections.
MetCal is intended as an abstraction for the end user. As such, it is limited in flexibility compared to the Developer's Interface. However, it is easy to learn, and will be expanded as the SPA continues to grow. For off-the-shelf diagnostics, this utility can be extremely useful.
The File I/O page (the first page that the user will see following
the copyright notice) allows the user to define the input and output
files to be processed by MetCal. For both
RPN file formats, the user also has the option to view
any of the input or output files. The primary input file
should reference the file containing all of the necessary input
variable, if possible. For the "Standard Outputs" setting
(see section Standard Outputs), the secondary input file can be
used for supplemental input; however, all other Major Modes
refer only to the primary input file. The output
file defines the data file into which to store the output from
MetCal. If this line is left blank, then the output is piped
directly back to the input file. The grid file allows the
user to remap fields to a desired output grid. All values read
from the primary input and secondary input files are
remapped to the domain contained in the grid file before
the execution of any calculations. If the grid file is left
blank, then no remapping of the input fields occurs (the
default). The file referenced in the grid entry must contain
at least one two-dimensional field of the grid onto which the data
will be remapped.
All of the data times and levels present in the input file will be operated on by MetCal. For this reason, try as much as possible to isolate the data times that you require so that MetCal does not continue to execute on the entire set.
The Major Modes notepad of MetCal (selected using the tab at the top of the page) controls the program's data and control flows during execution. As described in the following sections, each Major Mode has a distinct functionality that may be of more or less use to different users. The default Major Mode is for Standard Outputs. Selection of any other modes produces a pop-up window for input from the user. All of the entries in the window must be completed before MetCal will execute.
The Standard Outputs mode of MetCal provides access to many of the calculation functions of the SPA. The Standard Outputs page allows users to select the calculations to be performed. Each calculation represents a routine (usually a function) contained in the archive. See section Standard Outputs Page, for details.
This simple field differencing algorithm can be used to compute the
difference between a single variable at two different levels, or between
two different variables at the same level. Of course, you could compute
the difference between different variables at different levels, but you
would really have to ask yourself why you are spending time doing that.
The input and output identifiers must be the names of the variables
contained in the primary input file on the page, See section File IO Page.
This mode allows the user to perform simple (+, -, *, /) operations on the
selected two or three dimensional field. The quantity in the value
box may be either an integer or real number, but the computation takes place
with a floating point number. This mode is especially useful for
copying fields (multiply the desired field by 1) and for changing units.
The Advection Calculation mode provides access to the advection
routine of the SPA. Any level of any field (under the Field
Information heading) may be advected by the horizontal wind at any
level. The vertical advection calculation is not implemented in
version 1.0.0 of this distribution. Although the user
may select from either the primary or secondary input
data files by pressing the Input Variables button, this usage
is discouraged and will likely be disabled in future releases, thus
allowing only primary input file entries.
The field averaging algorithm accessed by this Major Mode computes
the average (either arithmetic or pressure-weighted) of a variable in a
column whose upper and lower bounds are defined by the Top Level
and Bottom Level entries. The input data for this
mode must be given in the primary input file.
The Filtering mode of MetCal runs a 25-point smoothing box over the
entirety of the domain for the two or three dimensional variable
specified in the Identifier entry. The shape and weights of
the cells in the filter are shown graphically, and may be modified by
the user to smooth more heavily or lightly, as required. There is
no "magic number" up to which the cell-totals must add, so feel
free to modify the filter to fit your requirements. One of the drawbacks
of the MetCal interface distributed with version 1.0.0
of this distribution is that the output identifier is set equal
to the Identifier. This oversight will be corrected in
future versions of the interface.
With horizontal interpolation handled automatically through the
grid file, the Interpolation Major Mode is responsible
for implementation of cubic-spline interpolation in the vertical.
The pop-up window defaults to the mandatory pressure levels, but
this is just an example of how to specify multiple level outputs.
As many levels as required may be specified in a comma-separated
list.
The Sounding mode of MetCal requires NCAR Graphics
libraries for plotting. If these libraries were not installed when
the SPA was built on your machine, then you will not have
access to the sounder. However, if the NCAR Graphics
libraries were (and still are) available to MetCal, then the only
entries required in the pop-up window are the x,y coordinates of the
gridpoint at which to take the sounding (it will be taken at this
point for every time in your input file, in keeping with MetCal
tradition). The Plot Title entry is one of the few optional
entries in the Major Modes. The soundings produced by this
algorithm are in "metafiles" produced by NCAR Graphics,
and can be viewed with the idt utility distributed with
the NCAR Graphics package, accessible through the
view output file button on the File IO page (see section File IO Page).
The Cyclone Tracking Major Mode of MetCal is the most complex in
terms of usage. Any two dimensional variable (in the Identifier
field) can be operated on in the region of a tracked cyclone.
Note that all cyclones are tracked using the height field (on pressure
levels, default 1000~hPa in the Level entry) and that it
must therefore be present in the primary input file, along
with the field of interest. The Maximum Cyclone Phase Speed
entry allows the user to track cyclones of different speeds. You will
probably only run into a problem if this is set too low, but the default
value of 30 m/s is already pretty high. The Radius of Interest
defines the low-centre-relative region over which to operate on the
field of interest. The default value for this entry is 1000 km.
The Cyclone Tracking Major Mode produces text output files of
any or all of the field of interest's mean, standard deviation,
minimum, or maximum near the low centre. These files are named
with the Text Output Root prefix and
-mean, -sd, -min, or -max suffixes.
The output format is space-separated "time value"
for forecast data, or "date value" for analysis data.
These text files can be ingested directly into a plotting program
such as xmgrace or (shudder) Excel to produce time-series
of storm-following quantities.
Two execution modes are selectable by the user. The automatic
start mode searches for the lowest height on the pressure level (i.e.
the deepest low) in the initial field, and continues to track that
feature. Manual start mode allows the user to input the x,y
grid coordinates of the cyclone to be tracked. Similarly, the
automatic step mode allows the algorithm to track the cyclone
automatically (or at least to attempt to). If the routine senses that
it has lost the track, it will prompt the user for the x,y coordinate
at a specific time in MetCal's parent shell. The manual step
mode always asks the user for the location of the storm at every step.
Because of the unique interactive nature of this Major Mode, MetCal must be run in the foreground of the parent shell for correct functionality. We hope to rectify this problem with an interactive TopLevel window in future versions of the interface.
The Output Fields page is specific to the Standard Outputs
Major Mode. Some of the more commonly used routines of the
SPA are accessed by a series of check buttons. The
Input Variables button allows the user to describe characteristics
of the input fields contained in either the primary input or
the secondary input data files. MetCal can, in general,
accurately predict the fields that it requires to make the requested
calculations. You should always check the input variables before
execution. The Check Variables button allows the user to
determine the output characteristics of the computed fields (essentially
just the output variable identifier). Once you know these by heart
for your usual file type, you probably will not need to use this
button again. This page represents the beginnings of MetCal, and
provides the most powerful functionality for the program.
The GUI can be modified and updated by a developer who is familiar with perl/Tk. Access is provided via flags to the Developer's Interface (see section Developer's Interface). In general, enhancements and upgrades should be distributed to the community and incorporated into the next release rather than being implemented in an ad-hoc fashion; however, if the development is just that good, then you have the flexibility to incorporate it between releases.
Several other tools are included with this distribution. Some of them relate exclusively to the RPN data file format, for which there is relatively little open-source software available. However, the Developer's Interface is central to the archive itself. Most of the tools distributed with version 1.0.0 of the SPA are described in the following sections.
The Developer's Interface is second only to MetCal as an avenue by which to access the SPA. This interface makes the job of developing routines almost enjoyable by relieving the developer from the tedious job of building a driver program. The basic steps involved in beginning a new development are:
Luckily, the SPA comes with a set of tools that make this process much simpler than it sounds. Each of these tools is described (in the standard order of their application) here. Each of these utilities is also supported by man pages. Please browse these pages for information not contained in this manual.
spaopen accepts an optional flag and a single argument. The
argument is the root name of the subdirectory, to which will be
appended _f90. This is a hold-over from the FORTRAN77 days
of the archive, but serves to emphasize the development directory
nicely, so it stays. The recognized flag is -gui which
loads the GUI driven template, and a copy of the MetCal source code
into the working directory. Running spaopen without a flag
(but still with the directory name) will result in a directory
containing the standard driver template, and is the common usage
of the utility.
Most
subroutines, functions, interfaces,
and/or modules (templates may also work, but is of
little practical use). These options of course refer to the
subroutines of the archive. See section Structure of the SPA, for a
complete description of the archive's structure. The ability
to list the existing source is useful in two ways. Firstly, it
allows you to ensure that there is no repetition of subprogram names in
your development, and secondly it provides information on the
algorithms already coded in the SPA but not explicitly
referenced (inasmuch as the subprogram names provide useful information
about the functionality of the source).
spainfo to be able to find the appropriate
source. A file header, contained in the source, is printed
to STDOUT and contains package, interface, version, and functionality
information. There are two primary uses for spainfo. The
first is to scan the archive for pre-existing routines which may
be of interest to you. The second is in interfacing to pre-existing
routines, since a full list of the arguments and their properties
are displayed in the header. Note that spainfo produces
a warning message if it finds a generic subprogram.
spaextract utility allows
the user to obtain source from the correct archive subdirectory.
Any number of routines can be obtained simultaneously. Again,
the full file name must be provided so that spaextract
knows where to look in the archive for the required source.
comp90.d developer's
interface tool allows the developer to painlessly develop a
Makefile with a full dependency list and extract
dependent files for recompilation in seconds (depending on
the number of files to retrieve, of course). The only flag
recognized by comp90.d is the -opt option, which
compiles code in an optimized form. The compilation step can take
quite a bit longer in this case, but optimization will yield
returns at run time. comp90.d should be run any time
that there is a modification to the source file listing
of the directory so that all of its dependency lists are
updated. Note that any SPA files that are automatically
extracted by comp90.d are distribution cleanable. You should
therefore run make distclean before re-running comp90.d
in your working directory to clean out all of the
automatically-retrieved code. Once the Makefile is built,
it has the functionality of a standard GNU makefile.
The comp90.d utility requires some help in determining
dependencies for function calls. If the source that you develop
makes use of the functions foo and foo2, then
your code should contain a line like:
@verbatim
! external :: foo,foo2
Although this is a comment line for the FORTRAN90 compiler, it will
be correctly interpreted for the source's dependency list by
comp90.d. The other anomaly associated with the
comp90.d utility is the requirement of library loading,
again displayed near the top of the template file:
@verbatim
! load FST <- force comp90.d loading of ARMNLIB \
(FST library)
! load GEMPAK <- force comp90.d loading of GEMLIB \
(GEMPAK library)
! load NCARG <- force comp90.d loading of NCARG \
(NCAR Graphics library)
This will ensure that the proper libraries are loaded by the
linker to create the executable. (Of course, only the `load XXXX' is
required - the comments are optional). Note that NCARG loading
is not standard in the template file.
The plotFST utility is a GUI which accesses the sigma
plotting language developed by RPN. Clearly, this
tool will only be useful for those using the RPN standard
file data format. The interface is nearly entirely self-explanatory,
and can be reformatted to either menus (default) or columns
by selection in the Display menu. Both formats are
functionally identical.
Up to three variables can be plotted simultaneously (one for each
"set"). The sets are activated by pressing the button at the
top of the set's column. The initialized values are fairly common,
so often there is not a lot of modification required before a usable
product is obtained. Users familiar with the RPN
standard file format will be used to dealing with the IP3
identifier, which can be used to specify fields beyond simple
time and level stamps. The IP3 stamp is particularly useful
for plotFST when running the utility on analysis data
(in conjunction with splitFST).
The Settings menu allows the user to set map options and
to create axis labels. However, it also aids in the quick production
of plots. The Locking options refer to the propagation
of time, level, and IP3 settings across sets. For example,
if all three locks are engaged (as are, say, Sets 1 and 2)
and the bar at the top of Set 1 is pressed, then the time,
level, and IP3 settings of Set 1 are propagated to Set 2. If
the hour lock is disengaged, then only the level and IP3 settings
are propagated. This makes leveling and time changes
much faster and practically bombproof.
Also under the Settings menu, the user is given the
Time Series options of Multiple Times or
Multiple Files. The time series output is engaged
by entering a colon-separated list in the Hour entry
box for the sets (i.e. 0:48:6) of the form
start:end:step in hours. This functionality is
also available for the IP3 entry. The Multiple Times
option produces a single metafile (the output default
output from sigma) with multiple times in it;
the Multiple Files creates a separate file for
each time, especially useful for GIF generation.
The splitFST file formatting utility is usable only
for RPN Standard data files. A complete man
page for the tool is available online and contains a more
detailed description of the capabilities of the tool that
that presented here. The most useful application of
the splitFST utility is in the plotting of analysis
files using plotFST. The command splitFST -dates
will provide each individual analysis time in a combined
analysis file with a unique IP3 identifier. This allows
plotFST to use its IP3 entry to isolate analysis
times within the file. A full listing of the options
accepted by plotFST can be obtained with the
-h option.
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Jump to: a - c - d - e - f - g - i - m - o - p - r - s - t
This document was generated on 20 June 2003 using texi2html 1.56k.