FEBio

Exercise | Error messages | Details

1. Getting the software

As of version 2.9 (2019 Apr 25) the source licence became truly free/libre and open source, although the downloadable binaries have a more restrictive licence. You will need to register in order to download.

The first official release of the new FEBio Studio took place on 2020 Aug 27 for Linux and Mac OSX and on 2020 Sep 1 for MS Windows. It includes preprocessing and postprocessing as well as the FEBio solver itself.

The downloads include good manuals in the doc directory. In addition, the FEBio Knowledgebase contains download and installation instructions (‘Getting Started’); tutorials that serve as useful introductions to the programme; the manuals; and more. In addition, the support forums are quite responsive.

To install FEBio Studio under MS Windows, download and save the .zip file; double-click on it to open it, and then double-click on the .exe file that it contains. Follow the steps to complete the installation.
If FEBio complains about missing DLL’s, see this forum link; at vs/older-downloads, under Other Tools, Frameworks, and Redistributables, download Microsoft Visual C++ Redistributable for Visual Studio 2017.

To install FEBio Studio under Linux, download the .run file; open a terminal window; use cd to get into the directory where the .run file was saved; use chmod +x to make the .run file executable; and then run it by doing ./FEBioStudio_…_installer.run where ‘_…_’ depends on the version that you’re installing.
If you're using Linux as a guest under VirtualBox or similar software, I recommend that you install FEBio Studio under your host operating system rather than under Linux.

Old versions of the separate FEBio, PreView and PostView software can be downloaded from the FEBio archive page. To install the software, open the .zip file for each package, extract and save the executable installer, and run it.

To install an old FEBio under Linux (because you have trouble with the latest version), download febio_lnx64_2.9.1.zip, for example, and save it in Downloads/FEBio/ under your home directory. Double-click on the .zip file and extract its contents (e.g., FEBio-2.9.1-linux-x64-installer.run). In a command window, do
cd ~/Downloads/FEBio
chmod u+x FEBio-2.9.1-linux-x64-installer.run
./FEBio-2.9.1-linux-x64-installer.run
Do the installation. Assuming that you accepted the default installation directory, and that your .feb file is test.feb in directory ~/whatever/, then to run your model give the commands
cd ~/whatever
~/FEBio-2.9.1/bin/febio2 test.feb

The parts of the instructions here that were written for the old PreView and PostView are in grey. Some or all of them may still be relevant.

If your computer has multiple processors (cores), an environment variable can be set to specify how many to use. For example, using the bash shell under Linux, do export OMP_NUM_THREADS=n. See the manual for details. An alternative wording in a forum post (2018 Apr 25) says that the linear solver automatically uses the maximum number of threads available; the OMP_NUM_THREADS environment variable applies only to matrix assembly, and requesting more threads may slow down the matrix assembly for small models.

1.1 Problems

2. Creating and running a simple model

Download and install FEBio Studio. At the FEBio Knowledgebase, under Tutorials ► Intro to FEBio Studio, do the three tutorials:

• Creating Your First Model in FEBio Studio
• Running Your First Simulation in FEBio Studio
• Performing Your First Analysis in FEBio Studio

Before starting the tutorials, you should read at least Chapters 1 and 2 of the FEBio Studio User’s Manual. The notes below may also be useful.

2.1 Preprocessing (creating a model)

• Step 1 of the tutorial says that a Project Manager window will appear when you run FEBio Studio, but that’s for an older version. Refer to the latest FEBio Studio manual for instructions on creating a new model. Click on New Model … or do File ► New Model …. In the window that pops up, select Structural Mechanics, specify a name for your model, and click on OK. Continue with Step 2 of the tutorial.
• In Step 2, you may need to scroll down to see the Parameters fields for setting the size of the box for the model, and to see the Create button.
  The toolbar with the mesh icon in it is at the bottom, not the top.
  I don’t see the Add Material icon that is referred to in the tutorial.
• After Step 6, you should save the model by doing File ► Save As ….
  Ignore the figure entitled Add Contact Interface.
• There are five ‘contexts’ tabs. Hovering over them doesn’t display a tooltip, and their names are given somewhat inconsistently in the manual and in the Edit ► Switch context menu. From left to right in the image on the right, the contexts are Model Viewer (Model), Create, Edit (Modify), Mesh, and Tools.
• 3-D rotation is awkward if you’re used to being able to do rotations about the z axis.
• To toggle between orthographic and perspective views, do View ► Orthographic Projection (or right-click on the model and use the context menu, or type P).
• If you have defined a mesh and don’t see the individual elements, try View ► Show Mesh Lines.
• When creating the model, the adjustment of the third point is rather unintuitive: the height of the box increases faster than the mouse is moved upward, and also increases when the mouse is moved below its starting position.
• If changes (like setting a material) don’t seem to be happening properly, check whether you’ve inadvertently created two superimposed objects.

