static code analysis:deepcode:ai

Summary

There is no need to reinvent the wheel when it comes to ODE solvers.

JavaOdeInt provides Java bindings to a set of widely respected Fortran ODE packages. These are the same packages powering Python's numpy library or R's deSolve.

JavaOdeInt 's aim is to provide the basics from which a fully fleshed out ode solver can be constructed.

Between the Java interface and the Fortran packages sits a very thin C-layer. The purpose of C interface is two-fold: To provide bridj with a header file from which it can generate the Java classes and to provide a very basic interface to the Fortran routines.

Interfaces

Basic Interface

The name of the basic interface is that of the encapsulated Fortran function followed by _basic, e.g. lsoda_basic. It's purpose is to get up and running with a basic set of defaults.

The basic C interface requires a callback function, the dimensionality of the ode system, the initial conditions and the time interval, plus any additional parameters. The results are written to a user provided stack.

The C function executes a loop over the Fortran function and writes the results to the user supplied stack. It may also change some of the integration parameters. For example if it detects that the integration requires a larger number of steps that parameter is increased.

Full Interface

Using the full Fortran interface is also possible. This exposes all the capabilities of the Fortran code.

Each Fortran function has an extensive preamble describing its use. This was extracted from the Fortran package and put in the txt subdirectory. It is strongly recommended to consult this.

bridj

Regardless of the interface you need to use bridj for memory allocation and pointer management.

Examples

Both the C interface and the Java interface come with a set of tests. The tests include examples of the use of the basic and full interface.

Additional examples can be found here

Building

Prebuilt

TBA

Using maven

Mac OSX

cd jodeint
mvn clean package

Linux

cd jodeint 
export LD_LIBRARY_PATH=`pwd`/src/main/resources/lib/linux_x64/:$LD_LIBRARY_PATH
mvn clean package

Dependencies

• maven of version 3.1 or later

• gfortran needs to be installed in order to build the source code

• bridj is used to generate the java interfaces. It's found in pom.xml in the jodeint directory.

• [os-maven-plugin] (https://github.com/trustin/os-maven-plugin) The maven plugin used to determine the version of the operating system requires a maven version at least version 3.1

Directory structure

• fodeint : The Fortran modules

  Each subdirectory corresponds to one of the Fortran packages listed below and contains the Fortran source code. Each package directory has two subdirectories. The src subdirectory contains the Fortran source code and Makefile. The txt subdirectory contains the preamble of the Fortran source code. It also contains any available auxiliary code or driver scripts.

• codeint : The glue

  This directory contains the C code interface. The name of each subdirectory is the name of the fortran package it interfaces to prefixed by a c. So the directory named codepack contains the c interface to odepack Fortran package.

  Each sub directory has two more directories : src and include. src contains the source code, internal headers and makefile. include contains the header used by bridj to generate the Java interface classes.

• jodeint : The Java interface

This directory contains the maven pom.xml and the Java code for the tests. The bridj generator will create the code for the Java bindings on the fly. These are found in the src path and can be inspected. You are not expected to edit these files in any way. The target directory contains files generated by the maven build process.

• config : Makefile configuration

Contains the main make files used by the Fortran and C code.

• data : Reference data for unit tests

Contains the reference data for the Java regression tests.

• util : Utilities

Contains various utilities.

• target : Fortran and C build artifects

This will contain the Fortran and C object and library files, as well as the C regression test executables.

Build process

The main build script is Build.sh which can be found in ./src/scripts in the jodeint folder.

The build script executes the makefile for each of the Fortran and C code packages, copies the headers and libraries to locations maven knows about, and then uses maven to run the bridj generator on each of the C interface header files. It does this by creating a configuration script for each package and hard linking bridj's configuration script to each one of these library specific ones.

Trouble-Shooting Build Issues

If the maven build fails, the following steps may be helpful in figuring out the isssue :

1. Make sure you have met the dependencies. gfortran is obviously crucial.
2. On Linux, make sure the LD_LIBRARY_PATH is set.
3. Run mvn clean to remove all clutter.
4. Build a single Fortran package (say odepack) and verify that you have a library under target.
5. Build its C interface (say codepack) and verify that you have its library.
6. Build one of the C unit tests (say lsoda_simple_pendulum) and see if it run successfully.
7. If everything under steps 4-6 is successful execute mvn package. At this stage inspect the generated java classes.

Fortran libraries covered

• odepack

  odepack is a collection of Fortran initial value problem solvers for systems of ordinary differential equations for both stiff and nonstiff problems. The fortran package has nine solvers but only the following four double precision routines are available :

  • dlsoda : Switches automatically between nonstiff and stiff solvers depending on the behavior of the problem.

  • dlsodar : Like lsoda, but includes root finding.

  • dlsode : The user can select to run stiff or non-stiff solvers.

  • dlsodes : Like lsode, but assumes that the Jacobian is sparse.

• dvode
• zvode

These are two initial value ODE solvers for a set of first order ode's for stiff and nonstiff problems. dvode is double precision real and zvode is double precision complex.

• quadpack

QUADPACK is a famous set of Fortran 77 routines dealing with integration of functions of one variable

* DQAGPE computes a definite integral.    
* DQAGSE estimates the integral of a function.
* DQAGIE estimates an integral over a semi-infinite or infinite interval.
* DQAWCE computes a Cauchy principal value.
* DQAWFE computes Fourier integrals.
* DQAWOE computes the integrals of oscillatory integrands.
* DQAWSE estimates integrals with algebraico-logarithmic endpoint singularities.

• radau5

  Numerical solution of a stiff (or differential algebraic) system of first order ordinary differential equations

                 m*y'=f(x,y).
  

  The system can be (linearly) implicit (mass-matrix != Identity Matrix) or explicit (m = I). The method used is an implicit runge-kutta method of order 5 with step size control and continuous output.

• dopri5

  Numerical solution of a system of first order ordinary differential equations y'=f(x,y). This is an explicit runge-kutta method of order (4)5 due to Dormand & Prince (with step-size control and dense output).

• dop853

Numerical solution of a system of first order ordinary differential equations y'=f(x,y). This is an explicit runge-kutta method of order 8(5,3) due to Dormand & Prince (with step-size control and dense output)

• gnicodes

• GNI_IRK2

  Solves second order ordinary differential equations of the form

                  q'' = f(x,q)
  

based on the symplectic and symmetric Gauss (irk) methods described in sections ii.1, viii.6 of the book:

  E. hairer, C. Lubich, G. Wanner, Geometric Numerical Integration,
     Structure-Preserving Algorithms for ODEs.
     Springer series in comput. math. 31, springer 2002.

• GNI_LMM2

  Solves second order ordinary differential equations of the form

                  q'' = f(x,q)
  

based on symmetric linear multistep methods described in chapter XIV of the book:

 E. hairer, C. Lubich, G. Wanner, Geometric Numerical Integration,
     Structure-Preserving Algorithms for ODEs.
     Springer series in comput. math. 31, springer 2002.

• rkf45

  A Fehlberg fourth-fifth order Runge-Kutta method. rkf45 is primarily designed to solve non-stiff and mildly stiff differential equations when derivative evaluations are inexpensive. rkf45 should generally not be used when the user is demanding high accuracy.

Copyright

https://opensource.org/licenses/BSD-3-Clause

Copyright (c) 2016, JodeInt developers All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BELIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE