A representation of finite element variational forms. More...

#include <Form.h>

Public Types
using	scalar_type = T
	Scalar type.

using	geometry_type = U
	Geometry type.

Public Member Functions
template<typename X> requires std::is_convertible_v< std::remove_cvref_t<X>, std::map<std::tuple<IntegralType, int, int>, integral_data<scalar_type, geometry_type>>>
	Form (const std::vector< std::shared_ptr< const FunctionSpace< geometry_type > > > &V, X &&integrals, std::shared_ptr< const mesh::Mesh< geometry_type > > mesh, const std::vector< std::shared_ptr< const Function< scalar_type, geometry_type > > > &coefficients, const std::vector< std::shared_ptr< const Constant< scalar_type > > > &constants, bool needs_facet_permutations, const std::map< std::shared_ptr< const mesh::Mesh< geometry_type > >, std::span< const std::int32_t > > &entity_maps)
	Create a finite element form.

	Form (const Form &form)=delete
	Copy constructor.

	Form (Form &&form)=default
	Move constructor.

virtual	~Form ()=default
	Destructor.

int	rank () const
	Rank of the form.

std::shared_ptr< const mesh::Mesh< geometry_type > >	mesh () const
	Common mesh for the form (the 'integration domain').

const std::vector< std::shared_ptr< const FunctionSpace< geometry_type > > > &	function_spaces () const
	Function spaces for all arguments.

std::function< void(scalar_type , const scalar_type , const scalar_type , const geometry_type , const int , const uint8_t , void *)>	kernel (IntegralType type, int id, int kernel_idx) const
	Get the kernel function for an integral.

std::set< IntegralType >	integral_types () const
	Get types of integrals in the form.

std::vector< int >	active_coeffs (IntegralType type, int id) const
	Indices of coefficients that are active for a given integral (kernel).

std::vector< int >	integral_ids (IntegralType type) const
	Get the IDs for integrals (kernels) for given integral domain type.

std::span< const std::int32_t >	domain (IntegralType type, int id, int kernel_idx) const
	Mesh entity indices to integrate over for a given integral (kernel).

std::span< const std::int32_t >	domain_arg (IntegralType type, int rank, int id, int kernel_idx) const
	Argument function mesh integration entity indices.

std::span< const std::int32_t >	domain_coeff (IntegralType type, int id, int c) const
	Coefficient function mesh integration entity indices.

const std::vector< std::shared_ptr< const Function< scalar_type, geometry_type > > > &	coefficients () const
	Access coefficients.

bool	needs_facet_permutations () const
	Get bool indicating whether permutation data needs to be passed into these integrals.

std::vector< int >	coefficient_offsets () const
	Offset for each coefficient expansion array on a cell.

const std::vector< std::shared_ptr< const Constant< scalar_type > > > &	constants () const
	Access constants.

Detailed Description

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>
class dolfinx::fem::Form< T, U >

A representation of finite element variational forms.

A note on the order of trial and test spaces: FEniCS numbers argument spaces starting with the leading dimension of the corresponding tensor (matrix). In other words, the test space is numbered 0 and the trial space is numbered 1. However, in order to have a notation that agrees with most existing finite element literature, in particular

\[ a = a(u, v) \]

the spaces are numbered from right to left

\[ a: V_1 \times V_0 \rightarrow \mathbb{R} \]

This is reflected in the ordering of the spaces that should be supplied to generated subclasses. In particular, when a bilinear form is initialized, it should be initialized as a(V_1, V_0) = / ..., where V_1 is the trial space and V_0 is the test space. However, when a form is initialized by a list of argument spaces (the variable function_spaces in the constructors below), the list of spaces should start with space number 0 (the test space) and then space number 1 (the trial space).

Template Parameters

T	Scalar type in the form.
U	Float (real) type used for the finite element and geometry.
Kern	Element kernel.

Constructor & Destructor Documentation

◆ Form()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

template<typename X>
requires std::is_convertible_v< std::remove_cvref_t<X>, std::map<std::tuple<IntegralType, int, int>, integral_data<scalar_type, geometry_type>>>

