*Peter Briggs*

*January 2000*

*Warning: this is an evolving document - the work is in progress!
Things may change - apologies for any inconsistencies.*

- Background
- Plan for rationalisation
- Mathematical routines in the CCP4 Suite
- Using BLAS and LAPACK
- Appendix A: Mathematical subroutines in CCP4 Supported Programs
- Appendix B: Mathematical subroutines in CCP4 Libraries

MODLIB is a CCP4 subroutine library containing a motley collection of mathematical-type routines. The operations catered for are rather arbitrary. Furthermore, not all the mathematical routines present in the suite are collected in MODLIB - some are in other libraries (for example, in SYMLIB), and there are any number of other routines in various programs.

There are four basic stages in the rationalisation programme:

**Document the contents of MODLIB**This has now been done; the resulting document is available at http://www.dl.ac.uk/CCP/CCP4/ccp4/html/modlib.html, and will be also be included as part of future CCP4 releases (v4.0 onwards).

**Compile a list of mathematical subroutines in the suite**This will mean sorting through the programs and other libraries and listing the ``mathematical'' subroutines.

Progress with this stage is below

**Rationalise MODLIB and the suite**This stage follows on directly from (2), and would consist in principle of two sub-stages:

1. Replacing subroutines in programs with calls to equivalent routines in MODLIB,

2. Transferring useful routines from programs or other libraries into MODLIB, and removing where possible duplicated functionality.It is also possible at this stage that omissions might be identified in the available routines in the library, or that a single generalised routine could replace a set of specific versions.

Comments and a plan of action is below

**Replace routines in MODLIB with optimised versions from BLAS etc**BLAS and LAPACK are freely-available libraries of mathematical subroutines, and versions optimised for specific systems can be obtained. It is possible that other external libraries might also be used.

BLAS and LAPACK are now available within CCP4 (v4.1 onwards). Some comments and ideas about BLAS and LAPACK are given below.

This is work in progress. Appendix A lists the routines
identified in various programs as *possible* candidates for rationalisation,
either by relocation to the library, or by replacement with calls to library
routines.

Programs examined so far:

**areaimol**, **act**, **almn**,
**absurd**, baverage, bones2pdb, bplot, cad,
**contact**, coordconv, **crossec**,
**detwin**, **distang**, dm,
dmmulti, **dyndom**,
ecalc, f2mtz, **fft**, **fhscal**, findncs, freerflag,
**gensym**, **geomcalc**,
**getax**, hgen, **hklplot**,
**icoefl**, **lsqkab**,
**makedict**, mama2ccp4, mapdump, mapmask,
maprot, **mapsig**,
maptona4, matthews_coef, **mlphare**, molrep,
mtz2various, mtzMADmod,
mtzdump, mtzmnf, mtztona4, mtzutils, ncsmask, **npo**,
**oasis**, **omit**, overlapmap, **pdbset**,
**peakmax**, phistats, **polarrfn**,
**polypose**, **protin**,
**rantan**, rebatch, refmac,
**reindex**, restrain,
**revise**, **rfcorr**, **rotmat**,
**rsearch**, rsps, rstats, rwcontents,
**scaleit**,
scalepack2mtz, **sc**, **scala**, sfall, sigmaa, sortmtz,
**sortwater**, stnet, surface, **tffc**, tracer, **truncate**, undupl,
unique, **vecref,** **vectors**, volume,
**watertidy**, watncs, **watpeak**, wilson

(Programs in **bold** have routines which should be examined for
rationalisation.)

Details of routines in the libraries can be found in Appendix B.

This exercise has revealed a substantial amount of duplication of functionality, and in many cases duplication of actual code, in routines found in different programs.

It is also apparent that there is a deficiency in the range of functions offered by MODLIB, in particular routines capable of dealing with:

- 4-matrices and vectors,
- eigenvalue and eigenvector problems,
- sorting routines, and
- generating rotation matrices from various conventions, and extracting rotation angles from existing matrices.

My suggested next set of steps is as follows:

- Identify duplicated
*code*and where possible bring these routines into the library.

Possible candidates include GMPRD, DCOSFD, MATMUL4. - Check for duplication of
*functionality*between routines in different programs, and between those in the programs and in the library.

