pyblp.Iteration

class pyblp.Iteration(method, method_options=None, compute_jacobian=False, universal_display=False)

Configuration for solving fixed point problems.

Parameters

• method (str or callable) –

  The fixed point iteration routine that will be used. The following routines do not use analytic Jacobians:

  • 'simple' - Non-accelerated iteration.

  • 'squarem' - SQUAREM acceleration method of Varadhan and Roland (2008) and considered in the context of the BLP problem in Reynaerts, Varadhan, and Nash (2012). This implementation uses a first-order squared non-monotone extrapolation scheme.

  • 'broyden1' - Use the scipy.optimize.root() Broyden’s first Jacobian approximation method, known as Broyden’s good method.

  • 'broyden2' - Use the scipy.optimize.root() Broyden’s second Jacobian approximation method, known as Broyden’s bad method.

  • 'anderson' - Use the scipy.optimize.root() Anderson method.

  • 'krylov' - Use the scipy.optimize.root() Krylov approximation for inverse Jacobian method.

  • 'diagbroyden' - Use the scipy.optimize.root() diagonal Broyden Jacobian approximation method.

  • 'df-sane' - Use the scipy.optimize.root() derivative-free spectral method.

  The following routines can use analytic Jacobians:

  • 'hybr' - Use the scipy.optimize.root() modification of the Powell hybrid method implemented in MINIPACK.

  • 'lm' - Uses the scipy.optimize.root() modification of the Levenberg-Marquardt algorithm implemented in MINIPACK.

  The following trivial routine can be used to simply return the initial values:

  • 'return' - Assume that the initial values are the optimal ones.

  Also accepted is a custom callable method with the following form:

  method(initial, contraction, callback, **options) -> (final, converged)
  

  where initial is an array of initial values, contraction is a callable contraction mapping of the form specified below, callback is a function that should be called without any arguments after each major iteration (it is used to record the number of major iterations), options are specified below, final is an array of final values, and converged is a flag for whether the routine converged.

  The contraction function has the following form:

  contraction(x0) -> (x1, weights, jacobian)

  where weights are either None or a vector of weights that should multiply x1 - x before computing the norm of the differences, and jacobian is None if compute_jacobian is False.

  Regardless of the chosen routine, if there are any computational issues that create infinities or null values, final will be the second to last iteration’s values.

• method_options (dict, optional) –

  Options for the fixed point iteration routine.

  For routines other and 'simple', 'squarem', and 'return', these options will be passed to options in scipy.optimize.root(). Refer to the SciPy documentation for information about which options are available. By default, the tol_norm option is configured to use the infinity norm for SciPy methods other than 'hybr' and 'lm', for which a norm cannot be specified.

  The 'simple' and 'squarem' methods support the following options:

  • max_evaluations : (int) - Maximum number of contraction mapping evaluations. The default value is 5000.

  • atol : (float) - Absolute tolerance for convergence of the configured norm. The default value is 1e-14. To use only a relative tolerance, set this to zero.

  • rtol (float) - Relative tolerance for convergence of the configured norm. The default value is zero; that is, only absolute tolerance is used by default.

  • norm : (callable) - The norm to be used. By default, the \(\ell^\infty\)-norm is used. If specified, this should be a function that accepts an array of differences and that returns a scalar norm.

  The 'squarem' routine accepts additional options that mirror those in the SQUAREM package, written in R by Ravi Varadhan, which identifies the step length with \(-\alpha\) from Varadhan and Roland (2008):

  • scheme : (int) - The default value is 3, which corresponds to S3 in Varadhan and Roland (2008). Other acceptable schemes are 1 and 2, which correspond to S1 and S2.

  • step_min : (float) - The initial value for the minimum step length. The default value is 1.0.

  • step_max : (float) - The initial value for the maximum step length. The default value is 1.0.

  • step_factor : (float) - When the step length exceeds step_max, it is set equal to step_max, but step_max is scaled by this factor. Similarly, if step_min is negative and the step length is below step_min, it is set equal to step_min and step_min is scaled by this factor. The default value is 4.0.

• compute_jacobian (bool, optional) – Whether to compute an analytic Jacobian during iteration. By default, analytic Jacobians are not computed, and if a method is selected that supports analytic Jacobians, they will by default be numerically approximated.

• universal_display (bool, optional) – Whether to format iteration progress such that the display looks the same for all routines. By default, the universal display is not used and no iteration progress is displayed. Setting this to True can be helpful for debugging iteration issues. For example, iteration may get stuck above the configured termination tolerance.

Examples

• Iteration Example