inversion_ideas.BFGSPreconditioner#

class inversion_ideas.BFGSPreconditioner(*args, **kwargs)#

BFGS Preconditioner.

Use this class to define a dynamic BFGS preconditioner from an objective function. This class implements the update method that can be used by minimizers to dynamically update the preconditioner.

Parameters:
objective_functionObjective

Objective function for which the Jacobi preconditioner will be built.

initial_matrixarray or sparray or LinearOperator or None, optional

Square matrix that will be used as the initial estimate of the inverse of the Hessian of the objective_function. If None, the identity matrix will be used.

dtypedtype, optional

Data type of the matrix.

Attributes

H

Hermitian adjoint.

T

Transpose.

index

Current index of the BFGS update algorithm.

matrix

Current preconditioner matrix \(H_k\).

Methods

__call__(x)

Apply this linear operator.

adjoint()

Hermitian adjoint.

dot(x)

Multi-purpose multiplication method.

matmat(X)

Matrix-matrix multiplication.

matvec(x)

Matrix-vector multiplication.

rdot(x)

Multi-purpose multiplication method from the right.

reset()

Reset the BFGS preconditioner.

rmatmat(X)

Adjoint matrix-matrix multiplication.

rmatvec(x)

Adjoint matrix-vector multiplication.

transpose()

Transpose.

update(model)

Update the BFGS preconditioner.

Notes

The preconditioner is built using the BFGS update equation (Nocedal & Wright, 1999, eq. 8.16):

\[H_{k+1} = (I - \rho_k s_k y_k^T) H_k (I - \rho_k y_k s_k^T) + \rho s_k s_k^T,\]

where

\[\rho_k = \frac{1}{y_k^T s_k},\]
\[\y_k = \nabla \phi(\mathbf{m}_{k+1}) - \nabla \phi(\mathbf{m}_k),\]
\[\s_k = m_{k+1} - m_k,\]

and \(\phi(\cdot)\) is the objective function that will be inverted.

By default, the \(H_0\) is set as the identity matrix. Alternatively, the user can set an initial value for it through the initial_preconditioner argument.

References

Nocedal, J., & Wright, S. J. (1999). Numerical optimization. Springer.

Attributes#

BFGSPreconditioner.H#

Hermitian adjoint.

See also

scipy.sparse.linalg.LinearOperator.adjoint

Equivalent method.

BFGSPreconditioner.T#

Transpose.

See also

scipy.sparse.linalg.LinearOperator.transpose

Equivalent method.

BFGSPreconditioner.index#

Current index of the BFGS update algorithm.

BFGSPreconditioner.matrix#

Current preconditioner matrix \(H_k\).

BFGSPreconditioner.ndim#

Methods#

Methods documentation

BFGSPreconditioner.__call__(x)#

Apply this linear operator.

Equivalent to __matmul__.

BFGSPreconditioner.adjoint()#

Hermitian adjoint.

Returns the Hermitian adjoint of this linear operator, also known as the Hermitian conjugate or Hermitian transpose. For a complex matrix, the Hermitian adjoint is equal to the conjugate transpose.

Returns:
LinearOperator

Hermitian adjoint of self.

See also

H

Equivalent attribute.

BFGSPreconditioner.dot(x)#

Multi-purpose multiplication method.

Parameters:
xarray_like or LinearOperator or scalar

Array-like input will be interpreted as a 1-D row vector or 2-D matrix (or batch of matrices) depending on its shape. See the Returns section for details.

Returns:
Axarray or LinearOperator

  • For LinearOperator input, operator composition is performed.

  • For scalar input, a lazily scaled operator is returned.

  • Otherwise, the input is expected to take the form of a dense 1-D vector or 2-D matrix (or batch of matrices), interpreted as follows (where self is an M by N linear operator):

    • If x has shape (N,) it is interpreted as a row vector and matvec is called.

    • If x has shape (..., N, K) for some integer K, it is interpreted as a matrix (or batch of matrices if there are batch dimensions) and matmat is called.

See also

__mul__

Equivalent method used by the * operator.

__matmul__

Method used by the @ operator which rejects scalar input before calling this method.

Notes

To perform matrix-vector multiplication on batches of vectors, use matvec.

