firedrake.external_operators package

Submodules

firedrake.external_operators.abstract_external_operators module

class firedrake.external_operators.abstract_external_operators.AbstractExternalOperator(*operands, function_space, derivatives=None, argument_slots=(), operator_data=None)

Bases: ExternalOperator

External operator base class providing the interface to build new external operators.

The AbstractExternalOperator encapsulates the external operator abstraction and is compatible with UFL symbolic operations, the Firedrake assembly, and the AD capabilities provided by ~.firedrake.adjoint. The AbstractExternalOperator class orchestrates the external operator assembly by linking the finite element assembly to the assembly implementations specified by the external operator subclasses.

Parameters:

• *operands (ufl.core.expr.Expr or ufl.form.BaseForm) – Operands of the external operator.

• function_space (firedrake.functionspaceimpl.WithGeometryBase) – The function space the external operator is mapping to.

• derivatives (tuple) – Tuple specifiying the derivative multiindex.

• *argument_slots (ufl.coefficient.BaseCoefficient or ufl.argument.BaseArgument) – Tuple containing the arguments of the linear form associated with the external operator, i.e. the arguments with respect to which the external operator is linear. Those arguments can be ufl.Argument objects, as a result of differentiation, or ufl.Coefficient objects, as a result of taking the action on a given function.

• operator_data (dict) – Dictionary containing the data of the external operator, i.e. the external data specific to the external operator subclass considered. This dictionary will be passed on over the UFL symbolic reconstructions making the operator data accessible to the external operators arising from symbolic operations on the original operator, such as the Jacobian of the external operator.

assemble(assembly_opts=None)

External operator assembly

Parameters:

assembly_opts (dict) – Dictionary containing assembly options of the finite element assembly, which may be of interest for the assembly methods of the external operator subclass. These options are passed on to the assembly methods of the external operator subclass.

Returns:

The result of assembling the external operator.

Return type:

firedrake.function.Function or firedrake.cofunction.Cofunction or firedrake.matrix.MatrixBase

Notes

More information can be found at www.firedrakeproject.org/external_operators.html#assembly.

assemble_method(args)

Decorator helper function to specify the type of external operator type associated with each assembly methods.

The assemble_method decorator is used to specify the type of external operator associated with the assembly methods of the external operator subclass. Each assembly method must be decorated with assemble_method. The role of this decorator is to record the assembly methods of the subclass. The type of external operator is fully specified via the derivative multi-index and a tuple representing the argument slots of the external operator.

Parameters:

• derivs (tuple) – Derivative multi-index of the external operator associated with the assembly method decorated.

• args (tuple) – Tuple representing the argument slots of the external operator, i.e. self.argument_slots(), in which integers stand for the numbers of the arguments of type Argument or Coargument, and None stands for arguments of type Function or Cofunction.

Notes

More information can be found at www.firedrakeproject.org/external_operators.html#build-your-own-external-operator.

function_space()

ufl_operands

class firedrake.external_operators.abstract_external_operators.AssemblyRegisterMetaClass(name, bases, attrs)

Bases: UFLType

Metaclass registering assembly methods specified by external operator subclasses.

This metaclass is used to register assembly methods specified by subclasses of AbstractExternalOperator. For any new external operator subclass, AssemblyRegisterMetaClass will collect all assembly methods specified by the subclass and construct a registry to map from assembly identifiers, specified via the assemble_method decorator to the corresponding assembly methods, and attach that registry to the subclass.

Notes

This metaclass subclasses UFLType to avoid metaclass conflict for AbstractExternalOperator.

firedrake.external_operators.abstract_external_operators.assemble_method(derivs, args)

Decorator helper function to specify the type of external operator type associated with each assembly methods.

The assemble_method decorator is used to specify the type of external operator associated with the assembly methods of the external operator subclass. Each assembly method must be decorated with assemble_method. The role of this decorator is to record the assembly methods of the subclass. The type of external operator is fully specified via the derivative multi-index and a tuple representing the argument slots of the external operator.

Parameters:

• derivs (tuple) – Derivative multi-index of the external operator associated with the assembly method decorated.

• args (tuple) – Tuple representing the argument slots of the external operator, i.e. self.argument_slots(), in which integers stand for the numbers of the arguments of type Argument or Coargument, and None stands for arguments of type Function or Cofunction.

Notes

More information can be found at www.firedrakeproject.org/external_operators.html#build-your-own-external-operator.

firedrake.external_operators.ml_operator module

