Usage¶

Then, import the package in your Python code:

import febio

Reading a FEBio input file (.feb)¶

To read a FEBio input file, use the febio.Feb function. This function returns a Feb object that can be used to access the contents of the FEBio input file. It automatically parses the input file and stores the contents in a structured format using xml.etree.ElementTree. Additionally, it automatically identifies the FEBio version used in the input file.

from febio_python import Feb
feb = Feb('path/to/file.feb')

The Feb object has a number of attributes and methods that can be used to manipulate the contents of the FEBio input file. For example, to access the root element of the input file, use the root attribute:

root = feb.root

The root attribute is an xml.etree.ElementTree.Element object that can be used to access the contents of the input file. Here you can direcly modify any part of the tree using the ElementTree API. The Feb object also has a number of convenience attributes that can be used to access specific parts of the input file, these are attributes are the lead tags for the Feb file. For example, to access the Material section of the input file, use the materials attribute:

materials = feb.materials

The materials attribute is a list of xml.etree.ElementTree.Element objects that represent the Material section of the input file. The Feb object also has a number of convenience methods that can be used to manipulate the contents of the input file. For example we can add Nodes to the input file using the add_node method:

from febio_python.core import Nodes

new_nodes = Nodes(name="NewNodes", coordinates=[[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0]])
feb.add_node([new_nodes])

The add_node method takes a list of Nodes objects and adds them to the input file. For full documentation on the Feb object, see the API documentation.

Writing a FEBio input file (.feb)¶

To write a FEBio input file, use the write method of the Feb object. It takes a single argument, the path to the output file:

feb.write('path/to/output.feb')

The write method writes the contents of the Feb object to the specified output file in FEBio format.

Running a FEBio simulation¶

To run a FEBio simulation, use the run function. You can run a simulation or multiple simulations depending on the input argument. If the input is a filepath, it will run the simulation using the specified input file. If the input is a directory, it will run all the simulations in the directory.

from febio_python import run

run('path/to/file.feb')

Reading the results of a FEBio simulation (.xplt)¶

To read the results of a FEBio simulation, use the febio.Xplt function. This function returns an Xplt object that can be used to access the contents of the FEBio results file.

from febio_python import Xplt
xplt = Xplt('path/to/file.xplt')

The Xplt object has a number of attributes that can be used to access the contents of the FEBio results file. You can retrieve the nodes, elements and surfaces from the simulation. For example, to access the nodes of the simulation, use the nodes attribute:

nodes = xplt.nodes

Or you can access the states (results) of the simulation. Each state is either stored as node, element or surface data. For example, to access the node states of the simulation, use the states attribute:

states = xplt.states
node_states = states.node

This will return a list of StateData for the nodes. Each StateData object has a name and data attribute that contains the information of the state. For full documentation on the Xplt object, see the API documentation.

The FEBio Container¶

For convenience, we have a Container class that can be used to store both Feb and Xplt objects. Allowing to access data from both the input and output files in a single object. For instance, you may want to access the input conditions (boundary and loads) while accessing the results of the simulation.

from febio_python import FEBioContainer

container = FEBioContainer(feb='path/to/file.feb', xplt='path/to/file.xplt') # or feb=feb, xplt=xplt if you already have the objects.

Converting to pyvista¶

We have some utility functions to convert the Febio-Python objects to pyvista objects. This is useful to visualize the results of the simulation or to provide a more interactive way to access the data, such as manipulating the mesh of the input file or plotting the results.

from febio_python.utils.pyvista_utils import febio_to_pyvista

listed_grid = febio_to_pyvista(container)

This will return a pyvista.UnstructuredGrid object for each state in the simulation. For consistency, it will always return a list of pyvista.UnstructuredGrid objects. Thus, if only one state is present, it will return a list with a single pyvista.UnstructuredGrid object. Additionally, if only the input (Feb) is provide, it will also return a list with a single pyvista.UnstructuredGrid object. To plot the mesh you can simply use:

listed_grid[0].plot()

For full documentation on the FEBioContainer object, see the API documentation.

Converting to vtk¶

For convenience, we have an utility function to convert the Febio-Python objects to vtk objects. This is useful to visualize the results of the simulation and post-process the data using the vtk software. This function will use febio_to_pyvista and save each pyvista.UnstructuredGrid object to a .vtk file.

from febio_python.utils.vtk_utils import febio_to_vtk

febio_to_vtk(container)

This will save the .vtk files in the same directory as the input file. For full documentation on the febio_to_vtk function, see the API documentation.