Engee documentation

DDE Problems

Defines a delay differential equation (DDE) problem. Documentation Page: https://docs.sciml.ai/DiffEqDocs/stable/types/dde_types/

Mathematical Specification of a DDE Problem

To define a DDE Problem, you simply need to give the function , the initial condition at time point , and the history function which together define a DDE:

should be specified as f(u, h, p, t) (or in-place as f(du, u, h, p, t)), should be an AbstractArray (or number) whose geometry matches the desired geometry of u, and should be specified as described below. The history function h is accessed for all delayed values. Note that we are not limited to numbers or vectors for ; one is allowed to provide as arbitrary matrices / higher dimension tensors as well.

Functional Forms of the History Function

The history function h can be called in the following ways:

  • h(p, t): out-of-place calculation

  • h(out, p, t): in-place calculation

  • h(p, t, deriv::Type{Val{i}}): out-of-place calculation of the ith derivative

  • h(out, p, t, deriv::Type{Val{i}}): in-place calculation of the ith derivative

  • h(args...; idxs): calculation of h(args...) for indices idxs

Note that a dispatch for the supplied history function of matching form is required for whichever function forms are used in the user derivative function f.

Declaring Lags

Lags are declared separately from their use. One can use any lag by simply using the interpolant of h at that point. However, one should use caution in order to achieve the best accuracy. When lags are declared, the solvers can be more efficient and accurate, and this is thus recommended.

Neutral and Retarded Delay Differential Equations

Note that the history function specification can be used to specify general retarded arguments, i.e. h(p,α(u,t)). Neutral delay differential equations can be specified by using the deriv value in the history interpolation. For example, h(p,t-τ, Val{1}) returns the first derivative of the history values at time t-τ.

Note that algebraic equations can be specified by using a singular mass matrix.

Problem Type

Constructors

DDEProblem(f[, u0], h, tspan[, p]; <keyword arguments>)
DDEProblem{isinplace,specialize}(f[, u0], h, tspan[, p]; <keyword arguments>)

isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred. specialize optionally controls the specialization level. See the specialization levels section of the SciMLBase documentation for more details. The default is AutoSpecialize.

For more details on the in-place and specialization controls, see the ODEFunction documentation.

Parameters are optional, and if not given, then a NullParameters() singleton will be used which will throw nice errors if you try to index non-existent parameters. Any extra keyword arguments are passed on to the solvers. For example, if you set a callback in the problem, then that callback will be added in every solve call.

For specifying Jacobians and mass matrices, see the DiffEqFunctions page.

Arguments

  • f: The function in the DDE.

  • u0: The initial condition. Defaults to the value h(p, first(tspan)) of the history function evaluated at the initial time point.

  • h: The history function for the DDE before t0.

  • tspan: The timespan for the problem.

  • p: The parameters with which function f is called. Defaults to NullParameters.

  • constant_lags: A collection of constant lags used by the history function h. Defaults to ().

  • dependent_lags A tuple of functions (u, p, t) -> lag for the state-dependent lags used by the history function h. Defaults to ().

  • neutral: If the DDE is neutral, i.e., if delays appear in derivative terms.

  • order_discontinuity_t0: The order of the discontinuity at the initial time point. Defaults to 0 if an initial condition u0 is provided. Otherwise, it is forced to be greater or equal than 1.

  • kwargs: The keyword arguments passed onto the solves.

Dynamical Delay Differential Equations

Much like Dynamical ODEs, a Dynamical DDE is a Partitioned DDE of the form:

Constructors

DynamicalDDEProblem(f1, f2[, v0, u0], h, tspan[, p]; <keyword arguments>)
DynamicalDDEProblem{isinplace}(f1, f2[, v0, u0], h, tspan[, p]; <keyword arguments>)

Parameter isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred.

Arguments

  • f: The function in the DDE.

  • v0 and u0: The initial condition. Defaults to the values h(p, first(tspan))... of the history function evaluated at the initial time point.

  • h: The history function for the DDE before t0. Must return an object with the indices 1 and 2, with the values of v and u respectively.

  • tspan: The timespan for the problem.

  • p: The parameters with which function f is called. Defaults to NullParameters.

  • constant_lags: A collection of constant lags used by the history function h. Defaults to ().

  • dependent_lags A tuple of functions (v, u, p, t) -> lag for the state-dependent lags used by the history function h. Defaults to ().

  • neutral: If the DDE is neutral, i.e., if delays appear in derivative terms.

  • order_discontinuity_t0: The order of the discontinuity at the initial time point. Defaults to 0 if an initial condition u0 is provided. Otherwise, it is forced to be greater or equal than 1.

  • kwargs: The keyword arguments passed onto the solves.

