Warning

You are reading a version of the website built against the unstable main branch. This content is liable to change without notice and may be inappropriate for your use case. You can find the documentation for the current stable release here.

firedrake.slate package

Subpackages

• firedrake.slate.slac package
  • Submodules
  • firedrake.slate.slac.compiler module
    • compile_expression()
  • firedrake.slate.slac.kernel_builder module
    • CellFacetKernelArg
    • CoefficientInfo
      • CoefficientInfo.local_temp
      • CoefficientInfo.offset_index
      • CoefficientInfo.shape
      • CoefficientInfo.space_index
      • CoefficientInfo.vector
    • IndexCreator
      • IndexCreator.__call__()
      • IndexCreator.domains
    • LayerCountKernelArg
    • LocalLoopyKernelBuilder
      • LocalLoopyKernelBuilder.cell_facets_arg_name
      • LocalLoopyKernelBuilder.cell_orientations_arg_name
      • LocalLoopyKernelBuilder.cell_sizes_arg_name
      • LocalLoopyKernelBuilder.collect_coefficients()
      • LocalLoopyKernelBuilder.collect_constants()
      • LocalLoopyKernelBuilder.collect_tsfc_kernel_data()
      • LocalLoopyKernelBuilder.coordinates_arg_name
      • LocalLoopyKernelBuilder.extent()
      • LocalLoopyKernelBuilder.facet_integral_predicates()
      • LocalLoopyKernelBuilder.generate_lhs()
      • LocalLoopyKernelBuilder.generate_tsfc_calls()
      • LocalLoopyKernelBuilder.generate_wrapper_kernel_args()
      • LocalLoopyKernelBuilder.initialise_terminals()
      • LocalLoopyKernelBuilder.is_integral_type()
      • LocalLoopyKernelBuilder.layer_arg_name
      • LocalLoopyKernelBuilder.layer_count_name
      • LocalLoopyKernelBuilder.layer_integral_predicates()
      • LocalLoopyKernelBuilder.local_facet_array_arg_name
      • LocalLoopyKernelBuilder.loopify_tsfc_kernel_data()
      • LocalLoopyKernelBuilder.shape()
      • LocalLoopyKernelBuilder.slate_call()
      • LocalLoopyKernelBuilder.supported_integral_types
      • LocalLoopyKernelBuilder.supported_subdomain_types
      • LocalLoopyKernelBuilder.tsfc_cxt_kernels()
    • SlateWrapperBag
  • firedrake.slate.slac.optimise module
    • ActionBag
      • ActionBag.coeff
      • ActionBag.pick_op
    • drop_double_transpose()
    • flip()
    • optimise()
    • push_block()
    • push_diag()
    • push_mul()
  • firedrake.slate.slac.tsfc_driver module
    • ContextKernel
      • ContextKernel.coefficients
      • ContextKernel.constants
      • ContextKernel.original_integral_type
      • ContextKernel.tensor
      • ContextKernel.tsfc_kernels
    • compile_terminal_form()
    • transform_integrals()
  • firedrake.slate.slac.utils module
    • RemoveRestrictions
      • RemoveRestrictions.expr()
      • RemoveRestrictions.positive_restricted()
    • depth_first_search()
    • merge_loopy()
    • slate2gem()
    • slate_to_gem()
    • topological_sort()
  • Module contents
• firedrake.slate.static_condensation package
  • Submodules
  • firedrake.slate.static_condensation.hybridization module
    • HybridizationPC
      • HybridizationPC.backward_substitution()
      • HybridizationPC.forward_elimination()
      • HybridizationPC.getSchurComplementBuilder()
      • HybridizationPC.initialize()
      • HybridizationPC.needs_python_pmat
      • HybridizationPC.sc_solve()
      • HybridizationPC.update()
      • HybridizationPC.view()
    • SchurComplementBuilder
      • SchurComplementBuilder.build_A00_inv()
      • SchurComplementBuilder.build_Sapprox_inv()
      • SchurComplementBuilder.build_inner_S()
      • SchurComplementBuilder.build_inner_S_inv()
      • SchurComplementBuilder.build_schur()
      • SchurComplementBuilder.inv()
      • SchurComplementBuilder.retrieve_user_S_approx()
  • firedrake.slate.static_condensation.la_utils module
    • LAContext
      • LAContext.field_idx
      • LAContext.lhs
      • LAContext.rhs
    • SchurComplementBuilder
      • SchurComplementBuilder.build_A00_inv()
      • SchurComplementBuilder.build_Sapprox_inv()
      • SchurComplementBuilder.build_inner_S()
      • SchurComplementBuilder.build_inner_S_inv()
      • SchurComplementBuilder.build_schur()
      • SchurComplementBuilder.inv()
      • SchurComplementBuilder.retrieve_user_S_approx()
    • backward_solve()
    • condense_and_forward_eliminate()
  • firedrake.slate.static_condensation.sc_base module
    • SCBase
      • SCBase.apply()
      • SCBase.applyTranspose()
      • SCBase.backward_substitution()
      • SCBase.forward_elimination()
      • SCBase.sc_solve()
  • firedrake.slate.static_condensation.scpc module
    • SCPC
      • SCPC.backward_substitution()
      • SCPC.condensed_system()
      • SCPC.forward_elimination()
      • SCPC.initialize()
      • SCPC.local_solver_calls()
      • SCPC.needs_python_pmat
      • SCPC.sc_solve()
      • SCPC.update()
      • SCPC.view()
  • Module contents

