tlm_adjoint.fixed_point

Module Contents

class tlm_adjoint.fixed_point.CustomNormSq(eqs, *, norm_sqs=None, adj_norm_sqs=None)

Defines the square of the norm of forward and adjoint solutions.

Callables are used to define squared norms for the forward and adjoint solutions of equations. The total squared norm is then the sum of the squares.

Parameters:

  • eqs – A Sequence of Equation objects.

  • norm_sqs – A Sequence. Each element is either a callable, or a Sequence of callables. The callables define the squared norm associated with the corresponding components of the forward solution for the corresponding Equation in eqs. Each callable accepts a single variable and returns a float. Defaults to the square of the \(l_2\) norm of the degrees of freedom vector.

  • adj_norm_sqs – A Sequence. Each element is either a callable, or a Sequence of callables. The callables define the squared norm associated with the corresponding components of the adjoint solution for the corresponding Equation in eqs. Each callable accepts a single variable and returns a float. Defaults to the square of the \(l_2\) norm of the degrees of freedom vector.

class tlm_adjoint.fixed_point.FixedPointSolver(eqs, solver_parameters, *, norm_sqs=None, adj_norm_sqs=None)

A fixed-point solver. Solves the given equations in sequence until either an absolute or relative tolerance is reached.

Derives tangent-linear and adjoint information using the approach described in:

  • Jean Charles Gilbert, ‘Automatic differentiation and iterative processes’, Optimization Methods and Software, 1(1), pp. 13–21, 1992, doi: 10.1080/10556789208805503

  • Bruce Christianson, ‘Reverse accumulation and attractive fixed points’, Optimization Methods and Software, 3(4), pp. 311–326, 1994, doi: 10.1080/10556789408805572

Parameters:

  • eqs – A Sequence of Equation objects. One forward iteration consists of computing, in order, a forward solution for all Equation objects.

  • solver_parameters –

    A Mapping defining solver parameters. Parameters (a number of which are based on KrylovSolver parameters in FEniCS 2017.2.0) are:

    • absolute_tolerance: A float defining the absolute tolerance for a change in the solution in one iteration. Required.

    • relative_tolerance: A float defining the relative tolerance for a change in the solution in one iteration. Required.

    • maximum_iterations: An int defining the maximum permitted iterations. Defaults to 1000.

    • nonzero_initial_guess: A bool indicating whether to use a non-zero initial guess in a forward solve. Defaults to True.

    • adjoint_nonzero_initial_guess: A bool indicating whether to use a non-zero initial guess in an adjoint solve. Defaults to True.

  • norm_sqs – Defines the squared norm used to test for convergence in a forward solve. See CustomNormSq.

  • adj_norm_sqs – Defines the squared norm used to test for convergence in an adjoint solve. See CustomNormSq.

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.

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.