What's New with BAP

Software Change History for BAP and Related AGRAM Programs

This documentation describes the changes from version 1.0 to version 1.1 of the National Strong-Motion Program's Basic Strong-Motion Accelerogram Processing (BAP) computer program and related AGRAM computer programs. A text version of this documentation can be obtained here (whatsnew.txt). This documentation was last updated on November 16, 1999. Questions regarding the BAP or the AGRAM computer programs should be directed to:

Kent Fogleman: (650) 329-4745, fogleman@usgs.gov
or
Chris Stephens: (650) 329-4752, cdstephens@usgs.gov

U.S. Geological Survey, MS 977
345 Middlefield Road
Menlo Park, CA 94025

1.0 Changes from BAP version 1.0 to version 1.1

     1.1 BAP version 1.1 files available via NMSP WWW and FTP sites.

     1.2 Upgraded SMC-format and online documentation

     1.3 New programs

     1.4 Removed programs

     1.5 New examples and documentation

     1.6 BAP changes

                Input/output files

                 Modified processing steps

                 Better top-of-plot titles

                 New run parameters

     1.7 Warnings

     1.8 Bug fixes

     1.9 New programming conventions

2.0 About the Response Spectra calculating subroutine

1.0 Changes From BAP Version 1.0 to Version 1.1

1.1 BAP Version 1.1 Files Available via NSMP WWW and FTP Sites.

The same files that are provided on the PC/BAP distribution diskettes are also available via the NSMP WWW site at the URL: "/processing.html" and the NSMP anonymous FTP server "https://ca.water.usgs.gov/nsmp" in the directory at "/software/bap/4pc/".

Back to Top of Page

1.2 Upgraded SMC-format:

The SMC-format used for data has evolved somewhat. The main changes are:

First line indicates the type of data in the file.
Time series can be unevenly sampled.
File can contain response spectra values rather than time-series values.
The comments section of the file can contain plot label information. The plot labels are used in BAP output plots, but they are not yet used by the TSPLOT program (because TSPLOT cannot read SMC files yet).

BAP can still read the version 1 SMC-format files.

The latest version of the SMC documentation is available via the NSMP WWW site at the URL:"/smcfmt.html" and via the NSMP anonymous FTP server "https://ca.water.usgs.gov/nsmp" in the directory at "/software/bap/docs/".

Back to Top of Page

1.3 New Programs

V2S will translate a "volume 1" or "volume 2" time series data file from CalTech, CSMIP, USC, USGS, Kinemetrics, etc. into one or more SMC-format time series files. For more information, just type V2S at the DOS command line.
SMCHDR allows the user to insert header information into SMC-format data files in situations where it would be cumbersome to make the changes with a text editor. For brief information, just type SMCHDR at the DOS command line. For a complete user's guide, refer to the first set of comment lines in the file at \agram\exes\smchdr.prl.
PERL16 and PERL32 are now redistributed along with the BAP/AGRAM software. They are used to implement the SMCHDR program, but they might be useful for user-written script files too. For more info about these versions of PERL and about PERL in general, refer to the file at \agram\docs\perlinfo.txt.
BOOT.BAT was renamed to REBOOT.BAT and it flushes the smartdrv cache if c:\windows\smartdrv.exe is on the PC. (Users on PCs using different caching technique may want to change or comment out that line in REBOOT.BAT.)

Back to Top of Page

1.4 Removed Programs

LOWBAP (This took more space on the distribution diskettes than it was worth.)
SFAS, PFAS (the FASPLT program doesn't offer much more than the Fourier amplitude plots from BAP do, and these two .EXE files took more space on the distribution diskettes than they were worth. The Fortran code for the FASPLT program is still distributed, however, in the \agram\gats\ood\ directory (gats= gathered source files; ood= out-of-date). The more important things FASPLT offered over BAP's FAS step were the ability to:
    = generate plots of spectral ratios from two inpu time series,
    = learn user-specified axes ranges and whether each axis should be log or linear,
    = generate plots of the Fourier phase spectra as well as amplitude spectra. Integrated or differentiated
        amplitude spectra too.)
