#*****************************************************************
 
#MRMLIB  -  GENERAL DOCUMENTATION.
 
 
#INTRODUCTION.
 
        "MRMLIB" IS A PERSONAL COLLECTION OF SUBPROGRAMS WHICH CAN
BE CALLED BY FORTRAN PROGRAMS AND WHICH CAN ALSO BE WRITTEN IN
FORTRAN.  THE PRINCIPAL AIM IN SETTING UP THIS LIBRARY HAS BEEN
TO ESTABLISH A REASONABLY PORTABLE SET OF SUBPROGRAMS WHICH CARRY
OUT OPERATIONS THAT WOULD OTHERWISE BE CONTINUALLY REWRITTEN, THUS
MANY OF THE ROUTINES IN THIS LIBRARY PERFORM SIMPLE (EVEN TRIVIAL)
TASKS.  TWO STRONG SECONDARY AIMS ARE TO ESTABLISH A STANDARD
SET OF INTERFACES WHICH ARE INHERENTLY MORE PORTABLE THAN THE
ROUTINES, AND TO ESTABLISH PROVEN SUBPROGRAMS FOR NON TRIVIAL
OPERATIONS PARTICULARLY IN THE NUMERICAL AREA.
        
        NO GUARANTEE AS TO THE CORRECTNESS OR EFFICIENCY OF ANY
ROUTINE CAN BE GIVEN BUT GENERALLY THE ROUTINES WILL HAVE BEEN
USED TO A DEGREE THAT SHOULD ALLOW SOME CONFIDENCE IN THEM.
 
        THE LIBRARY IS MAINTAINED BY:
 
        DR MARTIN. R. MANNING
        INSTITUTE OF NUCLEAR SCIENCES
        LOWER HUTT
        NEW ZEALAND.
 
IT IS FREELY AVAILABLE TO ANYONE WHO IS INTERESTED AND COMMENTS
CERTIFICATIONS, COMPLAINTS AND PARTICULARLY CONSTRUCTIVE
CRITICISMS WILL BE WELCOMED.
 
        THE "BASE" FOR THE LIBRARY CONSISTS OF 
 
        1.  GENERAL DOCUMENTATION (THIS DOCUMENT).
 
        2.  A CATALOGUE OF ALL CURRENT SUBPROGRAMS.
 
        3.  FORTRAN IV SOURCES FOR ALL ROUTINES.
 
IN ADDITION TO THIS "BASE" THERE WILL BE
 
        4.  ASSEMBLY LANGUAGE VERSIONS OF SOME ROUTINES FOR
        SOME SYSTEMS.
 
        5.  CATALOGUES OF THOSE ROUTINES AVAILABLE IN
        A GIVEN SYSTEM LIBRARY.  THIS MAY CONTAIN OTHER
        ROUTINES NOT IN "MRMLIB" AS WELL.
 
        6.  SPECIAL REPORTS ON ORIGINAL ALGORITHMS ETC.
 
AND AS DOCUMENTATION OF MANY ALGORITHMS WILL CONTAIN REFERENCES TO
THE GENERAL PUBLISHED LITERATURE, THE FULL DOCUMENTATION OF
"MRMLIB" IS BACKED UP BY STANDARD JOURNALS, REPORTS ETC.
 
        THE BASE FOR "MRMLIB" AS DESCRIBED ABOVE IS ALL KEPT ON
COMPUTER READABLE MEDIA AND WILL BE ACCESSIBLE THROUGH STANDARD
SUPPORT PROGRAMS SUCH AS EDITORS ETC. ON SEVERAL SYSTEMS.  IN
ADDITION SPECIAL PROGRAMS MAY BE MADE AVAILABLE TO ALLOW EASY
USER ACCESS TO SOURCES AND DOCUMENTATION.  TO AID THIS ASPECT
OF "MRMLIB" THE DOCUMENTATION FILES (INCLUDING SOURCE FILES ) ARE 
FORMATTED IN SUCH A WAY AS TO FACILITATE CONTEXT EDITING ETC.
 
        
#GENERAL DOCUMENTATION.
 
        THIS DOCUMENT IS INTENDED TO DESCRIBE THE GENERAL
