FEATool Multiphysics  v1.13
Finite Element Analysis Toolbox
FEniCS FEA Solver

The FEniCS and related Firedrake Projects are Finite Element Analysis (FEA) computing platforms, aimed at modeling and solving general systems of PDEs such as found in engineering and coupled multiphysics problems [1,2]. In contrast to MATLAB, FEniCS have support parallel execution allowing for large models to be efficiently solved. (FEniCS has been tested on problem sizes up to 108 degrees of freedom run on 512 CPUs in parallel [3].)

As both FEATool Multiphysics and FEniCS represent and model equations with the Finite Element Method (FEM) it is possible to directly translate the FEATool PDE syntax and convert it to equivalent FEniCS Python scripts. Since the equations are discretized in the same way, the produced solutions should also be virtually identical, making it possible to use FEniCS to validate and double check simulation results.

Basic Use

Similar to what has been done with the OpenFOAM and SU2 CFD solvers, the FEATool-FEniCS solver integration allows for easy and convenient conversion, export, solving, and re-importing models between FEATool and FEniCS directly from the GUI, as well as the MATLAB command line interface.

Control Panel

To use the FEniCS solver instead of the default solver, press the button in Solve Mode toolbar. This will open the FEniCS solver settings dialog box and control panel.

fenics_dlg_50.png

The Python code resulting from translating the current model to FEniCS syntax is shown in the Problem Data frame. This script can be inspected and manually edited, as well as changing the output File Name and system/shell Solve Command to run it (which is bash and python or python3 by default).

In the lower control button panel, the Solve button will start the automatic solution process with the current FEniCS script if the Auto toggle button is active. This means that the following steps are performed in sequence

  1. Export - export compatible FEniCS Python script and mesh files
  2. Solve - performs a system/subprocess call to the FEniCS solver and starts a monitoring process
  3. Import - interpolates and imports the computed solution back into FEATool for postprocessing and visualization

With the Auto toggle button disengaged, the Solve button only execute the FEniCS Python script in a bash shell if present (not export or import). The Export option saves the current grid in Dolfin XML format and exports the FEniCS simulation script, while Import will (interpolate and) import an existing solution if it matches with the FEATool problem definition.

Command Line Use

The installed fenics MATLAB function can also be used on the command line (CLI) to manually perform the export, solve, and import actions. In the following is an example to set up a simple heat transfer model on a unit circle with a unit heat source term, and T=0 fixed temperature on all the boundaries. In the MATLAB m-script language the model will look like the following

fea.sdim = {'x' 'y'};
fea.grid = quad2tri(circgrid());

fea = addphys(fea, @heattransfer);
fea.phys.ht.eqn.coef{6,end} = {1};   % Heat source term.
fea.phys.ht.bdr.sel(:) = 1;          % Zero temperature boundary conditions.

fea = parsephys(fea);                % Parse physics mode and fea problem struct.
fea = parseprob(fea);

fea.sol.u = solvestat(fea);

postplot(fea, 'surfexpr', 'T')

Similar to the solvetime and solvetime functions, the FEniCS solver can be called with a fenics function call

fea = fenics( fea );

This automatically converts the FEATool problem defined in the fea struct and calls FEniCS to compute a solution to the problem. The returned solution will be assigned to the fea.sol.u field.

If required the solver modes or phases can be called separately (available modes are check, export, solve, and import). For example, for the export mode

fenics( fea, 'modes', 'export' )

generates a Dolfin XML grid file featool-fenics.xml and FEniCS simulation script file featool-fenics.py as well as control shell files to call the FEniCS solver. For example, the FEniCS Python FEM script for the model above is shown below

from fenics import *

# Mesh and subdomains.
mesh = Mesh("featool-fenics.xml")

# Finite element and function spaces.
E0 = FiniteElement("P", mesh.ufl_cell(), 1)
V = FunctionSpace(mesh, E0)
T = Function(V)
T_t = TestFunction(V)

# Model constants and expressions.
rho = Constant(1)
cp = Constant(1)
k = Constant(1)
u = Constant(0)
v = Constant(0)
q = Constant(1)

# Bilinear forms.
a = ( (rho*cp*u)*T*T_t.dx(0) + (k)*T.dx(0)*T_t.dx(0) + \
      (rho*cp*v)*T*T_t.dx(1) + (k)*T.dx(1)*T_t.dx(1) )*dx

# Linear forms.
f = q*T_t*dx

