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)[source]¶
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. TheAbstractExternalOperator
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)[source]¶
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)[source]¶
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
orCoargument
, and None stands for arguments of typeFunction
orCofunction
.
Notes
More information can be found at www.firedrakeproject.org/external_operators.html#build-your-own-external-operator.
- ufl_operands¶
- class firedrake.external_operators.abstract_external_operators.AssemblyRegisterMetaClass(name, bases, attrs)[source]¶
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
orCoargument
, and None stands for arguments of typeFunction
orCofunction
.
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)[source]¶
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 theMLOperator
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)[source]¶
Assemble the Jacobian using the AD engine of the ML framework.
- assemble_jacobian_action(*args, **kwargs)[source]¶
Assemble the Jacobian action using the AD engine of the ML framework.
- assemble_jacobian_adjoint(*args, **kwargs)[source]¶
Assemble the Jacobian Hermitian transpose using the AD engine of the ML framework.
- assemble_jacobian_adjoint_action(*args, **kwargs)[source]¶
Assemble the action of the Jacobian adjoint using the AD engine of the ML framework.
- assemble_model(*args, **kwargs)[source]¶
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)[source]¶
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 theInterpolate
class and is mostly design for debugging purposes.- property expr¶
- ufl_operands¶
- firedrake.external_operators.point_expr_operator.point_expr(point_expr, function_space)[source]¶
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: