LAPS README

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).

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/
     

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 'etc/window_domain_rt.pl' ("window" hereafter). The window script makes use of namelist domain templates that specifically define a users 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 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, $LAPSINSTALLROOT contains bin/ and etc/ and $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 existing LAPS_DATA_ROOT" 

a) 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) window_domain_rt.pl -c -w laps:
  
   result: same as a) although lapsprd and log are removed and regenerated by
           "etc/makedatadirs.pm"
  
c) 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) 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) 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.

laps/src/lib/liblaps.a libnetcdf.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.

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.

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.

Additional information on the lookup tables can be found in the file 'laps/src/ingest/satellite/README'.

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.

Source directory: $LAPS_SRC_ROOT/src/ingest/sao (contains a README file)

Parameter file (specifies input data paths and formats): '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.

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.

An incorrect variable code generates a warning message, and the code should continue without acting on the station in question.

Note that when a station is blacklisted, its name, latitude, longitude, elevation, and time, will still be stored in the LSO file. However, the selected variables (up to "ALL" of them) will be set to the 'badflag' value and skipped in the analyses.

To actually get this stuff working, edit the file called "Blacklist.dat" in the 'data/static' directory. The "Blacklist.dat" being used at FSL is supplied in this directory as a default. Format the file *exactly* as the 'Blacklist.example' file (using your station information, of course). Save the file, and the next time 'obs_driver' runs, it will use the blacklist information. This will be noted in the 'obs_driver.log' file.

The WSI data are decoded externally to LAPS and written as netCDF files in NIMBUS format. The vrc_driver.x process reads these netCDF files. WSI sends out many types of radar data. We use the files that are labeled "_hd" (15 min freq). They also send out an "_hf" (5 min freq) file. We use hd because WSI hand edits these for ground clutter. The hf files are not edited. The hd and hf files are composites of "low-level" elevation scans from the 88D's around the country. The vrc_driver.x also maps from conus to laps domain for the wfo data set. The map transformation software is found in lib/gridconv, lib/nav, and lib/radar/wsi_ingest. The switch to use wsi versus wfo in variable c_raddat_type in nest7grid.parms. Pathway to data is variable path_to_wsi_2d_radar_cmn in nest7grid.parms.

The output reflectivity is used by the cloud and precip accumulation analyses.

This program runs once per LAPS cycle in the 'sched.pl'. The default is to write just one mosaic file for the cycle valid at 'systime'. A namelist option allows this program to produce multiple mosaic outputs within a given LAPS cycle. The multiple mosaics are all run at the same wall clock time, while the valid mosaic times are spaced throughout the previous LAPS cycle.

The nearest radar with valid data is the one chosen to contribute at each grid-point.

The output reflectivity mosaic is used by the cloud and precip accumulation analyses. Further QC is done within these analyses.

Parameter namelist file: 'static/radar_mosaic.nl'

Source directory: laps/src/ingest/profiler

Parameter namelist files: static/nest7grid.parms, static/vad.nl

Sample Input/Output: Should be available in the test data case.

For the 'pro' output, each profile starts with an ASCII header and the formatted entries are defined in sequence...

1)  WMO ID or other ID number. The use of this is optional and zero can
    be used if you don't know the number.

2)  Total number of levels for which data is provided. This can include
    the surface data as the first level.  

3)  Latitude (degrees)

4)  Longitude (degrees)

5)  Station Elevation (meters MSL)

6)  Station Name

7)  Time of observation (UTC). This is the middle of the observation period
    if time averaging is used. 

8)  Data type. Can be either "PROFILER" or "VAD"

After the header, the data entered for each level is as follows...

1)  Elevation (meters MSL)

2)  Wind Direction (degrees)

3)  Wind Speed (meters/second)

4)  Estimated Root Mean Square (RMS) error of measurement

Source directory: laps/src/ingest/rass

Sample Input/Output: Should be available in the test data case.

Source directory: The source code for this is in 'src/ingest/acars'.

Parameter namelist file (for data paths): 'static/nest7grid.parms'

Sample Input/Output: Should be available in the test data case

Source directory: laps/src/ingest/raob (contains a README file)

Parameter namelist file (for data paths): 'static/snd.nl'

Sample Input/Output: May be available in the test data case. If not, the README in the source directory contains a description of the 'snd' file.

Note: Sounding data is used if the observations lie in the time window centered on the analysis time. There are flags to toggle usage of the sounding (i.e. snd) data in 'wind.nl', 'temp.nl' and 'moisture_switch.nl'.

CTP grid Cloud-top pressure information

Parameter namelist file: 'static/satellite_lvd.nl'

Source directory: laps/src/ingest/satellite/lvd (contains a README file)