For dynamical and second order DDEs, the history function will return an object with the indices 1 and 2 defined, where h(p, t_prev)[1] is the value of and h(p, t_prev)[2] is the value of (this is for consistency with the ordering of the initial conditions in the constructor). The supplied history function must also return such a 2-index object, which can be accomplished with a tuple (v,u) or vector [v,u].

2nd Order Delay Differential Equations

To define a 2nd Order DDE Problem, you simply need to give the function and the initial condition which define an DDE:

f should be specified as f(du,u,p,t) (or in-place as f(ddu,du,u,p,t)), and u₀ should be an AbstractArray (or number) whose geometry matches the desired geometry of u. Note that we are not limited to numbers or vectors for u₀; one is allowed to provide u₀ as arbitrary matrices / higher dimension tensors as well.

From this form, a dynamical ODE:

Constructors

SecondOrderDDEProblem(f, [, du0, u0], h, tspan[, p]; <keyword arguments>)
SecondOrderDDEProblem{isinplace}(f, [, du0, u0], h, tspan[, p]; <keyword arguments>)

Parameter isinplace optionally sets whether the function is inplace or not. This is determined automatically, but not inferred.

Arguments

  • f: The function in the DDE.

  • du0 and u0: The initial condition. Defaults to the values h(p, first(tspan))... of the history function evaluated at the initial time point.

  • h: The history function for the DDE before t0. Must return an object with the indices 1 and 2, with the values of v and u respectively.

  • tspan: The timespan for the problem.

  • p: The parameters with which function f is called. Defaults to NullParameters.

  • constant_lags: A collection of constant lags used by the history function h. Defaults to ().

  • dependent_lags A tuple of functions (v, u, p, t) -> lag for the state-dependent lags used by the history function h. Defaults to ().

  • neutral: If the DDE is neutral, i.e., if delays appear in derivative terms.

  • order_discontinuity_t0: The order of the discontinuity at the initial time point. Defaults to 0 if an initial condition u0 is provided. Otherwise, it is forced to be greater or equal than 1.

  • kwargs: The keyword arguments passed onto the solves.

As above, the history function will return an object with indices 1 and 2, with the values of du and u respectively. The supplied history function must also match this return type, e.g. by returning a 2-element tuple or vector.

Example Problems

Example problems can be found in DiffEqProblemLibrary.jl.

To use a sample problem, such as prob_dde_constant_1delay_ip, you can do something like:

#] add DDEProblemLibrary
using DDEProblemLibrary
prob = DDEProblemLibrary.prob_dde_constant_1delay_ip
sol = solve(prob)
DDEFunction{iip,F,TMM,Ta,Tt,TJ,JVP,VJP,JP,SP,TW,TWt,TPJ,S.S2,S3,O,TCV} <: AbstractDDEFunction{iip,specialize}

A representation of a DDE function f, defined by:

and all of its related functions, such as the Jacobian of f, its gradient with respect to time, and more. For all cases, u0 is the initial condition, p are the parameters, and t is the independent variable.

Constructor

DDEFunction{iip,specialize}(f;
                 mass_matrix = __has_mass_matrix(f) ? f.mass_matrix : I,
                 analytic = __has_analytic(f) ? f.analytic : nothing,
                 tgrad= __has_tgrad(f) ? f.tgrad : nothing,
                 jac = __has_jac(f) ? f.jac : nothing,
                 jvp = __has_jvp(f) ? f.jvp : nothing,
                 vjp = __has_vjp(f) ? f.vjp : nothing,
                 jac_prototype = __has_jac_prototype(f) ? f.jac_prototype : nothing,
                 sparsity = __has_sparsity(f) ? f.sparsity : jac_prototype,
                 paramjac = __has_paramjac(f) ? f.paramjac : nothing,
                 syms = __has_syms(f) ? f.syms : nothing,
                 indepsym= __has_indepsym(f) ? f.indepsym : nothing,
                 paramsyms = __has_paramsyms(f) ? f.paramsyms : nothing,
                 colorvec = __has_colorvec(f) ? f.colorvec : nothing,
                 sys = __has_sys(f) ? f.sys : nothing)

Note that only the function f itself is required. This function should be given as f!(du,u,h,p,t) or du = f(u,h,p,t). See the section on iip for more details on in-place vs out-of-place handling. The history function h acts as an interpolator over time, i.e. h(t) with options matching the solution interface, i.e. h(t; save_idxs = 2).