WHATMEM (this program was provided with the Ergo DOS-extendingsoftware used with BAP version 1.0. BAP version 1.1 uses a different DOS-extender (PharLap) so the Ergo WHATMEM command is no longer provided with BAP.
HELP (this was a do-nothing command among the BAP .exes/.bats in the version 1.0 distribution files. All it ever did was get in the way of the DOS help command.)

Back to Top of Page

1.5 New Examples and Documentation

\agram\examples\rdbbf.for = example of how to read a BBF file.
The following documentation files (all in \agram\docs) are new:
WHATS.NEW (=this file),
PERLINFO.TXT (info about the Perl interpreters include among the BAP distribution files).
The following documentation files (all in \agram\docs) have been updated:
    SMCFMT.DOC   (completely rewritten),
    BBFFMT.DOC (minor changes),
    BAPINFO.TXT (how to get the software via FTP, ++),
    ALTBOOTS.NTS (BOOT.BAT was renamed to REBOOT.BAT, ++),
    PROGBAP.NTS (new call tree diagram, ++).

Back to Top of Page

1.6 BAP Changes

Input/output files:

=	BAP can read the expanded-format SMC time-series files as well as the older SMC-format files. BAP output time-series files are now in the newer format. The output response spectra files are by default consistent with the new SMC format too. The older, BAP-version-1.0, response spectra format can be requested via the new RSFMT run parameter. Fourier amplitude output file format has not changed.

=	SMC-format output time-series files will by default include the leading and trailing pads. In BAP version 1.0, only the BBF output files contained the pads. User can request that no pads be output with the time series via the new PADSOUT run parameter.

=	The extension on the response spectra output file name has changed from '.TXT', as it was in BAP version 1.0, to '.RS1' or '.RS2', depending on which response spectra output format was requested. Note that we are using '.RS2' rather than '.SMC' even though the new response spectra format is included in the new SMC file-format specification. BAP reserves the '.SMC' file extension for time series files so users can distiguish between time-series files and response spectra files just by noting the file name.

=	The extension on the Fourier amplitude output file name has changed also, to be consistent with the response spectra naming convention. The extension has changed from '.TXT' to '.FS1'. The format of the file has not changed.

=	BAP version 1.0 truncated comments it transfered from an input to an output SMC file at 40 lines. BAP version 1.1 will transfer any number of SMC comments from the input to the SMC-format output files.

=	BAP will now transfer SMC text header values and SMC comments to an output BBF-format file and vice-versa. The comments will be truncated to whatever will fit into BAP's in-memory character working area. (There's room for about 1000 characters there, more or less, depending on other character info stored there, like input/output file names.)

Modified processing steps:

=	RESPONse spectra:
	The default period list for use in response spectra calculations now begins at .04 rather than at the .05 used in BAP version 1.0. The addition makes the new list the same as that used in the older PHASE3 program. The line drawn on the plot when CLIPRS=OFF moved from 10/sps, as it was in BAP version 1.0, to 8/sps.

=	DECIMate:
	BAP version 1.0 reduced the sampling rate in this step by removing the 2 samples between every 3rd sample (or removing the NDENSE-1 samples between every NDENSE-th sample). We found that we needed to reduce the sampling rate of the time-series output from the new USGS digitizer from 500 to 200, however, and to do so we need to interpolate rather than discard points. So a new run parameter was added: SPSLAST. When SPSLAST is given and it is not evenly divisable into the undecimated sampling rate, the new DECIMation step will interpolate rather than discard samples.

