UFL Core

ufl.core.base_form_operator

Base form operator.

This module defines the BaseFormOperator class, which is the base class for objects that can be seen as forms and as operators such as ExternalOperator or Interpolate.

class ufl.core.base_form_operator.BaseFormOperator(*operands, function_space, derivatives=None, argument_slots=())

Bases: Operator, BaseForm, Counted

Base form operator.

Initialise.

Parameters:

• operands – operands on which acts the operator.

• function_space – the FunctionSpace or MixedFunctionSpace on which to build this Function.

• derivatives – tuple specifying the derivative multiindex.

• argument_slots – tuple composed containing expressions with ufl.Argument or ufl.Coefficient objects.

argument_slots(outer_form=False)

Returns a tuple of expressions containing argument and coefficient based expressions.

We get an argument uhat when we take the Gateaux derivative in the direction uhat: d/du N(u; v*) = dNdu(u; uhat, v*) where uhat is a ufl.Argument and v* a ufl.Coargument Applying the action replace the last argument by coefficient: action(dNdu(u; uhat, v*), w) = dNdu(u; w, v*) where du is a ufl.Coefficient.

coefficients()

Return all BaseCoefficient objects found in base form operator.

count()

Return the count associated to the base form operator.

ufl_free_indices: tuple[int, ...] = ()

ufl_function_space()

Return the function space associated to the operator.

I.e. return the dual of the base form operator’s Coargument space.

ufl_index_dimensions = ()

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...]

property ufl_shape

Return the UFL shape of the coefficient produced by the operator.

ufl.core.expr

This module defines the Expr class, the superclass for all expression tree node types in UFL.

NB: A note about other operators not implemented here:

More operators (special functions) on Expr instances are defined in exproperators.py, as well as the transpose A.T and spatial derivative a.dx(i). This is to avoid circular dependencies between Expr and its subclasses.

class ufl.core.expr.Expr

Bases: object

Base class for all UFL expression types.

Instance properties

Every Expr instance will have certain properties. The most important ones are ufl_operands, ufl_shape, ufl_free_indices, and ufl_index_dimensions properties. Expressions are immutable and hashable.

Type traits

The Expr API defines a number of type traits that each subclass needs to provide. Most of these are specified indirectly via the arguments to the ufl_type class decorator, allowing UFL to do some consistency checks and automate most of the traits for most types. Type traits are accessed via a class or instance object of the form obj._ufl_traitname_. See the source code for description of each type trait.

Operators

Some Python special functions are implemented in this class, some are implemented in subclasses, and some are attached to this class in the ufl_type class decorator.

Defining subclasses

To define a new expression class, inherit from either Terminal or Operator, and apply the ufl_type class decorator with suitable arguments. See the docstring of ufl_type for details on its arguments. Looking at existing classes similar to the one you wish to add is a good idea. Looking through the comments in the Expr class and ufl_type to understand all the properties that may need to be specified is also a good idea. Note that many algorithms in UFL and form compilers will need handlers implemented for each new type::.

@ufl_type()
class MyOperator(Operator):
    pass

Type collections

All Expr subclasses are collected by ufl_type in global variables available via Expr.

Profiling

Object creation statistics can be collected by doing

Expr.ufl_enable_profiling()
# ... run some code
initstats, delstats = Expr.ufl_disable_profiling()

Giving a list of creation and deletion counts for each typecode.

Initialise.

property T

Transpose a rank-2 tensor expression.

For more general transpose operations of higher order tensor expressions, use indexing and Tensor.

dx(*ii)

Return the partial derivative with respect to spatial variable number ii.

evaluate(x, mapping, component, index_values)

Evaluate expression at given coordinate with given values for terminals.

static ufl_disable_profiling()

Turn off the object counting mechanism. Return object init and del counts.

ufl_domain()

Return the single unique domain this expression is defined on, or throw an error.

ufl_domains()

Return all domains this expression is defined on.

static ufl_enable_profiling()

Turn on the object counting mechanism and reset counts to zero.

