UCRL-ID-103432 (Revised)
The APT Library:
Applied Particle Tracking,
Monte Carlo Sampling, Geometric Analysis
and Other Useful Subroutines
Arthur L. Edwards
(email: xenopsbird@comcast.net)
February 2, 2007
AVAILABILITY
The web site http://nuclear.llnl.gov/CNP/apt/ contains documention,
source files, and F77-compiled binary modules for the APT Subroutine Library,
as well as the GEOM code, which can do many geometric and Monte Carlo tasks
using data provided by the user, and uses many of the APT subroutines.
CONTENTS
ABSTRACT ............................................................
INTRODUCTION ........................................................
APT SUBROUTINE DESCRIPTIONS AND USE..................................
APT SUBROUTINE DESIGN ...............................................
FUZZY GEOMETRY TECHNIQUES ...........................................
MEMORY REQUIREMENTS .................................................
APPENDICES ..........................................................
APT SUBROUTINE ONE-LINE SUMMARIES...............................
APT KEY WORDS........................................
APT SUBROUTINE LINKS ...........................................
APT HISTORY.....................................................
DISTRIBUTION LIST ..............................................
ABSTRACT
The All-Particle-Tracking (APT) subroutine library contains over 300
subroutines, primarily for Monte Carlo and geometric applications.
It is designed especially to support 2-D and 3-D codes that generate and track
particles or beams of matter or energy, and contains subroutines useful in
many other kinds of codes. This users' document and other documentation,
the ANSI Standard FORTRAN source files, and the compiled binary modules
are available on the Open Network GPS Cluster.
INTRODUCTION
Many large-scale computer programs require modules for generating and
tracking particles or beams of matter or energy in 1-D, 2-D and 3-D geometries,
in various coordinate systems, and in various types of spatial meshes.
Some of these modules require Monte Carlo sampling of random variables from a
variety of probability distributions. These codes may also have to solve
difficult geometric problems in generating and rezoning the mesh. As a result,
a large number of subroutines, functions, and algorithms have been developed
over the years for Monte Carlo sampling and geometric applications, greatly
varying in style, structure, readability, accessibility, modularity, and
efficiency. A single large code may have the same function duplicated many
times, in many forms, in different code modules.
Thus, there is a clear need for a standard library of Monte Carlo sampling
and geometric subroutines, for use in developing new codes, especially those for
3-D geometries, and for replacing coding in existing codes as they are upgraded.
The goals in designing such libraries include improving speed, efficiency,
accuracy, reliability, accessibility, readability, generality, flexibility,
ease of maintenance, and ease of use.
The APT Library is designed to meet this immediate need, and to provide a
basis for expansion to meet future needs. The APT Library includes Monte Carlo
sampling and geometric subroutines usable by many Monte Carlo particle-tracking
codes, in addition to a comprehensive set of basic subroutines for geometric
applications in 1-D, 2-D and 3-D geometries, in Cartesian, cylindrical and
spherical coordinate systems. The development and inclusion in the library of
additional higher-level subroutines is simplified by the hierarchical nature of
the set of subroutines, and is being done as needed.
APT SUBROUTINE DESCRIPTIONS AND USE
The "Availability" section at the beginning of this document tells how to
Get the users' document apt_doc, the ANSI Standard FORTRAN source files,
And the compiled binary files of the subroutines in the APT Library.
The appendix "APT SUBROUTINE ONE-LINE SUMMARIES" contains a one-line
summary of each APT subroutine, arranged alphabetically in several major groups,and may be searched for key words associated with desired tasks.
The appendix "APT SUBROUTINE KEY WORD INDEX" is arranged alphabetically
by key words, and may be used to find the names of subroutines needed for any
particular task, if such a subroutine is in the APT Library.
The appendix "APT SUBROUTINE LINKS" lists any other APT subroutines
required by each APT subroutine that calls other APT subroutines.
The source file for each APT subroutine contains an initial comment block
containing the calling statement and argument list, the dates of origination and
last update, the location of the needed libraries and source file, the purpose
and general description of the subroutine, lists of input and output arguments,
a list of calls to other APT subroutines, a history of significant changes that
might affect long-time users, and detailed definitions of all arguments.
In most cases, this information should be sufficient to allow proper use of the
subroutine. If not, the source file contains additional information, including
definitions of all internal variables, comments describing each step of the
procedure, and the coding itself. Each source file is intended to be completely
self-documented.
For efficiency, 1-D and 2-D analogues of many 3-D geometric algorithms have
been placed in separate subroutines, to eliminate unnecessary subroutine
arguments and complexity. All strictly 2-D subroutines, in which all points an
vectors are confined to a major plane, have names ending in the letter "c".
Subroutines are provided for rotating any non-major plane into a major plane.
The rotation operator may be saved to do the inverse rotation later, after
major-plane calculations are done.
Many of the APT subroutines are designed to process data arrays.
Some algorithms are offered in two or more subroutines, depending on whether
certain arguments are scalar values or array values, or on how certain
geometric objects are defined. For example, a line may be represented by
two points, or a point and a directional vector, or a plane may be
represented by three points or a point and a normal vector. Subroutines are
provided to interconvert between these representations. Some subroutines are
available in both scalar and array versions. The array verstions are easily
converted to scalar versions, by a few simple changes.
All communications between APT subroutines and each other, and with the
calling program, are through argument lists, averaging 8 input arguments and
5 output arguments. There are no shared cliches or common blocks. Input and
output arrays in each argument list are usually members of a single table,
with the same index and same array size. It is up to the user to allocate
memory for these arrays, and put the input data into the required form.
Some local variables in APT subroutines are declared in local labelled common
blocks, named by prefixing the subroutine name with the letter "l", for integer
and floating-point data, and "a" or "c" for character data.
When local temporary arrays are needed, array processing is done in
blocks of 64 or less, so no local array is sized any greater than 64.
Most subroutines indicate an input data error, failure to find a requested
result, or the occurence of a special or limiting case, by returning a scalar
and/or array integer flag, or a physically impossible value of an output
argument. Integer flags may have several possible values. The most often used
flag, "nerr", is usually returned with a value of 1 when a specified array size
is non-positive. The calling program should test for any of these cases that
can possible occur, and take appropriate action before errors propagate or a
crash occurs. Great care is taken to identify all special and extreme cases,
and to indicate their occurence to the calling program by use of the special
result flags.
SUBROUTINE DESIGN
The subroutines in the APT Library were designed with the
following goals: speed, efficiency, accuracy, reliability, accessiblity,
readability, generality, flexibility, ease of maintenance, and ease of
use.
Calculational speed is obtained primarily by allowing maximum
optimization of do-loops, by eliminating unnecessary calculations by
using separate subroutines for 2-D analogues of 3-D procedures, and by
using input options to eliminate do-loops not needed for a particular
application.
Efficiency is obtained by using a hierarchy of subroutines,
beginning with a set of basic operations, followed by increasingly
higher-level subroutines, and making maximum use of calls to lower-level
subroutines to avoid repetition of coding. This also helps to insure
uniformity of method, increases reliability, simplifies maintenance,
and simplifies the addition of higher-level user applications to the
library.
Accuracy is obtained by thorough testing to eliminate coding errors, and
by the careful use of the techniques of "fuzzy geometry", to eliminate or
control the effects of numerical round-off errors. See the section of this
document titled "APT FUZZY GEOMETRY TECHNIQUES".
Reliability is obtained by thorough testing, including all possible
extreme, special, and degenerate cases, and all possible types of input errors,
to ensure that the expected results are obtained in all cases, and that
sufficient information is returned to the calling program to allow appropriate
action to be taken in all cases, whenever possible. The test program for a
particular subroutine has beeb run whenever that subroutine, or any subroutine
it is dependent on, has been changed.
Accessability is obtained by making all FORTRAN source files available
individually, and in TAR file aptflibe.
Readability is obtained by making each subroutine adhere to the same strict
coding standards. The requirements include the inclusion of an initial block of
comments containing certain required information and liberal use of blank lines
and comments. The coding standard also specifies the format of all FORTRAN
statements, ensure readability and uniformity in all subroutines. In general,
the names of dummy arguments and local variables are chosen by a consistent set
of rules in most subroutines, making it easier to remember their meanings.
Generality and flexibility are obtained by including all of the basic
geometric and vector operations in separate subroutines, allowing a hierarchy of
subroutines to be developed, ranging from low-level to high-level applications;
by including separate subroutines for 1-D, 2-D and 3-D analogues of the same
process, and for the same process carried out in different coordinate systems;
and by including subroutines for conversion between different coordinate
systems, and between different descriptions of the same geometric objects.
Ease of maintenance is obtained by a variety of methods, including use of
coding standards, use of nomenclature standards, use of a hierarchical
subroutine structure, and use of a number of computer tools for updating,
compiling, loading, saving, and documenting, all of which are in place, and
procedures for their use documented.
Ease of use is obtained by providing complete documentation, both here and
in each source file, by allowing communication with the calling program only
through the argument list, which eliminates any dependency on macros, cliches,
or shared common blocks; by the use of a very basic set of FORTRAN statement
types, minimizing or eliminating the need for changes to run on different
computers; and by the general, flexible, and modular structure of the
subroutines.
The average APT subroutine has 220 lines, of which 45 are blank,
75 are the initial comment block, 16 are other comments, 8 are dimension
declarations for arguments, 13 are common block declarations for local
variables, and the remaining 63 are other coding. Many of the latter
have appended comments. (Note: appended comments are easily moved to
a separate line by most standard text editors.)
APT FUZZY GEOMETRY TECHNIQUES
A unique feature of this library of subroutines is the inclusion
and careful use of a number of techniques to control or eliminate the
effects of round-off error due to the finite number of bits of precision
available on computers.
These "fuzzy geometry" techniqes make it possible to get correct
and unambiguous answers to important geometric questions such as whether
geometric objects are coincident, colinear, coplanar, parallel,
perpendicular or tangent, within the uncertainty due to round-off error,
and to avoid producing meaningless results that may later require special
handling and testing to prevent major errors or program crashes.
Many subroutines have an input argument specifying a relative
precision "tol", and allow certain intermediate and final results to
be truncated to zero, if their absolute values are less than the
estimated error in their calculation, based on "tol" and the actual
numerical procedures used.
Subroutines aptfdad, aptfdav, aptvlic, aptvlim, aptvtoc and aptvtol
provide options to truncate or place limits on scalar values,
spatial point coordinates, or vector components. Subroutine aptrnds
may be used to round off any floating point number to a specified
absolute or relative precision. These options may be tailored to the
precision of the computer in use, and to the requirements of the
particular application.
On machines using 64-bit floating point values, the value of
"tol" should be approximately equal to 1.e-12**(1/n), when the tested
value x is to be used in the form x**n. A larger value should be used
(e.g., 1.e-11), when the input arguments are likely to have been affected
previously by round-off error.
When an expression contains a denominator which can legitimately have
a value of zero, a fuzz factor "fuz", equal to 1.e-99, is usually added to
the denominator, to avoid division by zero. The value 1.e-99 might have
to be changed on some computers. Whenever this technique results in an
incorrect value of an output argument, either a separate warning flag is
returned, or the description or the output argument in the subroutine
comment block contains a warning, allowing the calling program to test for
such a result.
MEMORY REQUIREMENTS
The AR library of binary modules, libapt.a, currently needs about
1.4 megabytes of memory, or about 4500 bytes for each subroutine.
This includes about 1660 bytes for the local common block. Since a call
to one APT subroutine may initiate a chain of calls to other lower-level
APT subroutines, as well as subroutines in other system libraries, the
total memory requirement may be larger. Currently, the longest call chain
is five, and the largest number of APT subroutines required by a single
call is 31. See the appendix "SUBROUTINE LINKS ".
The FORTRAN source files in aptflibe require about 3 Mbytes of
memory, or about 10 Kbytes for each subroutine.
UCRL-WEB-209832