pyadjoint API reference¶
See also the dolfinadjoint API reference.
Core classes¶

class
pyadjoint.
Tape
(blocks=None)¶ The tape.
The tape consists of blocks,
Block
instances. Each block represents one operation in the forward model.
add_block
(block)¶ Adds a block to the tape and returns the index.

visualise
(output='log', launch_tensorboard=False, open_in_browser=False)¶ Makes a visualisation of the tape as a graph using TensorFlow or GraphViz. (Default: Tensorflow). If output endswith .dot, Graphviz is used.
 Parameters
output (str) – Directory where event files for TensorBoard is stored. Default log.
launch_tensorboard (bool) – Launch TensorBoard in the background. Default False.
open_in_browser (bool) – Opens http://localhost:6006/ in a web browser. Default False.


class
pyadjoint.
Block
¶ Base class for all Tape Block types.
Each instance of a Block type represents an elementary operation in the forward model.
 Abstract methods

classmethod
pop_kwargs
(kwargs)¶ Takes in a dictionary of keyword arguments, and pops the ones used by the Blocksubclass cls

add_dependency
(dep, no_duplicates=False)¶ Adds object to the block dependencies.
Will also save the output if it has not been saved before. Which should only happen if the BlockVariable was not created by a Block (but by the user).
 Parameters
dep (OverloadedType) – The object to be added.
no_duplicates (bool, optional) – If True, the dependency is only added if it is not already in the list. Default is False.

add_output
(obj)¶ Adds object to the block output list.
Will also save the output.
 Parameters
obj (
BlockVariable
) – The object to be added.

evaluate_adj
(markings=False)¶ Computes the adjoint action and stores the result in the adj_value attribute of the dependencies.
This method will by default call the evaluate_adj_component method for each dependency.
 Parameters
markings (bool) – If True, then each block_variable will have set marked_in_path attribute indicating whether their adjoint components are relevant for computing the final target adjoint values. Default is False.

prepare_evaluate_adj
(inputs, adj_inputs, relevant_dependencies)¶ Runs preparations before evalute_adj_component is ran.
The return value is supplied to each of the subsequent evaluate_adj_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.
 Parameters
inputs – The values of the inputs
adj_inputs – The adjoint inputs
relevant_dependencies – A list of the relevant block variables for evaluate_adj_component.
 Returns
Anything. The returned value is supplied to evaluate_adj_component

evaluate_adj_component
(inputs, adj_inputs, block_variable, idx, prepared=None)¶ This method should be overridden.
The method should implement a routine for evaluating the adjoint of the block that corresponds to one dependency. If one considers the adjoint action a vector right multiplied with the Jacobian matrix, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.
 Parameters
inputs (list) – A list of the saved input values, determined by the dependencies list.
adj_inputs (list) – A list of the adjoint input values, determined by the outputs list.
block_variable (BlockVariable) – The block variable of the dependency corresponding to index idx.
idx (int) – The index of the component to compute.
prepared (object) – Anything returned by the prepare_evaluate_adj method. Default is None.
 Returns
The resulting product.
 Return type
An object of a type consistent with the adj_value type of block_variable

evaluate_tlm
(markings=False)¶ Computes the tangent linear action and stores the result in the tlm_value attribute of the outputs.
This method will by default call the evaluate_tlm_component method for each output.
 Parameters
markings (bool) – If True, then each block_variable will have set marked_in_path attribute indicating whether their tlm components are relevant for computing the final target tlm values. Default is False.

prepare_evaluate_tlm
(inputs, tlm_inputs, relevant_outputs)¶ Runs preparations before evalute_tlm_component is ran.
The return value is supplied to each of the subsequent evaluate_tlm_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.
 Parameters
inputs – The values of the inputs
tlm_inputs – The tlm inputs
relevant_outputs – A list of the relevant block variables for evaluate_tlm_component.
 Returns
Anything. The returned value is supplied to evaluate_tlm_component