All of the remaining functions are optional for improving or accelerating the usage of f. These include:

  • mass_matrix: the mass matrix M represented in the ODE function. Can be used to determine that the equation is actually a differential-algebraic equation (DAE) if M is singular. Note that in this case special solvers are required, see the DAE solver page for more details: https://docs.sciml.ai/DiffEqDocs/stable/solvers/dae_solve/. Must be an AbstractArray or an AbstractSciMLOperator.

  • analytic(u0,p,t): used to pass an analytical solution function for the analytical solution of the ODE. Generally only used for testing and development of the solvers.

  • tgrad(dT,u,h,p,t) or dT=tgrad(u,p,t): returns

  • jac(J,u,h,p,t) or J=jac(u,p,t): returns

  • jvp(Jv,v,h,u,p,t) or Jv=jvp(v,u,p,t): returns the directional derivative$\frac{df}{du} v$

  • vjp(Jv,v,h,u,p,t) or Jv=vjp(v,u,p,t): returns the adjoint derivative$\frac{df}{du}^\ast v$

  • jac_prototype: a prototype matrix matching the type that matches the Jacobian. For example, if the Jacobian is tridiagonal, then an appropriately sized Tridiagonal matrix can be used as the prototype and integrators will specialize on this structure where possible. Non-structured sparsity patterns should use a SparseMatrixCSC with a correct sparsity pattern for the Jacobian. The default is nothing, which means a dense Jacobian.

  • paramjac(pJ,h,u,p,t): returns the parameter Jacobian .

  • syms: the symbol names for the elements of the equation. This should match u0 in size. For example, if u0 = [0.0,1.0] and syms = [:x, :y], this will apply a canonical naming to the values, allowing sol[:x] in the solution and automatically naming values in plots.

  • indepsym: the canonical naming for the independent variable. Defaults to nothing, which internally uses t as the representation in any plots.

  • paramsyms: the symbol names for the parameters of the equation. This should match p in size. For example, if p = [0.0, 1.0] and paramsyms = [:a, :b], this will apply a canonical naming to the values, allowing sol[:a] in the solution.

  • colorvec: a color vector according to the SparseDiffTools.jl definition for the sparsity pattern of the jac_prototype. This specializes the Jacobian construction when using finite differences and automatic differentiation to be computed in an accelerated manner based on the sparsity pattern. Defaults to nothing, which means a color vector will be internally computed on demand when required. The cost of this operation is highly dependent on the sparsity pattern.

iip: In-Place vs Out-Of-Place

For more details on this argument, see the ODEFunction documentation.

specialize: Controlling Compilation and Specialization

For more details on this argument, see the ODEFunction documentation.

Fields

The fields of the DDEFunction type directly match the names of the inputs.

Solution Type

DDEProblem solutions return an ODESolution. For more information, see the ODE problem definition page for the ODESolution docstring.

Example Problems

Example problems can be found in DiffEqProblemLibrary.jl.

To use a sample problem, such as prob_ode_linear, you can do something like:

#] add DiffEqProblemLibrary
using DiffEqProblemLibrary.ODEProblemLibrary
# load problems
ODEProblemLibrary.importodeproblems()
prob = ODEProblemLibrary.prob_ode_linear
sol = solve(prob)

DDEs with 1 constant delay

prob_dde_constant_1delay_ip

Delay differential equation

for ] with history function if and .

Solution

The analytical solution for ] can be obtained by the method of steps and is provided in this implementation.

prob_dde_constant_1delay_oop

Same delay differential equation as prob_dde_constant_1delay_ip, but purposefully implemented with an out-of-place function.

prob_dde_constant_1delay_scalar

Same delay differential equation as prob_dde_constant_1delay_ip, but purposefully implemented with a scalar function.

prob_dde_constant_1delay_long_ip

Delay differential equation

for ] with history function if and .

prob_dde_constant_1delay_long_oop

Same delay differential equation as prob_dde_constant_1delay_long_ip, but purposefully implemented with an out-of-place function.

prob_dde_constant_1delay_long_scalar

Same delay differential equation as prob_dde_constant_1delay_long_ip, but purposefully implemented with a scalar function.

DDEs with 2 constant delays

prob_dde_constant_2delays_ip

Delay differential equation

for ] with history function if and .

Solution

The analytical solution for ] can be obtained by the method of steps and is provided in this implementation.

prob_dde_constant_2delays_oop

Same delay differential equation as prob_dde_constant_2delays_ip, but purposefully implemented with an out-of-place function.

prob_dde_constant_2delays_scalar

Same delay differential equation as prob_dde_constant_2delays_ip, but purposefully implemented with a scalar function.

