pyblp.Iteration¶

class
pyblp.
Iteration
(method, method_options=None, compute_jacobian=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'
 Nonaccelerated 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 firstorder squared nonmonotone extrapolation scheme. If there are any errors during the acceleration step, it uses the last values for the next iteration of the algorithm.'broyden1'
 Use thescipy.optimize.root()
Broyden’s first Jacobian approximation method, known as Broyden’s good method.'broyden2'
 Use thescipy.optimize.root()
Broyden’s second Jacobian approximation method, known as Broyden’s bad method.'anderson'
 Use thescipy.optimize.root()
Anderson method.'krylov'
 Use thescipy.optimize.root()
Krylov approximation for inverse Jacobian method.'diagbroyden'
 Use thescipy.optimize.root()
diagonal Broyden Jacobian approximation method.'dfsane'
 Use thescipy.optimize.root()
derivativefree spectral method.
The following routines can use analytic Jacobians:
'hybr'
 Use thescipy.optimize.root()
modification of the Powell hybrid method implemented in MINIPACK.'lm'
 Uses thescipy.optimize.root()
modification of the LevenbergMarquardt 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, andconverged
is a flag for whether the routine converged.The
contraction
function has the following form:contraction(x0) > (x1, weights, jacobian)
where
weights
are eitherNone
or a vector of weights that should multiplyx1  x
before computing the norm of the differences, andjacobian
isNone
ifcompute_jacobian
isFalse
.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 tooptions
inscipy.optimize.root()
. Refer to the SciPy documentation for information about which options are available. By default, thetol_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
1e14
. 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 are1
and2
, 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 tostep_max
, butstep_max
is scaled by this factor. Similarly, ifstep_min
is negative and the step length is belowstep_min
, it is set equal tostep_min
andstep_min
is scaled by this factor. The default value is4.0
.
compute_jacobian (bool, optional) – Whether to compute an analytic Jacobian during iteration, which must be
False
ifmethod
does not use analytic Jacobians. By default, analytic Jacobians are not computed, and if amethod
is selected that supports analytic Jacobians, they will by default be numerically approximated.
Examples