ufl_free_indices: tuple[int, ...]

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...]

ufl_shape: tuple[int, ...]

class ufl.core.expr.UFLObject

Bases: ABC

A UFL Object.

class ufl.core.expr.UFLType

Bases: type

Base class for all UFL types.

Equip UFL types with some ufl specific properties.

ufl.core.expr.ufl_err_str(expr)

Return a UFL error string.

ufl.core.expr.update_ufl_type_attributes(cls)

Update UFL type attributes.

ufl.core.external_operator

External operator.

This module defines the ExternalOperator class, which symbolically represents operators that are not straightforwardly expressible in UFL. Subclasses of ExternalOperator must define how this operator should be evaluated as well as its derivatives from a given set of operands.

class ufl.core.external_operator.BaseFormOperator(*operands, function_space, derivatives=None, argument_slots=())

Bases: Operator, BaseForm, Counted

Base form operator.

Initialise.

Parameters:

• operands – operands on which acts the operator.

• function_space – the FunctionSpace or MixedFunctionSpace on which to build this Function.

• derivatives – tuple specifying the derivative multiindex.

• argument_slots – tuple composed containing expressions with ufl.Argument or ufl.Coefficient objects.

argument_slots(outer_form=False)

Returns a tuple of expressions containing argument and coefficient based expressions.

We get an argument uhat when we take the Gateaux derivative in the direction uhat: d/du N(u; v*) = dNdu(u; uhat, v*) where uhat is a ufl.Argument and v* a ufl.Coargument Applying the action replace the last argument by coefficient: action(dNdu(u; uhat, v*), w) = dNdu(u; w, v*) where du is a ufl.Coefficient.

coefficients()

Return all BaseCoefficient objects found in base form operator.

count()

Return the count associated to the base form operator.

ufl_free_indices: tuple[int, ...] = ()

ufl_function_space()

Return the function space associated to the operator.

I.e. return the dual of the base form operator’s Coargument space.

ufl_index_dimensions = ()

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...]

property ufl_shape

Return the UFL shape of the coefficient produced by the operator.

class ufl.core.external_operator.ExternalOperator(*operands, function_space, derivatives=None, argument_slots=())

Bases: BaseFormOperator

External operator.

Initialise.

Parameters:

• operands – operands on which acts the ExternalOperator.

• function_space – the FunctionSpace, or MixedFunctionSpace on which to build this Function.

• derivatives – tuple specifying the derivative multiindex.

• argument_slots – tuple composed containing expressions with ufl.Argument or ufl.Coefficient objects.

assemble(*args, **kwargs)

Assemble the external operator.

grad()

Returns the symbolic grad of the external operator.

ufl_element()

Shortcut to get the finite element of the function space of the external operator.

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...]

ufl.core.external_operator.ufl_type(is_abstract=False, is_terminal=None, is_scalar=False, is_index_free=False, is_shaping=False, is_literal=False, is_terminal_modifier=False, is_in_reference_frame=False, is_restriction=False, is_evaluation=False, is_differential=None, use_default_hash=True, num_ops=None, inherit_shape_from_operand=None, inherit_indices_from_operand=None, wraps_type=None, unop=None, binop=None, rbinop=None)

Decorator to apply to every subclass in the UFL Expr and BaseForm hierarchy.

This decorator contains a number of checks that are intended to enforce uniform behaviour across UFL types.

The rationale behind the checks and the meaning of the optional arguments should be sufficiently documented in the source code below.

ufl.core.multiindex

This module defines the single index types and some internal index utilities.

class ufl.core.multiindex.Counted(count=None, counted_class=None)

Bases: object

Mixin class for globally counted objects.

Initialize the Counted instance.

Parameters:

• count – The object count, if None defaults to the next value according to the global counter (per type).

• counted_class – Class to attach the global counter too. If None then type(self) will be used.

count()

Get count.

class ufl.core.multiindex.FixedIndex(value)

Bases: IndexBase

UFL value: An index with a specific value assigned.

Initialise.