Parameter namelist file: 'static/cloud_drift.nl'

Source directory: laps/src/ingest/satellite/cloud_drift

The wind analysis is done in three steps. The first step analyzes the non-radar data with the background wind field using a multiple iteration successive correction technique.

For the second step, the first step results are used as the background. The data used includes non-radar data; any grid-points with multiple- Doppler radial velocities are also mixed in. Radial velocities are taken from the Doppler radars after dealiasing and other quality control steps are done. If two or more radars illuminate a given grid-point, a full wind-vector is constructed from a combination of the radial velocities and the preliminary non-radar analysis. This is done via a "successive insertion" process, beginning with the background (non-radar analysis), then followed with the radial velocity from each radar in sequence.

For the final step the background field comes from the result of the second step. All point data is now used, including grid-points illuminated by only a single radar. The tangential component for each radar observation is estimated by using the background from the previous step (i.e. non-radar data and/or multi-radar data).

The omega field is calculated by kinematically integrating the horizontal wind divergence. The lower boundary condition is specified by the surface wind and terrain gradient.

Auxiliary functions:
	write out graphical products
		
Inputs: '*' = essential input
      * lga/fua grid            model data analysis/forecast
                                needed for current and previous cycle times
	pro     inter data      profiler, VAD, SODAR winds
        snd     inter data      RAOB/Dropsonde data including winds
	pin	inter data      ACARS Winds (using pressure altitude)
        cdw     inter data      cloud drift wind
      * lso     inter data      LAPS surface obs file (e.g. mesonet & METAR)

        (remapped from raw radar data)
	v01-vxx grid            3-D radar reflectivity/radial velocity 

Outputs: (LW3 is main output)
	pig	inter data	acars, cloud drift winds (prior to QC, 
                                                             true north)
	prg	inter data	profiler, sounding winds (prior to QC, 
                                                             true north)
	sag	inter data	surface winds  (prior to QC, true north)
	d01-dxx inter data 	derived radar vector obs    (grid north)

	lw3	3d grids        3-D winds (U and V are wrt GRID NORTH), omega
	lwm	2d grid		surface winds

Parameter namelist files: 'static/wind.nl', 'static/nest7grid.parms'

Further description and reference is at:

If you wish to skip over these steps, you can change the 'surface_analysis.nl' namelist file. This is recommended when using the separate flag to use the experimental Kalman quality control observation file (lso_qc), generated by 'sfc_qc.exe'.

There is an additional check for all analyzed fields (except visibility) within the 'spline' routine that rejects stations deviating from the background by more than a threshold number of standard deviations of the observation increments. This threshold can be independently adjusted (i.e. tightened or loosened) for each field via the 'surface_analysis.nl' namelist. If you see any bulls-eyes in the surface analysis that you don't believe, try contacting Steve Albers at FSL for more information on making these quality control namelist adjustments.

The experimental Kalman QC package 'sfc_qc.exe' (outlined in 3.2.2.2) 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. The log file for this new program is in 'sfc_qc.log'.

Further description and reference is at:

Parameter namelist files: static/cloud.nl, static/nest7grid.parms

Further description and reference is at:

RAOB ENHANCEMENT:

The RAOB data are added to the analysis via a second pass Barnes analysis. Normally, a Barnes analysis consists of two parts. The first fills the entire domain with values weighted by the distance to the neighboring points. In the second pass, a difference field (derived from the difference of the first pass and the observations) is added to the result from the first pass with adjusted weights to better tune to the scale of interest.

In this application we skip the first pass using instead the "background" analysis in place of the result of the first pass Barnes' result. The difference field is then generated and applied using a set of weights appropriate for the LAPS domain resolution and density of observations.

SATELLITE ALGORITHM: An essential ingredient of the variational method is a satellite forward radiance model. The forward model produces a simulated radiance based on temperature, moisture, and ozone profiles along with the temperature of the surface or cloud top, and the pressure of that radiating surface (i.e., surface pressure or cloud top pressure whichever applies). Also needed are the zenith angle, used to determine the air mass path and optical depth between the radiator and the satellite. The forward model used for this work was obtained from NESDIS. The forward model coefficients used for this study were vintage late 1995.

In order to apply the forward model appropriately, a determination of clear and cloudy fields-of-view (FOV) need to be determined. The LAPS cloud analysis is used to identify clear and cloudy LAPS grid points. The analysis as presented here is only working from FOVs classified as clear. Cloudy FOVs probably can be used, but this is an early attempt at this technique, so a conservative approach was chosen. Later research may focus on using a combination of both clear and cloudy FOVs in the algorithm.

