APT SUBROUTINE ONE-LINE SUMMARIES Author: Arthur L. Edwards (email: xenopsbird@comcast.net). Updated: 2006 July 7 13:00. The APT Library currently contains over 300 subroutines, ranging from basic low-level vector procedures to the higher-level Monte Carlo sampling and geometric methods needed for Monte Carlo tracking of particles or beams of matter or energy in 1-D, 2-D or 3-D geometries. To find a subroutine for a particular task, look up any of the key words describing the task in the appendix "APT SUBROUTINE KEY WORDS". To find any other subroutines required for use of a particular subroutine, see the appendix "APT SUBROUTINE LINKS". One-line summaries are given below, alphabetically by subroutine name, grouped into the six general categories below: Physical and chemical constants Geometry Monte Carlo sampling (geometric) Monte Carlo sampling (numerical) Mathematics and statistics Data manipulation Bit and character manipulation (machine independent) Precision and round-off error control Error procedures PHYSICAL AND CHEMICAL CONSTANTS A modern (1999) self-consistent set of values of the fundamental constants of physics and chemistry is provided in subroutines aptconl (180 values in cm-g-sh-jerk-kev units), and aptconm (217 values in SI units). aptconl Find 1999 values of specified fundamental constants in cm-g-sh-keV. aptconm Find 1999 values of specified fundamental constants in SI units. GEOMETRY The geometry group consists of the Monte Carlo (geometric) group, and the subroutines summarized below, including coordinate transformations; translation, rotation, reflection and inversion operations; vector operations; consideration of geometric objects, including points, lines, curves, planes and quadric surfaces, and their interrelationships; and much more. Many procedures are available in 1-D, 2-D and 3-D forms, in rectangular, cylindrical and spherical coordinate systems, and in forms to process scalar data and array data. aptacct Find points on a trajectory with time-dependent acceleration. aptafac Find all unexponentiated factors of an integer. aptaxis Find the principal axes, center and type of a quadric surface. aptbanc Find the bisectors of angles in a major plane. aptbang Find the bisectors of angles in 3-D space. aptbrkn Find if point is in a brick, local coordinates, distances. aptbrkp Find point with given local coordinates in a brick. aptbrkv Find coordinates, edge lengths, areas, volume of a brick. aptcang Find an angle in degrees, grads, radians, arc deg, min, sec. aptcinc Find the intersection between 2 circles in a major plane. aptcirc Find the circle through three points in a major plane. aptcirk Find the radii and centers of 2 circles tangent to 3 tangent circles. aptcirl Find the center of a circle tangent to two tangent circles. aptcirp Find the circle through three points in 3-D space. aptcirt Find the radii of two circles tangent to three tangent circles. aptclis Find equation of a cylinder with a given axis and radius. aptcnis Find equation of a cone on a major axis, given two points. aptcniz Find equation of a cone on the z axis, given two points. aptcois Find equation of a cone on a major axis, given vertex and angle. aptcris Find extreme curvatures at a point on a quadric surfaces. aptcsys Transform coordinates - Cartesian, cylindrical, spherical. aptcsyv Transform coordinates and vectors - Cartesian, cyl, spherical. aptcube Generate a cube centered on the origin. aptcycy Find axial and surface distances between two circular cylinders. aptcyis Find equation of a cylinder on a major axis, given the radius. aptdirt Find all unique directions between groups of points. aptdist Find distance and direction between two points, any coordinates. aptdode Generate a regular dodecahedron centered on the origin. aptelis Find equation of ellipsoid on major axis, given center, two pts. aptesis Find equation of ellipsoid at origin, given three semiaxes. aptetrl Find local coordinates of points in tetrahedrons. aptetrn Find if point is in a tetrahedron, distances, local coordinates. aptetru Find unit vector at specified angles from two other vectors. aptetrv Find line at specified angles from two other lines. aptetrw Find point with given vertex weights in tetrahedron, quadrangle. aptfdqc Find local coordinates of points in quadrangles. apticos Generate a regular icosahedron centered on the origin. aptil08 Tile a unit sphere with triangles: 8, 32, 128, 512, ... aptil12 Tile a unit sphere with triangles: 60, 240, 960, ... aptil20 Tile a unit sphere with triangles: 20, 80, 320, ... aptintq Find proximal or intersection points of two quadric surfaces. aptinvc Invert coordinates in a major plane. aptinvp Invert coordinates in xyz space. aptlnic Find intersection of a line with a circle in a major plane. aptlnlc Find intersection of 2 lines in a major plane. aptlnln Find the minimum distance between 2 lines in xyz space. aptlnpl Find intersection of a line with a plane. aptlntr Find intersection of a line with a plane through three points. aptmopv Operate on vectors with a 3 by 3 matrix operator. aptmove Move a point a specified distance and direction, any coord sys. aptmovs Move a point a specified distance and direction, spherical. aptmvcy Move a point a specified distance and direction, cylindrical. aptocta Generate a regular octahedron centered on the origin. aptparb Find points on a parabolic (linearly accelerated) trajectory. aptparh Find initial velocity for a parabolic trajectory to hit a point. aptparl Find proximal points of a parabolic trajectory with a line. aptparp Find intersections of a parabolic trajectory with a plane. aptparq Find intersections of parabolic trajectory with quadric surface. aptpars Find proximal points of a parabolic trajectory with a point. aptpart Find parabolic trajectory for one to three points and times. aptparx Find quadric surface equation extrema on parabolic trajectory. aptpblc Find the line perpendicularly bisecting a line in a plane. aptpbln Find the plane perpendicularly bisecting a line in xyz space. aptpent Subdivide a regular pentagon into 5 triangles, on a sphere. aptperc Project points onto a perspective view line in a major plane. aptpers Project points onto a perspective view plane in xyz space. aptpfac Find all prime factors of an integer, and Euler's totient function. aptpfit Find the equation of a plane through three points. aptplcy Find intersection/distance of a plane and a circular cylinder. aptplis Find intersection of a major plane with a quadric surface. aptplpl Find the line of intersection of two planes, or their distance. aptplqu Find intersection/distance of a plane and a quadric surface. aptplsp Find the circle of intersection of a plane and a sphere. aptpolc Generate any regular polygon in a major plane. aptpoly Generate any regular polygon in xyz space. aptprcy Project a set of points onto a cylinder in xyz space (options). aptprim Find prime numbers and irreducible proportion geometric factors. aptproc Project a set of points radially onto a circle in a major plane. aptprop Project a set of points normally onto a plane in xyz space. aptpros Project a set of points radially onto a sphere in xyz space. aptprsp Project a set of points onto a sphere in xyz space (options). aptptlc Find the distance from a point to a line in a major plane. aptptln Find the distance from a point to a line in xyz space. aptptpl Find the distance from a point to a plane, and the near point. aptqdic Find the distances from a point to the edges of a quadrangle. aptqexc Find the extrema of a quadric curve in a major plane. aptqexv Find any extrema of a quadric surface in a specified direction. aptqext Find any x, y, z extrema, type and center of a quadric surface. aptqfdc Find the local coordinates of points in a quadrangle. aptqfit Find the quadric surface through nine points. aptqhyp Find the quadric surface through edges and center of a quadrangle. aptqinc Find if a point is in a quadrangle in a major plane, distances. aptqnor Find a quadric surface normal vector and tangent plane at a point. aptqper Find a quadric surface two quadric surface families are orthogonal on. aptqprr Find a proximal point on a quadric surface using steepest ascent. aptqprt Find a proximal point on a quadric surface using random trials. aptquad Find the distance from a point to a nonplanar quadrangle. aptqupr Project a quadric surface in a specified direction. aptqupt Find extreme and axis intercept points on a quadric surface. aptquwt Find the point with given local coordinates in a quadrangle. aptqvac Find the shapes and vertex areas of a set of planar quadrangles. aptqval Find the value of a quadric surface function at a specified point. aptrabc Find lines that cut a triangle into two equal areas and perimeters. aptradv Project a set of points onto a view factor plane in xyz space. aptrcab Find result of aptrcut for a single vertex of a triangle. aptrcut Find lines that cut a triangle into two equal areas and perimeters. aptrefc Reflect a direction vector from a line, all in a major plane. aptrefl Reflect a direction vector from a plane perp to a major plane. aptrefq Analyze a reflection operator, to find the plane. aptrefs Reflect points or direction vectors from a specified plane. aptrext Given small triangle from aptrcut, find all original triangles. aptrich Find if three edge lengths can form a real triangle. aptripc Find the local coordinates of a point in a major plane triangle. aptripl Find the local coordinates of a point in an xyz space triangle. aptripp Find equilateral projection of triangle with specified vertices. aptripq Find a triple point of three quadric surfaces. aptripr Find equilateral projection of triangle with specified edges. aptrips Find the scalar triple product of three vectors. aptript Find the distance from a triangle to a point in xyz space. aptripv Find the vector triple product of three vectors. aptrkcl Find the intersection of a linear track with a 1-D cylinder. aptrkcy Find the intersection of a linear track with a z-r cone. aptrkis Find the intersection of a linear track with a quadric surface. aptrklc Find the intersection of a linear track with a line in a plane. aptrkpl Find the intersection of a linear track with a plane. aptrkrl Find the intersection of a linear track with a 1-D sphere. aptrksl Find the intersection of a linear track with a major plane. aptrloc Find point with given vertex weights in a major plane triangle. aptrlop Find point with given vertex weights in an xyz space triangle. aptrois Find new equation coefficients for transformed quadric surface. aptrota Find the rotation operator for a specified axis, angle. aptrotc Rotate vectors in a major plane by a specified angle. aptrotp Find the rotation operator to make a plane parallel to another. aptrotq Analyze a rotation operator to find the axis, angle. aptrots Find the operator for 3 rotations around the major axes. aptrott Find the operator to rotate a plane and vector onto another. aptrotv Find the operator to rotate a vector onto another vector. aptsclc Linearly scale a set of points or vectors in a major plane. aptscll Linearly scale a set of points or vectors in xyz space. aptsclr Cylindrically scale a set of points or vectors in xyz space. aptsclu Uniformly scale a set of points or vectors in xyz space. aptspcy Find distance between a sphere and a circular cylinder. aptspha Find the sphere centered on an axis, and through two points. aptsphk Find the radii and centers of 2 spheres tangent to 4 tangent spheres. aptsphl Find the center of a sphere tangent to three tangent spheres. aptsphp Find the sphere with its surface through four specified points. aptspht Find the radii of two spheres tangent to four tangent spheres. aptspsp Find the circle of intersection between two spheres. aptsver Find the Steiner vertex of a triangle. apttetd Find the volume and centroid of a tetrahedron in xyz space. apttetr Generate a regular tetrahedron centered on the origin. apttinc Find if a point is in a triangle in a major plane, distances. apttrac Translate the origin to a specified point in a major plane. apttran Translate the origin to a specified point in xyz space. apttric Find the edge lengths, area, centroid of a major plane triangle. apttrid Find the edge lengths, area, centroid of an xyz space triangle. apttrig Find general geometric data for an xyz space triangle. apttrip Find the distance from a point to a triangular surface, more. apttris Find new equation coefficients for translated quadric surface. aptvadc Find a vector sum with specified coefficients, in a major plane. aptvadd Find a vector sum with specified coefficients. aptvanc Find the angle between two vectors in a major plane. aptvang Find the cosine of the angle between two vectors. aptvaxb Find a vector product and its magnitude. Parallel?. aptvaxc Find vector product of two major plane vectors. Parallel?. aptvcvc Project a vector onto another vector in a major plane. aptvdic Find the direction vector between two points in a major plane. aptvdil Find the distance between two points on a major axis. aptvdis Find a vector difference. Coincidence?. aptvdoc Find scalar product of two major plane vectors. Orthogonal? aptvdos Find a scalar product of two vectors. (1+ 2nd.) Orthogonal?. aptvdot Find a scalar product of two vectors. (1+ pairs.) Orthogonal?. aptvpap Find vector components parallel and perp to another vector. aptvplc Find the vector perpendicular to a line, all in a major plane. aptvpln Find the vector normal to a plane specified by three points. aptvplp Project a vector onto a plane in xyz space. aptvsuc Find the weighted sum of two vectors in a major plane. aptvsum Find the weighted sum of two vectors. aptvuac Find magnitude, replace a major plane vector with unit vector. aptvubc Find magnitude, unit vector for a vector in a major plane. aptvuna Find magnitude, replace a vector with a unit vector. aptvunb Find magnitude, unit vector for a vector. aptvunz Find magnitude, replace a vector with a unit vector (scalar). aptvusz Find magnitude, unit vector for a vector (scalar version). aptvxuc Find magnitude, unit vector product of two major plane vectors. aptvxun Find magnitude, unit vector product of two vectors. aptwhis Find side, distance for a point near a quadric surface. aptwist Twist points around an axis depending on axial position. aptwirl Twist points around an axis depending or radial position. MONTE CARLO SAMPLING (GEOMETRIC) The Monte Carlo (geometric) group contains the subroutines summarized below. aptbrks Randomly sample points in a brick (coordinate volume). aptetrp Randomly sample points in a tetrahedron. aptlocd Randomly sample points on an annular disk. aptlocs Randomly sample points in a spherical annulus. aptlocy Randomly sample points in a cylindrical annulus. aptqloc Randomly sample points in a planar quadrangle or triangle. aptscad Randomly sample planar vectors from a uniform PDF. aptscan Randomly sample 3-D unit vectors at a fixed angle from an axis. aptscap Randomly sample 3-D unit vectors from a cosine-power PDF. aptscar Randomly sample 3-D vectors, cosine-power in spherical sector. aptscat Randomly sample 3-D unit vectors from a uniform PDF. aptscav Randomly sample 3-D unit vectors from cosine-power PDFs. aptscaz Randomly sample a 3-D unit vector at a fixed angle from an axis. aptsciz Randomly sample a 3-D unit vector from a uniform PDF. aptscma Randomly sample 3-D unit vectors at fixed angle from major axis. aptscmz Randomly sample 3-D unit vector at fixed angle from major axis. aptscns Randomly sample points on a frustrum of a right circular cone. aptscnv Randomly sample points in a frustrum of a right circular cone. aptspar Randomly sample points in a parallelopiped or parallelogram. apttloc Randomly sample points in a triangle in a major plane. apttlod Randomly sample points in a triangle in 3-D space. MONTE CARLO SAMPLING (NUMERICAL) The Monte Carlo (numerical) group contains the subroutines summarized below. aptalin Find the aliased bins for a piecewise linear tabulated PDF. aptalsb Randomly sample bins from an aliased tabulated PDF. aptalsh Randomly sample values from a set of specified bins, uniform. aptalsl Randomly sample values from a set of specified bins, linear. aptalst Randomly sample bins in packed aliased PDFs, one PDF per sample. aptcump Find the cumulative PDF for a histogram or piecewise linear PDF. aptcums Randomly sample bins from a cumulative PDF. aptcumt Randomly sample bins in packed CPDFs, one CPDF per sample. apteqin Find equal-probability bin indices for a piecewise linear PDF. apteqsb Randomly sample bins from an array of equally probable bins. apteqxn Find equal-probability bins for a piecewise linear PDF. apteqxs Randomly sample values from a set of equal-probability bins. aptexpl Randomly sample values from one or more limited exponential PDFs. aptexps Randomly sample values from one or more exponential PDFs. aptmaxw Randomly sample values from a relativistic Maxwellian PDF. aptnorm Randomly sample values from one or more Normal PDFs. aptrand Randomly reorder an array. aptrans Randomly sample values from an array, without replacement. aptrfps Randomly sample a value from a range of values (floating-point). aptrfpt Randomly sample values, with any degree of striation (fl-pt). aptrins Randomly sample a value from a range of values (integer). aptrint Randomly sample values, with any degree of striation (integers). aptslid Randomly sample values from a linear PDF. aptsliv Randomly sample one value from each linear PDF. aptspod Randomly sample values on an interval from a power-law PDF. aptxnup Randomly sample frequencies from a Planck or Wien PDF. MONTE CARLO SAMPLING (BIT AND CHARACTER) aptbitr Randomly sample bits and put into part of a machine word. aptchrn Randomly sample characters and put into a character string. MATHEMATICS AND STATISTICS Most of the mathematics and statistics subroutines have unique features to control round-off errors. aptpfab aptbadd Add two big integers (one digit per word, any number base). aptbasb Find the value of a big integer in a specified number base. aptbase Find the value of a decimal number in a specified number base. aptbcat Concatenate the digits of two nonzero big integers. aptbdiv Divide one big integer by another in a specified number base. aptbexp Find the exponential function of a big integer. aptbfac Find the factorial function of a big integer. aptbmul Multiply two big integers (one digit per word, any number base). aptbpac Find the number of perm's and comb's using big integers. aptbpow Find a power of a big integer (one digit per word). aptbrtn Find a root of a big integer (one digit per word). aptbsub Find the difference beween two big integers (one digit per word). aptbsum Find the count of each digit in a big integer, any number base). aptbtod Find the integer, floating point and log values for a big integer. aptcmad Find the greatest common divisor and least common multiple. aptcofr Find the continued fraction, convergents, sums for a given value. aptcofv Find the convergents, partial sums of a continued fraction. aptcomf Find the number of combinations of N things taken M at a time. aptcomg Find the number of ways a group can be separated into smaller groups. aptcrtr Find remainders for an integer, given integer divisors. aptcrts Find the solution to a Chinese Remainder Theorum problem. aptcubs Find the real and complex roots of a cubic polynomial equation. aptdet3 Find the determinant of a 3x3 matrix. aptdet4 Find the determinant of a 4x4 matrix. aptdtob Find the big integer for a specified decimal integer, any number base. aptfact Find the factorial function of an integer. aptftob Find the big integer for a specified decimal floating point value. aptgrat Find ratio of geometric series given first term, sum, length. aptiris Find the integer plus reciprocal integer series for a decimal number. aptltob Find the big integer for a the log10 of a decimal floating point value. aptmean Find mean value and standard deviation of a set of values. aptmord Find order, multiplicative inverse of an integer in modular arithmetic. aptmprd Find the matrix product of two n by n matrices. aptnewt Find a real root of a polynomial using Newtonian iteration. aptperf Find the number of permutations of N things taken M at a time. aptpfab Find all prime factors of a big integer (one digit per word). aptpfac Find all prime factors of an integer, and Euler's totient function. aptpfft Find all prime factors of a factorial function. aptpole Find the values of a polynomial equation for a set of arguments. aptpolf Factor a real root out of a polynomial equation. aptpolr Find real roots, extrema and infl pts of a polynomial equation. aptprim Find prime numbers and irreducible proportion geometric factors. aptqrts Find the real or complex roots of a quadratic equation. aptqrtv Find the real or complex roots of a set of quadratic equations. aptquar Find the real and complex roots of a quartic polynomial equation. aptsolv Solve linear equation sets, invert matrices. aptsudo Solve a Sudoku puzzle. aptsudp Find permitted digits for solving a Sudoku puzzle. aptsudu Find duplicate characters in Sudoku puzzle row, column or box. aptsudx Do bookkeeping for solving a Sudoku puzzle. DATA MANIPULATION The data manipulation subroutines allow a variety of operations on data, of use in many applications. aptcomb Generate all combinations of N things taken M at a time. aptdeld Reduce a table to rows with unique values in specified columns. aptintp Interpolate or extrapolate with two points, linear or log axes. aptlook Table look-up, any interval, ascending or desc, binary search. aptmnlg Find positive values and indices of min and max of an array. aptmnmx Find values and indices of minimum and maximum of an array. aptperm Generate all permutations of N things taken M at a time. aptsorm Sort two or more columns of a 2-D array, any direction, mode. aptsort Sort one column of a 1-D or 2-D array, any direction, mode. aptword Find if machine words are between two specified limits, any mode. BIT AND CHARACTER MANIPULATION (MACHINE INDEPENDENT) The bit and character manipulation subroutines allow parsing of input data, working with file names, formatting output data, and many other tasks. Two additional subroutines, aptbitr and aptchrn, in the Monte Carlo sampling group, allow random sampling of bits and characters. aptatob Copy digits 0-9 in a character string into separate words. aptbitb Do Boolean operations on bits of machine words. aptbite Expand bits from machine words into a type integer*1 array. aptbitf Find a bit string in a machine word. aptbitm Move a bit string from one machine word to another. aptbitp Contract bits from a type integer*1 array into machine words. aptbits Shift bits right or left in a machine word, wrap-around or pull. aptblsq Reduce multiple blanks to a single blank in a character string. aptchai Translate octal, decimal or hexadecimal characters into integer. aptchap Separate a character string into data fields, translate. aptchfp Find a character string in another character string. aptchfs Find a delimited character string in another character string. aptchia Translate integer into octal, decimal or hexadecimal characters. aptchin Increment or decrement a character string, with carry. aptchip Find and replace non-graphic characters in a character string. aptchmv Move a character string from one character array to another. aptchrp Replace individual characters in a character string. aptchsq Squeeze a character out of a string, right-fill with blanks. aptchtp Translate a character string into integer and/or floating-point. aptfbrk Find a delimited character string in another character string. aptffip Read and crack free-field input lines into symbols, by mode. apthexa Translate a decimal number into a hexadecimal string. apthexd Translate a hexadecimal string into a decimal number. aptquot Find a delimited character string, with escaped delimiters. aptrmbl Remove leading and/or trailing blanks from a character string. aptsuba Combine a stem and an ASCII subscript into a character string. aptsubb Combine a stem and ASCII subscripts into a character string. aptsubi Combine a stem and integer subscripts into a character string. aptsubm Translate a character string into a variable and subscripts, more. aptsubr Translate a character string into a variable and a subscript. aptsubs Translate a character string into a variable and a subscript, more. PRECISION AND ROUND-OFF ERROR CONTROL A number of techniques are needed to control or eliminate the effects of round-off error due to the finite number of bits of precision available on computers, especially to get correct and unambiguous answers to such important geometric questions 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. The following subroutines provide methods in addition to those built into most APT subroutines. aptfdad Apply limits to a fractional distance. aptfdav Apply limits to a set of fractional distances. aptnint Round off a value to an integer multiple of a factor, if close enough. aptrnds Round off a value to a relative or absolute precision. aptvlic Impose lower limits on components of a vector in a major plane. aptvlim Impose lower limits on the components of a vector. aptvtoc Impose limits on the components of a vector in a major plane. aptvtol Impose limits on the components of a vector. STANDARD ERROR PROCEDURE An error procedure subroutine is provided to test the error flag returned by another subroutine, write a message to specified output units, providing information about the source of the error, and then to either return or terminate the run, as specified by the user. aptnerr Test error flag, write messages to output files, and return or exit. UCRL-WEB-209832