ffcx.ir.representation

Compiler stage 2: Code representation.

Module computes intermediate representations of forms. For each UFC function, we extract the data needed for code generation at a later stage.

The representation should conform strictly to the naming and order of functions in UFC. Thus, for code generation of the function “foo”, one should only need to use the data stored in the intermediate representation under the key “foo”.

Functions

`basix_cell_from_string`(string)	Convert a string to a Basix CellType.
`compute_ir`(analysis, object_names, prefix, ...)	Compute intermediate representation.

Classes

`DataIR`(integrals, forms, expressions)	Intermediate representation of data.
`ExpressionIR`(expression, ...)	Intermediate representation of a DOLFINx Expression.
`FormIR`(id, name, signature, rank, ...)	Intermediate representation of a form.
`IntegralIR`(expression, rank, ...)	Intermediate representation of an integral.
`QuadratureIR`(cell_shape, points, weights)	Intermediate representation of a quadrature rule.

class ffcx.ir.representation.CommonExpressionIR(integral_type: str, entity_type: Literal['cell', 'facet', 'vertex', 'ridge'], tensor_shape: list[int], coefficient_numbering: dict[Coefficient, int], coefficient_offsets: dict[Coefficient, int], original_constant_offsets: dict[Constant, int], unique_tables: dict[str, dict[CellType, ndarray[tuple[Any, ...], dtype[float64]]]], unique_table_types: dict[CellType, dict[str, str]], integrand: dict[tuple[CellType, QuadratureRule], dict], name: str, needs_facet_permutations: bool, shape: list[int], coordinate_element_hash: str)[source]

Bases: NamedTuple

Common-ground for IntegralIR and ExpressionIR.

Create new instance of CommonExpressionIR(integral_type, entity_type, tensor_shape, coefficient_numbering, coefficient_offsets, original_constant_offsets, unique_tables, unique_table_types, integrand, name, needs_facet_permutations, shape, coordinate_element_hash)

coefficient_numbering: dict[Coefficient, int]: Alias for field number 3

coefficient_offsets: dict[Coefficient, int]: Alias for field number 4

coordinate_element_hash: str: Alias for field number 12

entity_type: Literal['cell', 'facet', 'vertex', 'ridge']: Alias for field number 1

integral_type: str: Alias for field number 0

integrand: dict[tuple[CellType, QuadratureRule], dict]: Alias for field number 8

name: str: Alias for field number 9

needs_facet_permutations: bool: Alias for field number 10

original_constant_offsets: dict[Constant, int]: Alias for field number 5

shape: list[int]: Alias for field number 11

tensor_shape: list[int]: Alias for field number 2

unique_table_types: dict[CellType, dict[str, str]]: Alias for field number 7

unique_tables: dict[str, dict[CellType, ndarray[tuple[Any, ...], dtype[float64]]]]: Alias for field number 6

class ffcx.ir.representation.DataIR(integrals: list[IntegralIR], forms: list[FormIR], expressions: list[ExpressionIR])[source]

Bases: NamedTuple

Intermediate representation of data.

Create new instance of DataIR(integrals, forms, expressions)

expressions: list[ExpressionIR]: Alias for field number 2

forms: list[FormIR]: Alias for field number 1

integrals: list[IntegralIR]: Alias for field number 0

class ffcx.ir.representation.ExpressionIR(expression: CommonExpressionIR, original_coefficient_positions: list[int], coefficient_names: list[str], constant_names: list[str], name_from_uflfile: str)[source]

Bases: NamedTuple

Intermediate representation of a DOLFINx Expression.

Create new instance of ExpressionIR(expression, original_coefficient_positions, coefficient_names, constant_names, name_from_uflfile)

coefficient_names: list[str]: Alias for field number 2

constant_names: list[str]: Alias for field number 3

expression: CommonExpressionIR: Alias for field number 0

name_from_uflfile: str: Alias for field number 4

original_coefficient_positions: list[int]: Alias for field number 1

class ffcx.ir.representation.FormIR(id: int, name: str, signature: str, rank: int, num_coefficients: int, name_from_uflfile: str, original_coefficient_positions: list[int], coefficient_names: list[str], num_constants: int, constant_ranks: list[int], constant_shapes: list[list[int]], constant_names: list[str], finite_element_hashes: list[int], integral_names: dict[str, list[str]], integral_domains: dict[str, list[basix.CellType]], subdomain_ids: dict[str, list[int]])[source]

Bases: NamedTuple

Intermediate representation of a form.

Create new instance of FormIR(id, name, signature, rank, num_coefficients, name_from_uflfile, original_coefficient_positions, coefficient_names, num_constants, constant_ranks, constant_shapes, constant_names, finite_element_hashes, integral_names, integral_domains, subdomain_ids)

coefficient_names: list[str]: Alias for field number 7

constant_names: list[str]: Alias for field number 11

constant_ranks: list[int]: Alias for field number 9

constant_shapes: list[list[int]]: Alias for field number 10

finite_element_hashes: list[int]: Alias for field number 12

id: int: Alias for field number 0

integral_domains: dict[str, list[CellType]]: Alias for field number 14

integral_names: dict[str, list[str]]: Alias for field number 13

name: str: Alias for field number 1

name_from_uflfile: str: Alias for field number 5

num_coefficients: int: Alias for field number 4

num_constants: int: Alias for field number 8

original_coefficient_positions: list[int]: Alias for field number 6

rank: int: Alias for field number 3

signature: str: Alias for field number 2

subdomain_ids: dict[str, list[int]]: Alias for field number 15

class ffcx.ir.representation.Integral(integrand: Expr, integral_type: str, domain, subdomain_id: int | tuple[int, ...], metadata: dict, subdomain_data: Any, extra_domain_integral_type_map: dict[Mesh, str] | None = None)[source]

