Proposal for nabla Package

(0) Rationale

Scientific computing involves sophisticated models driven by numerous equations. It is often required to compute both the values of these models, but also their sensitivity to input parameters. This sensitivity is related to their derivative. Computing the derivative of a function is called differentiation, there are two ways to do this.

Differentiation can be done numerically by finite differences schemes, but this has limitations:

• result is only an approximation, even if the base function is perfectly known
• computation cost overhead can be large if more than 2 points are used for finite differences
• there is always a compromise between accuracy and computation cost
• step size choice is always problem-dependent
• step size depends on parameter units (micrometers or kilometers, nanoseconds or years ...)
• step size for multivariate methods involving parameters of different kinds and orders of magnitude is a nightmare (distances in meters, angles in radians ...)
• it doesn't work near boundaries of function definition domains

Differentiation can be done symbolically, but this has drawbacks:

• only the simplest cases can be handled manually without errors
• automatic symbolic computation packages that can handle more complex equations and generate code are expensive and not widely available
• they use their own domain-specific (and often package-specific) language as input, requiring manual creation and manual edition
• they generate source code that cannot be maintained and has a fixed form which must be manually integrated within the application
• they are never fully integrated in a development workflow, there are many manual steps, both for using them and for integrating the generated code in the application
• they handle only fully defined and standalone functions one at a time
• using such packages is unrealistic when hundred of models and equations are to be used, there is too much manual overhead
• they often generate only Fortran or C source code
• programming languages control structures like loops and conditionals are not supported as they do not belong to pure mathematics
• they cannot do roundtrip engineering
• they can be used only if the team needing the derivative can ask for it to the team developing the models, not at all if the latter publish its work or libraries without knowledge of who will use it

The nabla package (∇) is intended to be a symbolic derivator for Java scientific applications that is completely automated and acts directly on the bytecode representation of compiled functions to remove all the drawbacks of symbolic differentiation.

(1) Scope of the Package

The Nabla project shall create and maintain a tool providing automatic differentiation for bytecode functions. Here are the specifications of the package:

• a public API must be available to perform differentiation at runtime
• differentiation must be exact symbolic differentiation
• the main (almost unique) function of the public API must have a form similar to
  derivative = nablaDifferentiator.differentiate(differentiable)
  where differentiable is an instance of some class providing a univariate function double f(double t) and derivative implements a Nabla-defined interface computing both the value of the function f and its derivative with respect to t
• all standard mathematical functions provided by the Math and StrictMath classes must be supported
• all arithmetic operators applying to double primitive types must be supported (including remainder)
• functions involving loops and conditionals must be supported
• number of classes, functions, or parameters involved must be unlimited
• generated bytecode must be cached
• for functions calling native code, a fallback using finite differences must be available, this may use a different API (i.e. it is possible to add a step size specification if needed)
• functions calling other bytecode functions, either in the same class or in another class from same or another package shall be supported
• recursive functions shall be supported
• after a call to the differentiate method specified above, the derivative instance should remain tightly linked to the differentiable instance in such a way that any subsequent change to the differentiable instance shall be reflected by the derivative instance
• standalone utilities, maven or IDE plugins may be provided to generate derivatives at compile time shall be provided

(1.5) Interaction With Other Packages

Nabla should rely on standard Java (version To be Defined) and on an existing bytecode engineering library at runtime. For development, it utilizes the JUnit unit testing framework, either ant or maven 2 and general quality checking tools (coding style, test coverage, classical error patterns monitoring).

No external configuration files are utilized.

(2) Initial Source of the Package

The initial codebase will be imported from an unpublished proof of concept developed by the proposal creator. This codebase supports basic differentiation only.

The proposed package name for the new component is org.apache.commons.nabla.

(3) Required Commons Resources

• Subversion Repository - New directory nabla in the commons subversion repository.
• Mailing List - Discussions will take place on the general dev@commons.apache.org mailing list. To help list subscribers identify messages of interest, it is suggested that the message subject of messages about this component be prefixed with [nabla].
• Jira - New component "nabla" under the "Commons" product category, with appropriate version identifiers as needed.

(4) Initial Committers

The initial committers on the nabla component shall be:

• Luc Maisonobe

• Phil Steitz