tlm_adjoint.overloaded_float

This module defines types which allow for basic floating point level algorithmic differentiation. The implementation is intended to be used for a small number of calculations, for example after the calculation of a functional obtained from a finite element model.

For example, if annotation and operator overloading is enabled

import numpy as np

x = Float(np.pi, name='x')
y = x * np.sin(x)

will lead to annotation of equations associated with the floating point calculations.

Module Contents

tlm_adjoint.overloaded_float.set_default_float_dtype(dtype)

Set the default data type used by SymbolicFloat objects.

Parameters:

dtype – The default data type.

class tlm_adjoint.overloaded_float.FloatSpace(float_cls=None, *, dtype=None, comm=None)

Defines the real or complex space.

Parameters:

• float_cls – The SymbolicFloat class, in particular used to instantiate new variables in space_new(). Defaults to SymbolicFloat.

• dtype – The data type associated with the space. Typically numpy.double or numpy.cdouble.

• comm – The communicator associated with the space.

property dtype

The data type associated with the space.

property comm

The communicator associated with the space.

property float_cls

The SymbolicFloat class associated with the space.

rdtype()

The real data type associated with the space.

tlm_adjoint.overloaded_float.no_float_overloading(fn)

Decorator to disable OverloadedFloat operator overloading.

Parameters:

fn – A callable for which OverloadedFloat operator overloading should be disabled.

Returns:

A callable for which OverloadedFloat operator overloading is disabled.

tlm_adjoint.overloaded_float.paused_float_overloading()

Construct a context manager which can be used to temporarily disable OverloadedFloat operator overloading.

Returns:

A context manager which can be used to temporarily disable OverloadedFloat operator overloading.

class tlm_adjoint.overloaded_float.SymbolicFloat(value=0.0, *, name=None, space_type='primal', static=False, cache=None, dtype=None, comm=None)

A sympy.core.symbol.Symbol which is also a ‘variable’, defining a scalar variable.

If constructing SymPy expressions then the SymbolicFloat class should be used instead of the OverloadedFloat subclass, or else OverloadedFloat operator overloading should be disabled.

Parameters:

• value – A numbers.Complex or sympy.core.expr.Expr defining the initial value. If a sympy.core.expr.Expr then, if annotation or derivation and solution of tangent-linear equations is enabled, an assignment is processed by the EquationManager manager.

• name – A str name for the SymbolicFloat.

• space_type – The space type for the SymbolicFloat. ‘primal’, ‘dual’, ‘conjugate’, or ‘conjugate_dual’.

• static – Defines whether the SymbolicFloat is static, meaning that it is stored by reference in checkpointing/replay, and an associated tangent-linear variable is zero.

• cache – Defines whether results involving the SymbolicFloat may be cached. Default static.

• dtype – The data type associated with the SymbolicFloat. Typically numpy.double or numpy.cdouble.

• comm – The communicator associated with the SymbolicFloat.

property value

Return the current value associated with the SymbolicFloat.

The value may also be accessed by casting using float or complex.

Returns:

The value.

new(value=0.0, *, name=None, static=False, cache=None)

Return a new object, which same type and space type as this SymbolicFloat.

Returns:

The new SymbolicFloat.

Arguments are as for the SymbolicFloat constructor.

assign(y)

SymbolicFloat assignment.

Parameters:

y – A numbers.Complex or sympy.core.expr.Expr defining the value.

Returns:

The SymbolicFloat.

addto(y)

SymbolicFloat in-place addition.

Parameters:

y – A numbers.Complex or sympy.core.expr.Expr defining the value to add.

class tlm_adjoint.overloaded_float.OverloadedFloat(value=0.0, *, name=None, space_type='primal', static=False, cache=None, dtype=None, comm=None)

A subclass of SymbolicFloat with operator overloading.

If constructing SymPy expressions then the SymbolicFloat class should be used instead of the OverloadedFloat subclass, or else OverloadedFloat operator overloading should be disabled.

For argument documentation see SymbolicFloat.

class tlm_adjoint.overloaded_float.Float(value=0.0, *, name=None, space_type='primal', static=False, cache=None, dtype=None, comm=None)

A subclass of SymbolicFloat with operator overloading.

If constructing SymPy expressions then the SymbolicFloat class should be used instead of the OverloadedFloat subclass, or else OverloadedFloat operator overloading should be disabled.

For argument documentation see SymbolicFloat.

class tlm_adjoint.overloaded_float.FloatEquation(x, expr)

Represents an assignment to a SymbolicFloat x,

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

for some \(\mathcal{G}\) defined by a sympy.core.expr.Expr. The forward residual is defined

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

Parameters:

• x – A SymbolicFloat defining the forward solution \(x\)

• expr – A sympy.core.expr.Expr defining the right-hand-side.

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.

subtract_adjoint_derivative_actions(adj_x, nl_deps, dep_Bs)

Subtract terms from other adjoint right-hand-sides.

Can be overridden for an optimized implementation, but otherwise uses Equation.adjoint_derivative_action().

Parameters:

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

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

• dep_Bs – A Mapping whose items are (dep_index, dep_B). Each dep_B is an AdjointRHS which should be updated by subtracting adjoint derivative information computed by differentiating with respect to self.dependencies()[dep_index].

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.

tlm_adjoint.overloaded_float.to_float(y, *, name=None)

Convert a variable to a Float.

Parameters:

• y – A scalar variable.

• name – A str name.

Returns:

The SymbolicFloat.