FEATURES OF THE LIBRARY AND STANDARD CONVENTIONS FOR SOME
GROUPS OF SUBPROGRAMS.  THE SUBPROGRAMS ARE OFTEN CONVENIENTLY
GROUPED INTO "PACKAGES" FOR THIS PURPOSE AND A SET OF CONVENTIONS
GIVEN FOR THE PACKAGE.  THESE MAY INCLUDE SUCH THINGS AS COMMON
BLOCKS, REGULAR FEATURES OF PARAMETER LISTS, DATA STORAGE
CONVENTIONS ETC.
 
 
#CATALOGUE.
 
        THE CATALOGUE OF ALL CURRENT SUBPROGRAMS WILL CONTAIN A
ONE-LINE ENTRY FOR EACH SUBPROGRAM GIVING ITS NAME, DATE
OF LAST CORRECTION, AND BRIEF PURPOSE.  OBVIOUSLY THIS FORMAT
CANNOT HOPE TO DESCRIBE ADEQUATELY THE PURPOSE OF COMPLEX ROUTINES
BUT IT IS ENFORCED IN THE INTERESTS OF MAKING QUICK SCANS OF
AVAILABLE ROUTINES.  SOME THOUGHT HAS BEEN GIVEN TO BASING THIS
BRIEF DESCRIPTION ON A SHORT DICTIONARY OF KEY-WORDS, HOWEVER
THIS HAS NOT BEEN DONE YET.
 
 
#FORTRAN SOURCE DOCUMENTATION.
 
        THE FORTRAN SOURCE WHICH DEFINES A ROUTINE CONTAINS A
CERTAIN AMOUNT OF INTERNAL DOCUMENTATION.  AT LEAST ENOUGH TO
INFORM A NEW USER WHETHER THE ROUTINE DOES WHAT HE WANTS AND HOW
HE SHOULD CALL IT TO GET THE DESIRED RESULT.  THIS IS GENERALLY
ABOUT ONE PAGE OVER AND ABOVE THE NORMAL FORTRAN BODY OF THE ROUTINE.
 
        THE STANDARD FORMAT DESCRIPTION PART IS GIVEN AS COMMENT
LINES TO THE BODY OF THE PROGRAM AND APPEARS AT THE HEAD.  THE
GENERAL FORMAT COMPRISES THE FOLLOWING SECTIONS IN ORDER:
 
0.      NAME , VERSION AND DATE.
        CONTAINS THE NAME IMMEDIATELY PRECEDED BY A # CHARACTER
        A VERSION NUMBER AND A DATE OF ORIGIN.  IT IS IMMEDIATELY
        FOLLOWED BY A LINE GIVING THE DATE OF LAST MODIFICATION.
 
        E.G.:
                C #MINIY   V1A   30-MAY-73
                C  LAST UPDATE:  6-JUN-73.
 
1.      DECLARATION.
        THIS SECTION GIVES (NOT AS A COMMENT) THE STANDARD "FUNCTION"
OR "SUBROUTINE" STATEMENT STARTING THE FORTRAN CODE AND IS IMMEDIATELY
FOLLOWED BY ANY TYPE DECLARATIONS, ARRAY DECLARATIONS THAT ARE
REQUIRED FOR THE PARAMETERS.
 
2.      PURPOSE.
        THIS SECTION IS ONE OR TWO SENTENCES (POSSIBLY MORE) TO
        PROVIDE A CONCISE DESCRIPTION OF WHAT THE ROUTINE DOES.
        A USER SHOULD BE ABLE TO READ THIS AND THEN KNOW WHETHER
        THE ROUTINE IS OF FURTHER INTEREST.
        THE KEY TO THIS SECTION IS A LINE:
                C *PURPOSE.
 
