module ODEPACK

This is a WIP(Work In Progress) to evaluate the effort required and feasibility of updating older Fortran code from the netlib repository using a combination of the commercial plusFORT/spag software and GNU utilities as well as conventional manual refactoring.

Many thanks to plusFORT for making an evaluation copy available for several months to the Fortran Community. The plusFORT tools were crucial to this study and unmatched in my experience for removing deprecated syntax from pre-f2003 code.

This began with ODEPACK

the ODEPACK package has been selected as a significant code that is well documented and structured for its vintage, and available on the netlib site and covered by a public domain license.

preliminary targets for phase I:

remove obsolescent syntax (trying plusFORT and spag)
able to build using fpm(1) (the Fortran Package Manager)
- in debug mode (ongoing)
- with ifort, gfortran, nvfortran
text viewable in ford(1) and extractable as markup that can run through pandoc(1) (ongoing)
available on github (or equivalent)
no common blocks
no equivalences
build as a (single?) module M_odepack (ongoing)
complete set of unit tests (tests currently only use the original examples)

The originally bundled subset of BLAS/LAPACK routines are being included in the module. In production, this might not be done in order to be able to easily call external optimized versions.

The biggest hinderance is some storage used for both INTEGER and DOUBLE PRECISION values.

One take-away is how critical unit tests are to enable rapid development (which so far this package does not have)

The initial pass was done just using the original sample programs as unit tests. This may have allowed for introduction of errors as this is a WIP but the original samples run with the same output as the original.

plusFORT was invaluable and reduced the effort by an estimated 85 percent. The results have been encouraging enough to inspire completing the transformation.

Phase II ?

Some of the goals of phase I are incomplete, but The results of this first pass were significant enough that this project will hopefully continue.

A complete unit test suite is required to allow development to proceed rapidily. Contributions, especially from current ODEPACK users are particularly welcome.

Another major issue is the remaining non-standard code. Non-standard (but at the time de-facto fortran standard) such as equivalencing different types, creating scratch space that is used as different numeric types, and treating scalars as arrays and vice-versa as well as passing the same arrays or values multiple times are the most time-consuming usages to correct to standard-conforming, particularly since spag(1) had already done an excellent job with updating the pre-f2003 code. spag(1) is not (currently?) sufficient by itself to automate the additional refactoring desired, which includes using post-f95 features and code restructuring, so the remaining work requires manual recoding.

The type-mismatch issues have not been eliminated enough to include all the routines in the module, so those in the files "M_da1/dprep.inc" "M_da1/dainvgs.inc" "M_da1/dprepi.inc" "M_da1/dstodi.inc" and "M_da1_/dstode.inc" still require being built without an interface definition.

building with fpm(1)

This version of ODEPACK already builds with an included make(1) file and as an fpm(1) package with the current options:

 fpm run                     --compiler nvfortran --example '*'
 fpm run --profile release   --compiler ifort     --example '*'
 # gfortran for production
 fpm run --profile release --flag -fallow-argument-mismatch --compiler gfortran  --example '*'
 # gfortran for debug
 fpm run --profile debug --flag -fallow-argument-mismatch --flag -std=f2018 --compiler gfortran  --example '*' --verbose

building with make(1)


cd src
# gfortran
make clean
make gfortran
make run
make test

# ifort
make clean
make ifort
make run
make test

# nvfortran
make clean
make nvfortran
make run
make test

To rebuild the documentation with ford(1), use

 ford ford.md

The code is far more readable after having been refactored by a combination of using spag(1) from the plusFORT package and manual editing, and is believed as useable as the original.

There are a few notes in src/M_odepack.f90 concerning continuing issues.

Current users of ODEPACK are encouraged to try this version and provide feedback.

Hopefully as a community we can complete creating a new maintained production-quality version of this venerable and still-valuable package.

Documentation

The ongoing API documentation for the current master branch can be found here. This is generated by processing the source files with FORD.

Solvers for explicitly given systems.

Links to the solver-specific documenation for the main procedures (as described below):

Here is an overview primarily from the original documentation ...

Brief Description of ODEPACK - A Systematized Collection of ODE Solvers (Double Precision Version)

Alan C. Hindmarsh
Center for Applied Scientific Computing, L-561
Lawrence Livermore National Laboratory
Livermore, CA 94551, U.S.A.

20 June 2001

Work performed under the auspices of the U.S. Department of Energy by the Lawrence Livermore National Laboratory under contract No. W-7405-Eng-48, and supported (formerly) by the DOE Office of Energy Research, Applied Mathematical Sciences Research Program.

ODEPACK is a collection of Fortran solvers for the initial value problem for ordinary differential equation systems. It consists of nine solvers, namely a basic solver called LSODE and eight variants of it -- LSODES, LSODA, LSODAR, LSODPK, LSODKR, LSODI, LSOIBT, and LSODIS. The collection is suitable for both stiff and nonstiff systems. It includes solvers for systems given in explicit form, dy/dt = f(t,y), and also solvers for systems given in linearly implicit form, A(t,y) dy/dt = g(t,y). Two of the solvers use general sparse matrix solvers for the linear systems that arise. Two others use iterative (preconditioned Krylov) methods instead of direct methods for these linear systems. The most recent addition is LSODIS, which solves implicit problems with general sparse treatment of all matrices involved.

The ODEPACK solvers are written in standard Fortran 77, with a few exceptions, and with minimal machine dependencies. There are separate double and single precision versions of ODEPACK. The actual solver names are those given above with a prefix of D- or S- for the double or single precision version, respectively, i.e. DLSODE/SLSODE, etc. Each solver consists of a main driver subroutine having the same name as the solver and some number of subordinate routines. For each solver, there is also a demonstration program, which solves one or two simple problems in a somewhat self-checking manner.

Recently, the ODEPACK solvers were upgraded to improve their portability in numerous ways. Among the improvements are (a) renaming of routines and Common blocks to distinguish double and single precision versions, (b) use of generic intrinsic function names, (c) elimination of the Block Data subprogram, (d) use of a portable routine to set the unit roundoff, and (e) passing of quoted strings to the error message handler. In addition, the prologue and internal comments were reformatted, and use mixed upper/lower case. Numerous minor corrections and improvements were also made.

The above upgrade operations were applied to LSODE earlier than they were to the rest of ODEPACK, and the two upgrades were done somewhat independently. As a result, some differences will be apparent in the source files of LSODE and the other solvers -- primarily in the formatting of the comment line prologue of the main driver routine. In Subroutines DLSODE/SLSODE and their subordinate routines, the prologue was written in "SLATEC format", while for the other solvers a more relaxed style was used. The differences are entirely cosmetic, however, and do not affect performance.

Documentation on the usage of each solver is provided in the initial block of comment lines in the source file, which (in most cases) includes a simple example. A demonstration program (in separate double/single precision versions) is also available.

What follows is a summary of the capabilities of ODEPACK, comments about usage documentation, and notes about installing the collection. For additional documentation on ODEPACK, see also the papers [1], [2] (for LSODE), and [3] (for LSODPK and LSODKR), and in the references cited there. (However, the document [2] does not reflect the

Odepack

Install / Use

README