Submodules

firedrake.slate.slate module

Slate is a symbolic language defining a framework for performing linear algebra operations on finite element tensors. It is similar in principle to most linear algebra libraries in notation.

The design of Slate was heavily influenced by UFL, and utilizes much of UFL’s functionality for FEM-specific form manipulation.

Unlike UFL, however, once forms are assembled into Slate \(Tensor\) objects, one can utilize the operations defined in Slate to express complicated linear algebra operations (such as the Schur-complement reduction of a block-matrix system).

All Slate expressions are handled by a specialized linear algebra compiler, which interprets expressions and produces C++ kernel functions to be executed within the Firedrake architecture.

class firedrake.slate.slate.Add(A, B)

Bases: BinaryOp

Abstract Slate class representing matrix-matrix, vector-vector

or scalar-scalar addition.

Parameters:

• A – a TensorBase object.

• B – another TensorBase object.

Constructor for the Add class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns a tuple of arguments associated with the tensor.

prec = 1

class firedrake.slate.slate.AssembledVector(function)

Bases: TensorBase

This class is a symbolic representation of an assembled vector of data contained in a Function.

Parameters:

function – A firedrake function.

Initialise a cache for stashing results.

Mirrors Form.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns a tuple of arguments associated with the tensor.

assembled = True

coefficients()

Returns a tuple of coefficients associated with the tensor.

constants()

Returns a tuple of constants associated with the tensor.

property form

operands = ()

prec = 0

reconstruct(form)

Reconstructs this assembled vector with new operands.

slate_coefficients()

Returns a tuple of coefficients associated with the tensor.

subdomain_data()

Returns a mapping on the tensor: {domain:{integral_type: subdomain_data}}.

terminal = True

ufl_domains()

Returns the integration domains of the integrals associated with the tensor.

class firedrake.slate.slate.Block(tensor, indices)

Bases: TensorBase

This class represents a tensor corresponding to particular block of a mixed tensor. Depending on the indices provided, the subblocks can span multiple test/trial spaces.

Parameters:

• tensor – A (mixed) tensor.

• indices – Indices of the test and trial function spaces to extract. This should be a 0-, 1-, or 2-tuple (whose length is equal to the rank of the tensor.) The entries should be an iterable of integer indices.

For example, consider the mixed tensor defined by:

n = FacetNormal(m)
U = FunctionSpace(m, "DRT", 1)
V = FunctionSpace(m, "DG", 0)
M = FunctionSpace(m, "DGT", 0)
W = U * V * M
u, p, r = TrialFunctions(W)
w, q, s = TestFunctions(W)
A = Tensor(dot(u, w)*dx + p*div(w)*dx + r*dot(w, n)*dS
           + div(u)*q*dx + p*q*dx + r*s*ds)

This describes a block 3x3 mixed tensor of the form:

\[\begin{split}\begin{bmatrix} A & B & C \\ D & E & F \\ G & H & J \end{bmatrix}\end{split}\]

Providing the 2-tuple ((0, 1), (0, 1)) returns a tensor corresponding to the upper 2x2 block:

\[\begin{split}\begin{bmatrix} A & B \\ D & E \end{bmatrix}\end{split}\]

More generally, argument indices of the form \((idr, idc)\) produces a tensor of block-size \(len(idr)\) x \(len(idc)\) spanning the specified test/trial spaces.

Constructor for the Block class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns a tuple of arguments associated with the tensor.

property assembled

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

coefficients()

Returns a tuple of coefficients associated with the tensor.

constants()

Returns a tuple of constants associated with the tensor.

property form

prec = 0

reconstruct(tensor=None, *, indices=None)

Reconstruct this block with a replacement tensor or indices.

slate_coefficients()

Returns a tuple of coefficients associated with the tensor.

subdomain_data()

Returns a mapping on the tensor: {domain:{integral_type: subdomain_data}}.

property terminal

Blocks are only terminal when they sit on Tensors or AssembledVectors

ufl_domains()

Returns the integration domains of the integrals associated with the tensor.