class firedrake.external_operators.ml_operator.MLOperator(*operands, function_space, derivatives=None, argument_slots=(), operator_data)

Bases: AbstractExternalOperator

External operator base class representing machine learning models implemented in a given

machine learning framework.

The MLOperator allows users to embed machine learning models implemented in a given machine learning framework into PDE systems implemented in Firedrake. The actual evaluation of the MLOperator subclass is delegated to the specified ML model using the ML framework considered.

Parameters:

• *operands (ufl.core.expr.Expr or ufl.form.BaseForm) – Operands of the ML operator.

• function_space (firedrake.functionspaceimpl.WithGeometryBase) – The function space the ML operator is mapping to.

• derivatives (tuple) – Tuple specifiying the derivative multiindex.

• *argument_slots (ufl.coefficient.BaseCoefficient or ufl.argument.BaseArgument) – Tuple containing the arguments of the linear form associated with the ML operator, i.e. the arguments with respect to which the ML operator is linear. Those arguments can be ufl.Argument objects, as a result of differentiation, or ufl.Coefficient objects, as a result of taking the action on a given function.

• operator_data (dict) – Dictionary to stash external data specific to the ML operator. This dictionary must at least contain the following: (i) ‘model’: The machine learning model implemented in the ML framework considered. (ii) ‘inputs_format’: The format of the inputs to the ML model: 0 for models acting globally on the inputs, 1 when acting locally/pointwise on the inputs. Other strategies can also be considered by subclassing the MLOperator class.

assemble_jacobian(*args, **kwargs)

Assemble the Jacobian using the AD engine of the ML framework.

assemble_jacobian_action(*args, **kwargs)

Assemble the Jacobian action using the AD engine of the ML framework.

assemble_jacobian_adjoint(*args, **kwargs)

Assemble the Jacobian Hermitian transpose using the AD engine of the ML framework.

assemble_jacobian_adjoint_action(*args, **kwargs)

Assemble the action of the Jacobian adjoint using the AD engine of the ML framework.

assemble_model(*args, **kwargs)

Assemble the operator via a forward pass through the ML model.

property inputs_format

property model

ufl_operands

firedrake.external_operators.point_expr_operator module

class firedrake.external_operators.point_expr_operator.PointexprOperator(*operands, function_space, derivatives=None, argument_slots=(), operator_data)

Bases: AbstractExternalOperator

External operator representing UFL expressions.

Parameters:

• *operands (ufl.core.expr.Expr or ufl.form.BaseForm) – Operands of the external operator.

• function_space (firedrake.functionspaceimpl.WithGeometryBase) – The function space the external operator is mapping to.

• derivatives (tuple) – Tuple specifiying the derivative multiindex.

• *argument_slots (ufl.coefficient.BaseCoefficient or ufl.argument.BaseArgument) – Tuple containing the arguments of the linear form associated with the external operator, i.e. the arguments with respect to which the external operator is linear. Those arguments can be ufl.Argument objects, as a result of differentiation, or ufl.Coefficient objects, as a result of taking the action on a given function.

• operator_data (dict) – Dictionary to stash external data specific to the PointexprOperator class. This dictionary must at least contain the following: - ‘func’: The function implementing the pointwise expression.

Notes

The PointexprOperator class mimics the Interpolate class and is mostly design for debugging purposes.

assemble_Jacobian(*args, assembly_opts, **kwargs)

assemble_Jacobian_action(*args, **kwargs)

assemble_Jacobian_adjoint(*args, assembly_opts, **kwargs)

assemble_Jacobian_adjoint_action(*args, **kwargs)

assemble_operator(*args, **kwargs)

property expr

ufl_operands

firedrake.external_operators.point_expr_operator.point_expr(point_expr, function_space)

Helper function for instantiating the PointexprOperator class.

This function facilitates having a two-stage instantiation which dissociates between class arguments that are fixed, such as the function space and the input function, and the operands of the operator, which may change, e.g. when the operator is used in a time-loop.

Example

# Stage 1: Partially initialise the operator.
N = point_expr(lambda x, y: x - y, function_space=V)
# Stage 2: Define the operands and use the operator in a UFL expression.
F = (inner(grad(u), grad(v)) + inner(N(u, f), v)) * dx

Parameters:

• point_expr (collections.abc.Callable) – A function expression (e.g. lambda expression)

• function_space (firedrake.functionspaceimpl.WithGeometryBase) – The function space into which the input expression needs to be interpolated.

Returns:

The partially initialised PointexprOperator class.

Return type:

collections.abc.Callable

Module contents