tlm_adjoint.linear_equation

Module Contents

class tlm_adjoint.linear_equation.LinearEquation(X, B, *, A=None, adj_type=None)

Represents the solution of a linear equation

\[A x = \sum_i b_i,\]

with left-hand-side matrix \(A\) and right-hand-side terms \(b_i\). The matrix and right-hand-side terms may depend on other forward variables \(y_i\).

The forward residual is defined

\[\mathcal{F} \left( x, y_1, y_2, \ldots \right) = A x - \sum_i b_i.\]

Parameters:

• X – A variable or a Sequence of variables defining the forward solution x.

• B – A RHS or a Sequence of RHS objects defining the right-hand-side terms.

• A – A tlm_adjoint.linear_equation.Matrix defining the left-hand-side matrix. Defaults to an identity matrix if not supplied.

• adj_type – The space type relative to X of adjoint variables. ‘primal’ or ‘conjugate_dual’, or a Sequence of these. Defaults to ‘primal’ if A is supplied and ‘conjugate_dual’ otherwise.

drop_references()

Drop references to variables which store values.

forward_solve(X, deps=None)

Compute the forward solution.

Can assume that the currently active EquationManager is paused.

Parameters:

• X – A variable if the forward solution has a single component, otherwise a Sequence of variables. May define an initial guess, and should be set by this method. Subclasses may replace this argument with x if the forward solution has a single component.

• deps – A tuple of variables, defining values for dependencies. Only the elements corresponding to X may be modified. self.dependencies() should be used if not supplied.

adjoint_jacobian_solve(adj_X, nl_deps, B)

Compute an adjoint solution.

Parameters:

• adj_X – Either None, or a variable (if the adjoint solution has a single component) or Sequence of variables (otherwise) defining the initial guess for an iterative solve. May be modified or returned. Subclasses may replace this argument with adj_x if the adjoint solution has a single component.

• nl_deps – A Sequence of variables defining values for non-linear dependencies. Should not be modified.

• B – The right-hand-side. A variable (if the adjoint solution has a single component) or Sequence of variables (otherwise) storing the value of the right-hand-side. May be modified or returned. Subclasses may replace this argument with b if the adjoint solution has a single component.

Returns:

A variable or Sequence of variables storing the value of the adjoint solution. May return None to indicate a value of zero.

adjoint_derivative_action(nl_deps, dep_index, adj_X)

Return the action of the adjoint of a derivative of the forward residual on the adjoint solution. This is the negative of an adjoint right-hand-side term.

Parameters:

• nl_deps – A Sequence of variables defining values for non-linear dependencies. Should not be modified.

• dep_index – An int. The derivative is defined by differentiation of the forward residual with respect to self.dependencies()[dep_index].

• adj_X – The adjoint solution. A variable if the adjoint solution has a single component, otherwise a Sequence of variables. Should not be modified. Subclasses may replace this argument with adj_x if the adjoint solution has a single component.

Returns:

The action of the adjoint of a derivative on the adjoint solution. Will be passed to subtract_adjoint_derivative_action(), and valid types depend upon the adjoint variable type. Typically this will be a variable, or a two element tuple (alpha, F), where alpha is a numbers.Complex and F a variable, with the value defined by the product of alpha and F.

tangent_linear(tlm_map)

Derive an Equation corresponding to a tangent-linear operation.

Parameters:

tlm_map – A TangentLinearMap storing values for tangent-linear variables.

Returns:

An Equation, corresponding to the tangent-linear operation.

class tlm_adjoint.linear_equation.Matrix(nl_deps=None, *, ic=True, adj_ic=True)

Represents a matrix \(A\).

This is an abstract base class. Information required by forward, adjoint, and tangent-linear calculations is provided by overloading abstract methods. This class does not inherit from abc.ABC, so that methods may be implemented as needed.

Parameters:

• nl_deps – A Sequence of variables, defining dependencies of the matrix \(A\).

• ic – Whether solution of a linear equation \(A x = b\) for \(x\) uses an initial guess. Defaults to True.

