ufl.core package

Submodules

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.

geometric_dimension()

Return the geometric dimension this expression lives in.

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)

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

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

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

Always True.

ufl_domains()

Return tuple of domains related to this terminal object.

property ufl_free_indices

This shall not be used.

property ufl_index_dimensions

This shall not be used.

property ufl_shape

This shall not be used.

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

Return a MultiIndex version of ii.

ufl.core.multiindex.indices(n)

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

ufl.core.operator module

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

class ufl.core.terminal.Terminal

Bases: Expr

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.core.ufl_type.attach_implementations_of_indexing_interface(cls, inherit_shape_from_operand, inherit_indices_from_operand)

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

Module contents