class ufl.core.multiindex.Index(count=None)

Bases: IndexBase, Counted

UFL value: An index with no value assigned.

Used to represent free indices in Einstein indexing notation.

Initialise.

class ufl.core.multiindex.IndexBase

Bases: object

Base class for all indices.

Initialise.

class ufl.core.multiindex.MultiIndex(indices)

Bases: Terminal

Represents a sequence of indices, either fixed or free.

Initialise.

evaluate(x, mapping, component, index_values)

Evaluate index.

indices()

Return tuple of indices.

is_cellwise_constant()

Check if cellwise constant.

Always True.

ufl_domains()

Return tuple of domains related to this terminal object.

property ufl_free_indices

Get the UFL free indices.

This should not be used.

property ufl_index_dimensions

Get the UFL index dimensions.

This should not be used.

property ufl_shape

Get the UFL shape.

This should not be used.

class ufl.core.multiindex.Terminal

Bases: Expr

Base class for terminal objects.

A terminal node in the UFL expression tree.

Initialise the terminal.

evaluate(x, mapping, component, index_values, derivatives=())

Get self from mapping and return the component asked for.

ufl_domains()

Return tuple of domains related to this terminal object.

ufl_free_indices: tuple[int, ...] = ()

ufl_index_dimensions = ()

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...] = ()

ufl_shape: tuple[int, ...]

ufl.core.multiindex.indices(n)

Return a tuple of n new Index objects.

ufl.core.multiindex.ufl_type(is_abstract=False, is_terminal=None, is_scalar=False, is_index_free=False, is_shaping=False, is_literal=False, is_terminal_modifier=False, is_in_reference_frame=False, is_restriction=False, is_evaluation=False, is_differential=None, use_default_hash=True, num_ops=None, inherit_shape_from_operand=None, inherit_indices_from_operand=None, wraps_type=None, unop=None, binop=None, rbinop=None)

Decorator to apply to every subclass in the UFL Expr and BaseForm hierarchy.

This decorator contains a number of checks that are intended to enforce uniform behaviour across UFL types.

The rationale behind the checks and the meaning of the optional arguments should be sufficiently documented in the source code below.

ufl.core.operator

Operator.

class ufl.core.operator.Expr

Bases: object

Base class for all UFL expression types.

Instance properties

Every Expr instance will have certain properties. The most important ones are ufl_operands, ufl_shape, ufl_free_indices, and ufl_index_dimensions properties. Expressions are immutable and hashable.

Type traits

The Expr API defines a number of type traits that each subclass needs to provide. Most of these are specified indirectly via the arguments to the ufl_type class decorator, allowing UFL to do some consistency checks and automate most of the traits for most types. Type traits are accessed via a class or instance object of the form obj._ufl_traitname_. See the source code for description of each type trait.

Operators

Some Python special functions are implemented in this class, some are implemented in subclasses, and some are attached to this class in the ufl_type class decorator.

Defining subclasses

To define a new expression class, inherit from either Terminal or Operator, and apply the ufl_type class decorator with suitable arguments. See the docstring of ufl_type for details on its arguments. Looking at existing classes similar to the one you wish to add is a good idea. Looking through the comments in the Expr class and ufl_type to understand all the properties that may need to be specified is also a good idea. Note that many algorithms in UFL and form compilers will need handlers implemented for each new type::.

@ufl_type()
class MyOperator(Operator):
    pass

Type collections

All Expr subclasses are collected by ufl_type in global variables available via Expr.

Profiling

Object creation statistics can be collected by doing

Expr.ufl_enable_profiling()
# ... run some code
initstats, delstats = Expr.ufl_disable_profiling()

Giving a list of creation and deletion counts for each typecode.

Initialise.

property T

Transpose a rank-2 tensor expression.

For more general transpose operations of higher order tensor expressions, use indexing and Tensor.

dx(*ii)

Return the partial derivative with respect to spatial variable number ii.

evaluate(x, mapping, component, index_values)

Evaluate expression at given coordinate with given values for terminals.

