Deprecated Functions

This appendix lists currently deprecated functionality along with how to replace it.

Starting in Stan 2.29, deprecated functions with drop in replacements (such as the renaming of get_lp or multiply_log) will be removed 3 versions later e.g., functions deprecated in Stan 2.20 will be removed in Stan 2.23 and placed in Removed Functions. The Stan compiler can automatically update these on the behalf of the user for the entire deprecation window and at least one version following the removal.

Integer division with operator/

Deprecated: Using / with two integer arguments is interpreted as integer floor division, such that

\[ 1 / 2 = 0 \]

This is deprecated due to its confusion with real-valued division, where

\[ 1.0 / 2.0 = 0.5 \]

Replacement: Use the integer division operator operator%/% instead.

integrate_ode_rk45, integrate_ode_adams, integrate_ode_bdf ODE Integrators

These ODE integrator functions have been replaced by those described in Ordinary Differential Equation (ODE) Solvers.

Specifying an ordinary differential equation as a function

A system of ODEs is specified as an ordinary function in Stan within the functions block. The ODE system function must have this function signature:

array[] real ode(real time, array[] real state, array[] real theta,
                 array[] real x_r, array[] int x_i);

The ODE system function should return the derivative of the state with respect to time at the time provided. The length of the returned real array must match the length of the state input into the function.

The arguments to this function are:

  • time, the time to evaluate the ODE system

  • state, the state of the ODE system at the time specified

  • theta, parameter values used to evaluate the ODE system

  • x_r, data values used to evaluate the ODE system

  • x_i, integer data values used to evaluate the ODE system.

The ODE system function separates parameter values, theta, from data values, x_r, for efficiency in computing the gradients of the ODE.

Non-stiff solver

array[,] real integrate_ode_rk45(function ode, array[] real initial_state, real initial_time, array[] real times, array[] real theta, array[] real x_r, array[] int x_i)
Solves the ODE system for the times provided using the Dormand-Prince algorithm, a 4th/5th order Runge-Kutta method.

Available since 2.10, deprecated in 2.24

array[,] real integrate_ode_rk45(function ode, array[] real initial_state, real initial_time, array[] real times, array[] real theta, array[] real x_r, array[] int x_i, real rel_tol, real abs_tol, int max_num_steps)
Solves the ODE system for the times provided using the Dormand-Prince algorithm, a 4th/5th order Runge-Kutta method with additional control parameters for the solver.

Available since 2.10, deprecated in 2.24

array[,] real integrate_ode(function ode, array[] real initial_state, real initial_time, array[] real times, array[] real theta, array[] real x_r, array[] int x_i)
Solves the ODE system for the times provided using the Dormand-Prince algorithm, a 4th/5th order Runge-Kutta method.

Available since 2.10, deprecated in 2.24

array[,] real integrate_ode_adams(function ode, array[] real initial_state, real initial_time, array[] real times, array[] real theta, data array[] real x_r, data array[] int x_i)
Solves the ODE system for the times provided using the Adams-Moulton method.

Available since 2.23, deprecated in 2.24

array[,] real integrate_ode_adams(function ode, array[] real initial_state, real initial_time, array[] real times, array[] real theta, data array[] real x_r, data array[] int x_i, data real rel_tol, data real abs_tol, data int max_num_steps)
Solves the ODE system for the times provided using the Adams-Moulton method with additional control parameters for the solver.

Available since 2.23, deprecated in 2.24

Stiff solver

array[,] real integrate_ode_bdf(function ode, array[] real initial_state, real initial_time, array[] real times, array[] real theta, data array[] real x_r, data array[] int x_i)
Solves the ODE system for the times provided using the backward differentiation formula (BDF) method.

Available since 2.10, deprecated in 2.24

array[,] real integrate_ode_bdf(function ode, array[] real initial_state, real initial_time, array[] real times, array[] real theta, data array[] real x_r, data array[] int x_i, data real rel_tol, data real abs_tol, data int max_num_steps)
Solves the ODE system for the times provided using the backward differentiation formula (BDF) method with additional control parameters for the solver.

Available since 2.10, deprecated in 2.24

Arguments to the ODE solvers

The arguments to the ODE solvers in both the stiff and non-stiff cases are as follows.

  • ode: function literal referring to a function specifying the system of differential equations with signature:
(real, array[] real, array[] real, data array[] real, data array[] int):array[] real