3.      PARAMETERS.
        THIS SECTION (WHICH GENERALLY MUST BE WRITTEN WITH THE
        MOST CARE) SHOULD CONTAIN A DESCRIPTION OF THE COMPLETE
        INTERFACE WITH THE CALLING ROUTINE.  IN PARTICULAR IT MUST
        GIVE DETAILS OF WHAT EACH PARAMETER IN THE LIST SIGNIFIES
        AT THE INPUT AND OUTPUT PHASES.  IT MUST CONTAIN A SHORT
        LIST OF ALL THE PARAMETERS WHCIH ARE INPUT PARAMETERS
        AND ALL WHICH ARE OUTPUT PARAMETERS.
        ( NOTE.  AN INPUT PARAMETER IS ONE WHOSE VALUE BEFORE THE
        CALL MAY POSSIBLY AFFECT THE RESULT OF THE CALL.  AN OUTPUT
        PARAMETER IS ONE WHOSE VALUE MAY CHANGE AS A RESULT
        OF THE CALL.  OFTEN PARAMETERS WILL BE OF BOTH TYPES.  IT
        IS A VERY DESIRABLE PROGRAMMING RULE TO ENSURE ALL OUTPUT
        PARAMETERS ARE MATCHED BY SIMPLE VARIABLE NAMES.)
        THE KEY TO THIS SECTION IS THE LINE:
                C *PARAMETERS.

4.      METHOD.
        THIS SECTION SHOULD GIVE A CONCISE DESCRIPTION OF ANY NON-
        TRIVIAL ALGORITHMS USED.  IT IS CURRENTLY FELT THAT A DETAILED
        JUSTIFICATION OF THE METHOD IS OUT OF PLACE HERE.  HOWEVER
        IF AN ALGORITHM CANNOT BE COMPLETELY DESCRIBED HERE IT SHOULD
        BE DOCUMENTED SEPARATELY IN A PUBLISHED PAPER,  REPORT  ETC.
        IN THIS CASE REFERENCE IS GIVEN TO THE LARGER REPORT.
        THE KEY TO THIS SECTION IS THE LINE:
                C *METHOD.
 
5.      ACCURACY.
        THIS SECTION SHOULD GIVE ANY NECESSARY INFORMATION AS TO
        THE ACCURACY OF OUTPUT VALUES, OR THE REQUIRED ACCURACY
        OF INPUT VALUES IN SOME CIRCUMSTANCES.  
        THE KEY TO THIS SECTION IS THE LINE:
                C *ACCURACY.
 
6.      RESTRICTIONS.
        THIS SECTION SHOULD GIVE THE RANGE(S) OF THE INPUT PARAMETERS
        FOR WHICH THE ROUTINE WILL WORK, AND ANY NECESSARY PROPERTIES
        OF THE COMPUTING ENVIRONMENT ( SUCH AS WORD LENGTH ).
        ITS KEY LINE IS:
                C *RESTRICTIONS.
 
7.      ERROR CONDITIONS.
        THIS SECTION GIVES THE WAY IN WHICH THE ROUTINE WILL REACT
        TO VIOLATION OF ANY OF THE RESTRICTIONS MENTIONED IN THE
        PRECEDING SECTION.  IT WILL ALSO DESCRIBE THE ROUTINE'S
        BEHAVIOUR IN ANY OTHER SITUATIONS WHICH COULD BE REGARDED
        AS AN ERROR.  ITS KEY LINE IS:
                C *ERROR CONDITIONS.
 
8.      NON STANDARD ROUTINES CALLED.
        THIS SECTION GIVES A BRIEF DESCRIPTION OF ANY ROUTINES
        CALLED FROM WITHIN THE ROUTINE.  NO ATTEMPT IS MADE TO
        GIVE ALL ROUTINES WHICH CAN BE CALLED INDIRECTLY - ONLY
        THOSE WHICH ARE CALLED DIRECTLY.  STANDARD ROUTINES WHICH
        ARE NOT MENTIONED ARE SIMPLY THOSE DEFINED FOR "ANSI" FORTRAN
        IV.  IN FACT ALL OTHER ROUTINES WILL BE IN "MRMLIB" OR ELSE
        WILL BE CALLED VIA AN EXTERNAL NAME OCCURING IN THE
        PARAMETER LIST.  THE KEY LINE FOR THIS SECTION IS:
                C *NON STANDARD ROUTINES CALLED.
 
9.      TYPICAL TIMES.
        THIS SECTION WILL GIVE RELATIVE TIMES FOR THE ROUTINE,
        RELATIVE THAT IS TO OTHER ROUTINES OR TO BASIC TIMES FOR ADD,
        MULTIPLY, ETC. OPERATIONS.  IT SHOULD ALSO GIVE THE DEPENDENCE
        OF THE TIME TAKEN ON THE VALUES OF THE INPUT PARAMETERS.
        THERE SEEMS LITTLE POINT IN THE TEDIOUS WORK OF OBTAINING
        ABSOLUTE TIMES FOR A ROUTINE WHEN COMPUTER SYSTEMS CHANGE AS
        AT PRESENT, AND WHEN THE ROUTINE IS DESIGNED TO RUN ON MANY
        SYSTEMS.
 