Bases: object

An integral over a single domain.

Initialise.

Parameters:

integrand – Integrand of the integral
integral_type – Type of integral, see: ufl.measure._integral_types for available types.
domain – Integration domain as an ufl.Mesh.
subdomain_id – Integer or tuple of integer restricting the integral to a subset of entities, marked in some way through subdomain_data.
metadata – Metadata that is usually passed to the form compiler
subdomain_data – Data associated with the subdomain, can be anything (depends on the compiler and user-facing API)
extra_domain_integral_type_map – Mapping from other ufl.Mesh objects present in integrand to specific integral types on this domain; see: ufl.measure._integral_types for possible types.

extra_domain_integral_type_map()[source]: Return the extra domain-integral_type map.

integral_type()[source]: Return the domain type of this integral.

integrand()[source]: Return the integrand expression, which is an Expr instance.

metadata()[source]: Return the compiler metadata this integral has been annotated with.

reconstruct(integrand=None, integral_type=None, domain=None, subdomain_id=None, metadata=None, subdomain_data=None, extra_domain_integral_type_map=None)[source]

Construct a new Integral object with some properties replaced with new values.

Example

<a = Integral instance> b = a.reconstruct(expand_compounds(a.integrand())) c = a.reconstruct(metadata={‘quadrature_degree’:2})

subdomain_data()[source]: Return the domain data of this integral.

subdomain_id()[source]: Return the subdomain id of this integral.

ufl_domain()[source]: Return the integration domain of this integral.

class ffcx.ir.representation.IntegralIR(expression: CommonExpressionIR, rank: int, enabled_coefficients: list[bool], part: TensorPart)[source]

Bases: NamedTuple

Intermediate representation of an integral.

Create new instance of IntegralIR(expression, rank, enabled_coefficients, part)

enabled_coefficients: list[bool]: Alias for field number 2

expression: CommonExpressionIR: Alias for field number 0

part: TensorPart: Alias for field number 3

rank: int: Alias for field number 1

class ffcx.ir.representation.QuadratureIR(cell_shape: str, points: npt.NDArray[np.float64], weights: npt.NDArray[np.float64])[source]

Bases: NamedTuple

Intermediate representation of a quadrature rule.

Create new instance of QuadratureIR(cell_shape, points, weights)

cell_shape: str: Alias for field number 0

points: ndarray[tuple[Any, ...], dtype[float64]]: Alias for field number 1

weights: ndarray[tuple[Any, ...], dtype[float64]]: Alias for field number 2

class ffcx.ir.representation.QuadratureRule(points, weights, tensor_factors=None)[source]

Bases: object

A quadrature rule.

Initialise.

id()[source]: Return unique deterministic identifier.

Note

This identifier is used to provide unique names to tables and symbols in generated code.

class ffcx.ir.representation.TensorPart(*values)[source]

Bases: Enum

What part of the tensor to assemble.

diagonal = 4

classmethod from_str(value: str)[source]: Workaround for string enum prior to Python 3.11.

full = 1

class ffcx.ir.representation.UFLData(form_data: tuple[ufl.algorithms.formdata.FormData, ...], unique_elements: list[basix.ufl._ElementBase], element_numbers: dict[basix.ufl._ElementBase, int], unique_coordinate_elements: list[basix.ufl._ElementBase], expressions: list[tuple[ufl.core.expr.Expr, npt.NDArray[np.floating], ufl.core.expr.Expr]])[source]

Bases: NamedTuple

UFL data.

Create new instance of UFLData(form_data, unique_elements, element_numbers, unique_coordinate_elements, expressions)

element_numbers: dict[_ElementBase, int]: Alias for field number 2

expressions: list[tuple[Expr, ndarray[tuple[Any, ...], dtype[floating]], Expr]]: Alias for field number 4

form_data: tuple[FormData, ...]: Alias for field number 0

unique_coordinate_elements: list[_ElementBase]: Alias for field number 3

unique_elements: list[_ElementBase]: Alias for field number 1

ffcx.ir.representation.basix_cell_from_string(string: str) → CellType[source]: Convert a string to a Basix CellType.

ffcx.ir.representation.compute_integral_ir(cell: Cell, integral_type: Literal['interior_facet', 'exterior_facet', 'ridge', 'cell'], entity_type: Literal['cell', 'facet', 'ridge', 'vertex'], integrands: dict[CellType, dict[QuadratureRule, Expr]], argument_shape: tuple[int], p: dict, visualise: bool)[source]

Compute intermediate representation for an integral.

Parameters:

cell – Cell of integration domain
integral_type – Type of integral over cell
entity_type – Corresponding entity of the cell that the integral is over
integrands – Dictionary mapping a quadrature rule to a sequence of integrands
argument_shape – Shape of the output tensor of the integral (used for tensor factorization)
p – Parameters used for clamping tables and for activating sum factorization
visualise – If True, store the graph representation of the integrand in a pdf file S.pdf and F.pdf

ffcx.ir.representation.compute_ir(analysis: UFLData, object_names: dict[int, str], prefix: str, options: dict[str, type[Any] | dtype[Any] | _SupportsDType[dtype[Any]] | tuple[Any, Any] | list[Any] | _DTypeDict | str | None | int | float | bool], visualise: bool) → DataIR[source]: Compute intermediate representation.

ffcx.ir.representation.create_quadrature_points_and_weights(integral_type, cell, degree, rule, elements, use_tensor_product=False)[source]: Create quadrature rule and return points and weights.

ffcx.ir.representation.sorted_expr_sum(seq)[source]: Sorted expr sum.