This LAPS README file (version 0-36-7) is viewable on the WWW via the LAPB home page at http://laps.noaa.gov/
TABLE OF CONTENTS -----------------
Below is a description of the tar file containing the LAPS data ingest and analysis code. The predictive component of LAPS (MM5, RAMS/SFM, ETA) is set up separately (see Section 3.4).
Please note that GSD provides support for LAPS software only if a prior agreement is made to that effect. Additionally, questions concerning LAPS must be asked in reference to the latest released tar file; we cannot support older versions of LAPS code. It is also recommended that LAPS users try to take advantage of the latest LAPS updates by periodically importing a fresh tar file every few months or so. Please check the LAPS Software Page at ' http://laps.noaa.gov/cgi/LAPS_SOFTWARE.cgi for information about recent releases.
Open Source License/Disclaimer, Forecast Systems Laboratory NOAA/OAR/GSD, 325 Broadway Boulder, CO 80305
This software is distributed under the Open Source Definition, which may be found at http://www.opensource.org/.
In particular, redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain this notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must provide access to this notice, this list of conditions and the following disclaimer, and the underlying source code.
- All modifications to this software must be clearly documented, and are solely the responsibility of the agent making the modifications.
- If significant modifications or enhancements are made to this software, the GSD Software Policy Manager (softwaremgr.fsl@noaa.gov) should be notified.
THIS SOFTWARE AND ITS DOCUMENTATION ARE IN THE PUBLIC DOMAIN AND ARE FURNISHED "AS IS." THE AUTHORS, THE UNITED STATES GOVERNMENT, ITS INSTRUMENTALITIES, OFFICERS, EMPLOYEES, AND AGENTS MAKE NO WARRANTY, EXPRESS OR IMPLIED, AS TO THE USEFULNESS OF THE SOFTWARE AND DOCUMENTATION FOR ANY PURPOSE. THEY ASSUME NO RESPONSIBILITY (1) FOR THE USE OF THE SOFTWARE AND DOCUMENTATION; OR (2) TO PROVIDE TECHNICAL SUPPORT TO USERS.
Supported UNIX platforms include...
IBM rs6000 AIX4.3 NFS mounted disks should be mounted with
NFS version 2 instead of 3.
HP HPUX 10.20 Requires f90
SunOS (Solaris) 5.6 Requires f90
IRIX64 6.5 Requires f90
DEC (Alpha)
LINUX (i386,i686,x86_64) pgf90 is suggested, ifort being tested
LINUX (Alpha) fort is suggested
We are working on adding more supported platforms. We welcome suggestions on how to modify LAPS for other platforms/versions. Note that we cannot guarantee the portability of LAPS to all of these other platforms (e.g. Windows NT).
The NetCDF package is required for laps, it is available via internet at ' http://www.unidata.ucar.edu/packages/netcdf/ netcdf 3.3.1 or higher is required. Once netCDF is properly installed, check that the 'ncdump' and 'ncgen' programs are in your path (e.g. 'which ncdump'), so that 'configure' will find them and provide the laps package with the proper path.
NetCDF is a general format structure. The detailed format of each data file is self-describing (via 'ncdump'), and is mirrored in a separate static file called the CDL. This CDL can be GSD's version or someone elses.
The NetCDF library contains C routines that are to be linked with the LAPS FORTRAN routines. Please see the discussion in section 2.2.2.1 for details on troubleshooting this.
The perl package is also required for laps, it is available via internet at any perl site such as http://www.perl.com. Perl 5.003 or higher is required. Check that 'perl' is in your path (e.g. 'which perl').
Laps Makefiles work best by using gnu make (version 3.75 or higher). This is downloadable from gnu sites such as the following URL: ' http://www.gnu.org/software/make/make.html . You can check your version of gnu make by typing 'make -v'. Some vendor provided make utilities may also work, however if you find you are having problems in this area please try obtaining and using gnu make. Check that 'make' is in your path.
In general, an ANSI compliant C compiler should be used. On some hardware ANSI compliance requires a compiler flag, if you're not sure check the documentation for your compiler. Some platforms such as Solaris and HPUX do not come with an ANSI compliant C compiler by default. If you have not purchased that additional product from the vendor, we recommend GNU C (gcc) available at ' http://www.gnu.org/software/gcc/gcc.html . Check that the C compiler is in your path.
For Solaris platforms, 'cc' is recommended.
For HP-UX platforms, 'cc' is suggested.
Please note that LAPS uses dynamic memory within the FORTRAN code in the form of automatic and allocatable arrays, as well as other FORTRAN 90 constructs. This implies that you will need an 'f90' compiler or the equivalent. LAPS will no longer work on most 'f77' compilers. Check that the FORTRAN compiler is in your path.
For IBM/AIX platforms 'xlf' is recommended.
For Solaris & HP-UX platforms, 'f90' works well.
For Linux platforms (i386,i686,x86_64), 'pgf90' is suggested 'ifort' is being tested
For Linux platforms (Alpha chip), 'fort' is suggested (normal serial use).
The disk space requirements for LAPS vary depending on factors such as domain size and purge parameters. As a general guide, 10MB would be needed for source code. About 30MB are needed for executable binaries. 500MB to 1GB are typically needed for 12-24 hours worth of output data. A similar amount of space is needed for the raw input data.
'ulimit' settings should be placed at 'unlimited' if possible. Memory requirements vary for LAPS. As a general guide, 128MB is needed and 256MB is preferred. More is needed for large domains. For very large domains, a rough guide to the memory needed would be 100 x NX x NY x NZ bytes.
To build the lapsplot process, access to an NCAR graphics library is needed to be able to run the 'ncargf77' command. Lapsplot is an optional plotting program, thus NCAR graphics is optional. You might wish to check the following World Wide Web location for more info on this now free software...
The 'lapsplot.exe' executable is an interactive program that reads in the NetCDF LAPS files and produces a 'gmeta' file as output. The 'gmeta' file can be displayed using other NCAR graphics utilities like 'ctrans' and 'idt'. The 'gmeta' file can be converted into a GIF/JPEG file for web display by using 'ctrans' in conjunction with 'netpbm' or another similar method.
'Lapsplot' is designed to work with version 3.2 (or higher) of NCAR graphics. The environment variable $NCARG_ROOT should be set when configuring, compiling, or running 'lapsplot.exe'.
Before running 'configure', check that 'ncargf77' is in your path. If you are using a compiler other than 'f77', check after running 'configure' to see that the right thing was done by inspecting 'NCARGFC' and 'FC' within 'src/include/makefile.inc'. If configure wants you to use 'ncargf90', you may consider soft linking 'ncargf90' to the 'ncargf77' script or copying 'ncargf77' to a new location and calling it 'ncargf90'.
If you only have an 'ncarg90' script (i.e. no 'ncargf77'), you may want to also make a script called 'ncargf77' that lists the 'f77' compiler. This can help 'configure' do its test for making the switch over from 'ncargf77' to 'ncargf90'.
Lapsplot is built as a special option to 'make', simply type 'make lapsplot' or 'make install_lapsplot'. It is not built with a plain run of 'make'.
In order to get 'lapsplot' to compile and link properly it may be necessary to edit your own version of 'ncargf90' or even the original 'ncargf77' script. A possible alternative to fixing 'ncargf77/ncargf90' is to edit 'src/include/makefile.inc' with the full path for 'NCARGFC', and appropriate compiler for 'FC' (and possibly compiler flags) for your system (after running configure).
At times the linking of 'lapsplot' may show undefined references to library routines. This often represets a mismatch between NCAR graphics and various system libraries. Possible solutions for this include editing the library list within the 'ncargf77/ncargf90' script or switching the -Bstatic flag on or off.
'Lapsplot' can be modified to show political boundaries outside of the U.S. The following data files are relevant from the 'static/ncarg' directory: 'continent_minus_us.dat', 'state_from_counties.dat', and 'uscounty.dat'. These political boundary files are stored in big_endian format. These would need to be converted manually prior to using 'lapsplot', if your machine is expecting little_endian. We will consider automating this in the future.
We are starting to put some of our web related scripts (for analyses) into the repository such as 'etc/www/followup_ncarg.sh'. Web products are defined with some configuration files in 'static/www/lapsplot.*'. Color tables are specified in 'static/www/*.lut'. Other user definable parameters are located in 'static/lapsplot.nl'. These pre-generated web products can be driven by the 'sched.pl -f' command line argument. Please see section 2.4 for more info on 'sched.pl'.
Another web related script is our "on-the-fly" page that is contained in 'etc/www/nph-laps.cgi'. This can be made to work on your local system and web server with some modifications arrived at by trail and error.
To run lapsplot you can do the following...
1. setenv LAPS_DATA_ROOT to the correct path
2. run $LAPSINSTALLROOT/bin/lapsplot.exe (answer the questions it asks interactively)
3. idt gmeta
Please note that 'lapsplot' is provided to help you check out how your LAPS implementation is working. The LAPB Branch does not have any other plotting or visualization packages available for distribution with LAPS at this time. Many users have interfaced LAPS with their own display software (e.g. VIS5D, AVS, IDL, NCL, GEMPAK). Feel free to post questions about these to the 'laps-users' bulletin board Web Page. NCAR graphics in no way is essential to the successful running of LAPS to create output grids.
Another note of interest is that LAPS is visualized as an integral part of the AWIPS system. If you have AWIPS, then LAPS should be running on it and you can view its output on the workstation.
We have added support for the background models read by lga to now include GRIB-formatted files. External compression libraries required for decoding GRIB2-formatted files are libjasper.a, libpng.a, and libz.a and are usually found in /usr/lib. It is recommended to have a system administrator download and install these external libraries if they are not already on your system.
The 'configure' script will determine if these libraries are present. If all are found, 'configure' prepares the file 'src/include/makefile.inc' with DEGRIBLIBS, DEGRIBFLAGS and CDEGRIBFLAGS values allowing the lga software to build to read both GRIB1 and GRIB2-formatted files. Without these three specific compression libraries available, lga is built to read only GRIB1-formatted files in addition to NetCDF-formatted files.
See source directory: $LAPS_SRC_ROOT/src/lib/degrib/README_LIBS file for additional information.
To introduce this section, here is a hierarchical listing of some primary directories and files in the laps tree. The default LAPS structure is shown in the first tree below. These directories are created/addressed in various portions of section 2.2 and beyond.
Various "root" directories are mentioned in the form of environment variables. These can optionally be set to make it easier to follow the instructions below more literally. The installation scripts can be run without setting these variables if you'd like to enter the associated paths directly as command line input.
$LAPS_SRC_ROOT - The full path that was created when the LAPS tar file was untarred. This contains the source code and other supporting software. $LAPS_SRC_ROOT is needed for building LAPS but is not needed at runtime.
$LAPSINSTALLROOT - The full path of installed binaries and scripts (bin and etc). This is where you build the executables, configure the scripts (converted the *.pl.in to *.pl), and configure $LAPS_SRC_ROOT/src/include/makefile.inc. Note: $LAPS_SRC_ROOT and $LAPSINSTALLROOT are in many cases the same but don't have to be. $LAPSINSTALLROOT is needed at runtime.
$LAPS_DATA_ROOT - The full path to the output data and namelists. This includes lapsprd subdirectories containing both LAPS output grids and intermediate data files. $LAPS_DATA_ROOT is needed at runtime and it contains all the files configured to run an analysis domain localized to a location on earth. The $LAPSINSTALLROOT tree can drive several $LAPS_DATA_ROOTs. Input data in its "raw" form is stored outside the $LAPS_DATA_ROOT tree.
Note: $LAPS_DATA_ROOT is usually (and recommended to be) different than $LAPS_SRC_ROOT/data and $LAPSINSTALLROOT/data but they don't need to be. Also, $LAPS_SRC_ROOT/data/cdl and $LAPS_SRC_ROOT/data/static are the repository versions and should be kept pristine.
Note: the namelists you get from the tar are configured for our Colorado domain. More on localizing a domain for your own area later on.
To summarize, these three environment variables can either be part of one directory tree or split out into separate trees as further discussed at various times below.
/home_disk/
raw_data/ (optional raw test data)
geog/
world_topo_30s
albedo_ncep
landuse_30s
laps-m-n-o.tar
laps-m-n-o/ ($LAPS_SRC_ROOT=$LAPSINSTALLROOT)
Makefile
src/
ingest/
etc/ (laps scripts)
bin/ (executables)
data/ (default $LAPS_DATA_ROOT, can be moved/duplicated
original data tree that comes with tar file)
lapsprd/
product_list/ (laps output)
log/
static/
nest7grid.parms (namelist parameters)
*.nl (namelist parameters)
static.nest7grid (gridded topography)
time/
testdata/ (optional, can be relocated)
lapsprd/
product_list/
In many UNIX environments, large data files are stored on a "data" disk and the source code is stored on a smaller "home" disk. Below is a typical laps directory structure for that setup. We recommend using something like this setup, especially if you are constructing and localizing with your own domain and parameters that are different from our default Colorado setup.
/home_disk/
builds/
laps-m-n-o.tar
laps-m-n-o/ ($LAPS_SRC_ROOT = $LAPSINSTALLROOT)
Makefile
src/ (source code)
ingest/
etc/ (laps scripts)
bin/ (executables)
template ($TEMPLATE parameters)
/data_disk/
geog/
world_topo_30s
albedo_ncep
landuse_30s
raw_data/ (optional raw test data)
laps/
data*/ ($LAPS_DATA_ROOT, can be duplicated)
lapsprd/
product_list/ (laps output)
log/
static/
nest7grid.parms (namelist parameters)
*.nl (namelist parameters)
static.nest7grid (gridded topography)
time/
testdata/ (optional, can be relocated)
lapsprd/
product_list/
Place the tar file in the directory '/home_disk' or '/home_disk/builds'.
Untar the laps source code using a command like...
prompt> gzcat laps-m-n-o.tgz | tar xf -
OR...
prompt> gunzip laps-m-n-o.tgz
prompt> tar -xf laps-m-n-o.tar
The $LAPS_SRC_ROOT directory will be set up one level below the tar file.
If you are having trouble running 'gunzip', the problem could be that the 'laps-m-n-o.tgz' file was corrupted during the download. In that case simply try downloading again.
Go to the $LAPS_SRC_ROOT directory and run...
prompt> ./configure
'configure' supports many options, the most important is the --prefix option which tells make where to install the laps system (FORTRAN executables, Perl Scripts, etc.). The default (if you did not use --prefix) is to install whereever the source is. The use of the --prefix option is highly recommended to make it easier to update your source code (e.g. importing a new LAPS tar file), without disturbing the binaries, data, and runtime parameters that you are working with on-site. This goes along with the second directory tree diagram shown above in Section 2.0.
For example, to install laps in directory '/usr/local/laps' (i.e.
$LAPSINSTALLROOT) use...
prompt> ./configure --prefix=/usr/local/laps
One or more data directories for running laps can be specified at runtime, if desired. A single set of binaries can thus support several data directories as described below.
Another configure option is --arch. Configure tries to get the architecture from a 'uname' command, but this can be overridden by having an $ARCH environment variable or by using --arch. The allowed values for 'arch' include 'aix', 'hpux', etc.
For more information on passing in command line flags to 'configure' run...
prompt> ./configure --help
The 'configure' script automatically modifies the compiler and compilation flags by modifying 'src/include/makefile.inc' according to what type of platform you are on. Hopefully the flags will work OK on your particular platform. If you want to change the flags from the default set, you can provide command line arguments to the 'configure' script.
Some examples based on our experience are as follows:
Solaris...
prompt> ./configure --cc=cc
For IBM/AIX platforms, you will want to override the default FORTRAN
compiler with 'xlf' using the command line option --fc=xlf as follows...
prompt>./configure --fc=xlf
For SGI platforms, certain flags may be needed. '-mips3' seems to help on IRIX64 v6.2.
A second method of modifying the compiler flags is to edit 'src/include/makefile.inc', after running configure. If you find that the default compiler flags don't work for your platform or that your platform has no default, you'll need to experiment to find the right set of flags. Changes in 'src/include/makefile.inc' will automatically modify the flags used throughout laps. If you find flags that work for your platform and would like us to add them to the defaults in 'configure' please let us know via e-mail.
On Solaris for example, you may want to remove "-C" from the DBFLAGS with an edit of 'src/include/makefile.inc' to allow compiling FORTRAN debug versions of the software.
On some platforms (e.g. Linux) the linking of FORTRAN programs to NetCDF and other C library routines may need adjustment. This relates to the existence and number of underscores in the C routine names when called by FORTRAN routines. Fixes for this may include a combination of changing the number of underscores in the C routines, changing the CPPFLAGS for LAPS, or changing the FFLAGS for LAPS.
As an example, with errors linking to NetCDF "nf" routines, you might rebuild the NetCDF C library with a different number of underscores and/or adjust the FFLAGS according to the man page in your FORTRAN compiler. On a Linux-Intel machine the NetCDF library can be rebuilt with the following flags...
FC=pgf90
CC=gcc
CPPFLAGS=-DpgiFortran
FFLAGS=-O
Errors linking to other LAPS C routines can be addressed with other
adjustments to the CCPFLAGS (among FORTRANUNDERSCORE and
FORTRANDOUBLEUNDERSCORE) or the FFLAGS.
In this file (mainly Sec 2.3), a number of potential manual changes to ingest code are outlined prior to running 'make' and '$LAPSINSTALLROOT/etc/localize_domain.pl', especially if one is using ingest data formats other than "standard" ones used at GSD. After becoming familiar with the changes needed for your implementation, it is recommended that you develop a method to save the hand edited files in a "safe" place outside of the laps directory structure, or by using a revision control system such as CVS. This strategy would make it easier to update your implementation of LAPS with the latest 'laps-m-n-o.tgz' file from GSD, while minimizing the hassle involved with software modifications for your local implementation.
The next step is to build and install the executables, this can be done by running the following (note the syntax might vary depending on the shell you are using)...
prompt> cd $LAPS_SRC_ROOT
prompt> make 1> make.out 2>&1
prompt> make install 1> make_install.out 2>&1
prompt> make install_lapsplot 1> make_install_lapsplot.out 2>&1
Check that the executables have been placed into the '$LAPSINSTALLROOT/bin' directory. The total number should be the number of EXEDIRS in '$LAPS_SRC_ROOT/Makefile' plus 2; this includes 'lapsplot.exe'.
Lapsplot can be installed only if you have NCAR graphics.
We recommend using Gnu Make Version 3.75 or later available via ftp from any GNU site.
There are many other targets within the Makefile that can be used for specialized purposes, such as cleaning things up to get a fresh start. In particular, note that a 'make distclean' is recommended before running 'configure' a second time so that things will run smoothly.
Currently there are three mandatory geography databases required to localize a LAPS domain. These are:
1) terrain elevation 2) landuse category 3) albedo climatology.
The 30" terrain elevation data is found in the tar files for 'topo_30s'.
The landuse data is global 30" data and required to compute a land/water mask. The mask is used during localization to force consistency between the other geography data at land-water boundaries. Land fraction is derived from the landuse data using the water category, with valid values ranging continuously between 0.0 and 1.0.
The global albedo climatology database has less resolution than either the terrain or landuse data. The albedo is approximately 8.6 minutes (0.144 degs) and was obtained from the National Center for Environmental Prediction (NCEP). This data is used in the LAPS cloud analysis with visible imagery data.
The geography data come in compressed tar files separate from the rest of the LAPS distribution. The data are used in process 'gridgen_model' which is the fortran code to process all the geography data as specified by the user (see section 2.7.4 for more information about gridgen_model). Only one copy of the geography data is required no matter how many LAPS 'dataroot' installations you are supporting. The paths to the geography data directories (topo_30s, landuse_30s, and albedo_ncep) are defined as runtime parameters within the 'nest7grid.parms' file (Sec 2.2.6).
The geography data is available on the LAPS Home Web page (software link). You will find the following global data sets at this web/ftp site. Some of the data have been subdivided into "quartershperes" for easier downloading. Select the files needed for your application or get all of them if you intend to generate localizations around the entire globe. .
132446109 Aug 24 2001 topo_30s/topo_30s_NE.tar.gz 63435504 Aug 24 2001 topo_30s/topo_30s_NW.tar.gz 37194099 Aug 24 2001 topo_30s/topo_30s_SE.tar.gz 29204244 Aug 24 2001 topo_30s/topo_30s_SW.tar.gz
12324069 Aug 24 2001 landuse_30s/landuse_30s_NE.tar.gz 6118611 Aug 24 2001 landuse_30s/landuse_30s_NW.tar.gz 3355822 Aug 24 2001 landuse_30s/landuse_30s_SE.tar.gz 2808861 Aug 24 2001 landuse_30s/landuse_30s_SW.tar.gz
albedo_ncep/A90S000E albedo_ncep/A90S000W albedo_ncep/AHEADER
User note:
The laps process 'gridgen_model' described below in section 3.0 can also process soil type, mean annual soil temperature, and greeness fraction but these are not mandatory data required in LAPS and therefore we do no describe them here. You'll see some reference to these data bases below and we have added paths to this data in our namelist file (nest7grid.parms) but you should enter dummy paths for these data in the event you do not have them available. The gridgen_model process will warn that these data are not available but you should still see the localization run to completion (ie., static.nest7grid is generated).
Runtime parameter changes may be needed to tailor LAPS for your domain(s); this includes ingest and geography data path names, grid dimensions, grid location, and potentially other aspects of the data processing. The parameter files are 'data/static/nest7grid.parms', 'data/static/*.nl', and 'data/static/*/*.parms'.
The localization involves several operations. The parameter files are merged/updated with the repository versions if needed. The dimensions in the 'cdl' files are also adjusted. Then several executable programs are run including 'gridgen_model.exe' and 'gensfclut.exe' as per section 3.1.
Below are two mainly equivalent procedures for localizing LAPS to set up one or more domains. The first is a newer, more efficient (and highly recommended) method using domain "template" directories. The second is our original method for localization. You'll want to use either Method 1 or Method 2 but not both.
The first method is especially useful if you are using a separated data tree and/or multiple domains. It is also recommended if you are doing repeated software updates. Once you learn this method it can save a lot of time and errors that may occur in the course of using Method 2.
SETTING RUNTIME PARAMETERS
If you are working in a separated data directory (e.g. using the second tree shown above), you can set up a copy of the runtime parameter files (for each window) in a new directory (called $TEMPLATE) with a reduced parameter subset. The $TEMPLATE directory namelist files should contain only those parameters that need to be changed for each of the domain(s) from the settings in the repository, $LAPS_SRC_ROOT/data/static. The remaining unchanged parameters should be omitted from the $TEMPLATE versions. Otherwise the template namelist looks exactly like the originally supplied namelist, except that the comment section should be omitted. The modified $TEMPLATE parameters generally include map projection settings, data paths, etc. The remaining fixed parameters will later be automatically merged in from the '$LAPS_SRC_ROOT/data/static' directory tree by the localization scripts (next step).
Templates are normally maintained in a location independent of the LAPS distribution (e.g. see the template directory in the tree diagrams above). In general, they contain parameters dependent on the local implementation and relatively independent of software updates. Once you set up the template directory you'll be ready to run the 'window_domain_rt.pl' script. Here is an idealized example illustrating the namelist merging process that is done during the localization...
template repository tar file localized result
________ ___________________ ________________
$TEMPLATE/vad.nl $LAPS_SRC_ROOT/data/static/vad.nl $LAPS_DATA_ROOT/static/vad.nl
................ ................................. .............................
a=1 a=1
b=5 b=2 b=5
c=3 c=3
d=6 d=4 d=6
And here is an example of an actual template for the 'nest7grid.parms' file...
&lapsparms_nl
C80_DESCRIPTION = 'NOAA/GSD LAPS running for Taiwan CWB'
C6_MAPROJ = 'lambrt',
STANDARD_LATITUDE = 10.0,
STANDARD_LATITUDE2 = 40.0,
STANDARD_LONGITUDE = +120.0,
GRID_CEN_LAT = +23.578,
GRID_CEN_LON = +120.91,
GRID_SPACING_M = 9000.,
NX_L = 153,
NY_L = 141,
path_to_topt30s='/home/data_disk/geog/world_topo_30s',
path_to_landuse30s='/home/data_disk/geog/landuse_30s',
path_to_albedo = '/home/data_disk/geog/albedo_ncep',
path_to_raw_profiler='/pj/fsldat/point/profiler/netcdf/',
path_to_qc_acars='/home/data_disk/dat/acars/',
c8_project_common='CWB',
/
LOCALIZING with 'window_domain_rt.pl'
Generating new localizations, reconfiguring existing localizations, and reconfiguring existing localizations without removing lapsprd or log information is made easier with the perl script '$LAPSINSTALLROOT/etc/window_domain_rt.pl' ("window" hereafter). The window script makes use of namelist domain templates that specifically define a user's localizations. The window script uses environment variables $LAPS_SRC_ROOT, $LAPSINSTALLROOT, and $LAPS_DATA_ROOT, however, -s, -i, and -d command-line inputs override those environment variables as necessary depending on user needs. The -t command-line input specifies the domain template directory and the script saves the log/lapsprd history if command line switch '-c' is not used; or, completely removes $LAPS_DATA_ROOT, then does a 'mkdir $LAPS_DATAROOT' if '-c' is supplied. The '-w laps' is always required. The window script can be run manually when configuring or reconfiguring localizations. Window copies the domain template namelists (partial nest7grid.parms or *.nl's) into a new "static" subdirectory which, in turn, are merged with the full namelists by script localize_domain.pl. Recall that $LAPSINSTALLROOT contains bin/ and etc/ while $LAPS_SRC_ROOT contains the untarred full namelists from the repository.
In the event that $LAPS_SRC_ROOT does not exist, a data/ subdirectory containing static/ and cdl/ must be available for use by 'localize_domain.pl' (i.e. $LAPS_SRC_ROOT = $LAPSINSTALLROOT). Even though it is possible to have $LAPS_SRC_ROOT/data = $LAPSINSTALLROOT/data = $LAPS_DATA_ROOT, this is not recommended since it does not allow multiple localizations. Templates will ensure that specific namelist modifications are merged with the untarred full namelists. Templates also ensure that specifics to a localization are merged into new software ports and new namelist variables (available with new software) are merged into existing localizations.
Examples:
setenv LAPS_SRC_ROOT /usr/nfs/common/lapb/operational/laps
setenv LAPSINSTALLROOT /usr/nfs/lapb/operational/laps
setenv LAPS_DATA_ROOT "any new or existing LAPS_DATA_ROOT"
cd $LAPSINSTALLROOT
a) perl window_domain_rt.pl -w laps:
result: lapsprd and log saved; operational namelists and cdl's are copied
into $LAPS_DATA_ROOT/static; $LAPSINSTALLROOT/bin/gridgen_model.exe
runs to regenerate static.nest7grid. "Saved" lapsprd and log are
restored into $LAPS_DATA_ROOT.
b) perl window_domain_rt.pl -c -w laps:
result: same as a) although lapsprd and log are removed and regenerated by
"etc/makedatadirs.pm"
c) perl window_domain_rt.pl -t "full path to template directory" -w laps
result: similar to a) but namelist specifics are copied to $LAPS_DATA_ROOT/
static and merged with full namelists in $LAPSINSTALLROOT.
d) perl window_domain_rt.pl -s $LAPS_SRC_ROOT -i $LAPSINSTALLROOT
-d $LAPS_DATA_ROOT -t "full path to template directory" -w laps
result: similar to c) except all required information is provided on the
command line. Window will use the command line info instead of
getting the paths from the environment.
setenv LAPS_SRC_ROOT /awips/laps
setenv LAPSINSTALLROOT /data/fxa/laps_data
setenv LAPS_DATA_ROOT /data/fxa/laps
e) perl window_domain_rt.pl -t /data/fxa/laps_template -s /awips/laps \
-i /awips/laps -c -w laps
result: Specific AWIPS relocalization command for lapstools GUI. GUI writes
user input to laps_template/ (subset namelists; eg.,
nest7grid.parms); $LAPS_DATA_ROOT/static and cdl/ are moved to
laps_data/; $LAPS_DATA_ROOT is removed; new $LAPS_DATA_ROOT is
generated and subdirectory structure created by
"etc/makedatadirs.pm"; laps_template namelist are copied to new
$LAPS_DATA_ROOT; localize_domain.pl merges $LAPSINSTALLROOT/ and
regenerates static.nest7grid.
If you decide to manually change any parameters in $LAPS_DATA_ROOT/static after running the localization, it is suggested to make the same change in the $TEMPLATE directory as well. This will help preserve your local changes in the future if you install an updated version of LAPS.
This method is included partly for historical reasons and can be useful if you haven't yet learned how to use template directories and/or the separated $LAPS_DATA_ROOT (see method 1). This procedure provides a result equivalent to that from Localization Method #1 and provides an alternative method (even if not recommended) of modifying the parameters.
For each domain you wish to create, run...
prompt> cd $LAPSINSTALLROOT/etc
prompt> perl makedatadirs.pl --srcroot=$LAPS_SRC_ROOT --installroot=$LAPSINSTALLROOT --dataroot=$LAPS_DATA_ROOT --system_type=laps
where the path name $LAPS_DATA_ROOT must be named differently for each data domain if there is more than one. Recall that each domain can be set up in a separate subdirectory under '/data_disk/laps'. Next, follow the setup and localization steps below.
The order of the command line arguments is important, but only the first one is required. If for example a $LAPS_DATA_ROOT is not supplied, the dataroot tree location will default to where the LAPS binaries are installed via configure. Thus, the default value of $LAPS_DATA_ROOT is '$LAPSINSTALLROOT/data'.
The runtime parameters should be emplaced and/or modified within each $LAPS_DATA_ROOT directory tree prior to running the localization. More details on 'nest7grid.parms' and other parameter files are discussed in subsequent parts of Section 2.
As one option you can edit the parameter files that are in '$LAPS_SRC_ROOT/data/static' and tailor them for your domain. If you have '$LAPS_DATA_ROOT' different from '$LAPS_SRC_ROOT/data/static', then a good alternative may be to copy any parameter files you need to edit into '$LAPS_DATA_ROOT/static' from '$LAPS_SRC_ROOT/data/static'.
Finally, you can create the static data files and look up tables specific to the domain(s) you have defined in 'data/static/nest7grid.parms' and other runtime parameter files. Shown below is an example of running the localization for a particular laps domain. This should be repeated (with a unique dataroot) for each domain if there is more than one.
prompt> cd $LAPSINSTALLROOT/etc
prompt> perl localize_domain.pl --srcroot=$LAPS_SRC_ROOT --install_root=$LAPSINSTALLROOT --dataroot=$LAPS_DATA_ROOT --which_type = 'laps'
There is a layer of "raw" data ingest code that may have to be modified for the individual location depending on data formats. Its purpose is to reformat and preprocess the various types of raw data into simple common formats used by the subsequent analyses. It also helps to modularize the software.
Working with the ingest code is usually the largest task within the porting of LAPS. The supported component of the LAPS code is the analysis section. Ingest code is supported only if your raw data looks has the same configuration and format as GSD's raw data. It is the reponsibility of the LAPS user to modify the LAPS ingest code if necessary to generate the intermediate data files that are inputs to the analysis code.
A flow chart for the ingest processes may be found at this URL: http://laps.noaa.gov/doc/slide1_v3.gif
The default LAPS ingest code obtains "raw" data, generally from the GSD NIMBUS system. The raw data can either be in ASCII, NetCDF (as point data), or NetCDF (as gridded data - generally not on the LAPS grid). Note that the ingest code is also generally compatable with raw SBN/NOAAPORT data as stored in NetCDF files on the WFO-Advanced system. The ingest code processes the raw data and outputs the LAPS "intermediate" data files. The intermediate files are generally in ASCII for point data and NetCDF format for gridded data that have now been remapped onto the LAPS grid. Most ingest code is located under the 'src/ingest directory'. When NetCDf format is used for the raw data, a cdl file for the raw data is sometimes included in the source code directory.
Depending on the data source, you may generally prefer one of three choices:
1) Modify LAPS ingest code to accept your own raw data format. This often entails writing a subroutine that reads the data and linking this routine into the existing ingest process. That process then writes out the LAPS intermediate file. Note that generating an GSD style raw data file is not here needed - all that really counts is producing an intermediate data file.
2) Run a process independent of the LAPS ingest code that creates the intermedate data file.
3) Convert your raw data to appropriate NetCDF formats then run the LAPS ingest code as is. The CDLs and sample raw/NIMBUS NetCDF files supplied with our test dataset can serve as a guide to writing the software to do this. If the CDL is unavailable, doing 'ncdump -h' on the actual data file will yield equivalent information. We generally do not maintain or support any software for writing "raw" NetCDF files as this is done external to LAPS. Sometimes by posting a message to 'laps-users' you can obtain information from other LAPS users as to how they may have implemented this step.
For gridded data sources such as the model background, generally (1) or (3) is easiest. For surface and other point data sources option (2) is sometimes the easiest route.
You may note the following data sources used at GSD. These data sources are what the GSD ingest code is tailored to for producing intermediate data files. Note that LAPS will still run even if some of the data sources are withheld, albeit in degraded fashion. A minimum dataset of model background and surface observations is generally needed to get reasonable results.
The pathnames for the ingest data sources are assigned within the './data/static/nest7grid.parms' and other '*.nl' files and can be set accordingly at runtime. Doing a grep for 'path' in these files will give you a quick listing of the relevant parameters.
Unless otherwise specified, the time window for data in the intermediate data files should be '+/- laps_cycle_time'. The time window for data in the raw data files is more variable and is generally specified within the raw data (e.g. in the CDL).
Further information on specific LAPS ingest processes for the various data sources is found in Section 3 of this README.
The model first guess (background) is generally on a larger-scale grid than LAPS and is run independently. The model data is interpolated to the LAPS grid by the LAPS ingest to produce 'lga/lgb' files. This 'lga/lgb' output is distinct from the 'fua/fsf' files that are first guess files of similar format generated by the LAPS forecast model using an intermittent 4dda mode.
The 'nest7grid.parms' namelist variable "fdda_model_source" controls the background used in the analysis, including lga. A list of "fdda" backgrounds that are available with this release are specified in file etc/laps_tools.pm - module mkdatadirs. Even though fdda subdirectories are populated with current backgrounds, the analysis can be forced to override this by making the first entry of "fdda_model_source" = 'lga'.
The acceptable models and formats for the background model are listed in 'data/static/background.nl'. Many models can be accepted in NetCDF format. A new capability in LAPS is to process GRIB input without first converting to NetCDF format. For Grib data to be decoded an associated Vtable.XXX needs to be found in directory 'data/static/Variable_Tables'. There is no guarentee that any model specified in background.nl will work.
RUC grids are ftp'ed from NCEP to GSD, then converted at GSD from GRIB to NetCDF. This NetCDF file is the input for the LAPS ingest process that writes "lga". For more information on RUC check the following URL for more RUC info: ' http://maps.fsl.noaa.gov/
RUC is also available from UNIDATA and distributed to universities through private companies like Alden.
The conversion from GRIB to NetCDF is done outside of LAPS by GSD's Information and Technology Services (ITS) group (in the NIMBUS system). Having the CDL should mostly be sufficient along with general knowledge of NetCDF for writing out the data. Beyond that, you may wish to contact the ITS group for more info (see the reference to them in section 3.2.1). The Atlanta, Sterling, and Seattle WFOs have followed a more direct route, going from the RUC/Eta to the intermediate "lga" file, bypassing the NetCDF file on the model grid. This includes RUC on isobaric surfaces.
GRIB-formatted background model files are now supported and can be directly read into lga.
--- Where Can Users Find GRIB Data? --- At the NCEP ftp server for real time data sets located at ftp://ftpprd.ncep.noaa.gov/pub/data/nccf/com/. These products can be downloaded from the web or via anonymous ftp. The following is a discussion for locating and acquiring NAM, GFS, and RUC model backgrounds for use with lga. The models are available in grib1 and grib2 formats as indicated.
NAM Model: NAM 221 High Resolution North American grid, 32-km can be found at ftp://ftpprd.ncep.noaa.gov/pub/data/nccf/com/nam/prod/ with the directory and filenames as follows nam.{YYYYMMDD}/nam.t{CC}.awip32{FF}.tm00{.grib2} where YYYYMMDD is the current date, CC is the model cycle time (00, 06, 12, or 18) and FF is the forecast hour (00-84). awip32 indicates the 32 km North America (NCEP grid 221).
GFS Models: GFS global longitude-latitude grid (360x181) 1.0 deg (fh 00-180) can be found at ftp://ftpprd.ncep.noaa.gov/pub/data/nccf/com/gfs/prod/ gfs.{YYYYMMDDHH}{CC}/gfs.t{CC}z.pgrbf{XXX}{.grib2}, and GFS global longitude-latitude grid (720x361) 0.5 deg (fh 00-180) can be found at ftp://ftpprd.ncep.noaa.gov/pub/data/nccf/com/gfs/prod/ gfs.{YYYYMMDDHH}{CC}/gfs.t{CC}z.pgrb2f{XXX} where CC is the model cycle time (i.e. 00, 06, 12, 18) and XXX is the forecast hour of product from 00 - 180.
The 1.0 degree GFS uses file identifier 'pgrb' (pressure-based grib) and is now available in grib2 as well when '.grib2' is present. The 0.5 degree GFS uses 'pgrb2' (pressure-based) and is only available in grib2.
RUC Model: RUC Rapid Update Cycle 40km and 20km pressure data sets can be found at ftp://ftpprd.ncep.noaa.gov/pub/data/nccf/com/ruc ruc2a.{YYYYMMDDHH}/ruc2.t{CC}z.pgrb{XXX}{.grib2} where CC is the model cycle time (i.e. 00, 06, 12, 18) and XXX is the forecast hour of product from 00 - 12 (or more). File identifier 'pgrb' is used for the 40km resolution and 'pgrb20' is used for the 20km.
Additional description of NCEP products can be found at http://www.nco.ncep.noaa.gov/pmb/products/. A master list of NCEP GRIDS ID numbers (e.g. 211) and other specifications can be found at http://www.nco.ncep.noaa.gov/pmb/docs/on388/tableb.html
--- How Do Users Name The GRIB Data Files? --- For LAPS initialization at NOAA/ESRL, we have a process that automatically downloads GRIB files to a designated directory. For example, /data/grid/gfs/global_0p5deg/, /data/grid/gfs/global_1p0deg/, and /data/grid/gfs/conus211/ are three directories for the GFS global 0.5 degree, global 1.0 degree and CONUS 211 domains. The files within these directories are renamed from the complex patterns listed above to filenames with the following pattern: YYJJJHHMMFFFF. So, a file for GFS CONUS 211 on Jul 23, 2008, 12 UTC, 6 forecast would be named /data/grid/gfs/conus211/grib/08205120006.
--- How Does lga.exe Know Where To Find The Data? --- For lga.exe, the acceptable models, directory paths and file formats are identified in 'data/static/background.nl'. In the example above if we wanted to use the US-scaled data, we would set bgpath='/data/grid/gfs/conus211/grib/', bgmodel=13 (for GRIB), and cmodel='GFS'.
The following are intermediate files for various forms of radar data. These may have already been pre-processed (remapped) from "raw" data, and at this stage are in Cartesian format on the LAPS grid.
(vrc) - Low-level reflectivity from single or
multiple radars. For example, our ingest
at GSD processes WSI-NOWRAD, stored at GSD
in NetCDF, to create the 'vrc' intermediate
file. Narrowband single-tilt data from AWIPS
is also stored in 'vrc' files.
(v01, v02, ... ) - WSR-88Ds or other radar data are stored as
a full volume.
- Each 'vxx' file has 3-d reflectivity,
velocity, and nyquist velocity for one
radar. Horizontal and vertical gaps are
filled in for reflectivity while sparse
arrays are used for velocity.
(vrz) - 3-D reflectivity mosaic from multiple radars
('vxx' files).
(ln3) - Layer reflectivity and echo tops, from a
single radar or mosaiced from multiple
radars. For example, WSI sends put a variety
of derived products from the WSR-88D's
which we call nexrad products. These
include 3 layer reflectivity products,
a composite reflectivity, echo tops, and
vil. FD also decodes these and writes
netCDF files. We have an experimental
process called 'ln3' that ingests these
data that we haven't yet approved for
release in our tar. This will probably
happen shortly though as the need
to further test/use this 3D reflectivity in
LAPS is increasing.
As of 9-22-98 we have committed the ln3 ingest
process to our repository and distribute this
source code with our tarfile. The reliability
of echo tops in conjunction with the layer
reflecitivity information still makes this a
problematical data set to use in the analyses.
Committing this source to the repository will
help to further investigate the utility of this
product.
The key fields from 'ln3' which are used
in the analyses are the Layer reflectivity
(0-4 km MSL, 4-8 km MSL, and >8 km MSL), as
well as echo tops (MSL).
A flow chart showing radar data usage in LAPS is on the Web at: ' http://laps.noaa.gov/albers/laps/radar/laps_radar_ingest.html , together with some text details in: ' http://laps.noaa.gov/albers/radar_decision_tree.txt . These include information on which types of radar data are processed via the various intermediate data files.
Further information on using individual radar ingest processes is in Section 3. Specifically we should establish whether your raw data is in polar or Cartesian form. If polar, please take a look at "Polar Radar Data" in section 3.2.3. NOWRAD / WSI (Cartesian) data is covered separately within Section 3.2.4.
Sfc Obs (lso): GSD uses surface data as input with the default being GSD's NIMBUS NetCDF format. A few other METAR formats are now being supported as listed in the 'static/obs_driver.nl' namelist. The GSD code is in the '.../src/ingest/sao' directory, and includes routines to read and reformat various surface data types (METAR/SYNOP, mesonet or local/LDAD, buoy/ship or maritime, and GPS/profiler surface obs). There is a subroutine tree outline in the 'src/ingest/sao/README' file including information on the supported data formats for each observation type. Users may need to modify/write the necessary routines to read their data formats to be able to output the ASCII LSO file. Looking in detail at the routines in the 'src/ingest/sao' directory may provide enough information to get you started on any needed modifications.
Paths to the datasets are specified in the 'obs_driver.nl' file. The surface data, including many the types mentioned above, over much of the world are available in realtime from GSD with some restrictions. This data, generally in 'WFO/AWIPS' NetCDF format, are distributed via GSD's MADIS project at http://www-sdd.fsl.noaa.gov/MADIS/. The supported MADIS LDAD surface observation dataset is 'mesonet'.
Note that only observations reasonably near the standard shelter height (2 meters, except 10 meters for wind) should be included in the LSO file. Tower mounted instruments should instead be placed in the SND file using "TOWER" for the observation type.
Profilers/RASS (pro/lrs) - The raw data are obtained from GSD's NIMBUS database and/or AWIPS in NetCDF format where they are stored in four different directories. The data originally come from GSD's Demonstration Branch (DB) from two main networks. The 30+ NPN (National Profiler Network - NOAAnet) profiler network is located mostly in the central U.S.
The second network supplies boundary layer profilers for both wind and temperature, with formats including NIMBUS, MADIS Multi-Agency Profilers (LDAD), and RSA (LDAD) format.
The profiler data for wind goes into the 'pro' intermediate file, and RASS temperature profiles go into the 'lrs' intermediate file. Note that the cdl's associated with each data source indicate the time frequency of the data that our ingest code can process.
To summarize...
Network Database(s) file frequency cdl(s)
------- ----------- ---- --------- -----------
NPN wind NIMBUS/AWIPS/MADIS/ PRO 404 MHz wpdn60.cdl
FTP wpdn06.cdl
NPN RASS NIMBUS/FTP LRS rass60.cdl
rass06.cdl
BLP wind NIMBUS PRO 915 MHz wpdn60.cdl
wpdn30.cdl*
BLP RASS NIMBUS LRS rass60.cdl
rass30.cdl*
BLP wind RSA/MADIS-MAP PRO 915 MHz
50 MHz
SODAR
BLP RASS RSA/MADIS-MAP LRS 915 MHz
50 MHz
* Indicates that the data with this cdl is available, but our
ingest code would need modification to process it.
The NPN wind profiler data is available via another route from GSD with some restrictions. This data, in 'WFO/AWIPS' NetCDF format, is distributed via GSD's MADIS project at http://www-sdd.fsl.noaa.gov/MADIS/
Another method to obtain NPN wind and RASS files is from the FTP server mentioned above, more specifically at this location... ftp://oak.fsl.noaa.gov/outgoing/npn/
PIREPS (pin) - We are ingesting GSD NIMBUS and WFO/AWIPS (NetCDF) pirep files to translate the cloud layers from voice pilot reports into intermediate "PIN" files.
ACARS (pin) - We are ingesting GSD NIMBUS, WFO/AWIPS (NetCDF) and AFWA databases for ACARS data to translate the automated aircraft observations. The wind, temperature and humidity obs are appended to our intermediate "PIN" file. A NIMBUS equivalent NetCDF database is available (with some restrictions) on the Web via MADIS at http://www-sdd.fsl.noaa.gov/MADIS/
Note the TAMDAR is presently being screened out from the NIMBUS database while this data source is being validated.
RAOBs (snd): GSD NIMBUS, WFO/AWIPS, CWB, or AFWA databases. These are available in real-time from GSD with some restrictions. RAOB data in 'WFO/AWIPS' NetCDF format is distributed via GSD's MADIS project at http://www-sdd.fsl.noaa.gov/MADIS/
Dropsondes (snd): A Dropsonde ingest module has been developed for the CWB database. An ingest module has also been developed for AVAPS. We now allow the SND format to be used as input (so far just for the "AIRDROP" project). For the SND input option, the ingest program simply does a time windowing of the raw data. We may include modules for other (e.g. NetCDF) databases in the future, such as NIMBUS or WFO/AWIPS.
Radiometers (snd): A radiometer ingest module has been developed for the MADIS database - http://www-sdd.fsl.noaa.gov/MADIS/
Satellite Image Ingest (lvd): GOES data ingest. Data is stored at GSD in NetCDF or AWIPS/NOAAPORT/SBN data (also in NetCDF). Ingest of Air Force Weather Agency (AFWA) satellite data is also possible. Raw GVAR satellite data can be ingested and navigated using GIMLOC routines. Further details can be found in the file 'src/ingest/satellite/lvd/README'. Another option under development is to use flat files (ascii files generated by RAMSDIS or binary data) as input. The flat file ingest is still under development as of 3-11-98.
Satellite Sounder Ingest (lsr): GOES satellite sounder data ingest. Program lsr_driver.exe processes data from both satellites. Product files are yyjjjhhmm.lsr and stored in subdirectories lapsprd/lsr/'satid'. Nineteen channels. Output is Radiance. The namelist 'data/static/sat_sounder.nl' defines the appropriate parameters for this ingest process. Only the moisture analysis is using this product. Currently GSD /public sounder files in netCDF format are processed. This data is useful only when GOES Vapor (GVAP) is unavailable.
Satellite derived soundings (snd): We have interfaces to GOES binary and MADIS POES formats. AFWA database format was previously used at GSD though not currently. For other formats you may wish to supply your own routine to convert your raw data into the 'snd' format.
GPS: LAPS uses GPS data from NIMBUS NetCDF files. The precipitable water is used in the humidity analysis and surface observations are read into the surface analyses.
There is a second format known as (LDAD) NetCDF that carries GPS data. This format can supply GPS surface data to the LAPS intermediate 'lso' file. LAPS does not yet read precipitable water from the LDAD format.
Radar VAD Algorithm winds (pro) GSD NIMBUS NetCDF database, from WSR-88D algorithm output. GSD obtains this from NCEP and does not presently redistribute it.
SODAR data (pro) - This is treated in a similar manner to wind profilers and can be processed by LAPS ingest to appear in the PRO file. This is available as part of the RSA project at Kennedy and Vandenberg Space Centers and comes into NetCDF format via AWIPS/LDAD.
Met Tower data (snd) - This is treated in a similar manner to RAOBs and can be processed by LAPS ingest to appear in the SND file. This is available as part of the RSA project at Kennedy and Vandenberg Space Centers and comes into NetCDF format via AWIPS/LDAD.
Radiometric Profiler (snd): We have an interface to radiometric profilers (in NetCDF via NIMBUS) that can be used for the temperature and humidity analyses.
Cloud Drift Winds (cdw): We are ingesting the ASCII satellite cloud-drift wind files for use in the wind analysis. These come from NESDIS (via NIMBUS) as well as from CWB and AFWA. We can also utilize NetCDF files from MADIS.
LAPS runs in real-time under cron; there is a sample cron script in '$LAPSINSTALLROOT/util/cronfile'. Referring to this cron, you can see that once each hour (or other cycle time), the main './etc/sched.pl' runs. As an example at GSD, we run the 'sched.pl' hourly at :20 after the top of the hour. By inspecting the 'sched.pl' file you can see the various executables that are run in a certain order. You might want to modify the 'sched.pl' file for your needs.
In the sample cron script several ingest processes are run separately from the 'sched.pl'. For example the satellite ingest (lvd) is run several times per hour and utilizes './etc/laps_driver.pl'. NOWRAD Radar ingest (vrc) is also run at more frequent intervals. You might also choose to run 'remap_polar_netcdf.exe' for radar ingest in this manner.
On many unix systems jobs that run in cron do not have access to the environment defined by the user. They instead use a system default environment defined in '/etc/profile'; thus 'perl' may not be in the $PATH.. The cron file uses the full path to 'perl' to ensure that this will not be a problem. If the path to 'ncgen' is not in '/etc/profile', then you may want to add this to your own '.profile' file.
Each script in the cron requires the path to laps as a command line argument. A second optional argument specifies the path to the laps data directory structure; this path defaults to '/fullpathto/laps/data' if not provided.
The 'util/cronfile' is created by the configure step. Much of the needed editing has already been done in the creation of this file. You might see some remaining '@....@' constructs though that can be edited either manually or by running the 'cronfile.pl' (next paragraph). The @laps_data_root@ can be replaced with your path to $LAPS_DATA_ROOT and the optional @followup@ can be replaced with anything you wish to run after the 'sched.pl' has completed (using a semicolon to separate the two commands).
There is also a script called 'etc/cronfile.pl' that creates a modified version of 'util/cronfile' tailored to a given domain. This script can be run manually and the output location of the cronfile is located in '$LAPS_DATA_ROOT/cronfile'.
The frequency of the cron entries for running 'sched.pl' is defined to be the LAPS cycle time. This should correspond to the value of the 'laps_cycle_time' parameter within the 'nest7grid.parms' file.
The best timing of the cron is often related to the arrival time of the raw surface observations. For example, if most of the surface data arrives within 20 minutes of the observation time, then running the cron 20 minutes after the 'systime' would be optimum. The time window for acceptance of surface stations in the LSO file can be controlled by runtime parameters in 'obs_driver.nl'.
Once we get the 'sfc_qc.exe' Kalman module operating in LAPS, we may be able to recommend running LAPS earlier. In that future mode, LAPS would process each most recent observation available and project ahead if needed any observations that did not yet arrive for the current 'systime'.
In most cases, the data cutoff time window for 3D observations is +/-laps_cycle_time/2 or +/-laps_cycle_time. For example an hourly LAPS cycle accepts RAOB data from a +/-60 minute time window and ACARS from a +/-30 minute window.
The script '/etc/purger.pl' purges the 'lapsprd' output files and is in turn run by the 'sched.pl'. There are default settings in place for the number of files and age of files to be kept. These can be overridden in three ways.
1) The 'sched.pl' command line options '-r -m N', where "N" is the (default) maximum number of files to be kept in each product directory by the purger
2) Overrides can be read in from '/data/static/purger.dat'. You can see the 'purger.pl' script to see how that information is used.
3) Simply edit the 'purger.pl' to change it accordingly.
Tar files containing test data (called 'lapsdata*') are available that contain a snapshot of several hour's worth of laps data from the Colorado domain using namelist settings taken from the repository. The tar files include intermediate files from the 'ingest' code plus outputs from the 'analysis' code. Several consecutive analysis cycles are posted with one file per cycle. Included are the contents of the 'lapsprd', 'time', 'static', and 'log' subdirectories under 'data' or $LAPS_DATA_ROOT. The log files are useful for diagnosing any differences in output you may observe. The contents of the various directories are outlined elsewhere in this README file. The data was created using the latest software release. Our users can download this data at this URL:
' http://laps.noaa.gov/cgi/LAPS_SOFTWARE.cgi .
It is suggested here to test the localization procedure to ensure that all the static files needed to run LAPS are present. To do this, check that the paths to the geography data are correct in '$TEMPLATE/nest7grid.parms' and/or '$LAPS_DATA_ROOT/static/nest7grid.parms'.
When running LAPS as a whole for the archived data, the 'etc/sched.pl' script will accept a '-A' command line argument. This forces the script to run for the time you are inputting instead of the current time. An example call is shown as follows...
prompt> perl sched.pl -A dd-mmm-yyyy-hhmm $LAPSINSTALLROOT $LAPS_DATA_ROOT
...where the inputted 'dd-mmm-yyyy-hhmm' value is the date (for example 28-Aug-2007-1500). This date can be inferred from the contents of '$LAPS_DATA_ROOT/time/systime.dat'. Best results are obtained when using a time just prior to the latest raw data tarfile time.
One can also initiate individual executables (bin directory) listed in the 'sched.pl' to run on the test data. This often helps in getting a better match between your output and ours. Note that $LAPS_DATA_ROOT needs to be set as an environment variable when executables are run individually. The time of the run is specified in '$LAPS_DATA_ROOT/time/systime.dat'. This can be modified if needed if you want to try a slightly different time from the one supplied. To do this, interactively run the script '$LAPSINSTALLROOT/etc/systime.pl' and write the standard output to '$LAPS_DATA_ROOT/time/systime.dat'.
Note that for any given process or set of processes, deviations from the GSD output may be caused by differences in the inputs as well as machine roundoff error. Most, but perhaps not all of the input data is supplied. One main area to check would be differences in available "raw" background data files. Having all of the data history from 'lapsprd' may also be an issue; this may be less of a problem if you run laps for the latest hour of data that is supplied. The history is then supplied from earlier 'lapsdata*/lapsprd' output. Output differences can be tracked down by recompiling specific analyses with the '-g' option. This can be done by typing 'make debug' in the appropriate 'src' directories. Various debuggers can then be used such as 'dbx'. Examination of the log files again is helpful.
We have a new script (in 2004) called 'casererun.pl' that can be used for archive data runs. We have yet to try it on the supplied test data case though it could prove to be useful.
You may want to check that any analysis outputs from this time are not present, leaving only the 'ingest' outputs in place. This may improve the results of comparisons of your own output with GSD analysis output, though this step is not always necessary. You might consider adding the '-T' command line option when you run 'sched.pl' so that we run the analysis executables only thus skipping the ingest processes. This can be done if the ingest outputs (i.e. analysis inputs) are already present in the various 'lapsprd' subdirectories.
One way to supply the analysis inputs is as follows for each input (taken from a list of ingest outputs, see section 3.2):
prompt> cp testdata/lapsprd/[inputlist]/*
$LAPS_DATA_ROOT/lapsprd/[inputlist]
OR
prompt> cd $LAPS_DATA_ROOT/lapsprd
prompt> ln -s testdata/lapsprd/[inputlist] .
For this type of test, you will want to download the 'rawdata*' tar files into your 'raw_data' directory to start the processing of LAPS. Recall that the 'raw_data' directory is on a separate tree than $LAPS_DATA_ROOT.
Raw data formats and filename conventions are consistent with the default namelist settings taken from the repository. This is generally in NIMBUS (self describing NetCDF) format with associated file naming conventions. A typical filename on NIMBUS looks like this: '0606701000100o' meaning 'yydddhhmmHHMM' where 'ddd' is the day of year, 'hhmm' is the time of day and 'HHMM' is the file recurrence interval. The 'o' at the end means that observations are binned into files according to observation time (instead of 'r' for receipt time) More about NIMBUS is detailed in publications on the web at this URL: http://www.fsl.noaa.gov/its/papers/jb_ams94.html
Time information will be needed in the form of 'data/time/systime.dat'; this can be extracted from the 'lapsdata*' tar file.
The 'raw_data' directory is a convenient place to store test data. User supplied raw data for operational runs can be stored anywhere on your system, often outside of the LAPS trees.
Note that the 'lapsdata*' tar files contain intermediate plus analysis output files only. The 'rawdata*' tar files supply much of the "raw" data that are inputted to the ingest processes. The times for the raw data match the 'lapsdata*' output approximately but not always exactly (one example being the raw background data files). As a hint with the background data check that the available raw files bracket the systime of interest. If needed one can change the 'use_analysis' flag in 'background.nl' to get 'lga.exe' to work better.
In many cases, a user could independently generate the intermediate data files (ingest output) and then compare them with ours. If other "raw" files are needed as they appear on GSD's NIMBUS & MADIS systems, please let us know and we can try to add them to our test data case or send them separately.
Once the laps library is compiled (as outlined above), laps grids can be read. There are three levels of software that can access the data.
1. Lowest Level - NetCDF c routine calls (not recommended unless you're
a NetCDF hacker)
2. Medium Level - READ_LAPS_DATA - look at the source code in
lib/readlapsdata.f for the arguments.
3. Highest (and easiest) level - get_laps_3d or get_laps_2d. The source
is contained in src/lib/laps_io.f. The various grids available are
listed later in this README file under the heading "NetCDF organization"
To link to the reading routines, you will want to link to:
laps/src/lib/liblaps.a libnetcdf.a
Laps will allow you to change the horizontal domain after compilation and before the running of the localization scripts. Below is a list of the relevant changes.
The dimensions and location of the horizontal domain can be changed at run time. Prior to running 'window_domain_rt.pl', set the following parameters in 'data/static/nest7grid.parms' or in the corresponding template directory (needed only if you are outside the default Colorado domain). This script in turn runs 'gridgen_model.exe' and other programs.
Adjust the horizontal dimensions in terms of the number of grid points (NX_L, NY_L) in './data/static/nest7grid.parms'.
NOTE: Various files in the ./data/cdl directory are automatically edited by ./etc/localize_domain.pl using the values found in './data/static/nest7grid.parms'.
1) Modify the 'grid_spacing_m' parameter (only if you want to
change from the default 10000m for the grid spacing).
Grid spacing in meters on the projection plane. Used for all
projections.
2) Modify the 'grid_cen_lat' and 'grid_cen_lon' parameters.
These are the latitude and longitude of the center of the
domain, expressed in degrees. The parameters are needed for
all projections.
3) c6_maproj:
Polar stereographic:
Set to 'plrstr'.
Lambert Conformal:
Set to 'lambrt'.
Mercator:
Set to 'merctr'.
In most cases, the Lambert projection is recommended.
Mercator is recommended if the domain includes the
equator, or for domains centered in the tropics where
sin(latitude) varies by more than a factor of two over the
domain.
If the domain includes one of the geographic poles, then
Polar Stereographic should be used instead.
See the note below regarding current map projection limitations.
4) standard_longitude:
Polar Stereographic:
This defines the longitude which is straight up and down
(parallel to the "y" axis) in the map projection.
Lambert Conformal:
This defines the longitude which is straight up and down
(parallel to the "y" axis) in the map projection.
Mercator:
N/A
5) standard_latitude:
Polar Stereographic:
This is the latitude at which the grid spacing is exactly
the nominal value ('grid_spacing_m' e.g. 10km).
This parameter is usually set to +/-90 degrees to match
the latitude of the projection pole ('standard_latitude2'),
given that the projection pole is at one of earth's
geographic poles. The actual grid spacing (measured on
the earth's surface) matches the 'grid_spacing_m'
parameter at the projection pole, which may or may not be
located within your domain. For domains distant from the
projection pole, the actual grid spacing inside the domain
becomes noticeably less. The value of 'grid_spacing_m'
can be increased to compensate. The projection plane is
tangent to the earth's surface.
When the projection pole is at a geographic pole,
'standard_latitude' can be set to values other than +/-90.
The 'grid_spacing_m' parameter then represents the
true grid spacing (measured on the earth's surface) at a
latitude of 'standard_latitude'. The projection plane
is secant to the earth's surface.
Consider the angle 'psi' which is the angular distance from
the pole of the projection. 'phi' = 90 - 'psi'. The map
factor 'sigma' is (1+sin(phi0))/(1+sin(phi)) and becomes
unity when 'phi' for a particular grid point is equal to
'phi0'. This occurs when you are located at the
'standard_latitude' for the case of a "secant" projection.
Note that the grid spacing for a particular location in
the domain is equal to 'grid_spacing_m'/'sigma'.
Example 1: grid_spacing_m = 10000.
standard_latitude = +90.
standard_latitude2 = +90.
grid_cen_lat = +40.
grid_spacing at projection (north) pole = 10km
grid_spacing at domain center (+40) ~ 8km
Example 2: grid_spacing_m = 10000.
standard_latitude = +40.
standard_latitude2 = +90.
grid_cen_lat = +40.
grid_spacing at projection (north) pole ~ 12km
grid_spacing at domain center (+40) = 10km
Example 3: grid_spacing_m = 10000.
standard_latitude = -90.
standard_latitude2 = -90.
grid_cen_lat = +40.
grid_spacing at projection (south) pole = 10km
grid_spacing at domain center (-40) ~ 8km
Example 4: grid_spacing_m = 10000.
standard_latitude = -40.
standard_latitude2 = -90.
grid_cen_lat = -40.
grid_spacing at projection (south) pole ~ 12km
grid_spacing at domain center (-40) = 10km
Note that the 'Dx' and 'Dy' values that appear in the
'static.nest7grid' should equal the value of
'grid_spacing_m'.
Lambert:
This is the latitude at which the grid spacing is exactly
the nominal value (e.g. 10km). The projection cone will
intersect the Earth's surface at this latitude.
Mercator:
This is the latitude at which the grid spacing is exactly
the nominal value (e.g. 10km). Equivalently this is the
latitude at which the projection cylinder intersects the
Earth.
6) standard_latitude2:
Polar Stereographic:
This must be set to +90. or -90. and defines the pole
latitude of the polar stereographic projection
(Earth's North or South Pole).
Lambert:
For a tangent lambert (e.g. CONUS), set this equal to
the 'standard_latitude' parameter. For a secant
(two-latitude) lambert, set this to the second true
latitude where the projection cone intersects the surface.
Mercator:
N/A
When you run ./etc/localize_domain.pl, the NetCDF static file 'static.nest7grid' will be automatically generated by process 'gridgen_model.exe'. This contains grids of latitude, longitude, elevation, and land (vs. water) fraction.
The following output message, "topo_30s file /U50N119W does not exist", does not necessarily mean there is a problem. It may signify that your domain runs outside the available 30" data, and should still be covered by the 10' worldwide data, if you are using the 'topo_30s' dataset. Other WARNINGs or ERRORs may be more significant.
LAPS runs with the polar stereographic, lambert, and mercator projections. Please let us know if you encounter any problems.
The polar stereographic projection has a pole that may be set to either earth's north or south geographic poles.
Setting the pole to an arbitrary lat/lon (local stereographic) is a possible future enhancement. A test local stereographic domain gave an error of 2km in the grid points; the test code works in cases where the projection pole coincides with the center of the domain. Further improvement of this may include more fully converting library subroutines 'GETOPS' and (possibly) 'PSTOGE' to double precision.
The projection rotation routine 'projrot_laps' also has some approximations when local stereographic is used. These need to be checked for their validity and refined if needed. Cases of interest include a projection pole point at the domain center, as well as offset from the center.
The local stereographic projection also ignores 'standard_latitude' from the namelist so this is internally assumed to be +90. This means that the grid spacing is valid at the projection pole location, regardless of both where on the earth the pole is and the pole's latitude.
The map projection calculations are performed with a spherical earth assumption.
The default value of the 'grid_spacing_m' parameter is 10000m. This is one of the parameters used in constructing the static file (as mentioned above). To date, we have run LAPS with resolutions ranging from 1000m to 48000m.
Edit the file 'data/static/nest7grid.parms'...
1) silavwt_parm:
Default value of 0. This parameter allows the potential use of
silhouette terrain which is the maximum elevation in the local area.
Useful range is anywhere between 0-1. A value of zero uses the
average terrain instead of the maximum. Note that a value of 1
may reduce the apparent effect of filtering with 'toptwvl_parm'.
2) toptwvl_parm:
For example, a value of 4 represents 4 delta-x filtering of the
terrain. You can change this to alter the smoothness of the
terrain. Higher numbers mean smoother terrain.
PRESSURE OF THE LEVELS (and vertical resolution):
To do this, perform the following between untarring the tar file and localizing LAPS
1. Edit 'data/static/pressures.nl'
Update the list of pressures that go in sequence from higher to lower pressures (bottom to top)
Note that the vertical grid uses pressure coordinates and that the vertical pressure interval can vary between levels. Of course, the top pressure should be greater than zero mb. The bottom level should extend below the terrain and below the observations. The pressure values must be in multiples of 100 pascals, corresponding to an integer number of millibars.
NUMBER OF LEVELS:
1. The default value of 'nk_laps' is set to 21 levels in 'data/static/nest7grid.parms' and will automatically be reset during the localization (based on the contents of 'pressures.nl').
2. Note that not all data sources have been tested with other than 21 vertical levels, particularly some aspects of the forward radiance model used in satellite data processing, and compatibility with model background data will depend of the vertical extent of that data source.
Note: If you are feeding LAPS output into an AWIPS workstation, then additional workstation related changes may be needed.
The default cycle time is 60 minutes. To change this, do as follows...
1. Edit runtime parameter file 'data/static/nest7grid.parms' to change the value of 'laps_cycle_time'.
Recent changes as of February 26, 2006 NAMELIST
The namelist file ./laps/static/moisture_switch.nl controls the data assimilation within the moisture analysis. This file is self-documented, refer to it for details. This file has not changed in this latest update however, one of it's controlling aspects is GVAP or GOES vapor (total precipitable water, product data) and the application of this data has changed since a major implementation change March 2005.
OPTRAN
The NESDIS Community Radiative Transmittance Model (CRTM) and forward radiance model called OPTRAN is incorporated into the current release of LAPS. Details of OPTRAN are available from: Tom Kleespies NOAA/NESDIS Thomas.J.Kleespies@noaa.gov
Also OPTRAN can be used by any U.S. Government or U.S. Military entity without problem. ALL other users need to contact NESDIS (Tom Kleespies) and receive authorization to use this software. Generally a simple acknowledgement to give full credit to the program author is all that is required. GSD assumes no obligation or responsibility in integrating this software as part of LAPS. To disable the use of OPTRAN in LAPS, simply assign the GOES option in the moisture_switch.nl namelist file to zero.
The version of OPTRAN in LAPS is configured to work with GOES-8 and -10 sounder or imager at this time. Note also that GOES imager channel 5 (water vapor split window) is currently not available on GOES 11, 12 and future satellites since it was replaced with a different band. Therefore, the GOES imager data should not be used in the moisture algorithm for any GOES satellite 11 and beyond. There are simply not enough moisture channels available to offer any useful information about moisture depth due to this change. Furthermore sounder radiances for GOES-10 are deemed about 98% reliable, they are regarded to be 100% reliable for GOES-8. NaN values have been observed being generated from the GOES-10 sounder coefficients that currently accompany this software. At this time there are only basic provisions to handle the NaN state conditions. They have not been observed to crash the moisture analysis and seem to be handled gracefully to date. Any observation otherwise needs to be communicated to:
Dan Birkenheuer NOAA/GSD Daniel.L.Birkenheuer@noaa.gov
To model the atmosphere with OPTRAN, an atmosphere is formulated that extends to 0.1 hPa. This is a composite of the normal LAPS analyzed vertical domain (nominally extending to 100 hPa), spliced together with a climatological atmosphere of 20 levels that extends to 0.1 hPa. The joining of the two vertical coordinate systems is computed automatically and is continuous. This will automatically take place even if the nominal LAPS levels are extended beyond 100 hPa. In this upper region, temperature, and mixing ratio are functions of latitude and Julian day. Ozone is based on the U.S. Standard Atmosphere.
ADDENDUM: routine RAOB_STEP.F
It should be noted that some users have had to modify the parameter that defines dimensions in routine raob_step.f due to the fact that this can overflow array limits on some machines. The current parameter snd_tot is set to 1000. The primary reason for this is to accommodate satellite soundings of which there can be many in even a small area. This parameter ties in to the dimensions of the weight matrix (ii,jj,snd_tot). If a large horizontal domain is defined, and you don't have a lot of RAOB data and are not using satellite processed soundings, you may have better success at compiling this routine by reducing the value of snd_tot to a smaller value.
GVAP
GVAP data are GOES sounder total precipitable water data acquired from the sounding retrieval process. These data were added to LAPS under a grant from NOAA NESDIS.
The analysis for GVAP data has recently changed from the prior application. Up until the March 2005 release, GVAP data were used as a direct total moisture data source in that the integrated state variable in the moisture routine (q) was compared to GVAP totals and part of the minimization procedure was to improve this match through variational techniques.
It was learned during the IHOP 2002 experiment that the GVAP data were badly biased, especially at asynoptic times. (see http://laps.fsl.noaa.gov/cgi/birk.pubs.cgi for all publications, and specifically http://laps.fsl.noaa.gov/birk/papers/Birkenheuer2005a/j.pdf for the article about IHOP, or it can be located in the literature at: Birkenheuer, D., and S. Gutman, 2005: A comparison of the GOES moisture-derived product and GPS-IPW during IHOP. J. Atmos. Oceanic Tech. 22, 1840-1847.)
As a result, the algorithm was modified to use GVAP gradients and to compute gradients in the solution field and match these gradients to those from GVAP. The advantage to using gradients in this procedure was that it eliminates bias and improves data structure. There is not a Tech Memo that has been published and is also available on line that describes this new technique. (refer to: http://laps.fsl.noaa.gov/birk/papers/tech_memos/GSD_Tech_Memo_32.pdf or a copy can be gotten directly from GSD)
There may be some parameters in the satellite code that change when the domain is moved. The latest info documented in the file './src/ingest/satellite/lvd/README'. Please contact John Smart (John.R.Smart@noaa.gov) for more details.
It is worthwhile to check the 'nest7grid.parms' and other namelist files in 'data/static' to make sure all the runtime parameters are correct. Some parameters worth noting are:
nest7grid.parms
_______________
c8_project_common - Depends on which "realization" of LAPS you are running.
Allowed values are listed within 'nest7grid.parms'.
cloud.nl
________
l_use_vis - Boolean set to indicate whether we are confident in the
calibration of the visible satellite data and albedo
fields for use in the cloud analysis. This is normally
set to .true. at GSD and .false. for WFO and other
ports unless we are confident in the vis data
normalization.
To determine how well LAPS was installed, verify that all (31 at last check) executables were built OK ('bin' directory) with no errors in the output of 'make'.
Similarly, check the output of the localization script.
If you have any problems during the configure, install and localization process, there are several things to check. For certain platforms, you can compare your build output with ours by clicking on "Results of Latest LAPS Builds" on the LAPS Software page. Also double check that you've followed all the installation steps in this section of the README. There is also a FAQ available at http://laps.noaa.gov/birk/LAPS_FACTS.htm Finally, check the release notes at the http://laps.noaa.gov/software/release_notes.html URL.
If you don't find the answer in these documents, send mail to oplapb.gsd@noaa.gov Include in your mail:
LAPS version number (hopefully you're using the latest version?) The type of system (often, uname -a) The system limits (ulimit -a) The applicable compiler versions (often a -v or -V option to the compiler) The entire output of configure The entire output of make (standard output + error output) The entire output of localize_domain.pl (found in $LAPS_DATA_ROOT/log/localize_domain.log*)
To see how well LAPS is running, check if output files are being placed in the various 'lapsprd' subdirectories. A graphical product monitor that can help with this is available in 'etc/laps_monitor.pl'. This script may need some simple editing to suit your needs (e.g. to specify the $LAPS_DATA_ROOT[s]). The monitor script writes HTML output to 'stdout'. This HTML output, if routed to a file or hooked up to a Web server, can be viewed with a browser. You can click on http://laps.noaa.gov/monitors/Laps_Monitor.cgi to see an example of the monitor output. Green means optimum product continuity, red means the product is failing to generate, yellow means it is generating OK now but has failed in the past. The numbers in the columns indicate the number of files in each directory, as well as the youngest and oldest file ages in hours. The data flow is generally from top to bottom on the product list, starting with analyses and ending with forecast model (fua/fsf) output being listed at the very bottom.
To check what model background and observational data were used in the analyses as well as some QC and error (verification) statistics, you can view the log file summaries in the files '$LAPS_DATA_ROOT/log/*.wgi.yydddhhmm'. Generally each named 'wgi' file corresponds to the name of an analysis process, except that 'sfc.wgi.*' is generated by one of several executables than can provide the LAPS surface analysis depending on the runtime configuration.
For more details, check the various log files in the '$LAPS_DATA_ROOT/log' directory for occurrences of the string 'error' and 'warning'. The errors are generally more significant. If any core dumps occur they can usually be flagged by searching for the 'sh:' string in 'sched.log.*'.
If you are reporting runtime errors it can be useful to tar up your entire $LAPS_DATA_ROOT and make it available on your web or FTP server as a compressed "tgz" file. If the data set is very large you might consider mailing us a CD or DVD. Alternatively if you have the untarred $LAPS_DATA_ROOT files on your web server we can browse through the directories for the log and product files as needed to help diagnose the run.
The following section contains information on which LAPS processes generate which LAPS output products. Static data (like lat and lon grids) are included in section 3.1. These are the processes contained within the LAPS tar file and built with the localization script.
"Inter data" is an ascii file containing non-gridded data (intermediate data files). Examples of this are surface obs, profiler obs, etc.
This list contains all outputs generated by LAPS processes.
The products listed under each process are the outputs produced by that process. Inputs are listed here for some analyses. If the cron including 'sched.pl' (see section 2.4) is run according to the flow therein, the necessary inputs will be available.
Package: gridgen_model.exe - Writes static file, run by localization script.
Contact: John Smart - John.R.Smart@noaa.gov
Inputs: Geography databases (topography, land fraction, landuse, soiltype top/bot) greenness fraction, mean annual soil temperature, and albedo. Files are typically in 10, 30, or 180 deg tiles. See section 2.2.5 for details on the geography data. static/nest7grid.parms
Outputs:
static/static.nest7grid NetCDF grid geography data mapped to LAPS
grid
'LAT' latitude in degrees
'LON' longitude in degrees
'AVG' mean elevation MSL
'LDF' land fraction (1.0=land; 0.0=water)
'LND' land-water mask (1=land; 0=water)
'USE' usgs 30s (24 vegetation categories)
landuse data (currently dominant category
for each grid point).
1: Urban and Built-Up Land
2: Dryland Cropland and Pasture
3: Irrigated Cropland and Pasture
4: Mixed Dryland/Irrigated Cropland and Pasture
5: Cropland/Grassland Mosaic
6: Cropland/Woodland Mosaic
7: Grassland
8: Shrubland
9: Mixed Shrubland/Grassland
10: Savanna
11: Deciduous Broadleaf Forest
12: Deciduous Needleleaf Forest
13: Evergreen Broadleaf Forest
14: Evergreen Needleleaf Forest
15: Mixed Forest
16: Water Bodies
17: Herbaceous Wetland
18: Wooded Wetland
19: Barren or Sparsely Vegetated
20: Herbaceous Tundra
21: Wooded Tundra
22: Mixed Tundra
23: Bare Ground Tundra
24: Snow or Ice
'U01-U24' Fractional distribution of landuse category (not active).
'STL' Soil type - top layer (0-30cm)
'SBL' Soil type - bottom layer (30-90cm)
(currently dominant category for each grid pt)
FAO/WMO 16-category soil texture:
1 SAND
2 LOAMY SAND
3 SANDY LOAM
4 SILT LOAM
5 SILT
6 LOAM
7 SANDY CLAY LOAM
8 SILTY CLAY LOAM
9 CLAY LOAM
10 SANDY CLAY
11 SILTY CLAY
12 CLAY
13 ORGANIC MATERIALS
14 WATER
15 BEDROCK
16 OTHER (land-ice)
'T01-T16' Fractional distribution of top layer soil texture class (not active)
'B01-B16' Fractional distribution of bottom layer soil texture class (not active)
'TMP' Mean annual soil temperature
'G01-G12' Monthly (center of month) greenness fraction
'A01-A12' Monthly (center of month) albedo climatology
'ALB' Not used
static/latlon.dat Binary grid latitude
longitude
static/topo.dat Binary grid mean elevation
static/corners.dat ASCII lat/lon of 4 corner points
static/latlon2d.dat ASCII latitude/longitude
Source directory: laps/src/grid
Sample Output: Should be available in the test data case. The grids start with gridpoint (1,1) in southwest corner of the domain and end with gridpoint (ni,nj) in the northeast corner. The bottom (southernmost) row of the domain is written first (I increases with consecutive grid points, then J increases). I increases as you're moving east on the grid, J increases as you're moving north.
Package: gensfclut.exe - Writes surface lookup tables, run by localization script. (contact: John McGinley / Steve Albers)
Source directory: laps/src/sfc/table
Output:
static/drag_coef.dat Binary grid Drag Coefficients
In 'gensfclut.exe', the friction parameter has been configured by automatically producing a scaling factor based on the range of elevations across the domain. This factor can be changed in the 'drag_coef' section of 'build_sfc_static.f', if so desired.
Package: genlvdlut.exe - Writes satellite lookup tables, run by localization script. (contact: John Smart)
Source directory: laps/src/ingest/satellite/lvd/table
Output:
static/lvd/*.lut Satellite Lookup tables
Additional information on the lookup tables can be found in the file 'laps/src/ingest/satellite/README'.
As mentioned above, a flow chart for the ingest processes may be found at ' http://laps.noaa.gov/doc/slide1_v3.gif .
Package: lga.exe - ingest background model data (contact: John Smart - John.R.Smart@noaa.gov).
LGA LAPS analysis grids from RUC or other analysis/forecast grids.
Inputs: Raw model data on the model's native grid. The acceptable models and formats for the background model are listed in 'data/static/background.nl'. We have recently added support for the background models to include GRIB-formatted files. See source directory: $LAPS_SRC_ROOT/src/lib/degrib/README_LIBS file for detailed information.
For some models you might want to do a separate conversion of GRIB to NetCDF prior to running LGA. One software option for this is available from the GSD/ITS group as described in section 3 of this web document at the following URL:
http://www-its.fsl.noaa.gov/dsg/FSL-WhitePaper.html
Tropical cyclone bogusing information is also an input in the form of the 'tcbogus.nl' namelists. These are generated independently of LAPS as "raw" data, yet are placed in the '$LAPS_DATA_ROOT/lapsprd/tcbogus' subdirectory. The filename convention should be 'yydddhhmm_tcbogus.nl'. To see the format check the sample file located in 'data/static/tcbogus.nl'.
Outputs: (Feeds various analyses)
lga grid background model 3-D data analysis/forecast lgb grid background model Sfc data analysis/forecast
Source directory: The source code for this is in 'src/background'.
Library directory: Associated library modules are in 'src/lib/bgdata'.
Parameter namelist file: 'static/background.nl'
Sample Input/Output: May be available in the test data case.
This software currently supports nearly 10 different models. If additional models are required, then software mods may be needed, potentially a new source file added to 'src/lib/bgdata/read*.f'. A key variable that relates to which model you're using is 'bgmodel'.
Note that time interpolation is used if the required LAPS analysis time(s) are between the valid forecast times for two of the set of input files. In this context output files are produced for the LAPS analysis time as well as +/- one LAPS analysis cycle time. Input data for LGA should thus be available over an appropriate time span.
LSO process - obs_driver.x - Ingest surface data (author: Pete Stamus/Steve Albers)
Input:
METAR/SYNOP data
Buoy/ship (maritime) data
LDAD mesonet data
GPS (sfc obs - without precipitable water)
Profiler surface data (via LDAD)
Output:
LSO ascii LAPS surface obs intermediate data file: METAR, Mesonet,
and Buoy/ship obs. The format of this file may be
determined from looking at library access routines such
as 'read_surface_data', the obs_driver code, or by
looking at sample LSO files in the test data case.
Sample Input/Output: May be available in the test data case.
Source directory: $LAPS_SRC_ROOT/src/ingest/sao (contains a README file)
Parameter file (specifies input data paths and formats): 'static/obs_driver.nl'
The LSO file is fairly self explanatory. The easiest way to see what goes where is to look at the routine 'read_surface_data' in the file 'src/lib/read_surface_obs.f', and the corresponding format statements in the file 'src/include/lso_formats.inc'.
The routines are pretty well commented, and should be enough to tell you what you need to know if you want to make a decoder that outputs an LSO-type formatted file directly. This direct route would allow you to bypass the step of producing "raw" NetCDF surface observation data.
Here are a few recommended settings for the observation type variables (reportType and autoStationType) if you are constructing your own LSO file:
raw data reportType autoStationType ________ __________ _______________ metar METAR UNK (unless an automated A01 or A02 station) synop SYNOP UNK (unless an automated A01 or A02 station) buoy MARTIM FIX ship MARTIM MVG
The expected accuracies are based on "offical" NWS numbers where possible. For LDAD observations, they're just a best guess, since no one really knows how good the obs are. These expected accuracies will be used in the quality control routines sometime in the future. The lat/lons are in decimal degrees.
Gross "climatological" QC error checks are applied to several variables including temperature, wind, and pressure.
Process: (sfc_qc.exe) LAPS Surface Ingest Quality Control
LSO QC process - sfc_qc.exe - QC the ingest surface data
(author: John McGinley / Pete Stamus)
Input:
lso ascii
Outputs:
lso_qc ascii QC'd LAPS surface obs file: METAR, Mesonet and
Buoy/ship obs.
lsq NetCDF QC'd LAPS surface obs in NIMBUS NetCDF format
lsq/monster*.dat' are binary files that contains internalinformation
about the data history
Sample Input/Output: May be available in the test data case.
Source directory: 'laps/src/ingest/sfc_qc'
The 'lso_qc' file is fairly self explanatory...the comments in the 'write_surface_obs' routine detail everything. The expected accuracies are based on "offical" NWS numbers where possible. For LDAD observations, they're just a best guess, since no one really knows how good the obs are. These expected accuracies will be used in the quality control routines sometime in the future. The lat/lons are in decimal degrees.
This new QC package compares the observations temporally and fills in predicted values for an observation when it is only intermittently available. This helps compensate for temporal changes in data density. A future enhancement may be to replicate cloud layer observations for a few hours. This would be especially helpful when running an hourly LAPS while SYNOP stations report clouds only every 3 hours.
More information is in the NWP conference paper on Kalman Filtering (McGinley 2001) at http://laps.noaa.gov/cgi/LAPB.pubs_01.cgi
(author: Steve Albers/Pete Stamus)
As part of the 'obs_driver' code, a Blacklisting function has been added. This allows users to tell LAPS to skip stations with known bad variables (one or several), or to skip a station completely. As of this writing, the user will have to edit a "Blacklist.dat" file...in the future we hope to include this function in the LAPS GUI.
An example file, called "Blacklist.example" has been included in the same directory as this README file. It shows the format that *must* be followed for the Blacklist to work properly. An error