FEATool Multiphysics  v1.10
Finite Element Analysis Toolbox
Quickstart Guide

The quickstart guide explains how to install and start FEATool Multiphysics as well as describes the modeling and simulation process. Furthermore, step by step instructions how to set up and solve five modeling examples illustrating different techniques and features of FEATool is also included.

1. Introductory example of modeling stresses and strains in a thin plate with a hole.

2. Multiphysics example coupling heat and fluid flow in a heat exchanger.

3. Equation editing example modeling axisymmetric fluid flow in a narrowing pipe.

4. Classic equation example for the Poisson equation on a circle with a point source.

5. Custom equation example for solving the wave equation on a circle.

Prerequisites

The FEATool Multiphysics simulation toolbox is written in the m-script language, which requires MATLAB to run and interpret the source code. MATLAB is available from The Mathworks Inc.

FEATool has been verified work with Windows, Mac, and Linux operating systems running MATLAB versions 7.9 (R2009b) and later. Furthermore, a system with 4 GB or more RAM memory is recommended.

Installation

In order to use the FEATool Multiphysics, toolbox the included files and directories must be installed on the intended computer system. It is recommended to first uninstall older versions of FEATool before updating to a newer version.

To install, first download and extract the FEATool distribution and software archive.

  • For MATLAB 2012b and later double click on the FEATool Multiphysics.mlappinstall file, or use the Get More Apps button in the MATLAB APPS toolbar. Once the app has been installed, a corresponding icon will be available in the toolbar to start FEATool. (Note that MATLAB may not show or give any indication of the app installation progress or completion.)
featool-multiphysics-toolbox-installation_50.jpg
  • For MATLAB 2009b-2012a, use the addpath command to add the extracted featool program directory to the MATLAB search paths, so that the program files can be found by the interpreter (for example addpath C:\featool). Then enter the command featool at the MATLAB command prompt to start the toolbox GUI and application.

Please note, that using spaces in user and installation directory paths is not recommended as it may cause issues with the external grid generation and solver interfaces. Moreover, as all functions are initially loaded into memory, FEATool may take some time to load and show the GUI on initial startup.

Registration

If you have purchased a FEATool license, you can use the one-time registration and activation token you received to generate a license key for your system.

To register and activate your license, start the FEATool GUI on the computer system you wish to activate (each registration token is only valid for a single use, and can only activate one system). Make sure your system is connected to the internet and not blocked by firewalls, then select the Register FEATool... option from the Help menu.

featool-registration-process_50.jpg

A dialog box will open where you can enter the registration token. Press the OK button and wait for confirmation that the licensing server has received your token, system information, and generated a license key. After the sever has sent the license key it will be saved and stored in the FEATool users directory, after which the registration process is complete. (It is recommended to restart both MATLAB and FEATool after registration to clear the memory and reset persistent functions).

To verify that your license has been registered select About FEATool... from the Help menu. The About FEATool dialog box will show the license type and duration.

Verification

To verify that FEATool has been installed correctly, launch FEATool by clicking on the corresponding icon in the MATLAB Add-Ons toolbar (or type featool on the command line when not using FEATool as a toolbox).

The FEATool installation can then be tested and validated by running the simulation model and example test suites by starting FEATool with either of these commands

featool testt    % Run tests for GUI tutorials
featool teste    % Run tests for m-script examples
featool test     % Run all test suites

Please note that running the test suites may take a significant amount of time.

External Solvers

FEATool Multiphysics includes both GUI and CLI support for the FEniCS, Firedrake, and OpenFOAM solvers. Due to very differing system and installation processes these solvers must be installed by the user separately. Please consult the corresponding FEniCS and OpenFOAM sections for suggested installation and usage.

External Grid Generators

FEATool Multiphysics comes with built-in support for the external mesh generators Gmsh, Gridgen2D (included with the FEATool distribution), and Triangle. External grid generators typically allows for faster and more robust grid generation, and also supports specifying different grid sizes on subdomains and boundaries. The Grid Generation Algorithm can be selected with the corresponding option in the Grid Generation Settings dialog box.