The arguments represent (1) time, (2) system state, (3) parameters, (4) real data, and (5) integer data, and the return value contains the derivatives with respect to time of the state,

  • initial_state: initial state, type array[] real,

  • initial_time: initial time, type int or real,

  • times: solution times, type array[] real,

  • theta: parameters, type array[] real,

  • data x_r: real data, type array[] real, data only, and

  • data x_i: integer data, type array[] int, data only.

For more fine-grained control of the ODE solvers, these parameters can also be provided:

  • data rel_tol: relative tolerance for the ODE solver, type real, data only,

  • data abs_tol: absolute tolerance for the ODE solver, type real, data only, and

  • data max_num_steps: maximum number of steps to take in the ODE solver, type int, data only.

Return values

The return value for the ODE solvers is an array of type array[,] real, with values consisting of solutions at the specified times.

Sizes and parallel arrays

The sizes must match, and in particular, the following groups are of the same size:

  • state variables passed into the system function, derivatives returned by the system function, initial state passed into the solver, and rows of the return value of the solver,

  • solution times and number of rows of the return value of the solver,

  • parameters, real data and integer data passed to the solver will be passed to the system function

integrate_1d 1D integrator

This function has been replaced by those described in 1D integrators.

Specifying an integrand as a function

Performing a 1D integration requires the integrand to be specified somehow. This is done by defining a function in the Stan functions block with the special signature:

real integrand(real x, real xc, array[] real theta,
               array[] real x_r, array[] int x_i)

The function should return the value of the integrand evaluated at the point x.

The argument of this function are:

  • x, the independent variable being integrated over

  • xc, a high precision version of the distance from x to the nearest endpoint in a definite integral (for more into see section Precision Loss).

  • theta, parameter values used to evaluate the integral

  • x_r, data values used to evaluate the integral

  • x_i, integer data used to evaluate the integral

Like algebraic solver and the differential equations solver, the 1D integrator separates parameter values, theta, from data values, x_r.

Call to the 1D integrator

real integrate_1d (function integrand, real a, real b, array[] real theta, array[] real x_r, array[] int x_i)
Integrates the integrand from a to b.

Available since 2.23

real integrate_1d (function integrand, real a, real b, array[] real theta, array[] real x_r, array[] int x_i, real relative_tolerance)
Integrates the integrand from a to b with the given relative tolerance.

Available since 2.23

Arguments to the 1D integrator

The arguments to the 1D integrator are as follows:

  • integrand: function literal referring to a function specifying the integrand with signature (real, real, array[] real, array[] real, array[] int):real The arguments represent
      1. where integrand is evaluated,
      1. distance from evaluation point to integration limit for definite integrals,
      1. parameters,
      1. real data
      1. integer data, and the return value is the integrand evaluated at the given point,
  • a: left limit of integration, may be negative infinity, type real,
  • b: right limit of integration, may be positive infinity, type real,
  • theta: parameters only, type array[] real,
  • x_r: real data only, type array[] real,
  • x_i: integer data only, type array[] int.

A relative_tolerance argument can optionally be provided for more control over the algorithm:

  • relative_tolerance: relative tolerance for the 1d integrator, type real, data only.

Return value

The return value for the 1D integrator is a real, the value of the integral.

Zero-crossing integrals

For numeric stability, integrals on the (possibly infinite) interval \((a, b)\) that cross zero are split into two integrals, one from \((a, 0)\) and one from \((0, b)\). Each integral is separately integrated to the given relative_tolerance.

Precision loss near limits of integration in definite integrals

When integrating certain definite integrals, there can be significant precision loss in evaluating the integrand near the endpoints. This has to do with the breakdown in precision of double precision floating point values when adding or subtracting a small number from a number much larger than it in magnitude (for instance, 1.0 - x). xc (as passed to the integrand) is a high-precision version of the distance between x and the definite integral endpoints and can be used to address this issue. More information (and an example where this is useful) is given in the User’s Guide. For zero crossing integrals, xc will be a high precision version of the distance to the endpoints of the two smaller integrals. For any integral with an endpoint at negative infinity or positive infinity, xc is set to NaN.

Algorithmic details

Internally the 1D integrator uses the double-exponential methods in the Boost 1D quadrature library. Boost in turn makes use of quadrature methods developed in (Takahasi and Mori 1974), (Mori 1978), (Bailey, Jeyabalan, and Li 2005), and (Tanaka et al. 2009).

