# ufl.utils package¶

## ufl.utils.counted module¶

Utilites for types with a global unique counter attached to each object.

class ufl.utils.counted.ExampleCounted(count=None)

Bases: object

An example class for classes of objects identified by a global counter.

Mimic this class to create globally counted objects within a single type.

count()
ufl.utils.counted.counted_init(self, count=None, countedclass=None)

Initialize a counted object, see ExampleCounted below for how to use.

## ufl.utils.derivativetuples module¶

This module contains a collection of utilities for representing partial derivatives as integer tuples.

ufl.utils.derivativetuples.compute_derivative_tuples(n, gdim)

Compute the list of all derivative tuples for derivatives of given total order n and given geometric dimension gdim. This function returns two lists. The first is a list of tuples, where each tuple of length n specifies the coordinate directions of the n derivatives. The second is a corresponding list of tuples, where each tuple of length gdim specifies the number of derivatives in each direction. Both lists have length gdim^n and are ordered as expected by the UFC function tabulate_basis_derivatives.

Example: If n = 2 and gdim = 3, then the nice tuples are

(0, 0) <–> (2, 0, 0) <–> d^2/dxdx (0, 1) <–> (1, 1, 0) <–> d^2/dxdy (0, 2) <–> (1, 0, 1) <–> d^2/dxdz (1, 0) <–> (1, 1, 0) <–> d^2/dydx (1, 1) <–> (0, 2, 0) <–> d^2/dydy (1, 2) <–> (0, 1, 1) <–> d^2/dydz (2, 0) <–> (1, 0, 1) <–> d^2/dzdx (2, 1) <–> (0, 1, 1) <–> d^2/dzdy (2, 2) <–> (0, 0, 2) <–> d^2/dzdz
ufl.utils.derivativetuples.derivative_counts_to_listing(derivative_counts)

Convert a derivative count tuple to a derivative listing tuple.

The derivative d^3 / dy^2 dz is represented in counting form as (0, 2, 1) meaning (dx^0, dy^2, dz^1) and in listing form as (1, 1, 2) meaning (dy, dy, dz).

ufl.utils.derivativetuples.derivative_listing_to_counts(derivatives, gdim)

Convert a derivative listing tuple to a derivative count tuple.

The derivative d^3 / dy^2 dz is represented in counting form as (0, 2, 1) meaning (dx^0, dy^2, dz^1) and in listing form as (1, 1, 2) meaning (dy, dy, dz).

## ufl.utils.dicts module¶

Various dict manipulation utilities.

class ufl.utils.dicts.EmptyDictType

Bases: dict

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

ufl.utils.dicts.dict_sum(items)

Construct a dict, in between dict(items) and sum(items), by accumulating items for each key.

ufl.utils.dicts.mergedicts(dicts)
ufl.utils.dicts.mergedicts2(d1, d2)
ufl.utils.dicts.slice_dict(dictionary, keys, default=None)
ufl.utils.dicts.some_key(a_dict)

Return an arbitrary key from a dictionary.

ufl.utils.dicts.split_dict(d, criteria)

Split a dict d into two dicts based on a criteria on the keys.

ufl.utils.dicts.subdict(superdict, keys)

## ufl.utils.formatting module¶

Various string formatting utilities.

ufl.utils.formatting.camel2underscore(name)

Convert a CamelCaps string to underscore_syntax.

ufl.utils.formatting.dstr(d, colsize=80)

Pretty-print dictionary of key-value pairs.

ufl.utils.formatting.estr(elements)

Format list of elements for printing.

ufl.utils.formatting.istr(o)

Format object as string, inserting ? for None.

ufl.utils.formatting.lstr(l)

Pretty-print list or tuple, invoking str() on items instead of repr() like str() does.

ufl.utils.formatting.sstr(s)

Pretty-print set.

ufl.utils.formatting.tstr(t, colsize=80)

Pretty-print list of tuples of key-value pairs.

## ufl.utils.indexflattening module¶

This module contains a collection of utilities for mapping between multiindices and a flattened index space.

ufl.utils.indexflattening.flatten_multiindex(ii, strides)

Return the flat index corresponding to the given multiindex.

ufl.utils.indexflattening.shape_to_strides(sh)

Return a tuple of strides given a shape tuple.

ufl.utils.indexflattening.unflatten_index(i, strides)

Return the multiindex corresponding to the given flat index.

## ufl.utils.sequences module¶

Various sequence manipulation utilities.

ufl.utils.sequences.and_tuples(seqa, seqb)

Return ‘and’ of all pairs in two sequences of same length.

ufl.utils.sequences.iter_tree(tree)

Iterate over all nodes in a tree represented by lists of lists of leaves.

ufl.utils.sequences.max_degree(degrees)

Maximum degree for mixture of scalar and tuple degrees.

ufl.utils.sequences.or_tuples(seqa, seqb)

Return ‘or’ of all pairs in two sequences of same length.

ufl.utils.sequences.product(sequence)

Return the product of all elements in a sequence.

ufl.utils.sequences.recursive_chain(lists)
ufl.utils.sequences.unzip(seq)

Inverse operation of zip: unzip(zip(a, b)) == (a, b)

ufl.utils.sequences.xor(a, b)

## ufl.utils.sorting module¶

Utilites for sorting.

ufl.utils.sorting.canonicalize_metadata(metadata)

Assuming metadata to be a dict with string keys and builtin python types as values.

Transform dict to a tuple of (key, value) item tuples ordered by key, with dict, list and tuple values converted the same way recursively. Lists and tuples are converted to tuples. Other values are converted using str(). This is such that the end result can be hashed and sorted using regular <, because python 3 doesn’t allow e.g. (3 < “auto”) which occurs regularly in metadata.

ufl.utils.sorting.sorted_by_count(seq)

Sort a sequence by the item.count().

ufl.utils.sorting.sorted_by_key(mapping)

Sort dict items by key, allowing different key types.

ufl.utils.sorting.sorted_by_ufl_id(seq)

Sort a sequence by the item.ufl_id().

ufl.utils.sorting.topological_sorting(nodes, edges)

Return a topologically sorted list of the nodes

Implemented algorithm from Wikipedia :P

No error for cyclic edges…

## ufl.utils.stacks module¶

Various utility data structures.

class ufl.utils.stacks.Stack(*args)

Bases: list

A stack datastructure.

peek()
push(v)
class ufl.utils.stacks.StackDict(*args, **kwargs)

Bases: dict

A dict that can be changed incrementally with ‘d.push(k,v)’ and have changes rolled back with ‘k,v = d.pop()’.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

push(k, v)

## ufl.utils.str module¶

String manipulation utilities.

ufl.utils.str.as_native_str(s)

Return s as unicode string, decoded using utf-8 if necessary.

ufl.utils.str.as_native_strings(stringlist)

## ufl.utils.ufltypedicts module¶

Various utility data structures.

class ufl.utils.ufltypedicts.UFLTypeDefaultDict(default)

Bases: dict

class ufl.utils.ufltypedicts.UFLTypeDict

Bases: dict