10.     ORIGIN.
        THIS SECTION GIVES THE ORIGIN OF THE ROUTINE, MEANING ITS
        CURRENT AND PAST AUTHOR(S).  WHEREVER POSSIBLE THIS SHOULD
        BE TRACED BACK AS FAR AS POSSIBLE, HOWEVER THIS IS OFTEN
        IMPOSSIBLE.  BECAUSE OF THIS I WOULD LIKE TO ISSUE A BLANKET
        APOLOGY TO ANYONE WHO FEELS HE SHOULD HAVE BEEN MENTIONED
        IN AN "ORIGIN" SECTION.  A NOTE TO ME WILL FIX THE MATTER.
        ANY ROUTINE WHICH IS NOT ENTIRELY ORIGINAL WILL HAVE
        COME FROM PUBLISHED LITERATURE FREELY AVAILABLE, OR ELSE
        HAS BEEN DONATED BY ITS AUTHOR.
        THE KEY LINE FOR THIS SECTION IS:
                C *ORIGIN
 
11.     COMMENTS.
        THE PURPOSE OF THIS SECTION IS TO ALLOW FOR ALL THE THINGS
        WHICH COULD NOT BE SAID IN ANY OF THE ABOVE SECTIONS OF THE
        DOCUMENTATION.  IN PARTICULAR IT SHOULD BE USED TO GIVE
        CROSS-REFERENCES TO OTHER ROUTINES ( INSIDE OR OUTSIDE
        "MRMLIB" )  WHICH DO SIMILAR OR RELATED THINGS.
        ITS KEY LINE IS:
                C *COMMENTS.
 
12.     END OF DESCRIPTION.
        CONSISTS OF THE LINE:
                C #END.
 
13.     BODY OF THE FORTRAN CODE.
        THE FORTRAN STATEMENTS AND EXPLANOTORY COMMENTS FOLLOW.
        THEY ARE TERMINATED BY THE STANDARD END LINE INDENTED
        TO COLUMN 6.
 
 
        ALTHOUGH THERE ARE SOME DISADVANTAGES IN KEEPING THE BASIC
DESCRIPTIVE DOCUMENTATION EMBEDDED IN THE SOURCE FILE IT IS FELT THAT
THE ADVANTAGES ARE GREATER.  IN PARTICULAR MODIFICATIONS TO THE
LIBRARY ROUTINES (A FRUSTRATINGLY FREQUENT OCCURRENCE), AND TRANSFER
OF INDIVIDUAL ROUTINES TO OTHER SYSTEMS OR TO USERS FOR PRIVATE
MODIFICATION IS VERY MUCH EASIER.
 
 
#SUBPROGRAM NAMING CONVENTIONS.
 
        SEVERAL LIBRARIES KNOWN TO ME HAVE USED A NAMING
SYSTEM WHICH REPLACES MNEMONIC NAMES WITH A CODED NAME GIVING THE
CLASS OF THE ROUTINE AND A NUMBER WITHIN THIS CLASS.  FOR EXAMPLE
THE HARWELL LIBRARY DOES THIS.  I HAVE NOT ADOPTED THIS PROCEDURE
BECAUSE OF PERSONAL PREFERENCE FOR THE MNEMONIC SYSTEM EVEN THOUGH
IT MUST BE ADMITTED THAT 6 CHARACTERS DO NOT GIVE MUCH FREEDOM
FOR MNEMONIC CREATION.
        THERE IS HOWEVER ONE CONVENTION IN THE NAMES USED HERE
AND THAT IS THAT THE LAST LETTER OF THE NAME DENOTES A VARIANT OR
VERSION NUMBER.  FOR EXAMPLE:
        LSFTA, LSFTB, LSFTF, LSFTG
ARE ALL LINEAR LEAST SQUARES FITTING ROUTINES WITH VERY MUCH
THE SAME CALLING SEQUENCES BUT DIFFERING IN SLIGHT DETAILS.
 
 
#OBSOLETE ROUTINES.
 
        AS THIS IS BASICALLY A PERSONAL LIBRARY I HAVE NO HESITATION
