class_docstr: Backward differentiation formula (BDF) solver for stiff ODEs.
  
  Implements the solver described in [Shampine and Reichelt (1997)][1], a
  variable step size, variable order (VSVO) BDF integrator with order varying
  between 1 and 5.
  
  #### Algorithm details
  
  Each step involves solving the following nonlinear equation by Newton's
  method:
  ```none
  0 = 1/1 * BDF(1, y)[n+1] + ... + 1/k * BDF(k, y)[n+1]
    - h ode_fn(t[n+1], y[n+1])
    - bdf_coefficients[k-1] * (1/1 + ... + 1/k) * (y[n+1] - y[n] - BDF(1, y)[n]
                                                          -  ... - BDF(k, y)[n])
  ```
  where `k >= 1` is the current order of the integrator, `h` is the current step
  size, `bdf_coefficients` is a list of numbers that parameterizes the method,
  and `BDF(m, y)` is the `m`-th order backward difference of the vector `y`. In
  particular, `BDF(0, y)[n] = y[n]` and
  `BDF(m + 1, y)[n] = BDF(m, y)[n] - BDF(m, y)[n - 1]` for `m >= 0`.
  
  Newton's method can fail because
  * the method has exceeded the maximum number of iterations,
  * the method is converging too slowly, or
  * the method is not expected to converge
  (the last two conditions are determined by approximating the Lipschitz
  constant associated with the iteration).
  
  When `evaluate_jacobian_lazily` is `True`, the solver avoids evaluating the
  Jacobian of the dynamics function as much as possible. In particular, Newton's
  method will try to use the Jacobian from a previous integration step. If
  Newton's method fails with an out-of-date Jacobian, the Jacobian is
  re-evaluated and Newton's method is restarted. If Newton's method fails and
  the Jacobian is already up-to-date, then the step size is decreased and
  Newton's method is restarted.
  
  Even if Newton's method converges, the solution it generates can still be
  rejected if it exceeds the specified error tolerance due to truncation error.
  In this case, the step size is decreased and Newton's method is restarted.
  
  #### References
  
  [1]: Lawrence F. Shampine and Mark W. Reichelt. The MATLAB ODE Suite. _SIAM
       Journal on Scientific Computing_ 18(1):1-22, 1997.
