dxh module#

Helper functions for DOLFINx.

dxh.define_dirichlet_boundary_condition(boundary_value, function_space=None, *, boundary_indicator_function=None)[source]#

Define DOLFINx object representing Dirichlet boundary condition.

Parameters:

boundary_value (Function | Constant | float) – Fixed value(s) to enforce at domain boundary, either as a single floating point (or dolfinx.fem.Constant) value or a finite element function object which gives the required values when evaluated at the boundary degrees of freedom.
function_space (Optional[FunctionSpace]) – Argument specifying finite element function space from which boundary degrees of freedom should be computed. If boundary_values is a dolfinx.fem.Function instance then should be set to None (the default) as in this case boundary_values.function_space will be used as the relevant function space.
boundary_indicator_function (Optional[Callable[[SpatialCoordinate], bool]]) – If specified, a function evaluating to True when the passed spatial coordinate is on the boundary and False otherwise. If not specified (the default) then the boundary is assumed to correspond to all exterior facets.

Return type:

DirichletBC

Returns:

Dirichlet boundary condition object.

dxh.error_norm(function_1, function_or_expression_2, degree_raise=3, norm_order=2)[source]#

Compute Lᵖ error norm between a function and another function or expression.

For scalar-valued functions \(f_1: \Omega \to \mathbb{R}\) and \(f_2: \Omega \to \mathbb{R}\) the \(L^p\) error norm is defined for \(1 \leq p \leq \infty\) as

\[\Vert f_1 - f_2 \Vert_p = \left( \int_{\Omega} |f_1(x) - f_2(x)|^p \, \mathrm{d}x \right)^{1/p}\]

and for \(p = \infty\) as

\[\Vert f_1 - f_2 \Vert_{\infty} = \sup_{x \in \Omega} |f_1(x) - f_2(x)|.\]

The impementation here interpolates the functions in to a higher-order finite element function space and computes the difference by directly subtracting the degrees of freedom arrays of the interpolated functions, this giving more numerically robust error norm estimates compared to a more direct implementation.

For the \(p = \infty\) case the implementation here approximates the norm by computing the maximum difference across the degrees of freedom (DOF) of the (interpolated) functions. This will only directly approximate the \(L^\infty\) norm as defined above for finite element functions defined on elements for which the DOF all correspond to pointwise evaluations of the function.

Adapted from the example code by Jørgen S. Dokken at https://jsdokken.com/dolfinx-tutorial/chapter4/convergence.html which is distributed under the terms of the Creative Commons Attribution 4.0 International License (http://creativecommons.org/licenses/by/4.0/).

Parameters:

function_1 (Function) – Finite element function to evaluate error for.
function_or_expression_2 (Function | Expr | Callable[[SpatialCoordinate], Expr]) – Finite element function, UFL expression in spatial coordinate of a finite element mesh or callable object returning UFL expression given a spatial coordinate, corresponding to function to compute error difference from.
degree_raise (int) – Non-negative integer specifying by increment to add to polynomial degree of finite element space for interpolating functions in to.
norm_order (Literal[1, 2, 'inf-dof']) – Order \(p\) of norm to compute. Currently only \(p = 1\), \(p = 2\) and \(p = \infty\) are supported (\(p = \infty\) is specified by passing a string "inf-dof" - see note above with regards to definition).

Return type:

float

Returns:

Computed Lᵖ error norm value.

dxh.evaluate_function_at_points(function, points)[source]#

Evaluate a finite element function at one or more points.

Parameters:

function (Function) – Finite element function to evaluate.
points (ndarray[Any, dtype[float64]]) – One or more points in domain of function to evaluate at. Should be either a one-dimensional array corresponding to a single point (with size equal to the geometric dimension or 3) or a two-dimensional array corresponding to one point per row (with size of last axis equal to the geometric dimension or 3).

Return type:

ndarray[Any, dtype[float64]]

Returns:

Value(s) of function evaluated at point(s).

dxh.get_matplotlib_triangulation_from_mesh(mesh)[source]#

Get Matplotlib triangulation corresponding to DOLFINx mesh.

Parameters:: mesh (Mesh) – Finite element mesh to get triangulation for.
Return type:: Triangulation
Returns:: Object representing triangulation of mesh to use in Matplotlib plot functions.

dxh.plot_1d_functions(functions, *, points=None, axis_size=(5.0, 5.0), arrangement='horizontal', share_value_axis=False)[source]#

Plot one or more finite element functions on 1D domains using Matplotlib.

Parameters:

functions (Function | Sequence[Function] | dict[str, Function]) – A single finite element function, sequence of functions or dictionary mapping from string labels to finite element functions, in all cases corresponding to the function(s) to plot. If a single function or sequence of functions are specified the function name attribute(s) will be used to set the title for each axis.
points (Optional[ndarray[Any, dtype[float64]]]) – Points to evaluate and plot function at. Defaults to nodes of mesh function is defined on if None.
axis_size (tuple[float, float]) – Size of axis to plot each function on in inches as (width, height) tuple.
arrangement (Literal['horizontal', 'vertical', 'stacked']) – One of "horizontal", "vertical" or "stacked" corresponding to respectively plotting functions on separate axes in a single row, plotting functions on separate axes in a single column or plotting functions all on a single axis.
share_value_axis (bool) – Whether to use a common vertical axis scale (representing function value) across all subplots.

Return type:

Figure

Returns:

Matplotlib figure object with plotted function(s).

dxh.plot_2d_functions(functions, *, plot_type='pcolor', axis_size=(5.0, 5.0), colormap=None, show_colorbar=True, triangulation_color=None, arrangement='horizontal', share_value_axis=False)[source]#

Plot one or more finite element functions on 2D domains using Matplotlib.

Can plot either pseudocolor plots (heatmaps) for each function showing variation in function value by color mapping or a three-dimensional surface plot with height coordinate corresponding to function value.

Parameters:

functions (Function | list[Function] | dict[str, Function]) – A single finite element function, sequence of functions or dictionary mapping from string labels to finite element functions, in all cases corresponding to the function(s) to plot. If a single function or sequence of functions are specified the function name attribute(s) will be used to set the title for each axis.
plot_type (Literal['pcolor', 'surface']) – String specifying type of plot to use for each function: Either "pcolor" for a pseudo color plot with function value represented by color, or "surface" for a surface plot with function value represented by surface height.
axis_size (tuple[float, float]) – Size of axis to plot each function on in inches as (width, height) tuple.
colormap (UnionType[str, Colormap, None]) – Matplotlib colormap to use to plot function values (if None default colormap is used).
show_colorbar (bool) – Whether to show a colorbar key showing color mapping for function values.
triangulation_color (UnionType[str, tuple[float, float, float], None]) – If not None, specifies the color (either as a string or RGB tuple) to use to plot the mesh triangulation as an overlay on heatmap.
arrangement (Literal['horizontal', 'vertical']) – Whether to arrange multiple axes vertically in a single column rather than default of horizontally in a single row.
share_value_axis (bool) – Whether to use a common vertical axis scale and/or colormap normalization (representing function value) across all subplots.

Return type:

Figure

Returns:

Matplotlib figure object with plotted function(s).

dxh.project_expression_on_function_space(expression, function_space)[source]#

Project expression onto finite element function space.

Parameters:

expression (Expr | Callable[[SpatialCoordinate], Expr]) – UFL object defining expression to project or function accepting single argument corresponding to spatial coordinate vector defining expression to project.
function_space (FunctionSpace) – Finite element function space.

Return type:

Function

Returns:

Function representing projection of expression.