core Package

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.

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 Exprs 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 expression instance will have certain properties. Most important are the 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. The type traits are accessed via a class or instance object on 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.

T

Transposed a rank two tensor expression. For more general transpose operations of higher order tensor expressions, use indexing and Tensor.

cell()

Return the cell this expression is defined on.

domain()

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

domains()

dx(*ii)

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

evaluate(x, mapping, component, index_values)

Evaluate expression at given coordinate with given values for terminals.

free_indices()

Return a tuple with the free indices (unassigned) of the expression.

geometric_dimension()

Return the geometric dimension this expression lives in.

index_dimensions()

Return a dict with the free or repeated indices in the expression as keys and the dimensions of those indices as values.

is_cellwise_constant()

Return whether this expression is spatially constant over each cell.

operands()

Return a sequence with all subtree nodes in expression tree.

rank()

Return the tensor rank of the expression.

reconstruct(*operands)

Return a new object of the same type with new operands.

shape()

Return the tensor shape of the expression.

signature_data()

Return data that uniquely identifies form compiler relevant aspects of this object.

static ufl_disable_profiling()

Turn off object counting mechanism. Returns object init and del counts.

static ufl_enable_profiling()

Turn on object counting mechanism and reset counts to zero.

multiindex Module

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

class ufl.core.multiindex.FixedIndex(value)

Bases: ufl.core.multiindex.IndexBase

UFL value: An index with a specific value assigned.

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

Bases: ufl.core.multiindex.IndexBase

UFL value: An index with no value assigned.

Used to represent free indices in Einstein indexing notation.

count()

class ufl.core.multiindex.IndexBase

Bases: object

class ufl.core.multiindex.MultiIndex(indices)

Bases: ufl.core.terminal.Terminal

Represents a sequence of indices, either fixed or free.

domains()

Return tuple of domains related to this terminal object.

evaluate(x, mapping, component, index_values)

indices()

is_cellwise_constant()

ufl_free_indices

ufl_index_dimensions

ufl_shape

ufl.core.multiindex.as_multi_index(ii, shape=None)

ufl.core.multiindex.indices(n)

UFL value: Return a tuple of n new Index objects.

operator Module

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

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

Bases: ufl.core.expr.Expr

free_indices()

Intermediate helper property getter to transition from .free_indices() to .ufl_free_indices.

index_dimensions()

Intermediate helper property getter to transition from .index_dimensions() to .ufl_index_dimensions.

is_cellwise_constant()

Return whether this expression is spatially constant over each cell.

operands()

reconstruct(*operands)

Return a new object of the same type with new operands.

signature_data()

ufl_operands

terminal Module

This module defines the Terminal class, the superclass for all types that are terminal nodes in the expression trees.

class ufl.core.terminal.FormArgument

Bases: ufl.core.terminal.Terminal

class ufl.core.terminal.Terminal

Bases: ufl.core.expr.Expr

A terminal node in the UFL expression tree.

domains()

Return tuple of domains related to this terminal object.

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

Get self from mapping and return the component asked for.

free_indices()

A Terminal object never has free indices.

index_dimensions()

A Terminal object never has free indices.

operands()

A Terminal object never has operands.

reconstruct(*operands)

Return self.

signature_data(renumbering)

Default signature data for of terminals just return the repr string.

ufl_free_indices = ()

ufl_index_dimensions = ()

ufl_operands = ()

ufl_type Module

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

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)

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