property ufl_operands

class firedrake.slate.slate.BlockAssembledVector(function, expr, indices)

Bases: AssembledVector

This class is a symbolic representation of an assembled vector of data contained in a set of Function s defined on pieces of a split mixed function space.

Parameters:

functions – A tuple of firedrake functions.

Initialise a cache for stashing results.

Mirrors Form.

property arg_function_spaces

Returns a tuple of function spaces associated to the corresponding block.

arguments()

Returns a tuple of arguments associated with the corresponding block.

coefficients()

Returns a tuple of coefficients associated with the tensor.

property form

slate_coefficients()

Returns a BlockFunction in a tuple which carries all information to generate the right coefficients and maps.

subdomain_data()

Returns mappings on the tensor: {domain:{integral_type: subdomain_data}}.

ufl_domains()

Returns the integration domains of the integrals associated with the tensor.

class firedrake.slate.slate.DiagonalTensor(A)

Bases: UnaryOp

An abstract Slate class representing the diagonal of a tensor.

Warning

This class will raise an error if the tensor is not square.

Constructor for the Diagonal class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns a tuple of arguments associated with the tensor.

diagonal = True

prec = 0

class firedrake.slate.slate.Factorization(tensor, decomposition=None)

Bases: TensorBase

An abstract Slate class for the factorization of matrices. The factorizations available are the following:

1. LU with full or partial pivoting (‘FullPivLU’ and ‘PartialPivLU’);

2. QR using Householder reflectors (‘HouseholderQR’) with the option to use column pivoting (‘ColPivHouseholderQR’) or full pivoting (‘FullPivHouseholderQR’);

3. standard Cholesky (‘LLT’) and stabilized Cholesky factorizations with pivoting (‘LDLT’);

4. a rank-revealing complete orthogonal decomposition using Householder transformations (‘CompleteOrthogonalDecomposition’); and

5. singular-valued decompositions (‘JacobiSVD’ and ‘BDCSVD’). For larger matrices, ‘BDCSVD’ is recommended.

Constructor for the Factorization class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns a tuple of arguments associated with the tensor.

coefficients()

Returns a tuple of coefficients associated with the tensor.

constants()

Returns a tuple of constants associated with the tensor.

prec = 0

reconstruct(tensor, decomposition=None)

Reconstructs this factorization with new operands.

slate_coefficients()

Returns a tuple of coefficients associated with the tensor.

subdomain_data()

Returns a mapping on the tensor: {domain:{integral_type: subdomain_data}}.

ufl_domains()

Returns the integration domains of the integrals associated with the tensor.

class firedrake.slate.slate.Inverse(A)

Bases: UnaryOp

An abstract Slate class representing the inverse of a tensor.

Warning

This class will raise an error if the tensor is not square.

Constructor for the Inverse class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns the expected arguments of the resulting tensor of performing a specific unary operation on a tensor.

class firedrake.slate.slate.Mul(A, B)

Bases: BinaryOp

Abstract Slate class representing the interior product or two tensors. By interior product, we mean an operation that results in a tensor of equal or lower rank via performing a contraction on arguments. This includes Matrix-Matrix and Matrix-Vector multiplication.

Parameters:

• A – a TensorBase object.

• B – another TensorBase object.

Constructor for the Mul class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns the arguments of a tensor resulting from multiplying two tensors A and B.

prec = 2

class firedrake.slate.slate.Reciprocal(A)

Bases: UnaryOp

An abstract Slate class representing the reciprocal of a vector.

Constructor for the Inverse class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns the expected arguments of the resulting tensor of performing a specific unary operation on a tensor.

prec = 0

class firedrake.slate.slate.ScalarMul(scalar, tensor)

Bases: UnaryOp

Represent multiplication of a Slate tensor by a scalar.

Parameters:

• scalar (numbers.Number, ufl.constantvalue.ConstantValue, or ufl.constantvalue.ScalarValue) – The scalar factor, which is not a Slate tensor.

• tensor (TensorBase) – The Slate tensor to scale.

Initialise the scalar multiplication node.

property arg_function_spaces

Return the function spaces on which the tensor is defined.

arguments()

Return the arguments associated with the tensor.

reconstruct(A=None)

Reconstruct this scalar multiplication with replacement operands.

class firedrake.slate.slate.Solve(A, B, decomposition=None)

Bases: BinaryOp

Abstract Slate class describing a local linear system of equations. This object is a direct solver, utilizing the application of the inverse of matrix in a decomposed form.

Parameters:

• A – The left-hand side operator.

• B – The right-hand side.

• decomposition – A string denoting the type of matrix decomposition to used. The factorizations available are detailed in the Factorization documentation.

Constructor for the Solve class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns the arguments of a tensor resulting from applying the inverse of A onto B.