=	INTERPolate:
	The interpolation step was modified so its resulting time series will always contain a sample at time=0.0. BAP version 1.0 always began interpolating with the first sample given in the input time series. The first sample in an input time series would normally be at time= 0.0 except in the unusual situation where one wished to pass a padded BAP output time series to a second BAP run in which the time series was reinterpolated (not recommended!). When the input file was padded, the version 1.0 interpolating algorithm could end up with a time series with samples that bracket 0.0 rather than with a sample right at 0.0. This became a problem when we used the same interpolating subroutine in the new DECIMate step as we use in the INTERPolate step.

=	LINear CORrection:
	A new "skew" option was added to the LINCOR step via the new TSKEW, YO, and SLOPE parameters. This option may be used in an attempt to eliminate the transients that result if the time series is so distorted that the values near the beginning and/or end are significantly different than zero, even after the mean has been removed. An example would be a time series with a bow-shaped distortion. Padding such a time series with zeros produces step changes at the beginning and/or end; filtering will produce transients associated with these steps.

Better top-of-plot titles.

	Version 1.1 BAP will get top-of-plot labeling lines from the new PLTLBL run parameter (see below) and/or from the input SMC-format time-series file.

	Top-of-plot labels are given in the comments section of SMC-format data files. They are indicated by a leading "<pltlbl=>" or "<loclbl=>" and a trailing "<end>". (Note that the <pltlbl=>, <loclbl=> and <end> must all be in lower case.) Both types of top-of-plot label can be more than one line long. Some sample comment lines that include top-of-plot labels:

	\| This time series was digitized at the USGS on 12dec97
	\| by Sam Spade.
	\| <pltlbl=> blah blah blah
	\| any number of lines here
	\| ending with: <end>
	\| <loclbl=> roof, north-west corner <end>
	\| More general comments here.

	The <pltlbl=> top-of-plot label is usually just one line that indicates the address or name of the recording station, if sufficient station identification would not fit on line 6 (colums 11-40). The <loclbl=> label gives information about the location of the recording transducer. It is usually quite short, and in the case of tri-axial recordings it is usually absent because all three transducers are in the same location. The <loclbl=> information is provided separately from <pltlbl=> info so the info unique to each transducer is separate from the info several transducers share. (Makes construction the plot labels more convenient for the TSPLOT program.)

New run parameters = PADSOUT, FASFMT, RSFMT, SPSLAST, PLTLBL, PLTTOP, PLTTYPE, PLTDPI, Y0, SLOPE, TSKEW

=	input/output parameters = PADSOUT, RSFMT, FASFMT
		PADSOUT =	ON or OFF to indicated whether or not the output time-series files should include the leading and trailing pads. By default, PADSOUT=ON. (In BAP version 1, the user had no control over whether or not the pads were written to the output files, other than in deciding which type of output file to request. Pads were written to output BBF files, but were not written to output SMC files.)

		RSFMT =	'RS1' or 'RS2' to indicate which of the two available formats the response spectra output file should be in. The RS1 format is that which was used for output response spectra files in BAP version1; the RS2 format is that specified for SMC-stlyle response spectra files in the \agram\docs\smcfmt.doc file. By default, RSFMT=RS2.

		FASFMT =	'FS1'. There is only one format available for the Fourier amplitude output files so far, so this parameter doesn't make much sense. It was introduced for consistency with the RSFMT parameter and to allow us to add alternative formats in the future.

=	plot parameters = PLTLBL, PLTTOP, PLTTYPE, PLTDPI
		PLTLBL =	top-of-plot label lines. Example: pltlbl = "blah blah blah"; "another line"; "third line"

		PLTTOP =	location for the top of the plot frame, given as a fraction of the page height. BAP version 1.1 will by default place the top of the plot frame just below all the top-of-plot label lines. But if one wanted to compare plots generated in different BAP runs having different numbers of top-of-plot lines, one should specify the same PLTTOP value for each run. And if one wanted to compare a BAP version 1.1 plot to a corresponding plot from BAP version 1.0, PLTTOP=0.85 should be used.

		PLTTYPE =	type of plot indicator. * this isn't used yet, but allowable values will be something like: aps, meta, 8ps, ... to indicate which plotting medium should be used. *

		PLTDPI =	resolution to be used in postscript plots, given as dots per inch. * isn't used yet. *

