# Tools#

## Version query#

modepy.version.VERSION#

A tuple like (2013, 1, 1) indicating modepy’s version.

modepy.version.VERSION_TEXT#

A textual representation of the modepy version.

## Interpolation matrices#

modepy.vandermonde(functions, nodes)[source]#

Return a (generalized) Vandermonde matrix.

The Vandermonde Matrix is given by $$V_{i,j} := f_j(x_i)$$ where functions is the list of $$f_j$$ and nodes is the array of $$x_i$$, shaped as (d, npts), where d is the number of dimensions and npts is the number of nodes.

functions are allowed to return tuple instances. In this case, a tuple of matrices is returned–i.e. this function works directly on modepy.Basis.gradients() and returns a tuple of matrices.

Vandermonde matrices are very useful to concisely express interpolation. For instance, one may use the inverse $$V^{-1}$$ of a Vandermonde matrix $$V$$ to map nodal values (i.e. point values at the nodes corresponding to $$V$$) into modal (i.e. basis) coefficients. $$V$$ itself maps modal coefficients to nodal values. This allows easy resampling:

modepy.resampling_matrix(basis, new_nodes, old_nodes, least_squares_ok=False)[source]#

Return a matrix that maps nodal values on old_nodes onto nodal values on new_nodes.

Parameters:
• basis – A sequence of basis functions accepting arrays of shape (dims, npts), like those returned by modepy.orthonormal_basis_for_space().

• new_nodes – An array of shape (dims, n_new_nodes)

• old_nodes – An array of shape (dims, n_old_nodes)

• least_squares_ok – If False, then nodal values at old_nodes are required to determine the interpolant uniquely, i.e. the Vandermonde matrix must be square. If True, then a point-wise least-squares best-approximant is used (by ways of the pseudo-inverse of the Vandermonde matrix).

Vandermonde matrices also obey the following relationship useful for obtaining point interpolants:

$V^T [\text{interpolation coefficents to point x}] = \phi_i(x),$

where $$(\phi_i)_i$$ is the basis of functions underlying $$V$$.

modepy.inverse_mass_matrix(basis, nodes)[source]#

Return a matrix $$A=M^{-1}$$, which is the inverse of the one returned by mass_matrix().

New in version 2015.1.

modepy.mass_matrix(basis, nodes)[source]#

Return a mass matrix $$M$$, which obeys

$M_{ij} = \int_\triangle \phi_i(x) \phi_j(x) dx = (V^{-T} V^{-1})_{ij}.$
Parameters:

basis – assumed to be an orthonormal basis with respect to the $$L^2$$ inner product.

New in version 2014.1.

Using the quadrature face_quad, provide a matrix $$M_f$$ that satisfies:

$\displaystyle {(M_f)}_{ij} \approx \int_F \phi_i(r) \psi_j(r) dr,$

where $$\phi_i$$ are the (volume) Lagrange basis functions obtained from test_functions at volume_nodes, and $$\psi_j$$ are the (surface) trial_functions.

New in version 2020.3.

Using the quadrature face_quad, provide a matrix $$M_f$$ that satisfies:

$\displaystyle {(M_f)}_{ij} \approx \int_F \phi_i(r) \psi_j(r) dr,$

where $$\phi_i$$ are the (volume) Lagrange basis functions obtained from test_functions at volume_nodes, and $$\psi_j$$ are the (surface) Lagrange basis functions obtained from trial_functions at face_nodes.

New in version 2020.3.

Using the quadrature face_quad, provide a matrix $$M_f$$ that satisfies:

$\displaystyle (M_f \boldsymbol u)_i = \sum_j w_j \phi_i(r_j) u_j,$

where $$\phi_i$$ are the (volume) Lagrange basis functions obtained from test_functions at volume_nodes, and $$w_i$$ and $$r_i$$ are the weights and nodes from face_quad.

New in version 2021.2.

Differentiation is also convenient to express by using $$V^{-1}$$ to obtain modal values and then using a Vandermonde matrix for the derivatives of the basis to return to nodal values.

Return matrices carrying out differentiation on nodal values in the $$(r,s,t)$$ unit directions. (See Coordinates on the triangle and Coordinates on the tetrahedron.)

Parameters:
• basis – A sequence of basis functions accepting arrays of shape (dims, npts), like those returned by modepy.Basis.functions().

• grad_basis – A sequence of functions returning the gradients of basis, like those in modepy.Basis.gradients.

• nodes – An array of shape (dims, n_nodes)

• from_nodes – An array of shape (dims, n_from_nodes). If None, assumed to be the same as nodes.

Returns:

If grad_basis returned tuples (i.e. in 2D and 3D), returns a tuple of length dims containing differentiation matrices. If not, returns just one differentiation matrix.