For clarity, it is recommended to use the matvec or matmat methods directly instead of this method when interacting with dense vectors and matrices.

BFGSPreconditioner.matmat(X)#

Matrix-matrix multiplication.

Performs the operation A @ X where A is an M x N linear operator (or batch of linear operators) and X is a dense N x K matrix (or batch of dense matrices).

Parameters:
X{matrix, ndarray}

An array with shape (..., N, K) representing the dense matrix (or batch of dense matrices).

Returns:
Y{matrix, ndarray}

An array with shape (..., M, K).

Notes

This method wraps any user-specified matmat routine or overridden _matmat method to ensure that Y has the correct type.

BFGSPreconditioner.matvec(x)#

Matrix-vector multiplication.

Applies A to x, where A is an M x N linear operator (or batch of linear operators) and x is a row vector (or batch of such vectors).

Parameters:
x{matrix, ndarray}

An array with shape (..., N) representing a row vector (or batch of row vectors).

Added in version 1.18.0: A FutureWarning is emitted for column vector input of shape (N, 1), for which an array with shape (M, 1) is returned. matmat can be called instead for identical behaviour on such input.

Returns:
y{matrix, ndarray}

An array with shape (..., M).

Notes

This method wraps the user-specified matvec routine or overridden _matvec method to ensure that y has the correct shape and type.

BFGSPreconditioner.rdot(x)#

Multi-purpose multiplication method from the right.

Note

This method returns x A. To perform adjoint multiplication instead, use one of rmatvec or rmatmat, or take the adjoint first, like self.H.rdot(x) or x * self.H.

Parameters:
xarray_like or LinearOperator or scalar

Array-like input will be interpreted as a 1-D row vector or 2-D matrix (or batch of matrices) depending on its shape. See the Returns section for details.

Returns:
xAarray or LinearOperator

  • For LinearOperator input, operator composition is performed.

  • For scalar input, a lazily scaled operator is returned.

  • Otherwise, the input is expected to take the form of a dense 1-D vector or 2-D matrix (or batch of matrices), interpreted as follows (where self is an M by N linear operator):

    • If x has shape (M,) it is interpreted as a row vector.

    • If x has shape (..., K, M) for some integer K, it is interpreted as a matrix (or batch of matrices if there are batch dimensions).

See also

dot

Multi-purpose multiplication method from the left.

__rmul__

Equivalent method, used by the * operator from the right.

__rmatmul__

Method used by the @ operator from the right which rejects scalar input before calling this method.

BFGSPreconditioner.reset()#

Reset the BFGS preconditioner.

Ditch the current preconditioner matrix estimation and start over with the initial matrix. Resets the index to None.

BFGSPreconditioner.rmatmat(X)#

Adjoint matrix-matrix multiplication.

Performs the operation A^H @ X where A is an M x N linear operator (or batch of linear operators) and X is a dense M x K matrix (or batch of dense matrices). The default implementation defers to the adjoint.

Parameters:
X{matrix, ndarray}

An array with shape (..., M, K) representing the dense matrix (or batch of dense matrices).

Returns:
Y{matrix, ndarray}

An array with shape (..., N, K).

Notes

This method wraps any user-specified rmatmat routine or overridden _rmatmat method to ensure that Y has the correct type.

BFGSPreconditioner.rmatvec(x)#

Adjoint matrix-vector multiplication.

Applies A^H to x, where A is an M x N linear operator (or batch of linear operators) and x is a row vector (or batch of such vectors).

Parameters:
x{matrix, ndarray}

An array with shape (..., M) representing a row vector (or batch of row vectors), or an array with shape (M, 1) representing a column vector.

Added in version 1.18.0: A FutureWarning is now emitted for column vector input of shape (M, 1), for which an array with shape (N, 1) is returned. rmatmat can be called instead for identical behaviour on such input.

Returns:
y{matrix, ndarray}

An array with shape (..., N).

Notes

This method wraps the user-specified rmatvec routine or overridden _rmatvec method to ensure that y has the correct shape and type.

BFGSPreconditioner.transpose()#

Transpose.

Returns:
LinearOperator

Transpose of the linear operator.

See also

T

Equivalent attribute.

BFGSPreconditioner.update(model)#

Update the BFGS preconditioner.

Parameters:
model(n_params,) array

Model array.