prob_dde_constant_2delays_long_ip

Delay differential equation

for ] with history function if and .

prob_dde_constant_2delays_long_oop

Same delay differential equation as prob_dde_constant_2delays_long_ip, but purposefully implemented with an out-of-place function.

prob_dde_constant_2delays_long_scalar

Same delay differential equation as prob_dde_constant_2delays_long_ip, but purposefully implemented with a scalar function.

DDETest Problems

Some details:

# DDEs with time dependent delays
prob_dde_DDETST_A1, prob_dde_DDETST_A2,
# DDEs with vanishing time dependent delays
prob_dde_DDETST_B1, prob_dde_DDETST_B2,
# DDEs with state dependent delays
prob_dde_DDETST_C1, prob_dde_DDETST_C2, prob_dde_DDETST_C3, prob_dde_DDETST_C4,
# DDEs with vanishing state dependent delays
prob_dde_DDETST_D1, prob_dde_DDETST_D2,
# neutral DDEs with time dependent delays
prob_dde_DDETST_E1, prob_dde_DDETST_E2,
# neutral DDEs with vanishing time dependent delays
prob_dde_DDETST_F1, prob_dde_DDETST_F2, prob_dde_DDETST_F3, prob_dde_DDETST_F4, prob_dde_DDETST_F5,
# neutral DDEs with state dependent delays
prob_dde_DDETST_G1, prob_dde_DDETST_G2,
# neutral DDEs with vanishing state dependent delays
prob_dde_DDETST_H1, prob_dde_DDETST_H2, prob_dde_DDETST_H3, prob_dde_DDETST_H4
prob_dde_DDETST_A1

Delay differential equation model of blood production, given by

for ] and history function for .

References

Mackey, M. C. and Glass, L. (1977). Oscillation and chaos in physiological control systems, Science (197), pp. 287-289.

prob_dde_DDETST_A2

Delay differential equation model of chronic granulocytic leukemia, given by

for ] and history function

for .

References

Wheldon, T., Kirk, J. and Finlay, H. (1974). Cyclical granulopoiesis in chronic granulocytic leukemia: A simulation study., Blood (43), pp. 379-387.

prob_dde_DDETST_B1

Delay differential equation

for ] with history function for ].

Solution

The analytical solution for ] is

References

Neves, K. W. (1975). Automatic integration of functional differential equations: An approach, ACM Trans. Math. Soft. (1), pp. 357-368.

prob_dde_DDETST_B2

Delay differential equation

for ] with history function .

Solution

The analytical solution for ] is

References

Neves, K. W. and Thompson, S. (1992). Solution of systems of functional differential equations with state dependent delays, Technical Report TR-92-009, Computer Science, Radford University.

prob_dde_DDETST_C1

Delay differential equation

for ] with history function for .

References

Paul, C. A. H. (1994). A test set of functional differential equations, Technical Report 249, The Department of Mathematics, The University of Manchester, Manchester, England.

prob_dde_DDETST_C2

Delay differential equation

₂

for ] with history function

for .

References

Paul, C. A. H. (1994). A test set of functional differential equations, Technical Report 249, The Department of Mathematics, The University of Manchester, Manchester, England.

prob_dde_DDETST_C3

Delay differential equation model of hematopoiesis, given by

for ] with history function , , and

where , , , , , , , , and .

References

Mahaffy, J. M., Belair, J. and Mackey, M. C. (1996). Hematopoietic model with moving boundary condition and state dependent delay, Private communication.

prob_dde_DDETST_C4

Delay differential equation model of hematopoiesis, given by the same delay differential equation as prob_dde_DDETST_C3

for ] with history function , , and for , where , , , , , , , , and .

References

Mahaffy, J. M., Belair, J. and Mackey, M. C. (1996). Hematopoietic model with moving boundary condition and state dependent delay, Private communication.

prob_dde_DDETST_D1

Delay differential equation

for ] with history function

for ].

Solution

The analytical solution for ] is

References

Neves, K. W. (1975). Automatic integration of functional differential equations: An approach, ACM Trans. Math. Soft. (1), pp. 357-368.

prob_dde_DDETST_D2

Delay differential equation model of antigen antibody dynamics with fading memory, given by

for ] with history function

for , where , , , and .

References

Gatica, J. and Waltman, P. (1982). A threshold model of antigen antibody dynamics with fading memory, in Lakshmikantham (ed.), Nonlinear phenomena in mathematical science, Academic Press, New York, pp. 425-439.

prob_dde_DDETST_E1

Delay differential equation model of a food-limited population, given by

for ] with history function for , where and .

References