Replace routines in programs with calls to equivalent routines in MODLIB (if routines with the required functionality don't exist in the library, transfer them from the programs first). - Check for duplication of functionality between routines within the library,
(for example GMPRD probably duplicates an existing library routine)
and rationalise.

Essentially this should be a cleaning-up exercise after the previous steps. - Identify routines which are not duplicated, but which seem to have useful functionality which is not covered by the library, and bring these into MODLIB too. A program like rsps has its own "library" which might be a useful model for identifying gaps in MODLIB at this stage.

It will not be appropriate to do this for every single routine or program; in some cases it will left up to the program authors/maintainers to decide whether to make the switch. After all, this job will be hard enough as it is!

**NOTE:** since the time of writing CCP4 4.1 has been released,
which has the option of linking in BLAS and LAPACK at install-time, and includes
the source code for BLAS and LAPACK taken from NetLib.

Some of the comments below are therefore now out-of-date; furthermore information
about LAPACK within CCP4 has become rather dispersed:

BLAS and LAPACK in CCP4 (from the MODLIB documentation).

Configure options from the current CCP4 INSTALL document (4.1 at the time of writing) - see the
**--with-lapack** option.

LAPACK in CCP4 4.1
from CCP4 newsletter 39 (may not be available yet).

This would be the last step in rationalisation, and consists of replacing CCP4 code with calls to external libraries to perform various maths functions. The motivation for doing this is that we can access routines which are robust and efficient.

BLAS (Basic Linear Algebra Subprograms) contains routines for "basic" vector and matrix operations, for example dot product. Architecture-specific optimised versions of BLAS are available for different systems (see list). Generic (non-optimised) versions of BLAS are also available from NetLib, though these will be slower (and in some cases may give significantly worse performance).

LAPACK (Linear Algebra PACKage) contains routines for: solving systems of linear equations, linear least squares problems, eigenvalue problems and singular value problems. LAPACK can also handle many associated computations such as matrix factorizations or estimating condition numbers.

The complete LAPACK can be freely obtained from NetLib. The routines are written so that as much as possible computations are performed by calls to the BLAS. Having optimised BLAS routines is therefore an advantage speed-wise; the generic version of BLAS allows LAPACK to be run on machines which do not have any other implementation of the BLAS. Some vendors provide maths libraries which include BLAS and LAPACK.

For more information about the BLAS, visit http://www.netlib.org/blas/faq.html; this site also offers links to vendor-supplied BLAS (though some of these seem out of date now).

For information about LAPACK see http://www.netlib.org/lapack/faq.html.

The BLAS libraries are provided in a number of different ways for different platforms, and it may be difficult to rationalise.

System | Name of library | Link | Comments |
---|---|---|---|

Digital/Compq | CXML (Compaq eXtended Math Library), libcxml | http://www.compaq.com/math/ | Freely downloadable, includes BLAS 1-3, LAPACK + others. |

SGI | SCSL | http://www.sgi.com/software/scsl.html | Freely available (only for IRIX 6.4 onwards however), includes BLAS and LAPACK. |

HP | MLIB (Mathemetical Software Library) | http://www.hp.com/rsn/mlib/mlibhome.html | Free evaluation copy available, otherwise must be paid for(?), includes BLAS and LAPACK. |

NT | Intel Math Kernal Library | http://developer.intel.com/vtune/perflibst/mkl/ | Licensed binaries are freely redistributable, includes BLAS and a "substantial subset" of LAPACK. |

Sun | ? | Try http://www.sun.com/workshop/fortran/ | Possibly part of Forte? |

Linux | Intel BLAS | http://www.cs.utk.edu/~ghenry/distrib/ | BLAS only. |

It will necessary for those wishing to use the BLAS etc routines to obtain the libraries themselves; they would not be supplied with the suite. This shouldn't be a problem since most vendors seem to supply a version of BLAS, either as part of the standard compilers or else freely downloadable, whilst Netlib also provides an (un-optimised) version. Netlib also provides the LAPACK routines.

A clone of MODLIB would be written which contains the same subroutines
and functions as the CCP4 version, but replaces the code within those
subroutines with calls to the BLAS etc libraries instead. A switch within
`configure` (eg. `--with-blas`) would be necessary to tell
the compilation which version of MODLIB it should use.

This stage is still some way off.

I have decided to organise the subroutines into groups based on similar/related functions, and within these groups to classify the routines with codes which identify those with (near-)identical functionality.

The groups are:

- Matrix operations
- Vector operations
- Rotations etc
- Sorting routines
- Eigen values/vectors
- Testing/setting matrices
- General array & matrix manipulations
- Solving sets of linear equations
- Miscellanous routines

The codes in this group are:

MM = matrix-matrix multiplication MV = matrix-vector multiplication IM = matrix inversion DET = calculate matrix determinant

Program | Routine | Function | Code/Action |
---|---|---|---|

areaimol | MATMUL4 | Multiply 2 4x4 matrices | Moved to library |

absurd | ML3MAT | to multiply three matrices | Moved to library |

almn | GMPRD | Ssp general matrix product | Moved to library |

contact | MATMUL4 | A=B*C (4x4 matrices) | Moved to library |

gensym | GMPRD | SSP GENERAL MATRIX PRODUCT R(N,L) = A(N,M) * B(M,L) | Moved to library |

hklplot | MATMULB | [matrix multiplication?] | Ignored |

npo | matrixmultply | matrix multiply a=b*c [3x3] | MM: Ignored |

npo | matrxbymatrx | multiply two matrices Z(3,3)=X(3,3)*Y(3,3) | MM: Ignored |

pdbset | matmln | Multiply two nxn matrices | Moved to library |

polarrfn | MATMLI | Integer matrix multiply [3x3] | Moved to library |

polarrfn | GMPRD | SSP GENERAL MATRIX PRODUCT | Moved to library |

protin | MATMLN | [general matrix-matrix multiplication?] | Moved to library |

rfcorr | MXMT3 | [matrix multiplication?] | Replaced by call to MATMULTRANS |

rotmat | M1TIM2 | matrix3 = matrix1 * matrix2 | MM |

mlphare | M3MUL | C = B*A [3x3 matrix multiplication] | Replaced by call to MATMUL |

mlphare | M3MULT | C = B*A(transpose) [3x3 matrix multiplication] | Replaced by call to MATMULTRANS |

sortwater | matml4 | Multiply 4x4 matrices P = Q . R | Replaced by call to MATMUL4 |

vectors | MATVC4 | Matrix x Vector A(3) = R(4x4) . B(3) | Moved to library |

vectors | GMPRD | SSP GENERAL MATRIX PRODUCT R(N,L) = A(N,M) * B(M,L) | Moved to library |

watertidy | matmln | [general matrix multiplication?] | Moved to library |

watpeak | GMPRD | SSP GENERAL MATRIX PRODUCT R(N,L) = A(N,M) * B(M,L) | Moved to library |

scala | ML3MAT | Multiplies three real matrices of any dimensions | Moved to library |

areaimol | INV44 | Invert 4x4 matrices | Moved to library |

almn | MATINV | invert a matrix | Replace by call to MINVN |

dyndom | M_INV | [3x3 matrix inversion?] | IM: Ignored |

almn | DETMAT | Calculate determinant DET of 3x3 matrix RMAT | Moved to library |

protin | DET3 | [3x3 matrix determinant?] | DET: Ignored |

rotmat | DETMAT | Calculate determinant DET of 3x3 matrix RMAT | Moved to library |

dyndom | DET | [3x3 matrix determinant?] | DET: Ignored |

act | XYZMAT | Multiply coordinates by a matrix | MV: Ignored |

act | XYZTR | Transform coordinates through a symmetry operation | MV: Ignored |

contact | dotransform | Transform vector x by 4x4 matrix RTmat (assumed to be essentiaLLy 3x4) | Replaced by call to TRANSFRM |

detwin | IMATVEC | Post-multiply a 3x3 matrix by a vector (integer) | Moved to library |

gensym | MATVC4 | Matrix x Vector A(3) = R(4x4) . B(3) | Moved to library |

getax | vecmat | [multiply vector by matrix?] | MV: Ignored |

npo | matrxbyvector | matrix * vector Z(3)=X(3,3)*Y(3) | MV: Ignored |

npo | vecttimesmatrx | transposed vector times matrix Z(3)=X(3)*Y(3,3) | MV: Ignored |

npo | vectbymatrxbyvector | transposed vector * matrix * vector vectbymatrxbyvector=X1(3)*Q(3,3)*X2(3) | MV: Ignored |

npo | vectbyvecttranspose | transposed vector * vector vectbyvecttranspose=X(3)*Y(3) | MV: Ignored |

pdbset | trnfrm | Transform vector x by 4x4 matrix rtmat (assumed to be essentially 3x4) Xo = [rtmat][Xi] | Replaced by call to TRANSFRM |

sortwater | mt4vec | Transform vector y = x by 4x4 matrix rtmat (assumed to be essentially 3x4) | Replaced by call to MATVC4 |

watpeak | MATVC4 | Matrix x Vector A(3) = R(4x4) . B(3) | Moved to library |

The codes in this group are:

VNORM = normalise vector (i.e. reduce to unit vector) VDOT = dot product VCROSS = cross product VDIFF = difference between two vectors VSUM = sum of two vectors VTRIP = vector triple product VPERM = permute vector elements VUNIT = set to unit vector (same as VNORM??)

Program | Routine | Function | Code |
---|---|---|---|

absurd | VNORM | Normalize a vector of length 3 | VNORM |

geomcalc | vnorm | Normalise 3 vector b -> a | VNORM |

sc | normal | [normalise vector?] | VNORM |

distang | VPROD | will be the vector product of a x b and will be normalised to unit length | VCROSS |

hklplot | VPROD | C will be the vector product of A x B and will be normalised to unit length | VCROSS |

dyndom | VECPROD | ROUTINE TO CALCULATE VECTOR PRODUCT BETWEEN TWO VECTORS | VCROSS |

npo | vectorproduct | vector product z=x*y [3-vectors] | VCROSS |

npo | vectordifference | vector - vector z(3)=x(3)-y(3) | VDIFF |

sc | triple | [vector triple product?] | VTRIP |

fft | PRMVEC | Permute vector JV(N,3) by permutation matrix PERM | VPERM |

fft | PRMVET | Permute vector JV(N,3) by transpose of permutation matrix PERM | VPERM |

rsearch | PRMVEC | duplicate of that in fft? | VPERM? |

rsearch | PRMVECT | duplicate of PRMVET in fft? | VPERM? |

npo | getunitvectors | [generate unit vector] | VUNIT |

The codes in this group are:

ANG2MAT = rotation matrix from angles MAT2ANG = angles from rotation matrix GETDIR = direction cosines from angles etc ANGDIR = angles from direction cosines etc

Program | Routine | Function | Code |
---|---|---|---|

almn | ANGFX2 | works out various rotation angles corresponding to a given rotation matrix | MAT2ANG |

almn | EULERA | Get Euler angles ALPHA,BETA,GAMMA from matrix | MAT2ANG |

getax | m2p | converts premultiplier matrix to polar angles OMEGA PHI KAPPA | MAT2ANG |

lsqkab | ANGFIX | works out various rotation angles corresponding to a given rotation matrix | MAT2ANG |

polarrfn | EULERA | Get Euler angles ALPHA,BETA,GAMMA from matrix TRSYM | MAT2ANG |

rfcorr | GETEUL | Get the Eulerian angles from the rotation matrix R. | MAT2ANG |

rfcorr | GETPOL | Get the axis vector & polar angles from the rotation matrix R. | MAT2ANG? |

rotmat | ANG010 | [extract Euler angles from matrix?] | MAT2ANG |

rotmat | ANG011 | [extract rotation angles from matrix?] | MAT2ANG |

rotmat | ANG018 | [extract ??? angles from matrix?] | MAT2ANG |

absurd | ROTMAT | FORMS ROTATION MATRIX MAT FROM THE THREE ANGLES ANG(1), ANG(2), AND ANG(3) | ANG2MAT |

absurd | RTMATS | to calculate a rotation matrix and derivatives | ANG2MAT |

getax | p2m | converts polar angles OMEGA PHI KAPPA to premultiplier matrix | ANG2MAT |

pdbset | polmat | Sets rotation matrix ROTN expressing a rotation through an angle KAPPA right-handedly about an axis with polar angles OMEGA, PHI | ANG2MAT |

pdbset | eulmat | Sets rotation matrix ROTN expressing a rotation through an angles alpha, beta, gamma (degrees) = ANGLES | ANG2MAT |

polarrfn | POLMAT | Sets rotation matrix ROTN expressing a rotation through an angle AKAPPA right-handedly about an axis with polar angles OMEGA, PHI | ANG2MAT |

rotmat | ROT010 | [generate rotation matrix from angles?] | ANG2MAT |

rotmat | ROT011 | [generate rotation matrix from Euler angles?] | ANG2MAT |

rotmat | ROT018 | [generate rotation matrix from spherical angles?] | ANG2MAT |

scala | RTMATS | Creates a rotation matrix and optional derivatives up to the 4th with respect to the angle of rotation. | ANG2MAT |

scala | rtzmat | Get rotation matrix around z | ANG2MAT |

almn | DCOSFD | Given a rotation matrix ROTN, expressing a rotation through an angle KAPPA right-handedly about an axis with direction cosines DIRCOS(I), DCOSFD determines DIRCOS() and KAPPA | GETDIR |

absurd | DCOSFD | Same as DCOSFD in almn? | GETDIR |

polarrfn | DRCCOS | Set dircetion cosines V of axis along omega = P(1), phi = P(2) | GETDIR |

polarrfn | DCOSFD | Same as DCOSFD in almn? | GETDIR |

scala | DCOSFD | Same as DCOSFD in almn? | GETDIR |

absurd | POLANG | Determines polar coordinates from the direction cosines of a vector | ANGDIR |

polarrfn | POLANG | Find polar angles OMEGA & PHI (degrees) from direction cosines DC | ANGDIR |

The codes in this group are:

SORT = sorting routine (details vary)

Program | Routine | Function | Code |
---|---|---|---|

almn | AHVSOR | [sorting routine?] | SORT |

almn | SORT1 | sorting routine | . |

crossec | SORT | [sorting routine?] | SORT |

getax | QSORTI | SORTS THE ARRAY A(I),I=1,2,...,N | SORT |

oasis | SORT | [sorting routine?] | SORT |

omit | SORT3 | SORT A VECTOR INTO INCREASING ORDER [integer sort] | SORT |

peakmax | SORT2 | THE ELEMENTS OF ARRAY A0(N) ARE SORTED INTO INCREASING ORDER OF MAGNITUDE | SORT |

polarrfn | SORT1 | THE ELEMENTS OF ARRAY A0(N) ARE SORTED INTO INCREASING ORDER OF MAGNITUDE | SORT |

rantan | SORT | SORT ON A. | SORT |

rantan | SORT1 | GENERAL PURPOSE SORT ON TWO INTEGER ARRAYS | SORT |

rantan | SORT2 | [another sorting routine?] | SORT |

rfcorr | BTSORT | Binary tree sort in ascending order | SORT |

dyndom | SORT | SORT USING STRAIGHT INSERTION METHOD | SORT |

dyndom | SORTR | SORT USING STRAIGHT INSERTION METHOD | SORT |

scala | qsortr | sorts arrays sarray non-recursive version of quicksort algorithm (c.a.r. hoare) | SORT |

vecref | BTSORT | Binary tree sort | SORT |

The codes in this group are:

EIGEN = obtain eigen values and/or vectors

Program | Routine | Function | Code |
---|---|---|---|

distang | EIGEN | compute eigenvalues and eigenvectors of a real symmetric matrix | EIGEN |

geomcalc | EIGN3 | RETURNS EIG-VALS IN DESC ORDER IN VALS CORRESP VECS AS COLS OF VECS | EIGEN |

icoefl | EA06D | [finds eigenvalue and eigenvectors?] | EIGEN |

icoefl | EA08D | [finds eigenvalue and eigenvectors?] | EIGEN |

lsqkab | EIGEN | compute eigenvalues and eigenvectors of a real symmetric matrix | EIGEN |

makedict | EIGN3 | RETURNS EIG-VALS IN DESC ORDER IN VALS; CORRESP VECS AS COLS OF VECS | EIGEN |

npo | geteigenvalues | eigenvalues and eigenvectors of 3x3 matrix | EIGEN |

mlphare | EIGN1M | This routine is a variant of eign which diagonalizes a matrix within itself. | EIGEN |

polypose | EIGVAL | EIGEN VALUE SUBROUTINE FOR TRI-DIAGONAL MATRICES | EIGEN |

polypose | EIGVEC | [eigen vector subroutine?] | EIGEN |

scaleit | EIGEN | Compute EIGENvalues and EIGENvectors of a real symmetric matrix [SSP routine?] | EIGEN |

vecref | EIGEN | SUBROUTINE TO COMPUTE EIGENVALUES & EIGENVECTORS OF A REAL SYMMETRIC MATRIX [SSP routine?] | EIGEN |

scala | bangle | Get rotation angle of principle axes from eigenvector matrix | EIGEN? |

scala | bfnorm | Normalize 2x2 Bfactor matrix to make sum of eigenvalues equal | EIGEN? |

The codes in this group are:

SETIDENT = set matrix to identity TESTIDENT = test if matrix is identity TESTDET = test determinant of matrix TESTROT = test if matrix is a rotation TESTORTH = test if rotation is orthonormal

Program | Routine | Function | Code |
---|---|---|---|

reindex | unitmt | Set nxn matrix U to unit matrix | SETIDENT |

sortwater | setim4 | Set 4x4 matrix a to identity | SETIDENT |

scala | unitmt | Set 3x3 matrix to unit matrix | SETIDENT |

contact | SIDENT | test for unit matrix and zero translation | TESTIDENT |

npo | testmatrix | test matrix for determinant of 1.0 | TESTDET |

pdbset | tstrot | Test if 3x3 part of 4x4 matrix is actually a rotation | TESTROT |

sortwater | chkmt4 | Check 4x4 matrix for orthogonality, ie that 3x3 rotation part is orthonormal | TESTORTH |

The codes in this group are:

COPY = copy one array into another ZERO = set an array to zero STATS = get statistics (e.g. mean) from an array of data

Program | Routine | Function | Code |
---|---|---|---|

act | MOMENT | calculate AVErage value, AVErage Deviation, Standard DEViation of an array of DATA of length N | STATS |

absurd | MOVEIT | Copy N items from A to B | COPY |

absurd | ZEROIA | Zero N elements of IA | ZERO |

absurd | ZERORA | Zero N elements of A | ZERO |

pdbset | strotn | STore ROTatioN Transfer rotational elements of 3x3 matrix A to 4x4 matrix B Other elements of B left unchanged | COPY? |

scala | MOVEIT | Copy N items from A to B | COPY |

The codes in this group are:

SOLVE = solve sets of linear equations

Program | Routine | Function | Code |
---|---|---|---|

npo | matrixsolve | Solution of matrix equation ax=b for x | SOLVE |

revise | GAUSSJ | Linear equation solution by Gauss-Jordan Elimination | SOLVE |

mlphare | MATSOL | Uses a modified cholesky method to solve the matrix system ax = b returning x in b. | SOLVE |

scaleit | EIGSOL | Solution of linear equations by eigenvalue filtering. | SOLVE |

vecref | EIGSOL | Solution of linear equations by eigenvalue filtering | SOLVE |

mlphare | MATIN1 | Matrix inversion with accompanying solution of linear equations | SOLVE? |

These are the ones left over, for the time being. Some of the codes are:

HASH = hashing routines INTERP = interpolation of functions MTRANS = transform matrices ANGLE = get angles from sets of vectors/points/etc

Program | Routine | Function | Code |
---|---|---|---|

almn | MDCFT2 | Multi-dimensional complex fourier transform for data stored as fortran complex numbers | MTRANS |

almn | MDHFT | Multidimensional hermitian symmetric transform | MTRANS |

absurd | WRMATX | Print matrix A (3x3) labelled S | . |

contact | GETANGL | Angle formed by three points | ANGLE |

crossec | AKNINT | AITKEN REPEATED INTERPOLATION | INTERP |

fhscal | FSPLIN | CUBIC SPLINE INTERPOLATION | INTERP |

icoefl | EA09D | [Harwell routine?] | . |

icoefl | MATIND | [?] | . |

icoefl | MD04B | [Harwell routine?] | . |

npo | getqmatrix | [get covariance matrix?] | MTRANS |

npo | transposematrix | transpose(transpose(x)*y)=z X,Y,Z ARE 3X3 MATRICES | MTRANS |

polarrfn | RNGANG | Put angle A into range 0-360 degrees | ANGLE |

polypose | TRIDI | TRI-DIAGONALIZATION SUBROUTINE | MTRANS |

mapsig | CONDIR | [Fletcher-Reeves-Polak-Ribiere conjugate direction minimisation?] | . |

mapsig | LINMIN | Minimisation of FX=FUNC(X) by line search along X | . |

mapsig | DELVEC | Apply shift vector F*DV to Chi-squared function argument vector | . |

tffc | FSPLIN | CUBIC SPLINE INTERPOLATION. | INTERP |

truncate | SCNDER | Returns second derivatices (Y2) of the interpolating function for y(x) whose N values Y are tabulated for points X | INTERP? |

truncate | SPLINT | Returns a cubic-spline interpolated value of function y(x) whose N values Y are tabulated for points X | INTERP |

dyndom | SVD | DETERMINES THE SINGULAR VALUE DECOMPOSITION
A=USV^{T} OF A REAL M BY N RECTANGULAR
MATRIX. HOUSEHOLDER BIDIAGONALIZATION AND A
VARIANT OF THE QR ALGORITHM ARE USED | . |

scala | EA06CD | [Harwell?] | . |

scala | MC04BD | [Harwell?] | . |

scala | EA08CD | [Harwell?] | . |

scala | EA09CD | [Harwell?] | . |

scala | CALERF | This packet evaluates erf(x), erfc(x), and exp(x*x)*erfc(x) for a real argument x. It contains three FUNCTION type subprograms: ERF, ERFC, and ERFCX (or DERF, DERFC, and DERFCX), and one SUBROUTINE type subprogram, CALERF | . |

scala | ORDR3F | Find NQ(1) so that |Q(NQ(1)| is biggest Q | . |

scala | SCNDER | Returns second derivatices (Y2) of the interpolating function for y(x) whose N values Y are tabulated for points X. | INTERP |

scala | SPLINT | Returns a cubic-spline interpolated value of function y(x) whose N values Y are tabulated for points X. | INTERP |

These are (generally) the programs which are made up from several files. Often they use internal routines with similar functions to those listed above but they have standard headers peculiar to that particular program, which makes them unsuitable at present for inclusion in the library. They are listed here for the sake of completeness.

These programs contain a number of generalised routines for manipulating vectors/matrices (symuvw, symmatmul etc) and for generating rotation matrices (eulertomatrix, polartomatrix).

Contains matrix operations, rotation-matrix generation, sorting, finding eigenvalues and eigenvectors (amongst others).

refmac has its own set of routines for matrix operations etc in the linalgebra.f file. This also contains routines for linear equation solution by Gauss-Jordan method (``GAUSSJ'') and solving the normal equation (a*dv=v) by conjugate gradient method (``CGSOLVE'').

restrain contains a number of routines for the solution of linear equations (some derived from LINPACK?).

Subroutines | Description |
---|---|

congra | This subroutine solves the normal equations by the Hestenes & Stiefel Conjugate Gradient method. |

detmat | THIS SUBROUTINE CHECKS DETERMINANT OF 3*3 ROTATION MATRIX |

orthog | THIS SUBROUTINE CHECKS IF 3*3 ROTATION MATRIX IS ORTHOGONAL |

renorm | THIS SUBROUTINE RENORMALISES 3*3 ORTHOGONAL ROTATION MATRIX |

eigen | SUBROUTINE TO COMPUTE EIGENVALUES & EIGENVECTORS OF A REAL SYMMETRIC MATRIX, FROM IBM SSP MANUAL [nb copy of eigen found in other progs?] |

matpol | Given rotation matrix R, returns direction D of rotation axis, and polar angles A (deg.). |

invmat | Invert 3x3 matrix. |

condir | Given a starting point XP that is a vector of length NP, Fletcher-Reeves-Polak-Ribiere conjugate direction minimisation is performed on a function defined by DELVEC(x), using its gradient calculated by SCGRAD(x,g) |

linmin | Minimisation of FX=FUNC(X) by line search along X |

EIGSOL | Solution of linear equations by eigenvalue filtering. |

solve | SOLVE NORMAL EQUATIONS BY CHOLESKY FACTORISATION. |

solved | (LINPACK) Single precision positive-definite packed real symmetric matrix. Factorization step. |

solver | (LINPACK (SPPSL)) Single precision positive-definite packed real symmetric matrix. Solve linear equations step. |

solvei | SOLVE NORMAL EQUATIONS BY CHOLESKY FACTORISATION - INVERSION STEP |

deigen | SUBROUTINE TO COMPUTE EIGENVALUES & EIGENVECTORS OF A REAL SYMMETRIC MATRIX, FROM IBM SSP MANUAL (SEE P165). |

saxpy | (LINPACK) Single precision constant*vector + vector. |

MATRIX | A SUBROUTINE TO TRANSFORM A TENSOR (TEN) TO THE TENSOR (CAR) WRT TO ANOTHER SET OF AXES BY MULTIPLYING BY THE MATRIX OF EIGENVECTORS (VEC) AND ITS TRANSPOSE: CAR = VEC~.TEN.VEC . |

MATMLT | A SUBROUTINE FOR MULTIPLYING TWO 3*3 MATRICES TOGETHER. |

CALCRS | THIS SUBROUTINE CALCULATE EIGENVALUES (EVAL) AND VECTORS (EVEC) OF MATRIX R OF ORDER N |

EIGEN | SUBROUTINE TO COMPUTE EIGENVALUES & EIGENVECTORS OF A REAL SYMMETRIC MATRIX, FROM IBM SSP MANUAL |

Matrix and vector operations can be found in veclib.f. This appears to be quite a comprehensive set of routines:

* s/r matcmp compare two n x m real matrices * s/r rmatcmp = matcmp * s/r imatcmp compare two n x m integer matrices * * s/r matcop copy n x m real matrix * s/r rmatcop = matcop * s/r imatcop copy n x m integer matrix * s/r drmatcop copy n x m double precision matrix to real * * s/r matclr clear n x m real matrix * s/r rmatclr = matclr * s/r imatclr clear n x m integer matrix * s/r dmatclr clear n x m double precision matrix * s/r cmatclr clear n x m character matrix * * s/r rmatset set all elements in n x m real matrix * s/r imatset set all elements in n x m integer matrix * s/r dmatset set all elements in n x m double precision matrix * s/r cmatset set all elements in n x m character matrix * * s/r vecdif subtract two real vectors * s/r vecadd add two real vectors * s/r vecabs abs of real vector elements * s/r rvecdif = vecdif * s/r rvecadd = vecadd * s/r rvecdif = vecdif * s/r rvecmod modulus of real vector * s/r ivecdif subtract two integer vectors * s/r ivecadd add two integer vectors * s/r ivecabs abs of integer vector elements * * s/r ivecf convert integer vector to real * s/r fveci convert real vector to integer * * s/r mtxtps transpose n x m real matrix * s/r mtxinv invert n x n matrix * s/r mtxmlt multiply n x m matrix by m x n matrix * s/r vmxmlt mulitply n x 1 vector by m x n matrix * * s/r transpose transpose n x n real matrix * s/r matinv invert 3 x 3 real matrix * s/r vmtply multiply 3 x 1 vector by 3 x 3 matrix * s/r mmtply multiply 3 x 3 matrix by 3 x 3 matrix * s/r cosabg cosine of three angles * s/r ortho get (de)orthogoanlization matrix from cell * s/r pnt2pln get plane equation from three points * fn plndst distance between point and plane * s/r polar2mtx convert polar angles to matrix * s/r nfold2mtx convert direction cosines and rot angle to matrix * s/r msk .and. two logical vectors, count and point * s/r mskcmp compare two logical vectors * * s/r isort sort real array, co-sort integer vector * s/r fsort sort real array, co-sort real vector * s/r qsortfi quicksort real array, co-sort integer vector * s/r qsortff quicksort real array, co-sort real vector * s/r qsortffi quicksort real array, co-sort real and integer vector * s/r qsortpf quicksort pointers * s/r nsorta Sort N columns on values in key column, acending * * fun det determinant of 3 x 3 matrix * fun vlen length (A) of fractional vector in ]-0.5,0.5[ * fun vlen2 length (A) of fractional vector * * fun imaxvc maximum element in vector (integer) * fun iminvc minimum element in vector (integer) * fun fmaxvc maximum element in vector (real) * fun fminvc minimum element in vector (real) * fun random pseudo-random number generator (real)

Library | Routine | Function | Comments/Action |
---|---|---|---|

symlib | DETERM | 4x4 matrix determinant | . |

symlib | INVSYM | subroutine to invert 4*4 matrices for conversion between real space and reciprocal space symmetry operators | . |

symlib | PRMVCI | Permute vector JV(N,3) by permutation matrix PERM | . |

symlib | PRMVCR | Permute vector AV(N,3) by permutation vector KP | . |

symlib | ROTFIX | Permutes inverse symmetry operations | . |

symlib | CCP4_HASH_LOOKUP | [Hashing function] | . |

symlib | CCP4_HASH_SETUP | [Hashing function] | . |

symlib | CCP4_HASH_ZEROIT | [Hashing function] | . |

lgglib | angle | calculate the angle between two vector v1, and v2 [3-vectors] | . |

lgglib | ANTIARR | [transpose arbitrary matrix/array] | . |

lgglib | ARRAD | [add arbitrary matrices/arrays] | . |

lgglib | ARRGIVE | [copy arbitrary vector/array] | . |

lgglib | ARRI | [copy "column" from matrix to a vector] | . |

lgglib | ARRJ | [copy "row" from matrix to a vector] | . |

lgglib | ARRMC | [multiply array by a constant] | . |

lgglib | ARRMULT | [generalised matrix multiplication?] | . |

lgglib | ARRPS | [subtract arbitrary matrices/arrays] | . |

lgglib | arrrtoi | to transfer a matrix from real to integer | . |

lgglib | arrvalue | [set all elements of a matrix to constant] | . |

lgglib | AVERG | A routine to calculate the averge value of a M*N array XIN. | . |

lgglib | DRVRBD | This is a subroutine to calcalate the matrix of deriv(E)/deriv(theta i) where E is a rotation 3*3 matrix and theta i (i=1,2,3) is Eulerian Angle in ROH system. | . |

lgglib | DRVROHTH | This is a subroutine to calcalate the matrix of deriv(E)/deriv(theta i) where E is a rotation 3*3 matrix and theta i (i=1,2,3) is Eulerian Angle in ROH system | . |

lgglib | DRVROHTHARC | This is a subroutine to calcalate the matrix of deriv(E)/deriv(theta i) where E is a rotation 3*3 matrix and theta i (i=1,2,3) is Eulerian Angle in ROH system | . |

lgglib | DRVROHTHD | This is a subroutine to calcalate the matrix of deriv(E)/deriv(theta i) where E is a rotation 3*3 matrix and theta i (i=1,2,3) is Eulerian Angle in ROH system | . |

lgglib | IARRGIVE | transfer a N-dimensional XYZ0 array to another one XYZ [integer version] | . |

lgglib | IARRMC | A ARRAY MULT A CONSTANT [integer version] | . |

lgglib | IMATMULT | MULT TWO ARRAY (a new qick versiion- this is for I4 version | . |

lgglib | IVSN | CHANG A MATRIC INTO A INVERSE MATRIC | . |

lgglib | matitor | transfer a matrix from integer*2 to real*4 | . |

lgglib | MATMULT | MULT TWO ARRAY (a new qick versiion) | . |

lgglib | matrtoi | transfer a matrix from real to integer | . |

lgglib | MTOPOLOR | [polar angles from rotation matrix?] | . |