`tlm_adjoint.equations`

Module Contents

class tlm_adjoint.equations.EmptyEquation

An adjoint tape record with no associated solution variables.

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.

class tlm_adjoint.equations.Assignment(x, y)

Represents an assignment

\[x = y.\]

The forward residual is defined

\[\mathcal{F} \left( x, y \right) = x - y.\]

Parameters:

x – A variable defining the forward solution \(x\).
y – A variable defining \(y\).

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_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.

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.

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.equations.Conversion(x, y)

Represents degree of freedom assignment

\[\tilde{x} = \tilde{y}\]

where \(\tilde{x}\) and \(\tilde{y}\) are vectors of degrees of freedom for \(x\) and \(y\) respectively. Can be used to convert between different variable types.

The forward residual is defined

\[\mathcal{F} \left( x, y \right) = \tilde{x} - \tilde{y}.\]

Parameters:

x – A variable defining the forward solution \(x\).
y – A variable defining \(y\).

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_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.

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.

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.equations.LinearCombination(x, *args)

Represents an assignment

\[x = \sum_i \alpha_i y_i.\]

The forward residual is defined

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

Parameters:

x – A variable defining the forward solution \(x\).
args – A tuple of two element Sequence objects. The \(i\) th element consists of (alpha_i, y_i), where alpha_i is a scalar corresponding to \(\alpha_i\) and y_i a variable corresponding to \(y_i\).

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_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.

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.

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.equations.Axpy(y_new, y_old, alpha, x)

Represents an assignment

\[y_\text{new} = y_\text{old} + \alpha x.\]

The forward residual is defined

\[\mathcal{F} \left( y_\text{new}, y_\text{old}, x \right) = y_\text{new} - y_\text{old} - \alpha x.\]

Parameters:

y_new – A variable defining the forward solution \(y_\text{new}\).
y_old – A variable defining \(y_\text{old}\).
alpha – A scalar defining \(\alpha\).
x – A variable defining \(x\).

class tlm_adjoint.equations.DotProduct(x, y, z, *, alpha=1.0)

Represents an assignment

\[x = \alpha z^T y.\]

The forward residual is defined

\[\mathcal{F} \left( x, y, z \right) = x - \alpha z^T y.\]

Parameters:

x – A variable whose degrees of freedom define the forward solution \(x\).
y – A variable whose degrees of freedom define \(y\).
z – A variable whose degrees of freedom define \(z\). May be the same variable as y.
alpha – A scalar defining \(\alpha\).

class tlm_adjoint.equations.InnerProduct(x, y, z, *, alpha=1.0, M=None)

Represents an assignment

\[x = \alpha z^* M y.\]

The forward residual is defined

\[\mathcal{F} \left( x, y, z \right) = x - \alpha z^* M y.\]

Parameters:

x – A variable whose degrees of freedom define the forward solution \(x\).
y – A variable whose degrees of freedom define \(y\).
z – A variable whose degrees of freedom define \(z\). May be the same variable as y.
alpha – A scalar defining \(\alpha\).
M – A tlm_adjoint.linear_equation.Matrix defining \(M\). Must have no dependencies. Defaults to an identity matrix.

class tlm_adjoint.equations.MatrixActionRHS(A, X)

Represents a right-hand-side term

\[A x.\]

Parameters:

A – A tlm_adjoint.linear_equation.Matrix defining \(A\).
x – A variable or a Sequence of variables defining \(x\).

drop_references(): Drop references to variables which store values.

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.

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.

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.

class tlm_adjoint.equations.DotProductRHS(x, y, *, alpha=1.0)

Represents a right-hand-side term

\[\alpha y^T x.\]

Parameters:

x – A variable whose degrees of freedom define \(x\).
y – A variable whose degrees of freedom define \(y\). May be the same variable as x.
alpha – A scalar defining \(\alpha\).

drop_references(): Drop references to variables which store values.

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.

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.

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.

class tlm_adjoint.equations.InnerProductRHS(x, y, *, alpha=1.0, M=None)

Represents a right-hand-side term

\[\alpha y^* M x.\]

Parameters:

x – A variable whose degrees of freedom define \(x\).
y – A variable whose degrees of freedom define \(y\). May be the same variable as x.
alpha – A scalar defining \(\alpha\).
M – A tlm_adjoint.linear_equation.Matrix defining \(M\). Must have no dependencies. Defaults to an identity matrix.

drop_references(): Drop references to variables which store values.

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.

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.

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.

tlm_adjoint.equations

Module Contents

`tlm_adjoint.equations`