emmy.numerical.ode — org.mentat/emmy 0.31.0

ODE solvers for working with initial value problems.

evolve clj/s

(evolve state-derivative & state-derivative-args)

evolve takes a state derivative function constructor and its arguments, and returns an integrator via make-integrator.

In particular, the returned function accepts a callback function which will be invoked at intermediate grid points of the integration.

integrate-state-derivative clj/s

(integrate-state-derivative state-derivative
                            state-derivative-args
                            initial-state
                            t1
                            dt)

A wrapper for evolve, which is more convenient when you just want a vector of (time, state) pairs over the integration interval instead of having to deal with a callback. Integrates the supplied state derivative (and its argument package) from [0 to t1] in steps of size dt

make-integrator clj/s

(make-integrator state-derivative derivative-args)

make-integrator takes a state derivative function (which in this system is assumed to be a map from a structure to a structure of the same shape, as differentiating a function does not change its shape), and returns an integrator, which is a function of several arguments:

• the initial state
• an intermediate-state observation function
• the step size desired
• the final time to seek, and
• an error tolerance.

If the observe function is not nil, it will be invoked with the time as first argument and integrated state as the second, at each intermediate step.

state-advancer clj/s

(state-advancer state-derivative & state-derivative-args)

state-advancer takes a state derivative function constructor followed by the arguments to construct it with. The state derivative function is constructed and an integrator is produced which takes:

• initial state
• target time

as arguments. Optionally, supply an options map with these optional fields:

:compile?: If true, the ODE solver will compile your state function.

:epsilon: The maximum error tolerance allowed by the ODE solver, both relative and absolute.

Returns the final state.

The state derivative is expected to map a structure to a structure of the same shape, and is required to have the time parameter as the first element.

stream-integrator clj/s≠

clj

(stream-integrator f' x0 y0 {:keys [epsilon] :or {epsilon default-epsilon}})

cljs

(stream-integrator f'
                   x0
                   y0
                   {:keys [epsilon js?]
                    :or {epsilon default-epsilon js? false}})

Produces a function, monotonic in its single numeric argument, that represents the integral of the function f' given the initial data $y_0 = f(x_0)$ and an options dictionary (presently containing the tolerance for error $\epsilon$, but eventually also selecting from a menu of integration techniques).

This is done by creating an adaptive step-size ODE solver, and advancing its steps as needed to supply function values. (This architecture accounts for why the arguments to f must be presented in order). Old solution segments are discarded. The goal of this approach is to avoid the requirement of supplying an upper limit to the integration. At the cost of requiring monotonic arguments to f, the integrated function can essentially be used forever without accumulating unbounded state.

The function f' should have the signature [x y y'], where y' is a primitive double array, which the function should fill in based on the values x and y.) Both y and y' will be primitive arrays of type double, the same length as that of y0. Both arrays are owned by the integrator. In particular, y should never be modified, and neither array should be modified or expected to persist after the return of f'. This approach has observable memory and performance impacts.

The return value of the integrating function, however, is newly allocated and belongs to the caller.

The integrating function may be called with no arguments to shut down the integration, allowing for the final reclamation of its resources.

When the ODE solver is provided by Java, it may be necessary to use an auxiliary thread to enable this style of flow control. If JavaScript, we expect the solver to provide a generator of solution segments.