2.2 Processing (running a simulation)

In the section heading ‘Running an FEBio Simulation in PreView’, ‘PreView’ means FEBio Studio. The instructions in this section are out of date. In step 1, when it says ‘Open the PreView file …’, it is referring to the model created in the first tutorial. You must have already saved it as an FEBio Studio model (.fsm) file. do FEBio ► Run FEBio … or left-click on the Run FEBio icon. In the dialogue window that opens up, for the sake of this tutorial you can probably just accept all of the default settings. Click on Run.

Watch the output go by and wait for FEBio to finish. Hopefully at the end there will be a message saying NORMAL TERMINATION. A file called filename.xplt should have been created. You will be asked if you wish to load the results – click on Yes.

The following notes in grey in this section are probably not useful if you’re using FEBio Studio.

1. Follow the instructions in Chapter 2 of the FEBio User’s Manual for setting up FEBio.
   • Linux
     With an alias. The manual describes how to create an alias in order to be able to run FEBio from whatever directory your model file is in. Debian GNU/Linux uses the bash shell by default so the alias command includes an equal sign:
     alias febio='/path/to/febio/executable/'
     For at least some versions of FEBio, the alias isn’t necessary because the installation procedure under Linux puts the location of the executable file into your PATH environment variable (the list of locations searched when you give a command). However, this seems to only be done the first time you installed FEBio. This means that, if you're not careful, you might end up running the first-installed version even after you install another version. It's important to confirm what version you're actually running by checking the version number displayed in FEBio's output.

     With a symbolic link. An alternative to either relying on the PATH or creating an alias is to create a ‘symbolic link’. The following procedure for doing so uses the command line in a terminal window:

     • In your home directory, use the mkdir command to make a bin subdirectory:
       mkdir bin
       In some Linux distributions (including Debian with the gdm3 display manager) this bin directory (if it exists) will automatically appear first in your PATH and will therefore be the first place the operating system looks when you give a command.
     • Use the cd command to change into that subdirectory:
       cd bin
     • Use the ln -s command to create a symbolic link febio that points to where the FEBio executable is. The details depend on the version of FEBio. An example is the following:
       ln -s ~/Downloads/FEBio/febio_lnx64_centos_2.5.2.8980/febio-2.5.2/bin/febio2.lnx64 febio
     Now, when you want to run FEBio, cd to the directory where your .feb file is and give the command
     febio filename.feb (replacing filename by the actual file name.
     Do not run FEBio by double-clicking on its icon. FEBio goes into a loop that writes the febio> prompt into ~/.xsession-errors and fills up the disk (ref).
   • Mac OS Mac OS is closely related to GNU/Linux so the information above applies to Mac OS also.
   • MS Windows
     Follow the directions in the manual for adding the location of the FEBio executable file to the PATH environment variable. (Some versions of the installer adjust the PATH for you.)

     For Windows 8, the place for setting the environment variable is found by doing Start ► All Apps ► Control panel ► System ► Advanced System Settings ► Advanced ► Environment variables.
     For Windows 10, Settings ► System ► About ► System info ► Advanced system settings ► Advanced ► Environment Variables.

     Alternative methods of running FEBio have disadvantages, such as involving more typing or not immediately displaying error messages. Don’t try putting the .feb file in the directory where the FEBio executable file has been installed – by default FEBio won't be able to write its results into that directory, and it’s a bad idea anyways to mix software and data.

     If you have trouble accessing the manual using the Start Menu entry, check that it specifies the correct file name; one version of the installer for version 2.3 specified 2.0 in the name of the manual.

     Note that for FEBio version 2:

     • The entry to be added to the PATH is something like C:\Program Files\febio-2.3.1\bin, not C:/Program Files/FEBio/ as shown in the manual.
     • The command to run FEBio is something like febio2 or febio2x64, not febio as shown in the manual.
     Check where FEBio ended up being installed and with what name.

     You need to invoke a new Command Prompt in MS Windows for the revised PATH to take effect.

2. Get access to a command line. For example, in MS Windows do Start ► All Programs ► Accessories ► Command Prompt.
3. At the command line, use the cd command to get into the directory where you stored the model that you created in PreView.
4. Give the command febio2 -i filename.feb
   or ~/bin/febio2 -i filename.feb
   if you’re using a symbolic link in your bin directory.

2.3 Postprocessing (analyzing simulation output)

For ‘Opening the Simulation Output’: After clicking on Yes to say you wish to load the results, you will immediately see the post-processing interface, effectively skipping this section.

For ‘Viewing the Model’s Animation’: The icon for the time dialogue box is now a clock face, not a check mark; it is just to the right of the animation toolbar.

For ‘Visualizing Data with the Color Map’: The icon with concentric circles may not be greyed out to start with. Look for the name of an .xplt file in the Post section at the left of the interface, rather than job1 in a Model tab.

1. Open the file filename.xplt.
2. From the dropdown list in the main toolbar, select which quantity you want to display; for example, displacement ► Total displacement
3. Click on the Play button in the animation toolbar. The animation toolbar, at the far right, may not be immediately visible unless your PostView window is very wide; it can be dragged to a different position.
4. If you don’t see any displacements, you can try increasing the Scale factor for the Displacement Map, or, if appropriate, adjust the material properties and loads in your model.
5. Use the Toggle colormap button to enable or disable the use of a colour map for the quantity being displayed. Several different colour maps are available. The Fire colour map provides strong contrast, a good use of different hues, and an almost monotonic increase of brightness between black and white.

3. Interpreting FEBio error messages

• If you see
  This model does not define any output variables.
Do you wish to continue?
  just click on Yes to continue. It shouldn’t cause further problems. A default set of result variables will be output.
• If you get Negative jacobian error messages like the following, saying that the model initialization failed, it may mean that some or all of your elements are numbered backward. If your model was generated using Fie, it may mean that some lines were traced clockwise instead of counterclockwise.

  **************************** E R R O R ****************************
  Negative jacobian detected at integration point 1 of element 1
  Jacobian = -320903
  Did you use the right node numbering?
  Nodes:619,685,1141,1091
  *******************************************************************
  
  FATAL ERROR: Model initialization failed
  

• If FEBio gets past the initialization step and then produces Negative jacobian messages like the following, it means that FEBio successfully ran your simulation for a while and then failed.

   *************************************************************************
   *                                ERROR                                  *
   *                                                                       *
   * Negative jacobian was detected at element 1231 at gauss point 1       *
   * jacobian = -0.346871                                                  *
   *                                                                       *
   *************************************************************************
  
  ------- failed to converge at time : 0.911313
  
  Max. nr of retries reached.
  
  N O N L I N E A R   I T E R A T I O N   I N F O R M A T I O N
  
  	Number of time steps completed .................... : 20
  

   E R R O R   T E R M I N A T I O N
  

  It should normally run all the way to t=1. In this case it completed 20 time steps and then failed at t≈0.9. This may mean that your deformations have become so large that some elements have become too distorted to be able to continue. You could try reducing the pressure or force loads.
• If you get Negative jacobian messages like those above but the number of time steps completed is equal to zero, it may mean that one of the following has occurred:
  • some of your elements are too badly deformed for FEBio to handle at all
  • your material properties are too soft, or your applied load is too large, so that the deformations become unmanageably large even for the first load increment
  • no boundary conditions were specified
• If you get an error message like the following, indicating that the maximum number of reformations was reached, with the number of time steps completed equal to zero, it may mean that no loads were specified.

   *************************************************************************
   *                               WARNING                                 *
   *                                                                       *
   * Max nr of iterations reached.                                         *
   * Stiffness matrix will now be reformed.                                *
   *************************************************************************
  Reforming stiffness matrix: reformation #15
  
   *************************************************************************
   *                                ERROR                                  *
   *                                                                       *
   * Max nr of reformations reached.                                       *
   *************************************************************************
  
  ------- failed to converge at time : 0.0015625
  
  Max. nr of retries reached.
  
  N O N L I N E A R   I T E R A T I O N   I N F O R M A T I O N
  
  	Number of time steps completed .................... : 0
  

   E R R O R   T E R M I N A T I O N
  

• The error messages may sometimes be misleading. For example, the message unrecognized tag "LoadData" has been known to occur because no pressure data were found.

4. FEBio details

This section summarizes some information from the FEBio documentation and source code.

4.1 Materials

FEBio's ‘elastic solid’ materials are all ‘hyperelastic’ (defined in terms of strain-energy functions) and are divided into two groups:

• ‘uncoupled’: the deviatoric and volumetric behaviours are uncoupled (i.e., treated separately). A ‘three-field’ element formulation is used that is well suited to nearly incompressible materials. In Section 4.2.1 of the User Manual, it is stated that ‘fully incompressible behavior can be obtained using an augmented Lagrangian method’, controlled by two extra parameters (laugon to turn the method on and atol to specify a tolerance). In Section 7.8.2, it is stated that incompressibility ‘is usually enforced using a penalty formulation (although an augmented Lagrangian method is also available)’.
• ‘unconstrained’: the deviatoric and volumetric behaviours are not (necessarily) treated separately. The term seems to indicate that the volume is not constrained, although the same may also be true of the uncoupled materials. These materials use (Section 4.1.3 says ‘can only be used with’) the standard displacement-based finite-element formulation rather than the three-field element formulation, and ‘they should not be used for nearly-incompressible material behavior due to the potential for element locking’. Some of the material names are prefixed by coupled when there is also an uncoupled version.

4.2 Discrete dampers

Defining a discrete damper in FEBio is painful. The dampers are known as ‘rigid dampers’, which is a perverse way of saying that they must be connected at both ends to rigid bodies. The following is a first attempt to explain it to myself.

Suppose you want to connect a damper between node number 101 on your model and node number 102 somewhere in space away from the model. For each of the two nodes, define a ‘rigid material’ that in turn defines a rigid body:

    <Material>
      <material id="14" name="node 101" type="rigid body">
	<density>1</density>
	<center_of_mass>x101, y101, z101</center_of_mass>
      </material>
      <material id="15" name="node 102" type="rigid body">
	<density>1</density>
	<center_of_mass>x102, y102, z102</center_of_mass>
      </material>
    </Material>
  

The ‘rigid body’ located on your model must be connected to the model by defining a contact:

    <Contact>
      <contact type="rigid" name="damperContact">
	<node id="101" rb="14"></node>
      </contact>
    </Contact>
  

The rigid body at the other end of the damper is fixed in space using a constraint, with the rigid body referred to by the name of its material:

    <Constraints>
      <rigid_body mat="15">
	<fixed bc="x"/>
	<fixed bc="y"/>
	<fixed bc="z"/>
	<fixed bc="Rx"/>
	<fixed bc="Ry"/>
	<fixed bc="Rz"/>
      </rigid_body>
    </Constraints>
  

Finally, the damper itself is created between the two rigid bodies with the damping coefficient c (in units of force per velocity):

    <Constraints>
      <constraint type="rigid damper" name="RigidDamper01">
	<body_a>14</body_a>
	<body_b>15</body_b>
	<c>c</c>
	<insertion_a>x101, y101, z101</insertion_a>
	<insertion_b>x102, y102, z102</insertion_b>
      </constraint>
    </Constraints>
  

It is necessary to set the flag <check_zero_diagonal> to false (ref).

4.3 Time-step controller

See Free Format Input ► Control Section ► Time Stepper Parameters in the User’s Manual.

In version 3.3.2 (2021 Apr 4) a new-time control parameter was added, dtforce, which forces the time stepper to use the maximum time step.

Pseudocode based on FETimeStepController.cpp:

• adjusting the time step after convergence:

        //! If the previous time step was able to converge in less than
        //! opt_iter iterations the step size is increased, else it
        //! is decreased.
        if(niter > 0) {
          scale = sqrt(opt_iter/niter)
          if(scale >= 1) {     //if niter <= opt_iter
            dtn = dtn + (dtmax - dtn)*MIN(.20, scale - 1);
            dtn = MIN(dtn, 5.0*m_dtp);
            dtn = MIN(dtn, dtmax);
          } else {
            dtn = dtn - (dtn - m_dtmin)*(1 - scale);
            dtn = MAX(dtn, m_dtmin);
            dtn = MIN(dtn, dtmax);
          }
        }
    

  opt_iter is initialized to 11, not 10.
• adjusting the time step after failure to converge:

        if (nretries == 0) ddt = dt / (max_retries + 1) //first time
        if (aggressiveness == 0) { dtn = dt - ddt }     //default method
        else { dtn = dt*0.5 }
      

4.4 Time-domain integration

In FESolidSolver2.cpp the following default Newmark-integration parameter values are defined, corresponding to the trapezoidal (or midpoint) rule:

ρ∞ = −2
α = αf = 1.0
αm = 1.0
β = 0.25
γ = 0.5

Later there is the following logic, which does not seem to be documented:

if (ρ∞ = −1)         //Euler integration
  α = αf = αm = 1.0
  β = 0.25(1 + αm − αf)2
  γ = 0.5 + αm − αf
else if (0 ≤ ρ∞ ≤ 1) //Generalized-α integration
  α = αf = 1/(1 + ρ∞)
  αm = (2−ρ∞)/(1+ρ∞)
  β = 0.25(1 + αm − αf)2
  γ = 0.5 + αm − αf
else                //use the user-defined α, β & γ 
  αf = αm = αuser
  β = βuser
  γ = γuser

For ρ_∞ = 0 (heaviest numerical damping):   α = α_f = 1,   α_m = 2,   β = 1,   γ = 1.5.

For ρ_∞ = 1 (lightest numerical damping):   α = α_f = 0.5,   α_m = 0.5,   β = 0.25,   γ = 0.5.