prec = 3

class firedrake.slate.slate.Tensor(form, diagonal=False)

Bases: TensorBase

This class is a symbolic representation of a finite element tensor derived from a bilinear or linear form. This class implements all supported ranks of general tensor (rank-0, rank-1 and rank-2 tensor objects). This class is the primary user-facing class that the Slate symbolic algebra supports.

Parameters:

form – a ufl.Form object.

A ufl.Form is currently the only supported input of creating a \(slate.Tensor\) object:

1. If the form is a bilinear form, namely a form with two ufl.Argument objects, then the Slate Tensor will be a rank-2 Matrix.

2. If the form has one \(ufl.Argument\) as in the case of a typical linear form, then this will create a rank-1 Vector.

3. A zero-form will create a rank-0 Scalar.

These are all under the same type \(slate.Tensor\). The attribute \(self.rank\) is used to determine what kind of tensor object is being handled.

Constructor for the Tensor class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns a tuple of arguments associated with the tensor.

block(indices)

Returns the \(ExtractSubBlock\)-split form for \(indices\), memoized on this Tensor so repeated requests for the same indices are identical, not merely equal.

coefficients()

Returns a tuple of coefficients associated with the tensor.

constants()

Returns a tuple of constants associated with the tensor.

empty()

Returns whether the form associated with the tensor is empty.

operands = ()

prec = 0

reconstruct(form, diagonal=None)

Reconstructs this Tensor with new operands.

slate_coefficients()

Returns a tuple of coefficients associated with the tensor.

subdomain_data()

Returns a mapping on the tensor: {domain:{integral_type: subdomain_data}}.

terminal = True

ufl_domains()

Returns the integration domains of the integrals associated with the tensor.

property ufl_operands

class firedrake.slate.slate.TensorBase(*_)

Bases: BaseForm

An abstract Slate node class.

Warning

Do not instantiate this class on its own. This is an abstract node class; is not meant to be worked with directly. Only use the appropriate subclasses.

Initialise a cache for stashing results.

Mirrors Form.

property T

abstract property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on. For example, if A is a rank-2 tensor defined on V x W, then this method returns (V, W).

abstractmethod arguments()

Returns a tuple of arguments associated with the tensor.

assembled = False

property blocks

Returns an object containing the blocks of the tensor defined on a mixed space. Indices can then be provided to extract a particular sub-block.

For example, consider the rank-2 tensor described by:

V = FunctionSpace(m, "CG", 1)
W = V * V * V
u, p, r = TrialFunctions(W)
w, q, s = TestFunctions(W)
A = Tensor(u*w*dx + p*q*dx + r*s*dx)

The tensor \(A\) has 3x3 block structure. The block defined by the form \(u*w*dx\) could be extracted with:

A.blocks[0, 0]

While the block coupling \(p\), \(r\), \(q\), and \(s\) could be extracted with:

A.block[1:, 1:]

The usual Python slicing operations apply.

property children

property coeff_map

A map from local coefficient numbers to the split global coefficient numbers. The split coefficients are defined on the pieces of the originally mixed function spaces.

abstractmethod coefficients()

Returns a tuple of coefficients associated with the tensor.

abstractmethod constants()

Returns a tuple of constants associated with the tensor.

diagonal = False

empty()

Returns whether the form associated with the tensor is empty.

property expression_hash

property id

property inv

property is_mixed

Returns \(True\) if the tensor has mixed arguments and \(False\) otherwise.

property rank

Returns the rank information of the tensor object.

property shape

Computes the shape information of the local tensor.

property shapes

Computes the internal shape information of its components. This is particularly useful to know if the tensor comes from a mixed form.

abstractmethod slate_coefficients()

Returns a tuple of Slate coefficients associated with the tensor.

solve(B, decomposition=None)

Solve a system of equations with a specified right-hand side.

Parameters:

• B – a Slate expression. This can be either a vector or a matrix.

• decomposition – A string describing the type of factorization to use when inverting the local systems. A complete list of available matrix decompositions are outlined in Factorization.

abstractmethod subdomain_data()

Returns a mapping on the tensor: {domain:{integral_type: subdomain_data}}.

terminal = False

ufl_domain()

This function returns a single domain of integration occuring in the tensor.

The function will fail if multiple domains are found.

abstractmethod ufl_domains()

Returns the integration domains of the integrals associated with the tensor.

property ufl_operands

class firedrake.slate.slate.Transpose(A)

Bases: UnaryOp

An abstract Slate class representing the transpose of a tensor.

Constructor for the TensorOp class.

property arg_function_spaces

Returns a tuple of function spaces that the tensor is defined on.

arguments()

Returns the expected arguments of the resulting tensor of performing a specific unary operation on a tensor.

Module contents