• adj_ic – Whether solution of an adjoint linear equation \(A^* \lambda = b\) for \(\lambda\) uses an initial guess.

drop_references()

Drop references to variables which store values.

nonlinear_dependencies()

Return dependencies of the tlm_adjoint.linear_equation.Matrix.

Returns:

A Sequence of variables defining dependencies.

has_initial_condition()

Return whether solution of a linear equation \(A x = b\) for \(x\) uses an initial guess.

Returns:

True if an initial guess is used, and False otherwise.

adjoint_has_initial_condition()

Return whether solution of an adjoint linear equation \(A^* \lambda = b\) for \(\lambda\) uses an initial guess.

Returns:

True if an initial guess is used, and False otherwise.

abstract forward_action(nl_deps, X, B, *, method='assign')

Evaluate the action of the matrix on \(x\), \(A x\). Assigns the result to B, or adds the result to or subtracts the result from B.

Parameters:

• nl_deps – A Sequence of variables defining values for dependencies. Should not be modified.

• X – Defines \(x\). A variable if it has a single component, and a Sequence of variables otherwise. Should not be modified. Subclasses may replace this argument with x if there is a single component.

• B – Stores the result. A variable if it has a single component, and a Sequence of variables otherwise. Subclasses may replace this argument with b if there is a single component.

• method – If equal to ‘assign’ then this method should set B equal to the result. If equal to ‘add’ then this method should add the result to B. If equal to ‘sub’ then this method should subtract the result from B.

abstract adjoint_action(nl_deps, adj_X, b, b_index=0, *, method='assign')

Evaluate the action of the adjoint of the matrix on \(\lambda\), \(A^* \lambda\). Assigns the b_index th component to b, or adds the b_index th component to or subtracts the b_index th component from b.

Parameters:

• nl_deps – A Sequence of variables defining values for dependencies. Should not be modified.

• adj_X – Defines \(\lambda\). A variable if it has a single component, and a Sequence of variables otherwise. Should not be modified. Subclasses may replace this argument with adj_x if there is a single component.

• b – A variable storing the result. Should be updated by this method.

• b_index – The component of the result which should be used to update b.

• method – If equal to ‘assign’ then this method should set b equal to the b_index th component of the result. If equal to ‘add’ then this method should add the b_index th component of the result to b. If equal to ‘sub’ then this method should subtract the b_index th component of the result from b.

abstract forward_solve(X, nl_deps, B)

Solve the linear system \(A x = b\) for \(x\).

Parameters:

• X – The solution \(x\). A variable if it has a single component, and a Sequence of variables otherwise. May define an initial guess. Subclasses may replace this argument with x if there is a single component.

• nl_deps – A Sequence of variables defining values for dependencies. Should not be modified.

• B – The right-hand-side \(b\). A variable if it has a single component, and a Sequence of variables otherwise. Should not be modified. Subclasses may replace this argument with b if there is a single component.

abstract adjoint_derivative_action(nl_deps, nl_dep_index, X, adj_X, b, *, method='assign')

Evaluate the action of the adjoint of a derivative of \(A x\) on an adjoint variable. Assigns the result to b, or adds the result to or subtracts the result from b.

Parameters:

• nl_deps – A Sequence of variables defining values for dependencies. Should not be modified.

• nl_deps_index – An int. The derivative is defined by differentiation of \(A x\) with respect to self.nonlinear_dependencies()[nl_dep_index].

• X – Defines \(x\). A variable if it has a single component, and a Sequence of variables otherwise. Should not be modified. Subclasses may replace this argument with x if there is a single component.

• adj_X – The adjoint variable. A variable if it has a single component, and Sequence of variables otherwise. Should not be modified. Subclasses may replace this argument with adj_x if the adjoint variable has a single component.

• b – A variable storing the result. Should be updated by this method.

• method – If equal to ‘assign’ then this method should set b equal to the result. If equal to ‘add’ then this method should add the result to b. If equal to ‘sub’ then this method should subtract the result from b.