evaluate_tlm_component
(inputs, tlm_inputs, block_variable, idx, prepared=None)¶ This method should be overridden.
The method should implement a routine for computing the tangent linear model of the block that corresponds to one output. If one considers the tangent linear action as a Jacobian matrix multiplied with a vector, then this method should return one entry in the resulting product, where the entry returned is decided by the argument idx.
 Parameters
inputs (list) – A list of the saved input values, determined by the dependencies list.
tlm_inputs (list) – A list of the tlm input values, determined by the dependencies list.
block_variable (BlockVariable) – The block variable of the output corresponding to index idx.
idx (int) – The index of the component to compute.
prepared (object) – Anything returned by the prepare_evaluate_tlm method. Default is None.
 Returns
The resulting product.
 Return type
An object of the same type as block_variable.saved_output

evaluate_hessian
(markings=False)¶

prepare_evaluate_hessian
(inputs, hessian_inputs, adj_inputs, relevant_dependencies)¶ Runs preparations before evalute_hessian_component is ran for each relevant dependency.
The return value is supplied to each of the subsequent evaluate_hessian_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.
 Parameters
inputs – The values of the inputs
hessian_inputs – The hessian inputs
adj_inputs – The adjoint inputs
relevant_dependencies – A list of the relevant block variables for evaluate_hessian_component.
 Returns
Anything. The returned value is supplied to evaluate_hessian_component

evaluate_hessian_component
(inputs, hessian_inputs, adj_inputs, block_variable, idx, relevant_dependencies, prepared=None)¶ This method must be overridden.
The method should implement a routine for evaluating the hessian of the block. It is preferable that a “ForwardoverReverse” scheme is used. Thus the hessians are evaluated in reverse (starting with the last block on the tape).

recompute
(markings=False)¶  Recomputes the overloaded function with new inputs
and stores the results in the checkpoint attribute of the outputs.
This method will by default call the recompute_component method for each output.
 Parameters
markings (bool) – If True, then each block_variable will have set marked_in_path attribute indicating whether their checkpoints need to be recomputed for recomputing the final target function value. Default is False.

prepare_recompute_component
(inputs, relevant_outputs)¶ Runs preparations before recompute_component is ran.
The return value is supplied to each of the subsequent recompute_component calls. This method is intended to be overridden for blocks that require such preparations, by default there is none.
 Parameters
inputs – The values of the inputs
relevant_outputs – A list of the relevant block variables for recompute_component.
 Returns
Anything. The returned value is supplied to recompute_component

recompute_component
(inputs, block_variable, idx, prepared)¶ This method must be overridden.
The method should implement a routine for recomputing one output of the block in the forward computations. The output to recompute is determined by the idx argument, which corresponds to the index of the output in the outputs list. If the block only has a single output, then idx will always be 0.
 Parameters
inputs (list) – A list of the saved input values, determined by the dependencies list.
block_variable (BlockVariable) – The block variable of the output corresponding to index idx.
idx (int) – The index of the output to compute.
prepared (object) – Anything returned by the prepare_recompute_component method. Default is None.
 Returns
An object of the same type as block_variable.checkpoint which is determined by OverloadedType._ad_create_checkpoint (often the same as block_variable.saved_output): The new output.

class
pyadjoint.block_variable.
BlockVariable
(output)¶ References a block output variable.

class
pyadjoint.
OverloadedType
(*args, **kwargs)¶ Base class for OverloadedType types.
The purpose of each OverloadedType is to extend a type such that it can be referenced by blocks as well as overload basic mathematical operations such as __mul__, __add__, where they are needed.
 Abstract methods:

classmethod
_ad_init_object
(obj)¶ This method will often need to be overridden.
The method should implement a way to reconstruct a new overloaded instance from a (possibly) notoverloaded instance.
 Parameters
obj – An instance of the original type
 Returns
An overloaded instance which is considered the same as obj.
 Return type