=	DECIMation parameters = SPSLAST
		SPSLAST =	the target sampling rate for the decimation step when we really want to interpolate rather than remove NDENSE -1 samples between every NDENSE-th sample.

=	LINear CORrection parameters = TSKEW, Y0, SLOPE

		TSKEW =	one to four numbers that indicate how BAP should determine a trend line to be removed from the time series. "TSKEW=0.0" is the most commonly-used version of this option; in this case, the line determined by the first and last points of the time series is subtracted from the time series. By default, TSKEW=* (meaning do not use the TSKEW option.)

			The first two TSKEW values indicate a time interval at the beginning of the time series, the second two values indicate a time interval at the end of the time series. If the user provides these in the run parameters list, BAP will determine the trend line as the line passing through the following two points: the FIRST zero-crossing of the time series with the mean value of the time series between TSKEW(1) and TSKEW(2) seconds, and the LAST zero-crossing of the time series with the mean value of the time series between TSKEW(3) and TSKEW(4) seconds.

			Or, if MLLSQF=ON, the two points will be deterimined from the first or last zero-crossings of the time series with the linear least squares fit (rather than the mean) of the time series in the two intervals specified in TSKEW.

			If just one number is indicated for TSKEW, it represents the time interval to be used at both ends of the time series. If that one number is 0.0, then the trend line will be determined from the two end-points of the time series. If two numbers are indicated, they represent the time interval to be used at the beginning of the time series and the end of the time series, respectively. If four numbers are given, the first two indicate the times that bracket the first interval and the second two indicate the times that bracket the second interval.

			Warning: one should probably use the ZCROSS padding option when using the skew option. Fortunately, ZCROSS is the default.

		Y0 =	y-intercept of a line to be subtracted from the time series. The slope of the line is indicated in the parameter named SLOPE. (The YO parameter was named VLINE in version 1.0 BAP. Either name may be used.)

		SLOPE =	slope of a line to be subtracted from the time series. The y-intercept of the line is indicated in the parameter named Y0.

			Only one linear correction option will be performed even if more than one is requested. TSKEW takes precedence over MLLSF=ON, which takes precedence over MMEAN=ON, which takes precedence over Y0 & SLOPE (and over VLINE, which is a synonym for Y0).

			By default, TSKEW=* (=undefined), MLLSQF=OFF, MMEAN=OFF, Y0=0.0, and SLOPE=0.0; this is equivalent to NOlincor.

Back to Top of Page

1.7 Warnings

The 32-bit programs (BAP, HDRSET, & Perl32) run in extended memory with the help of "DOS-extending" software. Attempts to run these programs can hang one's computer (it will just sit there doing nothing, even in response to control-C) when the computer is configured to use the same extended memory for another purpose (like a RAM disk). Refer to the file at \agram\docs\atboots.doc for information about setting up alternative configurations.

Back to Top of Page

1.8 Bug Fixes and Trivia