static ufl_disable_profiling()

Turn off the object counting mechanism. Return object init and del counts.

ufl_domain()

Return the single unique domain this expression is defined on, or throw an error.

ufl_domains()

Return all domains this expression is defined on.

static ufl_enable_profiling()

Turn on the object counting mechanism and reset counts to zero.

ufl_free_indices: tuple[int, ...]

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...]

ufl_shape: tuple[int, ...]

class ufl.core.operator.Operator(operands=None)

Bases: Expr

Base class for all operators, i.e. non-terminal expression types.

Initialise.

ufl_free_indices: tuple[int, ...]

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...]

ufl_shape: tuple[int, ...]

ufl.core.operator.ufl_type(is_abstract=False, is_terminal=None, is_scalar=False, is_index_free=False, is_shaping=False, is_literal=False, is_terminal_modifier=False, is_in_reference_frame=False, is_restriction=False, is_evaluation=False, is_differential=None, use_default_hash=True, num_ops=None, inherit_shape_from_operand=None, inherit_indices_from_operand=None, wraps_type=None, unop=None, binop=None, rbinop=None)

Decorator to apply to every subclass in the UFL Expr and BaseForm hierarchy.

This decorator contains a number of checks that are intended to enforce uniform behaviour across UFL types.

The rationale behind the checks and the meaning of the optional arguments should be sufficiently documented in the source code below.

ufl.core.terminal

This module defines the Terminal class.

Terminal the superclass for all types that are terminal nodes in an expression tree.

class ufl.core.terminal.Expr

Bases: object

Base class for all UFL expression types.

Instance properties

Every Expr instance will have certain properties. The most important ones are ufl_operands, ufl_shape, ufl_free_indices, and ufl_index_dimensions properties. Expressions are immutable and hashable.

Type traits

The Expr API defines a number of type traits that each subclass needs to provide. Most of these are specified indirectly via the arguments to the ufl_type class decorator, allowing UFL to do some consistency checks and automate most of the traits for most types. Type traits are accessed via a class or instance object of the form obj._ufl_traitname_. See the source code for description of each type trait.

Operators

Some Python special functions are implemented in this class, some are implemented in subclasses, and some are attached to this class in the ufl_type class decorator.

Defining subclasses

To define a new expression class, inherit from either Terminal or Operator, and apply the ufl_type class decorator with suitable arguments. See the docstring of ufl_type for details on its arguments. Looking at existing classes similar to the one you wish to add is a good idea. Looking through the comments in the Expr class and ufl_type to understand all the properties that may need to be specified is also a good idea. Note that many algorithms in UFL and form compilers will need handlers implemented for each new type::.

@ufl_type()
class MyOperator(Operator):
    pass

Type collections

All Expr subclasses are collected by ufl_type in global variables available via Expr.

Profiling

Object creation statistics can be collected by doing

Expr.ufl_enable_profiling()
# ... run some code
initstats, delstats = Expr.ufl_disable_profiling()

Giving a list of creation and deletion counts for each typecode.

Initialise.

property T

Transpose a rank-2 tensor expression.

For more general transpose operations of higher order tensor expressions, use indexing and Tensor.

dx(*ii)

Return the partial derivative with respect to spatial variable number ii.

evaluate(x, mapping, component, index_values)

Evaluate expression at given coordinate with given values for terminals.

static ufl_disable_profiling()

Turn off the object counting mechanism. Return object init and del counts.

ufl_domain()

Return the single unique domain this expression is defined on, or throw an error.

ufl_domains()

Return all domains this expression is defined on.

static ufl_enable_profiling()

Turn on the object counting mechanism and reset counts to zero.

ufl_free_indices: tuple[int, ...]

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...]

ufl_shape: tuple[int, ...]

class ufl.core.terminal.FormArgument

Bases: Terminal

An abstract class for a form argument (a thing in a primal finite element space).

Initialise the form argument.

ufl_shape: tuple[int, ...]

class ufl.core.terminal.Terminal

Bases: Expr