Form	(	const std::vector< std::shared_ptr< const FunctionSpace< geometry_type > > > &	V,
		X &&	integrals,
		std::shared_ptr< const mesh::Mesh< geometry_type > >	mesh,
		const std::vector< std::shared_ptr< const Function< scalar_type, geometry_type > > > &	coefficients,
		const std::vector< std::shared_ptr< const Constant< scalar_type > > > &	constants,
		bool	needs_facet_permutations,
		const std::map< std::shared_ptr< const mesh::Mesh< geometry_type > >, std::span< const std::int32_t > > &	entity_maps )

inline

Create a finite element form.

Note: User applications will normally call a factory function rather using this interface directly.

Parameters

[in]	V	Function spaces for the form arguments, e.g. test and trial function spaces.
[in]	integrals	Integrals in the form, where `integrals[IntegralType, domain ID, kernel index]` returns the integral (`integral_data`) of type `IntegralType` over domain `ID` with kernel index `kernel index`.
[in]	coefficients	Coefficients in the form.
[in]	constants	Constants in the form.
[in]	mesh	Mesh of the domain to integrate over (the 'integration domain').
[in]	needs_facet_permutations	Set to `true` is any of the integration kernels require cell permutation data.
[in]	entity_maps	If any trial functions, test functions, or coefficients in the form are not defined on `mesh` (the 'integration domain'),`entity_maps` must be supplied. For each key (a mesh, which is different to `mesh`) an array map must be provided which relates the entities in `mesh` to the entities in the key mesh e.g. for a key/value pair `(mesh0, emap)` in `entity_maps`, `emap[i]` is the entity in `mesh0` corresponding to entity `i` in `mesh`.

Note: For the single domain case, pass an empty entity_maps.

Member Function Documentation

◆ active_coeffs()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::vector< int > active_coeffs	(	IntegralType	type,
		int	id ) const

inline

Indices of coefficients that are active for a given integral (kernel).

A form is split into multiple integrals (kernels) and each integral might container only a subset of all coefficients in the form. This function returns an indicator array for a given integral kernel that signifies which coefficients are present.

Parameters

[in]	type	Integral type.
[in]	id	Domain index (identifier) of the integral.

◆ coefficient_offsets()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::vector< int > coefficient_offsets ( ) const

inline

Offset for each coefficient expansion array on a cell.

Used to pack data for multiple coefficients in a flat array. The last entry is the size required to store all coefficients.

◆ domain()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::span< const std::int32_t > domain	(	IntegralType	type,
		int	id,
		int	kernel_idx ) const

inline

Mesh entity indices to integrate over for a given integral (kernel).

These are the entities in the mesh returned by mesh that are integrated over by a given integral (kernel).

For IntegralType::cell, returns a list of cell indices.
For IntegralType::exterior_facet, returns a list with shape (num_facets, 2), where [cell_index, 0] is the cell index and [cell_index, 1] is the local facet index relative to the cell.
For IntegralType::interior_facet the shape is (num_facets, 4), where [cell_index, 0] is one attached cell and [cell_index, 1] is the is the local facet index relative to the cell, and [cell_index, 2] is the other one attached cell and [cell_index, 1] is the is the local facet index relative to this cell. Storage is row-major.

Parameters

[in]	type	Integral type.
[in]	id	Integral domain identifier.
[in]	kernel_idx	Index of the kernel with in the domain (we may have multiple kernels for a given ID in mixed-topology meshes).

Returns: Entity indices in the mesh::Mesh returned by mesh() to integrate over.

◆ domain_arg()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::span< const std::int32_t > domain_arg	(	IntegralType	type,
		int	rank,
		int	id,
		int	kernel_idx ) const

inline

Argument function mesh integration entity indices.

Integration can be performed over cells/facets involving functions that are defined on different meshes but which share common cells, i.e. meshes can be 'views' into a common mesh. Meshes can share some cells but a common cell will have a different index in each mesh::Mesh. Consider:

