Apache commons math 2.0

Parent package for common numerical analysis procedures, including root finding, function interpolation and integration. Note that the optimization (i.e. minimization and maximization) is a huge separate top package, despite it also operate on functions as defined by this top-level package.

Functions interfaces are intended to be implemented by user code to represent their domain problems. The algorithms provided by the library will then operate on these function to find their roots, or integrate them, or ... Functions can be multivariate or univariate, real vectorial or matrix valued, and they can be differentiable or not.

This package has been deprecated as of 2.0. It is replaced by the optimization.general package.

This package provides Genetic Algorithms components and implementations.

This package provides basic 3D geometry components.

This package provides classes to solve Ordinary Differential Equations problems.

This package solves Initial Value Problems of the form y'=f(t,y) with t0 and y(t0)=y0 known. The provided integrators compute an estimate of y(t) from t=t0 to t=t1.

All integrators provide dense output. This means that besides computing the state vector at discrete times, they also provide a cheap mean to get the state between the time steps. They do so through classes extending the {@link org.apache.commons.math.ode.sampling.StepInterpolator StepInterpolator} abstract class, which are made available to the user at the end of each step.

All integrators handle multiple discrete events detection based on switching functions. This means that the integrator can be driven by user specified discrete events. The steps are shortened as needed to ensure the events occur at step boundaries (even if the integrator is a fixed-step integrator). When the events are triggered, integration can be stopped (this is called a G-stop facility), the state vector can be changed, or integration can simply go on. The latter case is useful to handle discontinuities in the differential equations gracefully and get accurate dense output even close to the discontinuity.

The user should describe his problem in his own classes (UserProblem in the diagram below) which should implement the {@link org.apache.commons.math.ode.FirstOrderDifferentialEquations FirstOrderDifferentialEquations} interface. Then he should pass it to the integrator he prefers among all the classes that implement the {@link org.apache.commons.math.ode.FirstOrderIntegrator FirstOrderIntegrator} interface.

