## Describe Specifications/FebioFeatures here.
#acl +All:read Default
#format wiki
#language en
This page prioritizes and provides specifications for feature requests associated with FEBio development.
<<TableOfContents>>
= Target Outcome =
Implementation of analysis and pre- & post-processing related features in FEBio to accommodate simulations conducted using Open Knee(s)
= Priority List for Implementation =
1. In situ strain
1. Element, node, and surface set definitions
1. Connector elements for joint coordinate system
1. Penetration based contact
1. Spring elements with wrapping
1. Shell elements for cartilage
= Features Related to Constitutive Modeling =
== In Situ Strain ==
=== Description ===
The zero force reference lengths (or "slack length") of the ligamentous knee structures have been shown to be important contributors to overall joint mechanics. As they are difficult to measure, ligament slack lengths are a commonly targeted parameter during optimization of specimen-specific joint level kinetic-kinematic response. Regardless of the level of refinement in the modeling approach, whether continuum or spring based, a parameter based representation facilitates these iterative studies.
Ideally, this behavior could be defined either along the ligament line of action or locally within a given element. While the local mesh coordinate frames could be used to approximate a ligament's line of action (if hexahedral elements are used), it would also be convenient to incorporate ligament wrapping, without needing to remesh to reflect this behavior (if possible).
=== Test Problem ===
The test problem will be developed using the following:
* Geometry/Mesh: a 1 by 1 by 10 mm mesh with fiber direction defined along the 10 mm length.
* Boundary Conditions: a ramp displacement profile (+/- 2.5 mm load-unload) applied to one end of the mesh along the fiber direction (see figure below). The other end is fixed.
* Material Model: a fiber based model, e.g. transversely isotropic Mooney-Rivlin.
* Sensitivity: fiber direction ''in situ'' strain values ranging -0.2 to +0.2, in 0.1 increments.
* Output: force-displacement response of the loaded end of the mesh.
* For application in Open Knee(s) simulations, implementation in both implicit static and implicit dynamic analyses.
----
[[https://simtk.org/svn/openknee/doc/img/FEBio_insitu_test.png|{{https://simtk.org/svn/openknee/doc/img/FEBio_insitu_test.png|Test problem for in situ strain|width=600}}]]
=== Estimated Completion ===
April, 2014
=== Progress ===
See [[Febio/InSituStrain]].
= Features Related to Pre-/Post-Processing =
== Set Definitions for Elements, Nodes, and Surfaces ==
=== Description ===
The ability to define node, element, or surface sets could add convenience to both the pre- as well as post-processing of FEBio analyses. Often, models are made up of multiple components while the output(s) of interest may be limited to a specific component, or an even smaller region of interest. In terms of pre-processing, element sets could be used to assign material properties or request specific types of output for a given region. For post-processing, instead of searching across all elements (or nodes) in a model, and cross-referencing for specific element numbers, one could simply extract the region of interest by name.
=== Test Problem ===
To illustrate the use of element, node, and face sets a test problem will be constructed to solve for contact between two blocks:
* Geometry/Mesh: bottom block (prismatic with any desirable width, height, and thickness); top block (prismatic with any desirable width, height, and thickness)
* Material model: bottom block (any desirable constitutive model and parameter values); top block (any desirable constitutive model and parameter values)
* Contact: frictionless, between top surface of bottom block and the bottom surface of top block
* Boundary conditions: quarter symmetry, bottom block constrained at the bottom, a ramp displacement prescribed to the top of the top block.
* Sets:
* Element sets
* es_bb: all elements in bottom block
* es_tb: all elements in top block
* Node sets
* ns_bx: all nodes at x = 0 plane of bottom block
* ns_by: all nodes at y = 0 plane of bottom block
* ns_bz: all nodes at z = 0 plane of bottom block
* ns_tx: all nodes at x = 0 plane of top block
* ns_ty: all nodes at y = 0 plane of top block
* ns_tz: all nodes at top plane of top block
* Note that node sets have overlapping nodes laying on x, y, and z axes.
* Face sets
* fs_b: all faces at top surface of bottom block
* fs_t: all faces at bottom surface of top block
* Use of sets for model input
----
/!\ '''Edit conflict - other version:'''
----
* The goal is to define model parameters in FEBio input file by referring to set names.
* Assignment of material properties to
* es_bb
* es_tb
* Assignment of boundary conditions to
* ns_bx
* ns_by
* ns_bz
* ns_tx
* ns_ty
* ns_tz
* Assignment of contact interaction between
* fs_b
* fs_t
* Use of sets for model output
* The goal is to extract simulation results from FEBio xplt file by referring to set names.
* Extraction of volume at deformed states for
* es_bb
* es_tb
* Extraction of reaction forces for
* ns_bx
* ns_by
* ns_bz
* ns_tx
* ns_ty
* ns_tz
* Extraction of contact pressures for
* fs_b
* fs_t
----
[[https://simtk.org/svn/openknee/doc/img/ElSet_Nset_Surface_Test.png|{{https://simtk.org/svn/openknee/doc/img/ElSet_Nset_Surface_Test.png|Test problem for set definitions|width=800}}]]
=== Estimated Completion ===
September, 2014
=== Progress ===
See [[Febio/SetDefinitions]].
= Features Related to Rigid Body Kinematics Representations =
== Local Coordinate Systems ==
== Connector Elements for Joint Coordinate Systems ==
=== Description ===
Joint level simulations, especially in the knee, often rely on application and/or description of kinetic-kinematic response in commonly accepted joint coordinate systems (e.g. Grood and Suntay, JBME, 1983). This requires adoption of moving local coordinate systems that are assigned to a given body, e.g. the femur and tibia, to track overall rigid body motions as well as a means to "connect" two coordinate frames. In the case of Abaqus, we often use what's called "connector" elements to setup such frames. Their convenience is evident during model setup, prescription of joint level boundary conditions, as well as post-processing of the model results, where the connector outputs can be directly translated into clinically accepted descriptions of motion and/or loading.
In a Grood and Suntay convention, the following vector can be used to describe the position of an embedded tibial coordinate frame with respect to the femoral frame:
H = S1*e1 + S2*e2 + S3*e3
where e1, e2 and e3 are unit vectors along each of corresponding Si (i=1-3) magnitudes. e1 can be though of as the femoral flexion (FE) axis, while e3 is the internal-external (IE) rotation axis in the tibia and e2 is the common perpendicular between the two, i.e. the "floating axis."
In practice, all of the above can be combined to view the "connections" between two rigid bodies as a series of cylindrical joints:
[[https://simtk.org/svn/openknee/doc/img/coordinate_systems.png|{{https://simtk.org/svn/openknee/doc/img/coordinate_systems.png|Open Knee(s) local and joint coordinate systems|width=400}}]]
If implemented in this way, the rotations, displacements and reactions about each of the cylindrical axes can be used to describe or apply the desired joint kinetics. For robustness, the embedded clinical axes (IE for the tibia or "T" frame above and FE for the femur or "F" frame) should have the capability to be defined within body specific local coordinate frames, which may or may not be the same as the global (model) coordinate frame. Essentially, this approach results in follower loads and/or kinematics that are a function of the relative motion between the two bodies.
For reference, the yellow lines in the following represent the cylindrical connectors implemented in a joint level analysis (frames were setup to describe both tibiofemoral and patellofemoral articulations). Displacements, rotations, and reactions (load and moment) for each joint can be specified or extracted in this setup. A "cylindrical" connector elements, which constrains motion between two nodes to a displacement and rotation about the primary axis (the yellow lines), were utilized.
[[https://simtk.org/svn/openknee/doc/img/JCS_FEA.png|{{https://simtk.org/svn/openknee/doc/img/JCS_FEA.png|Joint coordinate systems|width=700}}]]
=== Test Problem ===
To accomplish this feature request, we anticipate setting up a test problem with a known input-output relationship. This test problem could act as a surrogate for joint level simulations and could be as simple as a set of linear springs between two coordinate frames.
=== Estimated Completion ===
Late 2014
=== Progress ===
----
See [[Febio/RigidBodyMotions]].
= Features Related to Surrogate Modeling =
== Penetration Based Contact ==
== Spring Elements with Wrapping ==
== Shell Elements for Contact Problems ==
= Features Related to Python Scripting =
Open Knee(s) will require a scripting interface to streamline modeling and simulation workflows and for cloud computing. At this moment, Python is used to develop in-house code for building new models, changing template models, and post-processing results. [[https://simtk.org/home/pyfebio|PyFEbio]] and planned scripting development by FEBio team will likely be helpful. In regard to modeling & simulation on the cloud using FEBio, a prototype is planned, see [[Specifications/CloudComputingPrototype]].
= Multiple File Input =
As of FEBio version 2.0, the definition of a FE model can be split across multiple input files. Each file can define one or multiple sections of the model definition. A master file combines all the different sections which are defined in separate files. The advantage of this approach over a single input file, is that it is a lot easier to edit small files, containing only a single section, compared to parsing and editing a large file. It also easier to customize models without having to create the entire model definition. For instance, to study the effect of different constitutive models, separate files containing a different Material section can be created. By choosing the appropriate file in the master file, a new model can be created easily.
For the second generation of !OpenKnee models, it is proposed to split the model definition into multiple files (although the single input file can be still be offered for users who prefer this approach). The following structure is proposed:
* ok2_mat.feb : contains all the material definitions.
* ok2_geom.feb : contains all the geometry and set definitions.
* ok2_contact.feb: contains the contact definitions. Contact surfaces reference the surface definitions in ok2_geom.feb
* ok2_bc.feb : defines the boundary conditions. For the OK2 model this is mostly the rigid kinematics.
* ok2_springs.feb: defines the springs in the model.
* ok2_lc.feb : defines the load curves required by the model. These lc's are used to define the rigid kinematics.
* ok2_out.feb : defines the Output section.
* ok2_steps.feb : defines all the Step sections. Currently, there are two steps: one for the passive kinematics, and one for the applied forces.
A master file then combines all these files in a single model definition. It would look something like this.
{{{
<?xml version="1.0" encoding="ISO-8859-1"?>
<febio_spec version="2.0">
<Material from="ok2_mat.feb"/>
<Geometry from="ok2_geom.feb"/>
<Contact from="ok2_contact.feb"/>
<Discrete from="ok2_springs.feb"/>
<Constraints from="ok2_bc.feb"/>
<LoadData from="ok2_lc.feb"/>
<Output from="ok2_out.fe"/>
<import>ok2_steps.feb</import>
</febio_spec>
}}}
The "from" attribute reads the corresponding section from another FEBio input file. Although as proposed here, this input file will only contain a single section, it is worth pointing out that this included file can have multiple sections, but only the referenced section will be read in. The Step sections are read in using the "import" keyword. (The "from" attribute won't work since it only reads in a single section and the OK2 model could have multiple sections as defined above).
As an example of how this can be customized easily, consider the case where the user wants to study the effect of in-situ strain on the ligaments. In FEBio2, this is accomplished by defining alternative constitutive models. Thus, a new material definition file needs to be created (e.g. ok2_mat_insitu.feb) which contains the new materials. Then, simply replace the material file reference in the master file (i.e. replace ok2_mat.feb with ok2_mat_insitu.feb) and a new OK2 model is created that now includes in-situ strains.