Time series samples in SMC-format files have only one digit in the exponent. After BAP processing, some of the time-series samples will have exponents less than -9, especially out in the pad area. BAP version 1.1 resets these samples to 0.0, but BAP version 1.0 outputs the number as a string of asterisks!
BAP will use the sampling rate of the input file (if the input file is evenly-sampled) for the output file. It will no longer use 200 sps as the default output sampling rate. This is consistent with what the user's manual says on page 4-8, but inconsistent with the "spsnew=200" on pages 4-4 and A-2. Those "spsnew=200" should now read "spsnew=*", where the * indicates that BAP will choose the output sampling rate as 200 if the input time series is unevenly sampled and keep the sampling rate unchanged if the input time series is evenly sampled.
BAP will no longer attempt to LINCOR beyond the end of the time series, even if user asks it to.
BAP can now calculate a response spectrum for just one damping value.
BAP: a command line interpreter bug was fixed. Used to be that user couldn't give the the short-form of an on/off run parameter (i.e., just give the parameter name without the trailing "=on") immediately before the short-form of the input file specification (i.e., just give the file name without the leading "infile="). Can now. For instance,
"BAP SHOW \DATA\MYFILE.BBF"
used to result in a "cannot interpret" error; doesn't now.
BAP now has diagnostics that warn PC users that the PC version will only allow 1.7e38 as the value representing "undefined" in the input time-series files. BBFFMT.DOC has been updated accordingly too. BAP will now change the value representing real "undefined" to 1.7e38 if it is given as anything else in an input SMC-format file. BAP will stop with a diagnostic (it used to stop without giving so much information) if it finds real "undefined" to be anything other than 1.7e38 in a BBF-format input file, except in the case where the PC version of BAP is reading a BBF file generated on a VAX that contains -0.3e-38 as real "undefined", and in which case PC/BAP changes the -0.3e-38 to 1.7e38.
The reasons PC/BAP and other PC/AGRAM programs restrict real "undefined" to 1.7e38 is that this this cell (the 2nd 32-bit word in the 2nd 512-byte block of the file) in an input BBF file is used to:
1) determine whether the file were originally written on a VAX or on a PC, and
2) determine (with other info) whether the file is a BBF or SMC-format file.
PCs and VAXes use different representations for real numbers, so PC/AGRAM programs inspect the value for real "undefined" to see whether the bit string looks like the VAX representation of 1.7e38, and if so the PC/AGRAM programs then change all the real numbers comming in from the file from the VAX real-number representation (DEC) to the PC representation (IEEE).
APS plots: April Converse made some changes to ZPLOTS.FOR, one of the subroutines that generates the .APS files, but didn't remember why.

Back to Top of Page

1.9 New Programming Conventions

The following changes affect the information given in the "Programming" appendix in the BAP version 1.0 users manual.

\agram\4L32\ became \agram\4L32v5\ when we upgraded to version 5 of the Lahey 32-bit compiler.
The contents of \agram\pccode\ and \agram\vaxcode\ directories were combined into a new directory: \agram\gats. ("GATS", short for gathered files, files that are output from the GATHER program.) The newer files therein, those that have changed since version 1.0, are no longer .VAX and .ADD files, but:
            GEN<whatever>.GAT
            VAX<whatever>.GAT
            L32<whatever>.GAT
            MPS<whatever>.GAT
            MSF<whatever>.GAT, and soon, maybe:
            SOL<whatever>.GAT.
The GEN<whatever>.GAT files each contain a gathered (concatinated) collection of all the portable, generic fortran files used to construct the <whatever> program. The other .GAT files contain additional files that are required to construct the program with the compiler indicated in the first three characters of the GAT file name.
            VAX => the VAX/VMS compiler,
            L32 => PC/Lahey 32-bit compiler,
            MPS => PC/Microsoft 32-bit compiler,
            MSF => PC/Microsoft 16-bit compiler,
            SOL => Solaris/SUN compiler.
The first set of comment lines in each of the .GAT files gives instructions for generating the relevant program.
Some of the out-of-date gathered files were moved from \agram\gats\ to \agram\gats\ood\: FASPLT.VAX, MSFFAS.ADD, MSFBAP.GAT.

Back to Top of Page

2.0 About the Response Spectra Calculating Subroutine

April Converse was under the impression, when she wrote the BAP user's manual and when she added the comments to subroutine CMPMAX.FOR, that the author of CMPMAX, I.M. Idriss, had written it according to the technique presented by Nigam and Jennings in a 1969 paper published in BSSA. Not true! Dr. Idriss developed his essentially identical technique independently of Nigam and Jennings, and at about the same time.

Back to Top of Page
Back to NSMP Home Page

Software Change History for BAP and Related AGRAM Programs

Table of Contents

1.0 Changes From BAP Version 1.0 to Version 1.1