# 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: 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['FormArgument', ...]
  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: tuple['FormArgument', ...]

## 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: tuple['FormArgument', ...]

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_free_indices: tuple[int, ...]
  ufl_operands: tuple['FormArgument', ...]
  ufl_shape: tuple[int, ...]

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

  ufl_shape: tuple[int, ...]

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: tuple[int, ...] = ()
  ufl_index_dimensions = ()
  ufl_operands: tuple['FormArgument', ...] = ()
  ufl_shape: tuple[int, ...]

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

  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.

## Module contents

UFL core.