# Boundary conditions.
dbc0 = DirichletBC(V, Constant(0), 0)
dbc1 = DirichletBC(V, Constant(0), 1)
dbc2 = DirichletBC(V, Constant(0), 2)
dbc3 = DirichletBC(V, Constant(0), 3)
dbc = [dbc0, dbc1, dbc2, dbc3]

# Initial conditions.
assign(T, interpolate( Constant(0), V))

# Solve.
solve( a - f == 0, T, dbc )

# Output.
import numpy as np
T_h = T.compute_vertex_values(mesh)
np.savetxt("featool_fenics_sol.txt", np.column_stack((T_h)))

The generated FEniCS Python script is longer and somewhat more verbose since all the FEATool physics mode defaults must be explicitly expressed.

The solution process will generate the file featool-fenics-sol.txt containing the nodal solution(s) which can be manually imported back into FEATool with

fea = fenics( fea, 'modes', 'import' );

which it can be postprocessed and visualized with the usual FEATool plotting functionality.

Moreover, the fenics_data function can also be used to convert FEATool problem structs to FEniCS format and export the corresponding FEniCS script problem files.

The m-script examples listed in the FEniCS tutorials section similarly allow for using the FEniCS solver instead of the default solver. Furthermore, the fenics function can also be embedded in user-defined custom m-scripts, which can use all other MATLAB functions and toolboxes.

Advanced Use

The FEniCS solver is capable of performing large scale simulations, and although technically possible to use FEATool Multiphysics to do this, for memory and stability reasons it is not advised to do this from within MATLAB.

For larger simulations it is recommended to export FEA models with the fenics export command or Export button in the FEniCS Settings dialog box. This will generate FEniCS Python scripts and mesh files. Then one can manually launch the FEniCS solver the system command line, and import the solution back into the FEATool GUI when the solution has finished.

Notes

The FEATool-FEniCS integration and problem file export should work for general multiphysics problems using both the GUI and command line. However, a subset of FEATool functionality is currently not supported (the known ones are listed here)

  • Point source terms are not supported by the FEniCS non-linear solution form (which is used by default since it also handles linear problems).
  • FEniCS does not currently support quadrilateral or hexahedral grid cells and must be converted to triangles and tetrahedra, respectively. Grid conversion of these types of grids can be performed directly in the GUI or with the quad2tri and hex2tet commands. Typically this will not be an issue since FEATool and the automatic mesh generator gridgen by default creates simplex type grid cells (line segments, triangles, and tetrahedra).

Installation

The FEATool-FEniCS solver integration has been extensively tested and verified with FEniCS version 2019.1.0, and works by performing system calls to the Python interpreter (with FEniCS installed).

The FEniCS software and Python are due to licensing and compatibility with various systems currently not included with the FEATool distribution, and must be installed separately (compiled directly from source code if required). The FEniCS homepage and reference manual provides instructions how to install FEniCS on various systems (note that Docker is currently not supported by FEATool).

For Ubuntu Linux and Windows 10 with Windows Subsystem for Linux (WSL) systems, FEniCS can be installed by opening a terminal shell and running the following commands (which automatically also installs required dependencies such as the Python programming language interpreter)

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:fenics-packages/fenics
sudo apt-get update
sudo apt-get install --no-install-recommends fenics

Although not necessary for FEATool-FEniCS functionality, to allow FEniCS plotting and visualization in Python with Matplotlib it is also necessary to install an X window server such as Xming on Windows systems using WSL FEniCS (note that plotting and output of solution variables is disabled by default during FEATool-FEniCS script export).

Verification

Select System Info... from the Help menu to verify that the correct Python and FEniCS installation can be found by FEATool. This will open a dialog box with details for the current system and FEATool configuration. Find the line item labeled FEniCS: and verify that it reports the correct FEniCS version number, for example

...
FEniCS Version: 2019.1.0
...

Tutorials

Although not directly illustrating use of the FEniCS solver, the majority of the tutorials available when selecting an example in the File > Model Examples and Tutorials... menu also allow for using FEniCS instead of the default solver.

The following m-script models, found in the in the examples directory of the FEATool installation folder, feature a 'solver', 'fenics' input parameter which can be used to directly enable the FEniCS solver

Further Information

Further information about FEniCS and its usage can be found on the official FEniCS homepage and FEniCS documentation.

References

[1] FEniCS Project homepage, 2020.

[2] Firedrake Project homepage, 2020.

[3] FEniCS-HPC website - Automated solution of PDE by high performance FEM, 2020.