3.1 Free Format Overview¶
This chapter describes the XML-based input format used by FEBio. Since this format follows standard XML conventions, the files can be viewed with any file viewer that supports XML files. Since the free format input file is a text file, it can be edited with any text editor.
An XML file is composed of a hierarchical list of elements. The first element is called the root element. Elements can have multiple child elements. All elements are enclosed by two tags: a tag defining the element and an end tag. A simple example of an XML file might look like this:
<root>
<child>
<subchild> ... </subchild>
</child>
</root>
The value of an element is enclosed between the name and the end tag.
<element> here is the value </element>
Note that the XML format is case-sensitive.
XML elements can also have attributes in name/value pairs. The attribute value must always be quoted using quotation marks (") or apostrophes (')1.
<element attr="value">...</element>
<element attr='value'>...</element>
If an XML element has no value, an abbreviated syntax can be used. The following two lines are identical.
<element [attribute list]></element>
or
<element [attribute list]/>
Comments can be added as follows.
<!-- This is a comment -->
The first line in the document – the XML declaration – defines the XML version and the character encoding used in the document. An example can be:
<?xml version="1.0" encoding="ISO-8859-1"?>
The free format organizes the FEBio input data into hierarchical XML elements. The root element is called febio_spec. This root element also defines the format version number (Note that FEBio and the input format specification follow different version numberings). This document describes version 4.0 of the FEBio specification2 (see Section Format Specification Versions below for more details on the different input specification formats). The root element will therefore be defined as follows:
<febio_spec version="4.0">
<!-- contents of file -->
</febio_spec>
The different sections introduced in this chapter are child elements of this root element. The following sections are currently defined:
Module defines the physics module for solving the model.
Globals Defines the global variables in the model
Control specifies control and solver parameters.
Material Specifies the materials used in the problem and the material parameters.
Mesh Defines the mesh of the problem, including nodal coordinates and element connectivity.
MeshDomains Assigns materials and other formulation attributes to element sets.
MeshData Defines element, facet, edge or nodal data that can be mapped to material parameters or certain boundary conditions and loads.
MeshAdaptor Defines mesh adaptors that modify the mesh.
Initial Defines initial conditions for dynamic problems, such as initial velocities, and for transient quasi-static problems.
Boundary Defines the boundary conditions that are applied on the geometry.
Loads Defines the loads applied to the model. This includes nodal loads, boundary loads and volume loads (or sources for heat transfer problems).
Contact This section defines all contact interfaces.
Constraints This section defines rigid and nonlinear constraints.
Rigid This sections defines rigid components, such as rigid constraints, rigid loads, and rigid connectors.
Discrete This section defines all the discrete elements (i.e. springs).
LoadData Defines the load controllers, which can control model parameters as a function of time.
Step Defines different analysis steps, where in each analysis the boundary, loads, contact and initial conditions can be redefined.
Output Defines additional data that needs to be stored to file.
Although there is some flexibility in the order in which these sections can be listed, it is recommended to list them in the same order as given above. Not all sections are required. Empty sections can be omitted. A minimal file must contain at least the Module, Control, Material, Mesh, and MeshDomains sections. The rest of this chapter describes each of these sections in more detail.
Format Specification Versions¶
This document describes version 4.0 of the FEBio input specification. This format differs in several aspects from the previous versions of the input specification. This section describes the major changes between the different versions.
-
Version 4.0: The latest and recommended version of the FEBio input specification described in this document. The main motivation for this format was to improve consistency between the feb file structure and the way the FEBio model is constructed in FEBio Studio. This format is very similar to version 3.0 and only differs in a few sections: Some solver parameters have moved. The Rigid section was restructured. Node and element sets can be specified more concisely.
-
Version 3.0: The major focus of this revision was adding support for FEBio 3.0's features for modeling heterogeneous parameters. Heterogeneous parameters can be created via mathematical expressions or via the MeshData section. It also introduces a more consistent way for referencing model parameters. The Geometry section was replaced with the Mesh and MeshDomains sections in order to further separate the definition of the mesh and its physical attributes (e.g. material assignments). This format is still supported but considered obsolete.
-
Version 2.5: This format differs from its predecessor in some important aspects: all nodesets, surfaces, etc., that are used by boundary conditions, loads, contact, etc., must be defined in the Geometry section. Boundary conditions, loads, contact, etc., are now defined by referencing the sets in the Geometry section. This format also adds the MeshData section and re-formats the Discrete section. Rigid node sets and prescribed rigid degrees of freedom are moved to the Boundary section. This format is still supported but considered obsolete.
-
Version 2.0: This is the first major revision of the input file format and redefines many of the file sections: The Elements section uses a different organization. Elements are now grouped by material and element type. Multiple Elements sections can now be defined to create multiple parts. Surfaces can now be defined in the Geometry section and referenced by boundary conditions and contact definitions. A new Contact section contains all the contact definitions. A new Discrete section was defined that contains all the materials and definitions of the discrete elements (e.g. springs). The Boundary section is also redesigned. This format is still supported but considered obsolete.
-
Version 1.3: This was an experimental version that redefined the Geometry section, but was later abandoned in favor of version 2.0. This version is no longer supported.
-
Version 1.2: A Loads section was added and all surface and body loads are now defined in this section instead of the Boundary section. This version is mostly supported but considered obsolete.
-
Version 1.1: Rigid body constraints are no longer defined in the rigid material definition but instead placed in a new Constraints section. This version is no longer supported.
-
Version 1.0: The original input format specification. This version is no longer supported.
As of FEBio 4.0, only versions 1.2, 2.0, 2.5, and 3.0 are supported. Versions 1.2 and 2.0 are considered obsolete and it is highly recommended to convert older files to the newest specification for use with newer versions of FEBio. This can be done for instance using FEBioStudio.
Notes on backward compatibility¶
Some features that were available in versions prior to 4.0 are no longer supported or require a different syntax.
-
The Parameters section is no longer supported. This section allowed users to define file parameters that could be used as parameter values. This section was removed since it was difficult to support in FEBio Studio and a better mechanism was implemented for defining model-level parameters. (See the User Variables section.)
-
Some fiber materials defined the theta and phi parameters for setting the fiber orientation. These parameters are no longer supported. Instead, the fiber direction should be specified via the fiber property, or if the fiber property is not available, the _mat_axis _property.
<fiber type="angles">
<theta>90</theta>
<phi>0</phi>
</fiber>
Multiple Input Files¶
FEBio supports distributing the model definition across multiple input files. This can greatly facilitate defining large, complex models and allows the re-use of model input files without the need to create the entire model input file from scratch. When using multiple input files to define a model, you must create a control input file that may reference other input files. This control file will be used to run the model in FEBio. There are two ways of including a file into the control file: The Include section, and the from attribute_._
Note that all input files must start with the febio_spec tag and use the same format specification.
Include Keyword¶
The Include keyword3 can be used to include the contents of another FEBio input file. The filename is entered as the value of the tag.
<Include>example.feb</Include>
The included file must be a valid FEBio file in that it must begin with the febio_spec tag and contain sections defined in this document. However, the included file does not need to define a complete model definition. For instance, it can contain only the Mesh section.
Note that the contents of the entire file will be included. This is different from the from attribute discussed below, which can be used to include only certain sections from files.
The 'from' Attribute¶
The from attribute can be used to include sections from other files. All the main sections defined in Section Free Format Overview support the from attribute which can be used to load the section from another input file. For example, to load the Material section from the file mat.feb, defining the Material section in the control input file as follows.
<Material from="mat.feb"/>
FEBio will now read the Material section from this child file. The child file must be a valid FEBio input file, meaning it must begin with the febio_spec root section, but does not have to be complete. For example, the file mat.feb only needs to define the Material section. However, the child file may contain other sections. In that case, only the section referenced in the control file will be read from the child file. For example, if the file in.feb contains both the Material and the Mesh section, the control file can read both these sections as follows.
<Material from="in.feb"/>
<Mesh from="in.feb"/>
To give a more concrete example, assume that the Material, Mesh, and Boundary sections are defined in the files mat.feb, geom.feb, and bc.feb respectively. The control input file could then look like the following.
<febio_spec version="4.0">
<Module type="solid"/>
<Control>
<time_steps>10</time_steps>
<step_size>0.1</step_size>
</Control>
<Material from="mat.feb"/>
<Mesh from="geom.feb"/>
<Boundary from="bc.feb"/>
</febio_spec>
Notice that the Control section is still defined in the control file. The control file can contain a combination of explicit section definitions and referenced sections using the from attribute. As mentioned above, the control file is used to run the model in FEBio. So, if the control file is called model.feb then the model is run as follows.
>febio –i model.feb
When FEBio parses the control file it will automatically parse the referenced child files it encounters in the control input file.