Kuang, Y. and Feldstein, A. (1991). Boundedness of solutions of a nonlinear nonautonomous neutral delay equation, J. Math. Anal. Appl. (156), pp. 293-304.

prob_dde_DDETST_E2

Delay differential equation model of a logistic Gauss-type predator-prey system, given by

for ] with history function

for , where , , and .

References

Kuang, Y. (1991). On neutral delay logistics Gauss-type predator-prey systems, Dyn. Stab. Systems (6), pp. 173-189.

prob_dde_DDETST_F1

Delay differential equation

for ] with history function and .

Solution

The analytical solution for ] is

References

Jackiewicz, Z. (1981). One step methods for the numerical solution of Volterra functional differential equations of neutral type, Applicable Anal. (12), pp. 1-11.

prob_dde_DDETST_F2

Delay differential equation

for ] with history function and for .

Solution

The analytical solution for ] is

if ], where

and .

References

Neves, K. W. and Thompson, S. (1992). Solution of systems of functional differential equations with state dependent delays, Technical Report TR-92-009, Computer Science, Radford University.

prob_dde_DDETST_F3

Delay differential equation

for ] with history function and , where and .

Solution

The analytical solution for ] is

prob_dde_DDETST_F4

Same delay differential equation as prob_dde_DDETST_F3 with .

prob_dde_DDETST_F5

Same delay differential equation as prob_dde_DDETST_F3 with .

prob_dde_DDETST_G1

Delay differential equation

for ] with history function for and for .

Solution

The analytical solution for ] is

References

El’sgol’ts, L. E. and Norkin, S. B. (1973). Introduction to the Theory and Application of Differential Equations with Deviating Arguments, Academic Press, New York, p. 44.

prob_dde_DDETST_G2

Delay differential equation

for ] with history function for and for .

Solution

The analytical solution for ] is

El’sgol’ts, L. E. and Norkin, S. B. (1973). Introduction to the Theory and Application of Differential Equations with Deviating Arguments, Academic Press, New York, pp. 44-45.

prob_dde_DDETST_H1

Delay differential equation

for ] with history function and .

Solution

The analytical solution for ] is

References

Castleton, R. N. and Grimm, L. J. (1973). A first order method for differential equations of neutral type, Math. Comput. (27), pp. 571-577.

prob_dde_DDETST_H2

Delay differential equation

for ] with history function and , where .

Solution

The analytical solution for ] is

References

Hayashi, H. (1996). Numerical solution of retarded and neutral delay differential equations using continuous Runge-Kutta methods, PhD thesis, Department of Computer Science, University of Toronto, Toronto, Canada.

prob_dde_DDETST_H3

Same delay differential equation as prob_dde_DDETST_H2 with .

References

Hayashi, H. (1996). Numerical solution of retarded and neutral delay differential equations using continuous Runge-Kutta methods, PhD thesis, Department of Computer Science, University of Toronto, Toronto, Canada.

prob_dde_DDETST_H4

Same delay differential equation as prob_dde_DDETST_H2 with .

References

Hayashi, H. (1996). Numerical solution of retarded and neutral delay differential equations using continuous Runge-Kutta methods, PhD thesis, Department of Computer Science, University of Toronto, Toronto, Canada.

Radar5 Test Problems

prob_dde_RADAR5_oregonator

Delay differential equation model from chemical kinetics, given by

for ] with history function

for , where , , , , , , , , and .

References

Epstein, I. and Luo, Y. (1991). Differential delay equations in chemical kinetics. Nonlinear models, Journal of Chemical Physics (95), pp. 244-254.

prob_dde_RADAR5_robertson

Delay differential equation model of a chemical reaction with steady state solution, given by

for ] with history function , for ], and , where , , , and .

References

Guglielmi, N. and Hairer, E. (2001). Implementing Radau IIA methods for stiff delay differential equations, Computing (67), pp. 1-12.

prob_dde_RADAR5_waltman

Delay differential equation model of antibody production, given by

for ] with history function

for , where , , , , , , , and .

References

Waltman, P. (1978). A threshold model of antigen-stimulated antibody production, Theoretical Immunology (8), pp. 437-453.

QS Example

prob_dde_qs

Delay differential equation model of Quorum Sensing (QS) of Pseudomonas putida IsoF in continuous cultures.

References

Buddrus-Schiemann et al. (2014). Analysis of N-Acylhomoserine Lactone Dynamics in Continuous Cultures of Pseudomonas Putida IsoF By Use of ELISA and UHPLC/qTOF-MS-derived Measurements and Mathematical Models, Analytical and Bioanalytical Chemistry.