auto mesh = this->mesh();
auto entities = this->domain(type, id, kernel_idx);
auto entities0 = this->domain_arg(type, rank, id, kernel_idx);

Assembly is performed over entities, where entities[i] is an entity index (e.g., cell index) in mesh. entities0 holds the corresponding entity indices but in the mesh associated with the argument function (test/trial function) space. entities[i] and entities0[i] point to the same mesh entity, but with respect to different mesh views.

Parameters

type	Integral type.
rank	Argument index, e.g. `0` for the test function space, `1` for the trial function space.
id	Integral domain identifier.
kernel_idx	Kernel index (cell type).

Returns

Entity indices in the argument function space mesh that is integrated over.

For cell integrals it has shape (num_cells,).
For exterior/interior facet integrals, it has shape (num_facts, 2) (row-major storage), where [i, 0] is the index of a cell and [i, 1] is the local index of the facet relative to the cell.

◆ domain_coeff()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::span< const std::int32_t > domain_coeff	(	IntegralType	type,
		int	id,
		int	c ) const

inline

Coefficient function mesh integration entity indices.

This method is equivalent to domain_arg, but returns mesh entity indices for coefficient Functions.

Parameters

type	Integral type.
id	Integral identifier index.
c	Coefficient index.

Returns

Entity indices in the coefficient function space mesh that is integrated over.

For cell integrals it has shape (num_cells,).
For exterior/interior facet integrals, it has shape (num_facts, 2) (row-major storage), where [i, 0] is the index of a cell and [i, 1] is the local index of the facet relative to the cell.

◆ function_spaces()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

const std::vector< std::shared_ptr< const FunctionSpace< geometry_type > > > & function_spaces ( ) const

inline

Function spaces for all arguments.

Returns: Function spaces.

◆ integral_ids()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::vector< int > integral_ids ( IntegralType type ) const

inline

Get the IDs for integrals (kernels) for given integral domain type.

The IDs correspond to the domain IDs which the integrals are defined for in the form. ID=-1 is the default integral over the whole domain.

Parameters

[in] type Integral type.

Returns: List of IDs for given integral type.

◆ integral_types()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::set< IntegralType > integral_types ( ) const

inline

Get types of integrals in the form.

Returns: Integrals types.

◆ kernel()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::function< void(scalar_type , const scalar_type , const scalar_type , const geometry_type , const int , const uint8_t , void *)> kernel	(	IntegralType	type,
		int	id,
		int	kernel_idx ) const

inline

Get the kernel function for an integral.

Parameters

[in]	type	Integral type.
[in]	id	Integral subdomain ID.
[in]	kernel_idx	Index of the kernel (we may have multiple kernels for a given ID in mixed-topology meshes).

Returns: Function to call for tabulate_tensor.

◆ mesh()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

std::shared_ptr< const mesh::Mesh< geometry_type > > mesh ( ) const

inline

Common mesh for the form (the 'integration domain').

Returns: The integration domain mesh.

◆ needs_facet_permutations()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

bool needs_facet_permutations ( ) const

inline

Get bool indicating whether permutation data needs to be passed into these integrals.

Returns: True if cell permutation data is required

◆ rank()

template<dolfinx::scalar T, std::floating_point U = dolfinx::scalar_value_t<T>>

int rank ( ) const

inline

Rank of the form.

bilinear form = 2, linear form = 1, functional = 0, etc.

Returns: The rank of the form.

The documentation for this class was generated from the following files:

/__w/dolfinx/dolfinx/cpp/dolfinx/fem/assembler.h
/__w/dolfinx/dolfinx/cpp/dolfinx/fem/Form.h

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Form()

Member Function Documentation

◆ active_coeffs()

◆ coefficient_offsets()

◆ domain()

◆ domain_arg()

◆ domain_coeff()

◆ function_spaces()

◆ integral_ids()

◆ integral_types()

◆ kernel()

◆ mesh()

◆ needs_facet_permutations()

◆ rank()