FEATool Multiphysics  v1.14
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 it must first be installed on the intended computer system. The toolbox can be installed from the MATLABĀ® APPS and Add-On Toolbar, or downloaded directly from the Precise Simulation GitHub repository and installed manually.

Please follow the steps below for your matching system to install FEATool as a MATLAB toolbox. It is recommended to first uninstall previous versions of toolboxes before installing/upgrading to a newer version. Also note that, as all functionality is loaded into memory at startup, the toolbox may take some time to fully initialize and launch the GUI.

Installation for MATLAB 2012b and later

1) First download the latest FEATool Multiphysics.mlappinstall toolbox installation file (if you have downloaded a zip archive instead, then extract the mlappinstall file from inside it).

2) Then start MATLAB, press the APPS toolbar button, and select the Install App button.

3) When prompted to choose a toolbox file to install, select the FEATool Multiphysics.mlappinstall file and press OK.

4) Press the Install button if prompted to Install to My Apps?.

featool-multiphysics-toolbox-installation_50.jpg

Once the toolbox has been installed, an app icon will be available in the APPS toolbar to start the FEATool GUI.

Note that MATLAB may not show or give any indication of the toolbox installation progress or completion. Furthermore, using spaces and/or special characters in user and installation directory paths is not recommended as it may cause issues with the external grid generation and solver interfaces.

Installation for MATLAB 2009b-2012a

1) First download the latest FEATool Multiphysics zip archive and extract it to a convenient folder on your system.

2) Start MATLAB in this folder, or change to the folder location in the MATLAB CLI interpreter with the command cd path_to_featool_program_folder

3) Run the command start_featool_gui from the FEATool program folder to start the GUI.

For convenience, one can also use the addpath path_to_featool_program_folder command to permanently add the FEATool program folder to the MATLAB search paths (one can then start FEATool from any location).

Activation

If you have purchased a FEATool license, you can use the one-time activation and registration 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 activation token is only valid for a single use, and can therefore only activate one system). Make sure your system is connected to the internet and not blocked by firewalls, then select the Activate FEATool... option from the Help menu.

featool-registration-process_50.jpg

A dialog box will open where you can enter the activation 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 activation process is complete. (It is recommended to restart both MATLAB and FEATool after registration and activation to clear the memory and reset persistent functions).

To verify that your license has been activated select About FEATool... from the Help menu. The About FEATool dialog box will show the license type and duration. In the Help menu you can also open and view the System Info... and Log File..., as well as find links to the documentation and an option to Send Feedback... to the software developer directly from the toolbox.

Troubleshooting

If you get the error "IER=210, Could not find matching activation/registration token" when trying to activate it means that the entered activation token could not be found in the online licensing server database, which may have two causes

  1. There was a typo entering the activation token, if you think this is the case please check your input and try again.
  2. The activation token has already been used once, and can therefore not be used again.

Activation tokens are one time use only, and can only activate a single computer system/seat. When used, the activation token is converted to a unique license file and matched to the computer system that was used to activate the software. After activation, the actual license key is stored on your computer in the file

%USERPROFILE%/Documents/MATLAB/.featool/license.dat

Please note that, licenses are in general issued per computer system/seat so that all users on the same computer/system may use the software. To allow a different user on the same computer system to use the activated license for a system you may have to copy the above license.dat file from the corresponding directory of the original user to the new user.

De-Activation

If you want to de-activate and move an active license to a new computer/system, make sure your computer is connected to the internet, start FEATool Multiphysics, and select Release License... from the Help menu. This will deactivate, remove, and release the license from your current/old system and generate a new activation token for use with a different system.

Verification

To verify that FEATool has been installed correctly, first starting and then closing the FEATool GUI again (this ensures that the MATLAB paths are set up so that all FEATool functions can be found).

The FEATool installation can then be tested and validated by running simulation model and example test suites by using either of these MATLAB 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, OpenFOAM, and SU2 solvers. Due to very differing system and installation processes these solvers must be installed by the user separately. Please consult the corresponding FEniCS, OpenFOAM, and SU2 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 and SU2 CFD solvers 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 various multi-physics applications can be selected and run from the File > Model Examples and Tutorials menu option in the GUI.

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

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

  1. Structural Mechanics Example - Thin Plate with Hole
  2. Multiphysics Example - Heat Exchanger
  3. Equation Editing Example - Axisymmetric Fluid Flow
  4. Classic Equation Example - Poisson Equation with a Point Source
  5. 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 data struct for the current model. For example, try exporting it to MATLAB (by using the File > Export FEA Struct to MATLAB menu option) 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.

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.

Uninstallation

To uninstall a MATLAB toolbox, right-click on the toolbox icon in the APPS toolbar and select the Uninstall option.

Some versions of MATLAB do not fully remove toolboxes if they have been launched in the current session. It is therefore recommended to only uninstall toolboxes in new MATLAB sessions. Alternatively, one can also locate the MATLAB Add-Ons/Apps directory in the userpath folder (typically found as USERHOME/Documents/MATLAB/Add-Ons/Apps) and manually delete folders corresponding to the toolbox one wishes to remove.