Base class for terminal objects.

A terminal node in the UFL expression tree.

Initialise the terminal.

evaluate(x, mapping, component, index_values, derivatives=())

Get self from mapping and return the component asked for.

ufl_domains()

Return tuple of domains related to this terminal object.

ufl_free_indices: tuple[int, ...] = ()

ufl_index_dimensions = ()

ufl_operands: tuple[ufl.core.terminal.FormArgument, ...] = ()

ufl_shape: tuple[int, ...]

ufl.core.terminal.ufl_type(is_abstract=False, is_terminal=None, is_scalar=False, is_index_free=False, is_shaping=False, is_literal=False, is_terminal_modifier=False, is_in_reference_frame=False, is_restriction=False, is_evaluation=False, is_differential=None, use_default_hash=True, num_ops=None, inherit_shape_from_operand=None, inherit_indices_from_operand=None, wraps_type=None, unop=None, binop=None, rbinop=None)

Decorator to apply to every subclass in the UFL Expr and BaseForm hierarchy.

This decorator contains a number of checks that are intended to enforce uniform behaviour across UFL types.

The rationale behind the checks and the meaning of the optional arguments should be sufficiently documented in the source code below.

ufl.core.ufl_type

UFL type.

class ufl.core.ufl_type.UFLObject

Bases: ABC

A UFL Object.

class ufl.core.ufl_type.UFLType

Bases: type

Base class for all UFL types.

Equip UFL types with some ufl specific properties.

ufl.core.ufl_type.attach_implementations_of_indexing_interface(cls, inherit_shape_from_operand, inherit_indices_from_operand)

Attach implementations of indexing interface.

ufl.core.ufl_type.camel2underscore(name)

Convert a CamelCaps string to underscore_syntax.

ufl.core.ufl_type.check_abstract_trait_consistency(cls)

Check that the first base classes up to Expr are other UFL types.

ufl.core.ufl_type.check_has_slots(cls)

Check if type has __slots__ unless it is marked as exception with _ufl_noslots_.

ufl.core.ufl_type.check_implements_required_methods(cls)

Check if type implements the required methods.

ufl.core.ufl_type.check_implements_required_properties(cls)

Check if type implements the required properties.

ufl.core.ufl_type.check_is_terminal_consistency(cls)

Check for consistency in is_terminal trait among superclasses.

ufl.core.ufl_type.check_type_traits_consistency(cls)

Execute a variety of consistency checks on the ufl type traits.

ufl.core.ufl_type.compute_expr_hash(expr)

Compute hashes of expr and all its nodes efficiently, without using Python recursion.

ufl.core.ufl_type.determine_num_ops(cls, num_ops, unop, binop, rbinop)

Determine number of operands for this type.

ufl.core.ufl_type.get_base_attr(cls, name)

Return first non-None attribute of given name among base classes.

ufl.core.ufl_type.set_trait(cls, basename, value, inherit=False)

Assign a trait to class with namespacing _ufl_basename_ applied.

If trait value is None, optionally inherit it from the closest base class that has it.

ufl.core.ufl_type.ufl_type(is_abstract=False, is_terminal=None, is_scalar=False, is_index_free=False, is_shaping=False, is_literal=False, is_terminal_modifier=False, is_in_reference_frame=False, is_restriction=False, is_evaluation=False, is_differential=None, use_default_hash=True, num_ops=None, inherit_shape_from_operand=None, inherit_indices_from_operand=None, wraps_type=None, unop=None, binop=None, rbinop=None)

Decorator to apply to every subclass in the UFL Expr and BaseForm hierarchy.

This decorator contains a number of checks that are intended to enforce uniform behaviour across UFL types.

The rationale behind the checks and the meaning of the optional arguments should be sufficiently documented in the source code below.

ufl.core.ufl_type.update_global_expr_attributes(cls)

Update global attributres.

Update global Expr attributes, mainly by adding cls to global collections of ufl types.

ufl.core.ufl_type.update_ufl_type_attributes(cls)

Update UFL type attributes.