ufl.core package

Submodules

ufl.core.base_form_operator module

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.

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 = ()

ufl_function_space()

Return the function space associated to the operator.

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

ufl_index_dimensions = ()

ufl_operands

property ufl_shape

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

ufl.core.compute_expr_hash module

Non-recursive traversal-based hash computation algorithm.

Fast iteration over nodes in an Expr DAG to compute memoized hashes for all unique nodes.

ufl.core.compute_expr_hash.compute_expr_hash(expr)

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

ufl.core.expr module

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.

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.core.expr.ufl_err_str(expr)

Return a UFL error string.

ufl.core.external_operator module

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.ExternalOperator(*operands, function_space, derivatives=None, argument_slots=())

Bases: BaseFormOperator

External operator.

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

ufl.core.interpolate module

This module defines the Interpolate class.

class ufl.core.interpolate.Interpolate(expr, v)

Bases: BaseFormOperator

Symbolic representation of the interpolation operator.

ufl_operands

ufl.core.interpolate.interpolate(expr, v)

Create symbolic representation of the interpolation operator.

Args:

expr: a UFL expression to interpolate. v: the FunctionSpace to interpolate into or the Coargument

defined on the dual of the FunctionSpace to interpolate into.

ufl.core.multiindex module

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

class ufl.core.multiindex.FixedIndex(value)

Bases: IndexBase

UFL value: An index with a specific value assigned.

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.

class ufl.core.multiindex.IndexBase

Bases: object

Base class for all indices.

class ufl.core.multiindex.MultiIndex(indices)

Bases: Terminal

Represents a sequence of indices, either fixed or free.

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.

ufl.core.multiindex.indices(n)

Return a tuple of n new Index objects.

ufl.core.operator module

Operator.

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

Bases: Expr

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

ufl_operands

ufl.core.terminal module

This module defines the Terminal class.

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

class ufl.core.terminal.FormArgument

Bases: Terminal

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

class ufl.core.terminal.Terminal

Bases: Expr

Base class for terminal objects.

A terminal node in the UFL expression tree.

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 = ()

ufl_index_dimensions = ()

ufl_operands = ()

ufl.core.ufl_id module

Utilites for types with a globally counted unique id attached to each object.

ufl.core.ufl_id.attach_ufl_id(cls)

Equip class with .ufl_id() and handle bookkeeping.

Usage:

1. Apply to class:

   @attach_ufl_id
   class MyClass(object):
   

2. If __slots__ is defined, include _ufl_id attribute:

   __slots__ = ("_ufl_id",)
   

3. Add keyword argument to constructor:

   def __init__(self, *args, ufl_id=None):
   

4. Call self._init_ufl_id with ufl_id and assign to ._ufl_id attribute:

   self._ufl_id = self._init_ufl_id(ufl_id)
   

Result:

MyClass().ufl_id() returns unique value for each constructed object.

ufl.core.ufl_type module

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.attach_operators_from_hash_data(cls)

Class decorator to attach __hash__, __eq__ and __ne__ implementations.

These are implemented in terms of a ._ufl_hash_data() method on the class, which should return a tuple or hashable and comparable data.

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.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)

This decorator is to be applied 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 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.

Module contents

UFL core.