Digital PDFs

AA-C984C-TC

October 1981

272 pages

Original

34MB

view download

OCR Version

29MB

view download

Document:	Laboratory Subroutines Programmer's Reference Manual
Order Number:	AA-C984C-TC
Revision:	0
Pages:	272
Original Filename:

OCR Text

soffare

Laboratory Subroutines
Programmer’s
Reference Manual
AA-C984C-TC

October 1981
This document describes the Laboratory Subroutines Package

available to users of FORTRAN/RT-11 and RSX-11M
FORTRAN IV and FORTRAN 77.
This manual replaces the Laboratory Subroutines

Programmer’'s Reference Manual, order number
AA-C984B-TC.

OPERATING SYSTEM:

RT-11 Version 4.0
RSX-11M Version 3.2

SOFTWARE:

FORTRAN IV Version 2.5
FORTRAN 77 Version 4.0

LSP Version 1.2

Software and manuals should be ordered by title and order number. In the United States. send orders to
the nearest distribution center. Outside the United States. orders should be directed to the nearest

DIGITAL Field Sales Office or representative.
Northeast/Mid—Atiantic Region

Central Region

Western Region

Technical Documentation Center

Cotton Road
Nashua, New Hampshire 03060
Telephone: (800)258-1710
NH residents: (603)884-6660

1050 East Remington Road
Schaumburg, lllinois 60195
Telephone: (312)640-5612

2525 Augustine Drive
Santa Clara. Califorma 95051
Telephone: (408)984-0200

digital equipment corporatione marlboro. massachusetts

First Printing, February 1978
Revised, June 1980
Revised, October 1981

The information in this document is subject to change without notice and

should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility for
any errors that may appear in this document.

The software described in this document is furnished under a license and
may only be used or copied in accordance with the terms of such license.

No responsibility is assumed for the use or reliability of software on equipment that is not supplied by DIGITAL or its affiliated companies.

The postage-prepaid READER’S COMMENTS form on the last page of this

document requests the user’s critical evaluation to assist us in preparing
future documentation.

The following are trademarks of Digital Equipment Corporation:
DEC

DECnet

IAS

DECUS

DECsystem-10

MASSBUS

DECSYSTEM-20

PDT

DECwriter

PDP

RSTS

UNIBUS

DIBOL

RSX

VAX

EduSystem

VMS

alilg]i]t[al1]

MINC-11

MINC-23
MINC/DECLAB23

Contents

Page

Preface

Chapter 1

Introduction to the Laboratory Subroutines
1.1
1.2

Chapter 2

The Laboratory Subroutines Package. . . . . . . . . .
The Laboratory Subroutines Package Distribution Kit .

1-1

1-3

. 2-2

The Peak-Processing (PEAK) Subroutine
2.1

2.2

Definition of Basic Terms and Conventions. . . . . . .
The Peak-Processing Algorithm: Processing Raw Data .

Use of the Digital Filter .

... ..

2.2.3

Trend Detection — Application of the Gate Factor

2.2.7

Calculation of Area under the Peak . . . . .
Algorithm Definition of the Width of a Peak .
Algorithmic Detection of the Baseline . . . .

Flow Charts for the PEAK Subroutine .

2—1

2-2
2-3

. 2-3

. 2-6

2-7

24
24

2—-17

2-20

2.5.3

. . . .
EAE (Extended Arithmetic Element).
.

AUTOGS (Autogaining)

2.54

DPP$ (Double Precision Integers)

25.5

NOFLT$ (NoFilter) .

How to Call the Peak-Processing Subroutine .

Using the Peak-Processing Subroutine .

Modifying the Subroutine — Using Options
2.5.1

25.2

2.6

AveragingofInputData.

2.2.6

2.5

222

2.2.5

2.4

221

2.2.4

2.3

EIS (Extended Instruction Set).

.
.

Examples Using the PEAK Subroutine.

.
.

. 2-22
2-22

2-22

2-24

2-22

111

Chapter 3

The Envelope-Processing (NVELOP) Subroutine
3.1

3.2

Definition of Basic Terms and Conventions
The Envelope-Processing Algorithm

Page

3-2

oooooooooooooo

3-2

oooooooooooooo

3.2.1

ooo

The Baseline Value

3.2.2

. . . . . . . . .. ... ...
Trend Detection — Application of the Gate Factor

3.2.3

The WidthofaPeak.

3.2.4

Calculating the AreaofaPeak.

3.2.5

3.2.6

..... 3-3
3-3

oooooo

. . . . .
Calculating the Centroid ofa Peak. . . .
Flow Charts for the NVELOP Subroutine

3.3

How to Call the Envelope-Processing Subroutine

3.4

Using the Envelope-Processing Subroutine

3.5

Modifying the Subroutine — Using Options

3.5.1

...

. 3-3

... 3—4
. .. 3—4
3—4

oooooooooo

3-16

ccccccccccc

3-20

oooooooooooooo

3-22

ooooooooooooo

3-22

oooooooooooooo

3.5.2

3-22

oooooooooooo

3.6

Examples Using the NVELOP Subroutine

4.1

Definition of Basic Terms and Conventions
Your Input to the Subroutine: Its Characteristics

3-22

oooooooooooooo

Chapter 4

4.2

oooooooooooooo

The Relation between Data and Categories
Describing the Categories

4.2.3

Overflow and Underflow Counts . . . . . . . . . .. . ... 4-3
How the Subroutine Interprets Single-Precision Numbers. . .

4-2

How to Call the Interval Histogramming Subroutine

4.4

Input and Output — Using the Subroutine

4.5

Modifying the Subroutine — Using Options
4.5.1

...

.. 4-3

000000000

..............

OOOOOOOOOOOOO

EIS (Extended Instruction Set).

4.5.2

. . .
EAE (Extended Arithmetic Element)

4.5.3

DPHS$ (Double-Precision Integers)

454

FREQS$ (Frequency Histogram)

oooooooooooooo

oooooooooooooooo

4-7
4-7

4-8

4-8
4-8

Examples of Input/Output Variation Using the HISTI
oooooooooooooooooooooooooooooo

The Interval Histogramming with Reference Points (RHISTI)

Subroutine
5.1

Definitions of Basic Terms and Conventions

5.2

Your Input to the Subroutine: Its Characteristics

ooooooooooooo

ooooooooooo

5.2.1

The Reference Points — Their Significance

0.2.2

The Relation between Data and Categories.

5.2.3

.
.

ooooooooooo

Number of Events to be Processed Following Each

Reference Point
5.3.2

0000000000

. . . . . . .
How the Subroutine Interprets Single-Precision Numbers.

How to Present Your Problem to the Subroutine

5.3.1

4-5

.. 4-8

0000000000000

Subroutine

5.3

4-2

4.2.2

4.3

4.6

4-1

4.2.1

4.2.4

Chapter 5

ooooooooooo

. .

...

Describing the Categories for the Interval Histogram

5.3.3

Overflow and Underflow Count

5.3.4

Frequency Histogram

...,

ooooo

oooooooooooooooo

oooooooooooooooooooo

4-10

5.4
5.5

5.6

5.7

Chapter 6

How to Call the RHISTI Subroutine . . . . .
Input and Output — Using the Subroutine.
.
Modifying the Subroutine — Using Options

5.6.1
0.6.2

EIS (Extended Instruction Set).
. . .
EAE (Extended Arithmetic Element)

5.6.3

DPRS$ (Double-Precision Integers)

Examples of Input/Output Variation Using the RHISTI
Subroutine

The Fast Fourier Transform (FFT) Subroutine
6.1

An Introduction to Fourier Transforms

6.1.1

6.1.2

Mathematical Definition of the Fourier Transform (CFD) .
Mathematical Definition of the Discrete Fourier

Transform (DFT)
6.2

Comparing the Continuous and Discrete Fourier Transform
6.2.1

6.2.2
6.2.3

Comparison of FFT and CFT Input.

.
Comparison of FFT and CFT Qutput .

6.3.1

6.4

...

. .

...

Internal Subroutine Scaling Procedure
Relational Scaling Procedure

Useful Properties of the FFT. . .
How to Call the FFT Subroutine
6.5.1

6.6

Scaling the Results of the FFT Subroutine
6.3.2

6.5

Similarities and Discrepancies between FFT and CFT

Results
6.3

Interpreting the Results of the Output Arrays

Modifying the Subroutine — Using Options
6.6.1

6.6.2
6.6.3

EIS (Extended Instruction Set).
. . .
EAE (Extended Arithmetic Element)

F.MAXN (Maximum I/O Array Size)

6.7

Example Using the FFT Subroutine

7.1

HowtoCal PHAMPL .

oooooooooo

ooooooo

Chapter 7

7.2

7.3

. . . . . .
Other Routines Used by PHAMPL .

...

Modifying the Subroutine — Using Options
7.3.1

ooooo

KIS (Extended Instruction Set).

7.3.2

. . .
EAE (Extended Arithmetic Element)

7.3.3

F4P$ (FORTRAN 77 Compiler).

ooo

oooooooooo

7.4

Examples Using the PHAMPL Subroutine

HowtoCallPOWRSP . . . .. . ... ...
Modifying the Subroutine — Using Options

ooo

...

Chapter 8

8.2

8.2.1

8.2.2

8.3

Chapter 9

. . . .
EAE (Extended Arithmetic Element).
.

Examples Using the POWRSP Subroutine .

.. 8-2

.. 9-2

. 8-2

The Correlation Function (CORREL) Subroutine
9.1

Using the Correlation Function Subroutine. .
Discrete Evaluationof CORREL . . . . . . .
Calculating the Correlation Coefficients . . .
HowtoCallCORREL . . . . . . . . . ...

9.5

Other Routines Used.

9.6

Modifying the Subroutine — Using Options

9.2
9.3

9.6.1
9.6.2
963

9.7

Appendix A

EIS (Extended InstructionSet).

.. 9-4

...

. 9-3

...

... 9-5

...

. 9-6

. 9-7

. . . . . . .
EAE (Extended Arithmetic Element).
. . . .
FFTOptions. . . . . . . . . . ...
...

... 9-7

EIS (Extended Instruction Set).

Examples Using the CORREL Subroutine

. 9-7

... 9-7

.. 9-7

Installing, Verifying, and Using LSP Under RT-11
A.1
A.2

Installation Requirements . . . . . . . . . . .
Installing the Laboratory Subroutines Software

...

... A-1

A.2.1

.. A-2

Copying the Distribution Volume
A.2.1.1

. A-2

Copying with Three or More Mass Storage

Devices
A.2.1.2

A.2.2

File Protection.

...

A.2.3

Making Corrections

A.2.4

Selecting the Form of SubroutinetoUse .

A.2.41
A24.2

A.3

Appendix B

. . . . . . . . .. ... A-3
Copying only Two Mass Storage Devices . . . . . . A4

...

... A-5

...

.. A-5

Using Distributed Object Files . . . .
Creating Customized Object Files —

.. A-5

LSPMAK, the Interactive Build Procedure .

. A-6

Verifying the Laboratory Subroutines Software.

A.3.1

Verifying the Distributed LSP Object Files.

A3.2

Verifying the Customized Object Files .

. A-9

.. A-10

Using Libraries .

Creating a Program that Calls the Laboratory Subroutines.
.

Storing the Laboratory Subroutines
.

. A-5

... A-10

...

. A-10

L. A-11

Installing, Verifying, and Using LSP Under RSX-11M/M-PLUS
B.1

Installation Requirements .

B.2

Installing the Laboratory Subroutines Software
B.2.1

Copying the Distribution Volume
B.2.1.1

...

... B-1

.. B-2

. B-3

B.2.1.2

. B-5

Copying a FILES-11 Distribution Volume with

Only Two Mass Storage Devices
B.2.1.3

. B-2

Copying a FILES-11 Distribution Volume with
Three or More Mass Storage Devices .

...

Copying a DOS-11 Distribution Volume

B.2.2
B.2.3

Making Corrections . . . . . . ... ...
Selecting the Form of Subroutine to Use

...

ooooo

B.2.3.1

B.2.3.2

ooooo

Using Distributed Object Files . . . . . . . . .
Creating Customized Object Files — LSPMAK,

the Interactive Build Procedure
B.3

Verifying the Laboratory Subroutines Software.

B.3.1
B.3.2
B.4
B.5

B.6

Appendix C

Verifying the Distributed LSP Object Files

oooooooooo

Verifying the Customized Object Files

Storing the Laboratory Subroutines . . . . . . .. . ..
Creating a Program that Calls the Laboratory Subroutines

Using Libraries

Sample of the Interactive Build Procedure for RT-11,
LSPMAK.SAV

Appendix D

Sample of the Interactive Build Procedure for RSX-1

1M,

LSPMAK.TSK

Figures
2-1
2-2
2-3
2—4

2-6
2-7

2-8

2-9
2-10

2-11
3—-1
3-2

3-3

3—4
3-5

3—6

Flow of the PEAK Subroutine . . . .
Calculation of True Peak Width . . .
Calculation of Estimated Peak Width

3-8
3-9

. . . . . . . .
Flow Chart for Peak-Processing; Initialization, Data

Flow Chart for Peak-Processing; Area Calculation .
. . . .
Flow Chart for Peak-Processing; Determining the Baseline

NEXTPT Subroutine — Peak-Processing
RITOUT Subroutine — Peak-Processing .

. . .
INPTR, INLAST, and NPEAKS Point to Slots

. . . . . .. . .. ..
Envelopes of Data (may contain more than one peak)

Actual Plot of the Input Data

Flow Chart for Envelope Processing; Data Entry . .
Flow Chart for Envelope Processing: Initialization,

...

...
.

Calculation of Peak Width, and Finding End of Envelop
e
Flow Chart for Envelope Processing; Count of Reject
Points and Reading Additional Values where Envelope
Flow Chart for Envelope Processing: New Minimum

...

NEXTPT Subroutine — Envelope Processing

RITOUT Subroutine — Envelope Processing . .
INPTR, NPEAKS, and INLAST Point to Slots

..
.

3-10 Actual Plot of Input Data, Showing Thresho
ld . . .
Plot of Input Data, Showing New Threshold Value
3-12 Plot of Input Data, Showing Threshold Value from
3-11

Begins .

and

Crest Detection . . . . . .. ... ... . . .
. .
Flow Chart for Envelope Processing; New Maximum;

Peak Beginsat Valley .
3-7

.
.

...

oooooooo

Example 2 and Assumed Baseline Offset

oooooooo

ooooooo

Vil

4-1

Interrelation between DATA/CATEGORY and

INTEGER/INTERVAL Concepts .
4-2

Page

...

... 4-2

Relation between FORTRAN Integers and Unsigned Binary

Values.
5-1

Interrelation between DATA/CATEGORY and

INTEGER/INTERVAL Concepts .
5-2

. . . . . . . . . .
Relation between FORTRAN Integers and Unsigned

6—-1

The Fourier Transform.

6—2

The Relationship Between FFT Input and CFT Input.

6-3

Output from the FFT

...

... 6—6

6—4

... 67

6-6

G(n - df) Returned by the FFT . . . . . . . .
Total Range of the Frequency Domain . . . .
Five Elements in the IREAL Output Array. .

.
.

.. 6-14
.. 6-16

2-1

Switch Settings for Significant Events in Peak Definition

2-2

Definition of Symbols

2-3

Definition of Peak Events .

...

... 2-15

3—-1

Definitions of Symbols Used .

...

... 3-5

...

... 3-14

...

Binary Values .

6-5

...

... 5-3

.., 5-4
. . . . . .. . ... ..... 6-1
.

. 6-5

Tables

3-2a Envelope-Processing Algorithm

. 2-7

.0 2-8

3-2b How to Compile and Prepare Data for
Envelope-Processing Subroutine .

Index

...

.. 3-16

Preface

MANUAL OBJECTIVES AND READER ASSUMPTION

The Laboratory Subroutines Programmer’s Reference Manual

describes the
Laboratory Subroutines Package (LSP), a set of eight
data-processing
subroutines to be used in a laboratory environment.

To use this manual, you should be a laboratory-oriented

programmer familmming language. You

1ar with the FORTRAN IV or FORTRAN 77 progra

should also be familiar with either the RT-11 operating

system (Single Job
or Foreground/Background (F/B) monitor) or the RSX-1
1M or
RSX-11M-PLUS operating system. In addition, you must
understand the
mathematics involved in explaining the subroutine
algorithms. However,
although the laboratory subroutines are written in the
MACRO programming language, you do not need to be familiar with MACR
O to use them.

(SJ)

MANUAL STRUCTURE

The Laboratory Subroutines Programmer’s Reference Manual

contains nine

chapters and four appendixes.

Chapter 1 introduces the Laboratory Subroutines softwar
e and explains
how to use the manual.

Chapter 2 describes the peak-processing subroutine, PEAK.
Chapter 3 details the envelope-processing subroutine,

NVELOP.

Chapter 4 discusses the interval histogramming subroutine,

HISTT.

Chapter 5 describes the interval histogramming with referen

routine, RHISTI.

ce points sub-

Chapter 6 details the fast Fourier transform subroutine, FFT.

Chapter 7 discusses the phase angle and amplitude spectra subroutine,
PHAMPL.

Chapter 8 describes the power spectrum subroutine, POWRSP.
Chapter 9 details the correlation function subroutine, CORREL.
Appendix A explains how to install, verify, and use LSP under the RT-11

operating system.

Appendix B explains how to install,
RSX-11M operating system.

verify,

and use LSP under the

Appendix C contains an example of the interactive build procedure for
RT-11, LSPMAK.SAV. The appendix also shows the output from the

procedure.

Appendix D contains an example of the interactive build procedure for
RSX-11M, LSPMAK.TSK. The appendix also shows the output from the

procedure.

RELATED DOCUMENTS

The following documents provide more information about the RT-11,
RSX-11M, or RSX-11M-PLUS operating systems and the FORTRAN IV
and FORTRAN 77 programming languages:
Reference
PDP-11

Order Number
FORTRAN 77 User's Guide

IAS/RSX-11

FORTRAN 1V User’s Guide

AA-1884D-TC
AA-1936E-TC

PDP-11 FORTRAN Language Reference Manual

AA-1855D-TC

RSX-1IM/M-PLUS MCR Operations Manual

AA-H263A-TC

RSX-11M/M-PLUS Task Builder Manual

AA-H266A-TC

RSX-11 Utilities Manual

AA-H268A-TC

RT-11 Programmer’s Reference Manual

AA-H378A-TC

RT-11/RSTS/E

AA-5749B-TC

FORTRAN IV User’s Guide

RT-11 Software Support Manual

AA-H379A-TC

RT-11 System User’s Guide

AA-5279B-TC

RT-11 System Message Manual

AA-5284C-TC

DOCUMENTATION CONVENTIONS
The following conventions are used in this manual.
e In programming examples, all information the computer prints appears

in black. All commands and responses you type appear in red.
o

means you must press the RETURN key on your terminal.

® You produce certain characters by typing a combination of keys together.
For example, hold down the CTRL key and type the letter C to produce

the CTRL C character. Combinations such as this are represented by

CTRLIC).

¢ Many commands in this manual contain the expression dvn:. When you

execute the commands, specify a device and unit number in place of dvn:.
If you do not include a unit number, the system uses unit 0 as a default.

For a list of devices and their abbreviations, see Chapter 3 of the
RT-11
System User’s Guide or Chapter 2 of the RSX-1IM/M-PLUS MCR
Operations Manual.
e In descriptions of commands or file names, capital letters represent actual
commands, file names, or file types. You must type these exactly as they

appear. Lower case letters mean that you must supply a name.
e The term RSX-11M/M-PLUS means either or both the RSX-11M or
RSX-11M-PLUS operating systems.

e Brackets represent optional elements in a specification. When you use an
option, do not type the brackets in the command line.

NOTE
Under RSX-11M/RSX-11M-PLUS, brackets are also a
part of the User File Directory (UFD) portion of file specifications, that is [group, member]. When you type this portion of a file specification, brackets are required syntax
elements. You must type the brackets in the command line.

Chapter 1
Introduction to the Laboratory Subroutines

The Laboratory Subroutines Programmer’s Reference Manual accompanies
the Laboratory Subroutines Package (LSP), a set of eight laboratory, dataprocessing subroutines.

This manual describes the eight subroutines and explains how to use them
with

your

FORTRAN

programs.

It contains

appendixes.

nine

chapters

and

four

You can use any chapter in this manual independently. Each chapter is a

self-contained document that deals with all the essential aspects of a particular subroutine. Each chapter outlines the algorithm and logic of a subrou-

tine. Each chapter describes the subroutine’s FORTRAN call, arguments,

and the options that can be used with the subroutine. Each chapter has a

special reference divider that precedes the chapter and that summarizes
the information contained in the chapter.

In addition, each chapter presents one or more example programs that use

the subroutines. Where necessary, certain chapters also present flowcharts
and glossaries to explain subroutine operation in greater detail.

The appendixes tell you how to install, verify, and use the Laboratory
Subroutines with your FORTRAN programs under the RT-11,
RSX-11M/M-PLUS operating systems.

1.1

The Laboratory Subroutines Package
The Laboratory Subroutines Package consists of eight subroutines that you
can call from any FORTRAN IV program running under the RT-11 opera-

ting system and from any FORTRAN IV or FORTRAN 77 program running

under the RSX-11M operating system. The eight subroutines perform a
variety of standard tasks commonly encountered in the laboratory.

NOTE

FORTRAN 77 V4.0 is the next version of FORTRAN
IV-PLUS V3.0. FORTRAN 77 is so named because it adhere
s
to the 1977 ANSI subset standard for FORTRAN programsming languages. Because FORTRAN 77 is compati
ble with
FORTRAN IV-PLUS V3.0, your FORTRAN IV-PL
US V3.0

programs can run under FORTRAN 77.

The eight LSP subroutines are:
1.

The peak-processing subroutine, PEAK, detects peaks in wavefor
m
data.
The envelope-processing subroutine,

NVELOP, detects peaks in discontinuous segments (envelopes) of waveform data.

The interval histogramming subroutine, HISTI, counts the number

of
elements in a data stream that fall into one or more predefin
ed

categories.

The interval histogramming with reference points subroutine,

counts the number of elements in a data stream marked with

points that fall into one or more numerical intervals.

RHISTI,

reference

The fast Fourier transform subroutine, FFT, numerically approximates
the analytical or continuous Fourier transform.

The phase angle and amplitude spectra subroutine, PHAMPL, converts
complex numerical values to phase angles and amplitudes.

The power spectrum subroutine, POWRSP, determines the power spectrum (the relationship between power and signal frequency) in a set of
Fourier coefficients.

The correlation function subroutine, CORREL, provides a discrete
method of performing the correlation function.

Each subroutine has hardware and software options you can use to extend

the capabilities of the subroutine. The chapter dealing with each subroutine explains which options the subroutine can use, what the options
do,
and when and how you should use the options. The Laboratory Subroutines
Package also contains a simple, interactive procedure that lets you build
the subroutines in order to create a customized version of your LSP software. “Building” consists of assembling the subroutines with the options

you choose enabled. The procedure does the following things:
1.

Lets you select which subroutines you want to assemble and which
options you want to use.

Creates a file that sets the switches to enable options you choose.
Creates a file that builds each subroutine you requested with the options you chose enabled.

1-2

Introduction to the Laboratory Subroutines

Creates a file that tests the subroutines you built to make sure your
software works properly.

All of the laboratory subroutines are written in MACRO assembly language, but you do not have to know MACRO to use them. You can invoke
any of the laboratory subroutines with a FORTRAN call statement as you

would invoke any FORTRAN subroutine.

The specific

FORTRAN call format for a Laboratory Subroutine is outlined
in the chapter describing that subroutine. In all calls you make
to any of
the Laboratory Subroutines, make sure you state all of the required
arguments explicitly. There are no default values for any of the argument
s. If
you omit an argument, accidentally or on purpose, or if you
supply too
many

arguments,

FORTRAN

error

processed.

1.2

message

results

and

data

The Laboratory Subroutines Package Distribution Kit
The distribution kit for the Laboratory Subroutines Package
mass-storage volume containing the Laboratory Subrout

consists of a

ines Package, this

manual, a software product description (SPD), and other forms.

The subroutines are supplied to you on the distribution volume
as both
source files and object files. If you decide to enable options,
the interactive
build procedure creates customized versions of the subroutines
from the
source files. If you decide not to enable any options, you can
use the procedure to build the subroutines without any options, or you can,
in some

cases, use the distributed object files by linking or task building

your FORTRAN programs. The object files were built with no

them to

switches set,
and therefore, with no options enabled. To determine if you
can use the
distributed object files, see Appendix A if you are using RT-11, or Appendi
x
B if you are using RSX-11M.

In addition, the distribution volume contains example program

s that call
the subroutines. Example programs exist on the distribution
volume as
FORTRAN source files. Example program file names have the
formEXnsub.FOR

where:

stands for the number of the subroutine example program

n
sub

EXnsub.FTN

stands for the first three letters of the subroutine’s file
name

For instance:
EX3RHI.FOR

EX3RHI.FTN

1s the third example program for the RHISTI subroutine.
Text of the example programs appears in each chapter along
minal output that results when you run the programs.

with the ter-

Introduction to the Laboratory Subroutines

1-3

Files on the distribution volume are as follows:

Peak-processing subroutine files:

For RT-11

For RSX-11M

FPEAK.MAC

FPEAK.OBJ

EX1FPE.FOR

EX1FPE.FTN

EX2FPE.FOR

EX2FPE.FTN

EX3FPE.FOR

EX3FPE.FTN

EX4FPE.FOR

EX4FPE.FTN

Envelope-processing subroutine files:
For RT-11

For RSX-11M

FNVLOP.MAC

FNVLOP.OBJ

EX1FNV.FOR

EX1FNV.FTN

EX2FNV.FOR

EX1FNV.FTN

EX3FNV.FOR

EX3FNV.FTN

Interval histogramming subroutine files:

For RT-11

For RSX-11M

HISTI.MAC

HISTIMAC

HISTI.OBJ

EX1HIS.FOR

EX1HIS.FTN

EX2HIS.FOR

EX2HIS.FTN

EX3HIS.FOR

EX3HIS.FTN

EX4HIS.FOR

EX4HIS.FTN

Interval histogramming with reference points subroutine files:
For RT-11

For RSX-11M

RHISTI.MAC

RHISTIL.MAC

RHISTI.OBJ

EX1RHI.FOR

EX1RHIL.FTN

EX2RHI.FOR

EX2RHI.FTN

EX3RHI.FOR

EX3RHI.FTN

Fast Fourier transform subroutine files:

1-4

For RT-11

For RSX-11M

F4FFT MAC

F4FFT.MAC

F4FFT.OBJ

EX1F4F
. FOR

EX1F4F FTN

Introduction to the Laboratory Subroutines

Phase angle and amplitude spectra subroutine files:

For RT-11

For RSX-11M

PHAMPL.MAC

PHAMPL MAC

PHAMPL.OBJ

EX1PHA.FOR

EX1PHA.FTN

EX2PHA.FOR

EX2PHA.FTN

Power spectrum subroutine files:
For RT-11

For RSX-11M

POWRSP.MAC

POWRSP.OBJ

POWRSP.OBJ
EX1POW.FTN
EX2POW.FTN

EX1POW.FOR
EX2POW.FOR

Correlation function files:
For RT-11

For RSX-11M

CORREL.MAC

CORREL.OBJ

EX1COR.FOR

EX1COR.FTN

Verification procedure files:
For RT-11

For RSX-11M

LSPVER.COM

LSPVER.CMD

Interactive build procedure files:
For RT-11

For RSX-11M

LSPMAK.SAV

LSPMAK.TSK

Files generated by the interactive build procedure:
For RT-11

LSPCND.MAC
LSPBLD.COM
LSPVER.COM

For RSX-11M

LSPCND.MAC
LSPBLD.CMD
LSPVER.CMD

For

instructions on installing, verifying, and using the
Laboratory
Subroutines, see Appendix A if you use RT-11 or Append
ix B if you use
RSX-11M/M-PLUS. Each appendix includes a description
of the interactive build procedure, LSPMAK, and instructions for using
it.

Introduction to the Laboratory Subroutines

1-5

PEAK-PROCESSING (PEAK) SUBROUTINE
FORMAT:
CALL PEAK(TABLE,INPUT,INLAST,INPTR,OUTPUT,IDIMO,NPEAKS)

Where:
ITABLE

is a 68-element integer array (a 79-element array if AUTOG$

or DPP$ is enabled).
ITABLE(1)

original point density

ITABLE(2)
ITABLE(3)

=
=

baseline test factor
gate parameter

ITABLE(4)

minimum increase indicator

ITABLE(5)

output data type

ITABLE(6)

error indicator,

ITABLE(7)

reentry pointer

ITABLE(8)

input type indicator (if AUTOG$ or DPP$ is
enabled)

INPUT

is an integer array containing input data.

INLAST

is an integer variable specifying subscript of last data element
in INPUT.

INPTR

is an integer variable specifying subscript of last element in
INPUT processed.

OUTPUT

is a double-subscripted array used to store output data.
OUTPUT(@(1,N)
OUTPUT((2,N)
OUTPUT(3,N)
OUTPUT(4,N)
OUTPUT(,N)
OUTPUT(6,N)
OUTPUT(7,N)
OUTPUT(8,N)
OUTPUT@H,N)

=
=
=
=
=
=
=
=
=,

area, Nth peak
crest height, Nth peak
crest time, Nth peak
leading minimum height, Nth peak
leading minimum time, Nth peak
width, Nth peak
trailing minimum height, Nth peak
trailing minimum time, Nth peak
ending indicator, Nth peak

OUTPUT(10,N)

= current

number

input

averaged

IDIMO

NPEAKS

is an integer variable specifying number of peak data sets that
can be stored in OUTPUT.

is an integer variable specifying number of peak data sets already stored in OUTPUT.

FILE NAMES:

FPEAK.MAC (source file); FPEAK.OBJ (object file)

points:

OPTIONS:
EIS

(Extended Instruction Set — KE11-E)

EAE

(Extended Arithmetic Element — KE11)

AUTOG$
DPPS$

(Autogaining)

NOFLT$

(No Filter)

(Double Precision Integer Input)

APPROXIMATE SIZE OF SUBROUTINE (IN WORDS):

If you use the digital filter and enable the following options:
NONE

|EIS

EAE

NONE

1033

905

946

AUTOGS$S

1237

1097

1150

DPP$

1219

1079

1132

If you enable the No Filter (NOFLT$) option and the following options:
NONE

EIS

EAE

NONE

957

831

870

AUTOGS

1118

982

1031

DPP$

1100

964

1013

TYPICAL EXECUTION SPEED:

With PDP-11/34 and EIS enabled: 1000 Points/second.
With PDP-11/03 and EIS enabled: 450 Points/second.

Chapter 2
The Peak-Processing (PEAK) Subroutine

The peak-processing subroutine detects significant fluctuat
ions, called
peaks, in data describing a waveform and reports definitive characte
ristics
for each peak found. The process is known as peak analysis.

Input to the subroutine is a series of discrete positive integers

corresponding to values of a waveform function at evenly spaced intervals
. To eliminate distortion-producing components in the data, the
input is linearly
averaged and filtered before final processing (Figure 2-1). You
can change
specified algorithm parameters to enhance detectability
of directional
trends and baselines for a given set of data.
Figure 2-1:

Flow of the PEAK Subroutine

PEAK-Processing Algorithm

INPUT;
Averaging

Digital
Filter

_ | Trend Width Baseline Detection:
Area Width Calculation: OUTPUT

PEAK Subroutine
MR-S-1600-81

Output from the subroutine is in the form of size and position for

each peak
detected. Size is defined by area, height, and width, and position
is expressed in terms of when a peak begins, crests, and ends. The
subroutine
further reports how each peak ends — on a baseline or at a valley.

2.1

Definition of Basic Terms and Conventions
It is important to understand how some of the terms and conventi
scribing the PEAK subroutine are used throughout this chapter.

ons de-

2-1

e The term data (input) stream describes all values presented to the sub-

routine for processing. Actual values processed by the algorithm are
sometimes called heights, for example, crest height, leading minimum

height.

¢ The duration axis of the waveform is the time axis. Time is measured as

the number of raw data points processed since the start of the input
stream. Thus, the term crest time means that crest height was observed

when a number of raw data points equal to crest time were processed.
e “Noise” is a generic term for all distortion-producing compone

nts in the

input data.

e Point-to-point changes are local changes, as contrasted with overall
changes during the course of the waveform, which are called trends.

e Changes are persistent in one direction if the number of changes in that

direction exceeds the number in the opposite direction.

2.2

The Peak-Processing Algorithm: Processing Raw Data
The peak-processing algorithm detects increasing and decreasing trends in

a set of data. Output from the PEAK subroutine is directly related to the
points where we observe changes in these trends. When we see an increasing trend, the point where the increase begins is labelled the start of the

peak, and its value the leading minimum height. The point where a subse-

quent decreasing trend begins is the crest, or crest height, of the peak. And

the

point

where

the

decreasing trend stops — or a baseline is
detected — is taken as the end of the peak, or its trailing minimum height.

We can then use this information to calculate the area and width of the
peak. Under ideal conditions this sequence defines the total function of the
algorithm.

Actual conditions are seldom ideal, however. Environmental influences
during data collection tend to distort the pure function being analyzed. To a
great degree the algorithm and any controls that you can exercise over the

subroutine parameters are aimed at removing these distortions so that only
the real (dominant) trends in the data are visible.

2.2.1

Averaging of Input Data

The peak-processing algorithm first takes a linear average of input-data
points; you can specify the number of points to be averaged by means of the
first variable parameter, the Original Point Density (OPD). Thereafter the

subroutine deals only with averaged heights, which can represent several

raw data points. Keep in mind, however, that the time associated with each

averaged height is based upon the total number of raw data points aver-

aged since input began.

This averaging process smooths any “rough edges” from the data. Obvi-

ously you will want to give serious thought to the value you assign to the
OPD. If too many points are averaged, real information may be lost. In an

extreme case you might miss an entire true peak, but a more common

result is late detection of significant trend changes. By averaging too few

points, on the other hand, you could detect false trend changes.

In certain applications of the subroutine you may find that peaks are “tall

and thin” at the outset of the waveform, then tend to become “short and fat”

as 1t progresses. The algorithm compensates for this tendency by Increasing
automatically the number of points averaged when it detects a peak width

that exceeds a preset optimum.' Thus the algorithm makes wide, short
peaks more visible and increases the likelihood of detecting real data fluctuations that might otherwise appear insignificant.

2.2.2

Use of the Digital Filter

The averaged data points are not processed directly by the trend-detecting
portion of the algorithm but are first filtered by means of a digital filter.

The

equation for this nonlinear center-weighted filter involves seven
averaged-data points having coefficients of a modified least-squares fit.

Yo=[-(Yu+ Y. +4(Y, + Y. + 11(Y, + Y. + 14Y,)/
42
The coefficients are tuned to prevent area distortion for small peaks in the
vicinity of large ones.

As each new averaged data point is calculated, it is placed in the filter as
the last, or Y., point. The new center point is calculated, after which the

points used in the filter are shifted down by one, that is, Y-, =Y,. Prerequisites for this process are:

e Seven averaged points must be calculated before the digital filter may be
applied.

e The first point to be considered for directional-trend detection is the center point resulting from application of the digital filter to these
seven points.

original

e Each subsequent set of seven points used by the filter is chosen using

a
sliding “window”, that is, each new averaged point (after the first six) is

used seven times in successive applications of the filter. There is a slight
twist to the sliding window in that once the filter has been applied
three
times, four of the points in the current application of the filter are the
result of averaging raw data while the other three (Y, Yo, Y-)) are
the
result of previous applications of the filter.

2.2.3

Trend Detection — Application of the Gate Factor

Although averaged and filtered data have been smoothed in earlier processing, the resultant filtered data points may still exhibit slight point-to-

point

fluctuations unrelated to the dominant trend of the data. You may set
1 When the half-width-at-half-height measurement of a peak
doubles the number of points averaged.

two

exceeds 25, the algorithm

The Peak-Processing (PEAK) Subroutine

2-3

parameters — the gate factor and the minimum increase — so that the

algorithm eliminates much of the effect of this fluctuation.

The gate factor (GT) specifies a valid directional trend in terms of the
number of changes in direction, either persistent or consecutive, over a

series of filtered points.

The minimum increase (IM) is a standard used to test for a real increase in

filtered data from point to point.

At the outset of the input stream and at points where crests are detected,

neither an increasing nor a decreasing directional trend has yet been established. The next established trend is determined at these points as the first

direction in which the data change “gate” times.

At intermediate points a current trend is already established. Changes in
directional trend at these points may be established only if the number of

consecutive local changes in the new direction is equal to the gating factor.

A local change is defined in terms of the relation between a given data
point and the local minimum or maximum. If the current height is less
than the local minimum, the change is downward, and conversely, if the

height is greater than the sum of the local maximum and the minimum
increase value (IM), the change is upward. If the height is between the local
minimum and maximum, no change is indicated (although the area is
updated).

When processing is initialized, and at the crest of each peak, the local
minimum is set to a very high value and the maximum to a very low value.

Between crests the local minimum and maximum may be best described by

the flow diagram.
It

should

stressed

that

the points of greatest interest on the
waveform — essentially the points that determine the peak — are found
at the points of trend change: the beginning of a peak, the peak crest, and
sometimes the end of a peak. This test is the heart of the algorithm.

2.2.4

Calculation of Area under the Peak

Two peak characteristics that are not entirely dependent on points of domi-

nant trend change are area and width. The area under the peak, or integral, is calculated by taking the sum of the area increments corresponding

to each filtered point and half the area increment at the first and last points

of a peak. The area increment at each filtered point is the product of its
height times the number of points currently being averaged.

2.2.5

Algorithm Definition of the Width of a Peak

Calculation of the peak width must be explained in a little more detail. The

peak-processing algorithm defines peak width as the difference between the

time when the crest occurs and the time when a point is reached on the

trailing side of the peak whose height is half the crest height as measured

from the height of the leading minimum (Figure 2-2).

The Peak-Processing (PEAK) Subroutine

It is possible that the data may establish an increasing trend on the trail-

ing side of a peak before the point is reached where width is normally

calculated. An increasing trend on the back of a peak is seen as terminat-

Ing the peak; the width calculation for the peak is then made at the point
where the increasing trend begins. The value calculated is called the
estimated peak width, and it is half the difference between time of crest
occurrence and time at which the increasing trend is observed (Figure 2-3).

Figure 2-2:

Calculation of True Peak Width

Height

Time

a = Leading Minimum Height
b

Crest

d = b-a

Height

¢ = Point Whose Value is '2(a+b)

Figure 2-3:

=d2

Peak

Width

Time

c'-Time

b’

MR-S-1601-81

Calculation of Estimated Peak Width

]

b o

Time

a = Leading Minimum Height
b = Crest Height
¢ = Trailing Minimum Height (Point at Which Peak
Ends Because Increasing Trend is Detected)

b’

d
e
f
g

=
=
=
=

b-a
Time ¢c'-Time b’
e/2 (Estimated Width)
Height at Which Peak Width Would Have Been

Calculated if Decreasing Trend Had Continued
MR-S-1602-81

The Peak-Processing (PEAK) Subroutine

2-5

2.2.6

Algorithmic Detection of the Baseline

A final and important step in peak analysis is to determine whether

reported for a peak have been affected by similar data observed for

data

another
peak. The algorithm checks to see whether recorded peak data indicate
a
period of relative quiescence before a new peak begins or whether
a new
peak begins with no intervening quiescent period. Such quiescence
relative
to the overall peak contour is interpreted as a baseline; when it does
not

occur, we say that the peak has ended at a valley. The problem
thus becomes one of detecting when, or if, the baseline is reached.

Normally we assume that when the algorithm is initiated, input
starts
from a quiescent state; therefore we may take the point at which an in-

creasing trend is first observed to be the current baseline height as well

as
the leading minimum height of the first peak. Because baseline detection

thereafter involves a comparison of relative minimums, this first detected
minimum has a profound effect on the entire process.

Once a crest has been detected, any attempt to find a new baseline begins
only after the width has been calculated. The time past crest detection
when the baseline search begins is a function of the calculated width. Spe-

cifically baseline detection begins at a time equal to crest time plus the
product of the width and the baseline test factor (BT), an input variable

parameter. The interval between crest detection and the start of baseline

detection reflects the duration of a normal peak as it decays to a relatively

quiescent state.

To detect an actual baseline height, the slopes of successive tangent lines

from the current baseline point to each new filtered point are calculated. If

two successive increases in slope are observed before an increasing trend in

the filtered data is established, the second of these points is taken as the
termination of the peak, and the peak is seen as ending on a baseline.

If an increasing trend is established before two successive increases in slope

are observed, the peak is said to end at a valley, the new peak begins at the
point where the increasing trend is first observed, and the baseline data
remain unchanged.

Note that even though two successive increases in slope indicate a baseline,
the next peak does not begin until that point where another increasing
trend is established. The leading minimum point for the next peak is inter-

preted as defining the height and time of the new baseline. The area be-

tween the trailing minimum of the last peak and the leading minimum of

the new peak is ignored.’

! Data taken during this period indicates that there is no peak-producing activity.

2.2.7

Flow Charts for the PEAK Subroutine

The series of flow charts presented as Figures 2—4 through 2-9 gives de-

tailed logic for the PEAK subroutine. Supplementary information is presented in Tables 2-1 through 2-3. Table 2-1 lists the combinations of

switch/indicator settings that characterize significant events during peak
detection. Table 2-2 defines the symbols used in the flow charts and accom-

panying explanation.

Table 2-3

reviews and summarizes flow-charted
events as they apply to three possible peak configurations:

e A peak starting on the baseline and ending on a “new” baseline
e A peak starting on the baseline and ending at a valley
e A peak starting at a valley and ending on either a baseline or a valley

Table 2-1:

Switch Settings for Significant Events in Peak Definition

Significant

Current Trend Indicators

Event Switch

Decreasing

Increasing

What is Happening with

Relation to Peak Processing

N/A

On front of peak that started on
current baseline

Detected a baseline value; looking for a new peak to begin (ini-

tial conditions)
0

Crest

detected

for

peak

that

started on baseline
1

N/A

New peak begins before point is
reached at which width is to be

calculated (forced calculation of
width)
1

After crest, looking for point
where width is to be calculated

N/A

front

side

peak

that

started at a valley
2

Testing for new baseline value

after width has been calculated
2

Crest

detected

for

peak

that

started at a valley

The Peak-Processing (PEAK) Subroutine

2-17

Table 2-2:

Definition of Symbols

Current Baseline height

BHT

Time of current baseline height

Baseline switch:
0

Peak starts on baseline

Looking for width

Looking for end on baseline

Baseline test factor'

Height of last crest”

CHT

Time of last crest”

Current number of persistent decreases in filtered data

Switch that is set (=1) if signal is decreasing

Number of persistent changes (gating factor) that defines an

increasing/decreasing trend’

Accumulated area as signal increases

Current number of persistent increases in filtered data

Switch that is set (=1) if signal is increasing

Minimum differential between filtered data points that the algorithm inter-

prets as signifying a real increase’
IPD

Switch that indicates whether an increase is needed in the number of points

averaged:

IPD=PD

if number of points is to be increased

IPD=0

if no increase is needed

LMH

Leading minimum height for peak®

LMT

Time of leading minimum height’

MNH

Current minimum height®’

MNT

Time of current minimum height”’

MXH

Current maximum height

MXT

Time of current maximum height

OMH

Old minimum height (before increasing trend is established)

OMT

Time of old minimum height

OPD

Original point density'

Old Slope

Point density; number of raw data points currently needed to obtain next

average point”’

Slope increase counter; baseline test

New or current slope

Accumulated total area during peak formation”TM

TTM

Raw point counter (current time)

Width of peak’

(Continued on next page)

2-8

The Peak-Processing (PEAK) Subroutine

Table 2-2:

Definition of Symbols (Cont.)

Large number used to reset small number

Element of digital filter

Current filtered point, that is, center point of current window

Type

Peak ends on valley

Peak ends on baseline”

I Value set by user
2 Value reported by algorithm

3 Value can change during peak detection; reported values are those
the end of a peak is detected.

Figure 2-4:

that are current when

Flow Chart for Peak-Processing; Initialization, Data
Averaging, and Application of Digital Filter

Set Variables for Initial Entry

Indicate
Error if

Possible

'S,e! ht‘ega:we
ointers

Zero

Get

First

Six

Values for Digital

Filter Via Six

Calls to NEXTPT

Go to IRESUM

1st

Call for Data
Stream

Go to ORESUM

MNH = XL

MXH =-XL

DCC==00

} Neither Trend Established

L|)|==()1

fSet Last Established Trend to Decreasing

Get Next Point
Call NEXTPT
Set Y +3=

PD=PD +IPD
TTMM=TM + PD

Results

IPD=0

1
Yo:[—(Y_:,+Y+3)+4(Y_2+Y+2)+11(Y_1

Reset Variables for Next Peak:
Set Current Minimum to Large Value

Set Current Maximum to Small Value

|Number of(l:nput \thllpes ::Iayége Doubled
ncrement

Current

Time

No Need to Increase Number of Input Values

Apply Digital Filter
+Y+1)+14Y0]42

1=-2-10.+1,+2,+3

Shift Window
Down Yi-1 = Yi

Center Point

- Latest Minimum?
Yes

Check for Maximum

MR-S-1603-81

The Peak-Processing (PEAK) Subroutine

2-9

Figure 2-5:

Flow Chart for Peak-Processing; Calculation of Peak
Width and Search for Baseline

Y Y

Found New Minimium

Look for Peak Width?

Yes

Is Y_,Low Enough to Find Width>

Yes

WD = TM-CHT
BS=2

Calculate Peak Width
Start Checking for Baseline

Width

25 Fiitered Points?

Yes

TA=TA+(Y,, 2)
IPD=PD

Add Correction Factor to Accumulation Area
Increase Number of Input Values

B
MNH = Y,

PDC =0C + 1
TA=TA
+ (Y_,‘PD) + 1A

Record Current Minimum Value
Record Current Time
Bump Number of Minimums Found
Accumulated Area + Current Area + Area During Increase

Does This Decrease Occur After A
Detection of Baseline?

Has an Increasing Trend Been Established

Since Baseline Detection?

Clear Current Area During Increase
TA=0

Disregard Area Between
Points at Which Baseline
Is Detected And Start of
Next Peak

Number of Minimums - Gate?
Yes

Establish Decreasing Trend

Current Maximum is Very Small
Number

s This a Decrease After an Establii shed
increase?

MXH
= -XL

Y es

DETECTED PEAK CREST

CH=MXH

Record Crest Height

Record Crest Time

Record Lendin? Minimum Height

Record Time of Leading Minimum Height
Look for Peak Width

Process Next Peak
MR-S-1604-81

2-10

The Peak-Processing (PEAK) Subroutine

Figure 2-6:

Flow Chart for Peak-Processing; Area Calculation

Update Total Accumulated Area
During Increase by Current Area

IA=1A+ (Y_,'PD)

Current Point - Current
Maximum + Minimum

Increase?

Yes

Reset Current Maximum Height
Reset Time of Latest Maximum
Bump Current Number of
Persistent Increases in
Filtered Data

Current Number of Increases

MXH=Y_,
MXT = TM
IC=IC +1

]

Gate?

Yes_{

N200

Clear Counter for Number of Minimums

DC=0

Is Current Trend Increasing?

DI=1
Yes

Update Accumulated Area During Increase
Save Time of Last Minimum

IA=1A +'2PD*"MNM
H=1 OMH = MNH

Establish Increasing Trend

DI=0 OMT = MNT

NEW PEAK STARTS
Peak Started on Baseline

Looking for Width

NEW BASELINE

Reset Baseline Height

Regrtu‘léiirgn:t of Occurrence

BH = OMH

BHT = OMT

-0

WD = /2(MNT-CHT)

Forced Estimate of Width

PEAK

Checking for
End on
Baseline

ENDING
ON VALLEY

Type=0

CALL RITOUT

b
BS =2

{'
—e{

N160

)}

Yes

—

This Switch Combined With
Increasing Trend Suggests
Search for Crest

Width - 25 Filtered Points?
WD PD- 25

WA:TA+(Y+1 2)

Add Area Correction
Increase Number of input Values

IPD=PD

MR-S-1605-81

The Peak-Processing (PEAK) Subroutine

2-11

Figure 2-7:

Flow Chart for Peak-Processing; Determining the

Baseline

Set Current Minimum to Current Maximum Height
MNH
= MXH

Baseline Test

Has Width Been Calculated?

Is Trend Decreasing?

Width Test

_ Current Point-Current Baseline

Height

Current Slope= Current Time-Current Baseline Time

SL= (Y_{'BH) (TM-BHT)

Old Slope Current Slope?

Yes

os=st
SC=0

Update Old Slope

Clear Slope

Increase Counter

Increment Slope Increase Counter

SC=SC+1

Is Slope Increase Counter -2?
SC -2

Yes

Type=1

CALL RITOUT

1
Clear Counter
Set Old Siope
Value
Clear Baseline Switch

SC=0
0S=XL
BS=0

»{

N100

MR-S-1606-81

2-12

The Peak-Processing (PEAK) Subroutine

Figure 2-8:

NEXTPT Subroutine — Peak-Processing

Subroutine NEXTPT (Not Accessible to

User)

Prepare to Average

Clear Sum

Copy PD

Reentry From

Main Program

Any Input Left in INPUT Array?

[Set INPTR = -1
Return to

Main Line Code

Set Next Entry

Main 16 IRESUMFrom

increment Input Pointer

Increment INPTR

NPTR- ; INLAS

Transparent to User)
Yes

Add Next Point tol
Sum; Decrement
Copy of PO

More Points
to Sum

Get Averaged Point
Divide Sum
by PD

)

Return to

Algorithm with

Average Point

MR-S-1607-81

The Peak-Processing (PEAK) Subroutine

2-13

Figure 2-9:

RITOUT Subroutine — Peak-Processing

Subroutine RITOUT (Not Accessible to User)

Add Correction
Factor to Ares
TA=TA + .5"MNH*PD

Increment OUTPUT Array Pointer

Reentry From

Main Program

increment

NPEAKS

Any Room Left in OUTPUT Array?

Set NPEAKS =-1
Return to
(Transparent to User)

Store
TA

CH
CHY

LMH
LMY
WD

MNH

MNT
T

Floating
Point

Return to

Algorithm

Convert to
Single-Precision

Floating Point

Double

Precision

iConvert to
Double-Percision|
Floating Point
MR-S-1608-81

Table 2-3:

Definition of Peak Events

{

:
T

I
'|
'
E%
b

Peak 1
|

d’

Time

| __—-1
I :
|
o
B
Peak 2 ——w{e—Peak 3 —s|

]

e’

]

i’

I’

MR-S-1611-81

Point/Section

Flow Chart

of Curve

Description

Referencel(s)

Input begins

Flowchart begins

a-b

Decreasing trend in data after baseline

detection
b

|BS=0.DI=1.11=0

DC=>GT IC<GT

Increasing

trend

minimum

height'time

established;

leading

of Peak

de-

|[OMH=b

BH-=b

|OMT=b’

BHT-=b’

tected; “new” baseline data (height and
time) defined

b-¢

Increasing trend in data: change in established

trend

will

indicate

crest

established;

crest

detection
c

Decreasing

trend

height and time detected and recorded;
leading minimum data recorded; start
looking for point
where
width
is

| BS=0,DI =0,I1=1
|DC<GT.ICGT

| LMH-OMH CH -¢

| LMT ~=OMT CHT =¢'

calculated
c-d

Decreasing trend in data after crest de-

|BS=1DI=1.11-0

tection and before width calculation

DC>GT,IC<GT

Point

where

width

calculated:

d=(b+c¢)2

d-e

Decreasing trend in data after width is
calculated

and

before

baseline

detected
e

|WD—=d'-¢’

|BS=2,DI=1.11-0
|DC>GT.IC<GT

Baseline detected; Peak 1 ends at this

| MNH =e

point,

|MNT=e’

which

recorded

trailing

minimum

Type =1

END OF PEAK 1

e-f

Decreasing trend after baseline detection and before start of next peak:; area
under curve ignored

|BS=0DI—=1.1=0
| DC >GT,IC<GT

(Continued on next page)

The Peak-Processing (PEAK) Subroutine

2-15

Table 2-3:

Definition of Peak Events (Cont.)

Point/Section

of Curve

Flow Chart

Description

Reference(s)

START OF PEAK 2

Increasing

trend

established:

leading

minimum (height and time) of Peak 2

detected;

baseline

data

(height

|OMH=f

BH=f

|OMT=f

BHT={

and

time) redefined
g

Height on Peak 2 (after crest detected)

| No corresponding point on

where width would be calculated if data | flow chart

were

to decrease to this point before

start of Peak 3:

g=(h+f)2=(CH,-OMH)2

f-h

Increasing trend in data; change in established trend will indicate crest detection (see b-c)

Decreasing trend
established;
crest
height and time detected and recorded;

leading minimum data recorded: start
looking for data value g
h-i

BS=0,DI=0,II=1

DC<GT,IC>GT

|LMH=OMH

CH=h

|LMT=OMT

CHT="h'

Decreasing trend in data after crest
detection and before width calculation
(see c-d)

|BS=1DI= 1,II=0

Increasing trend
established
before
width of Peak 2 calculated; forced estimation of width of peak 2 as (i'-n')/2;

|WD =(MNT-CHT)/2

DC>GT,IC<GT

|MNH=i BH=f OMH =i
|MNT=i' BHT=f OMT =i’

Peak 2 ends at valley with i as trailing | Type=0
minimum for Peak 2; Peak 3 begins
with 1 as leading minimum: baseline

data remain unchanged

END OF PEAK 2/START OF PEAK 3
1-j

Increasing trend in data; change in established trend will indicate crest detection (see b-c,f-h)

]

| BS=2,DI=0I1=1
| DC<GT.,IC>GT

Decreasing
trend
established;
crest | LMH=0OMH CH =]
height and time detected and recorded; | LMT =OQMT CHT
= )’
leading minimum data recorded: start
looking for point where width is to be

calculated
J-k

Decreasing trend in data after crest
detection and before width calculation
(see c-d)

Point

where

width

k=(j+1)2

calculated:

|BS=1,DI=11II1=0

DC>GT,IC<GT

WD=k'-’

(Continued on next page)

2-16

The Peak-Processing (PEAK) Subroutine

Table 2-3:

Definition of Peak Events (Cont.)

Point/Section

Flow Chart

of Curve

Description

k-1

Decreasing trend in data after width is
calculated and before baseline is detected (see d-e)

]

Reference(s)

|BS=2DI=111=0

|DC>GT,IC<GT

Increasing trend
established before
baseline is detected; peak 3 ends at val-

|MNH=1BH=f OMH=1

ley with 1 as trailing minimum; Peak 4

|OMT =1’

begins

with

leading

|MNT =1"

BHT =f"

minimum; | Type=0

baseline data remain unchanged

END OF PEAK 3/START OF PEAK 4

Peak 4 not shown in illustration

2.3

How to Call the Peak-Processing Subroutine
The symbolic name for the peak-processing subroutine is PEAK, and the
general format for the FORTRAN call is:

CALL PEAK(TABLE,INPUT,INLAST,INPTR,OUTPUT,IDIMO
NPEAKS)

For reference, argument names in the call to PEAK have been assigned
arbitrarily. You may supply your own argument names, but you must state

all of the arguments explicitly. There are no default values for any of the

arguments. If you omit an argument, either accidentally or on purpose, or if
you supply too many arguments, a FORTRAN error message results,
and
no data is processed. The arguments are described in the following

discussion.

ITABLE is an integer array used to store intermediate results and other
information required by the algorithm; its dimension is normally 68.
You must set the values of the following array elements to transmit
variable parameters and other information to the subroutine.

ITABLE(1)

Number of raw input values to be averaged to determine a
point for use by the digital filter; this variable parameter

1s called the original point density (OPD) in the description of the algorithm. In general, the OPD should be so
chosen that the number of averaged data points on the
first peak is about 100.

I See Section 2.5 for the options you can use with the peak-processing subroutine.

The Peak-Processing (PEAK) Subroutine

2-17

ITABLE(2)

The baseline test (BT) factor (Section 2.2.6); on a peak
whose width is WD, baseline detection begins at time?
WD-ITABLE(2) past crest time. In general, suggested values can range from 3 to 5.

ITABLE(3)

The

number of either persistent or consecutive local
changes in one direction needed to establish a new domi-

nant directional trend. It is the gate parameter discussed
in Section 2.2.3. In general, suggested values can range
from 3 to 8.

ITABLE(4)

Minimum differential (IM) between filtered data points
that the algorithm interprets as a real increase; this element, with ITABLE(3), determines real changes in domi-

nant directional trends (Section 2.2.3).
suggested values can range from 1 to 5.

ITABLE(5)

ITABLE(6)

general,

The data type of the output array:
=(

output type is double-precision integer

=1
=-1

output type 1s single-precision floating-point
output type is double-precision floating-point

Error

indicator

the

calling

sequence

input

parameters

Indicates no error

Indicates ITABLE(N) is in error, for example,

ITABLE(1)<0
ITABLE(2)<0

=-N
=-8

Indicates the Nth argument is in error, for example, INPTR>INLAST (see the following discussion)

Indicates that the calculated area to this point has
caused an overflow. That is, it exceeds 2% - 1.
When the overflow is detected, PEAK returns with

INPTR and NPEAKS set as usual. However,
OUTPUT (1, NPEAKS +1) will contain the value

of the area of the current peak up to and including
the point of overflow. You must take corrective ac-

tion by saving this value and returning to the
PEAK subroutine for further processing. PEAK
calculates the remaining area and peak character-

1stics. When PEAK returns again, the peak area
reported is the area of the peak from the last point

of overflow. To determine the actual area of the
peak, simply convert the overflowed value to a pos-

itive, double precision, real number and add to it

the remaining area of the peak.

2 Refer to conventions defined in Section 2.1 of this chapter.

ITABLE(7)

This element must be set to zero before the initial call is
made to the subroutine for each new stream of data. When

the subroutine processes a data stream in “parts” (Section
2.4), 1t uses ITABLE(7) for reentry to process each subsequent part. This element should thus not be altered by a

user until all parts have been processed.

ITABLE(8)

Elements used exclusively by the subroutine while the
data stream is being processed.

ITABLE(68)

INPUT is an integer array containing the raw data to be processed. Note
that all data must be positive and in the range 0 through 32767(2'° - 1).!

INLAST is an integer variable having the value of the subscript of the last

element of INPUT containing data.

INPTR is an integer variable having the value of the subscript of the last
element processed by PEAK. We can also think of it as having a value

one less than the subscript of the next datum in INPUT to be processed.
For example, if the first element of the array is to be processed, INPTR

should be set to zero. You must set the value of INPTR before calling
PEAK; however, PEAK changes the value before returning.

OUTPUT is a double-subscripted array used to store the results of applying the peak-processing algorithm. The first dimension specifies the
number of data elements to be output for each peak detected; there are

always ten. The second dimension specifies the number of sets of peak
data that can be stored by the algorithm while processing the input
data and is defined by IDIMO.

The data type of the output array is optional and can be any of those

specified by ITABLE(5).

The ten data elements reported for each peak are:
OUTPUT(1,N)

Area of Nth peak

OUTPUT(2,N)

Height of crest, Nth peak

OUTPUT(3,N)

Time of crest, Nth peak

OUTPUT4,N)

Height of leading minimum for Nth peak

OUTPUT(5,N)

Time of leading minimum for Nth peak

OUTPUT(6,N)

Width of Nth peak

OUTPUT(7,N)

Height of trailing minimum for Nth peak

OUTPUT(8,N)

Time of trailing minimum for Nth peak

I See Section 2.5 for the options you can use with the peak-processing subroutine.

The Peak-Processing (PEAK) Subroutine

2-19

OUTPUT(9,N)

Indicator of how peak ended:

OUTPUT(10,N)

ended on valley

ended on a baseline

Current number of input data points being averaged

IDIMO is an integer variable that transmits to the subroutine

the second
dimension of the output array. It defines the number of peaks
that can
be reported before the output array is filled.

NPEAKS is an integer variable giving the number of peak data sets

stored
in the output array. We can also think of it as having a value of one
less
than the second subscript for the next set of output data to be stored.
For example, for the initial set of peak data to be stored, NPEAKS
should be set to zero.
You must set the value of this argument before calling the subroutine;

however, the subroutine can change the value before returning.

NOTE
PEAK returns (assuming there are no errors) after either of
the following events:
1.

All input data elements have been processed.

The output array is filled, and there is another set of
peak data to report.
The arguments INPTR and NPEAKS indicate which

event caused the return and the current status of I/O
processing:

e If

condition

1
occurred then, INPTR=-1
and
IDIMO, that is, the subroutine has set
NPEAKS to the proper value for the next subroutine
NPEAKS=<

call.

o If condition

2 occurred,
NPEAKS=-1 and INPTR
equals the proper subscript value for reentry — one less

than the subscript of the next element to be processed.

If the subroutine is called again with either INPTR or
NPEAKS equal to -1, the subroutine interprets the value
as zero.

2.4

Using the Peak-Processing Subroutine
You can use several inherent features of the peak-processing subroutine to
process data produced in real time. Thus, you may use PEAK in conjunc-

tion with other routines that monitor and digitize real phenomena. The
particular arguments that make possible this real-time application are
INPTR, INLAST, and NPEAKS (see Section 2.3). Let us visualize the input

and output arrays as a series of “pigeonholes”, and INPTR and NPEAKS as

2-20

The Peak-Processing (PEAK) Subroutine

pointers to the next available data element to be processed and the next
slot for outputting data, respectively (Figure 2-10). INLAST is a pointer to

the last INPUT element containing data.
Figure 2-10:

INPTR, INLAST, and NPEAKS Point to Slots

INPUT

INLAST

-—b

INPTR

NPEAKS
MR-S-1609-81

The subroutine returns when all data in the input buffer have been

processed, that is, INP
= INLAST,
TR or the output array 1is filled, whichever
occurs first. If all data in the input buffer have been processed, INPTR
will
equal -1 and NPEAKS will point to the last slot (subscript) in the output
array that was filled. If, conversely, all slots in the output array have
been

filled, NPEAKS=-1 and INPTR points to the last element (subscrip
t) in
the input array that was processed. Neither is an error condition, and
neither is more advantageous outside the context of your specific application.

These conditions give you great flexibility in handling subroutine input
and output. When you have large quantities of data to process, you need
not

allocate space for all data at once because the subroutine is designed
to

process a given data set in sequential parts. In fact, all data
need not be

known before processing begins, as is true in real-time processing. Data
can
be asynchronously collected into one buffer at the same time that a
previously collected buffer is processed.

Handling of output is also flexible. It might, for example, be printed
or
stored after each return from the subroutine, or it might be further pro-

cessed only when the output buffer was filled, that is, NPEAKS=-1.

You

Further flexibility is introduced by the fact that all arguments in the

call-

may choose the procedure that is most convenient for you.

ing statement except ITABLE can be changed between successi

ve calls to

the subroutine to reflect the origin of the remaining input data
and where
the output is to be stored. ITABLE must not be tampered with during
the
intervals between calls for a given data stream because it contains
the

current information needed to resume processing at the point
where processing was stopped on the previous call.

The Peak-Processing (PEAK) Subroutine

2-21

The subroutine is position-independent and reentrant. Althoug
tures are of interest mainly at the system level, they do

h these fea-

result in additional

advantages at the user level. Perhaps most significant is the possibili
ty of
processing several data streams simultaneously. All pertinen
t information
concerning the history of a data stream is contained
in the ITABLE array
rather than in the code for the subroutine. Imaginative use
of the arguments in the subroutine call should make the subroutine function
ally compatible with any application that uses the peak-processing algorith
m.

2.5

Modifying the Subroutine — Using Options
The following sections explain which options you can use with the

peak-

processing subroutine. If you want to use any of the options,
you must
enable them when you build the subroutine from the source file using
the
interactive build procedure (see Section 1.1).

2.5.1

EIS (Extended Instruction Set)

Enable this option if your installation has EIS (KE11-E) hardware
or any
other floating-point option available. Enabling this option increase
s the
execution speed and decreases the memory requirements for the subrouti
ne
by approximately 139 words if AUTOGS$ or DPP$ is enabled or by approximately 129 words if AUTOGS$ or DPP$ is not enabled.

2.5.2

EAE (Extended Arithmetic Element)

Enable this option if your installation has EAE (KE11) hardware available.
Enabling this option increases the execution speed and decreases the
memory requirements for the subroutine by approximately 87 words.

2.5.3

AUTOGS (Autogaining)

Enable the autogaining option only if you have a bipolar 12-bit A/D converter supplied by DIGITAL that has four, program-selectable gain values:

1, 4, 16, 64. The converter has optional features that allow the dynamic
range to collapse under software control as the analog signal being moni-

tored approaches zero volts. This feature effectively increases the resolution

of the converted value as the analog signal becomes weaker.

Autogaining allows you to magnify the analog signal by a factor of one of

these gain values, so that the resulting converted value becomes as signifi-

cant as possible without causing an overflow. As an example, once a signal

decreases (in absolute value) to a voltage 1/4 the maximum convertible
voltage at a gain of 1, the gain is increased to 4. Thus the full digital range

of the converter is implemented. As the real voltage of the analog signal

continues to decrease in absolute value, the software increases the gain
appropriately.

2-22

The Peak-Processing (PEAK) Subroutine

It should be pointed out, however, that while the resolution of the converted

values increases, some analog signals differing exactly by magnifications
of
4, 16, or 64 continue to be represented by the same 12-bit number.
To

distinguish values converted at different hardware gain settings, the autogaining software sets two additional bits in words that contain
the converted values. These are bits 12 and 13, which indicate the gain value
for a
particular datum, as follows:
Gain Value Used

Bit 13

Bit 12

for Conversion

When the peak-processing subroutine is assembled to process data
using the autogaining algorithm, input data must still be positive;

collected

negative
values are set to zero. A characteristic of the bipolar converte
r used in
autogalning is to represent converted values in the range
mum positive voltage as 40004 to 7777,, and those in the

of zero to maxirange of zero to

maximum negative voltage as 3777, to 0000,.

To deal with all converted values in their proper relation
normalizes them before processing begins; all values are

, the subroutine

effectively represented as if sampled at a gain of 64. For example, all values
sampled at a
gain of 1 are multiplied by 64; those sampled at a gain of 4
are multiplied
by 16, and so on. Consequently the resulting heights and
areas are increased by a factor of 64 over those produced by samplin
g and processing

the same analog signal with a gain of 1 (no gain).

Multiplying a 12-bit number by 64 results in an 18-bit number,
which is a
double-precision word. Consequently:

e The size of the required code increases by approximately
® You must increase the dimension of ITABLE, the first

call to PEAK, from 68 to 79.

195 words.

argument in the

¢ You must set another element in ITABLE:

ITABLE(8)=0
=1

input data not autogained
1nput data autogained

By using this parameter, input that is not autoga
ined can still be

processed.

® You should select ITABLE(3) and ITABLE(4) with

an awareness that all
data processed can be as much as 64 times more sensitive than
if collected
with a gain of 1. For instance, if two values differ by one
when collected
at a gain of 1, they could be interpreted as differing
by as much as

when their values have been normalized.

The Peak-Processing (PEAK) Subroutine

2-23

2.5.4

DPPS$ (Double Precision Integers)

If the upper range of data points to be processed exceeds 32767 but is less

than 33554431 decimal (2*°-1), you must enable this option. If you enable
this option, all input data can be double precision integer, that is, the
second argument in the FORTRAN call statement, INPUT, can be an
INTEGER*4 array (or equivalent). Consequently:

e The size of the required code increases by approximately 195 words.
® You must increase the dimension of ITABLE, the first argument in the

call to PEAK, from 68 to 79.

e You must set another element in ITABLE:

ITABLE(8)=0

input data single-precision

1nput data double-precision

2.5.5

NOFLTS$ (No Filter)

This option disables the software digital filter that the subroutine normally
uses. Enable this option if you want to average and process data points
without filtering them, or if you want to apply your own filter to the raw

data before calling the PEAK subroutine.

Enabling the no filter option results in quicker processing of data points
and decreases the size of the subroutine.

2.6

Examples Using the PEAK Subroutine
The four examples presented here process the same waveform — the sum of

four Gaussian curves — represented by the identical 1024 points. The vari-

able input parameters are likewise the same for both examples, and the
resulting output is printed on the terminal. Figure 2-11 is a graphic repre-

sentation of the input data.

Figure 2-11:

Actual Plot of the Input Data

MR-S-1610-81

2-24

The Peak-Processing (PEAK) Subroutine

PEAK Example #1

Example 1 is idealized in several respects. Normally you will not know that
the input array will be empty upon return from the subroutine or that the

output array had sufficient room for all output data. You must therefore
provide for these possibilities by checking INPTR and NPEAKS. Also,
no
provision is made for error checking because the input and output
are
known and the program has been debugged with respect to these types
of
errors. In practice, ITABLE(6) should always be checked.

This type of example was chosen to illustrate 1) minimal requirements for
implementation and 2) how the subroutine and its parameters affect
a
given set of data.

In Example 1 the data are input as four 256-point parts; the subroutin
e
processes each part as it is received, placing the results in the output
array,

which is large enough to accommodate the complete set of processed data.
Upon return from the subroutine, the input array 1s always
(INPTR =-1) and the output array is never filled (NPEAKS
# -1).

The Peak-Processing (PEAK) Subroutine

empty

2-25

O OO

PEAK Example #1
DIMENSIDNINPUT(ZSB),OUTPUT(lO,B):EMU(&),SIGMA

(Q):SIZE(a)

DIMENSION ITABLE(BB) sUTYPE(Z2,2)
DATAVTYPE/

VA’ ,'LLEY','BASE’,'LINE’/

DATA EMU/20, 47043800, ,1000,/

DATA SIGMA/204

10,4200, ,100,/

DATA ITABLE/1+2+3+1+1+63%0/

DATA

INLASTyINPTR»IDIMO 'NPEAKS/256

013 ,0/

\/ =

(A} "C) 1

DO 3 K=1,4

(<)

DO 1

I=1,256

A=0,

K=K+1,
rd

DO
2 J=1.4
A=A+STZE(J)
*EXP (-,

S*#((X-EMU(J))/SIGMA
) *%2)
(J)

Jolok

INPUT(I)=A

CALL

PEAK(ITABLE »INPUT »INLAST ,INPTR ,OUTPUT +IDIMO

NPEAKS)

CONTINUE
TYPE 900
g00

FORMAT(1H1,T24
) 'PEAK ExampPle #1'//)

TYPE 1000
1000

FORMAT (*

PEAK NO. ‘' 48Xy "AREA ' 414Xy 'P

"LHEIGHT " »BX

TIME'

‘T TIME
' +8X s 'TYPE
'

HEIGHT ' +6¥,'P

/113, "HALF WIDTH’ +d4¥,’'T

TIME ‘ ,4Y ,
HEIGHT ‘' ,6Y ,

+8X'RATE
'/ /)

DO 4 L=1)NPEAKS
KK=0UTPUT(9,L)+1

4
2000

TYPEZOOO:(L:(DUTPUT(I;L),I=1,8)9(UTYPE(K»KK):K=1,2
),OUTPUT(IOoL))
FORMAT (I9,SF12
9% 3F12,.044%
.04/
2A4,F12,0)

END

2-26

The Peak-Processing (PEAK) Subroutine

60 00
©

Define array variables and their size.
VTYPE is used to print a word describing how the peak ended (TYPE).

Arrays EMU, SIGMA, and SIZE are used to produce the waveform to

be processed, which is the sum of four Gaussian curves,

Data statements initializing the variable input parameters to the
algorithm (ITABLE) and the arguments for the call to PEAK.

Section producing values that represent the waveform: as X increases

,
the next 256 values are calculated and PEAK is called. Four waveform

segments are produced.

Each time 256 values are produced, PEAK is called.
ITABLE is not affected by the program but is used by the subroutin

INPUT contains the input data; actual values change each time PEAK
1s called.

INLAST is the subscript of the last element in INPUT that

data; always 256 in this example.

contains

INPTR is either O (initially) or -1; subroutine looks for data to
start in
the first element in the INPUT array.

OUTPUT is the array where data for each peak is stored; space
is
allocated to accommodate all data produced: argument remains
unchanged by program.
IDIMO specifies the number of sets of peak data that can be
stored
before the OUTPUT array is filled.
NPEAKS specifies the number of sets of peak data produced thus
far;
because results are known, no check is made for a full conditio
n with

respect to the output array.

Loop for each of four sections of waveform. All elements of
INPUT
array are processed (INPTR=-1), but OUTPUT
array still has room

(NPEAKS<IDIMO).

This section types the results on the terminal.

The Peak-Processing (PEAK) Subroutine

2-27

Terminal output with digital filter enabled:
PEAKR Example
PEAK

NO.

AREA

P HEIGHT

P TIME

HALF WIDTH

L HEIGHT

L TIME

T HEIGHT

T TIME

TYPE

RATE

35795,

951,

19,

692,

12,

345,

23,

11803,

BASEL INE

451,

G8.

343,

o4,

a1,

93,

BASELINE

134928,

299,

096,

124,

13,

106,

200,

845,

VALLEY

Terminal output with No Filter option enabled:
PEAR Example

PEAK NO.

AREA

P HEIGHT

P TIME

HALF WIDTH

L HEIGHT

T HEIGHT

L TIME

T TIME

TYPE

RATE

38147,

953,

19,

GO8.

14,

1.,

342,

od.,

BASELINE

11835,

4354,

68.

342,

od
.,

a1,

93.

BASEL INE

132652,

300,

297,

14,

117,

106,

201,

831,

VALLEY

2-28

The Peak-Processing (PEAK) Subroutine

PEAK Example #2

Example 2 is also idealized because the input and output are known and

the program has been debugged. Therefore no error checking is done. The
variable input parameters (ITABLE) are set to the same values and in the
same manner as in Example 1.

All input for this example is presented to the subroutine in one large array.

However the output array is large enough for only one set of peak data.
Thus each time the subroutine returns to the main program (except
for the
last return), the output array is full (NPEAKS =-1) but the input array
has
not been completely processed (INPTR
# -1, <INLAST). On return from the
subroutine, the data in the output array must be further processed
(in this
example printed on the terminal) before another call is made to the
subroutine to process input data.

The Peak-Processing (PEAK) Subroutine

2-29

RO NROIOLC;

PEAK Example #2
DIMENSION INPUT(1024) ,OUTPUT(10) ,EMU(4) »SIGMA(A)
,SIZE(Y)
DIMENSION ITABLE(GB) »UTYPE(2,2)
DATAVUTYPE/"

WA’ ,'LLEY’,'BASE’,'LINE
"/

DATAEMU/20.

70,1600, 41000,/

DATASIGMA/
410, 4,200,
Z0,
,100,/
DATA SIZE
400,
/9S0
4300, 4200,/
.
DATA ITABLE/14+2+3+1
41 y63%#0/
DATA

INLAST»INPTR,,IDIMO INPEAKS/1024,0,1,0/

L=0

TYPE 900
900

G) 1000

FORM
(1H1 ,T24,
AT
'PEAK Example #2'//)
TYPE 1000

FORMAT ('

PEAK NO. ',

‘T TIME' »8X s

HEIGHT

DO 1

"AREA

»dX»

HEIGHT " 48X+ 'P

TIME ’ 4%,

X9’LTIME'9/911X»'HALFNIDTH':QK:’THEIGHT'r

'TYPE ' 8%, 'RATE’'/ /)

I=1,1024

A=0,

"=l
D0 2 J=1.+4

A=A+STZE
(- . S*((X-EMU(
(J)*
J))/SIGMA(
EXP
J) ) #%2)
1

INPUT(I)=A

CALL

PEAK(ITABLE

INPUT yINLAST,INPTR »OUTPUT,IDIMO 'NPEAKS)

IFCINPTR.LT.O.AND.NPEAKS,EQ.0)
STOP

L=L+1

ONNy

—(©—

2000

2-30

KK=0UTPUT(9)+1

TYPE 2000, (L

(DUTPUT(I) »I=1+8) y(UTYPE(K +KK) +K=1+2; »OUTPUT(10))

FORM
(I SF12.04/
AT39X s3F12.04,4X2A4F12,0)

IFCINPTR.GE.O)
GD TO 3

STOP
END

The Peak-Processing (PEAK) Subroutine

® Define array variables and their size.
® VTYPE is used to print a word describing how the peak ended (TYPE).
® Arrays EMU, SIGMA, and SIZE are used to produce the waveform to
®

Data statements initializing the variable input parameters to the
algorithm (ITABLE) and the arguments for the call to PEAK.

QOO

be processed, which is the sum of four Gaussian curves.

Type headings for peak output.
Produce 1024 values representing the waveform.

Call the PEAK subroutine to continue processing the input array. If

the input array is empty and no new peak data are in the output array,

exit.

ITABLE is not affected by the program but is used by the subroutin

INPUT contains data to be processed, some of which may already have

been processed.

INLAST is the subscript of the last element in INPUT containing data;
it is always 1024.

INPTR is always equal to the subscript of the last element in the input

array that was processed. Initially it is zero, but in subsequent calls
it
points to the last element in the input array that was processed when

the output array was filled. The PEAK subroutine manages this
element.

OUTPUT is array where data for each peak is stored. Space
is
available for only one set of peak data. Therefore each time
an
additional set of peak data is available, the subroutine returns to the

main program so that more space can be made available to store data.

IDIMO specifies the number of sets of peak data that can be stored
before the OUTPUT array is filled; it is set to one.

OJC,

NPEAKS is zero (initially), 1 (if one peak was found but the input
was
exhausted), or -1 if two sets of peak data are ready to be reported
.

Print peak data.
If input data is not completely processed, call PEAK again to continue

processing.

The Peak-Processing (PEAK) Subroutine

2-31

Terminal output with digital filter enabled:
PEAK
PEAK NO.

Example

AREA

P HEIGHT

P TIME

L HEIGHT

HALF WIDTH

L TIME

T HEIGHT

T TIME

TYPE

RATE

35795,

951.

19,

G9Z,

345,

o3,

11803,

BASEL INE

451 ,

68.

343.

od.,

a1,

93.

BASELINE

1348928,

299,

296,

13,

124,

106,

200,

845,

VALLEY

Terminal output with No Filter option enabled:
PEAK Example #2
PEAK

NO,

AREA

P HEIGHT

P TIME

L HEIGHT

HALF WIDTH

L TIME

T HEIGHT

T TIME

TYPE

RATE

38147,

953,

19.

608,

14,

342,

od,

BASELINE

11835,

434,

1.,

68.

342,

od.,

a1,

93,

BASEL INE

132652,

300,

297,

14,

117,

106,

201,

831,

VALLEY

2-32

The Peak-Processing (PEAK) Subroutine

PEAK Example #3

Example 3 is almost identical to Example 1. But, because Example 3 pro-

cesses autogained data, the peak-processing subroutine had to be built with

AUTOGS

example 1:

enabled.

Three

changes were made to

the source

code of

In Section 1, the size of ITABLE was increased to 79 elements.

In Section 4, elements 6 and 7 of ITABLE have been set to 0 and
element 8 has been set to 1 to specify autogained data.

In Section 5, each element in INPUT has had 4000 octal added to it to
simulate bipolar zero and 30000 octal added to it to simulate the high-

est gain value possible and to eliminate the need for normalization.

The Peak-Processing (PEAK) Subroutine

2-33

11
R OO

PEAK Example #3
DIMENSION INPUT(256) yOUTPUT(10,3) ,EMU(4) ,SIGMA(U)
»SITE(4)

DIMENSION ITABLE(79) yUTYPE(2,2

DATA VTYPE/"

WA’ ,'LLEY','BASE’','LINE"/

DATAEMU/20, 470,600,

1000,/

DATA SIGMA/20., 410,200, ,100,/
DATA SIZE
4400,
/9S0
4300, 4200,/
.,

DATA ITABLE/ 1424391 41 42%0,1,71%0/
DATA INLAST ,INPTR,IDIMO 'NPEAKS/2S6

0 43,0/

{=0,

DO 3 K=1,4
DO
1 I=1,256

(<)

)

A=0,
R=X+1,
)

100

DO 2 J=1.+4

A=A+STZE(J)*EXP
(-,

)}

INPUT(I)=A+"34000
CALL

S*((X-EMU(J))/SIGMA(J)
) %%2)

PEAK(ITABLE »INPUT »INLAST ,INPTR ,OUTPUT ,IDIMO ;NPEAKS)

CONTINUE
TYPE 900

900

FORMAT(1H1,T24,'PEAK Example #37//)

(o)

TYPE 1000

1000

FORMAT(’ PEAK NO.’ +8X s 'AREA’ 14X, 'P HEIGHT/' »6%
A

'L HEIGHT’

6X+»'L

TIME'

'TTIME'8Xy'TYPE'

/111X,

‘P TIME' ,4Y%
,

HALF WIDTH’ »4X,'T HEIGHT
’ ,6Y ,

8BXs'RATE'//)

DO 4 L=1/NPERKS

KK=0UTPUT(9,yL)+1
4

2000

TYPE 2000, (L »(OUTPUT(I L) +1I1=1+8) s (UTYPE(K

END

2-34

KK) yK=1,+2) yOUTPUT(10,L))

FORMAT(IOS
49X 13F12,044%y2A
F12.0
4,F12.,0)
4/

The Peak-Processing (PEAK) Subroutine

Define array variables and their size.
VTYPE is used to print a word describing how the peak ended (TYPE).
Arrays EMU, SIGMA, and SIZE are used to produce the waveform to

©®

be processed, which is the sum of four Gaussian curves.

Data statements initializing the variable input parameters to the
algorithm (ITABLE) and the arguments for the call to PEAK.

Section producing values that represent the waveform: as X increases,
the next 256 values are calculated and PEAK is called. Four waveform

segments are produced.

Each time 256 values are produced, PEAK is called.
ITABLE is not affected by the program but is used by the subroutine.
INPUT contains the input data; actual values change each time PEAK
1s called.

INLAST is the subscript of the last element in INPUT containing data;
always 256 in this example.

INPTR is either O (initially) or -1; subroutine looks for data to start in
the first element in the INPUT array.

OUTPUT is array where data for each peak is stored:; space 1s allocated

to accommodate all data produced; argument remains unchanged by
program.

IDIMO specifies the number of sets of peak data that can be stored

before the OUTPUT array is filled.

NPEAKS specifies the number of sets of peak data produced thus far;

because results are known, no check is made for a full condition with

respect to the output array.

Loop for each of four sections of waveform. All elements of INPUT
array are processed (INPTR=-1), but OUTPUT array still
has room

(NPEAKS<IDIMO).

This section types the results on the terminal.

The Peak-Processing (PEAK) Subroutine

2-35

Terminal output with digital filter enabled:
PEAK

r-J

PEAK NO,

Exameple #3

AREA

P HEIGHT

P TIME

HALF WIDTH

L HEIGHT

T HEIGHT

L TIME

T TIME

TYPE

RATE

35795,

951,

190

12,

692,

345,

a’

23,

11803,

BASEL INE

451,

1 ¢

880

343,

od.

a1,

93,

134928,

BASEL INE

299,

296,

1 ¢

124,

13,

200,

845,

106,

VALLEY

1 ]

Terminal output with No Filter option enabled:
PEAK Example

NO,

PEAK

2-36

AREA

P HEIGHT

P TIME

HALF WIDTH

L HEIGHT

T HEIGHT

L TIME

T TIME

TYPE

RATE

38147,

953,

19,

14,

608,

342,

od.,

11835,

BASELINE

434,

68,

342,

o4,

BASEL INE

a1,

93,

132652,

300,

297,

117,

14,

201,

106,

831,

VALLEY

The Peak-Processing (PEAK) Subroutine

PEAK Example #4

Example 4 is almost identical to Example 3. But because Example 4 pro-

cesses double precision input data, the peak-processsing subroutine had to
be built with DPP$ enabled. Four sections of Example 3 were changed:
1.

In Section 1, INPUT was changed to a double precision integer array
and some additional elements were defined for the purpose of generat-

ing the input data.
2.

In Section 3, the values of the parameters used to produce the input
waveform for PEAK were changed to yield double precision values.

In Section 4, ITABLE(5) was changed to -1 so that the output would be
given in double precision, floating-point values.

In Section 5, the algorithm to calculate the input to PEAK was changed
to produce double precision integer values.

The Peak-Processing (PEAK) Subroutine

2-37

1’ FOR O —O

PEAK Example #4
REAL*B OUTPUT(10,3) yEMU(4) ySIGMA(4) ySIZE(4) yA 4B
s
INTEGER TEMP(512)

DIMENSION ITABLE(79) yUTYPE(2,2

INTEGER*4 INPUT (256)
EQUIVALENCE (TEMP,INPUT)
DATA B/B5536.D0/

DATA VTYPE/’

WUA’,'LLEY’','BASE’,'LINE"/

DATA EMU/20.D0+70.,D0,600,D0,1000,D0/
DATA SIGMA/20.,D00,10,D0,200,D0,100,D0/
DATA SIZE/950.D3+400,D3,300,D3,200,D3/

DATA ITABLE/1+2
41 +-142%041,71
+3
%0/
DATA INLAST,INPTR»IDIMO

NPEAKS/256 /0,3 ,0/

X=0,D0

DO 3 K=1,4

DO11I=2,512,2
A=0,D0
X=X+1.DO
TM~

DO 2 J=1.,4
A=A+STZE(J) *DEXP(-,SDO*((X-EMU(J))/SIGMA(J)
) %%2)
TEMP(II)=A/B

C=A-B*TEMP(II)

IF(C.GE.32768.D0)

TEMP(II1-1)=C-B

IF(C.LT.32768.D0)

TEMP(II-1)=C

CONTINUE

CALL

PEAK(ITABLE

INPUT »INLAST,INPTR »OUTPUT,IDIMO

NPEAKS)

CONTINUE
TYPE 900

900

FORM
»T24+
AT(1
'PEAK ExampleH1
#4'//)
TYPE 1000

1000

FORMAT (*

PEAK NO. ' +8X»'AREA’ +d4X

"LHEIGHT " 46X

‘TTIME

P HEIGHT ' +GX+'P

TIME' v/ +11X» "HALF WIDTH' y4%

‘T

TIME ' +4¥,
HEIGHT ’ 46

+8Xy'TYPE’ +8Xy'RATE'//)

DO 4 L=1,+NPEAKS
KK=0UTPUT(9,L)+1
4

2000

2-38

TYPE 2000, (L

(OUTPUT(I L) +»I=1,+8) 1 (UTYPE(K

KK) »K=1,+2) ,0UTPUT(10,L))

FORMAT(I9SF1
39X 93F12,044X12
2,0+9/
A4F12,0)

END

The Peak-Processing (PEAK) Subroutine

® Define array variables and their size.
® VTYPE is used to print a word describing how the peak ended (TYPE).

Arrays EMU, SIGMA, and SIZE are used to produce the waveform to

Data statements initializing the variable input parameters to the
algorithm (ITABLE) and the arguments for the call to PEAK.

be processed, which is the sum of four Gaussian curves.

® Section producing double precision integer values that represent the
waveform: as X increases, the next 256 values are calculated and
PEAK is called. Four waveform segments are produced.

Each time 256 values are produced, PEAK is called.
ITABLE is not affected by the program but is used by the subroutine.
INPUT contains the double precision input data; actual values change
each time PEAK is called.

INLAST is the subscript of the last element in INPUT containing data;
always 256 in this example.

INPTR is either O (initially) or —-1; subroutine looks for data to start in

the first element in the INPUT array.

OUTPUT is array where data for each peak is stored; space is allocated

to accommodate all data produced; argument remains unchanged by
program.

IDIMO specifies the number of sets of peak data that can be stored

before the OUTPUT array is filled.

NPEAKS specifies the number of sets of peak data produced thus far;

because results are known, no check is made for a full condition with
respect to the output array.

@ Loop for each of four sections of waveform. All elements of INPUT
array are processed (INPTR=-1), but OUTPUT array still has room

(NPEAKS=<IDIMO).

This section types the results on the terminal.

The Peak-Processing (PEAK) Subroutine

2-39

Terminal output with digital filter enabled:
PEAK Example #4
NO.

PEAK

AREA

HALF WIDTH

P HEIGHT

P TIME

T HEIGHT

L HEIGHT

T TIME

L TIME

TYPE

RATE

32158219,

952958,

11,

20,

483071,

693113,

4522958,

BASEL INE

10732416,

a4,
68.

344193,
BASEL INE

1.,

o4,

189827,

134705883,

830

300062,

BOO,

119,

201630,

14923,

839.

107,

VALLEY

Terminal output with No Filter option enabled:
PEAK Examprle #4
NO,

r-J

PEAK

2-40

AREA

P HEIGHT

HALF WIDTH

P TIME

T HEIGHT

L HEIGHT

T TIME

L TIME

TYPE

RATE

35898677,

954478,

13,

20,

398766,

608373,

10745955,

a8.

4534131,

BASEL INE

68.

342397,

83,

24,

134706424,

1890897,
300068,

BASEL INE

119,

GO0,

201624,

14877,

839,

107,

VALLEY

1.,

The Peak-Processing (PEAK) Subroutine

ENVELOPE-PROCESSING (NVELOP) Subroutine
FORMAT:
CALL NVELOP(ITABLE,INPUT,INLAST,INPTR,OUTPUT,IDIMO,NPEAKS)

Where:
ITABLE

‘

1s a 51l-element integer array.

ITABLE(1) = number of additional values supplied
ITABLE(2)

gate parameter

ITABLE(3)

baseline value indicator

ITABLE(4)

output data type

ITABLE(5)

error indicator

ITABLE(6)

reentry pointer

INPUT

1s an integer array containing input data.

INLAST

1s an integer variable specifying subscript of last data element
in INPUT processed.

INPTR

is an integer variable specifying subscript of last element in
INPUT processed.

OUTPUT

is a double-subscripted array used to store output data.
OUTPUT(1,N)

ending indicator, Nth peak

OUTPUT(2,N)

area, Nth peak

OUTPUT(3,N)

centroid, Nth peak

OUTPUT4,N)

width, Nth peak

OUTPUT(,N)

crest time, Nth peak

OUTPUT(@6,N)

crest height, Nth peak

OUTPUT(7,N)

Ileading minimum time, Nth peak

The following elements appear if ITABLE(1)=1 or 2.
OUTPUT(8,N)
OUTPUT@,N)

first additional value preceding current

envelope
second additional value preceding current envelope

IDIMO

is an integer variable 'specifying number of peak data sets that
can be stored in OUTPUT.

NPEAKS

is an integer variable specifying number of peak data sets al-

ready stored in OUTPUT.
FILE NAMES:

FNVLOP.MAC (source file); FNVLOP.OBJ (object file)
OPTIONS:
@

EIS

(Extended Instruction Set — KE11-E)

EAE

(Extended Arithmetic Element — KE11)

APPROXIMATE SIZE OF SUBROUTINE (IN WORDS):
If the following options are enabled:
NONE | EIS | EAE
669

620 | 644

TYPICAL EXECUTION SPEED:

With PDP-11/34 and EIS enabled:

4300 Points/second.

With PDP-11/03 and EIS enabled:

2000 Points/second.

Chapter 3
The Envelope-Processing (NVELOP) Subroutine

This subroutine detects significant fluctuations, called peaks,
in sets of
data. These data represent discontinuous segments, or envelope
s, of a

waveform (Figure 3-1). The envelopes are chosen arbitrari
ly, but they
should be presented sequentially to the original waveform.

Figure 3-1:

Envelopes of Data (may contain more than one peak)

[
Beginning
of First
Envelope

Height

;

Beginning of
New Envelope

ANFirst Envelope
N to be Processéa N

,//

’/’

\
NN

]

Time

Between Envelopes
Time

—

Each envelope is represented by a series of discrete positive integers

sponding to values of a waveform at evenly spaced interval

MR-S-1612-81

corre-

s. For the result
of applying the algorithm for this subroutine to be correlat
ed with the
overall waveform, you must supply the distances (elapsed
times) between
envelopes. You can also supply as many as two addition
al data values for
related functions at the critical point where a new set of envelope
data
starts.

3-1

The subroutine reports definitive characteristics for all peaks found;

output
is the area, width, and centroid for each peak, as well as the height
and
time of its crest. The time at which each peak starts and where
it ends — at
envelope termination or at a valley — is also reported. The addition
al values supplied at the start of a new envelope are reported with
each peak

detected in that envelope.

3.1

Definition of Basic Terms and Conventions
It is important to understand how some of the terms and

scribing the

conventions deNVELOP subroutine are used throughout this chapter.

® The term data stream describes all values presented to the subrout
processing.

ine for

e Data values that represent the peak being processed are referred

to as
heights, for example, crest height is the maximum data value for a given

peak.

e The duration axis of the waveform is the time axis, for example

, the time
at which an envelope begins is the leading time of a peak. Time is
measured as the number of input values processed since input began.

e Point-to-point changes are local changes, as contrasted with
overall
changes during the course of a waveform, which are trends.

e Changes are persistent in one direction if the number of changes in that

direction exceeds the number in the opposite direction.

e “Noise” is a generic term for all distortion-producing components in the
input data.

3.2

The Envelope-Processing Algorithm
The

envelope-processing

algorithm detects increasing and decreasing
trends (which may define peaks) in a set of data representing a segment
of
a waveform. OQutput from the subroutine is directly related to the times
at
which the envelope begins and ends and the points where changes in the
Increasing/decreasing trends take place. We define the point where an envelope begins or where a subsequent increasing trend appears as the

leading minimum of a peak. A point where the data first show a decreasing

trend preceded by an increasing trend is called the crest of a peak. Each
peak ends either at the end of an envelope or at the start of a new peak (at a

valley).

A functional description of how the algorithm applies to each envelope of
data follows; details of how the envelope is defined are presented in Section

3.3, which describes the input stream.

3—2

The Envelope-Processing (NVELOP) Subroutine

3.2.1

The Baseline Value

A baseline value for the waveform data can be either the first element in

the input data stream or the third parameter in the input parameter table

(Section 3.3). Setting this baseline value is intended to be a mechanism for

eliminating the “constant” noise level inherent in input data: it should
therefore be less than any of the waveform data values to be processed.

This value is subtracted from each data value before the trend-detection
portion of the algorithm is applied. If the result of this subtraction is negative, it is treated as a zero.

3.2.2

Trend Detection — Application of the Gate Factor

Data points may exhibit slight point-to-point fluctuations unrelated to the
dominant trend of the data. You may eliminate much of this undesirable

fluctuation by selecting an appropriate gate factor. The gate factor specifies

a valid directional trend in terms of the number of either persistent or
consecutive changes in direction over a series of input data points.

At points where a peak begins or where a crest is detected, neither an
increasing nor a decreasing directional trend has yet been established. The
next current trend is the first direction in which the data change “gate”

number of times.

At intermediate points current trends are already established. Changes in

directional trend at these points can be established only if the number of
consecutive local changes in the new direction is equal to the gate factor.

A local change is defined in terms of the relation between a given data
point and the local minimum and maximum. If the current height is less

than the local minimum, the change is downward, and conversely, if the

height is greater than the local maximum, the change is upward. If the
height is between the local minimum and maximum, no change is indicated
(although the area and centroid are updated).

At points of trend change, such as the beginning of a peak or its crest, the

local minimum is set to a very high value and the maximum to a very low
value. Between points of trend change the local minimum and maximum

can be best described by the flow diagram.

It should be stressed that the points of greatest interest on the waveform —
essentially the points that determine the peak — are found at the points of

trend change, the beginning of the peak and its crest. This test is the heart

of the algorithm.

3.2.3

The Width of a Peak

Peak width is measured as elapsed time between its start and the end of the

peak or the end of the envelope. Time is measured in units of distance
between input data values; therefore peak width is the count of the number

of input data values that describe the peak.

The Envelope-Processing (NVELOP) Subroutine

3-3

Operation of the gate factor makes it imperative that at least “gate”
number of data values be recorded on either side of the crest before
a peak is
detected; that is, the width of each peak must be at least twice
the gate

parameter. The single exception is a peak that ends because
the envelope
terminates; the width of such a peak must be at least six!
for it to be
reported. The gate factor is not involved, and the output data
are reported
even if no crest has been detected.

3.2.4

Calculating the Area of a Peak

The area under a peak is found simply by summing the correct
the peak. Thus if the width is N,X; represents the ith input

the peak, and BAS is the baseline value

ed points on

data point on

AREA =

X;-BAS

i=1

3.2.5

Calculating the Centroid of a Peak

The centroid is the time axis component of the two-dimensiona

l center of
mass of a peak. It is calculated as the sum of the products
of the current
time and corrected points, divided by the area of the peak. Thus
if T, represents time of input of the ith data point, and other symbols
are as defined in

Section 3.2.4, then

CENTROID =

> T, - (X,- BAS)/ AREA
i=1

The centroid is the best approximation of the real position of the peak
respect to the entire waveform.

3.2.6

with

Flow Charts for the NVELOP Subroutine

The series of flow charts in Figures 3—-2 through 3-8 gives detailed logic

for
NVELOP subroutine. Supplementary information is presented in
Tables 3—1 and 3-2. Table 3-1 defines the symbols used in the flow
charts
and accompanying explanations; Table 3-2a reviews and summarizes flowthe

charted events and associated waveform phenomena as they relate to data

on possible peak configurations:

e A peak starting and ending at the boundaries of an envelope
» A peak starting at the beginning of an envelope and ending at a valley
e A peak starting at a valley and ending at the termination of an envelope

1 An arbitrarily chosen number that is twice the nominal gate factor; it is part of the
algorithm and therefore may not be changed without modifying the code.

3—4

The Envelope-Processing (NVELOP) Subroutine

Table 3-2b presents significant data-collection events on your part as they

relate to a waveform like that presented in Table 3—2a.

Note that the flow charts and accompanying illustrations and examples
assume that you impose an arbitrary threshold value to delimit data envelopes to be processed.

Table 3-1:

Definitions of Symbols Used

BAS

Baseline height'

NEW

Crest height’

NOFC

Next input value (height)

Number of extra values recorded

at beginning of new envelope'
Cl

Crest-found indicator

Partial area accumulated during
Increase

Time of crest height®

Partial centroid accumulated durIng increase

Counter for number of per-

Total area summation®

Total centroid summation®*

TTM

Local time

True time

Time of start of envelope

sistent decreases in height

Trend indicator (decreasing)
1

decreasing

not decreasing

Number
creases

of
or

persistent

decreases

inbe

considered a valid change in

trend’
IC

Counter for number of persistent increases in height

Trend indicator (increasing)
1

increasing

not increasing

LMT

Time of start of peak’

Width of peak®

Current minimum height

Large value

First extra value recorded”"

Current maximum height

Second extra value recorded”’

Time of current maximum

Type

0 Peak ends at end of envelope

MX
MXT

height

1 Peak ends at valley2

1 Value set by user
2 Value reported by algorithm
3 Value can change during peak detection; reported values are those that are current when
the end of the peak is detected.

The Envelope-Processing (NVELOP)
Subroutine

3-5

Figure 3-2:

Flow Chart for Envelope Processing; Data Entry

Indicate Error
if Possible

Set Negative
Pointers to Zero

Y
Go to IRESUM
|

Go to ORESUM

Put it in
Parameter Table

]

initialize True Time

MR-S-1613-81

3—6

The Envelope-Processing (NVELOP) Subroutine

Figure 3-3:

Flow Chart for Envelope Processing;
Initialization, Calculation of Peak Width,

and Finding End of Envelope

Call NEXTPT
Clear Crest-Found Indicator
Clear Partial Area Accumulated
During Increase
Clear Partial Centroid
Accumulated During

NEW = Value
Returned|

Increase

Is This the End of the Envelope?

Clear Local Time
Set Time of Start of Peak

Calculate Width of Peak
Clear Crest Height
Clear Crest Time
Clear Total Centroid
Clear Total Area

WD =TT-LMT

Is Current Peak Large Enough
to Report?

Set Current Minimum Very High
Set Current Maximum Very Low
Clear Counter for No. of
Persistent Decreases

Clear Counter for No. of
Persistent Increases
Set Current Trend to Decreasing
Clear Increasing Trend Indicator

Peak Ends at End of Envelope
Record Information

Type=1

Call RITOUT

Ci=0
PA=0
PC=0
TM=0
LMT=TT
+1

Get Next Input Value

N101

MR-S-1614-81

The Envelope-Processing (NVELOP) Subroutine

3-7

Figure 3—4:

Flow Chart for Envelope Processing;

Count of Reject Points and Reading Additional Values

where Envelope Begins

!
Call NEXTPT

Get Double-Precision Time of Rejected Data

TT =TT + Values JUpdate True Time to Include Period of Data
Returned
Rejection

Start of Envelope

o @

Are There Extra Values when Envelope Begins?

Yes

Call NEXTPT

Get and Store First Extra Value

X1 =Value
Returned

Are There Two Extra Values?

Yes

Call NEXTPT

Get and Store Second Extra Value

X2 = Value
Returned

|
MR-S-1615-81

Figure 3-5:

Flow Chart for Envelope Processing;
New Minimum and Crest Detection

EW=NEW-BA

Increment Local
Time
increment Total
Time
Subtract Baseline
Height from
Height of Next
Point

Does the Decrease

Counter Exceed
Minimum (Gate)?

Yes‘

Is Current Trend

Yes

NEW=0

ina?
Increasing?

Is New Height >
Baseline”

Set Trend Indicator
DI =

IC _ 0
MX
= —XL

Is New Height Current Minimum
Height?

MN =NEW
DC=DC+1
TC=TC+PC+TM*NEW

to Decreasing

Clear Increase
Counter

Set Current
Maximum Very Low

Reset Minimum
Increment Decrease

Counter
Update Total
Centroid
Summation
Update Total Area
Clear Partial
Centroid
Summation
Clear Partial Area

CREST DETECTED
.

CH =MX
CT=MXT

Save Crest Height
Save Crest Time

MR-S-1616-81

The Envelope-Processing (NVELOP) Subroutine

3-9

Figure 3-6:

Flow Chart for Envelope Processing; New Maximum;
Peak Begins at Valley

Is Current Trend
Decreasing?

PA=PA+NEW
PC=PC +TM*NE

Update Partial Area
Update Partial Centroid
Yes

Set Trend Indicator
=1

to increasing, not
Decreasing

Is New Height:~Current
Maximum?

Has a Crest Been
Detected Previously?

Yes

MX =NEW
MXT=TT
IC=IC+1

Reset Maximum
Reset Maximum Time
Increment Increase
Counter

Clear Crest-Found

Is Number of Persistent
Increases >Minimum
Needed to Change Trend?

Cl=0
WD =TT-LMT
Type=0

Indicator
Calculate Width of
Peak
Peak Ends at Valley

Record Peak Data

Call RITOUT
DC=0
MN =MX

Clear Decrease Counter
Set Current Minimum
to Maximum

LMT=TT

Reset Time of Start
of Peak

MR-S-1617-81

3-10

The Envelope-Processing (NVELOP) Subroutine

Figure 3-7:

NEXTPT Subroutine — Envelope Processing

Increment Input Pointer
INPTR=INPTR +1

Any Input Left in INPUT Array?

Set INPTR=-1

Return to
Main Program

Set Next Entry From
Main to IRESUM
(Transparent to User)

INPTR<INLAST

Return to

Subroutine
with Next
Value in NEW
MR-S-1618-81

The Envelope-Processing (NVELOP) Subroutine

3-11

Figure 3-8:

RITOUT Subroutine — Envelope Processing

Subroutine RITOUT
(Not Accessible to User)
Store

TC=(TC/TA)+TO

Do Final
Calculation
for Centroid

Type
TA
TC
WD

CT
CH
LMT

lgfiggment

NPEAKS =

NPEAKS +1

Set Next Entry From
Main to ORESUM
(Transparent to User)

Convert to
e Single-Precision

Floating Point

Pointer

Any Room
Left in
OUTPUT Array?

Set NPEAKS =-1
Return to
Main Program

PUT Array

Store X1 or
X1 and X2
If Necessary

Return to
Algorithm

Floating
Point

Double-

Precision

Convert to
Double-Precision
Floating Point

MR-S-1619-81

3-12

The Envelope-Processing (NVELOP) Subroutine

The Envelope-Processing (NVELOP)
Subroutine

3-13

Table 3-2a:

Envelope-Processing Algorithm

C rest Height #

N\
N \

_Ba_seline

—

i Threshold

_ ///

est Height %

\\
N

//////////////// _

Peak 2

Time ———»

MR-S-1624-81

Point/Section

Flow Chart

of Curve

Description of Event

New envelope begins; look for
1)

Reference

Elapsed time since last data point

processed

(or

beginning of wave-

form) and update current total time
2)

Values other than waveform data,

|TT=TT +time

supplied when new envelope begins;

|last envelope=Db’

since

save values to be output with data

for each peak detected during current envelope

New peak begins; save time of start

b-c

Increasing trend in data; change in established

trend

will

indicate

crest

established;

detect

LMT=TT+1=b"+1

|DI=01II=1
|DC<GT,IC>GT

detection
C

Decreasing

trend

and record crest height and time
c-d

Decreasing trend continues; change in
established trend will indicate end of

|CH=c

CT=c¢
|DI=1]11=0
|DC>GT,IC<GT

peak and start of next peak

Envelope of data ends; peak ends on

|WD=TT-LMT=d'-b’

threshold; calculate width and centroid;

|Type=0

enter peak data into output array

NOTE
The NVELOP subroutine must receive information describing the length

of interval d’-e’. Table 3-2b details this information.
(Continued on next page)

Table 3-2a:

Envelope-Processing Algorithm (Cont.)

Point/Section

Flow Chart

of Curve

Description of Event

New envelope begins: look for

Reference

Elapsed time since last data point
processed and update current total

time

Values other than waveform data,

| TT =TT
+ time

supplied when new envelope begins: |
last envelope
save values to be output with data |
=TT =(e'-d")

since

for each peak detected during current envelope

New peak begins; save time of start
e-f

Increasing trend in data: change in established
trend
will
indicate crest

detection

LMT=TT+1=¢" +1
|DI=0,Il=1

DC<GT,IC>GT

Decreasing trend established: detect
| CH=f
and record crest height and time
CT=f

f-g

Decreasing trend continues: change in
established trend will indicate end of
peak and start of next peak

Increasing

trend

established:

current

peak ends; calculate width and centroid

and enter peak data in output array
Next peak begins; save time of start

g-h

Increasing trend in data: change in es-

tablished

detection
h

h-i

trend

will

indicate

crest

Decreasing trend established: detect
and record crest height and time

|DI=1,I1=0
DC>GT,IC<GT

WD =TT-LMT=g'-¢’

Type=1
LMT =TT =g’

|DI=0,I1=1
DC<GT,IC>GT

|CH=h

CT=h'

Decreasing trend continues: change in |
DI=111=0
established trend will indicate end of
DC>GT,IC<GT

current peak and start of next peak

Envelope of data ends; peak ends on
threshold; calculate width and centroid

and enter peak data into output array

WD =TT-LMT=i'-g’
Type=0

The Envelope-Processing (NVELOP) Subroutine

3-15

Table 3-2b:

How to Compile and Prepare Data for

Envelope-Processing Subroutine
Pertinent

Times

a’

Data Supplied

Description of Event

Start

data

stream;

to the Subroutine

data

threshold

a’-b’

below | None (unless baseline value

entered)

Monitor data and test against threshold | None
value; count number of data samples be-

low threshold (rejected)
b’

Data break threshold; ascertain values | Supply reject count (doubleof auxiliary functions to be input
precision) and additional values (if required)

b’-d’

Data above threshold

Place

each

value

data

stream

d’

Data fall below threshold

d’-e’

Monitor data and test against threshold | None
value; count number of data samples be-

Place zero in data stream

low threshold (rejected)
c’

Data break threshold; ascertain values | Supply reject count (double-

of auxiliary functions to be input

precision) and additional values (if required)

e'-i’

Data above threshold

Place

each

value

data

stream

Data fall below threshold

3.3

Place zero in data stream

How to Call the Envelope-Processing Subroutine
The symbolic name for the envelope-processing subroutine is NVELOP,
and the general format for the FORTRAN call is:
CALL NVELOP(ITABLE,INPUT,INLAST,INPTR,OUTPUT,IDIMO,NPEAKS)

For reference, argument names in the call to NVELOP have been assigned
arbitrarily. You may supply your own argument names, but you must state

all of the arguments explicitly. There are no default values for any of the
arguments. If you omit an argument, either accidentally or on purpose, or if
you supply too many arguments, a FORTRAN error message results and no
data is processed. The arguments are described in the following discussion.
ITABLE is an integer array of 51 elements and is used by the subroutine
to store intermediate results and other information required by the algo-

rithm. You must set the values of the following array elements to
transmit variable parameters and other information to the subroutine.
ITABLE(1)

Number of additional values (no more than two) that you

supply in the data stream each time a set of data for a new

envelope begins. These values are presumably related to,
but not representative of, the waveform being processed.

3-16

The Envelope-Processing (NVELOP) Subroutine

ITABLE(2)

This parameter defines the number of either persistent or
consecutive local changes in one direction needed to estab-

lish a new dominant directional trend. It is the gate para-

meter discussed in Section 3.2.2. In general, suggested
values may range from 2 to 5.

ITABLE(3)

The parameter that indicates the baseline value BAS
(Section 3.2.4) to be used with the waveform data:
If ITABLE(3)=0, it is used as the baseline value.

If ITABLE(3)<O0, the first element in the data stream is
the baseline value; when this value is

detected in the data stream, the subrou-

tine inserts it into ITABLE(3).

ITABLE4)

The element that defines the data type of the output array:
=0

ITABLE(5)

Output is double-precision integer
Output is single-precision real

=-1

Output is double-precision real

The element used by the subroutine to indicate errors in
the calling sequence or input parameters:
=0

Indicates no error
Indicates ITABLE(N) is in error, for example,

ITABLE(1)>2

ITABLE(2)<0
=-N

Indicates the Nth argument is in error or missing; for example, INPTR>INLAST (see the following discussion)

ITABLE(6)

Element that must be set to zero before the initial call to
the subroutine to process a new waveform. When a data
stream 1s processed in parts (see Section 3.4), the subrou-

tine uses ITABLE(6) for reentry to process each subsequent part.

For

this

reason

you

should

not alter this

element until all parts have been processed.
ITABLE(7)

Elements used exclusively by the subroutine while the
data stream is being processed.

ITABLE(51)

INPUT is an integer array containing the raw data to

be processed by the
subroutine. There may be as many as five different types
of data for a
single waveform:

Baseline Value

If ITABLE(3) is nonnegative, this value is omitte
d
from the data stream. If ITABLE(3) is negative, the

first element in the input stream is taken to be the
baseline value to be used; if the baseline value is negative, it is treated as a zero (Section 3.2.1).

The Envelope-Processing (NVELOP) Subroutine

3-17

Reject Count

This double-precision integer provides the elapsed
time, in terms of data samples, between envelopes of

data. Actually it is the count of data values rejected
by the subroutine since the last value of the previous

envelope. Because the array is single-precision integer, two elements are needed for each reject count;
the least significant part (low order) is entered first,

followed immediately by the most significant part
(high order) in the next element. For example, if the

reject count is R, and the subscript for the preceding

element is N:

INPUT (N + 2) = R/ 2"
INPUT (N + 1) = R-(INPUT (N+2)) - 2'°
Keep in mind that R is real, INPUT is integer, and
that fractional truncation takes place when a real
number is equated to an integer.
Auxiliary Values

If ITABLE(1) is zero, no auxiliary values will appear
in the data stream. Otherwise as many as two values,
not representative of the waveform, may be supplied

and associated with each set of data corresponding to
an envelope to be processed. These values may be any

single-precision integers, and there must be as many
as specified in ITABLE(1).
Waveform
Data Values

Heights of the waveform at evenly-spaced intervals
must be supplied for each envelope of data to be pro-

cessed; heights that do not exceed the baseline value

are treated as equal to the baseline value and greater

than zero.
Zero Values

Because all waveform data to be processed must be

greater than zero, detection of a zero value has special significance in that it indicates the end of an envelope (if it is obviously not a baseline value).

The subroutine distinguishes between these various kinds of data in the
input stream on the basis of the order in which they are expected to appear:

__BASELINE VALUE
REJECT COUNT (LOW)

REJECT COUNT (HIGH—

Optional

Time since start of input data

AUXILIARY INPUT VALUE #1 — Optional

AUXILIARY INPUT VALUE #2
Waveform Data Values

_ZERO

As supplied to subroutine

End of waveform data for envelope

The subset of input values designated by the bracket

is repeated for each
envelope of data to be processed until the data stream ends.

INLAST is an integer variable that equals the value of the
last array element that contains data.

subscript of the

INPTR is an integer variable that points to the value

of the subscript of
the last element processed by the subroutine. We may also
think of it as
having a value one less than the subscript of the next datum
in the input

array to be processed. For example, if the first element

be processed, INPTR should be set to zero.

of the array is to

You must set the value of this argument before calling
the subroutine;
however, the subroutine changes the value before returning.

OUTPUT is a double-subscripted array used to store

the results of applying the envelope-processing algorithm. The first dimens
ion specifies the
number of data elements to be output for each peak
detected. There are
always at least seven. In addition the ITABLE(1) auxilia
ry values provided with each envelope are reported for each peak found
in that envelope. The second dimension specifies the number
of sets of peak data
that can be stored by the algorithm while processing
the input data.

Thus the first dimension is 7 + ITABLE(1), and the second
is defined
by IDIMO. Possible data elements reported for each peak
are:
OUTPUT(1,N)

Indicator of how peak ended:
= 0 ended at termination of envelope
= 1 ended at a valley

OUTPUT(2,N)

Area of Nth peak

OUTPUT(3,N)

Centroid of Nth peak

OUTPUT(4,N)

Width of Nth peak

OUTPUT(5,N)

Position of Nth peak (time of crest height)

OUTPUT(6,N)

Height of Nth crest

OUTPUT(7,N)

Starting position of Nth peak (time of leading min-

imum height)

The following elements are optional:

OUTPUT(8,N)

First additional
ITABLE(1)>0)

OUTPUT(9,N)

Second additional value at start of envelope (if
ITABLE(1)=2)

value

at start of envelope

(if

IDIMO is an integer variable that transmits to the

subroutine the second
dimension of the output array. It defines the numbe
r of peaks that can
be reported before the output array is filled.

The Envelope-Processing (NVELOP) Subroutine

3-19

NPEAKS is an integer variable giving the number of sets of peak data
stored in the output array. We may also think of it as having a value of

one less than the second subscript for the next set of output data to be
stored. For example, for the initial set of envelope data to be stored,
NPEAKS should be set to zero.

You must set the value of this argument before calling the subroutine;
however, the subroutine can change the value before returning.

NOTE

NVELOP returns (assuming there are no errors) after either

of the following events:
1.

All input data elements have been processed.

The output array is filled, and there is another set of
peak data to report.

The arguments INPTR and NPEAKS indicate which event
caused the return and the current status of I/O processing:

e If condition 1 occurred then, INPTR=-1 and NPEAKS<
IDIMO, that is, the subroutine has set NPEAKS to the
proper value for the next subroutine call.

e If condition 2 occurred, NPEAKS=-1 and INPTR equals
the proper subscript value for reentry — one less than the

subscript of the next element to be processed.
If the subroutine is called again with either INPTR or
NPEAKS equal to -1,

the subroutine interprets the value

as zero.

3.4

Using the Envelope-Processing Subroutine
You can use several inherent features of the envelope-processing subroutine to process data produced in real time. Thus, you can use NVELOP in

conjunction with other routines that monitor and digitize real phenomena.
The particular arguments that make possible this real-time application are
INPTR, INLAST, and NPEAKS (see Section 3.3).

Visualize the input and output arrays as a series of “pigeonholes”, and
INPTR and NPEAKS as pointers to the next available data element to be

processed and the next slot for outputting data, respectively (Figure 3-9).

INLAST is a pointer to the last INPUT element containing data.
The subroutine returns when all data in the input buffer have been pro-

cessed, that is,

INPTR =INLAST, or the output array is filled, whichever

occurs first. If all data in the input buffer have been processed, INPTR will

equal -1 and NPEAKS will point to the last slot (subscript) in the output

3-20

The Envelope-Processing (NVELOP) Subroutine

array that was filled. If, conversely, all slots in the

filled,

output array have been

NPEAKS =-1 and INPTR points to the last elemen
t (subscript) in
the input array that was processed. Neither is an error
condition, and neither is more advantageous outside the context of your specific
application.
These conditions give you great flexibility in handli
ng subroutine input
and output. When you have large quantities of data
to process, you need not
allocate space for all data at once because the subrou
tine is designed to

process a given data set in sequential parts.
In fact, all data need not be

known before processing begins, as illustrated by

real-time processing; data
can be asynchronously collected into one buffer
at the same time that a
previously collected buffer is processed.
Handling of output is also flexible. It might,
for example, be printed or
stored upon each return from the subroutine or
it might be further processed only when the output buffer was filled,
that is, NPEAKS=-1. You
may choose the procedure that is most conven
ient for you.
Furthermore, you can change all arguments in the
calling statement except
ITABLE between successive calls to the subroutine
to reflect the origin of
the remaining input data and where the output
1s to be stored. You must
not tamper with ITABLE during the interv
als between calls for a given

data stream. ITABLE contains the current inform

processing at the point where processing was

ation needed to resume

stopped on the previous call.

The subroutine is position-independent and reentr
tures are of interest mainly at the system level,

ant. Although these fea-

they do result in additional

advantages at the user level. Perhaps most signifi

cant is that several data

streams can be processed simultaneously.
All pertinent information concerning the history of a data stream is contai
ned in the ITABLE array

rather than in the code for the subroutine.

ments in the subroutine call should make

patible with any application that uses the

Figure 3-9:

Imaginative use of the argu-

the subroutine functionally com-

envelope-processing algorithm.

INPTR, NPEAKS, and INLAST Point to Slots

INPUT

INLAST

-b

INPTR

NPEAKS

The Envelope-Processing (NVELOP) Subroutine

MR-S-1620-81

3-21

3.5

Modifying the Subroutine — Using Options
The

following sections explain which options you can use with the
envelope-processing subroutine. If you want to use any of the options, you

must enable them when you build the subroutine from the source file using

the interactive build procedure (see Section 1.1).

3.5.1

EIS (Extended Instruction Set)

Enable this option if your installation has EIS(KE11-E) hardware avail-

able. Enabling this option increases the execution speed and decreases the
memory requirements for the subroutine by approximately 100 words.

3.5.2

EAE (Extended Arithmetic Element)

Enable this option if your installation has EAE(KE11) hardware available.
Enabling this option increases the execution speed and decreases the memory requirements for the subroutine by approximately 50 words.

3.6

Examples Using the NVELOP Subroutine
The three examples presented here all use the same code and process the
same 1024 data points — the sum of six Gaussian waveforms. The code
compares the composite waveform against a preset threshold value (Figure

3-10) and supplies the results to the NVELOP subroutine. Each time the

input array is filled (256 elements), the subroutine is called to process the
data and place the results in the output array. Upon return from the sub-

routine

to the main program, the input array is always empty
(INPTR=-1), and the output array has never overflowed (NPEAKS # -1).

The code for these examples is idealized in several respects. Normally you
will not know that the input array will be empty upon return from the

subroutine or that the output array had sufficient room for all output data.
You must therefore provide for these possibilities by checking INPTR and
NPEAKS. Also, no provision is made for error checking because the input

and output are known and the program has been debugged. In practice,
ITABLE(5) should always be checked.

This type of example was chosen to illustrate 1) minimal requirements for
implementation and 2) how the subroutine and its parameters affect a
given set of data.

3—22

The Envelope-Processing (NVELOP) Subroutine

Figure 3-10:

Actual Plot of Input Data, Showing Threshold

THRESHOL

MR-S-1621-81

The Envelope-Processing (NVELOP) Subroutine

3-23

NVELOP Example #1

The Envelope-Processing (NVELOP)

Subroutine

3-25

NVELOP Example #1
DIMENSION INPUT

(256) »OUTPUT(7+3) sEMU(B) »SIGMA(B) »SIZE(B)

DIMENSION ITABLE(S1) »UTYPE(3,2)

DATA VUTYPE/
'

VA YLLEY
'+

T'’+'HRES’
» "HOLD '/

DATA EMU/20., ,75.,,200, ,500, ,G00, ,900,/

DATA SIGMA/20. 410, 375,130, 35,4100,/
DATA SIZE/SO0. 100,200, ,800, ,700, ,300,/

DATA IT»IC+X/300:,0,0,/

DATA ITABLE/0 3401 ,47%0/
DATA J»INPTR+IDIMO 'NPEAKS/0 0,340/

DO3I=1,1024
A=0,
X=X+1,

DO 2 JJ=1,46

11—

A=A+STZE(JJ)*E
(- XP
S* ((X-EMU(JJ))/SIGMA(II) ) ##2)
IF(A.LE.IT) GO TO
4
IF(IC.EQ.0) GO TO
6
J=Jd+1

INPUT(J)=1IC
ASSIGN 21 TO IRET

GO 7O 30
21

J=J+1

INPUT (J)=0
ASSIGN 22 TO IRET
GO 70O 30
IC=0

J=Jd+1
IF(I.NE.1) GO TO
7
INPUT(1)=0
INPUT(2)=0
J=3

INPUT (J)=A

ASSIGN
3 TO IRET
GO TO 30

IF(JJ,EQ,O0,OR.IC.NE.O) GO TO 20

J=Jd+1

INPUT(J)=0
ASSIGN 20 TO IRET
GO TO 30

IC=1C+1

CONTINUE

IF(J.EQ.0) GO TO 10

ASSIGN 10 TO IRET

IF(J.NE.256.AND.I.,LT,1024) GO TO IRET

CALL NVELOP(ITABLE +INPUT »J+INPTR»OUTPUT »IDIMO ,NPEAKS)
J=0

GO TO IRET
10

900

TYPE 900

FORMAT(1H1
»T16, 'NVELOP Example #1',//)
TYPE 1002

1002

FORMAT (" PEAK NO. ' +8X»'TYPE' +8X

' AREA’' »dX +» 'CENTROID' +SX

‘P WIDTH'
»/ s1SX+’P TIME
' »d4X»’'P HEIGHT
' 3% 'LEAD TIME ")

DO 11 L=1,NPEAKS
KK=1+0UTPUT(1,L)
11

1003

TYPE 1003
Ly (UTYPE(K +KK) yK=1,3) »(OUTPUT(IsL) +I=2+7)
FORMAT(I9,3AR4,3F12.0,/+9X3F12.0)

END

The Envelope-Processing (NVELOP) Subroutine

O
©

Define array variables and their size.
VTYPE is used to print a word describing how the peak ended (TYPE).

Parameters external to the NVELOP subroutine are initialize
d.
Arrays EMU, SIGMA, and SIZE are used to produce the waveform
to
be processed, which is the sum of six Gaussian curves. IT is the
threshold value; IC and X are used for preparation of the data.

Data statements initializing the variable input parameters
to the
algorithm (ITABLE) and the arguments for the call to NVELOP
.

Section producing values that represent the waveform as a function

of X.

Raw data are prepared for processing by comparing them
to the
threshold value (IT), then either incrementing the reject count
(IC), if
the datum is below threshold, or entering the datum in the input
array
if above threshold.
Each time 256 input values are produced, or when all 1024 raw
data
points have been produced, NVELOP is called.

ITABLE is not affected by the program but is used by the subrouti

ne.

INPUT contains the input data; actual values change each
time
NVELOP is called.

J is the subscript of the last element in INPUT that contains
always 256 except on last call.

data;

INPTR is either O (initially) or -1; subroutine looks for data to
start in
the first element in the INPUT array.
OUTPUT is the array where data for each peak are stored;

allocated

accommodate

unchanged by program.

all

data

produced:;

argument

space is

remains

IDIMO specifies the number of sets of peak data that can be

before the OUTPUT array is filled.

stored

NPEAKS specifies the number of sets of peak data produced thus
far;
because results are known, no check is made for a full condition with
respect to the output array.

After NVELOP is called,
processed (INPTR =-1).

all elements of the INPUT array are

This section types the results on the terminal.

The Envelope-Processing (NVELOP) Subroutine

3-27

Terminal Output
NVELOP Example
NO.

r-J

PEAK

TYPE

AREA

P TIME

CENTROID

P HEIGHT

THRESHOLD

LEAD TIME

17882,

20,

211,

VALLEY

27935,

S04,

501,

B12,

THRESHOLD

458,

53617,

597,

5299,

706,

o594,

P WIDTH

4o,
96,

NVELOP Example #2
Example 2 processes the same raw data points

but the threshold value is
lower (Figure 3—11). More of the data points are now
above threshold than
in Example 1, and more peaks are recorded.
Thus we have enlarged the

output array so that we can use the same code

following changes in the source code.

as in Example 1. Note the

In Section 1, the size of OUTPUT is increased:
DIMENSION

INPUT(256) yOUTPUT(7+6) yEMU(B)

ySIGMA(B) sSIZE(E)

In Section 2, the threshold value (IT) is changed:
DATA

ITH»ICX/1504,0,0,/

In Section 3, the value of IDIMO is changed to indica

te that QUTPUT has

more room:

DATA

J»INPTR yIDIMO sNPEAKS/
4046 0/
0

Figure 3-11:

Plot of Input Data, Showing New Threshold

Value

v"v/\\j THRESHOLD \//\«—
MR-S-1622-81

Note that Peaks 1, 4, and 5 correspond to those in

are not affected by the lowered threshold

Example 1. Peak heights

value, but because more data are

“exposed”, almost every other data value is change

The Envelope-Processing (NVELOP)
Subroutine

3-29

Terminal Output
NUVELOP Example
NO.

PEARK

3—30

TYPE

AREA

CENTROID

P TIME

P HEIGHT

LEAD TIME

THRESHOLD

20890,

24,

20,

o111,

THRESHOLD

1730,

74,

7&0

161,

890

THRESHOLD

20376,

200,

193,

199,

144,

VALLEY

BOSGG6.

D02,

S01,

B12.

446,

THRESHOLD

07374,

GO1l,

599,

706,

ood.,

THRESHOLD

27046,

900,

892,

299,

783,

The Envelope-Processing (NVELOP) Subroutine

P WIDTH

108,

109,

234,

NVELOP Example #3

In Example 3 it is assumed that there is a nonzer
input units in the same raw data processed

o baseline offset of 50
in Examples 1 and 2 (Figure

3-12). Using the code as modified for Examp
le 2, we may eliminate the
assumed baseline offset by setting the third
value in the ITABLE array to

90 (Section 4):
DATA

ITABLE/0 13,5041 447%0/

Figure 3-12:

Plot of Input Data, Showing Threshold
Value from
Example 2 and Assumed Baseline Offse
t

A /\

THRESHOLD

N_———BASELINE

/\——

MR-S-1623-81

Because the only change introduced to Example 2
is the baseline correction,
the only output values that change are the height
s, and indirectly, the
areas.

The Envelope-Processing (NVELOP) Subro

utine

3-31

Terminal Output
NUELOP Example

r-J

NO.

PEAK

TYPE

AREA

CENTROID

P TIME

P HEIGHT

LEAD TIME

THRESHOLD

18140,

24,

20,

a61
.

1 ¢

THRESHOLD

1180,

74,

111,

69.

THRESHOLD

14926,

200,

193,

149,

144,

UVALLEY

09266,

D02,

201,

762,

446
.,

THRESHOLD

21774,

BOO,

299,

636G,

o094,

THRESHOLD

43296,

oo,

892,

249,

783,

P WIDTH

INTERVAL HISTOGRAMMING (HISTI) SUBROUTINE
FORMAT:
CALL HISTICTABLE,INPUT,IHGRAM)

Where:
ITABLE

is an integer array of at least 10 elements.

ITABLE(1)

= first interval lower limit

ITABLE(2)

= gpecified interval length

ITABLE(3)

= specified number of contiguous intervals

ITABLE4)

= total number of input array elements

ITABLE(5)

= initialization flag

considered
containing data
ITABLE(6)

= underflow count

ITABLE(7)

= overflow count

ITABLE(8)

= number of IHGRAM elements exceeding
largest possible single-precision integer

ITABLE(9)

= error indicator

ITABLE(10)

= temporary internal storage element

INPUT

i1s an integer array containing input data.

IHGRAM

is an integer array used to store output data.

FILE NAMES:

HISTI.MAC (source file); HISTI.OBJ (object file)

OPTIONS:
e

EIS

(Extended Instruction Set — KE11-E)

EAE

(Extended Arithmetic Element — KE11)

DPHS$

(Double-Precision Integers)

FREQ$

(Frequency Histogram)

APPROXIMATE SIZE OF SUBROUTINE (IN WORDS):
If the following options are enabled:
NONE

EIS

EAE

NONE

218

131

DPHS$

287

164

200

FREQ$
DPH$ AND FREQ$

279

158

192

368

245

281

TYPICAL EXECUTION SPEED:

With PDP-11/34 and EIS enabled:

20000 Points/second.

With PDP-11/03 and EIS enabled:

6500 Points/second.

Chapter 4
The Interval Histogramming (HISTI) Subroutine

The interval histogramming subroutine counts the number of data elements that fall into one or more predefined categories or data types. Sets of

such counts are often presented graphically as bar-graphs or histograms. In

the context of this subroutine, a category is a defined numeric interval, and
a set of categories for a given application must be representable as a contiguous group of intervals of equal length. Data to be processed must be repre-

sented as integers.

Results are presented as an array in which each output element corresponds to a specific category. The output element reports the number of

data elements that fall into that category. Reported separately is a count of
the number of input data elements that do not belong in any of the prede-

fined categories. In addition, the subroutine can optionally produce a frequency histogram.

4.1

Definition of Basic Terms and Conventions
It is important to understand how some of the terms and conventions describing the HISTI subroutine are used throughout this chapter.

e The term data stream (or input data stream) describes all data to be
processed to produce one histogram. Note that the entire data stream

need not be processed at once; it may be processed in sequential parts.

o Interval describes a subset of integers. If N is taken to be its length, the
interval is defined in terms of its lower boundary point and the next N-1

integers in ascending order.

¢ Category is a unique classification of data.

4-1

e Two areas that are outside the total range of interest

are: those values
that are smaller than the minimum, or underflow
values, and those
larger than the maximum, or overflow values.

o Event means something that generates a valid data

element.

¢ Continuum means a continuous entity, parts of
which can be distinguished from neighboring parts only by arbitrary
division.

4.2

Your Input to the Subroutine: Its Characteristics
4.2.1

The Relation between Data and Categories

Input to the subroutine is an array of Integers that are
related in some way
to the actual data they represent. If the data are numeric
al, such as measures of height, temperature, or time, this relation is immedi
ately meaningful and obvious. However, the relation may be purely
arbitrary, as when
the data deal with an abstract condition that is represe
nted by an integer
for convenience in processing; for example, if balls of
different colors are
being counted, an integer might be assigned to represent
one color and
distinguish it from other colors.

Data categories are also numerical; each is represented by
an interval of
integers. And like the data/integer relation, the relation
between a category and the interval representing it may be meaningful
or completely
arbitrary. Values assigned to these interrelated entities (Figure
4-1) must
be mutually consistent. For instance, an integer representing
a data ele-

ment must be in the numeric interval corresponding to
the particular category to which that data element belongs. Figure 4-1
illustrates that

relations 1 and 2 are fixed, and that once relation 3 or 4 is
chosen, the
remaining relation is no longer completely arbitrary.
Figure 4-1:

Interrelation between DATA/CATEGORY and

INTEGER/INTERVAL Concepts

e —_——————————
e
——————
—— -

!
:

[

Real World

DATA <—

(Fixed)

= CATEGORY

|
|

AU,
SJ
3

r —————
—q

:
I

INTEGER e

(Fixed)

= INTERVAL

Subroutine World

MR-S-1625-81

4-2

The Interval Histogramming (HISTI) Subroutine

4.2.2

Describing the Categories

The numeric intervals representing the categories of

interest to the subroutine are defined by an integer array of parameter values
that you set. The
first three values in the parameter table define
the intervals (see
Section 4.3):

e The first element of the parameter table defines the
of the first interval. Data values smaller than this

lower numeric limit
limit do not fall into

any predefined category and are reported separately

(see Section 4.2.3).

* The second element of the parameter table defines

the numeric length of
each interval. Therefore the first interval spans integer
s greater than or
equal to the first element but smaller than the sum
of the first and second
elements. Symbolically, if the first element is I and
the second is J, the
first interval spans all integers, K1., for which

I<=sKl. <I+J
The second interval spans all integers, K2., for which

[+d=<K2<I+2-J
and so on. Note that there are J elements in each
e The third element of the parameter table

interval.

tells the subroutine how many

intervals — starting with the value of the first elemen

t — to consider.

This element also specifies the minimum dimens

ion of the output array
because each interval has a corresponding output
array element. The
implication of this value is that the last interv
al of interest spans all
integers, KN., for which
I+ (N-1)+J<KN,<
+N-J
I

where N is the integer value of the third elemen
integer values of the first and second elements,

4.2.3

t and I and J are the

respectively.

Overflow and Underflow Counts

Because the intervals of interest may not span
integer input, it is possible that the input data

that do not fall within any specified category.
number of data values outside the upper and

categories. The number of data values that

the entire range of legal
stream may contain values
The subroutine counts the

lower limits of the specified

are smaller than the minimum

specified in the first element of the parameter

table is called the underflow

count and is reported in the sixth elemen
t of the parameter array.' The

number of values that exceed the maximum value
in the interval of interest 1s called the overflow count and is report
ed in the seventh element of
the parameter table.

I See Section 4.3, the subroutine call.

The Interval Histogramming (HISTI) Subroutine

4-3

4.2.4

How the Subroutine Interprets Single-Precision Numbers

Acceptable input and output values for the HISTI subroutine can be singleprecision integers in the range of 0 to 65535; single-precision positive in-

tegers in FORTRAN have a range of only 0 to 32767. This apparent conflict

1s actually a matter of interpretation and decimal representation of the
negative integers in FORTRAN; it is easily resolved, as we shall explain.

In theory a 16-bit binary number can represent a decimal number as large

as 65535. In FORTRAN this range is divided into two parts: values from 0
to 32767 are interpreted and used as positive integers; values in the other

half of the range

are interpreted and used as negative integers.

FORTRAN negative numbers ranging from -32768 to -1 correspond directly to binary numbers ranging from 32768 to 65535.
The HISTI subroutine does not process or report values less than zero.
Therefore all input and output values are treated as unsigned so that we

can use the full positive range of the 16-bit word.
You may well ask “How does this interpretation of the data by the subroutine affect my particular application?” The answer is that:

All input values and all resulting output data less than 32768 (2'°) are
treated in exactly the same way by the subroutine and by FORTRAN

(Figure 4-2).
2.

If either your input or output data contain values greater than 32767

(but not greater than 65535), they are interpreted as negative by
FORTRAN but not by the subroutine. For example, if the subroutine

outputs a single-precision integer value of 40,000, FORTRAN interprets it as —25536.

Figure 4-2:

Relation between FORTRAN Integers and Unsigned
Binary Values
FORTRAN Interpretation (2s Complement)

32767

0...

—-32768. . .

32767. ..

65535

Unsigned 16-Digit Binary Value
MR-S-1626-81

4-4

The Interval Histogramming (HISTI) Subroutine

We shall now present a simple mechanism for converting an integer
that
FORTRAN interprets as negative to a floating-point number
equal to the
unsigned interpretation of the value. This conversion may
not always be
necessary; some operations, such as addition and
subtraction, are unaf-

tected by the signs of the operands. The unsigned results of such

tion would be correct so long as the results were not less

an opera-

than 0 or greater

than 2'°. However, operations such as division and multiplication, or print-

ing and typing, are affected by the FORTRAN interpretation
of unsigned
integers larger than 32767 as negative numbers.

The following two methods can be used to convert unsigne
integers to floating-point numbers:

d single-precision

R = (1 - N/IABS(N)) /2 * 65536. + N
or

R =N

IF (N.LT.0)R = 65536. + N
where R is the floating-point variable equivalent to the
unsigned singleprecision integer stored in N, and IABS(N) is a functio
n available from the

FORTRAN library.

To convert a floating-point number less than 65536 to an unsigne

d integer

you can use one of the following equations:

N = R-65536 * IFIX (R/32768.)
or

N = R-65536.
IF (R.LT.32768.) N = R
where R is again the floating-point variable, N the unsigned integer
in N, and IFIX is a function available from the FORTRAN library.

4.3

stored

How to Call the Interval Histogramming Subroutine
The symbolic name for the interval histogramming subroutine
and the general format for the FORTRAN call is:

is HISTI,

CALL HISTIITABLE,INPUT,JHGRAM)

For reference, argument names in the call to HISTI have
arbitrarily. You may supply your own argument names, but

all of the arguments explicitly. There are no default values
arguments. If you omit an argument, either accidentally

been assigned
you must state
for any of the

or on purpose, or if

you supply too many arguments, a FORTRAN error messag
e results and no

data is processed. The arguments are described in the followi

ng discussion.

1 Format for the distributed version; it may change if the option FREQ$
Section 4.5.4).

is enabled (see

The Interval Histogramming (HISTI) Subroutine

4-5

ITABLE is an integer array of at least 10 elements, used to:

e Transmit

information

to the

through ITABLE(5))

subroutine from

the

user

(ITABLE(1)

* Return information from the subroutine to the user (ITABLE(6) through
ITABLE(9))
e Store information on an interim basis (by the subroutine) (ITABLE(10))

You

must

set the

array

elements

subroutine.

that transmit

information

the

ITABLE(1)

The lower limit of the first interval (see Section 4.2.2)

ITABLE(2)

The specified interval length (see Section 4.2.2)

ITABLE(3)

The total number of contiguous intervals to be considered

(see Section 4.2.2)
ITABLE(4)

The total number of array elements containing data (starting with the first element in the input array (INPUT))

ITABLE(5)

A value that must be set to zero before the initial call to
the subroutine; it signals the subroutine to initialize the
output array and other output elements in the parameter

table. On subsequent calls to the subroutine, if a different
segment of the same data stream is being processed, operation continues, and there is no reinitialization.

The next group of elements is used to report information not included in the

actual histogram.

ITABLE(6)

The underflow, or count of the number of input data values

that are smaller than ITABLE(1)

ITABLE(7)

The overflow, or count of the number of input data values
that exceeds the upper limit of the last interval; the num-

ber of data values exceeding

ITABLE(1)+ITABLE(2) - ITABLE(3)
are reported here.

ITABLE(8)

The number of output array elements that have exceeded

the largest possible single-precision integer (65535). In
FORTRAN this integer is 32767; however, this subroutine
can report integers as large as 65535 by treating all data

as unsigned positive integers (see Section 4.2.4).

ITABLE(9)

An element used to report error conditions:
=

Indicates no errors

Indicates

that
ITABLE(1)+ITABLE(2)ITABLE(3)>65535
Indicates ITABLE(N) is in error, for example,

ITABLE(2)=0
4-6

The Interval Histogramming (HISTI) Subroutine

The following element is used by the subroutine for its own operation:
ITABLE(10)

An element used for internal storage on a temporary basis.

INPUT is an integer array containing the data to be processed. All

data

are treated as positive and unsigned (see Section 4.2.4). The number

of
array elements to be processed is ITABLE(4), and processing
always
begins with the first element of the array. Note, however, that all data
need not be placed in the array at one time. Instead, one array of
data
can be processed, the array refilled with new data, and the subrouti
ne
called again to process the array a second time. It is possible to
continue
in this piecemeal fashion until all data have been processed. In
real-time
applications such a processing cycle becomes an ongoing function
.

IHGRAM is an integer array to store the results of processing;

each array
element is devoted exclusively to one of the numerical interval
s that

represent a single category. The order of the array element

s corresponds

to the numeric order of the intervals, that 1s, the Nth element

of the

output array will have a value equal to the number of data elements

the input stream that belong in the interval.

ITABLE(1) + (N-1)-ITABLE(2) to ITABLE(1) + N ITABLE(2)-1

4.4

Input and Output — Using the Subroutine
As previously stated, all data for a particular histogram need

not be available, or even known, before processing begins. Initialization takes
place (all

counters are set to zero) only when ITABLE(5) equals

zero. Parameter table

elements are also checked for correctness when ITABLE(5)
equals zero.
Before the subroutine returns, it automatically changes ITABLE
(5) so that
if a subsequent call is made to process new data for the same
histogram,

processing continues as though no interruption had

taken place. Thus an
entire set of data for one histogram may be processed at
one time, memory
space permitting; or, if the user wishes, the data
may be processed one
segment at a time. The value assigned to ITABLE
(4) should indicate the

number of elements in the input array to be processed for
The subroutine is position-independent and reentrant.

tures are of interest mainly at the system level, they do

a specific call.

Although these fearesult in additional

advantages at the user level. Perhaps most significant is the

processing several data streams in parallel. All pertine

possibility of

nt information con-

cerning the history of a data stream is contained in
the ITABLE array
rather than in the code for the subroutine. Imaginative
use of the arguments 1n the subroutine call should make the subrout

ine functionally com-

patible with any application that uses interval histogramming.

4.5

Modifying the Subroutine — Using Options
The following sections explain which options you can
use with the interval
histogramming subroutine. If you want to use any of the
options, you must
enable them when you build the subroutine from the
source file using the
interactive build procedure (see Section 1.1).

The Interval Histogramming (HISTI) Subroutine

4-7

4.5.1

EIS (Extended Instruction Set)

Enable this option if your installation has EIS (KE11-E) hardware or any
other floating-point option available. Enabling this option increases the

execution speed and decreases the memory requirements for the subroutine

by approximately 121 words if DPH$ is not enabled, and by approximately
123 words if DPHS$ is enabled.

4.5.2

EAE (Extended Arithmetic Element)

Enable this option if your installation has EAE (KE11) hardware available.

Enabling this option increases the execution speed and decreases the memory requirements for the subroutine by approximately 87 words.

4.5.3

DPHS$ (Double-Precision Integers)

If the data values to be histogrammed exceed 65535 (2'°-1), this option
must be enabled. If you are using a copy of the subroutine with the option

enabled, you must provide your data to the subroutine as follows:

e All input data must be double-precision integer, that is, the second argument

in the FORTRAN CALL
INTEGER*4 array (or equivalent).

statement,

INPUT,

must

o Because this option expands the possible range of input values by a factor

of 65536 (2'°), the range of variables used to define the exact range of

interest must also be expanded by 2'°. Therefore the first argument in the
FORTRAN CALL statement, ITABLE, must also be an INTEGER*4 array or the equivalent. ITABLE(1) and ITABLE(2) may then select the

range of interest.

Enabling this option has no effect on output because the range of input

values does not affect the size of output values.

Enabling DPH$ alone increases the memory requirement by 69 words.

4.5.4

FREQS$ (Frequency Histogram)

A frequency (or zeroth) histogram usually has meaning only when input
data elements represent contiguous measurements of a continuum and are
input sequentially. The frequency histogram then tells, for each contiguous

interval along the continuum, how often an event occurred that produced
one data element for the subroutine.

For example, suppose we are studying the distribution of discarded beer

cans on the side of a road. Let the input data be the distance between cans.
The interval histogram would then describe the number of times cans were

found within certain preset intervals, that is, how many were 5 feet apart

or less, how many were between 6 and 10 feet apart, and so on. The
frequency histogram would describe the distribution over sections of the
road; how many beer cans (events) were found in the first quarter mile, how
many in the second, and so on.

4-8

The Interval Histogramming (HISTI) Subroutine

Another example might be to determine how often two events occur within

specified time intervals: for instance, how often do the two events occur
within 2 seconds, how often between 2 and 4 seconds, and so on. The frequency histogram would show how many events occurred within each subsequent time slice.

Mathematically, if the interval length in the continuum is chosen to be K,

and if an input, which represents contiguous measurements of that continuum, is taken to be N;, the first element of the frequency histogram is M,,

where:

M,+1

<K=

i=1

The second element would be M,, where:
M,+M,

M, +M,+1

<2-K-=

i=1

and so on.

If a frequency histogram is to be produced by the subroutine, this option
must be enabled. When it is enabled, the length of the ITABLE array
(Section 4.3) must be increased from 10 to 17, and additional parameters

must be defined before implementation of the subroutine. The first nine
parameters

are

defined

exactly

if FREQ$

were

not

ITABLE(10) through ITABLE(17) must be defined as follows:

ITABLE(10)

but

Indicator of whether to produce a frequency histogram:
=0

ITABLE(11)

enabled,

Do not produce a frequency histogram
Produce a frequency histogram

Length (dimension) of array where results of the frequency

histogram are to be stored; it should be large enough to

hold all input data for one call.

ITABLE(12)

Length of the interval of the continuum to be used in con-

structing the frequency histogram; corresponds to value of

K in the preceding equations.
ITABLE(13)

Number of frequency histogram elements already calculated; will be set to 0 by the subroutine for the initial call

to HISTI, when ITABLE(5) is 0. ITABLE(3) is updated
continuously as input is processed by the subroutine. Be-

cause elements of this histogram are calculated sequentially, data from the storage array can be extracted each

time the subroutine has processed all data in the input
array and returned to the calling routine. If elements are
extracted, ITABLE (13) can then be adjusted to reflect
where the next element of the frequency histogram is to be

stored.

The Interval Histogramming (HISTI) Subroutine

4-9

ITABLE(14)

Current partial count for the next entry in the freque
ncy
histogram; as soon as the number of input elements
satisfies the requirements for completing the current
interval
of the frequency histogram, ITABLE(13) is incremented
by
1, and the next entry is placed in the histogram.

ITABLE(15)

Elements used exclusively by the subroutine for interna

storage.

ITABLE(17)
NOTE

If you enable FREQ$ when you build the subroutine,
you
must still dimension ITABLE to 17 even if ITABLE
(1)=0.

The subroutine uses ITABLE(15) through ITABLE(17).
The subroutine also needs another array to store the frequen

cy histogram
data. If ITABLE(10)=1, the FORTRAN CALL statement takes
the form:
CALL HISTIITABLE,INPUT,IHGRAM,IFREQ)

IFREQ is the array to contain the frequency histogram data.

This integer

array must be at least as long as specified by ITABLE(
11); upon return,

ITABLE(13) will notify the user how many elements in this

array contain

If you remove data from the array before a subsequent call

to the subrou-

data.

tine, you may adjust ITABLE(13) before reentry to reflect
storage space now available.

the additional

If the number of array elements available for storage 1s not large

enough,
that is, if ITABLE(13) becomes larger than ITABLE(11), the
subroutine
stops computing the frequency histogram (but continues

the

to process data for

interval histogram). You can take corrective action by making
ITABLE(13) smaller than ITABLE(11) when the subroutine returns.
Note
that ITABLE(13) also indicates the number of elements lost
in the frequency histogram calculation (ITABLE(13)-ITABLE(11)).

If FREQ$ is enabled, memory requirements are increased by approxi

mately
58 words if DPHS$ is not enabled and by approximately 78 words if DPHS$
is
enabled.

4.6

Examples of Input/Output Variation Using the HISTI Subroutine
The four examples presented here process equivalent sets of data in similar

ways but focus on different capabilities of the HISTI subrouti
ne. Example 1
is based on the distributed version of the subroutine. A set of
10,000 random integers ranging from 15 to 225 is processed, 500 at a time. Each

sequential set of input points is stored in alternate halves of
the input
array to simulate real-time applications, which conserve processi
ng time by

collecting and processing data in parallel.

4-10

The Interval Histogramming (HISTI) Subroutine

NOTE

If you use FORTRAN 77 and you want to duplicate the
nal output for the example programs, replace the

termi-

standard

random-number generator in F4POTS with FAPRA
N.OBJ.
Terminal output for the example programs 1s based
on the
FORTRAN IV random-number generator. The FORT
RAN 77
random-number generator is different from
that for
FORTRAN IV and will not produce the same output.
See
Section B.1.

Categories of interest comprise 40 intervals of five integer

s each; the mini-

mum value for the first interval is 20. When
processing is complete, the

following output is printed:

e Total count of data items belonging to each categor

y, that is, the interval

histogram (IHGRAM)

e The number of data items smaller than the total

interval of interest, that

® The number of data items larger than the total

interval of interest, that

1s, the underflow count (ITABLE(6))

18, the overflow count (ITABLE(7))

® The total number of output counters that have

exceeded 65535.

The Interval Histogramming (HISTI) Subroutine

4-11

HISTI Example #1

The Interval Histogramming (HISTI) Subroutine

4-13

HISTI Example #1
DIMENSION ITABLE(10) ,INPUT(1000) ,IHGRAM(40)

EQUIVALENCE (ITABLE(1)+IS) y(ITABLE(2) JIW)
DATA ITABLE/2045,40,+,500,6%0/

DATA I14I2/7040/
DO 2 J=2,21
N=300#MOD(J,2)+1

DO 1

I=N,N+499

INPUT(I)=RAN(I1,I2)%#210+15
CALL HISTI(ITABLE »INPUT(N) yIHGRAM)

IF(ITABLE(9) .,EQ.0) GO TO 2
TYPE 1000,ITABLE(9)
1000

FORMAT (' ERROR INDICATOR =

‘,13)

rJ3

STOP

CONTINUE
TYPE 900

900

FORMAT(1H1 »T30 ) ‘HISTI Example 817 ,//)
TYPE 2000

2000

FORMAT (24X +» "RESULTING INTERVAL HISTOGRAM
'/ /

ac’

INTERVAL COUNT
") /)

TYPE 3000, ((N-1)#IW+IS/N*IW+IS»IHGRAM(N) yN=1,40)
3000

FORMAT(4(I74'-"»14+16))

4000

FORMAT(//

TYPE 4000, (ITABLE(I) +1=6,8)
1

' UNDERFLOW COUNT =

* 13,4/’ OVERFLOW COUNT =

" NO, OF COUNTERS WHICH OVERFLOWED =

*,12,//)

CALL EXIT
END

4-14

The Interval Histogramming (HISTI) Subroutine

*,I3,/,

® Define

array

elements

and

their

sizes;

convenience.

use

equivalence

for

® Set parameter table elements: there are 40 intervals of interest,

starting at 20, and comprising 5 elements each; input array contains
500 data elements; set ITABLE(5) to zero to signal initialization.
Initialize random number generation variables.

Provide 20 sets of data (500 points each) for processing.
Determine which half of the input array is to receive the next set of

input data.

Calculate next set of random numbers for processing.
Process next set of input values:
ITABLE contains parameter table
INPUT contains input for processing, starting at subscript N
IHGRAM is array where interval histogram is stored

@ Q

Check for error on return.
End of data generation and processing loop
Print output:

Interval histogram (IHGRAM)
Underflow (ITABLE(6)); overflow (ITABLE(7)); counter overflow count

(ITABLE(8))

The Interval Histogramming (HISTI) Subroutine

4-15

Terminal Output
HISTI

RESULTING

INTERVAL

COUNT

INTERVAL

Example

INTERVAL HISTOGRAM

COUNT

INTERVAL

COUNT

20-

218

29-

234

30~

—

248

35-

do-

45-

242

299

20~

216

BO-

29
-

244

65-

228

226

70~

245

Bo-

75-

271

B5-

242

235

90 -

217

100

100-

105

231

95-

105-

110

256

246

110-

115

229

120-

125

237

115-

125-

233

130

217

130-

135

242

135-

140-

145

232

140

145-

229

150

224

150-

155

298

160-

165

241

1535-

160

165-

170

249

231

170-

173

268

175-

180

180~

185

240

185-

295

190

231

190-

195

232

200

[Ay

200-

205

240

195
-

205-

210

219

210-

215

220

215-

Law 2

OVERFLOW COUNT
= 231

4-16

INTERVAL

UNDERFLOW COUNT
= 249

NO.

COUNT

OF COUNTERS WHICH OVERFLOWED
= 0

The Interval Histogramming (HISTI) Subroutine

s
t)

239

HISTI Example #2

Example 2 is identical to Example 1 except that a frequency histogra

m is
produced in addition to the results output in Example 1. The distribut
ed
version of the object file for the HISTI subroutine cannot be
used to produce
a frequency histogram. The subroutine must be built from the
source file
with the FREQ$ option enabled in order to produce a frequenc
y histogram

(see Section 4.5.4 and Section 1.1).

Once FREQ$ has been enabled and the correct form of the subrouti
ne is
available, the parameter table must be expanded to include definiti
ons for
the interval size of the frequency histogram and the size
of the array in
which the frequency histogram data are to be stored. The name
of the array
to be used to store the frequency histogram data (IFREQ
) must also be
added to the FORTRAN CALL statement.

Upon completion of processing, the output includes the element
s of the
frequency histogram in addition to the values output in Exampl
e 1.

The Interval Histogramming (HISTI) Subroutine

4-17

DIMENSION ITABLE(17) »INPUT(1000),IHGRA
,IFREQ(12
M(40O)
0)
EQUIVALENCE (ITABLE(1),IS) ,(ITABLE(2) yIW)
DATA ITABLE/Z0,5+d40,500,5%#0,1,120,10000,5%0
/

DATA
I1 4127040/
DO 2 J=2,21
N=SO0*#MOD (J,2)+1

DO
1 I=NsN+499
INPUT(I)=RAN(I1,I2)%210+15

CALL HISTIC(I
INPUT(N) TABL
yIHGRAM,IFREQ)
E

IFCITABLE(9),EQ.
GO TO
0)
2
TYPE 1000,ITABLE(9)
1000

FORM
ERROR
AT(*
INDICATOR = *,13)

STOP
rJ

1 QO
O © h Gy

HISTI Example #2

CONTINUE
TYPE 900

900

FORMAT (1H1 yT30, 'HISTI

Example #2/,//)

TYPE 2000
2000

FORMAT
(24X '"REINTERVAL
SULT
HISTOGRAM
ING
'/ /
1

ac’

INTERVAL COUNT ") /)

TYPE 3000, ((N-1)%#IW+IS

N*#IW+IS,IHGRAM(N) yN=1 ,40)

3000

FORMAT(4(I7,'-"414,16))

4000

FORMAT (//

TYPE 4000, (ITABLE(I)
1=6,8)
1

' NO.

' UNDERF
COUNT
LOW
=

413/, OVER
COUNT
FLOW
= “,13,/,

OF COUNTERS WHICH OVERFLOWED =

*,12)

TYPE SO0
SO00

FORMAT (///20X,’CORRES
FREQUENCY
PONDI
HISTOGRAMNG
' // ,
S’
ENTRY COUNT ") /)

I=ITABLE(13)

IF(ITABLE(13).GT.ITABLE(11))

I=ITABLE(11)

TYPE 7000, (N»IFREQ(N)
yN=1,1)
7000

FORMAT(S(IB,16))
CALL EXIT
END

4-18

The Interval Histogramming (HISTI) Subroutine

® Define

array

elements

and

their

sizes;

use

convenience

equivalence

for

® Set parameter table elements: there are 40 intervals of interest, starting at 20, and comprising 5 elements each; input array contains

500

elements; set ITABLE(5) to zero to signal initialization; indicate fre-

quency histogram should be produced, set number of element
s in frequency histogram array, and specify length of frequency
histogram
interval.

Initialize random number generation variables.

Provide 20 sets of data (500 points each) for processing.

Determine which half of the input array is to receive the

next set of

input data.

Determine next set of random numbers for processing.
Process next set of input values:

ITABLE contains parameter table

INPUT contains input for processing, starting at subscript
N
IHGRAM is array where interval histogram is stored

IFREQ is array where frequency histogram is stored

Check for error on return.
Note that ITABLE(13) is assumed to be less than ITABLE(

@ Q@

1s set at 120; therefore ITABLE(13) is not checked.

11), which

End of data generation and processing loop
Print output:

Interval histogram (IHGRAM)
Underflow ITABLE(6)); overflow (ITABLE(7)); counter overflo

w count

(ITABLE(8))

Frequency

histogram
ITABLE(13))

(IFREQ(),

where

ranges

from

The Interval Histogramming (HISTI) Subroutine

4-19

Terminal Output
HISTI

RESULTING
INTERVAL

COUNT

INTERVAL HISTOGRAM

COUNT

INTERVAL

COUNT

INTERVAL

COUNT

20
-

218

25-

234

30-

226

248

35-

40
-

45-

242

239

o0-

216

60O-

29
-

244

B5-

228

226

70-

245

75-

BO-

271

85-

242

2395

go-

217

100

100-

95-

291

105-

110

206

246

1 10-

115

120-

229

115-

237

120

125-

130

233

217

1 30-

135

242

140-

232

135-

140

145-

150

229

224

1 °o0-

155

258

160
-

155-

241

160

165-

170

249

231

1 70-

1795

268

180-

175-

240

180

185-

299

190

231

1 90-

195

232

195-

200

200-

240

205-

228

210

219

10-

215

290

215-

29
oo
)

239

UNDERFLOW COUNT
OVERFLOW COUNT

NO.,

INTERVAL

Example

=
-

249
0

OF COUNTERS WHICH OVERFLOWED

CORRESPONDING FREQUENCY HISTOGRAM

4-20

ENTRY

COUNT

EN TRY

COUNT

ENTRY

COUNT

ENTRY

COUNT

ENTRY

COUNT

80O

)

795

8.2

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

The Interval Histogramming (HISTI) Subroutine

HISTI Example #3

The processing scheme used in Example 3 is identical to that for Example

1. One major variation in Example 3 is that each input data element
is
increased by a factor of 65536 (2'°) and must therefore be treated as
a
double-precision integer. Because the distributed version of the object file
for the HISTI subroutine cannot process double-precision integers, the
source file must be built with the DPH$ option enabled (see Section
1.1).

Example 3 illustrates how the proper version of the subroutine processes
double-precision integers. Input values are exactly 2'° (65536) times larger
than those values processed in the previous examples, and output is
analogous to that in Example 1.

Note that when double-precision integers are processed, both the input

ar-

ray and certain of the parameter table values must be double-pr
ecision
integer arrays (data type INTEGER*4). Because the 1st, 2nd, and
12th
parameters of ITABLE are all increased by 2'®, categories
and intervals of
interest are increased so that their relation to the input remains
the same
as in Example 1. Thus output from Example 3 is identica
l to that from
Example 1.

Because this example uses FORTRAN 1V, double-precision arrays

ITABLD
and INPUTD are equivalenced to single-precision arrays ITABLE
and
INPUT of the same word length. As a result values for the double-p
recision
elements can be set via their single-precision equivalents.

The Interval Histogramming (HISTI) Subroutine

4-21

1 E @ron O

HISTI Example #3
DIMENSION ITABLE(20) » INPUT(2000) yIHGRAM(40)

INTEGER*4 ITABLD(10) »INPUTD(1000)
EQUIVALENCE
1

(ITAB
»(ITABLE(4)
LE(2)
,IW) »(ITABLE
,IS)
ITABLD) »
(INPUT »INPUTD)

DATA ITABLE/0O 12040 ,+5,4040,500,13%0/

DATA INPUT/2000%0/

DATAI1,12/0,0/
DO 2 J=2,21
N=300#MOD(J,2)+1

DO
1 I=N*»2,(N+499)%2,2
1

INPUT(I)=RAN(I1,I2)%#210+15

CALL

HISTI(ITABLD »INPUTD(N)

IHGRAM)

IFCITABLE(17).,EQ.,0)
GO TO 2

TYPE 1000,ITABLE(17)
1000

FORMAT(’ ERROR INDICATOR =

“,13)

STOP
CONTINUE

TYPE 900
900

FORMAT(1H1,T3Example
0,'HISTI
#3',//)
TYPE 2000

2000

FORMAT (24X, 'RESULTING INTERVAL HISTOGRAM'//
1

4(¢7

INTERVAL " yBX) »/ 14 ("

N2**16 COUNT ") /)

TYPE 3000, ((N-1)%IW+IS /N*#IW+IS,IHGRyN=1,40)
AM(N)
3000

FORMAT(4(I74+'-"4144+16))

4000

FORMAT(//+'

TYPE 4000 »(ITABLE(I) »I=11,15,2)
1

UNDERFLOW COUNT =

4,13,/

" NO. OF COUNTERS WHICH OVERFLOWED =

' OVERFLOW
COUNT =

“,I2)

CALL EXIT
END

4-22

The Interval Histogramming (HISTI) Subroutine

® Define array elements and their sizes; use equivalence for convenience; note that ITABLD and INPUTD are double-precision.

® Set parameter table elements: there are 40 intervals of interest, start-

ing at 20-2'° = 1,310,720, and comprising 5-2'® = 327,680 elements

each; input array contains 500 elements; set ITABLD(5) to zero to
signal initialization.

Clear high and low parts of double-precision input.
Initialize random number generation variables.
Provide

sets

of data

(500

double-precision

points

each)

processing.

for

Determine which half of the input array is to receive the next set of

input data.

Determine next set of random numbers for processing; place random

number range from 15 to 225 in the high order part of the doubleprecision integer array ITABLD via ITABLE, effectively producing

random numbers in the range of 15-2'¢ to 225-216.
Process next set of input values:

ITABLD contains parameter table
INPUTD contains input for processing, starting at subscript N
IHGRAM is array where interval histogram is stored

@ Q

Check for error on return.
End of data generation and processing loop
Print output:

Interval histogram (IHGRAM)

Underflow (ITABLD(6)); overflow (ITABLD(7)); counter overflow count

(ITABLD(8))

The Interval Histogramming (HISTI) Subroutine

4-23

HISTI Example #4
DIMENSION ITABLE(34) »INPUT(2000) yIHGRAM(A0)
,IFREQ(120)
INTEGER#4 ITABLD(17) INPUTD(1000)
EQUIVALENCE (ITABLE(2),IS)»(ITABLE(4) yIW) s (ITABLE
»ITABLD) ,
(INPUT,INPUTD)
DATA ITABLE/0120,0+5,4040,500,11%0,1 10+1204904,
0,10000,10%0/

KN OO

DATA INPUT/2000%0/
DATA I1,12/0,0/

DO 2 J=2,21
N=500%#MOD(J,2)+1

DO 1

I=N#*2,(N+499)%2,2

INPUT(I)=RAN(I1/I2)%#210+15

IF(ITABLE(17).EQ.,0) GO TO 2

()

CALL HISTI(ITABLD
» INPUTD(N) »IHGRAMIFREQ)
TYPE 1000,,ITABLE(17)

1000

FORMAT (' ERROR INDICATOR =

‘' 413)

STOP

CONTINUE

TYPE 900

900

FORMAT(1H1 T30, 'HISTI Example 4’ ,//)
TYPE 2000

2000

FORMAT (24X +» "RESULTING INTERVAL HISTOGRAM‘// ,

ac’
INTERVAL ' yBX) s/ 44 ("
X 2Z2#%16 COUNT
") /)
TYPE 3000,((N-1)#IW+IS N*#IW+IS,IHGRAM(N) sN=1,40)

3000

FORMAT(4(I7,'-",14+16))

4000

FORMAT(//+’ UNDERFLOW COUNT =

TYPE 4000, (ITABLE(I) yI=11,15,2)

NO.

*,13,/,' OVERFLOW COUNT =

OF COUNTERS WHICH OVERFLOWED =

“,12)

TYPE S000

5000

FORMAT(///20X+'CORRESPONDING FREQUENCY HISTOGRAM'/
/ ,
S’
ENTRY COUNT
) /)
I=ITABLE(25)

IFC(ITABLE(25) .GT,.ITABLE(21))

I=1TABLE(21)

TYPE 7000 ,(N»IFREQ(N) +N=1,1)
7000

FORMAT(S(I8,16))
CALL EXIT

END

4-26

The Interval Histogramming (HISTI) Subroutine

* 134/,

O
®

Define array elements and their sizes; use equivalence
for convenience; note that ITABLD and INPUTD are double-precisi
on.

Set parameter table elements: there are 40 intervals

of interest, start-

ing at 20-2' = 1,310,720, and comprising 5-2'¢ =
327,680 elements

each; input array contains 500 elements; set ITABL
D(5) to zero to
signal initialization; indicate frequency histogram
should be produced,
set number of elements in frequency histogram
array, and specify
length of frequency histogram interval (10000-2!¢ =
655,360,000).
Clear high and low parts of double-precision input.
Initialize random number generation variables.
Provide

sets

of data

(500

processing.

double-precision

points

Determine which half of the input array 1s to receive

each)

for

the next set of

input data.

Determine next set of random numbers for process

ing; place random

number range from 15 to 225 in the high order
part of the doubleprecision integer array ITABLD via ITABL
E, effectively producing
random numbers in the range of 15:2'¢ to 225-2'6
,

Process next set of input values:
ITABLD contains parameter table
INPUTD contains input for processing, starting
IHGRAM is array where interval histogram is

at subscript N

stored

IFREQ is array where frequency histogram is stored

Check for error on return.
Note that ITABLD(13) is assumed to be less than
1s set at 120; therefore ITABLD(13) is not checke

ITABLD(11), which

@ Q

End of data generation and processing loop
Print output:

Interval histogram (IHGRAM)
Underflow (ITABLD(6)); overflow (ITABLD(7)); counte

r overflow count

(ITABLD(8))

Frequency histogram (IFREQ(I),
ITABLD(13)=ITABLE(25))

where

ranges

The Interval Histogramming (HISTI) Subro

from

utine

4-27

Terminal Output
HISTI

RESULTING

INTERUAL
M

Z%%16

Example

INTERVAL HISTOGRAM

INTERVAL
COUNT

N 2*%16

INTERVAL
COUNT

2%#% 16

INTERVAL
COUNT

2#%16

COUNT

20-

218

29-

234

30-

40-

226

248

35-

45-

295

S0-

BO-

895

GBS

216

244

295~

65-

228

226

70-

43S

75-

242

8O-

271

B5-

235

90-

217

100-

95-

105

100

251

256

105-

110

246

110-

120-

115

125

237

229

125-

115-

130

120

217

130-

233

140-

135

145

232

242

145-

135-

150

140

o Xe

2295

150-

160-

155

1G5

241

2598

165-

155-

170

160

231

249

170-

180-

175

185

268

240

175-

185-

190

180

231

2995

190-

200-

195

205

232

240

195-

205-

210

200

219

228

210-

2195

250

215~

220

239

ENTRY

COUNT

UNDERFLOW COUNT
= 249
OVERFLOW COUNT
= 231
NO.,

OF COUNTERS WHICH OVERFLOWED
= 0

CORRESPONDING FREQUENCY HISTOGRAM
ENTRY

4-28

COUNT

ENTRY

COUNT

ENTRY

COUNT

ENTRY

COUNT

895

929

895

102

100

104

107

108

109

112

110

114

117

115

119

The Interval Histogramming (HISTI) Subroutine

INTERNAL

HISTOGRAMMING

WITH

REFERENCE

POINTS

(RHISTI) SUBROUTINE
FORMAT:
CALL RHISTIITABLE,INPUT,IHGRAMI[,IFREQ])

Where:
ITABLE

i1s an integer array of at least 16 elements.
ITABLE(1)

first interval lower limit

ITABLE(2)

specified interval length

ITABLE(3)

total number of contiguous intervals

ITABLE(4)

total number of array elements con-

considered
taining data
ITABLE(5)

number of data values to be processed
after each reference is

detected
ITABLE(6)

initialization flag

ITABLE(7)

number of reference points

ITABLE(8)

underflow count

ITABLE(9)

overflow count

ITABLE(10)

number

detected

exceeding

output

largest

array

elements

possible

single-

precision integer

ITABLE(11)
ITABLE(12)

error flag
frequency histogram indicator
0 = no frequency histogram
1 = frequency histogram

ITABLE(13)

number of array elements used to store
frequency histogram ITABLE(12)=1)

ITABLE(14)

number of frequency histogram elements

already

calculated

(if

ITABLE(12)=1)

ITABLE(15)

current partial count for next entry
into

the

frequency

histogram

(@f

ITABLE(12)=1)

ITABLE(16)

internal storage

INPUT

1s an integer array containing input data.

IHGRAM

1s an integer array used to store output data.

IFREQ

1s an integer array used to store frequency histogram data
(required only when ITABLE(12)=1).

FILE NAMES:

RHISTI.MAC (source file); RHISTI.OBJ (object file)

OPTIONS:

e
e
e

EIS
EAE
DPRS$

(Extended Instruction Set — KE11-E)
(Extended Arithmetic Element — KE11)
(Double-Precision Integers)

APPROXIMATE SIZE OF SUBROUTINE (IN WORDS):
If the following options are enabled:

NONE
DPR$

NONE

|EIS

|EAE

286
360

165
237

| 199
| 273

TYPICAL EXECUTION SPEED:

With PDP-11/34 and EIS enabled:

15000 Points/second.

With PDP-11/03 and EIS enabled:

5000 Points/second.

Chapter 5
The Interval Histogramming with Reference Points
(RHISTI) Subroutine

The interval histogramming with reference points subroutine counts the
number of data elements that fall into one or more predefined categories, or

data types. Sets of such counts are often presented graphically as bargraphs or histograms. The subroutine interprets preset numerical intervals
as categories; a set of categories for a given application must be represent-

able as a contiguous group of intervals of equal length.
Data to be processed must be represented by unsigned integers not equal to
zero. Data elements equal to zero are interpreted by the subroutine as
reference points. Processing of input data begins only after the first reference point is detected. Additional reference points are significant in that

they partition the data stream.
Interval histogramming results are presented as an array in which each

output element is associated with a specific category. A count is also kept of
input elements that do not belong in any predefined category; this count is
reported separately.

If a frequency histogram is also produced, each element of its output array
contains the total number of data elements that appear in the data stream

in the segment described by each pair of reference points.

5.1

Definitions of Basic Terms and Conventions
It is important to understand how some of the terms and conventions de-

scribing the RHISTI subroutine are used throughout this chapter.

® Data stream (or input data stream) describes all data to be processed to

produce one histogram. Note that the entire data stream need not be
processed at once; it may be processed in sequential parts.

-1

e Interval describes a subset of integers. If N is taken to be its
interval is defined in terms of its lower boundary point

integers in ascending order.

length, the

and the next N-1

e Category is a unique classification of data.
® Two areas that are outside the total range of interest

are: those values

that are smaller than the minimum, or underflow values,
and those
larger than the maximum, or overflow values.

e Event means something that generates a valid data element

9.2

Your Input to the Subroutine: Its Characteristics
Your input to the subroutine should have the form of a stream of
integers,
divided into like segments by a set of reference points. This section
deals
with how this data stream is seen in the real world and in the
subroutine
world; it also explains how the subroutine interprets the single-precision
integers in the input stream.

9.2.1

The Reference Points — Their Significance

Reference points serve two purposes:
e They indicate the point in the input data stream where the interval

histo-

e They denote boundary points in the input stream which are used

in the

gram should begin, that is, at the first reference point.

production of a frequency histogram (see Section 5.3.4).

Reference points are normally used to signify events that subdivide

the
input data stream into related partitions. For example, reference points

can signity ticks of a clock at a preset rate during a sampling process.

Or,

if you are monitoring responses to a series of stimuli, the occurrence of

each stimulus could be recorded as a reference point, and the data characterize the response being observed.

9.2.2

The Relation between Data and Categories

Data to be histogrammed are nonzero integers related in some way to the

actual data they represent. If the data are numerical, such as measures
of
height, temperature, or time, this relation is immediately meaningful and

obvious. However, the relation may be purely arbitrary, as when the data
deal with an abstract condition that is represented by an integer to be
processed by the subroutine; for example, if balls of different colors are

being counted, an integer must be assigned to represent one color to distinguish it from other colors.

Data categories are also numerical; each is represented by an interval of
integers. And like the data/integer relation, the relation between a cate-

gory and the interval representing it may be obvious or completely arbi-

trary. Values assigned to these interrelated entities (Figure 5-1) must be

The Interval Histogramming with Reference Points (RHISTI) Subroutine

mutually consistent; for instance, an integer representing a data element
must be in the numeric interval corresponding to the particular category to
which that data element belongs. Figure 5-1 illustrates that relations 1
and 2 are fixed, and that once relation 3 or 4 is chosen, the remaining

relation is no longer completely arbitrary.
Figure 5-1:

Interrelation between DATA/CATEGORY and
INTEGER/INTERVAL Concepts
r———F—FF~F~ F«~F~F~—~~"~"""""~""~""""~/"—/—
"7
7777~ a3

:
:

DATA =

Real World
1
(Fixed)

|
» CATEGORY

|
|

[ (N 4

3
r-— =—"f" TM"~%¢~

"~ ~~"~"~"~—~F"~"~"~""~V"—/~—~"~"~7V"~""%§¢—————— 7
2
INTEGER =
— INTERVAL
(Fixed)

Subroutine World

MR-S-1627-81

5.2.3

How the Subroutine Interprets Single-Precision Numbers

Acceptable input and output values for the RHISTI subroutine are single-

precision integers in the range of 0 to 65535; single-precision positive in-

tegers in FORTRAN have a range of 0 to 32767. This apparent conflict is

actually a matter of interpretation and decimal representation of the nega-

tive numbers in FORTRAN; it is easily resolved, as we shall explain.

In theory a 16-bit binary number can represent a decimal number as large

as 65535. In FORTRAN this range is divided into two parts: values from 0
to 32767 are interpreted and used as positive integers; values in the other

half of the range are interpreted and used as negative integers. In
FORTRAN negative numbers ranging from -32768 to -1 correspond directly to binary numbers ranging in decimal value from 32768 to 65535.

The RHISTI subroutine does not process or report values less than zero.

Therefore all input and output values are treated as unsigned so that we

can use the full positive range of the 16-bit word.

You may well ask “How does this interpretation of the data by the subroutine affect my particular application?” The answer is:
1.

All input values and all resulting output data less than 32768 (2) are

treated in exactly the same way by the subroutine and by FORTRAN

(Figure 5-2).

If either your input data or the resulting output contain values greater

than 32767 (but not greater than 65535), they are interpreted as negative by FORTRAN but not by the subroutine. For example, if the sub-

routine outputs a single-precision integer value of 40,000, FORTRAN

interprets it as -25536.

The Interval Histogramming with Reference Points (RHISTI) Subroutine

-3

Figure 5-2:

Relation between FORTRAN Integers and Unsign
ed
Binary Values
FORTRAN Interpretation (2s Complement)

32767

=-32768. . .

32767. . .,

65535

Unsigned 16-Digit Binary Value
MR-S-1628-81

We shall now present a simple mechanism for converting
a value that
FORTRAN interprets as negative to a floating-point number equal
to the
unsigned interpretation of the value. This conversion may
not always be
necessary; some operations, such as addition
and subtraction, are unaf-

fected by the signs of the operands. The unsigned results of such
an operation would be correct so long as the results were not less than 0 or
greater
than 65535. However, operations such as division and multiplication,
or
printing and typing, are affected by the FORTRAN interpre
tation of unsigned numbers larger than 32767 as negative numbers. The followin
g two
methods can be used to convert unsigned single-precision numbers
to

floating-point numbers:

R = (1-(N/IABS(N))/2) * 65536. + N
or

R=N
IF (N.LT.0)R = 65536. + N
where R is the floating-point variable equivalent to the unsigned
singleprecision integer stored in N, and IABS(N) is a function available
from the

FORTRAN library.

To convert a floating-point number less than 2'° to an unsigned integer, you
can use one of the following equations:

N = R-65536. * IFIX (R/32768.)
or

N = R-65536.
IF (R.LT.32768.) N = R

where R is again the floating-point variable, N the unsigned integer stored
in N, and IFIX is a function available from the FORTRAN library.

5-4

The Interval Histogramming with Reference Points (RHISTI) Subroutine

5.3

How to Present Your Problem to the Subroutine
You can control the type and scope of the histogram(s) output by this sub-

routine by setting the appropriate parameter table elements. You must
specify the number of data elements to be processed following each refer-

ence point and define your categories of interest so that the resulting interval histogram meets your requirements. You can also specify whether a

corresponding frequency histogram is to be produced. An array of parameter values is used to pass your processing requirements to the subroutine

(Section 5.4).

5.3.1

Number of Events to be Processed Following Each
Reference Point

The number of events to be counted into the interval histogram following

detection of each new reference point is specified by the fifth element of the

parameter array (ITABLE(5)), Section 5.4. If this element is set to

zero, all

data elements following each reference point are counted into the interval
histogram. Regardless of the value of ITABLE(5), all data elements following each reference point are counted into the frequency histogram, if one

produced.

This particular feature of the RHISTI subroutine is useful for applicati

ons
In which statistical information involves a fixed number of data elements

related to each reference point. In such applications the reference
point
often represents an event that causes, or provides the stimulus for, the
data
to be histogrammed. Such data elements often represent measures
of time
or space relative to the causing event.

For example, suppose you wish to study the arrival times of the first

four

pieces of fire-fighting apparatus at the scene of a fire after
the alarm
sounds. The sounding of the alarm is the stimulus, and is represen
ted by a

reference point in the data stream; the data elements represent

time between the sounding of the alarm and the arrival of

the elapsed

the pieces of
equipment. Thus, if ITABLE(5) is set to 4 and the data are input
chronologically, the arrival times of the first four pieces of equipment
are counted
into the interval histogram. A corresponding frequency
histogram would

record the total number of pieces of equipment responding to

9.3.2

the alarm.

Describing the Categories for the Interval Histogram

The numerical intervals representing the categories of
interest to the
subroutines are defined by means of a table of parameter values
set by the
user. The first three values in the parameter table define
these intervals
(see Section 5.3):
e The first element of the parameter table defines the lower

limit of the
first interval. Data values smaller than this limit do not fall
into any
predefined category and are reported separately (see Section 5.2.3).

The Interval Histogramming with Reference Points (RHISTI

) Subroutine

5-5

e The second element of the parameter table defines the numerica

l length

of each interval. Therefore the first interval spans values greater than or

equal to the first element but smaller than the sum of the first and second
elements. Symbolically, if the first element is I and the second is J
, the
first interval spans all data, K1,, for which

I=sKl, <I+J
The second interval spans all values, K2,, for which
I+Jd=<K2<I+2-J

and so on. Note that there are J values in each interval.
e The third element of the parameter table tells the subroutine how many

intervals — starting with the value of the first element — to consider.
This element also specifies the minimum dimension of the output array

because each interval has a corresponding output array element. The
implication of this value is that the last interval of interest spans all
values, KN,, for which

I+ (N-1)-J<KN, <I+N-J

where N is the value of the third element and I and J are the values of the
first and second elements, respectively.

5.3.3

Overflow and Underflow Count

Because the intervals of interest may not span the entire range of legal

Integer input, it is possible that the input data stream may contain values
that do not fall within any specified category. The subroutine counts the

number of data values outside the upper and lower limits of the specified

categories. The number of data values that are smaller than the minimum

specified in the first element of the parameter table (Section 5.3) is called
the underflow count and is reported in the eighth element of the parameter

table. The number of values that exceed the maximum value in the interval

of interest is called the overflow count and is reported in the ninth element
of the parameter table.

9.3.4

Frequency Histogram

In addition to the other processing characteristics described, an optional

frequency or zeroth histogram can also be produced. It takes the form of an

additional output array that indicates the level of activity between each
pair of reference points. Specifically the number of input elements following

the nth reference point and preceding the n+ 1th reference point are reported as the nth element of the frequency histogram array.

5.4

How to Call the RHISTI Subroutine
The symbolic name for the interval histogramming with reference points
subroutine is RHISTI, and the general format of the FORTRAN call is:

The Interval Histogramming with Reference Points (RHISTI) Subroutine

CALL RHISTIITABLE,INPUT,IHGRAM[,IFREQ))

For reference, argument names in the call to RHISTI have been assigned

arbitrarily. You may supply your own argument names, but you must state

all of the arguments explicitly. There are no default values for any of the

arguments. If you omit an argument either accidentally or on purpose, or if
you supply too many arguments, a FORTRAN error message results and no

data is processed. The arguments are described in the following discussion.
ITABLE is an integer array of at least 16 elements used to:
e Transmit

information from the
through ITABLE(6))

user to

the

subroutine

(ITABLE(1)

e Return information from the subroutine to the user ITABLE(7) through

ITABLE(11))

* Transmit/report information to/from the subroutine on the optional fre-

quency histogram (ITABLE(12) through ITABLE(15))

e Store information on an interim basis (by the subroutine) (ITABLE(16),
ITABLE(17))

You

must

set

the

array

elements

subroutine.

that transmit

information

the

ITABLE(1)

The lower limit of the first interval (see Section 5.3.2)

ITABLE(2)

The specified interval length (see Section 5.3.2)

ITABLE(3)

The total number of contiguous intervals to be considered
(see Section 5.3.2)

ITABLE(4)

The total number of array elements containing data (starting with the first element of the input array (INPUT))

ITABLE(5)

The number of data values to be processed after each refer-

ence point is detected; if set to zero, all values are pro-

cessed (see Section 5.3.1)
ITABLE(6)

A value that must be set to zero before the initial call to
the subroutine; it signals the subroutine to initialize the

output array and other output elements in the parameter

table. On subsequent calls to the subroutine, if a different
segment of the same set of data is being processed, operation continues and there is no reinitialization.

The next group of elements is used to report information not included in the
actual histogram:

ITABLE(7)

The number of reference points detected

ITABLE(8)

The underflow, or the count of the number of input data

values that are smaller than ITABLE(1)

The Interval Histogramming with Reference Points (RHISTI) Subroutine

-7

ITABLE(9)

The overflow, or the count of the number of input data
values that exceed the upper limit of the last interval; data
values exceeding

ITABLE(1) + (ITABLE(2)- ITABLE(3))
are counted.

ITABLE(10)

The number of output array elements that have exceeded

the largest possible single-precision number (65535) (or
overflow/underflow count) (see Section 5.2.3)
ITABLE(11)

An element used to report error conditions:
=

Indicates no errors

Indicates

Indicates the ITABLE(N) is in error, for example,

=-N

Indicates incorrect number of arguments in call

that
ITABLE(3)>65535

ITABLE(1)+ITABLE(2)-

ITABLE(2)=0

The next group of elements is used to transmit/report information concern-

ing the optional frequency histogram. Note that you must set ITABLE(
12),
and that ITABLE must be dimensioned to 17 regardless of whether
a frequency histogram is produced.

ITABLE(12)

Indicator of whether a frequency histogram should be

produced:
=0
=1

Do not produce a frequency histogram
Produce a frequency histogram

It ITABLE(12)=1, the fourth argument in the
call statement must be present (IFREQ).
ITABLE(13)

The number of elements in the array used to store the
frequency histogram (the dimension of IFREQ in the
CALL statement)

ITABLE(14)

Number of frequency histogram elements already calculated; will be set by the subroutine to 0 for the initial call

to RHISTI, when ITABLE(6) is 0. ITABLE(14) is updated

continuously as input is processed by the subroutine. Be-

cause elements of this histogram are calculated sequentially, data from the storage array may be extracted each

time the subroutine has processed all data in the input
array and returned to the calling routine. If elements are

extracted, ITABLE(14) may then be adjusted to reflect
where the next element of the frequency histogram is to be

stored.

ITABLE(15)

The current partial count for the next ITABLE(14)+1)
entry in the frequency histogram; each time another refer-

ence point is detected, ITABLE(14) is updated and the next
entry is placed in the histogram.

The Interval Histogramming with Reference Points (RHISTI) Subroutine

The next elements are used only by the subroutine:
ITABLE(16),

Elements used exclusively by the subroutine for internal
storage

ITABLE(17)

INPUT is an integer array containing the data to be processed. All data

are treated as positive and unsigned (see Section 5.2.3). All input elements equal to zero are interpreted as reference points (see Section
5.2.1). The number of array elements to be processed is ITABLE4), and

processing always begins with the first element of the array. Note, how-

ever, that all data need not be placed in the array at one time. Instead,
one array of data can be processed, the array refilled with new data, and

the subroutine called again to process the array of data a second time. It

1s possible to continue in this piecemeal fashion until all data have been
processed. In real-time applications such a processing cycle becomes an

ongoing function.

IHGRAM is an integer array to store the results of interval histogram
processing; each array element is devoted exclusively to one of the nu-

merical intervals that represents a single category. The order of the
array elements corresponds to the numeric order of the intervals, that is,

the Nth element of the output array will have a value equal to the
number of data elements in the input stream that belong in the interval.

LITABL
+ (N-1)-ITA
E(1
BLE(2)]
) to [ITABLE(
+ N-ITABLE
1)
(2) - 1]
IFFREQ is an array required only when ITABLE(12)=1 and is used to
store the frequency histogram data. This integer array must be at least
as long as specified by ITABLE(13). Upon return, ITABLE(14) notifies
the user how many elements in the array contain data.
If you remove data from the array before a subsequent call to the subrou-

tine, you can adjust ITABLE(14) before reentry to reflect the additional
storage space now available.

If the number of array elements available for storage is not large
enough, that is, if ITABLE(14) becomes larger than ITABLE(13), the
subroutine stops computing the frequency histogram (but continues to

process interval histogram data). If this condition arises, frequency his-

togram data may be lost. To correct this problem, make ITABLE(14)
smaller than ITABLE(13). ITABLE(14) indicates the number elements

lost ITABLE(14)-ITABLE(13)).

9.5

Input and Output — Using the Subroutine
As previously stated, all data for a particular histogram
need not be available, or even known, before processing begins. Initialization
takes place (all
counters are set to zero) only when ITABLE(6) equals

zero. Parameter table

elements are also checked for correctness when ITABLE(6)
equals zero.

The Interval Histogramming with Reference Points (RHISTI

) Subroutine

-9

Before the subroutine returns, it automatically changes ITABLE(6)

so that
if a subsequent call is made to process new data for the same histogra
m,

processing continues as though no interruption had taken place.

entire set of data for one histogram can be processed at one time,

Thus an

memory

space permitting; or, if the user wishes, the data can
be processed one

segment at a time. The value assigned to ITABLE(4)
should indicate the

number of elements in the input array to be processed for a specific

call.

The subroutine is position-independent and reentrant. Although these
tures are of interest mainly at the system level, they do result in

fea-

additional

advantages at the user level. Perhaps most significant is that several

data

streams can be processed simultaneously. All pertinent informat
ion concerning the history of a data stream is contained in the ITABLE
array

rather than in the code for the subroutine. Imaginative use of the
ments in the subroutine call should make the subroutine functiona

argu-

lly compatible with any application that uses interval histogramming
of data
relative to reference points.

9.6

Modifying the Subroutine — Using Options
The following sections explain which options you can use with the interval

histogramming with reference points subroutine. If you want to use any of
the options, you must enable them when you build the subroutine from the
source file using the interactive build procedure (see Section 1.1).

9.6.1

EIS (Extended Instruction Set)

Enable this option if your installation has EIS (KE11-E) hardware or any
other floating-point option available. Enabling this option increases the
execution speed and decreases the memory requirements for the subroutine
by approximately 121 words if DPRS$ is not enabled, and by approximately
123 words if DPRS$ is enabled.

5.6.2

EAE (Extended Arithmetic Element)

Enable this option if your installation has EAE (KE11) hardware available.

Enabling this option increases the execution speed and decreases the memory requirements for the subroutine by approximately 87 words.

9.6.3

DPRS$ (Double-Precision Integers)

If the range of data values to be histogrammed exceeds 65535 (2'°-1), this
conditional option must be enabled. Note that if you are using a copy of the

subroutine in which the symbol DPR$ has been enabled, you must provide
your data to the subroutine as follows:

e All input data must be double-precision integer, that is, the second argu-

ment in the FORTRAN CALL
INTEGER*4 array (or equivalent).

5-10

statement,

INPUT,

must

The Interval Histogramming with Reference Points (RHISTI) Subroutine

e Because this option expands the possible range of input values by a factor

of 2'°, the range of variables used to define the exact range of interest
must also be expanded by 2'°. Therefore the first argument in the
FORTRAN CALL statement, ITABLE, must also be an INTEGER*4 array or the equivalent. ITABLE(1) and ITABLE(2) can then select the
range of interest.

Enabling this option has no effect on the output because the range of input
values does not affect the size of output values.
If DPR$ is enabled, the size of the subroutine increases by approximately

74 words.

5.7

Examples of Input/Output Variation Using the RHISTI

Subroutine
The three examples presented here process equivalent sets of data in similar ways but focus on different capabilities of the RHISTI subroutine.

Example 1 is based on the distributed version of the subroutine. A set of
10,000 random integers ranging from 15 to 225 is processed, 500 at a time.
Each sequential set of input points is stored in alternate halves of the

INPUT array to simulate real-time applications, which conserve processing
time by collecting and processing data in parallel.

NOTE
If you use FORTRAN 77 and you want to duplicate the terminal output for the example programs, replace the standard
random-number generator in F4POTS with F4PRAN.OBJ.
Terminal output for the example programs is based on the
FORTRAN IV random-number generator. The FORTRAN 77

random-number

generator

different

from that for
FORTRAN IV and will not produce the same output. See
Section B.1.

Categories of interest comprise 40 intervals of five integers each; the mini-

mum value for the first interval is 20. When processing is complete, the
following output is typed on the terminal:

e The total count of data items belonging to each category, that is, the
interval histogram (IHGRAM)
e The total number of reference points detected (ITABLE(7))

¢ The number of data items smaller than the total interval of interest, that
1s, the underflow count (ITABLE(8))

e The number of data items larger than the total interval of interest, that
is, the overflow count (ITABLE(9))

e The

total

number

output

counters

that

have

exceeded

65535

The Interval Histogramming with Reference Points (RHISTI) Subroutine

5-11

(ITABLE(10))

RHISTI Example #1

The Interval Histogramming with Reference Points

(RHISTI) Subroutine

o—-13

IOl
mimCmICIONOLS

RHISTI Example #1
DIMENSION ITABLE(17) »INPUT(1000) ,ITHGRAM(40)

EQUIVALENCE (ITABLE(1),1S8) (ITABLE(2) +IW)

DATA ITABLE/20+5+40+500,13%0/

DATAI1+12/0,0/
DO 2 J=2,21
N=300#MOD(J2)+1

DO 1

I=NsN+499

K=RAN(I1,12)%#210+1S

M=K/80

IF(M*B0.EQ.K) K=0

INPUT(I)=K

CALL RHISTI(ITABLE »INPUT(N) »IHGRAM)
IF(ITABLE(11).EQ.0) GO TO 2

TYPE 1000,ITABLE(11)

1000

FORMAT(’ ERROR INDICATOR =

’413)

STOP

CONTINUE
TYPE 900

900

FORMAT(1
T30+ 'RHISTI
H1 Example 81’ ,//)
TYPE 2000

2000

FORMAT(2BX)» 'RESULTING HISTOGRAM'//
1

4c¢’

INTERVAL COUNT ") /)

(o)

TYPE 3000, ((N-1)*IW+IS ,N#IW+IS,IHGRAM(N)
sN=1,40)

é) 3000

FORMAT(A(I7,'-'414,18))

TYPE 4000, (ITABLE(1) y1=7,10)
4000

FORMAT(//,’

NO,

OF REFERENCE POINTS
=

" UNDERFLOW COUNT =

“ 13/

4,134/’ OVERFLOW COUNT =

" NO., OF COUNTERS WHICH OVERFLOWED =

' ,13,/,

*,12,/7/)

CALL EXIT
END

o-14

The Interval Histogramming with Reference Points (RHISTI) Subroutine

@ Define array elements and their sizes; use equivalence of convenience.
@

Set parameter table elements: there are 40 intervals’of interest, start-

ing at 20, and comprising five elements each; input array contains 500

data elements; set ITABLE(6) to zero to signal initialization (no fre-

quency histogram is produced); set number of data values to be processed after each reference point to zero to signify that all values are
to

be processed.

Initialize random number generation variables.
Provide 20 sets of data (500 points each) for processing.

Determine which half of the input array is to receive the next

set of

Determine next set of random numbers for processing; produce

some

input data.

zero values (reference points).

Process next set of input values:

ITABLE contains parameter table
INPUT contains input for processing, starting at subscript N

@ Q

IHGRAM is array where interval histogram is stored
End of data generation and processing loop
Type output:

Interval histogram (IHGRAM)
Number of reference points detected ITABLE(7))
Underflow (ITABLE(8)); overflow (ITABLE(9)); counter overflow

(ITABLE(10))

The Interval Histogramming with Reference Points (RHIST

I) Subroutine

count

Terminal Output
RHISTI

Example #1

RESULTING HISTOGRAM

INTERVAL

NO.

COUNT

INTERVAL

COUNT

INTERUVAL

COUNT

INTERVAL

20-

214

29-

232

30 -

224

40-

45-

35-

248

253

GB5-

23
-

243

215

GO-

20-

226

70-

242

75-

239

BOo-

199

85-

234

90
-

248

216

105-

95-

100

105

110

245

253

110-

115

225

115-

120

231

225

120-

125

239

125-

130

212

140-

130-

145

135

240

145-

135-

150

220

140

160-

165

150-

135

191

254

165-

170

155-

160

229

170-

247

180-

175

1895

237

264

185-

175-

190

180

225

250

190-

195

226

200

2095

237

205-

210

195-

200-

213

210-

215

247

215-

236

OF REFERENCE POINTS =

OVERFLOW COUNT

5-16

239

100-

114

UNDERFLOW COUNT
= 240

NO.

COUNT

228

OF COUNTERS WHICH OVERFLOWED
= 0O

The Interval Histogramming with Reference Points (RHISTI) Subroutine

RHISTI Example #2

Example 2 is identical to Example 1 except that a frequency

produced in addition to the results output in Example 1.

histogram is

The Interval Histogramming with Reference Points (RHISTI) Subroutine

5-17

RHISTI Example #2
DIMENSION ITABLE(17) yINPUT(1000) ,IHGRAM(40) JIFREQ(120)
EQUIVALENCE (ITABLE(1),IS) +(ITABLE(2) »IW)
DATA ITABLE/20,+,5,40,S500,7%#0,1,120,4%0/

DATA I1,12/70,0/
DO 2 J=2,21

N=300%#MOD(J,2)+1
DO 1

I=N,N+499

K=RAN(I1,I2)%#210+13

M=K/80

IF(M*BO.EQ,K) K=0

INPUT
(1) =K

CALL RHISTI(
»INPUT(N)
ITABLE
yIHGRAM,IFREQ)
IF(ITABLE(11),EQ.0O)
GO TO 2

TYPE 1000,ITABLE(11)

1000

FORMAT(’
ERROR INDICATOR = *,13)

STOP
CONTINUE

TYPE 900

900

FORMAT(1H1
T30 'RHISTI Example 82/ ,//)
TYPE 2000

2000

FORMAT(28X)»'RESULTING HISTOGRAM '/ /,
1

4¢’

INTERVAL COUNT ") /)

TYPE 3000 ((N-1)%#IW+IS,N*#IW+IS»IHGRAM(N)
yN=1,40)

3000

FORMAT(A(I74'-",144+18))
TYPE 4000, (ITABLE(I) »1=74+10)

(§)

4000

FORMAT(//
4+’ NO,

OF REFERENCE POINTS
= 4134/,

1 “ UNDERFLOW COUNT = ' y13+/ ' OVERFLOW COUNT = ' 4,134/
2

" NO.

COUNTERS WHICH OVERFLOMWED =

’412,4//)

TYPE 5000
5000

FORMAT(///20X,'CORRESPON
FREQUENCY HISTOGRAM
DING
'/ /
1

5¢7

ENTRY COUNT ") /)

I=ITABLE(14)

IFC(ITABLE(14) .GT.ITABLE(13))

I=1ITABLE(13)

TYPE 7000, (N»IFREQ(N)
yN=1,1)

7000

FORMAT(S(18+16))
CALL EXIT
END

5-18

The Interval Histogramming with Reference Points (RHISTI) Subroutine

@ Define

array

elements

and

convenience.

their

sizes;

use

equivalence

for

@ Set parameter table elements: there are 40 intervals of interest, starting at 20, and comprising five elements each; input array contains 500

elements; set number of data values to be processed after each refer-

ence point to zero to signify that all values are to be processed; set
ITABLE(6) to zero to signal initialization; indicate that frequency his-

togram should be produced and set number of elements in frequency

histogram array.

Initialize random number generation variables.
Provide 20 sets of data (500 points each) for processing.
Determine which half of the input array is to receive the next set of

Determine next set of random numbers for processing; produce some
zero values (reference points).

input data.

Process next set of input values:
ITABLE contains parameter table
INPUT contains input for processing, starting at subscript N

IHGRAM is array where interval histogram is stored

IFREQ is array where frequency histogram is stored

Check for error on return.
End of data generation and processing loop

Type output:
Interval histogram (IHGRAM)
Number of reference points detected (ITABLE(7))
Underflow (ITABLE(8)); overflow (ITABLE(9)); counter overflow count

(ITABLE(10))

Frequency

histogram

ITABLE(14))

(IFREQ(N),

where

ranges

from

The Interval Histogramming with Reference Points (RHISTI) Subroutine

5-19

Terminal Output
RHISTI

Example #2

RESULTING HISTOGRAM
INTERVAL

COUNT

INTERVAL

214

29
-

248

as
-

243

65-

199

85-

248

105-

110

245

235

125-

130

INTERVAL

COUNT

INTERVAL

COUNT

30-

272

35-

S0-

)

215

29
-

70-

242

234

75
-

90-

239

216

95-

100

110-

115

233

223

115-

120

130-

135

231

240

135-

140

150-

155

229

254

155-

160

170-

175

247

264

175-

180

2350

253

239

145

145-

150

165

191

165-

170

185

237

185-

190

2y
e
e

190-

195

203

237

205-

210

195-

213

200

210-

229

215

247

215-

220

236

NO.

OF REFERENCE POINTS =
UNDERFLOW COUNT
= 240
OVERFLOW COUNT
= 22

NO.

COUNT

220

229

”y

114

OF COUNTERS WHICH OVERFLOWED
= 0

CORRESPONDING FREQUENCY HISTOGRAM

ENTRY

COUNT

ENTRY

COUNT

ENTRY

COUNT

ENTRY

CO UNT

119

206

~
<

124

130

161

101

433

126

1295

323

224

o—-20

COUNT

209

10
47

192

164

133

158

1351

134

149

376

103

245

147

139

113

181

306

100

101

102

166

103

104

106

275

135

107

105

430

108

111

109

112

110

113

60O

The Interval Histogramming with Reference Points (RHISTI) Subroutine

RHISTI Example #3

Example 3 is identical to Example 2 except that each input data element
increased by a factor of 65536(2'®) and must therefore be represen

double-precision integer. The distributed version of the subrouti

ted as a

ne cannot
process double-precision integers. The subroutine must be
built from the
source file with DPR$ enabled in order to produce an object
file capable of
processing double-precision input (see Section 5.6.3 and Section
1.1).
Example 3 illustrates how the proper version of the

subroutine processes
double-precision integers. Input values are exactly 65536
times those processed in previous examples, and output is analogous
to that in Example 2

Note that when double-precision integers are processed,

both the input ar-

ray and certain of the parameter table values must
be double-precision
integer (data type INTEGER*4). Because the 1st
and 2nd parameters of
ITABLE are increased by 65536, categories of interes
t are increased so that

their relation to input remains the same as in Examp
le 2. Thus output from
Example 3 is identical to that from Example 2.
Because this example uses FORTRAN 1V, double-precisi
and INPUTD are equivalent to single-precision arrays

on arrays ITABLD
ITABLE and INPUT

of the same length; thus values for the double-precisi
on elements can be set
via their single-precision equivalents.

The Interval Histogramming with Reference

Points (RHISTI) Subroutine

5-21

(DO @O

RHISTI Example #3
DIMENSION ITABLE(34) »INPUT(2000) ,JHGRAM(40) ,IFREQ(120)

INTEGER*4 ITABLD(17) +INPUTD(1000)

EQUIVALENCE
1

(ITABLE(2)+IS),IW)
s(ITABL
»(ITABLE,ITAB
E(4)
LD) ,
(INPUT»INPUTD)

\DATA ITABLE/0,20,015+404+0,+500,15%
40,120 ,9%0/
0,1
DATA INPUT/2000%0/
DATA I1,12/0,0/

DO 2 J=2,21
N=300#MOD(J,2)+1

DO1 I=N#2,(N+499)%2,2
K=RAN(I1,12)%#210+15

M=K/80

IF(M*B0.,EQ.K)
K=0

INPUT(I)=K

CALL

RHISTI(ITABLD»INPUTD(N) »IHGRAMIFREQ)

IF(ITABLE(21).EQ,0)
GO TO 2
TYPE 1000,ITABLE(21)
1000

FORMAT
ERROR INDICATOR
(’= *,13)

STOP

CONTINUE
TYPE 900

900

FORMAT(1H1,T30)'RHIS
Example #3’,//)
TI

TYPE 2000

2000

FORMAT(28X»'RESULTING HISTOGRAM'//
1

4¢’

INTERVAL " +vBX) +/d ("’

X Z##16 COUNT ") /)

TYPE 3000, ((N-1)*#IW+IS N*#IW+IS,IHGRAM(N)
yN=1,40)
3000

FORMAT(A(I7,'-",14,16))

4000

FORMAT(//
' NO., OF REFERENCE POINTS
= ' 413,/

TYPE 4000

()

€)

(ITABLE(I) »1=13,19,2)

1 * UNDERFLOW COUNT = 413,/ OVERFLOW COUNT = *,I3,/,

' NO., OF COUNTERS WHICH OVERFLOWED =

“4y12,//)

TYPE 5000

5000

FORMAT(///20%,'COR
FREQUENCY
RESPONDIN
HISTOGRAM '/ G
/

5¢7

ENTRY COUNT ") /)

I=ITABLE(27)
IF(ITABLE(27).GT.ITABLE(25))
TYPE 7000

7000

I=ITABLE(25)

(NsIFREQ(N) yN=1,1)

FORMAT(5(18+16))

CALL EXIT
L

522

END

The Interval Histogramming with Reference Points (RHISTI) Subroutine

Define array elements and their sizes; use equivalence for conven1ence; note that ITABLD and INPUTD are double-precision.

Set parameter table elements: there are 40 intervals of interest, starting at 20-2'° = 1,310,720, and comprising 5-2'¢ = 327,680 elements

each; input array contains 500 elements; set number of data values to
be processed after each reference point; set ITABLE(6) to zero to signal
Initialization; indicate that frequency histogram should be produced
,

and set number of elements in frequency histogram array.
Clear high and low parts of double-precision input.
Initialize random number generation variables.
Provide

sets

of data

(500

double-precision

processing.

points

each)

Determine which half of the input array is to receive the next set
input data.

for

Determine next set of random numbers for processing; place random
number range from 15 to 255 in high order part of the double-precision

integer array ITABLD via ITABLE, effectively producing random
numbers in the range of 15-2'° to 225-2'¢; produce random zero values
(reference points).

@ Process next set of input values:
ITABLD contains parameter table
INPUT contains input for processing, starting at subscript N

IHGRAM is array where interval histogram is stored
IFREQ is array where frequency histogram is stored

@ Q

Check for error on return.
End of data generation and processing loop

Type output:
Interval histogram (IHGRAM)
Number of reference points detected (ITABLD(7))

Underflow (ITABLD(8)); overflow (ITABLD(9)); counter overflow count

(ITABLD(10))

Frequency

histogram (IFREQ(N),
ITABLD(13)=ITABLE(25))

where

The Interval Histogramming with Reference Points (RHISTI)

ranges

from

Subroutine

5-23

Terminal Output
KHISTI

Example #3

RESULTING HISTOGRAM

INTERVAL
N

NO.

INTERVAL

2%*16

COUNT

2%%16

INTERVAL
COUNT

20-

214

25-

40-

495

248

45-

60-

GBS

243

65-

go-

199

85-

245

100-

105

248

105-

110

120-

125

235

125-

130

140-

145

229

145-

150

2%%16

INTERVAL
COUNT

2%%106

COUNT

30-

S50~

855

215

2
[y

70~

242

75-

234

239

90-

216

95-

100

110-

2393

115

229

115-

120

130~

231

135

240

135-

140

220

150-

225

155

2354

1535-

160

247

253

35-

239

99~

160-

1695

191

165-

170

[
.

170~

180-

185

175

237

264

185-

175-

190

180

229

190~

2390

[y
.

200-

205

195

237

205-

210

195-

200

213

210-

225

215

247

215-

22¢

236

OF REFERENCE POINTS =

114

ENT RY

COUNT

UNDERFLOW COUNT
= 240

OVERFLOW COUNT
= 22
NO. OF COUNTERS WHICH DVERFLOWED
= O

CORRESPONDING FREQUENCY HISTOGRAM
ENTRY

o024

COUNT

ENTRY

COUNT

ENTRY

COUNT

ENTRY

COUNT

119

206

124

130

161

101

433

126

125

323

224
44

“

209

10
a7

°d

192

164

133

158

151

134
81

2
<L

149

376

103

245

147

139

113

101

106

135

111

181

835

306

1 Q0

102

166

103

104

275

1 03

107

430

108

109

112

1 10

60O

113

The Interval Histogramming with Reference Points (RHISTI) Subroutine

FAST FOURIER TRANSFORM (FFT) SUBROUTINE
FORMAT:
CALL FFTOIERROR,N,IREAL,IMAG,INVRS,ISCALE)

Where:
IERROR

1s an integer variable used to report errors.

1s an integer variable specifying the number of elements to be
transformed.

IREAL

1s an integer array containing the real portion of input or

output data.
IMAG

1s an integer array containing the imaginary portion of the
input or output data.

INVRS

1s an integer variable indicating whether FFT is to perform a
forward or inverse transform.
0 = a forward transform
1

ISCALE

= an inverse transform

1s an integer variable set by FFT to indicate scaling factor
(number of times results have been divided by 2).

FILE NAMES:
FAFFT.MAC (source file); FAFFT.OBJ (object file)

OPTIONS:
e

EIS

EAE

(Extended Arithmetic Element — KE11)

F MAXN

(Maximum Array Size)

(Extended Instruction Set — KE11-E)

APPROXIMATE SIZE OF SUBROUTINE (IN WORDS):

If the following options are enabled:
NONE

EIS

EAE

F.MAXN=1024

798

662

668

F.MAXN =2048

1004

918

924

F.MAXN =4096

1516

1430

1436

F.MAXN =8192

2540

2454

2460

TYPICAL EXECUTION SPEED:

With PDP-11/34 and EIS enabled:

900 Points/second.

With PDP-11/03 and EIS enabled:

320 Points/second.

Chapter 6
The Fast Fourier Transform (FFT) Subroutine

The fast Fourier transforms (FFT) subroutine provides an efficient means

of numerically approximating analytical or continuous Fourier transforms.

This chapter discusses the fast Fourier transform (FFT) subroutine, describes the subroutine’s FORTRAN call, and outlines the requirements for
the subroutine’s use. Before discussing the FFT subroutine, however, this
chapter presents an introduction to Fourier transforms.

6.1

An Introduction to Fourier Transforms
The Fourier transform converts functions in the time domain to expressions

in the frequency domain. Figure 6-1 shows the effect of the Fourier
transform.

Figure 6-1:

The Fourier Transform

| #(t) = COS(t)
1

F(f)

iF(j)

iG()

H(f)

|iH(f)

1900 =5 SIN (21)
5

h(t) =sc|:r:)(§t) +.5°
)

6-1

The Fourier transform separates a function of time into a set of sinusoids

that are represented by a complex-valued frequency function. Each non-

zero value of the frequency function indicates that a sinusoid at that frequency is a component of the original time function. The value of the
frequency function for a given frequency is equal to the amplitude of the

associated sinusoid.
The real components of the complex-valued frequency function indicate

sinusoids that are even functions, that is, are functions having the property
ft) =1(t)

Conversely, the imaginary components of the complex-valued frequency
function indicate sinusoids that are odd functions; that is, they are functions having the property
ft) =-f(-t)

There 1s also an inverse Fourier transform. The inverse Fourier transform

converts a function in the frequency domain to an expression in the time

domain.

6.1.1

Mathematical Definition of the Fourier Transform (CFT)

The analytical expression of the Fourier transform is called the continuous

Fourier transform (CFT). Mathematically, the CFT is represented as:
o0

H(f)=| ht)-e?
> tdt
-0

The inverse CFT function is represented mathematically as
o0

—Q0

Where:

6.1.2

isV
1.
h(t)

is the time function to be transformed.

H(f)

is the Fourier transform of h(t).

1s time.

is frequency.

Mathematical Definition of the Discrete Fourier Transform

(DFT)
A digital computer cannot perform the integration indicated by the expression for the CFT. A digital computer only can deal with discrete data

6-2

The Fast Fourier Transform (FFT) Subroutine

points. Thus, the FFT subroutine must use a method known as the discrete
Fourier transform (DFT) to approximate the CFT at discrete frequencies.

The DFT does not process a continuous function. Instead, it processes discrete points that give only an approximation of the continuous function.

The DFT is represented mathematically as

H(R.gi) =

N-1

hlkedt)e 5275 for n=0,12,..,N-1

k=0
The mathematical expression of the inverse DFT is

N-1

hed= &+ >0

_n_

i.2.mn-k
.
H(Reqt)
e "N fork=0,
12,..N-1

n=0

Where (in addition to those terms explained for the CFT in Section 6.1.1):
is the number of sample input values from h(t) or H(f).

Although the FFT subroutine uses the DFT algorithm as a model,
it also
takes advantage of certain computational shortcuts to reduce
the time required to evaluate the resulting values. Because of this computational
time
reduction, the shortcut method used by the subroutine is known
as the fast
Fourier transform (FFT).

The results of FFT algorithm differ from the results of DFT algorit

hm only
by a known scale factor. (See Section 6.3 for a description of
the scale
factor.)

6.2

Comparing the Continuous and Discrete Fourier Transform
In general, largely because of different inputs, the results of the

FFT and
the DFT only resemble the expected results of the CFT. Only under
certain
special conditions do the FFT and the DFT produce the same
results as the
CFT for corresponding frequencies.
The following sections describe the special conditions in which

the CFT produce identical output. They also explain, without

the FFT and
formal proof,

how and why some discrepancies arise between the CFT and the

FFT.

NOTE

These sections do not provide an exhaustive explanation of
the discrete approximations to the Fourier transform, the dis-

crepancies that generally result, or the methods needed
to
minimize these discrepancies. For such a description, see
a
good, general text such as The Fast Fourier Transform
by
E. Oran Brigham.

The Fast Fourier Transform (FFT) Subroutine

6-3

6.2.1

Comparison of FFT and CFT Input

The input to the DFT or the FFT for a function differs significantly from

the input to the CFT for the same function. Input to the CFT is typically a

continuous function defined for all values of time. Input to the FFT for the

“same” function must be a finite set of discrete samples of the input func-

tion to the CFT.

This inherent difference between the actual input to the CFT and the
actual input to the FFT is the most significant element causing discrepan-

cies between the expected and the actual results of the FFT.

To determine what the expected results of the FFT should be, you should
examine the results of the analytic CFT performed on the actual input to
the FFT. Mathematically, an expression for the input to the FFT would be:

g(t) = h(t)

Ay (t) - x(t)

Where:

1s time.

g (t)

is the input to the FFT.

1s the multiplication operation.

h (t)

is the original assumed input.

A, (t)

is the sampling function.

The

mathematical

representation

of the

sample

function is
oC

Z o (t—-k - dt)
k = ¢

where:

1s the impulse or the Dirac delta
function.

the

time

interval

between

samples.
X (t)

1s the truncation function.

The truncation function defines the total length of the sampling period. If

the function h(t) is to be sampled during a time duration, T,, then:
x (t)
= 1, for

-dt
d
?St<TO-—-§-

and
x (t) = O for all other values of t.

Figure 6-2 shows the relationship between FFT and CFT input. It also
provides a graphic representation of the relationship of h, A,, x and the
resulting g (t).

6—4

The Fast Fourier Transform (FFT) Subroutine

In Figure 6-2,
h(t) = A-COS (Bt)

To=2n/B

dt = T,/ 16
Figure 6-2:

The Relationship Between FFT Input and CFT Input
.h(t) = A *COS (BY)

X(1)

]

| |t
)

-—

—

MR-S-1630-81

6.2.2

Comparison of FFT and CFT Output

Given the mathematical expression for g(t), the actual CFT of g(t) can be
derived analytically. Three facts allow this derivation.
1.

The CFT of h(t) is assumed to be known.

The Fourier transforms of Ay(t) and x(t) are well known.

The Fourier transform of the product of two functions is demonstrably
equal to the convolution of the transforms of the functions.

Thus,

FFT is

a mathematical expression for the CFT of the actual

G (f) =

Where:

input to the

H(f) = Ay (f) * X (f)

G (f)

is the Fourier transform (CFT) of g (t).

1s the convolution function.

H (f)

is the Fourier transform of h (t).

A, (f)

1s the Fourier transform of A, (t).

X (f)

is the Fourier transform of x (t).

Its mathematical representation is
[Tg« SIN (- Ty

)]/ (w+ T,

is frequency.

The Fast Fourier Transform (FFT) Subroutine

6-5

Figure 6-3 illustrates the transformed output of the input
in Figure 6-2.

Figure 6-3:

Output from the FFT
H

;X(f)

functions shown

-1/To

1:’T0

l
LY

AL(f)

3T,

G(f)

t1 dt

L
\

-1/dt

17,

1 dt

i
]

ATO.'zdt

{

'u‘

--X-

+H+¢+
_

17,

!
Y

P17y

—.f
3T,
MR-S-1631-81

As Figure 6-3 shows, the expected output from the DFT or FFT

— a CFT of
the continuous function h(t) — bears little resemblance to the results
that
should be obtained from the CFT of the discrete samples of h(t) that
are the
actual input to the FFT.
The result of the CFT, G(f), does not appear to be good enough

to make the
FFT a useful algorithm. However, the actual result of the FFT
is not G(f)
but rather is a set of discrete samples of G(f).

When N input values are sampled with a time interval of dt, that is:

the sample values of G (f) that result from the FFT are at frequencies

..,

For convenience,

n-1

1
T,

is referred to as df.

Figure 64 shows G(n - df) returned by the fast Fourier transform.
As shown in Figure 64, the output from the FFT (indicated by the

dots) is:

Gn-df),for0<n<N-1
and the values yielded are
Gn-df) =

A'TO
9 dt

forn=1andn=N-1

and
G (n - df) = O for other n between 0 and N - 1

6-6

The Fast Fourier Transform (FFT) Subroutine

large

Figure 6—4:

G(n * df) Returned by the FFT
- - --G(f)
eeooeoG(

iG(n/To)
|

§~

”
-

I
\_/

—

~——

\ATg 2l

1,.-1'0

VS 3.1’0 (S

N-1

To
MR-S-1832-81

Thus, the sampled results of G(f) returned by the FFT seem to correspond
well with those of H(f), the expected result for frequencies in the range 0 to
[(N - 1)/2 - df]. However, in the frequency range [N/2 - df] to [N - 1) - df],
even the sampled results of the FFT still do not render a close approxima-

tion of H(f).

Nevertheless, because of the periodicity of G(f) caused by the convolution of
H(f) with X(f), this problem area can be interpreted as part of the desired
solution. As Figure 6-3 shows, G(f) is periodic. The period of G(f)

is equal
to N - df. Thus, G(f) in the range [(-N)/2 - df] to —df is identical with G(f) in

the range [N/2 - df] to [N-1 - df ]. Therefore, the last N/2 values returned by

the FFT can be interpreted as representing this negative frequency range.
In this case, if the output is considered to be associated with the following

frequency range:

-[N/2.dfJto[(N-1)/2
- df]
or

—[1/(2-dt)] to 1/(2
- dt)
the FFT gives a close approximation of H(f).

6.2.3

Similarities and Discrepancies between FFT and CFT

Results

The case illustrated in Figure 6-3 is an unusual one. Normally, the actual

results of the FFT do not match the expected results to within a scale
factor. In fact, the example illustrated in Figure 6-3 represents the one

class of functions and uses the one sampling technique for which the results
of the FFT and the results of the CFT agree within a known scale factor.

Three conditions must be satisfied to get such agreement between the results of the FFT and the results of the CFT.
1.

The function to be transformed must be periodic and band-limited; that

is, the function’s highest frequency component must be finite.

The Fast Fourier Transform (FFT) Subroutine

The function to be transtormed must be truncated at exactly

zero integer multiple of the function’s period.

The function to be transformed must be sampled at a rate

twice the function’s highest frequency component.

All of these conditions are met in the example illustrated in

one non-

greater than

Figure 6-3.

The expression, h(t)=A + COS(Bt) satisfies the first condition.

Because T;=2 - n/B, the expression x(t) satisfies the second conditio

Because

dt
=
(2-w)/B - 16)
(implying a
sampling
(B - 16)/(2 - ), dt is greater than twice B/2 - r, the highest

component of h(t)), and the expression A, (t) satisfies the

rate
of
frequency

third condition.

If these three conditions are not met, discrepancies in the results

begin to

accumulate. For example, if the third requirement is not
met — if the

chosen value for dt is too large — then the period for G(f) is too
short. This
shortened period causes aliasing, that is, overlapping representations
of the
expected transform that produce false frequency contributions.

If the second requirement is not met, that is, if T or N is not chosen
so that
the original function is truncated at an exact integer multiple of
the period
of the h(t), the results of the FFT show a distorting effect known
as leakage.
If T is an integer multiple of the period of h(t), it causes the form of
X(f) to
be such that the samples of G(f) returned by the FFT that are not related
to
H(f) coincide with the zero’s of X(f) (see Figure 6-4). However, if T
is not

an integer multiple of the period of h(t), the results returned by the
FFT are
due in large part to the transform of the function x(t) and not just
to the
transform of the intended function h(t).

If the first requirement is not met, then either the second or the
third
condition cannot be met. This failure causes the associated discrepancies in

the results.

In general, these discrepancies cannot be totally resolved. But you

should

recognize their causes and possible effects so that you can use this
FFT

subroutine effectively.

6.3

Scaling the Results of the FFT Subroutine
As mentioned in Section 6.1, the FFT subroutine uses a scaling procedure
that is not used in the DFT algorithm.
There are two types of scaling procedure that are especially applicable to

the FFT subroutine. The first type is peculiar to the subroutine itself and
not to the FFT or DFT algorithms. The second type relates the actual sub-

routine results to those expected from the original CFT function.

The following sections describe both types of scaling procedure.

6-8

The Fast Fourier Transform (FFT) Subroutine

6.3.1

Internal Subroutine Scaling Procedure

The FFT subroutine uses internal scaling procedures that cause it to vary
from the DFT algorithm in two ways.
1.

To maximize speed, the FFT subroutine performs all operations in integer arithmetic. Thus the input and output of the subroutine are singleprecision, integer values.

However, the FFT subroutine generally cannot represent its output in
the legal integer range (+32767) of FORTRAN. Because of this limitation, the FFT subroutine must scale the output internally to fit the
FORTRAN legal range.

The fast Fourier transform subroutine indicates the scaling factor it
uses in the argument ISCALE (see Section 6.5). To obtain the actual
results of the FFT, you must scale all data by multiplying them by

2**[SCALE.

When performing an inverse transform, the FFT does not include the
factor 1/N that appears in the expression for the inverse DFT. Thus,

you must multiply the output of the inverse FFT by 1/N to duplicate the

results of the inverse DFT.

6.3.2

Relational Scaling Procedure

The relational scaling procedure is relatively simple. Its rationale however

1s complicated and must be explained in some detail. Thus, a review of
some of the information presented in previous sections is appropriate.
In Section 6.2.1, the continuous function of time, h(t) was set equal to
A - COS(Bt). It was then stated that:

CFT

ht) =A-COSB:t)e—
H(f)= =

for+

O,fOI‘f—rJ:i

Where:

CFT

B
—=

is the continuous Fourier transform.

Then h(t) was sampled and truncated to produce g(t), the input to the DFT
for the continuous function of time.

It was also shown that:

CFT

g (t) «<—>G (f)
Although G(f) bears little resemblance to H(f), the DFT produces values

G(f) that give a good approximation for the same value of H(f) when dt and
T, are chosen correctly.

The Fast Fourier Transform (FFT) Subroutine

6-9

For example

g (n - dt) 2111; Gk-df)=C:-H(k-d
Where:

1s0,...,N-1.

is0,...,(N-1)/2,-N/2,...
1.

is 1/(N - dt).

is the scaling component.
is the multiplication operation.

In the above example, because h(t) is periodic and band-limited, and
because dt and T, were chosen correctly,
G(k= C:-H
df
k- )
df)
In Section 6.2.2, it was shown that
G(k-df) = _g_g‘_to

= 0,

for k-df
= =+

"fi;

Ty n=0, 1, £2, +3, ... +x

fork-df#t—%; + B

From the above expression, and from H(f) given previously, it follows

that

C="T,/dt
Furthermore, because
dt = T,/N
it follows that

C=N

Where:

N is the total number of samples.

Thus, for the example we have

Gk-df) = Nk-H
df)
or

1/N-G(k-df) = H(k-df)
In general, if h(t) is periodic,
1/N-G(k-df)=
(k - df)
H

Here it must be stressed that factor 1/N is not part of the DFT. Factor 1/N

1s a direct result of the approximation that resulted in g(t) from h(t). The

DFT of g(t) is G(f), not 1/N + G(f). To summarize, if

CFT
h (t) «<—H (f)
then

6-10

The Fast Fourier Transform (FFT) Subroutine

DFT
h(t)
- dt)=g
«<—G (n
(k - df)

Where:

=0,...N-1

=0,...(N-1)/2,-N/2,...
-1

The description given above also applies to the output
of the FFT subroutine for a forward transform (from time to frequency
domain) because the
results of the DFT and the results of the FFT subrout
ine are identical in
the forward direction.

However, this description does not apply to the output
of the FFT subroutine for an inverse transform. The output from the FFT
subroutine and the
output from the DFT differ by a factor of 1/N for the
inverse transform. This
difference is directly attributable to the DFT algorithm.
(See Section 6.1.2.)

Therefore, if
DFT

gn-dt) «—>G k -df),n=0,...
N-1
k=O,...,(N—l)/2,—N/2,...,—1
then

FFT

g(n-dt)— G (k - df)
but
FFT

(1/N)-g(
«<—
n-dt
G (k - df)
)
or

FFT

gn«<—
-d
(1 /N) -G
t)
(k- df)
But we have just determined that 1/N + G(k - df) is approx
imately H(k - df)
and, under special circumstances, is exactly H(k - df).
Thus

FFT

gn-dt) <—(1
Gk /N
-df) ~ H)(k df)
or

CFT
g(n-dt)=~ H (k- df)
To summarize the scaling procedure that fast Fourie

r transform subroutine

uses, we have

FFT
ht)~gm-dt)— G(k=N df
H (k -)
df)

and

FFT
h(t)~g
<— (1 /N):
(n
Gk -d
-df)~Ht)
(k - df)

The Fast Fourier Transform (FFT) Subroutine

6-11

Thus, if one understands the assumptions that must be made, the scaling of

the output from the FFT subroutine can be performed as follows

CFT

h(t-dt) ~7 FFT (h(t))-1/N-2

FFT(H(f))-2

ISCALE

Where:

ISCALE

t=k-dtk=0,1,... N-1

CFT
“~ H{)f=k-dfk=0,...(N-1)/2-

N/2, ... -1

h (t)

is the assumed function of time.

FFT (h(t))

is the output of the FFT subroutines for a for-

ward transform.

CFT
>

1s an approximate forward CFT.

1s the number of samples.

H (f)

the

assumed

frequency

function

transformed.

FFT (H(f))

is the output of the FFT subroutine on inverse
transform.

6.4

CFT
&

)
.
:
i1s an approximate inverse CFT.

ISCALE

is the scaling indicator the subroutine returns
to the calling program.

Useful Properties of the FFT
The fast Fourier transform has a number of useful properties. These properties are listed as follows: The fast Fourier transform has a number of useful
properties. These properties are listed as follows:

6-12

® Linearity:

h(n) +

g(n) «<—H (m) + G (m)

® Symmetry:

1/NH(@m)<— h(n)

® Time Shifting:

h (n - k) «— H (m) e 7#TMN

® Frequency Shifting:

h (n) e TMY «—— H (m - k)

® Even Function:

h (n) «<— Re [H (m)]

® Odd Function:

h (n) «— jIm [H (m)]

® Time Convolution:

h (n) * g (n) «<— H (m) G (m)

® Frequency Convolution:

h (n) g (n) «— %I— H (m) * G (m)

The Fast Fourier Transform (FFT) Subroutine

6.5

How to Call the FFT Subroutine
The general format of the FORTRAN call to the FFT subroutine is:
CALL FFTAIERROR,N,IREAL,IMAG,INVRS,ISCALE)

For reference, argument names in the call to FFT have been assigned arbi-

trarily. You may supply your own argument names, but you must state all
of the arguments explicitly. There are no default values for any of the

arguments. If you omit an argument, either accidentally or on purpose, or if
you supply too many arguments, a FORTRAN error message results and no
data is processed. The arguments are described in the following discussion.

IERROR is an integer variable used to report error conditions. The values
that IERROR can return and their meanings are given below.
0O

Noerror

N isless than eight

N is greater than 8192 or FMAXN

N s not a power of two

—n

Incorrect number of arguments in call

N is an integer variable that specifies the number of elements to be trans-

formed. N must be a value that is a power of two between eight and
whatever maximum array size you specified in the conditional assembly

parameters F.MAXN. (See Section 6.6.3 for an explanation of F.MAXN.)

IREAL is an integer array N elements long that contains the real portion
of the input data to be transformed. FFT returns the real results to this
array, replacing the input data.

IMAG is an integer array N elements long that contains the imaginary

portion of the input data to be transformed. FFT returns the lmaginary

results to this array, replacing the output data.

INVRS is an integer variable that indicates whether the subroutine is to
perform a forward or an inverse transform. The two values that you can
use in INVRS, and their meanings are given below.

INVRS =0
INVRS =1

The subroutine is to perform a forward transform

The subroutine is to perform an inverse transform

ISCALE is an argument set by the FFT subroutine. It is an integer vari-

able that indicates the number of times the results of the FFT subroutine

have been divided by two. The FFT subroutine sets the scaling factor as
necessary to overflow.

To obtain the unscaled results of the fast Fourier transform, multiply
each output element in IREAL and IMAG by (real) 2!SCALE

The Fast Fourier Transform (FFT) Subroutine

6-13

6.5.1

Interpreting the Results of the Output Arrays

Each output element returned to IREAL and IMAG as a result of
applying
the FFT corresponds to the transformed function evaluated at a
given frequency value. The frequency value at which the function

is evaluated de-

pends on the length of the period of the input function, T,. Thus,

frequency
values are evaluated at evenly spaced intervals of 1/T,, which is referred
to
as df. For convenience, the following explanation discusses IREAL
only, but
applies equally to IMAG.

The total frequency domain consists of values in the range —(N/2)-(
[(N/2)-1]-(df). Figure 6-5 shows the total range of the frequency

df) to

domain

expressed as a graph where the x axis represents frequency and the
represents amplitude.

Figure 6-5:

y axis

Total Range of the Frequency Domain

Amplitude

: Frequency

~(N/2)-df |=

-t

N
—_

—= (N/2-1).df
_

Total Range of the Frequency Domain

MR-S-1633-81

Although evaluated at evenly spaced intervals, values returned in the first

half of IREAL represent values in the second half of the frequency domain;
that is, they represent values in the range 0 to [(N/2)-1]-(df). Thus, values
returned in IREAL beginning with the first element, or IREAL(1), can

expressed as:

IREAL(1)

= G(f)
where f = 0

IREAL(2)

= G(f)
where f = df or 1/T,

IREAL3)

= G(f)

where f = 2 - df

IREAL(N/2) = G(f)

where f = (—-2- —-1) - df

6-14

The Fast Fourier Transform (FFT) Subroutine

Values returned in the second half of IREAL represent values in the first
half of the frequency domain; that is, they represent values in the range

—(N/2) - (df) to —(df). Thus, values returned in IREAL beginning with the

first element in the second half of the array or IREAL(N/2 + 1) can be
expressed as:

IREAL(N/2 + 1) = G(f)

where f =

- E
2

[ ] df

IREAL(N/2 + 2) = G(f)

where f = (— N, 1) . df
)

IREAL(N/2 + 3) = G(f)

where f = (— g + 2) - df

IREAL(N)

= G(f)

where f = (— l;- + % —1) . df or df

For

an explanation
Section 6.2.2.

of why

the

FFT

output

works

this

way,

Figure 6-6 shows five elements of the IREAL output array, each

see

of which

represents a transformed function. The figure shows
which values in the

frequency domain each element (transformed function) corresponds
five elements are:

to. The

IREAL(1)

The first element in the output array

IREAL(2)

The second element in the output array

IREAL(N/2)

The last element in the first half of the output array

IREAL(N/2 +

The first element in the second half of the output
array

IREAL(N)

The last element in the second half of the output ar-

ray. IREAL(N) is also the last element of the entire

output array.

The Fast Fourier Transform (FFT) Subroutine

6-15

Figure 6-6:

Five Elements in the IREAL Output Array

IREAL(N) ——=\

=———IREAL(2)

IREAL(N/2 + 1)

L—:oNRt

Y
|

‘\./'

”

Vi
\
\

IREAL(N/2)

4‘\,’r pET e==
’

IREAL(1)

MR-S-1634-81

6.6

Modifying the Subroutine — Using Options
The following sections explain which options you can use with the fast
Fourier subroutine. If you want to use any of the options, you must enable

them when you build the subroutine from the source file using
interactive build procedure (see Section 1.1).

6.6.1

the

EIS (Extended Instruction Set)

Enable this option if your installation has EIS (KE11-E) hardware or any

other floating-point option available. Enabling this option increases the
execution speed and decreases the memory requirements for the subroutine

by approximately 86 words.

6.6.2

EAE (Extended Arithmetic Element)

Enable this option if your installation has EAE (KE11) hardware available.

Enabling this option increases the execution speed and decreases the memory requirements for the subroutine by approximately 80 words.

6.6.3

F.MAXN (Maximum I/O Array Size)

The F.MAXN option specifies the maximum number of complex elements

that the FFT subroutine can process at one time. The maximum number of

complex elements is limited to those multiples of 1K (1024) that are powers

of 2 in the range 1K to 8K (8192). In other words, F.MAXN is limited to the
values 1024, 2048, 4096, and 8192.

F.MAXN allows you to control the size of the FFT subroutine. The FFT
subroutine uses a quarter-sine-wave, look-up table that requires a number

of elements directly proportional to the maximum size of the FFT subroutine input array.

6-16

The Fast Fourier Transform (FFT) Subroutine

F.MAXN is not enabled on the distributed object file. If you do not choose to

enable F.MAXN, the FFT subroutine uses a default value of 1024 for

F.MAXN.

If you want to use a larger maximum number of complex values, you should
redefine F.MAXN as 2048, 4096, or 8192 in the distributed source file.

Redefining F.MAXN increases the memory requirements for the FFT sub-

routine. Specifically:
1.

Changing

F. MAXN from 1024 to 2048 increases the FFT subroutine

size by 256 words.

6.7

Changing F.MAXN from 1024 to 4096 increases the FFT subroutine
size by 768 words.

Changing F.MAXN from 1024 to 8192 increases the FFT subroutine
size by 1792 words.

Example Using the FFT Subroutine
The following FORTRAN program example illustrates how the FFT sub-

routine produces both forward and inverse transforms of a specific set of
input data.

The Fast Fourier Transform (FFT) Subroutine

6-17

FFT Example #1

The Fast Fourier Transform (FFT) Subroutine

6-19

D OO

FFT Example #1
DIMENSION IR(32) +IM(32)

DATAPI/3.,141593//)IM/32%0/C/ .01/
n=0,

DO1I=1,32

T=SIN(X)

IRCI)=T*#1000,+SIGN(C.,T)
1

XK=X+DELX
TYPE 800

TYPE 900
TYPE 1001,1IR

TYPE 1002,1IM

CALLFFT(IE»329IR+IM,0O,ISF)
IF(IE) 99,2,99

IF(ISF.NE.O)
TYPE 999,ISF

O r

TYPE 1000

TYPE 1001 IR
TYPE 1002,1IM

CALLFFT(IE32yIR+IM»1,ISI)
IF(IE) 99,3,99

IF(ISI.NE.O)
TYPE 999,151

TYPE 2000

TYPE 1001 ,IR
TYPE 1002,1IM

SCAL=2.#%#(ISF+ISI)

0041=1,32
IRCI)=SCAL*#(IR(I)/32)

FEI

IMCI)=SCAL*(IM(I)/32)
TYPE 3000

TYPE 1001 IR
TYPE 1002,IM
STOP

TYPE 998, 1E
STOP

80O

FORMAT(1H1 »T25'FFT Example 81’ ,//)

900

FORMAT (" DATA TO BE TRANSFORMED - SINE WAVE SCALED BY 1000, /)

998

FORMAT(//’' THE ERROR CODE RETURNED =

999

FORMAT(// ' THE SCALE FACTOR RETURNED =

1000
@

FORMAT(//
1

’,14)

" POINTS OF A SINE WAVE ')

1001

FORMAT (/'

1002

FORMAT(/’ -

2000

FORMAT(//,’ RESULTS FROM THE INVERSE FOURIER TRANSFORM
1

3000

- REAL PART -’/,(BI18))
IMAGINARY PART - '/ ,(818))

//+32%,’- BEFORE SCALING
FORMAT(//,32X,’- AFTER SCALING - ')
END

6-20

‘' ,14)

' RESULTS FROM THE FORWARD FOURIER TRANSFORM OF 32/,

The Fast Fourier Transform (FFT) Subroutine

Define array variables and their sizes; initialize parameters external
to the subroutine, and set the value of array IM to zero.

Compute 32 values of a sine wave scaled by 1000.
Print the real and imaginary parts of the numbers to be

transformed.

Call the FFT subroutine to perform a forward transform on
values

stored in IR and IM.

If IE(RROR) is not equal to zero, print an error message; if

ISCALE is

not equal to zero, print the scaling factor.

Print the real and imaginary parts of the forward transfo

rm.

Call the FFT subroutine to perform an inverse transform

stored in IR and IM.

on values

If IE(RROR) is not equal to zero, print an error messag

e; if ISCALE is

Print the real and imaginary parts of inverse transfo
rms (before
scaling).

not equal to zero, print the scaling factor.

Compute the scaling factor.
Multiply the real and imaginary parts of the inverse transf

by the scaling factor.

orm of data

Print the real and imaginary parts of the inverse transfo
rm of data
(after scaling).

Print error messages (error code returned).
Format statements

The Fast Fourier Transform (FFT) Subroutine

6-21

Terminal Output
FFT Example

DATA
TO BE TRANSFORMED - SINE WAVE SCALED BY

1000,

382

923

-195

-382

-1000

-980

-923

IMAGINARY

PART

195

980

W
wun
— OS] = O]

1000

- REAL PART 707

831

923

707

555

382

195

-707

-831

-923

-980

-707

-555

-382

-193

980

§)

RESULTS FROM THE FORWARD FOURIER TRANSFO
OFRM
32 POINTS OF

A SINE WAVE

-7

IMAGINARY

PART

-15981

-5

-1

RESULTS FROM THE

-2

§)

-1

-4

-5

15984

31336

(R0 I o0 I o0 B AN

- REAL PART -

INVERSE FOURIER TRANSFORM

- BEFORE SCALING - REAL PART

-4

6217

12200

17749

22598

26578

293531

31972

31354

29327

26582

22604

17752

1222

-6217

-12200

-17749

-22598

-26578

-29531

-31356

-31972

-31354

-29527

-26582

-22604

-17752

-12223

-6254

IMAGINARY

6254

PART -

-12

-8

-9

-6

-2

-4

-5

-6

-17

-14

-15

-20

-4

979

AFTER SCALING - REAL PART

6-22

194

381

054

706

830

922

999

979

922

830

706

554

381

195

-194

-381

-334

-706

-830

~-999

-979

-922

-979

-922

-830

-706

-554

-381

-195

IMAGINARY PART 0O

)

The Fast Fourier Transform (FFT) Subroutine

PHASE

ANGLE

AND

AMPLITUDE

SPECTRA

(PHAMPL)

SUBROUTINE
FORMAT:
CALL PHAMPL(N,IR,IM,PH,AM)

Where:

is an integer variable that specifies the length of the input and
output arrays.

is an integer array containing the real parts of the input data.

is an integer array containing the imaginary parts of the input
data.

is a real array used to store phase angles.

is a real array used to store amplitudes.

FILE NAMES:

PHAMPL.MAC (source file); PHAMPL.OBJ (object file)
OTHER ROUTINES USED:
FLOAT, ATAN2, and SQRT from the FORTRAN library.
OPTIONS:
®

EIS

(Extended Instruction Set — KE11-E)

EAE

(Extended Arithmetic Element — KE11)

F4P$

(FORTRAN 77 compiler)

APPROXIMATE SIZE OF SUBROUTINE (IN WORDS):

If the following options are enabled:
NONE

EIS

EAE

182

138

157

TYPICAL EXECUTION SPEED:

With PDP-11/34 and EIS enabled:

180 Points/second.

With PDP-11/03 and EIS enabled:

70 Points/second.

Chapter 7
The Phase Angle and Amplitude Spectra (PHAMPL)

Subroutine

The phase angle and amplitude spectra (PHAMPL) subrout
complex values of the type produced by the fast Fourier

ine deals with

transform (FFT)

subroutine. (See Chapter 6 for more information on the FFT
subroutine.)
PHAMPL converts such complex values into phase angles
and amplitudes.

The input to PHAMPL consists of two Integer arrays. One
integer array

contains the real parts of the complex values to be convert
ed. The other

Integer array contains the imaginary parts of the comple
x values to be

converted.

The output from PHAMPL consists of two real arrays. One
tains the phase angles of the complex values. The other

the amplitudes of the complex values. All values in both

related through their subscripts.

real array con-

real array contains

real arrays are

Mathematically, the function of the subroutine can be describ

ed as:

A, = VIR + IMZ
P, = TAN" (IM/IR,)

Where:

1s the real array containing the related phase angles.

is the real array containing the related amplitudes.

is the integer array containing the real parts of the com-

plex values.

is the integer array containing the imaginary parts of the

complex values.

7-1

7.1

How to Call PHAMPL
The general format for the FORTRAN call is:
CALL PHAMPL(N,IR,IM,PH,AM)

For reference, argument names in the call to PHAMPL have been assigned
arbitrarily. You may supply your own argument names, but you must state
all of the arguments explicitly. There are no default values for any of the

arguments. If you omit an argument, either accidentally or on purpose,
or if
you supply too many arguments, a FORTRAN error message results, and
no data is processed. The arguments are described in the following

discussion.

1s an integer that defines the length of the input and output arrays.

1s an integer array containing the real parts of the complex values

to be converted.
IM

1s an integer array containing the imaginary parts of the complex
values to be converted.

1s a real array in which the subroutine stores the phase angles
from the conversion.
PH(I) = ATAN2(FLOATIM(I))/FLOATIR())

1s a real array in which the subroutine stores the amplitudes resulting from the conversion.
AM(D = SQRT(FLOATIR() - IR(I) +IM() - IM(D)))

7.2

Other Routines Used by PHAMPL
PHAMPL requires the FORTRAN library routines FLOAT, ATAN2, and

SQRT. However, you do not have to take any special steps to access these

library routines. Because the FORTRAN library is required by all
FORTRAN programs, the necessary library routines are accessed automatically when you link or task-build the program that calls PHAMPL.

PHAMPL accesses the FORTRAN 77 library and the FORTRAN IV library

differently. See Section 7.3.3 if you are using FORTRAN 77.

7.3

Modifying the Subroutine — Using Options
The following sections explain which options you can use with the phase

angle and amplitude spectra subroutine. If you want to use any of the
options, you must enable them when you build the subroutine from the
source file using the interactive build procedure (see Section 1.1).

7-2

The Phase Angle and Amplitude Spectra (PHAMPL) Subroutine

7.3.1

EIS (Extended Instruction Set)

Enable this option if your installation has EIS (KE11E) hardware or any
other floating-point option available. Enabling this option
increases the
execution speed and decreases the memory requirements

by approximately 44 words.

7.3.2

for the subroutine

EAE (Extended Arithmetic Element)

Enable this option if your installation has EAE (KE11)

Enabling this option increases the execution speed and

ory requirements for the subroutine by approx

hardware available.
decreases the mem-

imately 25 words.

7.3.3

F4P$ (FORTRAN 77 Compiler)

The distributed object file is intended for use with
the FORTRAN IV compiler. Enable this option if you are using the FORT
RAN 77 compiler.

7.4

Examples Using the PHAMPL Subroutine
The two examples presented here illustrate how to use
complex values to their corresponding phase angles

ple 1 uses random, complex numbers generated by

PHAMPL to convert
and amplitudes. Exama random-number gen-

erator. Example 2 uses output from the FFT subrout

ine.

NOTE
If you use FORTRAN 77 and you want to duplicate the
nal output for the example programs, replace the

termi-

standard

random-number generator in F4POTS with FAPRA
N.OBJ.
Terminal output for the example programs is based
on the
FORTRAN IV random-number generator. The FORT
RAN 7 7
random-number generator is different from
that for
FORTRAN IV and will not produce the same
output. See
Section B.1.

The Phase Angle and Amplitude Spectra (PHAM

PL) Subroutine

7-3

PHAMPL Example #1

The Phase Angle and Amplitude Spectra (PHAMPL) Subroutine

7-5

PHAMPL Example #1
DIMENSION IR(32) ,IM(32)+P(32)+A(32)
DATANM/0:+0/

NEXT(V)=(RAN(N,M)#1000,)-500,

DO 101I=1,32
IRCIN=NEXT(X)
<2>

IMCI)=NEXT(X)
TYPE 900

TYPE 1002,1IR
TYPE 1003,1IM

DO111I=1,32
X0=IR(I)
X1=IMC(I)

P(I)=ATANZ2
(X1 +X0)
11

ACI)=SQRT(X1%#X1+XO0#X0)

TYPE 1006,P
TYPE 1007,A
CALL PHAMPL(32,IR»IMyP,A)

TYPE 1004 ,P
TYPE 1005,A

800
1002

FORMAT(1H1+720,'PHAMPL Example 81’ ,//)
FORMAT (* RANDOM INPUT DATA'/’ REAL PART' +/+(4115))

1003

FORMAT (/'

1004

FORMAT(//

1006

FORMAT(//

1007

FORMAT (/' AMPLITUDES FROM DIRECT CALCULATIONS’ 4/ ,(4F15.5))

C‘S) 1005

IMAGINARY PART
' +/»
'

(4115))

PHASE ANGLES FROM SUBROUTINE' +»/+»(4F15.,5))

FORMAT (/' AMPLITUDES FROM SUBROUTINE ',/ »(4F15.,5))
' PHASE ANGLES FROM DIRECT CALCULATIONS ' 4/ +(4F15,.5))

STOP
END

7-6

The Phase Angle and Amplitude Spectra (PHAMPL) Subroutine

Define array variables and their sizes; initialize parameters external
to PHAMPL subroutine; define real and imaginary values of 32 ran-

©@

0 e

dom numbers to be processed.

Compute 32 random values and print real and imaginary parts.

Calculate phase angles and amplitudes for random input values and

print results.

Call the PHAMPL subroutine to calculate phase angles and amplitudes for random input values and print results.
Format statements

The Phase Angle and Amplitude Spectra

(PHAMPL) Subroutine

-7

Terminal Output
PHAMPL Example #1

RANDOM

INPUT DATA

REAL PART

IMAGINARY

-499

302

-487

-23

148

338

-393

-106

-81

326

-344

158

426

-86

-173

-182

241

132
346
-462
-180

-45

147

-194
360

448

-423

PART

-499

-496

-493

455

373

-329

-177

490

-190

326

277

-428

206

461

229

-191

-106

384

-29

334

122

-218

130

178

269

-151

PHASE ANGLES FROM DIRECT CALCULATIONS
-2.35619
-2.35921
-1,02118
V27747

-0.,87709

0.85865
2.61971

0.57654

a7
283

-2.39015

3.04596

-0,77191

-1,70002

1,88517

1,92980

-1.75784

-0,52998

1,96628

1,50539

-2.61420

1,01033

-1,53633

1.19443

1,92417

2,66973

-0,97752

0.47514

0,54075

0.34654

3,05669

3.04021

-1,38105

2.13730

666.47882

345.57922

342,80023

435.59729

AMPLITUDES FROM DIRECT CALCULATIONS
705,69257
703,57446

578.,14618

492,76059

471.68317

178.,48810

511,86325

453,34866

223,23082

229,49074

453,36188

29,01724

359.,13785

130,03461

217.,80037

262,93155

389.10153

382.,75317

522,55621

424,52914

464 .,38455

153,75955

335,39380

247.,11131

210,61813

508,13876

492,39212

377.83197

PHASE ANGLES FROM SUBROUTINE

-2+.35619

-2.,35921

-1,02118

-2+39015

3.04596

0.85865

-0,77191

-1,70002

1.27747

2.61971

-0.,87709

1.,88517

0.5765%4

-1.753784

1.96628

1.92980

-0,52998

1.,50539

-2.61420

1.01033

-1.,33633

1.19443

1,92417

2.66973

~0,97752

0.47514

0,354075

0.34654

3.05669

3.04021

-1,38105

2+.13730

345.,57922

AMPLITUDES FROM SUBROUTINE

7-8

705.,69257

703.57446

666.47882

578.14618

492.76059

471.68317

211.86325

453.34866

178.,48810

342.80023

435.,59729
377.83197

247.11131

208.13876

223.,23082

492.,39212

229.49074

4533.36188

210,61813

359.13785

29.01724

£17.80037

130,03461

262,93155

389.10153

382.75317

022.95621

464.,3845%5

424.,52914

153.7595%5

335.,39380

The Phase Angle and Amplitude Spectra (PHAMPL) Subroutine

PHAMPL Example #2

The Phase Angle and Amplitude Spectra (PHAMPL) Subroutine

-9

PHAMPL Example #2
DIMENSION AMP(32) yPHASE(32) s IMAG(32)
INTEGER REAL(32) ySCALE +ERROR
DATANI1+I2+T+»A+BC+sD/32+0+0+,0, 100, 4200,
,.5 124/
DATAPI/3.141593/IMAG/32%0/

DT=PI1/8.
CALL

RANDU(I1 yI2,X)

DO1 I=1,N

REAL (1) =A*SIN(C#*T)+B#
(-1, #%1)
COS(D
%15, #RAN(I1,1
*T)+
2)

T=T+DT

TYPE 900
TYPE 1000

TYPE 1001

REAL

TYPE 1002, IMAG

)

CALL FFT(ERROR »N»REAL »IMAG 0 ,SCALE)

IF(ERROR.NE.O) PRINT 3000 ,ERROR
CALL PHAMPL (N+sREAL »IMAG PHASE »AMP)

TYPE 2000

TYPE 1001 »REAL
TYPE 1002 ,IMAG
TYPE 2001 »PHASE

TYPE 2002 ,AMP
STOP

900
1000

FORMAT(1H1,T722,'PHAMPL Example 82/ ,//)
FORMAT(' INPUT DATAFORFFT')

1001

FORMAT(/' #%*REAL PART*%%’,/,(4116))

1002

FORMAT
(' ##*%*IMAGINARY PART*##',/,(4116))

@) 2000
2001
2002
3000

FORMAT(//’ RESULTS OF THE FFT ")

FORMAT (/' #*%»%PHASE ANGLES#*#*%’,/,(d4F16,5))

FORMAT (' #%*AMPLITUDES**%’,/,(4F16.,5))
FORMAT(///’'ERROR CODE FROMFFT
= *,16+///)

END

7-10

The Phase Angle and Amplitude Spectra (PHAMPL) Subroutine

Define array variables and their sizes; initialize variables external to

the subroutine; specify input as integer.

@ Generate 32 random values for input to the FFT subroutine and print
the real and imaginary values:

Values =100.*SIN(X/2.) + 200.*COS(2.*X) + NOISE

@ Call FFT subroutine to process these input values; print any error
messages.

Call PHAMPL subroutine to process the output from the FFT subrou-

tine; print the real and imaginary results of the FFT and

sponding phase angles and amplitudes.

the corre-

Format statements

The Phase Angle and Amplitude Spectra (PHAMPL) Subroutine

7-11

Terminal Output
PHAMPL Example #2

INPUT DATA FOR FFT
*x*REAL PART
* %
199

160

-129

-86

-60

227
-70

299

227

-131

-93

185

151

120

-49

-283

-202

-230

95
-285
**%x IMAGINARY

-209

-93

-104

-229

-42

115

PART***
0

000

Q
QO

OO0

0
Q

Q
0

RESULTS OF THE FFT

*%x%*NEAL PART
%% %

*%x % IMAGINARY

-221

3188

-9

-7

-32

-29

-27

-29

-12

-6

3189

-1611

-39

-31

-4

-14

-3

-13

-29

-20

-13

PART ***

-7

-19
11

-37

1615

3.,14159

-1.,35632

-1,00076

-1.,22982

0.,00251

-1.,32582

-2+14213

1.,14202

-0.89606

-2.,00742

-3.,07917

-1.42890

*%%xPHASE ANGLES*
%%

-0.,94405

0.44976

-2+253784

0.61073

-0,783%40

2.63449

-0.,34985

0.,90483

1.,10713

3.07274

2,3996°5

0,89606

-1,08640

1.,97369

0.,19740

-0.,00220

1,03489

0.97705

1,55222

221.,00000

1611.16418

46.32494

32.89377

3188.01001

4,12311

16.64332

38.48376

**xAMPLITUDES**%

7-12

6.40312

16.55295

32.,06244

7.07107

35.80503

32.20248

35.22783

12.20656

13.00000

18.,38478

30.88689

36.,35932

35.60899

6.70820

29.06888

16.27882

6.40312

41.,39327

15.23135

2,08902

3189.00737

37.215589

48.25971

1615.27856

The Phase Angle and Amplitude Spectra (PHAMPL) Subroutine

POWER SPECTRUM (POWRSP) SUBROUTINE
FORMAT:
CALL POWRSP(N,IR,IM,P)

Where:
N

1s an integer variable that specifies the length of the input arrays.

is an integer array containing the real parts of the input data.

is an integer array containing the imaginary parts of the input
data.

is a real array used to store power spectrum results.

FILE NAMES:

POWRSP.MAC (source file); POWRSP.OBJ (object file)

OPTIONS:
@

EIS

(Extended Instruction Set — KE11-E)

EAE

(Extended Arithmetic Element — KE11)

APPROXIMATE SIZE OF SUBROUTINE (IN WORDS):
If the following options are enabled:

NONE

EIS

EAE

119

TYPICAL EXECUTIONS SPEED:

With PDP-11/34 and EIS enabled:

5500 Points/second.

With PDP-11/03 and EIS enabled:

2400 Points/second.

Chapter 8
The Power Spectrum (POWRSP) Subroutine

The power spectrum (POWRSP) subroutine deals with complex values of
the type produced by the fast Fourier transform (FFT) subroutine. (See
Chapter 6 for a detailed description of the FFT subroutine.) POWRSP computes the power spectrum — the relationship between power and signal
frequency — of a set of Fourier coefficients by calculating the squares of the
magnitudes of that set of Fourier coefficients.

The input to POWRSP consists of two integer arrays. One integer array
contains the real parts of the Fourier coefficients. The other integer array

contains the imaginary parts of the Fourier coefficients.
The output from POWRSP consists of one real array that contains the

calculated power spectrum.
Mathematically, the function of the subroutine can be described as

Where:

is the real array used to store the power spectrum.

is the integer array containing the real parts of the
Fourier coefficients.

is the integer array containing the imaginary parts of the
Fourier coefficients.

8.1

How to Call POWRSP
The general format for the FORTRAN call is:
CALL POWRSP(N,IR,IM,P)

8-1

For reference, argument names in the call to POWR

SP have been assigned

arbitrarily. You may supply your own argument

all of the arguments explicitly. There are

names, but you must state
no default values for any of the

arguments. If you omit an argument, either
accidentally or on purpose, or if
you supply too many arguments, a FORT
RAN error message results and no

data is processed. The arguments are described

in the following discussion.

is an integer that defines the length of the input

1s an integer array containing the real parts
of the complex Fourier
coefficients.

1s an integer array containing the imaginary

Fourier coefficients.
P

and output arrays.

parts of the complex

1s a real array in which POWRSP stores the
power spectrum results. Values for the array elements in P are
computed as follows
P(I) = IR(M*IR) + IMD*IM(I)

8.2

Modifying the Subroutine — Using Options
The following sections explain which options
spectrum subroutine. If you want to use any

you can use with the power

of the options, you must enable

them when you build the subroutine from the
source file using
interactive build procedure (see Section 1.1).

8.2.1

the

EIS (Extended Instruction Set)

Enable this option if your installation has EIS (KE11

-E) hardware or any
other floating-point option available. Enabling this
option increases the

execution speed and decreases the memory requir

by approximately 44 words.

8.2.2

ements for the subroutine

EAE (Extended Arithmetic Element)

Enable this option if your installation has EAE
hardware available.
Enabling this option increases the execution speed and
decreases the mem-

ory requirements for the subroutine by approximatel

y 25 words.

8.3

Examples Using the POWRSP Subroutine
The following example FORTRAN program illustr
ates how to use
POWRSP to calculate the power spectrum of comple
x Fourier coefficients.
Example 1 uses random, complex numbers generated
by a random-number

generator. Example 2 uses output from the FFT subrout

ine.

8-2

The Power Spectrum (POWRSP) Subroutine

NOTE
If you use FORTRAN 77 and you want to duplicate the termi-

nal output for the example programs, replace the standard
random-number generator in F4POTS with F4APRAN.OBJ.
Terminal output for the example programs is based on the
FORTRAN IV random-number generator. The FORTRAN 77
random-number generator is different from that for
FORTRAN IV and will not produce the same output. See
Section B.1.

The Power Spectrum (POWRSP) Subroutine

8-3

POWRSP Example #1

The Power Spectrum (POWRSP) Subroutine

8-5

@O/ —®—
G

POWRSP Example #1
DIMENSION IR(32) +IM(32),P(32)
DATA NsM/0 40/
NEXT(V)=(RAN(N
M)
#300,)-250,

DO 10 I=1,32
IRCINI=NEXT(X)
10

IMCI)=NEXT(X)
TYPE 900

TYPE 1002IR
TYPE 10031IM

DO 11

1=1,32

XO0=IR(I)
X1=IM(I)

PCI)=X0#XO0+X1%X1

—

CONTINUE

1 O

TYPE 1004 ,P
CALL POWRSP(32+IR+»IM,P)
TYPE 1005,P

—©

900

8-6

FORMAT(1H1
»T20 ) 'POWRSP ExampPple #1',//)

1002

FORMAT ( RANDOM INPUT DATA’/ '’ REAL PART' +/»(d4115))

1003

FORMAT (/'

1004

FORMAT(//

POWER FROM DIRECT CALCULATIONS '/ »(4F15,5))

1005

FORMAT(//

POWER FROM SUBROUTINE' »/ +(4F15.,5))

IMAGINARY PART "/ »

(4113))

STOP

END

The Power Spectrum (POWRSP) Subroutine

Define array variables and their sizes; initialize parameters external
to POWRSP subroutine; define real and imaginary values of 32 ran-

dom numbers to be processed.

Compute 32 random values and print real and Imaginary parts.
Calculate power spectrum for random input values and print results.
Call the POWRSP subroutine to calculate power spectrum for random

input values and print results.

Format statements

The Power Spectrum (POWRSP) Subroutine

8-7

Terminal Output
POWRSP Example 1

RANDOM

INPUT DATA

REAL PART

-249

151

-243

161

169

-196

-11

-53

-40

163

-172

213

-43

-86

-91

120

-22

-97

173

224

180

-211

-231
-90

IMAGINARY PART

-249

-24d8

-246

-22

186

-164

-88

2435

113

-95

163

138

-214

103

230

114

-9%

-93

192

-14

167

-109

134

-75

141

POWER FROM DIRECT CALCULATIONS
124002,00000
123505,00000

110578.,00000

29840,00000

83317.,00000

BOS17.,00000

63301.00000

51185.00000

23457 .,00000
29378,00000

153266.,00000

64413.,00000

12458,00000

B0Z296.,00000

13045,00000

21264 .,00000

11090,00000

196.00000

4205.,00000

17210,00000

68132.,00000

44845.00000

11810.,00000

36625.,00000
°821.,00000

7865,00000
47396.,00000

33294,00000
32245,00000
37850.,00000

238890,00000
27981.,00000

POWER FROM SUBROUTINE

124002,00000

123505.00000

83317,00000

1105378.00000

B0O317.,00000

B3301,00000

234537.00000

21185.,00000

7865.,00000

15266,00000
12458.,00000

29378.,00000

64413.,00000

47396.,00000

BOZ296.,00000

39594,00000

11090,00000

196,00000

4205,00000

11810,00000

17210,00000

37850,00000

36625,00000

23890.,00000

68132.,00000

8-8

13045,00000

44845.,00000

The Power Spectrum (POWRSP) Subroutine

21264.,00000

0821.,00000

29840,00000

32245,00000

27981,00000

POWRSP Example #2

The Power Spectrum (POWRSP) Subroutine

8-9

POWRSP Example #2
DIMENSION PSPECT(32) ,IMAG(32)

INTEGER REAL(32) »SCALE yERROR
DATANI1+I2+4T+A4B+C+D/32+0+0+04 1100,
1200, +.5,2./
DATAPI/3.141593/,IMAG/32%0/
DT=P1/8.,

CALL RANDU(I1,12,X)
DO
1 I=1,N

REAL(I)=A*SIN(C#T)+B
(-1, #%I)
*COS(
%15, %RAN(I1,
D*T)+
12)

T=T+DT

TYPE 900

TYPE 1000
TYPE 1001 ,REAL

TYPE 1002+ IMAG
CALL FFT(ERROR sN»REAL +IMAG 0 ,SCALE)
IF(ERROR.NE.O) PRINT 3000 /ERROR

CALL POWRSP(N,REAL +IMAG,PSPECT)
TYPE 2000

TYPE 1001 ,REAL
TYPE 1002+ IMAG

TYPE 2001 ,PSPECT

STOP
900

FORMAT(1H1+722,'POWRSP Example #2°',//)

1000

FORMAT(’

1001

FORMAT(/' »**REAL PART*#%',/,(4116))

1002

FORMAT(’ ##*%IMAGINARY PART#*#%',/,(4116))

2001

FORMAT(//' POWER SPECTRUM RESULTS '/ +s(4F16.1)
)
FORMAT(///'ERROR CODE FROMFFT
= ' ,16+//7/)

INPUT DATAFOR FFT ')

@) 2000 FORMAT(//’ RESULTS OF THE FFT")
3000

END

8-10

The Power Spectrum (POWRSP) Subroutine

Define array variables and their sizes; initialize variables external to

the subroutine; specify input as integer.

@ Generate 32 random values for input to the FFT subroutine and print
real and imaginary values:

Values=100.*SIN(X/2.) + 200.*COS(2.*X) + NOISE

Call FFT subroutine to process these input values; print any error
messages.

@ Call POWRSP subroutine to process the output from the FFT subroutine; print the real and imaginary results of the FFT and the corre-

sponding power spectrum.

@ Format statements

The Power Spectrum (POWRSP) Subroutine

8-11 .

Terminal Output
POWRSP Example #2

INPUT DATA FOR FFT
**#REAL

PART ***

*%x% IMAGINARY

199

160

-129

-60O

299

227

-131

-93

185

-283

-230

-285

-209

-86

227
-70

151

-202
33
i

0
§)

115

PART
%% %
0

RESULTS OF THE FFT
¥ *REAL PART
* %%

*¥%##IMAGINARY

-22

3188

-9

-7

-32

-29

-27

-29

-12

3189

-6

PART*#*x
0

-1611

-39

-4

-31

-3

-14

-15

-29

-20

-7

-13

-37

-7

48841 .0

2595850,0

10163408.0

2146.,0

17.0

1082.,0

277.0

1481.0

-19

1615

POWER SPECTRUM RESULTS

8-12

41,0

274.0

1282.0

1028.0

1037.0

20,0

169.0

1241.,0

338.0

149.0

1268.0

954.0

1322.0

41.0

45,0
1730,0

845.,0

265.0

10169770.,0

232.0

1385.,0

26,0

2329.0

2609125.,0

The Power Spectrum (POWRSP) Subroutine

CORRELATION FUNCTION (CORREL) SUBROUTINE
FORMAT:
CALL CORREL(IERROR,N,IA1,JA2,IFFTA ISCALE)

Where:

IERROR

1s an integer variable used to report errors.

is an integer variable used to specify the number of samples to
be correlated.

IA1

1s an integer array N elements long containing the samples of
the first function to be correlated.

IA2

1s an integer array N elements long containing samples of the

second function to be correlated.
IFFTA

1s an integer array used to hold the imaginary part(s) of the
input to the FFT subroutine.

ISCALE

1s an integer variable set by CORREL to indicate the scaling
factor (number of times results have been divided by 2).

FILE NAMES:

CORREL.MAC (source file); CORREL.OBJ (object file)
OTHER ROUTINES USED:
Fast Fourier Transform (FFT) Subroutine

OPTIONS:
@

EIS

(Extended Instruction Set — KE11-E)

EAE

(Extended Arithmetic Element — KE11)

APPROXIMATE SIZE OF SUBROUTINE (IN WORDS):
If the following options are enabled:
NONE

EIS

EAE

266

240

246

TYPICAL EXECUTION SPEED:

With PDP-11/34 and EIS enabled:

420

Points/second

(for

auto-

(for

cross-

(for

auto-

(for

cross-

correlation)
280

Points/second

correlation)

With PDP-11/03 and EIS enabled:

150

Points/second

correlation).
100

Points/second

correlation).

Chapter 9
The Correlation Function (CORREL) Sub

routine

The correlation function subroutine

(CORREL) produces an estimate for
the correlation function. The correlatio
n function measures the similarity
of two functions as one of the functions
is shifted in time. The value of the

correlation function for any time shift,

“t,” is the integral over all time of

the product of the first function multiplied
shifted by an amount “t.”

by the second function after it is

Mathematically, the correlation funct

ion can be described as:

R, =] x(®y(@ +t)dp
Where:

x(B) and y(B) are the two functions to be

compared.

t 1s the time shift.

R,,(t) is the resulting correlation funct

ion.

When x(B) =y(B), R,,(t) is called an auto-

correlation function. When x(B)
y(B), R,,(t) is called a cross-correlation functi
on.
As this formula indicates, the correlatio
n function yields useful information
only when the functions being correlated
have finite content:
o0

f f2(t) dt < oo
—00

But, because the functions to be corre
lated do not normally have finite

content, the correlation function
does not generally yield useful infor
ma-

tion. Under these circumstances, an estim
ate

called

the

information.

average

-correlation

function,

of the correlation function,

must

provide

the

desired

9-1

The mathematical formula for the average correlation function is:
1

Ry
() = = jo x(B)y
(B + t)dp
Where:

R,, (t) is the estimated average correlation function.
x (B) and y (B) are the two functions to be correlated.

T is a representative time interval.
It is this average correlation function that CORREL estimates.

The input to CORREL consists of two integer arrays. One integer array
contains the samples of the first function to be correlated. The other integer
array contains the samples of the second function to be correlated.
The output from CORREL (that is, the estimates of the average correlation

function at various time shifts) is returned in the first input integer array.

9.1

Using the Correlation Function Subroutine
The discrete evaluation of the correlation function implies a large number

of mathematical operations. Indeed, the number of mathematical operations increases linearly as the number of values of ny(t) to be calculated
increases.

When you use CORREL, however, this situation is improved. CORREL

calls the fast Fourier transform (FFT) subroutine to process the input data,
significantly decreasing the number of mathematical operations required to
approximate the average correlation function. In fact, this method of evaluation becomes more efficient as the number of values of ny to be calculated
increases.

See Chapter 6 for a full description of the FFT subroutine.
To use CORREL, the two functions you want to correlate should meet the
following requirements:

They must have a Fourier transform.

They must be real (not complex) functions.

They must be sampled at the same evenly spaced intervals. (The num-

ber of samples must be a power of two.)
4.

They must be periodic.

They must have a sample period that represents a non-zero, integermultiple of their periods.

There are exceptions to these requirements. You can also use CORREL to
correlate functions that are non-zero over only a finite-term interval.

9-2

The Correlation Function (CORREL) Subroutine

To correlate such a function, first sample the

function over the non-zero
intervals. Then, double the number of sample
values to be processed.
Finally, set the extra samples to zero.

9.2

Discrete Evaluation of CORREL
The following is a brief summary, without proof,
of the derivation of the
technique used by CORREL.
Convolution, represented by the symbol *, is define

d as

S,
® =x®*y®t)=[ x®)yE-tdt
—00

Correlation, represented by the symbol ® , 1s
defined as
o0

Ry@®=x®®y®t) =] x®yE+t)dt
—00

These two functions are related as shown
X)) *xy () =x({t)® y(t)

since
oo

X(O*
@) =]
y x(t)y(E-t)dt
—00

Now, let B = -t, and
—00

X()*y®) =-[

x@yE+p) dp

=] x® yE+p)
dp
—0Q0

=xX(B)®

y(B)orx(t)®

y(t)

It can also be shown that
FT
x((t)
t
«—
)X(f)
*Y
y
(f)

Where:

<> represents the Fourier transform and
Xx(t)

«—>X(f)

and y (t)

«<——

Y (f)

The Correlation Function (CO

RREL) Subroutine

9-3

Furthermore, it can be observed that if
x(t)

FT
«e—> X ()

then
FT
A
X (-t) «—> X (f) = X (f) (the conjugate of X (f))

since the real of portion of X (f) is an even function and the imaginary

portion is an odd function of f.

Finally, assuming all the preceeding statements are true, we have

=x®)® yt) =x(t)*yt)«—>X ()
Y ()

R, (&) = <>
X" ()
Y ()
CORREL uses this final relationship to produce the correlation function.
The specific steps are:
1.

Transform x (t).

x (t) F—T-) X (f)
2.

Transform y (t).

y (t) E‘L Y (f)
3.

Calculate the conjugate of X (f).

X' (f) = X (4. Multiply X" (f) by Y (f)

X' ()Y
5.

)

Perform an inverse transform on the result of Step 4.
FT

R, () <
X () Y (f)

9.3

Calculating the Correlation Coefficients
The results obtained by CORREL provide an estimate for the discrete auto-

correlation function or the discrete cross-correlation function. The normalized results of the auto-correlation function and of the cross-correlation
function are known as correlation coefficients.
The following equation provides the algorithm by which you can derive the

correlation coefficients from the results of the subroutine.

The Correlation Function (CORREL) Subroutine

C,,(n) =
Where:

S., R,, (n)

VS, * Ry(0) - S,, « R, ,(0)

Forn=0,1,2,... N-1

1s the number of points.

ny(n)

are the calculated correlation coefficients
in
the range -1, 1 for the functions x(t),
y(t).

ny(n)

1s the raw integer result for the correlatio

function estimate returned by CORREL

for

the functions x(t), y(t).
RXX(O)

1s the value of the auto-correlation funct

ion

estimate for x(t) for a zero displaceme
nt,

that is, for n=0.
Ryy(O)

1s the value of the auto-correlation funct
ion
estimate for y(t) for a zero displ
acement,

that is, for n=0.
xy’

are the scale factors indicated by COR

REL

when calculating ny, R _, and Ryy respec-

tively.

(For an illustration,

see the pro-

gramming example in Section 9.7.)

For many applications, the scaled resul
as much, if not more, information

9.4

ts of the correlation function provide

than do the correlation coefficients

How to Call CORREL
The general format for the FORTRAN

call to CORREL is:

CALL CORREL(IERROR,N ,IA1,IA2 IFFTA

ISCALE)

For reference, argument names in the call

arbitrarily. You may supply your own

all of the arguments explicitly. There

arguments. If you omit an argument,

you supply too many arguments,

no data is processed.
discussion.

The

to CORREL have been assigned

argument names, but you must state

are no default values for any of the

either accidentally or on purpose, or

a FORTRAN error message results,

arguments

are

described

in the

and

following

IERROR is an integer variable used to

report error conditions.
Because CORREL calls the FFT subro
utine, the values IERROR can

return are the same as those retur

ned by the IERROR argument in

FFT subroutine.

The values that IERROR can return,
0O

No error

Nis less than eight

Nis greater than

F.MAXN)

the

and their meanings are as follows:

F. MAXN (see Section 6.6.3 for a descr

The Correlation Function (CORREL) Subro

iption of

utine

9-5

N is not a power of two

-N

Incorrect number of arguments in call

N is an integer variable that specifies the number of samples in both func-

tions to be correlated. N must be a value that is a power of two in the

range of 8 to F.MAXN.

IAl is an integer array at least N elements in length that contains the

samples of the first function to be correlated. CORREL returns its results
to this array, replacing the input values.

IA2 is an integer array at least N elements in length that contains the
samples of the second function to be correlated.

If the array specified for IA1 has the same name and/or occupies the
same location as the array specified for IA2 (in other words, if the two
arrays

are equivalenced), CORREL performs the average autocorrelation function. If IA1 has a different name and occupies a different

location from the array specified for IA2, CORREL performs the average
cross-correlation function.

IFFTA is an integer array used for the imaginary part(s) of the input to

the FFT subroutine.

The length of IFFTA depends on whether CORREL is to perform an
auto-correlation or a cross-correlation. If CORREL is to perform an auto-

correlation, then IFFTA must be N elements long. If CORREL is to
perform a cross-correlation, then IFFTA must be 2 -+ N elements long.
NOTE

The original values in IA1, IA2, and IFFTA are altered upon
return from the subroutine.

ISCALE is an integer variable that is set by CORREL. It indicates the

scaling factor, that is, the number of times the results of the correlation

function have been divided by two. CORREL sets ISCALE as necessary

to avoid overflow.
To obtain the unscaled results of the correlation function, you must mul-

tiply the real and imaginary output of the subroutine by 2°“4F.

9.5

Other Routines Used
CORREL uses the FFT subroutine. Thus, you must include both the
CORREL object module and the FFT object module when you link or task-

build a FORTRAN program that calls CORREL.
See Appendixes A and B for a detailed description of how to build a
FORTRAN program.

9-6

The Correlation Function (CORREL) Subroutine

9.6

Modifying the Subroutine — Using Options
The following sections explain which options you can use
tion function subroutine. If you want to use any of the

with the correla-

options, you must

enable them when you build the subroutine from the source

interactive build procedure (see Section 1.1).

9.6.1

file using the

EIS (Extended Instruction Set)

Enable this option if your installation has EIS (KE11E) hardware or any
other floating-point option available. Enabling this
option increases the
execution speed and decreases the memory requirements
for the subroutine
by approximately 26 words.

9.6.2

EAE (Extended Arithmetic Element)

Enable this option if your installation has EAE (KE11)
hardware available.
Enabling this option increases the execution speed and
decreases the mem-

ory requirements for the subroutine by approximatel

y 20 words.

9.6.3

FFT Options

Because CORREL calls the FFT subroutine, the FFT
influence on CORREL’s operation. Thus, you should

into consideration whenever you modify CORREL.

options have a direct
take the FFT options

See Section 6.6 for a description of the FFT options.

9.7

Example Using the CORREL Subroutine
The example presented here illustrates how to use

CORREL to find both
the average cross-correlation and the average auto-co
rrelation functions of
a specific set of input data.

The example program computes the unscaled and
scaled average Cross-

correlation function of 32 sine values and 32 cosine

values scaled by 1000.
Then, the example program computes the value
of the average autocorrelation function, with zero shift, of 32 sine values

Finally, the example program computes the averag

ficients of the 32 sine and 32 cosine values.

and 32 cosine values.

e cross-correlation coef-

The Correlation Function (CORREL) Subroutine

9-7

CORREL Example #1

The Correlation Function (CORREL) Subroutine

9-9

CORREL Example #1
DIMENSION IC0S(32) ,ISIN(32),I1
C0S2(32) v ISIN2(32)
DIMENSION ISTORE(64) ,COR(32)
COMPLEX%*8 ERRMES(2,3)

<1>

DATA ERRMES/ ‘LESS THA' ‘N EIGHT ’, "EXCEEDS ’,'F.MAXN

1’NOT APO’y'WEROF 2/

DATAPI/3.14159/,T/0./C/.01/
DT=P1/186.

TYPE 900

DO 1 I=1,32
D=COS(T)

E=SIN(T)
ICOS(1)=D*#1000,+SIGN(C
+0)

ISIN(I)=E*1000,+SIGN(C E)

1COS2(1)=1COS(1)

ISINZ(I)=ISIN(I)
1

T=T+DT

CALL CORREL(IERROR,32/+ISIN,ICOS,ISTORE » ISCALE)
IF (IERROR.NE.O) GO TO 20

TYPE 1000,ISIN

FAC=2,%#%IABS(ISCALE)

IF(ISCALE.LT.0) FAC=1,/FAC

D021=1,32

COR(I)=FAC*#ISIN(I)
TYPE 1001,COR

CALL CORREL(IERROR32,ISIN2,IS
IN?

IF(IERROR.NE.O) GO TO 20

»ISTORE »ISCALE)

FAC=2.,%#%*IABS(ISCALE)
IF(ISCALE.LT.0)FAC=1,/FAC
CSINO=FAC*ISIN2(1)

CALL CORREL (IERROR+32,1C0S2,1C0O
S2 »ISTORE » ISCALE)
IF(IERROR.NE.O) GO TO 20

FAC=2.,#*IABS(ISCALE)
IF(ISCALE.LT.0)FAC=1./FAC

CCOSO=FAC*ICODS2(1)
FAC=SQRT(CSINO*CCOS0)
D03 1I=1,32

COR(I)=COR(I)/FAC

TYPE 1002,CSINO,CCOS0O,COR

STOP

TYPE 2000, (ERRMES(I yIERROR) 11=1,2)
STOP

900
1000

FORMAT(1H1+T25, 'CORREL Example #1 ')
FORMAT(///' UNSCALED RESULTS OF CORRELA
TION OF SINE AND COSINE '/,
1 /,04117))

1001
1

FORMAT(///' SCALED RESULTS OF CORRELA
TION OF SINE AND COSINE‘//,
(1P4E17.5))

(8) 1002 FORMAT(///' VALUE OF AUTO-CORRELATION OF SIN#1000
WITH
1

2
3
2000

9-10

ZERO SHIFT

='41PE10.4+//,' VALUE OF AUTO-CO
RRELATION OF COS#1000 WITH ZERD

SHIFT = '41PE10.4,+//
' CROSS-CORRELATION COEFFICIENTS
FOR SIN#100
0BY COS#1000 ARE AS FOLLOWS: ' +//+(1PA
EL17.5))
FORMAT(///' #%%#%ERROR**%% ARRAY LENGTH
1dAqg)
END

The Correlation Function (CORREL) Subroutine

Dimension array variables and initialize
the error message variable
ERRMES.

Initialize arrays for input to the subroutine

. Sine and cosine values -

©®

1000 for one period.

Call CORREL to produce the unscaled

sine

values

and

cosine

values.

results of cross-correlation of

unscaled results of crosss. If IERROR 1s not zero, print the

correlation of sine and cosine value

proper error message. Comp
ute the scaling factor

of cross-correlation of sine values and

. Print scaled results

cosine values.

Call CORREL to produce auto-corre
lation of sine values scaled by
1000. If IERROR is not equal to zero,
print the appropriate error mes-

sage. Compute auto-correlation of

sine values scaled by 1000.

Call CORREL to produce auto-corre

lation of cosine values scaled by
1000. If IERROR is not equal to zero,
print the appropriate error message. Compute value of auto-corre
lation of cosine values scaled by
1000.

®
@

Compute the cross-correlation coeff

icients for scaled sine and cosine

values.

Print error message (if error code retur

ned).

Format statements

The Correlation Function (CORRE

L) Subroutine

9-11

Terminal Output
CORREL Example #1
UNSCALED RESULTS OF CORRELATION OF SINE AND COSINE

-3

6085

11938

17335

22065

20943

28828

30603

31213

30608

28833

25948

22065

17337

11940

6089

-6085

-11939

-17335

-220653

-25943

-28828

-30605

-31213

-30608

-28833

-25948

-220695

-17337

-11940

-6089

SCALED RESULTS OF CORRELATION OF SINE AND COSINE
-8,00000E+01

9.73600E+04

1.91024E+00

2+77360E+05

3+33040E+03

4,15088E+05

4.61248BE+05

4.,89680E+05

4,99408E+05

4.,8972Z28BE+05

4,6132BE+03

4,15168E+03

3+33040E+03

2+77392E+053

1,91040E+03

9.74240E+04

8.,00000E+01

-9.73600E+04

-1.91024E+05

-24+77360OE+0D

-3,23040E+03

-4,135088E+05

-4.61248E+05

-4.,89680E+05

-4.,99408BE+03
-3.93040E+03

-4.,89728E+05
-2+77392E+05

-4.,61328E+03
-1.,91040E+03

-4,15168BE+05
-9.74240E+04

VALUE OF AUTO-CORRELATION
OF SIN*#1000 WITH ZERO SHIFT
= 4,9930E+05

VALUE OF AUTO-CORRELATION OF COS*1000 WITH JERO SHIFT
= 4,9928E+03
CROSS-CORRELATION COEFFICIENTS FOR SIN*#1000 BY COS*#1000 ARE AS FOLLOWS:

9-12

-1,60228E-04
7.07087E-01

8.,31360E-01

1.,94998E-01

3.825893E-01
9,23811E-01

S.95511E-01
9.807537E-01

1, 00024E+00

7.07087E-01
1.60228E-04
-7,07087E-01
~-1.,00024E+00
-7.07087E-01

9.80853E-01

v 23972E-01

8.31520E-01

5.+03375E-01
-1.,94998E-01
-8.31360E-01
-9.80853E-01
-9.,335375Ek-01

3.826253E-01
-3.82593E-01
-9.23811E-01
-9.23872E-01
-3.826253E-01

1.,995126E-01
-3.33511E-01
-9.807537E-01
-8.31520E-01
-1.,95126E-01

The Correlation Function (CORREL) Subroutine

Appendix A
Installing, Verifying, and Using LSP Under RT-11

This

appendix explains how to install and verify the
Laboratory
Subroutines Package (LSP) software and how to create
a FORTRAN IV

program that calls the Laboratory Subroutines under the
system.

RT—11 operating

However, the appendix provides only general information

programs. It does not include detailed information about

about creating

the FORTRAN IV

programming language, the FORTRAN IV compiler
, the MACRO assem-

bler, or the RT-11 operating system. For additional informa

tion on these

topics, refer to the appropriate RT-11 or FORTRAN
IV documentation

cited in this appendix.

A.1

Installation Requirements
Instructions in this appendix require that:
1.

All files acted upon by system programs are on the default
unless otherwise noted in this appendix.

device, DK:,

You use the default files types which are:
.FOR

.MAC

FORTRAN source files
MACRO source files

.OBJ

object files and object library files

SAV

image (executable) background files

The system MACRO library, SYSMAC.SML, and the MACR
bler, MACRO.SAV, have already been built and reside

device, SY:.

O assemon the system

The FORTRAN IV compiler, FORTRA.SAV, has already been built and

resides on the system device, SY:.

The FORTRAN Object Time System, OTS.SAV, has been built and
added to the system library, SYSLIB.OBJ, which resides on the system

device, SY:.

The system utility programs, PIP.SAV, DUP.SAV, the RT-11 linker,
LINK.SAV, and the RT-11 librarian, LIBR.SAV, have been installed
and reside on the system device, SY:.

All necessary system programs and files are installed and reside on the

system device, SY:.

A.2

Installing the Laboratory Subroutines Software
Installing the Laboratory Subroutines software consists of copying the LSP
distribution volume and making any necessary corrections to the LSP
software.

If you wish to enable any of the options described in this manual, you must
also run the file LSPMAK.SAV which is part of your distributed LSP soft-

ware. LSPMAK builds the subroutines by assembling them with the options enabled. You can also use LSPMAK to build the subroutines without
any options, but if you do not wish to use options, you do not need to run

LSPMAK. Section A.2.4.2 explains how to use LSPMAK.

A.2.1

Copying the Distribution Volume

Because all storage media can be adversely affected by environmental con-

ditions, vandalism, and human error, you should keep several copies of any

software that cannot be easily re-created. Copy the LSP distribution volume and then store it in a safe place. Use the distribution volume only

when copying the LSP software. Use only copies for all other procedures

described in this appendix.
The LSP software is distributed on a single volume that RT-11 can read.

The procedure for copying the distribution volume varies depending on how
many mass storage devices you have. If you have three or more mass

storage devices, follow the procedure in Section A.2.1.1. If you have only
two mass storage devices, follow the procedure in Section A.2.1.2.

NOTE
Instructions for copying one volume to another use the

SQUEEZE command rather than the COPY command. The
SQUEEZE command copies the protection code of files; the

COPY command does not. For additional information on
removing and restoring the protection code of files, see
Section A.2.2.

A-2

Installing, Verifying, and Using LSP Under RT-11

A.2.1.1

Copying with Three or More Mass Storage Devices — To copy the LSP

distribution volume with three or more mass storage devices, do the
following:
1.

Load the distribution volume.

Load a blank storage volume.

Format the blank storage volume if necessary. If you use RK05 disks,
format each disk. If you use RX02 drives, format each diskette to be
either single density or double density. Other storage media cannot be
formatted.
Use the FORMAT command to format your disks and diskettes. The
following example formats an RK05 disk:
+FORMAT RK1:®ED
kK1:/FORMAT-Are

vou

sure?YRLD

"FORMAT-I-Formatting

compPlete

When you use the FORMAT command, diskettes on RX02 drives are
formatted to be double density by default. If you want them to be single
density, use the /SINGLEDENSITY switch with the FORMAT command. The following example formats a diskette to be single density:
+FORMAT/SINGLEDENSITY DY
1 :@T
vou sure?YRE

D¥1:/FORMAT-Are

?"FORMAT-I-Formatting

compPplete

See the RT—-11 System User’s Guide for more information about the
FORMAT command.
4.

Initialize the blank storage volume using the /BADBLOCKS switch to

search for and isolate bad blocks. Type:
+INITIALIZE/BADBLOCKS dun
:@
Juns/Initializes
DUP-I-No

bad

Are

blocks

vou

sure? YRED

detected

dun:

See the RT-11 System User’s Guide for more information about the
INITIALIZE command and what the system does if it finds bad blocks.

Use the SQUEEZE command with the /OUTPUT switch to copy files
from the distribution volume to the blank storage volume. Using the

SQUEEZE command with the /OUTPUT switch copies all files from the
input (distribution) volume to the beginning of the output (storage)
volume and consolidates all empty space on the output volume at the

end of that volume. The following example copies all files from dv1: to
dv2:
+SQUEEZE/QUTPUT:duZ:

dul :RED

See the RT-11 System User’s Guide for more information about the
SQUEEZE command and copying files.

Installing, Verifying, and Using LSP Under RT-11

A-3

A.2.1.2

Copying with only Two Mass Storage Devices
— If you have only two
mass storage devices, you cannot copy the LSP
distribution volume directly

since the RT-11 system volume occupies one of your

copy

the

distribution

following:

volume

under these

mass storage devices.
circumstances, do the

Load a blank storage volume.

Format the storage volume if necessary. If you
use RK05 disks, format
each disk. If you use RX02 drives, format each
diskette to be either
single density or double density. Other storag
e media cannot be
formatted.

Use the FORMAT command to format your disks
and diskettes. The
following example formats an RK05 disk:
FORMAT

RK
1 ¢ Rem

RR1:/FORMAT-Are

vou sure’TMy "FORMAT-I-Formatting complete

When you use the FORMAT command, diskettes
on RX02 drives are
formatted to be double density by default. If you want
them to be single
density, use the /SSINGLEDENSITY switch with
the FORMAT command. The following example formats a diskette
+FORMAT/SINGLEDENSITY

DY1:/FORMAT-Are

to be single density:

DV 1R

vou sure?,
&>
?"FORMAT-I-Formatting complete

See the RT-11 System User’s Guide for more inform
ation about the
FORMAT command.
3.

[Initialize the blank storage volume using the /BADB
LOCKS switch to
search for and isolate bad blocks. Type:
+INITIALIZE/BADBLOCKS dup &
dJun:/Initialize’ Are vou sure’?

DUP-I-No

bad

blocks

detected

dun:

See the RT-11 System User’s Guide for more information
about the
INITIALIZE command and what the system does if it finds
bad blocks.
4.

Use the SQUEEZE command with both the /WAIT and the

/OUTPUT

switches to copy files from the distribution volume to the

blank storage

remove the RT-11 system volume from the system device.

Then you can

volume. Using the /WAIT switch causes RT-11 to pause before
copying
files, allowing you to load a blank storage volume, if necessa
ry, and to

load the LSP distribution volume in the system device. RT—11

you with messages telling you when to do each of these

YG®ED to each message when you are ready to continue.

prompts

things. Answer

The /OUTPUT switch causes RT-11 to copy all files from
the input

(distribution) volume to the beginning of the output (storage) volume

Installing, Verifying, and Using LSP Under RT-11

and consolidates all empty space on the output volume at the end of
that volume. After RT-11 finishes copying the files, it prompts you with
a message telling you to replace the system volume in the system device. The following example copies all files from dv0: to dvl:
+OQWUEELZE/WATIT/0UTPUT
= dul s

Mount

output

Mount

inpPut

volume in dul:i Continue? Y&
volume in du0s3 Continue? YR
-—

At this point, RT-11 copies the files and then types the following message on your terminal:
Mount

s¥stem

volume

du0:3

Continue? Y RET;

See the RT-11 System User’s Guide for more information about the
SQUEEZE command and copying files.

A.2.2

File Protection

Remember that all files in the LSP distribution volume have been
protected. Never remove this protection. However, after copying the
distribution volume, you may remove the protection of files from your
copies, if you
wish, by using the RENAME command with the/ NOPROTECTI
ON switch.

To protect an unprotected file, use the /PROTECTION switch
with the
RENAME command.

See the RT-11 System
RENAME command.

A.2.3

User’s Guide for more information about the

Making Corrections

From time to time, the RT-11 Software Dispatch publishes correctio

ns that

you must make to the LSP software. The dispatch also publishe
s instruc-

tions on how to make the corrections.

You only need to make corrections published in the dispatch for version
1.2
of the LSP software. Corrections that were published in the dispatch
for
previous versions of LSP have already been included in version 1.2.

Never make corrections to your distribution volume. Make correctio

your copies. After making any corrections, copy your software

A.2.4

ns to

again.

Selecting the Form of Subroutine to Use

You receive the Laboratory Subroutines as both object files and
MACRO
source files. Read the following sections to determine which
form of the
subroutine to use.
A.2.4.1

Using Distributed Object Files — If you do not want to
enable any of

the options described in this manual, you can use the distribu

by linking them to your FORTRAN programs. (See Section

ted object files
1.2 for a list of

Installing, Verifying, and Using LSP Under RT-11

A-5

the LSP files.) Before you do so, however, test them to verify that they work
correctly by running the program LSPVER.COM which is part of your dis-

tributed LSP software. See Section A.3 for information about how to run
LSPVER.COM.
A.2.4.2

Creating Customized Object Files — LSPMAK, the Interactive Build
If you do want to enable any of the options described in this

Procedure —

manual, use the interactive build procedure, LSPMAK.SAV, to create
customized object files of the Laboratory Subroutines from the distributed
source files. (See Section 1.2 for a list of the LSP files.)

LSPMAK.SAV is part of your distributed LSP software. It lets you specify
the subroutines you want to assemble and the options you want to use.
Options available include:

library option — lets you place the subroutines in a library which you
create by supplying a library name.

hardware options — let you make use of EIS hardware (or any floatingpoint option) or EAE hardware if you have any.

subroutine options — let you specify which subroutines you want to
assemble and which option you want to use for each subroutine.

When you run LSPMAK.SAV, it prompts you with questions. Most ques-

tions give the name of a subroutine or option. Answer “yes” if you want to
build the subroutine or enable the option. Answer “no” if you do not. Some
questions request information and tell you how to type your answers. Fol-

low the instructions given when you respond. After you answer all the

questions, LSPMAK creates three files on your output device as follows:

LSPCND.MAC — This file sets the switches to enable the options you

requested.

LSPBLD.COM — This indirect-command file builds each subroutine you

requested. Building consists of assembling each subroutine you specifed
with the switches set to enable the options you chose. If you specified a
library while running LSPMAK, LSPBLD creates that library and includes

in it the subroutines you specified.

LSPVER.COM — This indirect-command file verifies that your LSP soft-

ware 1s in good working order. It does this by running an example program

that tests each subroutine you asked to build.

Before you attempt to run LSPMAK.SAV, assign logical device names to:
1.

The device containing all the Laboratory Subroutines software. Assign

this device the logical name “IN” for “input device.” Type:
+ASSIGN dun:

IN:Q@D

The device receiving the assembled object files. Assign this device the

logical name “OU” for “output device.” Type:
+ASSIGN dun: OU:RD

A-6

Installing, Verifying, and Using LSP Under RT-11

Now run the file LSPMAK.SAV. Type:
JRUN

IN:LSPMAKRE

The build procedure runs and begins typing questi

your terminal. The following text shows all

ons and information on

the questions and information

that LSPMAK can type. However, when you
run LSPMAK, not all the

questions and information will appear since
some of it depends on your
responses to previous questions. A sample

appears in Appendix C.

LSPMAK .SAV

and its output

Laboratory Subroutines Ui,?2 Build
Procedure for RT-11

Have vyouw assidgned devices for input
NOTE:

(IN:)

and outeut

(OU:)? [Y/N]

This procedure assumes that all
distributed files for
the Laboratory Subroutines pacKa
de are on deuvice "IN",

This procedure directs all output
and temporary files
(except library files) to device
"OU",

LIBRARY OPTION

Do »ou want to build a NEW libra
ry file from these subroutine
s?
LY/N]

Erter the specification

desired library file,
ENTER NAME
:

(maximum of 14 characters)
(example DK:LSPLIB.OBJ)

of the

As each subroutine

is added to the library, its corre
sponding
is normally Jeleted from devic
e "QU"
:
Is this acceptable? CY/N]

obdect file

HARDWARE OPTIONS

Does vour machine have the EIS
option
(the EIS ortion) [Y/N]

(or any floatind Point opPtion)?

Does vour machine have the EARE
oPtion?
(the EAE oPtion) [Y/N]

SUBROUTINE AND ALGORITHM OPTIO
NS

Do You want to build the subro
utine "PEAK"? [Y/N]
Do vyou want to disable the softw
are digital filter?
(enable the NOFLTS$ orPption)
CY/N]

Installing, Verifying, and Using LSP

Under RT-11

A-7

Do youwant to enable double precision inPut data processing by PEAK?
(the DPP% oprtion)

[Y/N]

Do rouwant to enable processing of coded A/D inrPut data by PEAK?
(the AUTOG® option) [Y/N]

Do youwant to build the subroutine "NUVELOP"? [Y/N]

Do vou want to build the subroutine "HISTI"? [Y/N]
Do youwant toenable HISTI to produce a frequency histodram?
(the FREQ$ orption)

[Y/N]

Do youwant to enable double precision inPut data processing by HISTI®?
(the DPH% option) [Y/N]

Do vouwant to buuild the subroutine "RHISTI"? [Y/N]

Do youwant to enable double precision inPut data processing by RHISTI®
(the DPR$ option) [Y/N]

Do vouwant to build the subroutine "FFT"? [Y/N]
What is the maximum length of any inPut array to be processed by FFT
(the F.MAXN oprtion)
10247 [Y/N]
20487 [Y/N]
40967 [VY/N]

81927 [Y/N]
*#¥THE DEFAULT

INPUT ARRAY LENGTH WILL BE USED

(1024) 1 %%
%

Do vou want to build the subroutine-"PHAMPL"? [Y¥/N]

Do vouwant to build the subroutine "POWRSP"? [Y/N]

NOTE:

CORREL needs subroutine FFT to function!

Do vyouwant to build the subroutine "CORREL"? [Y/N]
This first portion of the Labtoratory Subroutines build
procedure 1s complete.,

File LSPCND.MAC has beern created on device "0OU", This file
sets the switches
have

required toenable the oprtions that vou

requested.,

File LSPBLD.COM has also been created on device "0OU", You
should execute this indirect command file next.,

build each subroutine

It will

requested on device "0OU" and create

the library file specified,
Finallvys the file LSPVER.COM has beern created on device "0OU",
You should execute this command file after using LSPBLD.COM

tobuild vyourcustomized Laboratory Subroutines obdect files,
This command file will verify that vour software has been

successfully installed,
STOP --

A-8

Installing, Verifying, and Using LSP Under RT-11

Now run the indirect-command file LSPBLD.COM

. This file builds the subroutines you

requested on device “OU” and creates

a library file on that device if you specif

ied one.

Type:

A.3

Verifying the Laboratory Subroutines Soft

ware

After installing the LSP software, test it

installation procedure correctly, and that

to verify that you performed the
your LSP software was delivered

good working order. To do so, run
the indirect command file,
LSPVER.COM. Instructions for running LSPV
ER.COM follow. If you plan

to use the distributed object files, follow
the instructions in Section A.3.1. If
you used LSPMAK, follow the instructions
in Section A.3.2.

A.3.1

Verifying the Distributed LSP Object Files

To verify the distributed LSP object files,
use the distributed version of
LSPVER.COM. The distributed version of
LSPVER.COM runs the first example program in each chapter of this manua
l. These programs call the
distributed subroutine object files thus indica
ting whether they work correctly. Before attempting to run LSPVER,
do the following:
1.

Make

sure

Section A.1.
2.

that your

system

meets the

requirements

listed

Assign logical device names. Assign the logica

l name “IN” to the device

containing the Laboratory Subroutine
s software. Assign the logical
name “OU” to the device which will be
your output device.

To assign an input device type:
v ASSIGN
dun: IN:GkT

To assign an output device, type:
v ASSIGN

doun:

QU: &R

Copy all object files for the Laboratory
Subroutines to your output device. See Section 1.2 for a list of the LSP
files.

Now run LSPVER. Type:
, BIN:LSPYERRED

LSPVER types the name and number of
each example program it runs
along with the output from that prog
ram on your terminal. Compare the

output with that of the correspond

ing example program in the manua

they do not agree, and if you are sure

requirements listed in Section A.1,

l. If

you have not neglected any of the

you may have received a defective copy

of your LSP software. Contact DIGITAL

for more information.

Installing, Verifying, and Using LSP Unde

r RT-11

A-9

A.3.2

Verifying the Customized Object Files

To verify your customized object files, use the indirect-command file
LSPVER.COM that was created when you ran LSPMAK. LSPVER.COM
runs the example program that calls the version of the subroutine with the
options you enabled. To run LSPVER, do the following:

Make sure that the device assignments for “IN” and “OU” in Section
A.2.4.2 are still in effect. If they are not, assign them so they are the
same as when you ran LSPMAK.

Now run LSPVER. Type:
, BOU:LSPVERGRED

LSPVER types the name and number of each example program it runs
along with the output from that program on your terminal. Compare the

output with that of the corresponding example program in the manual. If

they do not agree, and if you are sure you have not neglected any of the
requirements listed in Section A.1, you may have received a defective copy

of your LSP software. Contact DIGITAL for more information.

A.4

Storing the Laboratory Subroutines
After determining that the Laboratory Subroutines you want to use are

sound, copy them to your system volume or to the development volume

where you store your FORTRAN programs, or put them in a library (see

Section A.6).

A.5

Creating a Program that Calls the Laboratory Subroutines
To create a FORTRAN IV program that calls the Laboratory Subroutines,
do the following:
1.

Write and check your program.

Use one of the RT-11 editors, such as EDIT, to enter your program into
a source file. The EDIT command with the /CREATE switch invokes

EDIT and tells it to create a new file. Type:
+EDIT/CREATE Prod.,FORRED

where:

prog

1s the name of your FORTRAN source program.

For information about entering the text of your file, making changes,

and displaying the file, see the Introduction to RT-11 and the

System User’s Guide.
NOTE
Always specify a file type when you use an RT-11 editor.
RT-11 editors do not use default file types. In this case,
give your source file the type .FOR since that is the default file type the FORTRAN IV compiler uses when it

compiles your program.

A-10

Installing, Verifying, and Using LSP Under RT-11

RT-11

Use the FORTRAN IV compiler to create an object file

Type:

of your program.

+FORTRAN P ro g

where:
4.

prog

1s the name of your FORTRAN source program.

Use the RT-11 linker to link the object file of your
program with

object files of your Laboratory Subroutines. Type:

the

vLINK Progssublsysub2,,,.¢ubn@l
where:

prog

is the name of your FORTRAN program.

subl

is the name of the first Laboratory Subroutine
object
file you want to link.

subn

is the name of the last Laboratory Subroutine
object
file you want to link.

To avoid linking individual subroutines to your
the subroutines in a library. See Section A.6.

program, you can place

Run the program. Type:
+RUN P o9&

where:

prog

1s the name of your executable program.

For more information about compiling, linking, and

running FORTRAN IV

programs, see the RT—-11 System User’s
Guide, and the RT—-11/RSTS/E

FORTRAN 1V User’s Guide.

A.6

Using Libraries
Once you decide which of the Laboratory Subrou
tines you will use most
frequently, you can link them more easily to
your programs by placing
them in a library. When you place them in a library
, you do not need to list
each individual subroutine in the link command
line. You only need to list
the library name. When vyou place them
in the system library,
SYSLIB.OBJ, you do not even need to list the
library name in the link

command line. The RT-11 linker automaticall

y searches the system library

for a subroutine or function needed by a program.

For example, suppose your compiled program,
MYPROG.OBJ calls the
subroutines FPEAK.OBJ and FAFFT.OBJ. To
link MYPROG, you have to

type:

+LINK

MYPROG »FPEAK sF4FF TEE)

If you place the subroutines in a library called
, for example, MYLIB.OBJ :
you link MYPROG by typing:
+LINK

MYPyMYL
ROG
IBGRD

Installing, Verifying, and Using LSP Under

RT-11

A-11

If you add the subroutines to the system library, SYSLIB.OBJ, you link
MYPROG by typing:
+LINK MYPROGEE

The RT-11 librarian program, LIBR.SAV lets you add object files or object
file libraries to SYSLIB. When you do so, however, you must remove certain global symbols from SYSLIB’s directory for the library to function

properly. Remove the global symbol $OVRH each time you add files or
libraries to SYSLIB. Also remove $ERRS and $ERRTB if you previously

added the FORTRAN IV OTS library to SYSLIB.
To add individual object files or a library to a system library containing the
distributed SYSLIB.OBJ file and the FORTRAN IV OTS library, use the

LIBRARY command with the /REMOVE switch. The LIBRARY command
invokes LIBR.SAV. The /REMOVE switch allows you to remove a global

symbol from a library directory. The following example adds an object file
residing on dvl: to SYSLIB on dv0: and removes the appropriate global
symbols:
+LIBRARY/REMOVE du0:SYSLIB dul:file.,O0BJRE
Global? $0VRHRDD
Global? $ERRSRED
Global? $ERRTBRE

Global®?

(anvy

other

global

Ppreviously

removed

from either

library)@D
Global®
RED

where:

file

is the name of the file or library you want to place in the
library.

If you fail to remove any of the necessary global symbols when you execute

this command, you will get a warning message for each symbol you failed
to remove. An example of the warning message is:
?LIBR-W-Illegal

insert of $0VRH

If you forget which global symbols to remove, create a dummy library file

by typing a command such as the following:
+LIBRARY/CREATE dummy SYSL IBRED

where:

dummy

is the name of a dummy library file.

Executing this command will produce error messages that list all the global
symbols you should remove. After noting the names of the global symbols,
delete the dummy library file and type the correct command for adding files

to SYSLIB.
For more information about the LIBRARY command and the RT-11 librar-

ian program LIBR.SAV, see the RT-11 System User’s Guide.

A-12

Installing, Verifying, and Using LSP Under RT-11

Appendix B

Installing, Verifying, and Using LSP Under
RSX-11M/M-PLUS

This

appendix explains how to install and verify the Laboratory
Subroutines Package (LSP) software and how to create a FORTRAN pro-

gram that calls the Laboratory Subroutines under the RSX-11M/M-PLUS
operating systems.

However, the appendix provides only general information about creating
programs. It does not include detailed information about the FORTRAN IV
or FORTRAN 77 programming languages, the FORTRAN IV or FORTRAN

77 compilers, the MACRO assembler, or the RSX-11M/M-PLUS operating

systems. For additional information on these topics, refer to the appropriate
RSX-11M/M-PLUS, FORTRAN IV, or FORTRAN 77 documentation cited
in this appendix.

B.1

Installation Requirements
Instructions in this appendix require that:
1.

All files acted upon by system programs are on the default device, SY:,

under your UIC, unless otherwise noted in this appendix.
2.

You use the default file extensions which are:
JFTN

MAC

FORTRAN source files
MACRO source files

.OBJ

object files

.OLB

object library files

TSK

task-image (executable) files

The system MACRO libraries, RSXMAC.SML and EXEMC.MLB, have

already been built and reside on the system device, SY:.

Either the FORTRAN IV or the FORTRAN 77 compiler has already
been built and resides on the system device, SY:.

the FORTRAN Object Time System (FOROTS) or
the
FORTRAN 77 Object Time System (F4POTS) has been
built and added
to the system library, SYSLIB.OLB, which resides on the
system device, SY:. Make sure that only the object time system
you will use is
added to the system library.

If you use FORTRAN 77 and you want to duplicate the
terminal output
for the example programs, replace the standard random
-number gener-

Either

ator in F4POTS with F4PRAN.OBJ. Terminal output
for the example
programs is based on the FORTRAN IV random-numbe
r generator. The

FORTRAN 77 random-number generator is differe
nt from that for
FORTRAN IV and will not produce the same output.
To replace the
standard random-number generator with FAPRAN.OBJ ,
set the UIC to
[1,1] and use the following command:
sLBR SYSLIB=dun:[9.:mIF4PRAN/RPREN

where:

dvn:

is the device where FAPRAN.OBJ resides

[g,m]

is the UIC that F4PRAN.OBJ is stored under

System utility programs, for example DSC, FLX, LBR,
and the
RSX-11M task-builder, TKB, have been installed and reside
on the
system device, SY:.

All necessary system programs and files are installed and

system device, SY:.

B.2

reside on the

All tasks and MCR functions are installed.

Installing the Laboratory Subroutines Software
Installing the Laboratory Subroutines software consists of

copying the LSP
distribution volume and making any necessary corrections to
the LSP
software.
If you wish to run any of the options described in this manual,
also run the file LSPMAK.TSK which is part of your distribu

you must

ted LSP software. LSPMAK builds the subroutines by assembling them
with the options enabled. You can also use LSPMAK to build the subrouti
nes without
any options. Section B.2.3.2 explains how to use LSPMAK.

B.2.1

Copying the Distribution Volume

Because all storage media can be adversely affected by environ
mental conditions, vandalism, and human error, it is a good idea to keep several
copies
of any software that cannot be easily recreated. Copy the LSP distribut
ion
volume and then store it in a safe place. Use the distribution volume
only
when copying the LSP software. Use only copies for all other procedur
es
described in this appendix.

B-2

Installing, Verifying, and Using LSP Under RSX-11M

The LSP software is distributed on a single
volume. Most of the LSP distribution volumes are in FILES-11 forma
t which RSX-11M/M-PLUS can
read. Magnetic tape distribution volumes,
however, are in DOS-11 format
which RSX-11M/M-PLUS cannot read.
Copy procedures vary depending on the type
of distribution volume and the
number of mass storage devices you have:
e If your distribution volume is a FILE
S-11 volume such as an RKO5,
RKO06, RLO1, or RL02 disk and you have
three or more mass storage

devices, follow the instructions in Section

e If your distribution volume is a FILES—11
mass storage devices, follow the instru

B.2.1.1.

volume and you have only two

ctions in Section B.2.1.2.

o If your distribution volume is a DOS-

the instructions in Section B.2.1.3.

11 formatted magnetic tape, follow

B.2.1.1
Copying a FILES-11 Distribution Volum
e with Three or More Mass
Storage Devices —
To copy a FILES-11 distribution
volume, do the

following:
1.

Load the distribution volume. Allocate
the drive and mount the distribution volume. The volume label for
the Laboratory Subroutines is
LSP. The User Identification Code (UIC)
is [200,200]. Type:
>ALL dun @D
>MOU dun: LSPRE

Load a blank storage volume. Allocate

the drive. Type:

>ALL dun s RED

If you use RSX-11M-PLUS, mount
the blank storage volume foreign
since it has not yet been initialized as
a FILES-11 volume. Type:
*MCU durn s /FORGEED

Format the blank storage volume if neces
sary. If you use RKO05 disks,
format each disk. If you use RX02 drives
, format each diskette to be
either low (single) or high (double) densi
ty. Other storage media cannot
be formatted.

Use the RSX utility FMT to format your
disks and diskettes. The following example formats an RK05 disk:
>FMT OK2:ReD
**

WARNING

CONTINUE?

DATA WILL BE LOST ON DK2:

[Y OR NJ V@D

START FORMATTING
OPERATION COMPLETE
>

Installing, Verifying, and Using LSP Under RSX-1

B-3

When you use FMT, diskettes on RX02 drives are formatted to be low

(single) density by default. If you want them to be high (double) den-

sity, use the /DENS
= HIGH option. The following example formats an

RXO02 diskette to be double density:
+FMT DY1:/DENS=HIGHED
**%

WARNING

CONTINUE?

DATAMWILL BELOSTONDY1:

#*#

[Y OR N3] YED

START FORMATTING
OPERATION COMPLETE

See the RSX-11 Utilities Manual for more information about FMT.
Run the Bad Block Locator Utility (BAD) to search for bad blocks on
the storage volume. The /LI switch causes BAD to list at your terminal

the decimal number of any bad blocks found. Type:
SBAD dun s /LIED

If BAD finds bad blocks, it types a message for each one found. An

example of the message is:
BAD

dun: BAD BLOCK FOUND

LBN

pmnnnnmn

LBN means Logical Block Number, and nnnnnn is the decimal number

of the bad block found. When BAD finishes reading the storage volume
it types a message telling how many bad blocks it found:
BAD

dun: TOTAL BAD BLOCKS=

If BAD found none, it types 0. If your volume has bad blocks, isolate

them using the /BAD=[AUTO] option with the INI command (see
step 6).

If BAD types any other message, see Chapter 9 of the RSX-11 Utilities
Manual to find out what the message means and what to do about it.

Initialize the blank storage volume so it will be in FILES-11 format.
Use the MCR command INI with the /BAD =[AUTO] option to isolate
bad blocks on the volume. Type:
sINI dun:/BAD=LAUTOIRED
INI

NO BAD BLOCK DATA FOUND

If you use RSX-11M-PLUS, INI does not type the above message; it
just displays its prompt to indicate it found no bad blocks.

See the RSX-11M/M-PLUS MCR Operations Manual for more information about using the MCR command INI.

Installing, Verifying, and Using LSP Under RSX-11M

If you use RSX-11M-PLUS, your storage volume is still mounted for-

eign although it is now in FILES-11 format. Dismount it. Type:
>DMOU
dunr : RET

For both RSX-11M and RSX-11M-PLUS, mount the volume as a
FILES-11 volume. Type:
dun ;@B
*MOU

Use the RSX Disc Save and Compress Utility (DSC) to copy files from
the distribution volume to the storage volume. The following example

copies files from a distribution volume on drive 1 to a storage volume on

drive 2:

>DSC du2:=4dul:
BT

See the RSX-11 Utilities Manual for more information about using
DSC to copy files.
B.2.1.2 Copying a FILES-11 Distribution Volume with only Two Mass
Storage
Devices — If you have only two mass storage devices, you can not copy the

LSP distribution volume directly since the RSX-11M/M-PLUS system volume occupies one of your mass storage devices.

To copy the distribution volume under these circumstances, use the RSX
utility program DSCS8. DSCSS8 is a stand alone version of DSC. Once
booted, DSCS8 no longer needs the system volume. You can unload the

system volume thus freeing the system device. Then you can load the LSP

distribution volume in the system device and begin copying files. The fol-

lowing procedure explains how to copy the distribution volume using
DSCSS.
NOTE

Since this procedure requires you to remove the system volume, and halt the processor, make sure that no one else is

using the system when you execute the procedure.

Load a blank storage volume. Allocate the drive it is on. Type:
>A
dur
LL
GO

If you use RSX-11M-PLUS, mount the blank storage volume foreign

since it has not yet been initialized as a FILES-11 volume. Type:
>MOU dun:/FORRED

Format the blank storage volume if necessary. If you use RK05 disks,
format each disk. If you use RX02 drives, format each diskette to be

either low (single) or high (double) density. Other storage media can
not be formatted.

Installing, Verifying, and Using LSP Under RSX-11M

B-5

Use the RSX utility FMT to format your disks and diskettes. The following example formats an RK05 disk:
>FMT DK1 :ReED
*%

WARNING

CONTINUE?

DATA WILL BE LOST ONDK1:

#*%*

[Y OR N1 Y@

START FORMATTING

OPERATION COMPLETE

When you use FMT, diskettes on RX02 drives are formatted to be low

(single) density by default. If you want them to be high (double) den-

sity, use the /DENS = HIGH option. The following example formats an
RX02 diskette to be double density:
*FMT DY1:/DENS=HIGHGRED
*%

WARNING

CONTINUE?

DATA WILL BELOSTONDY1:

*=*

[Y OR NJ YRED

START FORMATTING

OPERATION COMPLETE

See the RSX-11 Utilities Manual for more information about FMT.
4.

Run the Bad Block Locator Utility (BAD) to search for bad blocks on
the storage volume. The /LI switch causes BAD to list at your terminal

the decimal number of any bad blocks found. Type:
*BAD dur /L IGD
BAD

NO BAD BLOCK DATA FOUND

If BAD finds bad blocks, it types a message for each one found. An
example of the message is:
BAD

durn: BAD BLOCK FOUND

LBN

nnnnnn

LBN means Logical Block

Number, and nnnnnn is the decimal number
of the bad block found. When BAD finishes reading the storage volume,

it types a message telling how many bad blocks it found:
BAD

dun:

TOTAL BAD BLOCKS=

If BAD found none, it types 0. If your volume has bad blocks, isolate

them using the /BAD=[AUTO]

option with the INI command (see

step 6).

If BAD types any other message, see Chapter 9 of the RSX-11 Utilities
Manual to find out what the message means and what to do about it.
5.

Initialize the blank storage volume so it will be in FILES-11 format.

Use the MCR command INI with the /BAD =[AUTO] option to isolate
bad blocks on the volume. Type:

B-6

Installing, Verifying, and Using LSP Under RSX-11M

#INI dun:/BAD=CAUTOIGD
INI

NO BAD BLOCK DATA FOUND

If you use RSX-11M-PLUS, INI does not
type the above message; it
Just displays its prompt to indicate it found no
bad blocks.
See the RSX-11M/M-PLUS MCR Operations
Manual for more infor-

mation about using the MCR command INI.

Boot DSCSS8. The UIC is [1,51]. Type:
#BOOT [1,511DSCSBERD
RAS115 V2,2 BL26 DISC SAYE AND
COMPRESS UTILITY Y 3,7

DSCS8 displays its prompt. It is now boote

d and ready for input.

DSCS8

Remove the RSX-11M/M-PLUS system volum
e and load a copy of the
LSP distribution volume in the system device
.
Now instruct DSCSS8 to
begin copying files. The following example
copies files from a distribution volume, on drive 0 to a storage volum
e on drive 1:
DSCS8>dul:=du0:
RN

Copying now begins. When it completes,

DSCSS8 displays its prompt.

DSCS8:

Now halt the processor. Remove the LSP distri

system

device

and

RSX-11M-PLUS.

replace

the

system

bution volume from the

volume.

Boot RSX-11M or

See the RSX-11 Utilities Manual for more
information about using
DSCSS to copy files if you have only two mass
storage devices. Information about DSCS8 (sometimes called
“stand-alone DSC”) is in the
chapter on DSC.
B.2.1.3

Copying a DOS-11 Distribution Volum

tion magnetic tape, do the following:
1.

e — To copy a DOS-11 distribu-

Load the distribution volume. Allocate
the drive and mount the distribution volume. The User Identification Code
(UIC) is [200,200]. Type:
>ALL dun @D
*MOU dun : RED

Load a blank storage volume. Allocate the drive

it is on. Type:

ALL dun RO

If you use RSX-11M-PLUS, mount the
blank storage volume foreign
since it has not yet been initialized as
a FILES—11 volume. Type:
>MOU dun: /FORGRE)

Installing, Verifying, and Using LSP Under

RSX-11M

B-7

Format the blank storage volume if necessary. If you use RK05 disks,

format each disk. If you use RX02 drives, format each diskette to be
either low (single) or high (double) density. Other storage media cannot

be formatted.

Use the RSX utility FMT to format your disks and diskettes. The following example formats an RK05 disk:
>FMT DK
1 : GED
#%

WARNING

CONTINUE?

DATAWILL BE LOST ONDK1:

[Y OR N1 YRET

START FORMATTING
OPERATION COMPLETE

When you use FMT, diskettes on RX02 drives are formatted to be low
(single) density by default. If you want them to be high (double) den-

sity, use the /DENS=HIGH option. The following example formats an
RXO02 diskette to be double density:
>FMT DY1:/DENS=HIGHGRT
*##*

WARNING

CONTINUE?

DATAWILL BE LOSTONDY1:

[Y OR N1 Y@

START FORMATTING
OPERATION COMPLETE
>

See the RSX-11 Utilities Manual for more information about FMT.
Run the Bad Block Locator Utility (BAD) to search for bad blocks on

the storage volume. The /LI switch causes BAD to list at your terminal
the decimal number of any bad blocks found. Type:
>BAD dun: /L IRED
BAD

NO BAD BLOCK DATA FOUND

If BAD finds bad blocks, it types a message for each one found. An
example of the message is:
BAD

dun: BAD BLOCK FOUND

LBN

nnnnnn

LBN means Logical Block Number, and nnnnnn is the decimal number

of the bad block found. When BAD finishes reading the storage volume,
it types a message telling how many bad blocks it found:
BAD

dun: TOTAL BAD BLOCKS=

If BAD found none, it types 0. If your volume has bad blocks, isolate
them using the /BAD=[AUTO]

option with the

step 6).

B-8

Installing, Verifying, and Using LSP Under RSX-11M

INI command (see

If BAD types any other message, see Chapter 9 of the RSX—11

Manual

find

out

what

about it.

the

message

means

and

Utilities

what

Initialize the blank storage volume so it will be in FILES—

11 format.
Use the MCR command INI with the /BAD =[AUTO] option to
isolate
the bad blocks on the volume. Type:
*INI

dun:/BAD=LAUTO
IR

INI

NO BAD BLOCK DATA FOUND

If you use RSX-11M-PLUS, INI does not type the above message
; it
Just displays its prompt to indicate it found no bad blocks.

See the RSX-11M/M-PLUS MCR Operations Manual for more

mation about using the MCR command INI.

infor-

If you use RSX-11M-PLUS, your storage volume is still mounted
foreign although it is now in FILES-11 format. Dismount it. Type:
*DMOU dunr :RED

For both RSX-11M and RSX-11M-PLUS, mount the volume
as a
FILES-11 volume. Type:
*MOU dun : R

Create a UIC of [200,200] on the storage volume. Use the
MCR command UFD (User File Directory). Type:
UFD dun:[200 4,200 1R

10. Use the RSX utility FLX to copy files from the

DOS-11 distribution

tape to your FILES-11 storage volume. The /RS switch
identifies the
storage volume as a FILES-11 volume, and the /DO
switch identifies

the distribution volume as a DOS-11 volume. The wildcar
d construction, *.*, tells RSX-11M/M-PLUS that you wish to copy the
most recent
version of all files. (You cannot specify version number
s on a DOS—11
formatted volume.)

The following example copies files from a DOS—11 distribu
on drive 0 to a FILES-11 storage volume on drive 1:
PRLX
>

tion volume

vl :[2004,2001/RS=du0:[200,2001%, %/D0G

See the RSX-11 Utilities Manual for more information about

FLX.

11. Use the RSX-11M utility program PIP to create a contigu
ous file from
LSPMAK.TSK, the interactive build procedure. Type:
>PIP

/CO=C200,2001LSPMAK . TSKGRED

See the RSX-11 Utilities Manual for more information about

PIP.

Installing, Verifying, and Using LSP Under RSX-11M

B-9

B.2.2

Making Corrections

From time to time, the RSX-11M/S-RSX-11M-PLUS Software Dispatch
publishes corrections you must make to the LSP software. The dispatch also

publishes instructions on how to make the corrections.

You only need to make corrections published in the dispatch for version

1.2
of the LSP software. Corrections that were published in the dispatch for

previous versions of LSP have already been included in version 1.2.

Never make corrections to your distribution volume. Make corrections to

your copies. After making any corrections, copy your software again.

B.2.3

Selecting the Form of Subroutine to Use

You receive the Laboratory Subroutines as both object files and MACRO

source files. Read Sections B.2.3.1 and B.2.3.2 to determine which form of

the subroutine to use.
B.2.3.1

files if:

Using Distributed Object Files —

You can use the distributed object

Youdo not want to enable any of the options described in this manual.

You are using FORTRAN IV.

Your system does not have a hardware floating-point unit.

You use the distributed object files by task-building them to your
FORTRAN programs. (See Section 1.2 for a list of the LSP files.) Before you

do so, however, test them to verify that they work correctly by running the

program LSPVER.CMD which is part of your distributed LSP software. See

Section B.3 for information about how to run LSPVER.CMD.
B.23.2

Creating Customized Object Files — LSPMAK, the Interactive Build
If you want to enable any of the options described in this

Procedure —

manual, use the interactive build procedure, LSPMAK.TSK, to create customized object files of the Laboratory Subroutines from the distributed
source files. You can also use LSPMAK to build the subroutines without
any options. (See Section 1.2 for a list of the LSP files.)

LSPMAK.TSK is part of your distributed LSP software. It lets you specify
the subroutines you want to assemble and the options you want to use.

Options available include:

B-10

library option — lets you place the subroutines in a library which you
create by supplying a library name.

hardware options — let you make use of EIS hardware (or any floatingpoint option) or EAE hardware if you have any.

FORTRAN options — let you specify whether or not you will be using
FORTRAN 77.

Installing, Verifying, and Using LSP Under RSX-11M

subroutine options — let you specify
which subroutines you want to
assemble and which options you want
to use for each subroutine.

When you run LSPMAK.TSK, it promp

ts you with questions. Most quesor option. Answer “yes” if you want
to
build the subroutine or enable the optio
n. Answer “no” if you do not. Some
tions give the name of a subroutine

questions request information and

tel] you how to type your answers.

Fol-

low the instructions given when you
respond. After you answer all the

questions, LSPMAK creates three
files on your output device under
the
current UIC as follows:

LSPCND.MAC — This file sets the
switches to enable the options you

requested.

LSPBLD.CMD — This indirect-com

mand file builds each subroutine you

requested. Building consists of assem
bling each subroutine you specified

with the switches set to enable the
options you chose. If you specified
a
library while running LSPMAK, LSP
BLD creates that library and includes
In it the subroutines you specified.

LSPVER.CMD — This indirect-com

ware 1s in good working order. It

mand file verifies that your LSP soft-

does this by running an example

that tests each subroutine you asked
Before

you

attempt

run

names to:

to build.

LSPMAK.TSK,

assign

program

logical

device

The device containing all the Labo
ratory Subroutines software. Assi
gn
this device the logical name “IN” for
“input device.” Type:
*ASN dur:=IN;:RE

The device receiving the assemble
d object files. Assign this device the
logical name “OU” for “output devic
e.” Type:
*ASN dun:=0U:RD

Now run the file LSPMAK.TSK. Type:
RUN IN:[200,2001LSPMAKGE
D)

The build procedure runs and begi

your terminal. The followin

ns typing questions and informat

ion on

g text shows all the question

s and information

that LSPMAK can type. However,
when you run LSPMAK, not all
the

questions and information will
appear since some of it depe
nds on your

responses to previous quest

appears in Appendix D.

ions. A sample of LSPMAK

.TSK and its output

Laboratory Subroutines
YU1,?2 Build Procedure for
RSX-11M

Have vou assidned dJevi
ces for input

(IN:)

and outeput

Installing, Verifying, and Using

(OU:)? LY/N]

LSP Under RSX-11M

B-11

NOTE:

This procedure assumes that all distributed files for
the Laboratory Subroutines packade are on dJevice "IN"
under UIC [200,2001].,

This procedure directs all output and tempPorary files

(excert library files) to device "OU" under the
default UIC.

LIBRARY OPTION

Do vouwant tobuild aNEWIlibrary file from these subroutines?
CY/N]

Enter the specification (maximumof 30 characters) of the
Jesired library file, (example SYO:[1,1]LSPLIB.OLB)
ENTER NAME
:

As each subroutine is added to the librarvs its corresponding
obdect file is normally deleted from device "0OU",
Is this accerptable? [Y/N]

HARDWARE OPTIONS

Does vyour machine have the EIS option (or any floatingd Point opPtion)?
(the EIS option) [Y/N]

Does vyour machine have the EAE ortion?
(the EAE option)

[Y/N]

FORTRAN OPTIONS

Will vou bhe using FORTRAN 777 (the F4P% option) [Y/N]

NOTE:

The software verification command files OU:LSPVER.CMD
will use FORTRAN IV to compile the Laboratory Subroutines

test programs. The task build procedure for these test
programs will assume that the appropriate FORTRAN IV
obJject time svystem library is added to the svystem library,

SYSLIB.OLB.

Also,s since vou have responded that vour svystem does not
have a floating-pPoint units, the task build procedure
Wwill assume that vour FORTRAN IV obJect time svystem
dJoes not require a floating-rPoint unit,

NOTE:

The software verification command files» OU:LSPVER.CMD, will
nuse FORTRAN 77 to compile the Laboratory Subroutines
test prodrams. The task build procedure for these test
prodrams will assume that the approprriate FORTRAN 77
obJject time system library is added to the svrstem library,
SysLIB.OLB.

B-12

Installing, Verifying, and Using LSP Under RSX-11M

SUBROUTINE AND ALGORITH
M OPTIONS

Do vou want to build the
subroutine "PEAK"? LY/N
]
Do vou want to disable
the software digital
filter?
(enable the NOFLTS orPt
ion) [Y/N]
Do you want to enable
double Pprecision inPu
t data Processing by
PEAK?
(the DPP$ option) [Y/N
]
Do you want to enable
Processing of coded A/D
input data by PEAK?
(the AUTOGS option) [Y/N
]

Do vouwant to build the
subroutirne "NUVELOP"?
[Y/N]

Do vou want to build the
subroutine "HISTI"? [Y/N
]
Do you want to enable
HISTI to produce a freq
uency histogram?
(the FREQ$ option) LY/N
]
Do vou want to enable
double Pprecision inPu
t data Processing by
HISTI?
(the DPH$ oPtion) [Y/N
]

Do you want to build the
subroutine "RHISTI"?
[Y/N)]
Do youwant to enable
double Precision inPu
t data Processing by
RHISTI?
(the DPR% ortion) CY/N
]

Do youwant to build the
subroutine "FFT"? CY/N
]
What is the maximum
lendth of anvy inPut arra
vy to be processed by
FFT
(the F.MAXN option):

10247 [Y/N]
20487 [Y/N]
40967 [Y/N]
81927 [Y/N]

**%*THE DEFAULT MAXI
MUM

INPUT ARRAY LENGTH
WILL BE USED

(1024) | %%

Do vou want to build
the subroutine "PHAMPL"
? [Y/N]

Do youwant to build
the subroutine "POWRSP"
? [Y/N]

NOTE:

CORREL needs subrouti
ne FFT to function!

Do youwant to build
the subroutine "COR
REL"? [Y/N]

This first po rtionof
the Laboratory Sub rout
ines build
Procedur
e

comrplete,

File LSPCND.,MAC has been
created on device "OU"
, Thig file
sets the
switches

have requested,

required

enable

the

oPtions

that

vou

File LSPBLD.CMD has
also been created on
device "QU", You
should execute this
indirect command fil
enext, It will
build each sub routine
requested on device
"OU", and create
the library file spPp
ecified,

Installing, Verifying, and Usin

g LSP Under RSX-11M

B-13

Finallvys the file LSPUER.CMD has bheenrn created on
You should execute this command file after using
tobuild vyour customized Laboratory Subroutines
This command file will verify that vrour software

device "0OU",
LSPBLD.CMD
obbdect files,
has been

successfully installed,
TTran -- STOP

Now run the indirect-command file LSPBLD.CMD. This file builds the subroutines you
requested on device “OU” and creates a library on that device if you specified one.
Type:
+»@0U: LSPBLDGRED

B.3

Verifying the Laboratory Subroutines Software
After installing the LSP software, test it to verify that you performed the
installation procedure correctly, and that your LSP software was delivered
in good working order. To do so, run the indirect-command file,
LSPVER.CMD. Instructions for running LSPVER.CMD follow. If you plan
to use the distributed object files, follow the instructions in Section B.3.1. If
you used LSPMAK, follow the instructions in Section B.3.2.

B.3.1

Verifying the Distributed LSP Object Files

To verify the distributed LSP object files, use the distributed version of
LSPVER.CMD. The distributed version of LSPVER.CMD runs the first example program in each chapter of this manual. These programs call the
distributed subroutine object files thus indicating whether they work correctly. Before attempting to run LSPVER, do the following:

Make

sure

that your

system

meets

the

requirements

listed in

Section B.1.

Assign logical device names. Assign the logical name “IN” to the device
containing the Laboratory Subroutines software. Assign the logical
name “OU” to the device which will be your output device.
To assign an input device, type:
ASN dun:=IN:RED

To assign an output device, type:
“ASN dunzs= ou :

Copy all of the object files for the Laboratory Subroutines to your output device. (See Section 1.2 for a list of the LSP files.)

Now run LSPVER. Type:
s@IN:[200,200]1LSPUVERRED

B-14

Installing, Verifying, and Using LSP Under RSX-11M

LSPVER types the name and number of each example program
it runs
along with the output from that program on your terminal. Compar
e the

output with that of the corresponding example in the manual.

If they do not
agree and you are sure you have not neglected any of the
requirements

listed in Section B.1, you may have received a defective copy
of your LSP
software. Contact DIGITAL for more information.

B.3.2

Verifying the Customized Object Files

To verify your customized object files, use the version
of LSPVER.CMD
that was created when you ran LSPMAK. This version of
LSPVER.CMD
runs the example program that calls the version of the subrout
ine with the
options you enabled. To run LSPVER, do the following:
1.

Make sure that the device assignments for “IN” and

“OU” in Section
B.2.3.2 are still in effect. If they are not, assign them
so they are the
same as when you ran the LSPMAK.

Now run LSPVER. Type:
#B0U: LSPVERRE

LSPVER types the name and number of each exampl
e program it runs
along with the output from that program on your termina
l. Compare the

output with that of the corresponding example progra

m in the manual. If

they do not agree, and if you are sure you have not neglect

ed any of the

requirements listed in Section B.1, you may have receive

d a defective copy

of your LSP software. Contact DIGITAL for more informa

tion.

B.4

Storing the Laboratory Subroutines
After determining that the Laboratory Subroutines
you want to use are
sound, copy them to your system volume or to the
development volume
where you store your FORTRAN programs, or place
them in a library (see

Section B.6).

B.5

Creating a Program that Calls the Laboratory Subro

utines

To create a FORTRAN program that calls the Labora
tory Subroutines, do
the following:
1.

Write and check your program.

Use one of the RSX-11M/M-PLUS editors, such

program into a source file. Type:

as EDI, to enter your

*EDI Prog.FTNGRE

where:

prog

1s the name of your FORTRAN source program.

For information about entering the text of your
file, making changes
and displaying the file, see the RSX—11 Utiliti
es Manual and the
RSX-11M/M-PLUS Guide to Program Development.

Installing, Verifying, and Using LSP Under

RSX-11M

B-15

NOTE

Always specify a file extension when you use an editor.
RSX-11M/M-PLUS editors do not use default file extensions. In this case, give your source file the extension
FTN since that is the default extension the FORTRAN

IV or FORTRAN 77 compiler uses when it compiles your
program.

Use the FORTRAN IV or

of your program.

FORTRAN 77 compiler to create an object file

If you are using the FORTRAN IV compiler, Type:
PREOR

mreog=e
g L PY

’’’’

If you are using the FORTRAN 77 compiler, Type:
2877

prog=ogg
R

where:
4.

prog

is the name of your FORTRAN source program.

Use the RSX-11M/M-PLUS task builder to task-build the object file of
your program with the object files of your Laboratory Subroutines. The

/FP switch tells the task-builder to use the floating-point unit. Use the

/FP switch if you use FORTRAN IV and your system has a floating-

point unit. Always use the /FP switch if you use FORTRAN 77 since

your system always has a floating-point unit. Type:
PTRB progl/FPI=pP
. ronlsenb2 0 rog
subn®

where:

prog

is the name of your FORTRAN program.

subl

is the name of the first Laboratory Subroutine object
file you want to task build.

subn

is the name of the last Laboratory Subroutine object
file you want to task build.

You can specify as many object files as you wish for input. However, if
your list of input files will use more than one line on your terminal, you
should see the RSX-11M/M—-PLUS Task Builder Manual for information about how to input files using multiple lines.

To avoid linking individual subroutines to your programs, you can
place the subroutines in a library. See Section B.6.

Run the task. Type:
>RUN progRD

where:

prog

1is the name of your executable program.

For more information about compiling, linking, and running FORTRAN
programs, see the RSX-11M/M-PLUS Guide to Program Development, the
IAS/RSX-11 FORTRAN 1V User’s Guide, and the PDP-11 FORTRAN 77
User’s Guide.

B-16

Installing, Verifying, and Using LSP Under RSX-11M

B.6

Using Libraries
Once you decide which of the Laboratory Subroutines you will use most
frequently, you can task-build them to your programs more easily by placing them in a library. When you place them in a library, you do not need to

list each individual subroutine in the TKB command line. You only need to

list the library name. When you place them in the system library,
SYSLIB.OLB, you do not even need to list the library name in the TKB

command

line.

The

RSX-11M/M-PLUS task builder automatically
searches the system library for a subroutine or function needed by a

program.

For example, suppose your compiled program, MYPROG.OBJ calls the sub-

routines FPEAK.OBJ and F4FFT.OBJ. To task-build MYPROG, you have

to type:
*TKB

MYPROGL/FPI=MYPROG
»FPEAK «FAFF TRED

If you place the subroutines in a library called, for example, MYLIB.OLB,
you task-build MYPROG by typing:
*TKB

MYPROGL/FP1=MYPROG yMYLIB/LBRE

You have to use the /LB switch to tell RSX—11M/M-PLUS that MYLIB is a

library file. However, if you add the subroutines to the system library,
SYSLIB.OLB, you task-build MYPROG by typing:
ROGGRE
>TKB MYPROGL/FP1=MYP

Note that the interactive build procedure, LSPMAK, allows you to create a

library of your own. If you use this option, LSPMAK places in the library

those subroutines you tell it to build in response to later questions. If you do

not use this option when you first run LSPMAK, but later decide you want
to use a library, you can either rerun LSPMAK or use the RSX utility
program LBR to create a new library or add to an existing one.

See the RSX-11 Utilities Manual for information about using LBR. The
RSX-11 Utilities Manual also tells you how to use the system library.

Installing, Verifying, and Using LSP Under RSX-11M

B-17

Appendix C

Sample of the Interactive Build Procedure
for
RT-11, LSPMAK.SAV

The

following

example shows
LSPMAK.SAV with its output.

the

interactive

build

procedure,

The example does the following:
1.

Places the subroutines in a new library called

Enables the EIS option.

Builds the following subroutines:

LSPLIB.OBJ.

e PEAK — with the double-precision intege

enabled.

rs option (the DPP$ option)

o FFT — with a maximum input array lengt

h of 8192.

C-1

+ASSIGN DMO:

IN:&S

+ASSIGN DLO: QU :ReT
+RUN IN:LSPMAKERED)

Laboratory Subroutines Y1.2Build Procedure for RT7-11

Have vyou assidned devices for inPut

NOTE:

(IN:)

and outeput

(OU:)? [Y/N]I

This procedure assumes that all distributed files for
the Laboratory Subroutines packade are on dJevice "IN",
This procedure directs all output and temrporary files
(exceprt

library files)

to device "0OU",

LIBRARY OPTION

Do vouwant to build a NEW library file from these subroutines?
Enter the specification

desired library file,

ENTER NAME:

(maximumof 14 characters)

of the

(example DK:LSPLIB.OBJ)

DLO:LSPLIB,OBJRD

As each subroutine is added to the librarvsy 1ts corresponding

obJect file is normally deleted from device "OU":

Is this acceptable? [Y/N]

NGED

HARDWARE OPTIONS

Does vyour machine have the EIS oprtion (or anvy floatind point oprtion)?

(the EIS option) [Y/N]

SUBROUTINE AND ALGORITHM OPTIONS

Do vouwant to build the subroutine "PEAK"? [Y/N]

YGRE

Do vyou want to disable the software didgital filter?

(enable the NOFLT$ option)

[Y/N]

NERD

Do youwant to enable double precision inpPut data processing by PEAR?

(the DPP$ option) [Y/N]

YERET

Do you want to build the subroutine "NVELOP"? [Y/N]

Do vou want to build the subroutine "HISTI"? [Y/N]

NGED

NERE

Do youwant to build the subroutine "RHISTI"? [Y/N]

Do youwant to build the subroutine "FFT"? [Y/N]

NGEED

YG&ED

What 1s the maximum lendth of any inpPut array to be processed by FFT
(the F.MAXN orPtion)

10247 [Y/N]
20487 [Y/N]1

C-2

NGEE
NGEED

Sample of the Interactive Build Procedure for RT-11, LSPMAK.SAV

81927 [Y/N]

Do vouwant to build the subroutine

"PHAMPL"? [Y/N]

Do vouwant to build the subroutine "POWRSP"? [Y/N]

Do vouwant to build the subroutine "CORREL"? [Y/N]

NET

This first portion of the Laboratory Subrout
ines build
Procedure is complete,
File LSPCND.MAC has beern created on dJevice
"OU", This file
sets

the

have

requested,

switches

reauired

to enable

the oPptions

that

vyou

File LSPBLD.COM has also been created on
Jevice "OU", You
should execute this indirect command file
next, It will
build each subroutine reauested on device
"QU" and create
the library file specified, DLO:LSPLIB.OBJ.

Finallv, the file LSPUER.COM has been created
on Jevice "0OU",
You should execute this command file after
using LSPBLD.COM
tobuild vour customized Laboratory Subrout
ines obJect files,
This command file will verify that vyour softwar
e has been
successfully

installed,

STOP --

+MACRO/0BJECT:0U:FPEAK
ERRORS DETECTED:

OU:LSPCND+IN:FPEAK

+LIBRARY /CREATE DL:LSPLIB.0OBJ OU:FPEAK
+MACRO/OBJECT:0U:FA4FFT

ERRORS DETECTED:

OU:LSPCND+IN:FAFFT

+LIBRARY DL:LSPLIB.OBJ OU:FAFFT

+FORTRAN/OBJECT:0U:LSPEX IN:EX4UFPE
+MAIN,

+LINK/EXECUTE:OU:LSPEX OU:LSPEX DL:LSPLIB.0OBJ

+RUN OU:LSPEX

Sample of the Interactive Build Procedure for

RT-11, LSPMAK.SAV

C-3

PEAK

NO.

AREA

P HEIGHT

P TIME

HALF WIDTH

T HEIGHT

32158219,

952958,

11,

483071,

10732416,

432238,

Example

L HEIGHT

L TIME

TYPE

RATE

20,

693113,

a4d.

BASELINE

G8.

344193,

od.

TIME

189827,

83.

BASEL INE

134705883,

300062,

BOO,

14923,

107,

119,

201630,

VALLEY

STOP -+DELETE/NOQUERY

OU:LSPEX . %

+FORTRAN/OBJECT :0U:LSPEX IN:EX1FAF
+MAIN,

+LINK/EXECUTE:OU:LSPEX
OU:LSPEX DL:LSPLIB.OBJ
+RUN OU:LSPEX
FFT Example
#1

DATA TO BE TRANSFORMED - SINE WAVE SCALED BY 1000,
REAL PART

195

382

1000

980

923

-195

-382

-1000

-980

-923

(ss QUG
Qs
JNO)
WUnwa
— N e N

707

831

923

707

555

382

195

-707

-831

-923

-980

=707

-555

-382

-195

980

- IMAGINARY PART
Q

§)

)

RESULTS FROM THE FORWARD FOURIER

-7

rRM G

OMNOMN

- REAL PART -

- IMAGINARY PART
-

C-4

-15981

-5

-1

-4
rr

Sample of the Interactive Build Procedure for RT-11, LSPMAK.SAV

0
15984

RESULTS FROM THE INVERSE FOURIER TRANSF
ORM
-

BEFORE SCALING

- REAL PART
-

-4

6217

12200

31972

17749

31354

22598

29952

26578

26582

29531

-6217

22604

-12200

177352

-31972

-17749

1222

-31354

-22598

-298952

-26578

-26582

-29531

-22604

-31356

-17752

-1222

-62%54

-9

-6

-17

-5

-2

-14

-15

-20

- IMAGINARY PART
-12
-8
-

-9

31356
6254

)

-4

)

AFTER SCALING -

979

- REAL PART -

194

381

999

o094

979

706

922

830

-194

706

-381
-922

-830

195

-979

-706

381

-999

-394

o9d

-830

-922

-706

-979

-554

-381

-195

IMAGINARY PART
0

)

STOP --

DELETE/NOQUERY OU:LSPEX.,
¢

Sample of the Interactive Build Procedure for

RT-11,

LSPMAK .SAV

C-5

Appendix D

Sample of the Interactive Build Procedure for
RSX-11M, LSPMAK.TSK

The

following example
shows
LSPMAK.TSK with its output.

the

interactive

build

procedure

’

The example does the following:
1.

Places the subroutines in a new library called LSPLIB

Enables the EIS option.

Enables the FORTRAN 77 option (the F4P$ option)

Builds the following subroutines:

.OLB.

e PEAK — with the double-precision integers option

enabled.

FFT — with a maximum input array length of

(the DPP$ option)

8192.

*ASN DM1:=1IN:@
*ASN DR2:=0U:RD
*RUN IN:[200,200]1LSPMAKRE)

Laboratory Subroutines V1,2 Build Procedure for RS¥-11M

Have vou assidned devices for input
NOTE:

(IN:)

and outeut

(OU:)? [Y/N]

Y RED)

This procedure assumes that all distributed files for
the Laboratory Subroutines packade are on device "IN"

under UIC [200,2007,
This procedure directs all output and temporary files
(exceprt librarv files) to device "OU" under the
dJefault UIC.,

LIBRARY OPTION

Do vouwant to build a NEW librarv file from these subroutinesg?

[Y/N]

YRED

Enter the specification

desired librarv file,
ENTER NAME:

(maximum of 30 characters) of the
(example SYO:[1,+11LSPLIB.OLB)

DRZ2:[201,2011LSPLIB,OLBRY

As each subroutine is added to the librarv,s its corresponding
obJect file is normally deleted from device "QU":,

Is this acceptable? [Y¥Y/N]

HARDWARE OPTIONS

Does vour machine have the EIS ortion
(the EIS option)

[Y/N]

(or any floating Ppoint oPption)?

Y@e

FORTRAN OPTIONS

Will vou be using FORTRAN 777 (the FAP% option)

NOTE:

[Y/N]

The software verification command filey OU:LSPYER.CMD, will
use FORTRAN 77 to compile the Laboratory Subroutines
test prodrams,

Prodrams will

The task build procedure for these test

assume that the appProprriate FORTRAN 77

obJect time system library

is added to the system library

SYSLIB.OLB.

SUBROUTINE AND ALGORITHM OPTIONS

Do vouwant to build the subroutine "PEAK"? [Y/N]

Do you want to disable the software digital filter?
(enable the NOFLT$ option) [Y/N] NRED
Do you want to enable double precision inPut data processing by PEAK?
(the DPP$ option) [Y/N] Y@

D-2

Sample of the Interactive Build Procedure for RSX-11, LSPMAK.TSK

Do vou want to build the
subroutine "NUVELOP"? [Y/N
]
Do vouwant to build the
subroutine "HISTI"? [Y/N
J

N@RET

NGRED

Do vouwant to build the
subroutine "RHISTI"? [Y/N
]

NRET

Do vouwant to build the
subroutine "FFT"? [Y/N
] Y (RET
What is the maximum leng
th of any input array
to be processed by FFT
(the FIMAXN ortion)
10247 [Y/NI NET
20487 [Y/N]1
40967 [Y/N]
B1927 [Y/N]1

NGE

NRD

Do vou want to build the
subroutine "PHAMPL"?
[Y/N]

NQRET

Do ou want to build
the subroutine "POWRSP"
? [Y/N]

NEe)

Do vyou want to build the
subroutine "CORREL"?
CY/N]

NRE

This first po rtion of
the Latbo ratory Subrouti
nes build
Proc
edure

complete,

File LSPCND.MAC has
beeri created on devi
ce "OU",
sets

the

have

requested,

switches

required

enable

the

oPtions

Thisg file
that

vou

File LSPBLD.CMD has
also beern created on
Jevice "QU", You
should execute this
indirect command file
next, It will
build each subrouti
ne requested on devi
ce "OU" and create
the library file spec
ified) DR2:[201 »201
1LSPLIB,OLB,
Finallv,y the file LSPU
YER,CMD has been crea
ted on device "QU",
You should execute this
command file after usin
g LSPBLD.CMD
tobuil
d

vour customized Labo
rato

ry Subroutines obje
ct files,
This command file Will
verify that vour soft
ware has been
successf
ully

installed,

TT41 -- STOP

*@0U:LSPBLDEED
*MAC OU:FPEAK =0U
:LSPCND,IN:[

200,20

0]1
PEAF
K
*LBR DRZ:[201,2011LSP
LIB.OLB/CR=0U:FPEAK
*MAC OU:FAFFT =0U:LS
PCNDIN:[200,2001F4
FFT
*LBR DRZ:[201,2011LSP
LIB,OLB=0U:FA4FFT

*@ <{EOF
:

*@OU:LSPVERGED
*F77 OU:LSPEX=IN:[20
0,2001EXAFPE
}TKBOU:LSPEX/FP=OU
:LSPEX,DR2:[201,20
1]LSPLIB.DLB/LB
*RUN OU:LSPEX

Sample of the Interactive Build

Procedure for RSX-11, LSPMAK

.TSK

D-3

PEAR Example #d
AREA

P HEIGHT

P TIME

L HEIGHT

L TIME

HALF WIDTH

T HEIGHT

T TIME

TYPE

RATE

32158219,

952958,

20,

693113,

11,

483071,

a4,

BASEL INE

10732416,

452258,

68.

344193,

od,

r-J

PEAK NO.

189827,

83.

BASEL INE

134705883,

300062,

GO0,

14923,

107,

119,

201630,

839.

VALLEY

1.,

>PIP OU:LSPEX.*3%/DE

>F77 OU:LSPEX=IN:[200,200]EX1F4F

>TKB OU:LSPEX/FP =0QU:LSPEXDR2:[201,2011LSPLIB.OLB/LB
>RUN OU:LSPEX

#1
FFTExample

DATA TO BE TRANSFORMED - SINE WAVE SCALED BY 1000,
- REAL PART

382
923
-382
-923

195
980
-195
-980

0
1000
0

1000

atedal
831

70
70

-959%5

-70

-831

-70

980

831

923

299

382

195

-831

-923

-980

-335

-382

-1995

- IMAGINARY PART
0

RESULTS FROM THE FORWARD FOURIER
-

-7

- IMAGINARY PART
-15981
0
-3
0
-1
0
-1
0

0
0
0
0

-6

- L

Lo AN

- REAL PART

-4

15984

-2

RESULTS FROM THE INVERSE FOURIER TRANSFORM
- BEFORE SCALING -

29531

17732

12223

6254

-12200

-26578

-29331

-31356

-29527

_26582

-22B60 4

-17732

-1222

-6254

-14

-4

Sample of the Interactive Build Procedure for RSX-11, LSPMAK.TSK

- 6

r~J

-B

-17

-9
-6
9
6

-3135%4

-31972

-6217

{

12200
29527

OMRNON

26578

2260 4
-2259 8

6217
31354

2259 8

-4
31972

- IMAGINARY PART
-8
-12
-3
-4
8
12
>
4

31356

17749
26582
17749

—

- REAL PART -

- AFTER SCALING -

- REAL PART
-

194

999

381

979

294

922

706

830

706

922

354

381

195

879

-194

-381

-999

-334

-979

-706

-922

-830

-922

-706

-979

-394

-381

-195

- IMAGINARY PART
Q

§)

TT41
-- STOP

0
O

>PIP OU:LSPEX.,*i%/DE

>@ <EOF>
>

Sample of the Interactive Build Proc

edure for RSX-11, LSPMAK.TSK

D-5

IndeXx

Algorithm,

envelope-processing, 3—1
peak-processing, 2—1

PHAMPL, 7-1

POWRSP, 8-1
Aliasing, 6-8
ALL command, B-3, B-5, B-7
Amplitude spectra, 7-1

Amplitudes, 7-1 to 7-12

Baseline

definition of, 2—6
Baseline correction, 3—22

Baseline value,

NVELOP, 3-3, 3-17, 3-18
BOOT command, B-7
Build procedure,

Interactive, 1-3, 1-5, A-6 to A-9, B-10 to
B-14, C-1, D-1

Angle,

phase, 7-1 to 7-12
Approximate Fourier transform, 6-2, 6-13
Area,

peak, 2-1, 24, 3—4
Arguments,

CORREL, 9-5 to 9-6
FFT, 6-13

HISTI, 4-5 to 4-6
NVELOP, 3-16 to 3-20
PEAK, 2-17 to 2-20

PHAMPL, 7-2
POWRSP, 8-2

RHISTI, 5-7, 5-8
ASN command, B-11, B-14
Assembler,

RSX-11M MACRO, B-1

RT-11 MACRO, A-1

ASSIGN command, A-6, A-9
ATAN2, 7-2

Auto-Correlation, 9-1, 9-2

AUTOGS option, 2—22, A-8, B-3
Autogain, 2-22, A-8, B-3

Average correlation function, 9-1 to 9-5

Axis,

definition of time, 2-2, 3—-2
/BAD =[AUTO]switch, B4, B-7, B-9

BAD command, B—4, B-6, B-8
BAD utility, B4, B-6, B-8
/BADBLOCKS switch, A-3, A4
Bar-graph, 4-1, 5-1

Category,
data and, 4-2

definition of, 4-1, 4-2, 5-2

Centroid,
definition of, 3—4

CFT,
comparing, 6-3

DFT and, 6-3

FFT and, 6-3

definition of, 6—2
input, 6—4
output, 6-5

Change,

definition of local, 21, 2—-2
local, 2-2, 24, 3-2
trend, 2-3, 24, 3-2

Characteristics,
Input,

HISTI, 4-2 to 4-5
RHISTI, 5-2 to 5-5
/CO switch, B-9

Coefficients,
correlation, 9-1

Fourier, 8-1

Command files,
Indirect,

LSPBLD, A-6, B-11
LSPCND, A-6, B-11
LSPMAK, A-6, B-11
LSPVER, A-6, B-11

Index-1

Commands,
RSX-11M,

CORREL,
arguments, 9-5 to 9-6

ALL, B-3, B-5, B-7

example program, 9-9

ASN, B-11, B-14

file, 1-5, 9-7

BAD, B4, B-6, B-8
BOOT, B-7

FORTRAN call, 9-5

DMOU, B-5, B-9

output, 9-2, 9-12

DSC, B-5, B-7

terminal output, 9-2, 9-12

DSCSS8, B-7

input, 9-2

using, 9-2

EDI, B-15

Correlation coefficients, 9-1

FLX, B-9

Correlation function,

FMT, B-3, B4, B-6, B-8

average, 9-1 to 9-5

FOR, B-16

definition of, 9-1

F77, B-16

description, 9-1 to 9-12

INI, B—4, B-7, B-9
LBR, B-2

MOU, B-3, B-5, B-7
PIP, B-9

RUN, B-11, B-16

subroutine, 9-1 to 9-12

CORREL.MAC, 1-5
CORREL.OBJ, 1-5

Count,
HISTI overflow, 4-3, 4-16, 4-20

TKB, B-16, B-17

HISTI underflow, 4-3

UFD, B-9

NVELOP reject, 3-18

RT-11,
ASSIGN, A-6, A-9

RHISTI overflow, 5-6

RHISTI underflow, 5-6

COPY, A2

/CREATE switch, A-10

EDIT, A-10

Creating,

FORMAT, A-3, A4

customized object files, A—6, B-10

FORTRAN, A-11

programs,

INITIALIZE, A-3, A4
LIBRARY, A-12
LINK, A-11, A-12

RENAME, A-5

RUN, A-7, A-11
SQUEEZE, A-2, A-3, A-5

Comparing,
DFT and CFT, 64

under RSX-11M, B-15
under RT-11, A-10

Crest,
peak, 2-1, 24, 2-6
PEAK, 2-1, 24, 2-6

Cross correlation, 9-1 to 9-12
Customized object files,
creating, A-6, B-10

FFT and CFT input, 64
FFT and CFT output, 6-5

Compiler,
FORTRAN IV, A-1, A-2, A-11, B-2, B-16

FORTRAN 77, B-2, B-16

Data,
averaging, 2—2

definition of, 2—-1, 2-2
raw, 2—-1, 2-2

Continuous Fourier transform, 6-2

Data and category, 4-2

Continuum,

Data/integer relation, 5-1, 5-2

definition of, 4-2
COPY command, A-2
Copying the distribution volume
under RSX-11M, B-2
under RT-11, A-2
Correction,
baseline, 3—-22
Corrections,
making, A-5, B-5

Index-2

Default,
file types,

RSX-11M, B-1, B-16
RT-11, A-1, A-10

Definition of,

baseline, 2—6
category, 4-1, 4-2, 5-2

centroid, 3—4

CFT, 6-2

Definition of, (Cont.)
continuum, 4-2

correlation function, 9-1

data, 2-1, 2-2
DFT, 6-2
event, 4-2, 5-2

FFT, 6-1
FORTRAN 77, 1-2
Fourier transforms, 6-1
interval, 5-1, 5-2
local change, 2-2, 24, 3-2
noise, 2—-2, 3-2

overflow values, 4-2, 5-2

peak height, 2-1, 3-1, 3-2
reference points, 5-1, 5-2
time axis, 2-2, 3-2
trends, 2-3, 2—4, 3-2

underflow values, 4-2, 5-2
valley, 2-1, 2-6, 2-7, 3-2, 3—4
/DE
= NS
HIGH switch, B-4, B-6, B_8
Description,

correlation function, 9-1

Device,
storage, A-2, B-3

DOS-11-formatted, B-3, B-5
FILES-11-formatted, B-3, B—7

DFT,

definition of, 6-2
inverse, 6-3
Digital filter,
software, 2—-3

Discrete,
~

evaluation of CORREL, 9-3
Fourier transform, 6-2, 6-3

Distributed files,

object, 14, 1-5, A-5, B-10
source, 1-4, 1-5, A—6, B-10

Distribution volume,
contents of, 1-3 to 1-5

copying the,

under RSX-11M, B-2
under RT-11, A-2

DMOU command, B-5, B-9
/DO switch, B-9
DOS-11 formatted device, B-3, B-5

Double-precision integers, 2-24 4-8 5-17

DPHS$ option, 4-8, A-8, B-13
DPP$ option, 2-24, A-8, B-12, C-2, D-2

DPRS$ option, 5-17, A-8, B-13

DSC,

command, B-7

utility, B-5, B-7

DSCSS8 utility, B-5
DUP utility, A-2

EAE option, 2-22, 3-22, 4-8, 5-10, 6-186,
7-3, 8-2, 9-7, A-7, B-12
EIS option, 2-22, 3-22, 4-8, 5-10, 6186, 7-3,

8-2, 9-7, A-7, B-12, C-2, D-2
EDI command, B-15

EDIT command, A-10
Editor,

RSX-11M, B-15
RT-11, A-10
Envelope-processing,

algorithm, 3-1
subroutine, 3—-1 to 3-32
terms and conventions, 3—2

Estimated peak width, 2-1, 2-5, 3-3
Evaluation of CORREL,
discrete, 9-3
Event,

definition of, 4-2, 5-2
Events,

NVELOP, 3-14
Example program file names, 1-3 to 1-5

Example programs,

CORREL, 9-9 to 9-12
FFT, 6-19 to 6-22
HISTI, 4-12 to 4-28
NVELOP, 3-22 to 3-28
PEAK, 2-24 to 2-40

PHAMPL, 7-5 to 7-12
POWRSP, 8-5 to 8-12
RHISTI, 5-13 to 5-24
EXEMC.MLB, B-1
F4FFT.MAC, 14
F4FFT.OBJ, 14

F4P$ option, B-12, D-1, D-2
F77 command, B-16
F4PRAN.OBJ, 4-11, 5-11, 7-3, 8-3, B-2

Factor,

PEAK gate, 2-3
scaling, 6-8 to 6-12

Fast Fourier transform subroutine, 6-1
to 6-22

FFT,

definition of, 6-1
arguments, 6-13

example program, 6-19 to 6-22

file, 14, 6-16

FORTRAN call, 6-13
input, 6—4

maximum [/O array size, 6-16
output, 6-5, 622
properties, 6-14

terminal output, 6-22

using, 6—1 to 6-22

Index-3

File,

CORREL, 1-5, 9-7
FFT, 1-4, 6-16

HISTI, 1-4, 4-7

LSPBLD, A-6, B-11
LSPCND, A-6, B-11
LSPMAK, A-6, B-11

LSPVER, A-6, B-11
NVELOP, 14, 3-22

PEAK, 1-4, 2-22

PHAMPL, 1-5, 7-2

POWRSP, 1-5, 8-2
RHISTI, 1-4, 5-10
File names,

distribution kit, 1-3 to 1-5
example programs, 1-3 to 1-5

subroutine,

object, 1-3 to 1-5
source, 1-3 to 1-5

File protection, A-5

File types,
default,
RSX-11M, B-1, B-16

RT-11, A-1, A-10
Files,

indirect-command,
LSPBLD, A-6, B-11

LSPCND, A-6, B-11
LSPMAK, A-6, B-11

LSPVER, A-6, B-11

object, 1-3 to 1-5, A-5, B-10
source, 1-3 to 1-5, A-5, B-10

verifying, A-9 to A-10, B-14 to B-15

FILES-11-formatted device, B-3, B-7
Filter,

FORTRAN command, A-11, B-16
FORTRAN IV,
compiler, A-1, A-2, A-11, B-2, B-16

library, 4-5, 7-2, A-12
object time system, A-2, B-2
random-number generator, 4-11, 5-11,
7-3, 83

FORTRAN 77,
compiler, B-2, B-9
definition of, 1-2

library, 4-5, 7-2

object time system, A-2, B-2
random-number generator, 4-11, 5-11,
7-3, 8-3, B-2
Forward transform, 6-1

Fourier coefficients, 8-1
Fourier transform subroutine,

fast, 6-1 to 622
/FP switch, B-16, B-17

FPEAK. MAC, 1-4
FPEAK.OBJ, 1-4

FREQ$ option, 4-8, A-8, B-13
Frequency functions, 4-9, 6-2

Frequency histogram, 4-1 to 4—4
Function,
average correlation, 9-1 to 9-5

definition of correlation, 9-1

Functions,

frequency, 4-9, 6-2

Gate factor,
NVELOP, 3-3
PEAK, 2-3

Graphs,

bar, 4-1, 5-1

software digital, 2-3

FLOAT, 7-2

Flowchart,

Height,

definition of peak, 2-1, 3-1, 3-2

NEXTPT, 2-13, 3-11

peak, 2-1, 3-1, 3-2

RITOUT, 2-14, 3-12

peak baseline, 3-1, 3-2

NVELOP, 3-6 to 3—10
PEAK, 2-9 to 2-12
FLX,

HISTI,
arguments, 4-5 to 4—-6

example programs, 4-12 to 4-28

command, B-9

file, 1-4, 4-7

utility, B-2

FORTRAN call, 4-5 to 4-7

F.MAXN option, 6-16, A-8, B-13, C-2, D-3

input, 4-2

FMT utility, B-3, B—4, B-6, B-8

input characteristics, 4-2 to 4-5

FNVLOP.MAC, 14

output, 4-7

FNVLOP.OBJ, 14

overflow count, 4-3

FOR command, B-16

terminal output, 4-16, 4-20, 4-24, 4-28

/FOR switch, B-3, B-7

terms and conventions, 4-1

FORMAT,

underflow count, 4-3

command, A-3, A—4
utility, A-3, A4

Index—4

using, 4-7

HISTI.MAC, 1-4

HISTI.OBJ, 14

Histogram,
frequency, 4-1

Inverse DFT, 6-3

Inverse Fourier transform, 6-2, 6-3

interval, 4-1

/LB switch, B-17

zeroth, 5—6

LBR utility, B-2, B-17

Histogramming,
interval, 4-1 to 4-28

Histogramming subroutine,
interval, 4-1 to 4-28

Histograms, 4-1 to 4-28

Indicator,

scaling, 6-9
Indirect-command files,

LSPBLD, A-6, B-11
LSPCND, A-6, B-11
LSPMAK, A-6, B-11
LSPVER, A-6, B-11

INI command, B—4, B-7, B-9
INITIALIZE command, A-3, A—4
Input,

CORREL, 9-2
FFT, 64
HISTI, 4-2
NVELOP, 3-17

PEAK, 2-2
PHAMPL, 7-1

POWRSP, 8-1

RHISTI, 5-9
Input characteristics,

HISTI, 4-2 to 4-5
RHISTI, 5-2 to 5-5
Input data averaging, 2-2

Installation,
using RSX-11M, B-1
using RT-11, A-1

Integer and interval, 4-2, 5-2

Integers,

double-precision, 2—24, 4-8, 5-17
single-precision, 2-24, 4-8, 5-17
signed, 44, 5-3
unsigned, 44, 5-3

Interactive build procedure, 1-3, 1-5, A—6 to
A-9, B-10 to B-14, C-1, D-1
Internal scaling procedure, 6-9
Interval,

definition of, 5-1, 5-2
integer and, 4-2, 5-2

Interval histogramming, 4-1, 5-1

Interval histogramming subroutine, 4-1
to 4-28

Interval histogramming with

reference points

subroutine, 5-1 to 5-24

Laboratory Subroutines package,
definition of, 1-1 to 1-5

Leakage, 6-8
/LI switch, B—4, B-6, B-8

LIBR utility, A-12
Libraries,

FORTRAN IV, 4-5, 7-2, A-12
FORTRAN 77, 4-5, 7-2

System,
MACRO, A-1, B-1

object, A-1, A-11, A-12, B-1, B-17
using, A-12, B-17

LIBRARY command, A-12

LINK command, A-11, A-12

Linker, A-2, A-11
Local change,

definition of, 2—-2
Local maximum, 24
Local minimum, 2—4
LSPBLD, A-6, B-11

LSPCND, A-6, B-11
LSPMAK, A-6, B-11

LSPVER, A-6, B-11
MACRO,

assembler,

RSX-11M, B-1
RT-11, A-1
Making corrections, A-5, B-5
Maximum,

local, 2—4
Minimum,

local, 2—4
MOU command, B-3, B-5, B-7

NEXTPT,

flowchart, 2-13, 3-11
subroutine, 2-13, 3-11
NOFLTS$ option, 2-24, A-7, B-13, C-2, D-2
Noise,

definition of, 2-2, 3—-2
/INOPROTECTION switch, A-5

Numbers,
see Integers

NVELOP,
arguments, 3-16 to 3-20

baseline value, 3-3, 3-17, 3-18
events, 3—-14

example programs, 3—-25 to 3—32

Index-5

NVELOP, (Cont.)
file, 1-4, 3-22

flowcharts, 3-6 to 3—10
FORTRAN call, 3-16
gate factor, 3-3
input, 3-17

options, 3-22
output, 3-19, 3-20

reject count, 3—18

symbol definition, 3-5
terms and conventions, 3-2
terminal output, 3-28, 3-30, 3—32

threshold value, 3-22, 3-23, 3-29, 3-31
using, 3-20 to 3-22

PEAK,
arguments, 2-17 to 2-20

autogain, 2-22, A-8, B-3

baseline, 2—6
crest, 2-1, 2—4, 2-6

digital filter, 2-3
example programs, 2-24 to 2—40
flowcharts, 2-9 to 2—12

file, 14, 2-22
FORTRAN call, 2-17
gate factor, 2-3
input, 2-2

local,
change, 2-2

zero values, 3-18

maximum, 2—4

NVELOP.MAC, 14

NVELOP.OBJ, 1-4

Object files,

list of, 1-3 to 1-5
creating customized, A—-6, B-10

distributed, 1-4, 1-5, A-5, B-10
Operating system,
RSX-11M, 1-1 to 1-5, B-1, D-1
RT-11, 1-1 to 1-5, A-1, C-1

Options,
AUTOGS, A-22, A-8, B-3

minimum, 2—4
output, 2-21

switch settings, 2—7
symbols, 2—-8, 2-9
terminal output, 2-28, 2-32, 2-36, 2-40
terms and conventions, 2—-1, 2-2

using, 2-20
peak,
area, 2-1, 24, 34

area calculation, 3—4

baseline, 2-6
centroid, 3—4

DPH$, 4-8, A-8, B-13
DPP$, 2-24, A-8, B-13, C-2, D-2

centroid calculation, 3—4

DPRS$, 5-17, A-8, B-13

height,

EAE, 2-22, 3-22, 4-8, 5-10, 6-16, 7-3,
8-2, 9-7, A-7, B-12

EIS, 2-22, 3-22, 4-8, 5-10, 6-16, 7-3, 8-2,
9-7, A-7, B-12, C-2, D-2

F.MAXN, 6-16, A-8, B-13, C-2, D-3

F4P$, 7-3, B-12, D-1, D-2

FREQS$, 4-8, A-8, B-13
NOFLTS, 2-24, A-7, B-13, C-2, D-2
using, 1-1 to 1-3, 2-22, 3-22, 4-7, 5-10,
6-16, 7-2, 8-2, 9-7, A-5 to A-9, B-10

to B-14, C-1, D-1

Output,
CORREL, 9-2, 9-12
FFT, 6-5, 6-22
HISTI, 4-16, 4-20, 4-24, 4-28
NVELOP, 3-28, 3-30, 3-32

PEAK, 2-28, 2-32, 2-36, 2—40
PHAMPL, 7-12
POWRSP, 8-8, 8-12
RHISTI, 5-16, 5-20, 5-24
/OUTPUT switch, A-3, A-5

Overflow count,

HISTI, 4-3, 4-16, 4-20

RHISTI, 5-6

Index-6

crest, 2-1, 2-4, 2-6

definition of, 2—-1, 3-1, 3-2
width, 2-1, 2-5, 3-3

Peak-processing,
algorithm, 2-1
subroutine, 1-2, 2—-1 to 2—40

PHAMPL,

algorithm, 7-1
arguments, 7-2

example programs, 7-5 to 7-12

file, 1-5, 7-2

FORTRAN call, 7-2
input, 7-1
output, 7-1

terminal output, 7-12

using, 7-1

PHAMPL.MAC, 1-5
PHAMPL.OBJ, 1-5
Phase angle and amplitude spectra

subroutine, 7-1 to 7-12
Phase angles, 7-1
PIP,
command, B-9

utility, A-2, B-9

Points,
reference, 5-1, 5-2
Power spectrum subroutine, 8~1 to 8-12

POWRSP,

algorithm, 8-1
arguments, 82

example programs, 85 to 8-12

file, 1-5, 8-2

FORTRAN call, 8-1
input, 8-1
output, 8-1

terminal output, 8-8, 8-12

using, 8-1

POWRSP.MAC, 1-5
POWRSP.OBJ, 1-5
Procedure,
interactive build, 1-3, 1-5, A—6 to A-9,

B-10 to B-14, C-1, D-1

internal scaling, 6-9
relational scaling, 6-9
Properties,

FFT, 6-14
Protection of files, A—5
/PROTECTION switch, A-5

Random-number generator, 4-11, 5-11, 7-3,
8-3, B-2

Raw data, 2-1, 2-2
Reference points, 5-1, 5-2
Reject count,

NVELOP, 3-18
Relation,

data/integer, 5-1, 5-2
integer/interval, 4-2, 5-2

of FFT to CORREL, 9-2
Relational scaling procedure, 6-9

/REMOVE switch, A-12

RITOUT,
flowchart, 2—14, 3—-12
subroutine, 2-14, 3-12
/RP switch, B-2
/RS switch, B-9

RSX-11M,

BAD utility, B4, B-6, B-8
creating programs under, B-15

default file types, B-1, B-16
DSC utility, B-5, B-7
DSCS8 utility, B-5

editor, B-15
FLX utility, B-2

FMT utility, B-3, B-4, B—6, B—8
FORTRAN IV compiler, B-2, B-16

FORTRAN 77 compiler, B-2, B-16

LBR utility, B-2, B-17
MACRO assembler, B—1

operating system, 1-1 to 1-5, B-1, D-1

PIP utility, B-9

task-builder, B-1, B-2, B-16, B-17
RSXMAC.SML, B-1

RT-11,
creating programs under, A—10

default file types, A—1, A—10

DUP utility, A-2
editor, A-10

FORMAT utility, A-3, A—4
FORTRAN IV compiler, A-1, A-2 A-11

LIBR utility, A-12

linker, A-2, A-11
MACRO assembler, A-1
operating system, 1-1 to 1-5, A-1, C-1

PIP utility, A-2

RUN command, A-7, A-11, B-11, B-16,

C-2, D-2

RENAME command, A-5

RHISTI,
arguments, 5-7 to 5-8

characteristics, 5-2 to 5-5
example programs, 5-13 to 5-24

file, 14, 5-10

FORTRAN call, 5-7
input, 5-9
output, 5-11

overflow count, 5-6
terminal output, 5-16, 5-20, 5-24
terms and conventions, 5-1 to 5-2

underflow count, 5-6

using, 5-5, 5-9

RHISTI.MAC, 1-5
RHISTI.OBJ, 1-5

Scaling,
factor, 6-8 to 6-12
FFT results, 6-8 to 6—12
indicator, 6-9

Selecting the form of subroutine to use, A-5,
B-10

Signed integers, 44, 5-3

/SINGLEDENSITY switch, A-3, A—4

Single-precision integers, 4-8, 517
Software digital filter, 2-3

Source files, 1-3 to 1-5, A-5 B-10

Spectra,

amplitude, 7-1

Spectra subroutine,
Phase angle and amplitude, 7-1 to 7—12

Index-7

Spectrum subroutine,
power, 81 to 8-12

SQRT, 7-2
SQUEEZE command, A-2, A-3, A-5
Storage devices, A-2, B-3, B-5, B-7
Subroutine,
correlation function, 1-2, 9—1 to 9-12

envelope-processing, 1-2, 3-1 to 3-32
fast Fourier transform, 1-2, 6-1 to 6-22

interval histogramming, 1-2, 4-1 to 4-28

Task-image file, B-1, B-2
Terminal output,

CORREL, 9-12
FFT, 6-22
HISTI, 4-16, 4-20, 4-24, 4-28

NVELOP, 3-28, 3-30, 3-32
PEAK, 2-28, 2-32, 2-36, 2—40

PHAMPL, 7-12
POWRSP, 8-8, 8-12

RHISTI, 5-16, 5-20, 5-24

interval histogramming with reference

Testing software

points, 1-2, 5-1 to 5-24
NEXTPT, 2-13, 3-11

Threshold value, 3-22, 3-23, 3-29, 3-31

peak processing, 1-2, 2-1 to 2-40
phase angle and amplitude spectra, 1-2,
7-1 to 7-12
power spectrum, 1-2, 8-1 to 8-12

RITOUT, 2-14, 3-12
selecting the form of, A-5, B-10

Subroutine example program names, 1-4
to 1-5

Subroutine file names, 1-4 to 1-5

Switches,
/BAD =[AUTO], B4, B-7, B-9
/BADBLOCKS, A-3, A4
/CO, B-9

/CREATE, A-10
/DENS
= HIGH, B4, B-6, B-8
/DO, B-9

/FOR, B-3, B-7

/FP, B-16, B-17
/LB, B-17
/LI, B—4, B-6, B-8

see verifying

Time axis,

definition of, 2-2, 3-2
TKB command, B-16, B-17
Transform,
approximate Fourier, 6-2, 6-13

forward, 6-1, 6-2
inverse, 62

Transform subroutine,

fast Fourier, 6-1 to 6-22
Transforms,
continuous Fourier, 6-2

discrete Fourier, 6-2, 6-3
inverse Fourier, 6-2
Trend,

change, 2-3, 2—4, 3-2

definition of, 2-3, 2—4, 3-2
True peak width, 2-5
UFD command, B-9
Underflow count,

/NOPROTECTION, A-5

HISTI, 4-3

/OUTPUT, A-3, A-5

RHISTI, 5-6

/PROTECTION, A-5

/REMOVE, A-12

Underflow values, 4-2, 5-2
Unsigned integers, 44, 5-3

/RP, B-2

Using,

/RS, B-9

CORREL, 9-2

/SINGLEDENSITY, A-3, A4

customized object files, A-6, B-10

/WAIT, A4, A-5

distributed files, A-5, B-10

SYSLIB.OBJ, A-1, A-11

FFT, 6-1 to 6-22

SYSLIB.OLB, B-2

HISTI, 4-7

SYSMAC.SML, A-1

Libraries, A-12, B-17

System libraries,
MACRO, A-1, B-1

options, 1-1 to 1-3, 2-22, 3-22, 4-7, 5-10,

NVELOP, 3-20

object, A-1, A-11, A-12, B-1, B-17

6-16, 7-2, 8-2, 9-7, A-5 to A-9, B-10

using, A-12, B-17

to B-14, C-1, D-1

PEAK, 2-20

Task, B-16

PHAMPL, 7-1

Task-builder,

POWRSP, 8-1

RSX-11M, B-1, B-2, B-16, B-17

Index-8

RHISTI, 5-5, 5-9

Utilities,
RSX-11M,
BAD, B4, B-6, B-8
DSC, B-5, B-7
DSCSS8, B-5
FLX, B-2

FMT, B-3, B-4, B-6, B-8
LBR, B-2, B-17
PIP, B-9

RT-11,
gUPM‘;&z A
L%;, T A

Value,
NVELOP baseline, 3-3, 3-17, 3—-18
threshold, 3-22, 3-26, 3-27

Values,

NVELOP zero, 3-18
Verifying,

Laboratory Subroutines software, A-9 to
A-10, B-14 to B-15

Width,
peak, 2-1, 2.5 3_3
/WAIT switch, A4, A_5

PIP, A-2

Valley,
definition of, 2-1, 2-6, 2-7, 3-2, 3—4

Zero values,

NVELOP, 3-18
Zeroth histogram, 5-6

Index-9

Laboratory Subroutines
Programmer’s Reference Manual
AA-C984C-TC

READER’S COMMENTS

NOTE:

This form is for document comments only. DIGITAL will use comments sub-

mitted on this form at the company’s discretion. If you require a written reply

and are eligible to receive one under Software Performance Report (SPR) service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well-organized? Please
make

suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of reader that you most nearly represent.

[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[J Student programmer
[J Other (please specify)
Name

Date

Organization

Telephone

Street
City

State

Zip Code
or Country

No Postage
Necessary

if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID

BY ADDRESSEE

SOFTWARE PUBLICATIONS
200 FOREST STREET MR1-2/E37

Cut Along Dotted Line

MARLBOROUGH, MASSACHUSETTS 01752

Printed in U.S.A.