abstract adjoint_solve(adj_X, nl_deps, B)

Solve the linear system \(A^* \lambda = b\) for \(\lambda\).

Parameters:

• adj_X – The solution \(\lambda\). A variable if it has a single component, and a Sequence of variables otherwise. May define an initial guess. Subclasses may replace this argument with adj_x if there is a single component.

• nl_deps – A Sequence of variables defining values for dependencies. Should not be modified.

• B – The right-hand-side \(b\). A variable if it has a single component, and a Sequence of variables otherwise. Should not be modified. Subclasses may replace this argument with b if there is a single component.

abstract tangent_linear_rhs(tlm_map, X)

Construct tangent-linear right-hand-side terms obtained by differentiation of

\[\mathcal{G} \left( x, y_1, y_2, \ldots \right) = -A x\]

with respect to dependencies of the matrix \(A\). i.e. construct

\[-\sum_i \frac{\partial \mathcal{G}}{\partial y_i} \tau_{y_i},\]

where \(\tau_{y_i}\) is the tangent-linear variable associated with the dependency \(y_i\). Note the negative sign. Does not include the term \(-A \tau_x\) where \(\tau_x\) is the tangent-linear variable associated with \(x\).

Parameters:

• tlm_map – A TangentLinearMap storing values for tangent-linear variables.

• X – Defines \(x\). A variable if it has a single component, and a Sequence of variables otherwise. Subclasses may replace this argument with x if there is a single component.

Returns:

A RHS, or a Sequence of RHS objects, defining the right-hand-side terms. Returning None indicates that there are no terms.

class tlm_adjoint.linear_equation.RHS(deps, nl_deps=None)

Represents a right-hand-side term.

This is an abstract base class. Information required by forward, adjoint, and tangent-linear calculations is provided by overloading abstract methods. This class does not inherit from abc.ABC, so that methods may be implemented as needed.

Parameters:

• deps – A Sequence of variables defining dependencies.

• nl_deps – A Sequence of variables defining non-linear dependencies.

drop_references()

Drop references to variables which store values.

dependencies()

Return dependencies of the RHS.

Returns:

A Sequence of variables defining dependencies.

nonlinear_dependencies()

Return non-linear dependencies of the RHS.

Returns:

A Sequence of variables defining non-linear dependencies.

abstract add_forward(B, deps)

Add the right-hand-side term to B.

Parameters:

• B – A variable if it has a single component, and a Sequence of variables otherwise. Should be updated by the addition of this RHS. Subclasses may replace this argument with b if there is a single component.

• deps – A Sequence of variables defining values for dependencies. Should not be modified.

abstract subtract_adjoint_derivative_action(nl_deps, dep_index, adj_X, b)

Subtract the action of the adjoint of a derivative of the right-hand-side term, on an adjoint variable, from b.

Parameters:

• nl_deps – A Sequence of variables defining values for non-linear dependencies. Should not be modified.

• deps_index – An int. The derivative is defined by differentiation of the right-hand-side term with respect to self.dependencies()[dep_index].

• adj_X – The adjoint variable. A variable if it has a single component, and a Sequence of variables otherwise. Should not be modified. Subclasses may replace this argument with adj_x if the adjoint variable has a single component.

• b – A variable storing the result. Should be updated by subtracting the action of the adjoint of the right-hand-side term on the adjoint variable.

abstract tangent_linear_rhs(tlm_map)

Construct tangent-linear right-hand-side terms obtained by differentiation of this right-hand-side term. That is, construct

\[\sum_i \frac{\partial b}{\partial y_i} \tau_{y_i},\]

where \(b\) is this right-hand-side term, and \(\tau_{y_i}\) is the tangent-linear variable associated with a dependency \(y_i\).

Parameters:

tlm_map – A TangentLinearMap storing values for tangent-linear variables.

Returns:

A RHS, or a Sequence of RHS objects, defining the right-hand-side terms. Returning None indicates that there are no terms.