Fenics-Numpy Conversion¶

converter ¶

Conversion routines between Fenics and Numpy/Scipy.

The underlying array representation of Fenics/dolfin vectors and matrices can sometimes be intransparent. To enforce a generic and consistent interface in SPIN, this module provides bi-directional conversion routines between dolfin and Numpy/Scipy data structures. The structure of arrays not resembling coordinates is determined by the components of the underlying dolfin function space. For a vector with \(K\) components and \(N\) degrees of freedom (according to the underlying mesh), the resulting numpy array has shape \(K\times N\). For coordinate arrays, the dimension of the domain is relevant. For a mesh with \(N\) degrees of freedom, discretizing a domain of dimension \(D\), the resulting array has shape \(N\times D\).

Functions:

Name	Description
`create_dolfin_function`	Compile a dolfin function from string expressions.
`convert_to_numpy`	Convert a dolfin vector to a numpy array.
`convert_to_dolfin`	Convert a numpy array to a dolfin function.
`convert_multivector_to_numpy`	Convert a Hippylib multivector to a list of numpy arrays.
`convert_to_multivector`	Convert a list of numpy arrays to a Hippylib multivector.
`get_coordinates`	Get the coordinates of the mesh underlying a function space.
`extract_components`	Extract components of a vector defined on a vector function space.
`combine_components`	Combine a list of component vectors into a vector on a vector function space.
`convert_matrix_to_scipy`	Convert a dolfin matrix to a Scipy sparse array.

spin.fenics.converter.create_dolfin_function ¶

create_dolfin_function(string_expression: str | Iterable[str], function_space: dl.FunctionSpace) -> dl.Function

Compile a dolfin function from string expressions.

The user can either provide a single string expression for scalar function spaces, or a list for vector spaces. The number of expression strings has to match the number of components in a vector space.

Expression syntax

Expressions to be compiled in dolfin need to adhere to C++ syntax. Dolfin can compile most functions from the cmath library.

Parameters:

Name	Type	Description	Default
`string_expression`	`str \| Iterable[str]`	Expression strings to compile.	required
`function_space`	`dl.FunctionSpace`	Function space of dolfin function to create.	required

Raises:

Type	Description
`ValueError`	Checks that only a single string is supplied for scalar vector spaces.
`ValueError`	Checks that number of strings matches number of components for vector spaces.

Returns:

Type	Description
`dl.Function`	dl.Function: Created dolfin function.

spin.fenics.converter.convert_to_numpy ¶

convert_to_numpy(vector: dl.Vector | dl.PETScVector, function_space: dl.FunctionSpace) -> npt.NDArray[np.floating]

Convert a dolfin vector to a numpy array.

This method takes into account the number of components in the given function space. For \(K\) components, the resulting array has shape \(K\times N\) entries, where \(N\) is the number of dofs of the underlying mesh.

Parameters:

Name	Type	Description	Default
`vector`	`dl.Vector \| dl.PETScVector`	Vector to convert.	required
`function_space`	`dl.FunctionSpace`	Function space vector has been defined on.	required

Raises:

Type	Description
`ValueError`	Checks that the size of the vector matches the function space dimension.

Returns:

Type	Description
`npt.NDArray[np.floating]`	npt.NDArray[np.floating]: Converted numpy array.

spin.fenics.converter.convert_to_dolfin ¶

convert_to_dolfin(array: npt.NDArray[np.floating], function_space: dl.FunctionSpace) -> dl.Function

Convert a numpy array to a dolfin function.

This method is the counterpart to the convert_to_numpy method. It takes into account the number of components in the given function space. For \(K\) components, the input array has to have shape \(K\times N\) entries, where \(N\) is the number of dofs of the underlying mesh. Scalar function spaces are compatible with one-dimensional arrays as well.

Parameters:

Name	Type	Description	Default
`array`	`npt.NDArray[np.floating]`	Numpy array to convert.	required
`function_space`	`dl.FunctionSpace`	Function space to project to.	required

Raises:

Type	Description
`ValueError`	Checks that the size of the array matches the function space dimension.

Returns:

Type	Description
`dl.Function`	dl.Function: Created dolfin function.

spin.fenics.converter.convert_multivector_to_numpy ¶

convert_multivector_to_numpy(multivector: hl.MultiVector, function_space: dl.FunctionSpace) -> list[npt.NDArray[np.floating]]

Convert a Hippylib multivector to a list of numpy arrays.

Strictly speaking, this method is not a Fenics converter, but specific to Hippylib. It converts a Hippylib Multivector (a compiled collection of dolfin vectors) to a list of numpy arrays. Each individual vector has to be defined from the same function space, and is converted with the convert_to_numpy method.

Parameters:

Name	Type	Description	Default
`multivector`	`hl.MultiVector`	Multivector to convert.	required
`function_space`	`dl.FunctionSpace`	Function space individual vectors have been defined on.	required

Raises:

Type	Description
`ValueError`	Checks that the size of individual vectors matches the function space dimension.

Returns:

Type	Description
`list[npt.NDArray[np.floating]]`	Iterable[npt.NDArray[np.floating]]: Converted list of arrays.

spin.fenics.converter.convert_to_multivector ¶

convert_to_multivector(list_of_arrays: Iterable[npt.NDArray[np.floating]], function_space: dl.FunctionSpace) -> hl.MultiVector

Convert a list of Numpy arrays to a Hippylib multivector.

Counterpart of the convert_multivector_to_numpy method. This method converts a list of numpy arrays to a Hippylib Multivector. The size of each individual array has to match the dimension of the supplied function space. Conversion of individual arrays is done with the convert_to_dolfin method.

Parameters:

Name	Type	Description	Default
`list_of_arrays`	`Iterable[npt.NDArray[np.floating]]`	Numpy arrays to convert.	required
`function_space`	`dl.FunctionSpace`	Function space to define dolfin vectors on.	required

Raises:

Type	Description
`ValueError`	Checks that the size of individual arrays matches the function space dimension.

Returns:

Type	Description
`hl.MultiVector`	hl.MultiVector: Output multivector.

spin.fenics.converter.get_coordinates ¶

get_coordinates(function_space: dl.FunctionSpace) -> npt.NDArray[np.floating]

Get the coordinates of the mesh underlying a function space.

For vector spaces, the same coordinates are assumed for all components, so that only the coordinates of the first component are returned. For a mesh with \(N\) vertices, in \(D\) dimensions, the resulting array has shape \(N\times D\).

Parameters:

Name	Type	Description	Default
`function_space`	`dl.FunctionSpace`	Function space to extract coordinates from.	required

Returns:

Type	Description
`npt.NDArray[np.floating]`	npt.NDArray[np.floating]: Numpy array of mesh coordinates.

spin.fenics.converter.extract_components ¶

extract_components(vector: dl.Vector | dl.PETScVector, components: Iterable[dl.Vector | dl.PETScVector], function_space: dl.FunctionSpace) -> Iterable[dl.Vector | dl.PETScVector]

Extract components of a dolfin vector defined on a vector function space.

This method extracts the components of a vector defined on a vector function space and returns a list of scalar vectors defined on the respective subspaces. The vector function space needs to be homogeneous, mixed spaces are not supported.

In-place operation

This method modifies the components in-place, which have to be provided as input argument. No new memory is allocated.

Parameters:

Name	Type	Description	Default
`vector`	`dl.Vector \| dl.PETScVector`	Vector to split up.	required
`components`	`Iterable[dl.Vector \| dl.PETScVector]`	Components to write vector content to.	required
`function_space`	`dl.FunctionSpace`	Vector function space of the initial vector.	required

Raises:

Type	Description
`ValueError`	Checks that the number of components matches the number of subspaces.
`ValueError`	Checks that the size of the input vector matches the function space dimension.

Returns:

Type	Description
`Iterable[dl.Vector \| dl.PETScVector]`	Iterable[dl.Vector \| dl.PETScVector]: Iterable of component vectors.

spin.fenics.converter.combine_components ¶

combine_components(components: Iterable[dl.Vector, dl.PETScVector], vector: dl.Vector | dl.PETScVector, function_space: dl.FunctionSpace) -> dl.Vector | dl.PETScVector

Combine a list of component vectors into a vector on a vector function space.

In-place operation

This method modifies the vector in-place, which has to be provided as input argument. No new memory is allocated.

Parameters:

Name	Type	Description	Default
`components`	`Iterable[dl.Vector, dl.PETScVector]`	Components to assemble into vector.	required
`vector`	`dl.Vector \| dl.PETScVector`	Combined vector.	required
`function_space`	`dl.FunctionSpace`	Vector function space for combined vector.	required

Raises:

Type	Description
`ValueError`	Checks that the number of components matches the number of subspaces.
`ValueError`	Checks that the size of the output vector matches the function space dimension.

Returns:

Type	Description
`dl.Vector \| dl.PETScVector`	dl.Vector \| dl.PETScVector: Combined vector.

spin.fenics.converter.convert_matrix_to_scipy ¶

convert_matrix_to_scipy(matrix: dl.Matrix | dl.PETScMatrix) -> sp.sparse.coo_array

Convert a dolfin matrix to a Scipy sparse array.

Parameters:

Name	Type	Description	Default
`matrix`	`dl.Matrix \| dl.PETScMatrix`	Dolfin matrix to convert	required

Returns:

Type	Description
`sp.sparse.coo_array`	sp.sparse.coo_array: Scipy COO array