If Gmsh or Triangle is selected as grid generation algorithm and FEATool cannot find the corresponding binaries, they will automatically be downloaded, and installed when an internet connection is available. Alternatively, the mesh generator binaries can downloaded from the external grid generators repository and/or compiled manually and installed into any of the directories available on the MATLAB paths (external binaries are typically placed in the bin folder of the FEATool installation directory).

Modeling Process

The typical modeling process in FEATool logically follows the six mode buttons located in the upper portion of the left side toolbar in the main graphical user interface (GUI) window. The modeling steps are thus as follows:

  • The first step is to create a geometry to define the domain to be modeled. Geometry objects such as rectangles, circles, blocks, and cylinders can be created and combined to represent complex domains.
  • From the geometry a grid or mesh can be generated or imported from an external preprocessing tool or grid generator. The modeled phenomena is to be approximated on each grid cell by a finite element polynomial or shape function. Finer more dense grids and regularly shaped high quality grid cells generally leads to more accurate solutions.
  • Equations (PDEs) and model coefficients are then specified in subdomain/equation mode to describe the physical phenomena to be modeled. Equations are pre-defined for many types of physical phenomena like for example heat transfer, structural strains and stresses, and fluid flow. In addition FEATool also allows arbitrary and custom systems of PDE equations to be described and entered.
  • Boundary conditions must be prescribed on the geometrical boundaries to account for interactions with the surroundings outside of the modeled domain. For time dependent problems initial conditions must also be given at the start of the simulations.
  • After the model problem is fully specified a suitable solver can be employed to compute a solution. FEATool can either use the default MATLAB linear solvers or use specialized external ones, such as the OpenFOAM CFD solver or FEniCS for increased performance.
  • Finally, after the problem has been solved, the solution can be visualized, postprocessed, and exported to evaluate the computed results.

Tutorials and Examples

Pre-defined automated modeling tutorials and examples for a selection of multi-physics applications can be run directly from the File > Model Examples and Tutorials menu option.

featool-multiphysics-automated-simulation-tutorials_50.jpg

Example m-script files and simulation models are also available in the examples folder of the FEATool program directory. Moreover, more tutorials and articles are published on the FEATool Technical Articles Blog.

The following five tutorials illustrate how to set up, define, and solve typical models with FEATool.

Structural Mechanics Example - Thin Plate with Hole

Multiphysics Example - Heat Exchanger

Equation Editing Example - Axisymmetric Fluid Flow

Classic Equation Example - Poisson Equation with a Point Source

Custom Equation Example - Wave Equation on a Circle

Working with FEATool

FEATool Multiphysics is unique in that it allows several different ways for users to work with FEM modeling and simulation. The whole spectrum from using the high-level graphical user interface down to low-level access of the fundamental matrices of the underlying finite element FEM discretization is possible. On top of this, since FEATool is written in m-script code, it can be extended and combined with MATLAB toolboxes and custom m-file scripts and functions. The four different ways of working with FEATool are using

  1. Graphical User Interface (GUI)
  2. Pre-defined physics modes
  3. Weak FEM equation formulation
  4. Direct matrix assembly

where the last three approaches involve leaving the GUI behind in favor of the MATLAB command line and m-script files.

Graphical User Interface (GUI)

Designed with ease of use in mind, the graphical user interface or GUI is usually the first way one works with FEATool.

featool-multiphysics-easy-to-use-gui_50.jpg

Although simple in nature, the FEATool GUI allows for some powerful features that can be utilized to extend code functionality. Every action taken in the GUI is recorded and can either saved as a Finite Element Script (fes) which can later be replayed in the GUI and is very suitable for creating tutorials. Alternatively the modeling process can be exported as standard MATLAB m-script text files suitable for command line use.

It is also possible to import and export data and variables between the GUI and MATLAB main command line workspaces by using the corresponding Import and Export menu options under the File menu.

featool-multiphysics-matlab-gui-import-and-export_50.jpg

