#***************************************************************** #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. *************************************************************************