class_docstr_tok: ["Backward","differentiation","formula","(","BDF",")","solver","for","stiff","ODEs",".","Implements","the","solver","described","in","[","Shampine","and","Reichelt","(","1997",")","]","[","1","]",",","a","variable","step","size",",","variable","order","(","VSVO",")","BDF","integrator","with","order","varying","between","1","and","5",".","#","#","#","#","Algorithm","details","Each","step","involves","solving","the","following","nonlinear","equation","by","Newton's","method",":","``","`","none","0","=","1\/1","*","BDF","(","1",",","y",")","[","n+1","]","+","...","+","1\/k","*","BDF","(","k",",","y",")","[","n+1","]","-","h","ode_fn","(","t","[","n+1","]",",","y","[","n+1","]",")","-","bdf_coefficients","[","k-1","]","*","(","1\/1","+","...","+","1\/k",")","*","(","y","[","n+1","]","-","y","[","n","]","-","BDF","(","1",",","y",")","[","n","]","-","...","-","BDF","(","k",",","y",")","[","n","]",")","``","`","where","`","k",">","=","1","`","is","the","current","order","of","the","integrator",",","`","h","`","is","the","current","step","size",",","`","bdf_coefficients","`","is","a","list","of","numbers","that","parameterizes","the","method",",","and","`","BDF","(","m",",","y",")","`","is","the","`","m","`","-th","order","backward","difference","of","the","vector","`","y","`",".","In","particular",",","`","BDF","(","0",",","y",")","[","n","]","=","y","[","n","]","`","and","`","BDF","(","m","+","1",",","y",")","[","n","]","=","BDF","(","m",",","y",")","[","n","]","-","BDF","(","m",",","y",")","[","n","-","1","]","`","for","`","m",">","=","0","`",".","Newton","'s","method","can","fail","because","*","the","method","has","exceeded","the","maximum","number","of","iterations",",","*","the","method","is","converging","too","slowly",",","or","*","the","method","is","not","expected","to","converge","(","the","last","two","conditions","are","determined","by","approximating","the","Lipschitz","constant","associated","with","the","iteration",")",".","When","`","evaluate_jacobian_lazily","`","is","`","True","`",",","the","solver","avoids","evaluating","the","Jacobian","of","the","dynamics","function","as","much","as","possible",".","In","particular",",","Newton's","method","will","try","to","use","the","Jacobian","from","a","previous","integration","step",".","If","Newton","'s","method","fails","with","an","out-of-date","Jacobian",",","the","Jacobian","is","re-evaluated","and","Newton","'s","method","is","restarted",".","If","Newton","'s","method","fails","and","the","Jacobian","is","already","up-to-date",",","then","the","step","size","is","decreased","and","Newton","'s","method","is","restarted",".","Even","if","Newton","'s","method","converges",",","the","solution","it","generates","can","still","be","rejected","if","it","exceeds","the","specified","error","tolerance","due","to","truncation","error",".","In","this","case",",","the","step","size","is","decreased","and","Newton","'s","method","is","restarted",".","#","#","#","#","References","[","1","]",":","Lawrence","F.","Shampine","and","Mark","W.","Reichelt",".","The","MATLAB","ODE","Suite",".","_SIAM","Journal","on","Scientific","Computing_","18","(","1",")",":1-22",",","1997","."]
docstr: Initializes the solver.
  
  Args:
    rtol: Optional float `Tensor` specifying an upper bound on relative error,
      per element of the dependent variable. The error tolerance for the next
      step is `tol = atol + rtol * abs(state)` where `state` is the computed
      state at the current step (see also `atol`). The next step is rejected
      if it incurs a local truncation error larger than `tol`.
      Default value: `1e-3`.
    atol: Optional float `Tensor` specifying an upper bound on absolute error,
      per element of the dependent variable (see also `rtol`).
      Default value: `1e-6`.
    first_step_size: Optional scalar float `Tensor` specifying the size of the
      first step. If unspecified, the size is chosen automatically.
      Default value: `None`.
    safety_factor: Scalar positive float `Tensor`. When Newton's method
      converges, the solver may choose to update the step size by applying a
      multiplicative factor to the current step size. This factor is `factor =
      clamp(factor_unclamped, min_step_size_factor, max_step_size_factor)`
      where `factor_unclamped = error_ratio**(-1. / (order + 1)) *
      safety_factor` (see also `min_step_size_factor` and
      `max_step_size_factor`). A small (respectively, large) value for the
      safety factor causes the solver to take smaller (respectively, larger)
      step sizes. A value larger than one, though not explicitly prohibited,
      is discouraged.
      Default value: `0.9`.
    min_step_size_factor: Scalar float `Tensor` (see `safety_factor`).
      Default value: `0.1`.
    max_step_size_factor: Scalar float `Tensor` (see `safety_factor`).
      Default value: `10.`.
    max_num_steps: Optional scalar integer `Tensor` specifying the maximum
      number of steps allowed (including rejected steps). If unspecified,
      there is no upper bound on the number of steps.
      Default value: `None`.
    max_order: Scalar integer `Tensor` taking values between 1 and 5
      (inclusive) specifying the maximum BDF order.
      Default value: `5`.
    max_num_newton_iters: Optional scalar integer `Tensor` specifying the
      maximum number of iterations per invocation of Newton's method. If
      unspecified, there is no upper bound on the number iterations.
      Default value: `4`.
    newton_tol_factor: Scalar float `Tensor` used to determine the stopping
      condition for Newton's method. In particular, Newton's method terminates
      when the distance to the root is estimated to be less than
      `newton_tol_factor * norm(atol + rtol * abs(state))` where `state` is
      the computed state at the current step.
      Default value: `0.1`.
    newton_step_size_factor: Scalar float `Tensor` specifying a multiplicative
      factor applied to the size of the integration step when Newton's method
      fails.
      Default value: `0.5`.
    bdf_coefficients: 1-D float `Tensor` with 5 entries that parameterize the
      solver. The default values are those proposed in [1].
      Default value: `(-0.1850, -1. / 9., -0.0823, -0.0415, 0.)`.
    evaluate_jacobian_lazily: Optional boolean specifying whether the Jacobian
      should be evaluated at each point in time or as needed (i.e., lazily).
      Default value: `True`.
    make_adjoint_solver_fn: Callable that takes no arguments that constructs a
      `Solver` instance. The created solver is used in the adjoint senstivity
      analysis to compute gradients (if they are requested).
      Default value: A callable that returns this solver.
    validate_args: Whether to validate input with asserts. If `validate_args`
      is `False` and the inputs are invalid, correct behavior is not
      guaranteed.
      Default value: `False`.
    name: Python `str` name prefixed to Ops created by this function.
      Default value: `None` (i.e., 'bdf').