_ad_convert_type
(value, options={})¶ This method must be overridden.
Should implement a way to convert the result of an adjoint computation, value, into the same type as self.
 Parameters
value (Any) – The value to convert. Should be a result of an adjoint computation.
options (dict) – A dictionary with options that may be supplied by the user. If the convert type functionality offers some options on how to convert, this is the dictionary that should be used. For an example see fenics_adjoint.types.Function
 Returns
An instance of the same type as self.
 Return type

_ad_create_checkpoint
()¶ This method must be overridden.
Should implement a way to create a checkpoint for the overloaded object. The checkpoint should be returned and possible to restore from in the corresponding _ad_restore_at_checkpoint method.
 Returns
 A checkpoint. Could be of any type, but must be possible
to restore an object from that point.
 Return type
object

_ad_restore_at_checkpoint
(checkpoint)¶ This method must be overridden.
Should implement a way to restore the object at supplied checkpoint. The checkpoint is created from the _ad_create_checkpoint method.
 Returns
The object with same state as at the supplied checkpoint.
 Return type

adj_update_value
(value)¶ This method must be overridden.
The method should implement a routine for assigning a new value to the overloaded object.
 Parameters
value (
object
) – Should be an instance of the OverloadedType.

_ad_mul
(other)¶ This method must be overridden.
The method should implement a routine for multiplying the overloaded object with another object, and return an object of the same type as self.
 Parameters
other (
object
) – The object to be multiplied with this. Should at the very least acceptfloat
andinteger
objects. Returns
 The product of the two objects represented as
an instance of the same subclass of
OverloadedType
as the type of self.
 Return type

_ad_imul
(other)¶ Inplace multiplies self with other.
This method should be overridden if the default behaviour is not compatible with this OverloadedType.
 Parameters
other (object) – The object to multiply self with. Should at the very least accept float objects.
 Returns
None

_ad_add
(other)¶ This method must be overridden.
The method should implement a routine for adding the overloaded object with another object, and return an object of the same type as self.
 Parameters
other (
object
) – The object to be added with this. Should at the very least accept objects of the same type as self. Returns
 The sum of the two objects represented as
an instance of the same subclass of
OverloadedType
as the type of self.
 Return type

_ad_iadd
(other)¶ Inplace adds other to self.
This method should be overridden if the default behaviour is not compatible with this OverloadedType.
 Parameters
other (object) – The object to multiply self with. Should at the very least accept objects of the same type as self.
 Returns
None

_ad_dot
(other)¶ This method must be overridden.
The method should implement a routine for computing the dot product of the overloaded object with another object of the same type, and return a
float
. Parameters
other (
OverloadedType
) – The object to compute the dot product with. Should be of the same type as self. Returns
The dot product of the two objects.
 Return type
float

static
_ad_assign_numpy
(dst, src, offset)¶ This method must be overridden.
The method should implement a routine for assigning the values from a numpy array src to the checkpoint dst. dst should be an instance of the implementing class.
 Parameters
dst (obj) – The object which should be assigned new values. The type will most likely be an OverloadedType or similar.
src (numpy.ndarray) – The numpy array to use as a source for the assignment. src should have the same underlying dimensions as dst.
offset (int) – Start reading dst from offset.
 Returns
 obj: The dst object. If dst is mutable it is preferred to be the same
instance as supplied to the function call. Otherwise a new instance must be initialized and returned with the correct src values.
int: The new offset.
 Return type
tuple

static
_ad_to_list
(m)¶ This method must be overridden.
The method should implement a routine for converting m into a list type. m should be an instance of the same type as the class this method is implemented in. Although maybe the backend version of this class, meaning it is not necessarily an OverloadedType.
 Parameters
m (obj) – The object to be converted into a list.
 Returns
A list representation of the data structure of m.
 Return type
list

_ad_copy
()¶ This method must be overridden.
The method should implement a routine for copying itself.
 Returns
A (deep) copy of self.
 Return type