The gradients of the integral are computed in accordance with the Leibniz integral rule. Gradients of the integrand are computed internally with Stan’s automatic differentiation.

algebra_solver, algebra_solver_newton algebraic solvers

These algebraic solver functions have been replaced by those described in Algebraic Equation Solvers..

Specifying an algebraic equation as a function

An algebraic system is specified as an ordinary function in Stan within the function block. The algebraic system function must have this signature:

 vector algebra_system(vector y, vector theta,
                              data array[] real x_r, array[] int x_i)

The algebraic system function should return the value of the algebraic function which goes to 0, when we plug in the solution to the algebraic system.

The argument of this function are:

  • y, the unknowns we wish to solve for

  • theta, parameter values used to evaluate the algebraic system

  • x_r, data values used to evaluate the algebraic system

  • x_i, integer data used to evaluate the algebraic system

The algebraic system function separates parameter values, theta, from data values, x_r, for efficiency in propagating the derivatives through the algebraic system.

Call to the algebraic solver

vector algebra_solver(function algebra_system, vector y_guess, vector theta, data array[] real x_r, array[] int x_i)
Solves the algebraic system, given an initial guess, using the Powell hybrid algorithm.

Available since 2.17, deprecated in 2.31

vector algebra_solver(function algebra_system, vector y_guess, vector theta, data array[] real x_r, array[] int x_i, data real rel_tol, data real f_tol, int max_steps)
Solves the algebraic system, given an initial guess, using the Powell hybrid algorithm with additional control parameters for the solver.

Available since 2.17, deprecated in 2.31

Note: In future releases, the function algebra_solver will be deprecated and replaced with algebra_solver_powell.

vector algebra_solver_newton(function algebra_system, vector y_guess, vector theta, data array[] real x_r, array[] int x_i)
Solves the algebraic system, given an initial guess, using Newton’s method.

Available since 2.24, deprecated in 2.31

vector algebra_solver_newton(function algebra_system, vector y_guess, vector theta, data array[] real x_r, array[] int x_i, data real rel_tol, data real f_tol, int max_steps)
Solves the algebraic system, given an initial guess, using Newton’s method with additional control parameters for the solver.

Available since 2.24, deprecated in 2.31

Arguments to the algebraic solver

The arguments to the algebraic solvers are as follows:

  • algebra_system: function literal referring to a function specifying the system of algebraic equations with signature (vector, vector, array[] real, array[] int):vector. The arguments represent (1) unknowns, (2) parameters, (3) real data, and (4) integer data, and the return value contains the value of the algebraic function, which goes to 0 when we plug in the solution to the algebraic system,

  • y_guess: initial guess for the solution, type vector,

  • theta: parameters only, type vector,

  • x_r: real data only, type array[] real, and

  • x_i: integer data only, type array[] int.

For more fine-grained control of the algebraic solver, these parameters can also be provided:

  • rel_tol: relative tolerance for the algebraic solver, type real, data only,

  • function_tol: function tolerance for the algebraic solver, type real, data only,

  • max_num_steps: maximum number of steps to take in the algebraic solver, type int, data only.

Return value

The return value for the algebraic solver is an object of type vector, with values which, when plugged in as y make the algebraic function go to 0.

Sizes and parallel arrays

Certain sizes have to be consistent. The initial guess, return value of the solver, and return value of the algebraic function must all be the same size.

The parameters, real data, and integer data will be passed from the solver directly to the system function.

Back to top

References

Bailey, David H., Karthik Jeyabalan, and Xiaoye S. Li. 2005. “A Comparison of Three High-Precision Quadrature Schemes.” Experiment. Math. 14 (3): 317–29. https://projecteuclid.org:443/euclid.em/1128371757.
Mori, Masatake. 1978. “An IMT-Type Double Exponential Formula for Numerical Integration.” Publications of the Research Institute for Mathematical Sciences 14 (3): 713–29. https://doi.org/10.2977/prims/1195188835.
Takahasi, Hidetosi, and Masatake Mori. 1974. “Double Exponential Formulas for Numerical Integration.” Publications of the Research Institute for Mathematical Sciences 9 (3): 721–41. https://doi.org/10.2977/prims/1195192451.
Tanaka, Ken’ichiro, Masaaki Sugihara, Kazuo Murota, and Masatake Mori. 2009. “Function Classes for Double Exponential Integration Formulas.” Numerische Mathematik 111 (4): 631–55. https://doi.org/10.1007/s00211-008-0195-1.