Changed in version 2013.4: Added from_nodes.

modepy.diff_matrix_permutation(node_tuples, ref_axis)[source]#

Return a numpy array permutation of integers so that:

diff_matrices[ref_axis] == diff_matrices[permutation][:, permutation]


New in version 2020.1.

## Modal decay/residual#

Estimate the smoothness of a function represented in a basis returned by modepy.orthonormal_basis_for_space().

A. Kloeckner, T. Warburton, and J. S. Hesthaven. “Viscous Shock Capturing in a Time-Explicit Discontinuous Galerkin Method”. Mathematical Modelling of Natural Phenomena 6, No. 3 (May 16, 2011): 57-83. http://dx.doi.org/10.1051/mmnp/20116303 http://arxiv.org/abs/1102.3190

New in version 2013.2.

modepy.modal_decay.simplex_interp_error_coefficient_estimator_matrix(unit_nodes: ndarray, order: int, n_tail_orders: int) [source]#

Return a matrix $$C$$ that, when multiplied by a vector of nodal values, yields the coeffiicients belonging to the basis functions of the n_tail_orders highest orders.

The 2-norm of the resulting coefficents can be used as an estimate of the interpolation error.

New in version 2018.1.

modepy.modal_decay.fit_modal_decay(coeffs: ndarray, dims: int, n: int, ignored_modes: int = 1) [source]#

Fit a curve to the modal decay on each element.

Parameters:
• coeffs – an array of shape (num_elements, num_modes) containing modal coefficients of the functions to be analyzed.

• dims – number of dimensions.

• ignored_modes – the number of modal coefficients to ignore at the beginning. The default value of ‘1’ ignores the constant.

Returns:

a tuple (expn, constant) of arrays of length num_elements, where the modal decay is fit to the curve constant * total_degree**exponent. -exponent-1 can be used as a rough indicator of how many continuous derivatives the underlying function possesses.

modepy.modal_decay.estimate_relative_expansion_residual(coeffs: ndarray, dims: int, n: int, ignored_modes: int = 1) [source]#

Use the modal fit to estimate the relative residual of the expansion. The arguments to this function exactly match fit_modal_decay().

Returns:

An array of estimates of the fraction of the $$L^2$$ norm contained in the (unrepresented) tail of

H. Feng and C. Mavriplis, “Adaptive Spectral Element Simulations of Thin Premixed Flame Sheet Deformations”, Journal of Scientific Computing, Volume 17, Nr. 1, S. 385-395, Dec. 2002. http://dx.doi.org/10.1023/A:1015137722700

For this function, however, the decay curve is fitted using the Kloeckner/Warburton/Hesthaven technique (see above).

### Transformations between coordinate systems on the simplex#

All of these expect and return arrays of shape (dims, npts).

modepy.tools.equilateral_to_unit(equi)[source]#
modepy.tools.barycentric_to_unit(bary)[source]#
Parameters:

bary – shaped (dims+1, npoints)

modepy.tools.unit_to_barycentric(unit)[source]#
Parameters:

unit – shaped (dims,npoints)

modepy.tools.barycentric_to_equilateral(bary)[source]#

### Interpolation quality#

modepy.tools.estimate_lebesgue_constant(n, nodes, shape=None, visualize=False)[source]#

Estimate the Lebesgue constant of the nodes at polynomial order n.

Parameters:
Returns:

the Lebesgue constant, a scalar.

New in version 2013.2.

Changed in version 2020.2: domain parameter was added with support for nodes on the unit hypercube (i.e. unit square in 2D and unit cube in 3D).

Changed in version 2020.3: Renamed domain to shape.

### DOF arrays of tensor product discretizations#

modepy.tools.reshape_array_for_tensor_product_space(space: TensorProductSpace, ary: ReshapeableT, axis=- 1) [source]#

Return a reshaped view of ary that exposes the tensor product nature of the space. Axis number axis of ary must index coefficients corresponding to a tensor-product-structured basis (e.g. modal or nodal coefficients).

Parameters:
• ary – an array with last dimension having a length matching the space_dim of space.

• resultary reshaped with axis number axis replaced by a tuple of dimensions matching the dimensions of the spaces making up the tensor product. Variation of the represented function along a given dimension will be represented by variation of array entries along the corresponding array axis.

modepy.tools.unreshape_array_for_tensor_product_space(space: TensorProductSpace, ary: ReshapeableT, axis=- 1) [source]#

Undoes the effect of reshape_array_for_tensor_product_space(), given the same space and axis.

### Types used in documentation#

class modepy.tools.ReshapeableT#

An array-like protocol that supports finding the shape and reshaping.