_ad_dim
()¶ This method must be overridden.
The method should implement a routine for computing the number of components of self.
 Returns
The number of components of self.
 Return type
int
Core utility functions¶

pyadjoint.
get_working_tape
()¶

pyadjoint.
set_working_tape
(tape)¶

pyadjoint.tape.
no_annotations
(function)¶ Decorator to turn off annotation for the decorated function.

class
pyadjoint.
stop_annotating
¶

pyadjoint.
annotate_tape
(kwargs=None)¶ Returns True if annotation flag is on, and False if not.
If kwargs is given, the function will try to extract the annotate keyword. If the annotate keyword is not present it defaults to True. If annotation has been paused, then it will always return False.
 Parameters
kwargs (dict) – A dictionary of keyword arguments to extract from. Note that this should be passed as a dictionary and not actual keyword arguments.
Returns: bool

pyadjoint.overloaded_type.
create_overloaded_object
(obj, suppress_warning=False)¶ Creates an OverloadedType instance corresponding obj.
If an OverloadedType corresponding to obj has not been registered through register_overloaded_type, a RuntimeWarning will be issued.
 Parameters
obj (object) – The object to create an overloaded instance from.
suppress_warning (bool, optional) – When set to True, suppresses warning message when a suitable overloaded class is not found. Default False.
 Returns
OverloadedType

pyadjoint.overloaded_type.
register_overloaded_type
(overloaded_type, classes=None)¶ Register an overloaded type for use in create_overloaded_object
Overloaded types used with this function should have implemented a classmethod _ad_create_object. For usage as a decorator, OverloadedType should be the first base of overloaded_type, and classes the second base.
 Parameters
overloaded_type (type) – The OverloadedType subclass to register.
classes (type, tuple, optional) – The original class/classes that this OverloadedType subclass
overloads. –
 Returns
returns only overloaded_type such that it can be used as a decorator.
 Return type
type
User interface¶

class
pyadjoint.
Control
(control)¶ Defines a control variable from an OverloadedType.
The control object references a specific node on the Tape. For mutable OverloadedType instances the Control only represents the value at the time of initialization.
Example
Given a mutable OverloadedType instance u.
>>> u = MutableFloat(1.0) >>> float(u) 1.0 >>> c1 = Control(u) >>> u.add_in_place(2.0) >>> c2 = Control(u) >>> float(u) 3.0 >>> c1.data() 1.0 >>> c2.data() 3.0
Now c1 represents the node prior to the add_in_place Block, while c2 represents the node after the add_in_place Block. Creating a ReducedFunctional with c2 as Control results in a reduced problem without the add_in_place Block, while a ReducedFunctional with c1 as Control results in a forward model including the add_in_place.
 Parameters
control (OverloadedType) – The OverloadedType instance to define this control from.

pyadjoint.
compute_gradient
(J, m, options=None, tape=None, adj_value=1.0)¶ Compute the gradient of J with respect to the initialisation value of m, that is the value of m at its creation.
 Parameters
J (AdjFloat) – The objective functional.
m (list or instance of Control) – The (list of) controls.
options (dict) – A dictionary of options. To find a list of available options have a look at the specific control type.
tape – The tape to use. Default is the current tape.
 Returns
 The derivative with respect to the control. Should be an instance of the same type as
the control.
 Return type

pyadjoint.
compute_hessian
(J, m, m_dot, options=None, tape=None)¶ Compute the Hessian of J in a direction m_dot at the current value of m
 Parameters
J (AdjFloat) – The objective functional.
m (list or instance of Control) – The (list of) controls.
m_dot (list or instance of the control type) – The direction in which to compute the Hessian.
options (dict) – A dictionary of options. To find a list of available options have a look at the specific control type.
tape – The tape to use. Default is the current tape.
 Returns
 The second derivative with respect to the control in direction m_dot. Should be an instance of
the same type as the control.
 Return type