IN PURGING ROUTINES WHICH I FEEL ARE OF NO FURTHER USE FROM THE
"BASE" OF THE LIBRARY.  NATURALLY ONE CANNOT BE SO CAVALIER WITH
THE LIBRARIES IMPLEMENTED ON PARTICULAR SYSTEMS, AND HERE ROUTINES
MUST BE KEPT IN THE LIBRARY (AND DOCUMENTATION KEPT AVAILABLE) AT
LEAST UNTIL ALL USERS HAVE BEEN PERSUADED TO USE ANOTHER VERSION.
        DETAILS OF THIS PURGING WILL BE DEPENDENT ON DETAILS OF THE
PARTICULAR SYSTEM.
 
 
#PARAMETER LISTS - GENERAL CONVENTIONS.
 
        AS FROM 1-JUL-73 ROUTINES ENTERED IN "MRMLIB" WILL
WHEREVER FEASIBLE HAVE THEIR PARAMETER LISTS ORDERED ACCORDING
TO THE FOLLOWING CONVENTIONS:
 
        1.  THE PARAMETERS ARE GROUPED INTO THE CLASSES
            A. ALL EXTERNAL FUNCTION NAMES, SUBROUTINE NAMES,
               ARRAYS AND THEIR DIMENSION PARAMETERS.
            B. ALL OTHER INPUT-ONLY VARIABLES.
            C. ALL OTHER INPUT AND OUTPUT VARIABLES.
            D. ALL OTHER OUTPUT-ONLY VARIABLES.
 
        2.  WITHIN CLASS A. THE PARAMETERS ARE ORDERED AS
            A. EXTERNAL NAMES.
            B. ARRAY NAMES
            C. DIMENSION PARAMETERS FOLLOW AFTER THE LAST ARRAY
                TO WHICH THEY REFER.
            D. GENERALLY OUTPUT ARRAYS WILL FOLLOW INPUT ONES.
 
        3.  WITHIN CALSSES B, C, D THE PARAMETERS ARE ORDERED AS:
            A. REALS ( AND DOUBLE PRECISION, COMPLEX)
            B. INTEGERS
            C. LOGICALS
 
        THIS SCHEME IS NOT DESIGNED TO CATER FOR ALL SITUATIONS
NOR SHOULD BE CONSIDERED BINDING.  IT DOES HOWEVER GIVE A USEFUL
GUIDELINE AS TO WHAT ROLE A PARAMETER MAY PLAY WHEN READING A
TYPICAL CALLING STATEMENT.
 
 
#STANDARD INTERFACE FEATURES.
 
        ROUTINES ADDED TO MRMLIB AFTER 1-JUL-73 WILL NOT ALLOW
SEPARATE MEANINGS FOR SIMPLE VARIABLE PARAMETERS AT THE INPUT AND
OUTPUT PHASES.  THERE WILL ALSO BE A STRONG TENDENCY TO AVOID
SIMPLE VARIABLE PARAMETERS HAVING DIFFERENT VALUES AT THE TWO STAGES.
 
        THE ROUTINES IN MRMLIB GENERALLY DO NOT USE COMMON BLOCKS.
 
        THE STANDARD WAY OF RETURNING INDICATION OF INTERNAL ERROR
WILL BE THROUGH AN OUTPUT-ONLY INTEGER VARIABLE (NORMALLY "IERR"
IN THE LISTING) WHICH IS NON-ZERO IF AN ERROR OCCURRED AND ZERO IF
NOT.
 
        MANY COMPLEX ROUTINES WILL HAVE AN OPTIONAL OUTPUT OF
LOGGING MESSAGES.  IN THIS CASE THERE IS AN INPUT-ONLY INTEGER
PARAMETER WHICH IS ZERO IF NO LOGGING MESSAGES ARE REQUIRED AND
ELSE IS A POSITIVE NUMBER GIVING THE FORTRAN I/O CHANNEL TO
USE FOR THIS OUTPUT.  LOGGING MESSAGES NORMALLY INCLUDE A BRIEF
SUMMARY OF THE PROGRESS OF THE ROUTINE AND CERTAINLY INCLUDE 
SELF-EXPLANATORY ERROR MESSAGES IN CASES OF ERROR.
 
        MANY COMPLEX ROUTINES WILL BE ABLE TO OPERATE QUITE WELL