The solution of the integration problem is provided by two means. The first one is aimed towards simple use: the state vector at the end of the integration process is copied in the y array of the {@link org.apache.commons.math.ode.FirstOrderIntegrator#integrate FirstOrderIntegrator.integrate} method. The second one should be used when more in-depth information is needed throughout the integration process. The user can register an object implementing the {@link org.apache.commons.math.ode.sampling.StepHandler StepHandler} interface or a {@link org.apache.commons.math.ode.sampling.StepNormalizer StepNormalizer} object wrapping a user-specified object implementing the {@link org.apache.commons.math.ode.sampling.FixedStepHandler FixedStepHandler} interface into the integrator before calling the {@link org.apache.commons.math.ode.FirstOrderIntegrator#integrate FirstOrderIntegrator.integrate} method. The user object will be called appropriately during the integration process, allowing the user to process intermediate results. The default step handler does nothing.

{@link org.apache.commons.math.ode.ContinuousOutputModel ContinuousOutputModel} is a special-purpose step handler that is able to store all steps and to provide transparent access to any intermediate result once the integration is over. An important feature of this class is that it implements the Serializable interface. This means that a complete continuous model of the integrated function throughout the integration range can be serialized and reused later (if stored into a persistent medium like a filesystem or a database) or elsewhere (if sent to another application). Only the result of the integration is stored, there is no reference to the integrated problem by itself.

Other default implementations of the {@link org.apache.commons.math.ode.sampling.StepHandler StepHandler} interface are available for general needs ({@link org.apache.commons.math.ode.sampling.DummyStepHandler DummyStepHandler}, {@link org.apache.commons.math.ode.sampling.StepNormalizer StepNormalizer}) and custom implementations can be developed for specific needs. As an example, if an application is to be completely driven by the integration process, then most of the application code will be run inside a step handler specific to this application.

Some integrators (the simple ones) use fixed steps that are set at creation time. The more efficient integrators use variable steps that are handled internally in order to control the integration error with respect to a specified accuracy (these integrators extend the {@link org.apache.commons.math.ode.nonstiff.AdaptiveStepsizeIntegrator AdaptiveStepsizeIntegrator} abstract class). In this case, the step handler which is called after each successful step shows up the variable stepsize. The {@link org.apache.commons.math.ode.sampling.StepNormalizer StepNormalizer} class can be used to convert the variable stepsize into a fixed stepsize that can be handled by classes implementing the {@link org.apache.commons.math.ode.sampling.FixedStepHandler FixedStepHandler} interface. Adaptive stepsize integrators can automatically compute the initial stepsize by themselves, however the user can specify it if he prefers to retain full control over the integration or if the automatic guess is wrong.

Fixed Step Integrators
Name	Order
{@link org.apache.commons.math.ode.nonstiff.EulerIntegrator Euler}	1
{@link org.apache.commons.math.ode.nonstiff.MidpointIntegrator Midpoint}	2
{@link org.apache.commons.math.ode.nonstiff.ClassicalRungeKuttaIntegrator Classical Runge-Kutta}	4
{@link org.apache.commons.math.ode.nonstiff.GillIntegrator Gill}	4
{@link org.apache.commons.math.ode.nonstiff.ThreeEighthesIntegrator 3/8}	4

This package provides classes to handle discrete events occurring during Ordinary Differential Equations integration.

Discrete events detection is based on switching functions. The user provides a simple {@link org.apache.commons.math.ode.events.EventHandler#g g(t, y)} function depending on the current time and state. The integrator will monitor the value of the function throughout integration range and will trigger the event when its sign changes. The magnitude of the value is almost irrelevant, it should however be continuous (but not necessarily smooth) for the sake of root finding. The steps are shortened as needed to ensure the events occur at step boundaries (even if the integrator is a fixed-step integrator).

When an event is triggered, several different options are available:

• integration can be stopped (this is called a G-stop facility),
• the state vector or the derivatives can be changed,
• or integration can simply go on.

The first case, G-stop, is the most common one. A typical use case is when an ODE must be solved up to some target state is reached, with a known value of the state but an unknown occurrence time. As an example, if we want to monitor a chemical reaction up to some predefined concentration for the first substance, we can use the following switching function setting:

  public double g(double t, double[] y) {
    return y[0] - targetConcentration;
  }

  public int eventOccurred(double t, double[] y) {
    return STOP;
  }

The second case, change state vector or derivatives is encountered when dealing with discontinuous dynamical models. A typical case would be the motion of a spacecraft when thrusters are fired for orbital maneuvers. The acceleration is smooth as long as no maneuver are performed, depending only on gravity, drag, third body attraction, radiation pressure. Firing a thruster introduces a discontinuity that must be handled appropriately by the integrator. In such a case, we would use a switching function setting similar to this:

  public double g(double t, double[] y) {
    return (t - tManeuverStart) * (t - tManeuverStop);
  }

  public int eventOccurred(double t, double[] y) {
    return RESET_DERIVATIVES;
  }

The third case is useful mainly for monitoring purposes, a simple example is:

  public double g(double t, double[] y) {
    return y[0] - y[1];
  }

  public int eventOccurred(double t, double[] y) {
    logger.log("y0(t) and y1(t) curves cross at t = " + t);
    return CONTINUE;
  }

This package provides classes to solve non-stiff Ordinary Differential Equations problems.

This package provides classes to handle sampling steps during Ordinary Differential Equations integration.

In addition to computing the evolution of the state vector at some grid points, all ODE integrators also build up interpolation models of this evolution inside the last computed step. If users are interested in these interpolators, they can register a {@link org.apache.commons.math.ode.sampling.StepHandler StepHandler} instance using the {@link org.apache.commons.math.ode.FirstOrderIntegrator#addStepHandler addStepHandler} method which is supported by all integrators. The integrator will call this instance at the end of each accepted step and provide it the interpolator. The user can do whatever he wants with this interpolator, which computes both the state and its time-derivative. A typical use of step handler is to provide some output to monitor the integration process.

In a sense, this is a kind of Inversion Of Control: rather than having the master application driving the slave integrator by providing the target end value for the free variable, we get a master integrator scheduling the free variable evolution and calling the slave application callbacks that were registered at configuration time.

Since some integrators may use variable step size, the generic {@link org.apache.commons.math.ode.sampling.StepHandler StepHandler} interface can be called either at regular or irregular rate. This interface allows to navigate to any location within the last computed step, thanks to the provided {@link org.apache.commons.math.ode.sampling.StepInterpolator StepInterpolator} object. If regular output is desired (for example in order to write an ephemeris file), then the simpler {@link org.apache.commons.math.ode.sampling.FixedStepHandler FixedStepHandler} interface can be used. Objects implementing this interface should be wrapped within a {@link org.apache.commons.math.ode.sampling.StepNormalizer StepNormalizer} instance in order to be registered to the integrator.

This package provides common interfaces for the optimization algorithms provided in sub-packages. The main interfaces defines optimizers and convergence checkers. The functions that are optimized by the algorithms provided by this package and its sub-packages are a subset of the one defined in the analysis package, namely the real and vector valued functions. These functions are called objective function here. When the goal is to minimize, the functions are often called cost function, this name is not used in this package.

Optimizers are the algorithms that will either minimize or maximize, the objective function by changing its input variables set until an optimal set is found. There are only four interfaces defining the common behavior of optimizers, one for each supported type of objective function:

• {@link org.apache.commons.math.optimization.UnivariateRealOptimizer UnivariateRealOptimizer} for {@link org.apache.commons.math.analysis.UnivariateRealFunction univariate real functions}
• {@link org.apache.commons.math.optimization.MultivariateRealOptimizer MultivariateRealOptimizer} for {@link org.apache.commons.math.analysis.MultivariateRealFunction multivariate real functions}
• {@link org.apache.commons.math.optimization.DifferentiableMultivariateRealOptimizer DifferentiableMultivariateRealOptimizer} for {@link org.apache.commons.math.analysis.DifferentiableMultivariateRealFunction differentiable multivariate real functions}
• {@link org.apache.commons.math.optimization.DifferentiableMultivariateVectorialOptimizer DifferentiableMultivariateVectorialOptimizer} for {@link org.apache.commons.math.analysis.DifferentiableMultivariateVectorialFunction differentiable multivariate vectorial functions}

Despite there are only four types of supported optimizers, it is possible to optimize a transform a {@link org.apache.commons.math.analysis.MultivariateVectorialFunction non-differentiable multivariate vectorial function} by converting it to a {@link org.apache.commons.math.analysis.MultivariateRealFunction non-differentiable multivariate real function} thanks to the {@link org.apache.commons.math.optimization.LeastSquaresConverter LeastSquaresConverter} helper class. The transformed function can be optimized using any implementation of the {@link org.apache.commons.math.optimization.MultivariateRealOptimizer MultivariateRealOptimizer} interface.

For each of the four types of supported optimizers, there is a special implementation which wraps a classical optimizer in order to add it a multi-start feature. This feature call the underlying optimizer several times in sequence with different starting points and returns the best optimum found or all optima if desired. This is a classical way to prevent being trapped into a local extremum when looking for a global one.

This package provides optimization algorithms that don't require derivatives.

Curve fitting is a special case of a least squares problem were the parameters are the coefficients of a function f whose graph y=f(x) should pass through sample points, and were the objective function is the squared sum of residuals f(xi)-yi for observed points (x_i, y_i).

UnivariateStatistic API Usage Examples:

UnivariateStatistic:

StorelessUnivariateStatistic: