Welcome to FEB3, pronounced Phoebe, a C++ Finite Element and Isogeometric Analysis software for modelling three-dimensional multiphysics and multiscale problems in bioengineering. Phoebe is designed as a modular framework, permitting the user to plug in their own constitutive relations and boundary conditions with ease. It incorporates both forward and inverse finite deformation analysis methods, and implements both implicit and explicit Total Lagrangian solvers for elliptic and parabolic boundary-value problems.

Overview of FEB3

FEB3 (Phoebe) is capable to simulate static and dynamic solid mechanics, transport phenomena, multiphase materials, and (solid & fluid) mechanics at multiple spatio-temporal scales. Currently, FEB3 features the following:

• Nonlinear elasticity
  • Compressible solids and nearly-incompressible solids
  • Isotropic, transversely isotropic and orthotropic elastic materials
  • Continuum scale fibre-reinforced materials
  • Growth mechanics
  • Multiphase mechanics
  • Biphasic and poroelastic deformation and fluid flow
• Coupled micro-macro nonlinear mechanics
  • Microscale incompressible fibre networks
  • Microfluid flow in capillaries
• Reaction-convection-diffusion dynamics

Biomedical applications FEB3 currently supports include:

• Soft tissue biomechanics
• Tumour growth
• Angiogenesis and vascularisation
• Drug delivery
• Wound healing (physiological or pathological)
• Cell mechanics & biology

These applications feature coupled multiphysics solvers, permitting a physiological description of the chosen process with user-defined constitutive relations, material properties and boundary conditions.

FEB3 is an open-source software intended to be used for academic or research purposes. Its core is founded on various open-source libraries (i.e., PETSc, libMesh, GSL, MPICH, blitz++, BioDynaMo, Boost). Compilation and utilisation of FEB3 necessitates installation of the open-source libraries listed below, which are freely available online.

Currently, FEB3 supports Gmsh-formatted input meshes for Finite Element Analysis simulations, while for Isogeometric Analysis simulations a specialised combination of Gmsh and native input data files are required (for details please consult corresponding examples). Also, all outputs results are generated in VTK and Exodus II file formats - both can be processed using the open-source visualisation platform Paraview.

How do I get it?

If you'd like to test or/and use FEB3, please contact Dr Vasileios Vavourakis or Dr Peter A. Wijeratne with a brief description of who you are and what you're going to use it for, and we'll send you a copy. This helps us understand your needs while it could guide future development of this project.

• Repository owner: Vasileios Vavourakis
• Repository administrators: Vasileios Vavourakis and Peter A. Wijeratne

Code compilation & installation

Before compiling FEB3 (Phoebe), one needs to configure/compile/install a set of numerical libraries and modelling platforms that FEB3 depends upon. These include MPICH, GSL, blitz++, BioDynaMo, PETSc and libMesh, as explained below.

Assuming the FEB3 project code has been copied in a local directory (e.g., /home/johndoe/FEB3, after executing git clone ...), the user will need to create a copy the generic makefile provided (see /home/johndoe/FEB3/Makefile.generic) and name it Makefile. This makefile can be edited where necessary, and be used to customise the compilation of the source code. The Makefile is split in two separate sections: the first section is the only section that needs to be edited by the user - the information are self-explanatory, while the rest is advisable be left unmodified by regular users; however, developers are free to edit accordingly with cautiously.

Phoebe setup identifies two steps: installation of its dependencies (libraries and platforms) and then compilation of the project code.

Firstly, the user needs to ensure that a proper compiler for C, C++ and Fortran programming languages has been installed, while also the installation path to MPI library is provided. Then, the user needs to make sure this macro has been set: SETUP_LIBS_FIRST = true, confirm if a release or a debug mode of the project is preferred (set the macro into: IN_RELEASE_MODE = true or IN_RELEASE_MODE = false respectively), and set the macro COMPILE_BIODYNAMO = true or COMPILE_BIODYNAMO = false if FEB3 should include the BioDynaMo library or not. Subsequently, the user can execute the following rule all_libs (which can be found in the hidden file: /home/johndoe/FEB3/.Makefile.libs) to configure, compile and install automatically all libraries. Please note that current configuration assumes that all libraries will be installed locally (i.e., in the path /home/johndoe/FEB3/libs/installed) except for BioDynaMo, which will be installed in the home directory (i.e., /home/johndoe). It is also worth noting that installation of the FLANN library is not imperative for the compilation of the FEB3 code.

After successful compilation and installation of all libraries, then this flag needs to be reset back in the makefile into: SETUP_LIBS_FIRST = false. Then, to compile the FEB3 source code, the rule feb3 should be executed, while the rule clean will evidently clear all compilation and linker files. A list of the rules available and compilation nitty-gritty is provided in the hidden file: /home/johndoe/FEB3/.Makefile.feb3. After code compilation and binaries linking has been successfully completed, an executable is generated in the directory /home/johndoe/FEB3/bin/. To quickly test that FEB3 works, the user could execute in the terminal /home/johndoe/FEB3/bin/./feb3*.exe --help - this will print out of a help message ;)

In general, setup of FEB3 has been tested on Unix-based machines only (Ubuntu, CentOS and macOS).

Testing

We are doing our best to keep up testing and maintaining FEB3 (Phoebe) up-to-speed! :)

The user can find a series of examples to run simulations in biomechanics-related problems. They are located in the directory /home/johndoe/FEB3/examples/.

Referencing

To reference FEB3 (Phoebe), we would greatly appreciate citing any of the following published papers:

1. de Montigny et al. (2020) Methods, DOI:10.1016/j.ymeth.2020.01.006
2. Wijeratne and Vavourakis (2019) Royal Soc Interf Focus DOI:10.1098/rsfs.2018.0063
3. Vavourakis et al. (2018) PLOS Comp Bio, DOI:10.1371/journal.pcbi.1006880
4. Wijeratne et al. (2017) PLOS One, DOI:10.1371/journal.pone.0184511
5. Vavourakis et al. (2017) PLOS Comp Bio, DOI:10.1371/journal.pcbi.1005259
6. Vavourakis et al. (2016) PLOS One, DOI:10.1371/journal.pone.0159766
7. Wijeratne et al. (2016) Biomech Model Mechanobiol, DOI:10.1007/s10237-015-0745-2

Also, you can view some demo animations in the YouTube channel from here.

Credits

The logo of the Phoebe project was inspired by the illustration of the bird Black Phoebe (Sayornis nigricans) found from here.