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 computer program and related AGRAM computer 
programs. 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

This documentation was last updated on November 12, 1999.  
_____________________________________________________________________                                              

                  Table of Contents
                 
  1.0 Changes from BAP version 1.0 to version 1.1
     1.1  BAP v1.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: 
"http://nsmp.wr.usgs.gov/processing.html" and the NSMP anonymous FTP   
server "ftp://smftp.wr.usgs.gov" in the directory at
"/software/bap/4pc/".

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:"http://nsmp.wr.usgs.gov/smcfmt.html" and via the 
NSMP anonymous FTP server "ftp://smftp.wr.usgs.gov" in the directory at
"/software/bap/docs/".

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

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, 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 input 
                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-extending
              software 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.)

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 included
                             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, ++).

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:
                1) the FIRST zero-crossing of the time series with 
                   the mean value of the time series between
                   TSKEW(1) and TSKEW(2) seconds, and
                2) 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.

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.

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.

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.

_______________________________________________________________________

      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.