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 or a
Sequence
of variables storing the solution. May define an initial guess, and should be set by this method.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 or a
Sequence
of variables storing the solution. May define an initial guess, and should be set by this method.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 or a
Sequence
of variables. Should not be modified.
- 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 elementtuple
(alpha, F), where alpha is anumbers.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 or
Sequence
of variables defining the initial guess for an iterative solve. May be modified or returned.nl_deps – A
Sequence
of variables defining values for non-linear dependencies. Should not be modified.B – The right-hand-side. A variable or
Sequence
of variables storing the value of the right-hand-side. May be modified or returned.
- 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 or a
Sequence
of variables storing the solution. May define an initial guess, and should be set by this method.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 or a
Sequence
of variables. Should not be modified.
- 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 elementtuple
(alpha, F), where alpha is anumbers.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 or
Sequence
of variables defining the initial guess for an iterative solve. May be modified or returned.nl_deps – A
Sequence
of variables defining values for non-linear dependencies. Should not be modified.B – The right-hand-side. A variable or
Sequence
of variables storing the value of the right-hand-side. May be modified or returned.
- 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 elementSequence
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 or a
Sequence
of variables storing the solution. May define an initial guess, and should be set by this method.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 or a
Sequence
of variables. Should not be modified.
- 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 elementtuple
(alpha, F), where alpha is anumbers.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 or
Sequence
of variables defining the initial guess for an iterative solve. May be modified or returned.nl_deps – A
Sequence
of variables defining values for non-linear dependencies. Should not be modified.B – The right-hand-side. A variable or
Sequence
of variables storing the value of the right-hand-side. May be modified or returned.
- 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.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 thisRHS
. 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 aSequence
ofRHS
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 thisRHS
. 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 aSequence
ofRHS
objects, defining the right-hand-side terms. Returning None indicates that there are no terms.