docstr_tok: ["Initializes","the","solver",".","Args",":","rtol",":","Optional","float","`","Tensor","`","specifying","an","upper","bound","on","relative","error",",","per","element","of","the","dependent","variable",".","The","error","tolerance","for","the","next","step","is","`","tol","=","atol","+","rtol","*","abs","(","state",")","`","where","`","state","`","is","the","computed","state","at","the","current","step","(","see","also","`","atol","`",")",".","The","next","step","is","rejected","if","it","incurs","a","local","truncation","error","larger","than","`","tol","`",".","Default","value",":","`","1e-3","`",".","atol",":","Optional","float","`","Tensor","`","specifying","an","upper","bound","on","absolute","error",",","per","element","of","the","dependent","variable","(","see","also","`","rtol","`",")",".","Default","value",":","`","1e-6","`",".","first_step_size",":","Optional","scalar","float","`","Tensor","`","specifying","the","size","of","the","first","step",".","If","unspecified",",","the","size","is","chosen","automatically",".","Default","value",":","`","None","`",".","safety_factor",":","Scalar","positive","float","`","Tensor","`",".","When","Newton","'s","method","converges",",","the","solver","may","choose","to","update","the","step","size","by","applying","a","multiplicative","factor","to","the","current","step","size",".","This","factor","is","`","factor","=","clamp","(","factor_unclamped",",","min_step_size_factor",",","max_step_size_factor",")","`","where","`","factor_unclamped","=","error_ratio","*","*","(","-1",".","\/","(","order","+","1",")",")","*","safety_factor","`","(","see","also","`","min_step_size_factor","`","and","`","max_step_size_factor","`",")",".","A","small","(","respectively",",","large",")","value","for","the","safety","factor","causes","the","solver","to","take","smaller","(","respectively",",","larger",")","step","sizes",".","A","value","larger","than","one",",","though","not","explicitly","prohibited",",","is","discouraged",".","Default","value",":","`","0.9","`",".","min_step_size_factor",":","Scalar","float","`","Tensor","`","(","see","`","safety_factor","`",")",".","Default","value",":","`","0.1","`",".","max_step_size_factor",":","Scalar","float","`","Tensor","`","(","see","`","safety_factor","`",")",".","Default","value",":","`","10.","`",".","max_num_steps",":","Optional","scalar","integer","`","Tensor","`","specifying","the","maximum","number","of","steps","allowed","(","including","rejected","steps",")",".","If","unspecified",",","there","is","no","upper","bound","on","the","number","of","steps",".","Default","value",":","`","None","`",".","max_order",":","Scalar","integer","`","Tensor","`","taking","values","between","1","and","5","(","inclusive",")","specifying","the","maximum","BDF","order",".","Default","value",":","`","5","`",".","max_num_newton_iters",":","Optional","scalar","integer","`","Tensor","`","specifying","the","maximum","number","of","iterations","per","invocation","of","Newton","'s","method",".","If","unspecified",",","there","is","no","upper","bound","on","the","number","iterations",".","Default","value",":","`","4","`",".","newton_tol_factor",":","Scalar","float","`","Tensor","`","used","to","determine","the","stopping","condition","for","Newton","'s","method",".","In","particular",",","Newton","'s","method","terminates","when","the","distance","to","the","root","is","estimated","to","be","less","than","`","newton_tol_factor","*","norm","(","atol","+","rtol","*","abs","(","state",")",")","`","where","`","state","`","is","the","computed","state","at","the","current","step",".","Default","value",":","`","0.1","`",".","newton_step_size_factor",":","Scalar","float","`","Tensor","`","specifying","a","multiplicative","factor","applied","to","the","size","of","the","integration","step","when","Newton","'s","method","fails",".","Default","value",":","`","0.5","`",".","bdf_coefficients",":","1-D","float","`","Tensor","`","with","5","entries","that","parameterize","the","solver",".","The","default","values","are","those","proposed","in","[","1","]",".","Default","value",":","`","(","-0.1850",",","-1",".","\/","9.",",","-0.0823",",","-0.0415",",","0.",")","`",".","evaluate_jacobian_lazily",":","Optional","boolean","specifying","whether","the","Jacobian","should","be","evaluated","at","each","point","in","time","or","as","needed","(","i.e.",",","lazily",")",".","Default","value",":","`","True","`",".","make_adjoint_solver_fn",":","Callable","that","takes","no","arguments","that","constructs","a","`","Solver","`","instance",".","The","created","solver","is","used","in","the","adjoint","senstivity","analysis","to","compute","gradients","(","if","they","are","requested",")",".","Default","value",":","A","callable","that","returns","this","solver",".","validate_args",":","Whether","to","validate","input","with","asserts",".","If","`","validate_args","`","is","`","False","`","and","the","inputs","are","invalid",",","correct","behavior","is","not","guaranteed",".","Default","value",":","`","False","`",".","name",":","Python","`","str","`","name","prefixed","to","Ops","created","by","this","function",".","Default","value",":","`","None","`","(","i.e.",",","'bdf","'",")","."]
code: def __init__(
      self,
      rtol=1e-3,
      atol=1e-6,
      first_step_size=None,
      safety_factor=0.9,
      min_step_size_factor=0.1,
      max_step_size_factor=10.0,
      max_num_steps=None,
      max_order=bdf_util.MAX_ORDER,
      max_num_newton_iters=4,
      newton_tol_factor=0.1,
      newton_step_size_factor=0.5,
      bdf_coefficients=(-0.1850, -1.0 / 9.0, -0.0823, -0.0415, 0.0),
      evaluate_jacobian_lazily=False,
      make_adjoint_solver_fn=None,
      validate_args=False,
      name="bdf",
  ):
      """Initializes the solver.
  
      Args:
        rtol: Optional float `Tensor` specifying an upper bound on relative error,
          per element of the dependent variable. The error tolerance for the next
          step is `tol = atol + rtol * abs(state)` where `state` is the computed
          state at the current step (see also `atol`). The next step is rejected
          if it incurs a local truncation error larger than `tol`.
          Default value: `1e-3`.
        atol: Optional float `Tensor` specifying an upper bound on absolute error,
          per element of the dependent variable (see also `rtol`).
          Default value: `1e-6`.
        first_step_size: Optional scalar float `Tensor` specifying the size of the
          first step. If unspecified, the size is chosen automatically.
          Default value: `None`.
        safety_factor: Scalar positive float `Tensor`. When Newton's method
          converges, the solver may choose to update the step size by applying a
          multiplicative factor to the current step size. This factor is `factor =
          clamp(factor_unclamped, min_step_size_factor, max_step_size_factor)`
          where `factor_unclamped = error_ratio**(-1. / (order + 1)) *
          safety_factor` (see also `min_step_size_factor` and
          `max_step_size_factor`). A small (respectively, large) value for the
          safety factor causes the solver to take smaller (respectively, larger)
          step sizes. A value larger than one, though not explicitly prohibited,
          is discouraged.
          Default value: `0.9`.
        min_step_size_factor: Scalar float `Tensor` (see `safety_factor`).
          Default value: `0.1`.
        max_step_size_factor: Scalar float `Tensor` (see `safety_factor`).
          Default value: `10.`.
        max_num_steps: Optional scalar integer `Tensor` specifying the maximum
          number of steps allowed (including rejected steps). If unspecified,
          there is no upper bound on the number of steps.
          Default value: `None`.
        max_order: Scalar integer `Tensor` taking values between 1 and 5
          (inclusive) specifying the maximum BDF order.
          Default value: `5`.
        max_num_newton_iters: Optional scalar integer `Tensor` specifying the
          maximum number of iterations per invocation of Newton's method. If
          unspecified, there is no upper bound on the number iterations.
          Default value: `4`.
        newton_tol_factor: Scalar float `Tensor` used to determine the stopping
          condition for Newton's method. In particular, Newton's method terminates
          when the distance to the root is estimated to be less than
          `newton_tol_factor * norm(atol + rtol * abs(state))` where `state` is
          the computed state at the current step.
          Default value: `0.1`.
        newton_step_size_factor: Scalar float `Tensor` specifying a multiplicative
          factor applied to the size of the integration step when Newton's method
          fails.
          Default value: `0.5`.
        bdf_coefficients: 1-D float `Tensor` with 5 entries that parameterize the
          solver. The default values are those proposed in [1].
          Default value: `(-0.1850, -1. / 9., -0.0823, -0.0415, 0.)`.
        evaluate_jacobian_lazily: Optional boolean specifying whether the Jacobian
          should be evaluated at each point in time or as needed (i.e., lazily).
          Default value: `True`.
        make_adjoint_solver_fn: Callable that takes no arguments that constructs a
          `Solver` instance. The created solver is used in the adjoint senstivity
          analysis to compute gradients (if they are requested).
          Default value: A callable that returns this solver.
        validate_args: Whether to validate input with asserts. If `validate_args`
          is `False` and the inputs are invalid, correct behavior is not
          guaranteed.
          Default value: `False`.
        name: Python `str` name prefixed to Ops created by this function.
          Default value: `None` (i.e., 'bdf').
      """
      super(BDF, self).__init__(
          make_adjoint_solver_fn=make_adjoint_solver_fn,
          validate_args=validate_args,
          name=name,
      )
      # The default values of `rtol` and `atol` match `scipy.integrate.solve_ivp`.
      self._rtol = rtol
      self._atol = atol
      self._first_step_size = first_step_size
      self._safety_factor = safety_factor
      self._min_step_size_factor = min_step_size_factor
      self._max_step_size_factor = max_step_size_factor
      self._max_num_steps = max_num_steps
      self._max_order = max_order
      self._max_num_newton_iters = max_num_newton_iters
      self._newton_tol_factor = newton_tol_factor
      self._newton_step_size_factor = newton_step_size_factor
      self._bdf_coefficients = bdf_coefficients
      self._evaluate_jacobian_lazily = evaluate_jacobian_lazily
  
imports: import collections
  import functools
  import numpy
  import tensorflow.compat.v1
  import tensorflow.compat.v2
  from tensorflow_probability.python.internal import dtype_util
  from tensorflow_probability.python.internal import prefer_static
  from tensorflow_probability.python.internal import tensorshape_util
  from tensorflow_probability.python.math.ode import base
  from tensorflow_probability.python.math.ode import bdf_util
  from tensorflow_probability.python.math.ode import util
label_desc: Use image node_id 1 to create a new BDF object from inherited base classes: base with example: obj = BDF(rtol, atol, first_step_size, safety_factor, min_step_size_factor, max_step_size_factor, max_num_steps, max_order, max_num_newton_iters, newton_tol_factor, newton_step_size_factor, bdf_coefficients, evaluate_jacobian_lazily, make_adjoint_solver_fn, validate_args, name)