The first step in the algorithm is to assure all the data needed for proper execution are present. These include channel radiances derived from AWIPS imagery, the LAPS cloud analysis output, the LAPS surface temperature output, and LAPS 3-D temperatures. The forward model also requires an ozone profile along with moisture and temperature profiles above 100 hPa. These are gotten from climatology since LAPS extends only to 100 hPa. The entire ozone profile is provided by the forward model since LAPS does not analyze this parameter.

Next, the forward model is run to verify "clear" LAPS gridpoints, where clear is defined as those points in which both the modeled and measured GOES image radiances in channel 4 (11 micron) agree to with 2K. This step uses the LAPS thermal and as yet unmodified moisture profiles. Disparity in the channel 4 brightness temperature comparison indicates that the LAPS thermal profile is too far off or perhaps it is really cloudy where the LAPS cloud analysis is indicating it is clear. (It doesn't have to be totally cloudy for a disparity to exist, it can be partially cloudy and this will still be detectable in this difference test.) This is a conservative test; it really goes beyond simple cloud detection though that is a likely cause of differences, the forward model check is very sensitive and in many ways eliminates any thermal profiles that subsequent variational technique will find difficult to deal with. We are basically saying that we will not worry about moisture adjustment unless the thermal profiles are reasonable.

At this point, all gridpoints offering promise of moisture adjustment have been identified. If the domain is totally cloudy, the GOES adjustment is discontinued and returns unmodified moisture values which are passed to the final QC step. Assuming some gridpoints have been classified as clear, the next step is a variational adjustment at those locations. The functional evaluated at each gridpoint has the form (using TEX- type ASCII, ^=superscript and _=subscript),

           5                             3
     J = sum [R^o_i -R(t,o,cw)_i]^2  + sum  (1-c_k)^2        (1)
         i=3                           k=1

The first term in the functional maximizes agreement between the forward model and observed radiance at the expense of only modifying the water vapor profile. The second term adds stability and gives more weight to solutions in which the coefficients departure from unity (no change to the initial profile) is minimized. The stability term was discovered to be necessary since without it some very good radiance matches were solved but with unreasonable coefficients.

Note that differences in all three channels are minimized in this technique, not only the moisture channel. Thus, any improvement in the "dirty window," channel 5, will also contribute to the solution. A variational technique is used to minimize this function and typically requires three to 10 iterations to converge. A limit of 50 iterations was set as the maximum number to attempt. If limit was reached, that particular gridpoint was excluded and treated as cloudy.

Once the coefficients are determined, Laplaces equation is solved for interior points for which coefficients have not been determined. Then the entire domain is averaged using a spatial invariant filter; simply averaging the values in a 3x3 gridpoint window, assigning that average to the window's central grid location.

When the coefficients have been determined, they are applied to the specific humidity field at each pressure level for which they are designated. The modified specific humidity field is then advanced to the final analysis step. In this August 1996 release, the coefficient adjustment is limited to above 500 hPa only.

Reference: Birkenheuer, D. (1999): The effect of using digital satellite imagery in the LAPS moisture analysis. Published in Wea. Forecasting (14), pp 782-788.

Further description and references are at:

Parameter namelist file: static/nest7grid.parms

Reference: Albers S., J. Mcginley, D. Birkenheuer, and J. Smart 1996: The Local Analysis and Prediction System (LAPS): Analyses of clouds, precipitation, and temperature. Weather and Forecasting, 11, 273-287.

This program is in the early stages of development and provides a three layer analysis of soil conditions. A snow cover analysis is included. The fractional snow cover is a composite over time of information from the cloud analysis (visible and IR satellite), and snow accumulation (derived mainly from radar). More documentation can be found within the source code.

Source directory: laps/src/soil

Parameter namelist file: 'static/balance.nl'

The balance package starts by inputting the results from a simple, offline cloud model which retrieves liquid and ice partitioning and an estimate of vertical motion from the observed clouds (lwc/lco). The variational scheme is designed to accept cloud vertical motion estimates and ice and water content as observations. The cloud observations are fully coupled to the three dimensional mass and momentum field using dynamical constraints which minimize the local tendency in the velocities and ensure continuity is satisfied everywhere.

The scheme performs the analysis on the difference from an input model background with the benefit that existing background model balances need not be recreated each model cycle and that background model error daily compiled is input explicitly on a gridpoint by gridpoint basis.

Reference: McGinley, J.A. and J.R. Smart, 2001: On providing a cloud-balanced initial condition for diabatic initialization. Preprints, 18th Conf. on Weather Analysis and Forecasting, Ft. Lauderdale, FL, Amer. Meteor. Soc.

Parameter namelist file: 'static/lapsprep.nl'

Source directory: 'laps/src/lapsprep'

Please contact the author for additional information