WITH CERTAIN DEFAULT VALUES OF CERTAIN PARAMETERS, AND IT MAY
BE THAT ONLY THE SPECIALIST USER WILL NEED TO USE SOME PARAMETERS.
IN SUCH A CASE THESE EXTRA PARAMETERS MAY BE COLLECTED INTO A
REAL ARRAY (NORMALLY CALLED "OPT" IN THE LISTING) AND THE DEFAULT
VALUES WILL BE ASSUMED IF THE CORRESPONDING "OPT" ENTRY IS ZERO.
 
 
#FORTRAN SOURCE STANDARDS.
 
        ROUTINES IN "MRMLIB" WILL PREFERABLLY BE WRITTEN IN A
STRUCTURED WAY.  THAT IS THE "GOTO" STATEMENTS WILL NORMALLY BE
JUST THOSE THAT WOULD BE INSERTED BY A HIGH-LEVEL LANGUAGE IN
WHICH THE "GOTO" STATEMENT DID NOT OCCUR.  IN ADDITION INDENTING
OF "DO-LOOP", "IF-THEN-ELSE" AND "CASE" CONSTRUCTIONS ETC WILL
OFTEN BE DONE.
 
        BACKWARD JUMPS WILL BE MINIMIZED.
 
        ANY NON-STANDARD ANSI FORTRAN IV FEATURES WILL USUALLY BE
DISTINGUISHED BY APPROPRIATE COMMENTS, AND THE COMMENTS WILL GIVE
POSSIBLE ALTERNATIVES FOR THE ANSI STANDARD.  HOWEVER AS THE
ANSI STANDARD IS NOT WELL KNOWN BY MOST PROGRAMMERS NO GUARANTEE
CAN BE GIVEN AS TO THIS.  NORMALLY THE ROUTINE WILL HAVE BEEN
COMPILED AND RUN ON AT LEAST TWO DIFFERENT SYSTEMS.
 
        COMMENTS WILL BE RELEVANT AND REASONABLY COPIOUS.  A
ROUGH GUIDE TO THE NUMBER OF COMMENTS IS THAT WHEN THE STANDARD
DOCUMENTATION AT THE BEGINING IS TAKEN INTO ACCOUNT THERE SHOULD
BE MORE COMMENT LINES THAN ALL OTHERS PUT TOGETHER.
 
 
#CONVENTIONS FOR PACKAGES.
 
*QUANTUM MECHANICS  -  TRANSFORMATION BRACKETS PACKAGE.
 
        ANGULAR MOMENTUM QUANTUM NUMBERS ARE REPRESENTED BY INTEGERS
WITH TWICE THE VALUE OF THE PHYSICAL ANGULAR MOMENTUM.  THUS
J=0, 1, 2, 3.  REFERS TO STATES OF ANGULAR MOMENTUM 0, 1/2, 1, 3/2.
ETC.  THIS HAS ONE DISADVANTAGE IN THAT A SPECIAL FUNCTION HAS
TO BE PROVIDED TO RETRIEVE THE FACTORIAL OF HALF ITS ARGUMENT.
 
*SPECIAL FUNCTIONS.
 
        THERE IS AN ADDITIONAL NAMING CONVENTION FOR PROBABILITY
FUNCTIONS AS FOLLOWS.  PROBABILITY DENSITY FUNCTIONS, THAT IS
POINT PROBABILITY FUNCTIONS, ALL BEGIN WITH THE LETTER "D".
CUMULATIVE PROBABILITY FUNCTIONS, THAT IS INTEGRALS OF THE DENSITY
FUNCTION, OVER A RANGE FROM MINUS INFINITY ( OR ZERO AS APPROPRIATE)
UPWARDS BEGIN WITH THE LETTER "P".  THE OPPOSITE TYPE OF CUMULATIVE
PROBABILITY DISTRIBUTION FUNCTION FROM THE TOP OF THE RANGE DOWNWARDS
WILL ALWAYS BEGIN WITH THE LETTER "Q".  THIS FOLLOWS THE CONVENTIONS
USED IN "ABRAMOWITZ AND STEGUN".
 
 
#END.
 
 
*************************************************************************

