updated info, attribution, citation, etc for rksuite

Author: drsteve

README.md

@@ -17,4 +17,8 @@ make
 ```
 
 To build the fortran only run `make ptm`, to build/install the Python module only run `make python`, and to convert the Markdown documents to PDF use `make docs`.
-The documentation conversion uses the Node.js `mdpdf` module, which can be installed using `npm install mdpdf -g`. PDF documentation is placed in the `docs` directory.
+The documentation conversion uses the Node.js `mdpdf` module, which can be installed using `npm install mdpdf -g`. PDF documentation is placed in the `docs` directory.
+
+### RKSUITE
+In addition to the basic RK4 integrator, SHIELDS-PTM provides an interface to the RKSUITE library allowing users to select higher-order, adaptive integrators.
+If these integrators are used, RKSUITE and its originators should be credited. For details, please see [rksuite_readme](src/rksuite_readme).

src/rksuite.f90

@@ -5,7 +5,7 @@ module rksuite_90_prec
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 integer, parameter :: wp = kind(1.d0) 
 
@@ -18,7 +18,7 @@ module rksuite_90
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 use rksuite_90_prec, only:wp
 
@@ -132,7 +132,7 @@ subroutine machine_const(round_off,sqrrmc,cubrmc,sqtiny,outch)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 real(kind=wp), intent(out) :: round_off, sqrrmc, cubrmc, sqtiny
 integer, intent(out) :: outch
@@ -160,7 +160,7 @@ subroutine method_const(rk_method, a, b, c, bhat, r, e, ptr, no_of_stages, &
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 integer, intent(in) :: rk_method
 real(kind=wp), intent(out) :: a(13,13), b(13), c(13), bhat(13), r(11,6), e(7)
@@ -594,7 +594,7 @@ subroutine setup_r1(comm,t_start,y_start,t_end,tolerance,thresholds, &
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 real(kind=wp), intent(in) :: t_end, t_start                          !indep!
 real(kind=wp), intent(in) :: tolerance
@@ -857,7 +857,7 @@ subroutine collect_garbage_r1(comm)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 type(rk_comm_real_1d) :: comm
 !
@@ -934,7 +934,7 @@ recursive subroutine range_integrate_r1(comm,f,t_want,t_got,y_got,yderiv_got, &
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 real(kind=wp), intent(in) :: t_want                                  !indep!
 real(kind=wp), intent(out) :: t_got                                  !indep!
@@ -1171,7 +1171,7 @@ recursive subroutine step_integrate_r1(comm,f,t_now,y_now,yderiv_now,flag)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 real(kind=wp), intent(out) :: t_now                                  !indep!
 integer, intent(out), optional :: flag
@@ -1565,7 +1565,7 @@ subroutine truerr_r1(comm,f,ier)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 type(rk_comm_real_1d), intent(inout) :: comm
 integer, intent(inout) :: ier
@@ -1697,7 +1697,7 @@ subroutine step_r1(comm,f,tnow,y,yp,stages,tol,htry,y_new,    &
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 type(rk_comm_real_1d), intent(inout), target :: comm
 real(kind=wp), intent(out) :: err
@@ -1947,7 +1947,7 @@ subroutine stiff_r1(comm,f,toomch,sure_stiff)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 type(rk_comm_real_1d), intent(inout), target :: comm
 logical, intent(in) :: toomch
@@ -2330,7 +2330,7 @@ subroutine statistics_r1(comm,total_f_calls,step_cost,waste,num_succ_steps,&
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 type(rk_comm_real_1d), intent(inout) :: comm
 real(kind=wp), optional, intent(out) :: h_next                       !indep!
@@ -2421,7 +2421,7 @@ subroutine global_error_r1(comm,rms_error,max_error,t_max_error)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 type(rk_comm_real_1d), intent(inout) :: comm
 real(kind=wp), optional, intent(out) :: max_error
@@ -2524,7 +2524,7 @@ subroutine reset_t_end_r1(comm,t_end_new)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 real(kind=wp), intent(in) :: t_end_new                               !indep!
 type(rk_comm_real_1d), intent(inout) :: comm
@@ -2615,7 +2615,7 @@ subroutine interpolate_r1(comm,f,t_want,y_want,yderiv_want)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 real(kind=wp), intent(in) :: t_want                                  !indep!
 type(rk_comm_real_1d), intent(inout), target :: comm
@@ -2947,7 +2947,7 @@ subroutine rkmsg_r1(ier,srname,nrec,comm,flag)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 integer, intent(in) :: ier, nrec
 integer, intent(out), optional :: flag
@@ -3033,7 +3033,7 @@ subroutine set_saved_state_r1(srname,state,comm)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 integer, intent(in) :: state
 type(rk_comm_real_1d), intent(inout) :: comm
@@ -3066,7 +3066,7 @@ function get_saved_state_r1(srname,save_states)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 integer, dimension(7), intent(inout) :: save_states
 character(len=*), intent(in) :: srname
@@ -3104,7 +3104,7 @@ function get_saved_fatal_r1(comm)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 type(rk_comm_real_1d), intent(in) :: comm
 logical :: get_saved_fatal_r1
@@ -3136,7 +3136,7 @@ function get_stop_on_fatal_r1(comm)
 !
 ! Authors: R.W. Brankin (NAG Ltd., Oxford, England)
 !          I. Gladwell  (Math Dept., SMU, Dallas, TX, USA)
-!          see main doc for contact details
+!          see rksuite_readme for contact details
 !
 type(rk_comm_real_1d), intent(in) :: comm
 logical get_stop_on_fatal_r1

src/rksuite_readme

@@ -0,0 +1,121 @@
+The file 'rksuite.f90' includes routines from the RKSUITE software made available
+at www.netlib.org/ode/rkuite. The netlib-provided README file is duplicated below.
+The full RKSUITE library, including the templates, documentation, and F90 and C++
+implementations, can be found at the specified URL.
+
+
+**********************RKSUITE read.me file *************************
+                   ****************************************
+
+
+                  RKSUITE Release 1.0  November 1991
+
+                             written by
+
+          R.W. Brankin (*),  I. Gladwell(**),  and  L.F. Shampine (**)
+
+ (*)  Numerical Algorithms Group Ltd.
+      Wilkinson House
+      Jordan Hill Road
+      Oxford OX2 8DR
+      U.K.
+      email: richard@nag.co.uk
+             na.brankin@na-net.ornl.gov
+      International phone: + 44 865 511245
+      International fax: + 44 865 310139
+
+ (**) Department of Mathematics
+      Southern Methodist University
+      Dallas, Texas 75275
+      U.S.A.
+      email: h5nr1001@vm.cis.smu.edu
+      U.S. phone: (214) 692-2542
+      U.S. fax: (214) 692-4138
+
+
+RKSUITE is a suite of codes based on Runge-Kutta methods for the numerical
+solution of the initial value problem for a first order system of ordinary
+differential equations.  It is the result of decades of research and
+development of such methods and software by the authors.  It supersedes
+some very widely used codes written by the authors and their coauthors,
+namely, the RKF45 code that is available in several books and its descendant
+DDERKF in the SLATEC library, and D02PAF and the associated codes in the NAG
+Fortran library.
+
+RKSUITE is being made available free of charge to the scientific community as
+a public service.  It is expected that anyone making substantial use of the
+software will acknowledge this use, and in particular, give a proper citation
+in any publications resulting from this use.  A suitable reference is:
+
+           R.W. Brankin, I. Gladwell, and L.F. Shampine, RKSUITE: a suite
+           of Runge-Kutta codes for the initial value problem for ODEs,
+           Softreport 92-S1, Department of Mathematics, Southern Methodist 
+           University, Dallas, Texas, U.S.A, 1992.
+         
+The authors have tested the codes on a variety of problems, computers, and
+compilers.  The codes are believed to perform correctly on problems for
+which they were designed.  Of course, errors are possible in a software 
+project of this size.  The authors assume no responsibility for the 
+consequences of errors resulting from the use of this free software.  They
+would greatly appreciate notification of unsatisfactory performance that 
+might indicate the presence of a bug.  Constructive criticism would also be
+much appreciated.
+
+Future releases are planned that will add capabilities to the suite and 
+correct any errors that might be discovered.  
+                      
+                      ============================================
+                      ============================================
+                      YOU SHOULD READ THE DOCUMENTATION CAREFULLY.
+                      ============================================
+                      ============================================
+
+
+                      ===================================================
+                      ===================================================
+                      THE EASIEST WAY TO SOLVE A PROBLEM IS OFTEN TO EDIT 
+                      ONE OF THE TEMPLATES PROVIDED IN THIS DIRECTORY.
+                      ===================================================
+                      ===================================================
+
+
+                             Installation Details
+
+All machine-dependent aspects of the suite have been isolated in the 
+subroutine ENVIRN found in the rksuite.for file.  Some environmental
+parameters must be specified in this subroutine.  The values in the
+distribution version are those appropriate to the IEEE arithmetic 
+standard.  They must be altered, if necessary, to values appropriate to 
+the computing system you are using before calling the codes of the suite.
+If the IEEE arithmetic standard values are not appropriate for your
+system, appropriate values can be often be obtained by calling routines
+named in the Comments of ENVIRN.
+
+         ================================================================
+         ================================================================
+         TO MAKE SURE THAT YOU SPECIFY THESE MACHINE AND INSTALLATION 
+         DEPENDENT QUANTITIES PROPERLY, WHEN THE DISTRIBUTION VERSION IS
+         CALLED IT WRITES A MESSAGE ABOUT THE QUANTITIES TO THE STANDARD 
+         OUTPUT CHANNEL THEN TERMINATES THE RUN.  THE VALUES PROVIDED IN 
+         THE DISTRIBUTION VERSION SHOULD BE ALTERED, IF NECESSARY, THEN
+         THE "WRITE" AND "STOP" STATEMENTS MUST BE COMMENTED OUT.
+         ================================================================
+         ================================================================
+
+The distribution version of rksuite.for is in DOUBLE PRECISION. A REAL 
+version is also available.  When solving ordinary differential equations 
+on many popular computers, it is advisable to use DOUBLE PRECISION. However,
+if DOUBLE PRECISION provides more than about 20 significant figures, the 
+REAL version will usually be satisfactory, provided that the accuracy 
+required of the solution is meaningful in the REAL machine precision. 
+
+The values of the coefficients of the Runge-Kutta methods are supplied in
+the subroutine CONST as DOUBLE PRECISION constants. Some of the coefficients
+are given to 30 significant figures.  It is likely that your compiler will 
+round these constants correctly to the nearest representable machine number.
+If possible, you should request your compiler to round the constants rather
+than truncate them.  Your compiler might warn you that it has shortened
+the representation of the constants. The warning does not imply anything is
+wrong, but you might wish to take action to avoid receiving such messages
+every time you compile RKSUITE. 
+