For example, the variable fea contains the FEATool finite element struct for the current model. For example, try exporting it to the main MATLAB workspace and entering the command fea to see what the fea struct contains. More information about the composition of the fea struct can be found in the problem definition section. Be aware that manipulating this variable directly in the GUI may cause the program to crash if invalid input is given. (Beware that importing and overwriting the fea struct in the GUI is not recommended, and may cause unintended consequences.)

Pre-defined physics modes

The first step in working with MATLAB command line and m-script FEATool models is generally to use the pre-defined physics modes. A good way to understand and learn how FEATool script models are built up and constructed is to use the Save As M-Script Model... option instead of the binary (fea) model format file.

featool-multiphysics-save-as-matlab-model-m-script-file_50.jpg

The output MATLAB m-script model source files can be opened in any text editor and the shown output corresponds directly with how the model was constructed in the GUI. Everything from the geometry definition, to solving and postprocessing has corresponding MATLAB function commands.

An example of solving the Poisson equation for a unit line defined with the Poisson physics mode can be found as the CLI Tutorial Using Physics Modes tutorial example. As can be seen in the example code, the physics modes are stored in the fea.phys field of the fea model definition struct. The actual strong PDE formulation is defined in the seqn sub-field, in this case

fea = addphys( fea, @poisson );
fea.phys.poi.eqn.seqn = 'dts_poi*u' - d_poi*(ux_x + uy_y) = f_poi'

PDE equation coefficients can be specified as

fea.phys.poi.eqn.coef = { 'dts_poi' [] [] { 1 } ;
                          'd_poi'   [] [] { 1 } ;
                          'f_poi'   [] [] { 1 } ;
                          'u0_poi'  [] [] { 0 } };

where u0_poi is the initial condition for the dependent variable u as defined in fea.phys.poi.dvar. Similarly Dirichlet and Neumann boundary conditions can be prescribed through the bcr_poi and bcg_poi coefficients, respectively

fea.phys.poi.bdr.sel  = 1;
fea.phys.poi.bdr.coef = ...
 { 'bcr_poi' [] [] [] [] [] { 0 } ;
   'bcg_poi' [] [] [] [] [] { 1 } };

Lastly, the command parsephys

fea = parsephys( fea );

parses the equations in all the fea.phys structs and enters the corresponding weak finite element formulations into the global fea.eqn and fea.bdr multiphysics fields.

Weak FEM equation formulation

If one prefers to directly work with the FEM weak formulations this is also possible as shown in the CLI Tutorial Without Physics Modes example for the same Poisson problem as above. Note how there is no phys field or call to parsephys necessary when directly prescribing the fea.eqn and fea.bdr fields

fea.eqn.a.form = { [2 3; 2 3] };
fea.eqn.a.coef = { [1 1] };
fea.eqn.f.form = { 1 };
fea.eqn.f.coef = { 1 };

n_bdr          = max(fea.grid.b(3,:));
fea.bdr.d      = cell(1,n_bdr);
[fea.bdr.d{:}] = deal(0);
fea.bdr.n      = cell(1,n_bdr);

Direct matrix assembly

Finally, for advanced FEM users it is entirely possible to use the core finite element assembly routines assemblea and assemblef to assemble the system matrix and right hand side/load vector after which they can be directly manipulated. Again, the corresponding Poisson problem example is described in the Poisson equation CLI tutorials. The source code for the matrix and source term vector assembly looks like the following

form  = [2 3;2 3];
sfun  = {'sflag1';'sflag1'};
coef  = [1 1];
i_cub = 3;   % Numerical quadrature rule to use.

[vRowInds,vColInds,vAvals,n_rows,n_cols] = ...
     assemblea( form, sfun, coef, i_cub,  ...
       fea.grid.p, fea.grid.c, fea.grid.a );

A = sparse( vRowInds, vColInds, vAvals, n_rows, n_cols );


form  = [1];
sfun  = {'sflag1'};
coef  = [1];
i_cub = 3;

f = assemblef( form, sfun, coef, i_cub, ...
      fea.grid.p, fea.grid.c, fea.grid.a );

Note that here we have to directly prescribe boundary conditions to the system matrix and right hand side vector.

Altogether one can see that FEATool together with MATLAB allows for many possibilities to set up, perform, and analyze multiphysics FEM simulations.