class
pyadjoint.placeholder.
Placeholder
(obj)¶ A class that functions as a placeholder for block variables (for dependencies).
This means that you can replace the dependency of a Block with another block variable on the fly. Do note that Block outputs can not be placeholders.
The placeholders are useful when you require earlier values in the computational graph to be values computed later in the computational graph from the previous recomputation. This can be the case for the initial guess for iterative solvers. If the recomputations are expected to only slightly change the solution, then using the previously found solution as initial guess can significantly speed up the recomputation.
 Usage:
>>> u = OverloadedType() >>> p = Placeholder(u) >>> v = annotated_operator(u) >>> p.set_value(v)
Each recomputation will now use the previously computed v as input to annotated_operator.

class
pyadjoint.
ReducedFunctional
(functional, controls, scale=1.0, tape=None, eval_cb_pre=<function ReducedFunctional.<lambda>>, eval_cb_post=<function ReducedFunctional.<lambda>>, derivative_cb_pre=<function ReducedFunctional.<lambda>>, derivative_cb_post=<function ReducedFunctional.<lambda>>, hessian_cb_pre=<function ReducedFunctional.<lambda>>, hessian_cb_post=<function ReducedFunctional.<lambda>>)¶ Class representing the reduced functional.
A reduced functional maps a control value to the provided functional. It may also be used to compute the derivative of the functional with respect to the control.
 Parameters
functional (
OverloadedType
) – An instance of an OverloadedType, usuallyAdjFloat
. This should be the return value of the functional you want to reduce.controls (list[Control]) – A list of Control instances, which you want to map to the functional. It is also possible to supply a single Control instance instead of a list.

__call__
(values)¶ Computes the reduced functional with supplied control value.
 Parameters
values ([OverloadedType]) – If you have multiple controls this should be a list of new values for each control in the order you listed the controls to the constructor. If you have a single control it can either be a list or a single object. Each new value should have the same type as the corresponding control.
 Returns
 The computed value. Typically of instance
of
AdjFloat
.
 Return type

derivative
(options={})¶ Returns the derivative of the functional w.r.t. the control.
Using the adjoint method, the derivative of the functional with respect to the control, around the last supplied value of the control, is computed and returned.
 Parameters
options (dict) – A dictionary of options. To find a list of available options have a look at the specific control type.
 Returns
 The derivative with respect to the control.
Should be an instance of the same type as the control.
 Return type

hessian
(m_dot, options={})¶ Returns the action of the Hessian of the functional w.r.t. the control on a vector m_dot.
Using the secondorder adjoint method, the action of the Hessian of the functional with respect to the control, around the last supplied value of the control, is computed and returned.
 Parameters
m_dot ([OverloadedType]) – The direction in which to compute the action of the Hessian.
options (dict) – A dictionary of options. To find a list of available options have a look at the specific control type.
 Returns
 The action of the Hessian in the direction m_dot.
Should be an instance of the same type as the control.
 Return type

optimize_tape
()¶

class
pyadjoint.reduced_functional_numpy.
ReducedFunctionalNumPy
(functional, controls=None, tape=None)¶ This class implements the reduced functional for given functional and controls based on numpy data structures.
This “NumPy version” of the pyadjoint.ReducedFunctional is created from an existing ReducedFunctional object: rf_np = ReducedFunctionalNumPy(rf = rf)

pyadjoint.
taylor_test
(J, m, h, dJdm=None, Hm=0)¶ Run a taylor test on the functional J around point m in direction h.
Given a functional J, a point in control space m, and a direction in control space h, the function computes the taylor remainders and returns the convergence rate.
 Parameters
J (reduced_functional.ReducedFunctional) – The functional to evaluate the taylor remainders of. Must be an instance of
ReducedFunctional
, or something with a similar interface.m (overloaded_type.OverloadedType) – The expansion points in control space. Must be of same type as the control.
h (overloaded_type.OverloadedType) – The direction of perturbations. Must be of same type as the control.
 Returns
The smallest computed convergence rate of the tested perturbations.
 Return type
float