Input file for boneload simulations · Wiki · Boman Romain / fossils

Structure of an input file

Let us have a look at the contents of an input file. Input files are written in Python and contain a set of parameters gathered in a python dictionary and 2 sets of commands which run either Metafor or fossils.

As an example, let us analyze dolicorhynchops_10k.py.

This python file contains 3 parts.

The first one is a function named params which defines a python dictionary filled with the parameter names and their values.

def parms(d={}):
    p = {}

    # series of lines such as: p['parameter_name'] = value
    # [...]

    p.update(d)
    return p

The second part is the entry point of Metafor (a function named getMetafor). This function is called by Metafor when the script is executed by Metafor. It imports bonemodel.py which defines the Metafor model.

def getMetafor(p={}):
    import bonemodel as model
    return model.getMetafor(parms(p))

The third and last part is related to fossils. These lines are executed when the input file is run in the frame of fossils. It imports bonemodel2.py which is the "fossils" version of bonemodel.py. Then, the function named solve is called with the parameters as arguments.

if __name__ == "__main__":
    import models.bonemodel2 as model
    model.solve(parms())

In practice, the last two blocks can be blindly copied as shown hereabove at the end of any input file. The only important piece of information, which differs from one input file to the other, is the list of parameters in the params function.

Parameters

main dictionary

name	type	description
`bone`	filename	Full path to the surface mesh. STL, PLY, MSH and GEO files are accepted.
`muscles`	list of dict	A list of muscles. Each muscle is defined by a dictionary (see below).
`fixations`	list of dict	A list of fixations (displacements prescribed to 0 along a direction). Each fixation is defined by a dictionary (see below)
`loads`	list of dict	A list of additional nodal loads. Each fixation is defined by a dictionary (see below)
`extractors`	list of dict	A list of additional extractors. Extractors extract results such as stresses, strains or displacements computed at given nodes (see below)
`density`	scalar	Bone density (only used by the Chung-Hulbert time integration scheme of Metafor - not used with the linear-statics solver of fossils).
`Young`	scalar	Linear elasticity: Young's modulus.
`Poisson`	scalar	Linear elasticity: Poisson's coefficient.

muscles

name	type	description
`file`	filename	Full path to the file containing the part of the surface mesh corresponding to the muscle insertion surface. This mesh should contain a subset of the triangles from the bone surface mesh (see `bone` parameter above).
`force`	scalar	Amplitude of the muscle force. The distributed forces will be scaled such that the norm of their sum equals to this value.
`focalpt`	[x,y,z], or filename	The position of the focal point specified either with a coordinate list [x,y,z] or a filename of a mesh containing a single point. This point is also used as a direction if `method`is `D`. It is not used when `method`= `N`.
`method`	string	The load distribution method: `U` (uniform loading): the load is uniformly distributed on the surface; `T` (tangential loading): the loads follow the muscle fibres. The forces pointing through the bone are projected onto the tangent plane of the bone surface, `T+N` (tangent+normal): same as `T` but a normal component is added to the tangential one, which models the compressive action of the fibres that wrap around the bone. `D` (directional loading): the nodal forces are aligned along direction `focalpt` interpreted as a vector. It is equivalent to `U` with a focal point located infinitly far from the mesh in a given direction. `N` (normal loading): the nodal forces are perpendicular to the surface of the mesh. More mathematical details here.

fixations

name type description

name	type	description
`name`	string	user name of the fixation. This string is only used to display the associated forces after calculation. Examples: `axis_pt1`, `axis_pt2`, `contact_pts`, etc.
`nodes`	[x,y,z] or list of [x,y,z] or filename	node(s) on which the displacement will be prescribed to 0. It could be a point specified using its coordinates, or a list of coordinates, or the filename of a mesh (PLY, STL or OFF) the vertices of which will be used.
`direction`	list of chars	list of axis labels among `'x'`, `'y'`, `'z'` used to define the directions along which the displacement is prescribed to 0. Example: `['x', 'z']` contraints the x and z coordinates of the node(s) but let their y coordinate free.

name

string

user name of the fixation. This string is only used to display the associated forces after calculation. Examples: axis_pt1, axis_pt2, contact_pts, etc.

nodes

[x,y,z] or

list of [x,y,z] or filename

node(s) on which the displacement will be prescribed to 0. It could be a point specified using its coordinates, or a list of coordinates, or the filename of a mesh (PLY, STL or OFF) the vertices of which will be used.

direction

list of chars

list of axis labels among 'x', 'y', 'z' used to define the directions along which the displacement is prescribed to 0. Example: ['x', 'z'] contraints the x and z coordinates of the node(s) but let their y coordinate free.

loads

name type description

name	type	description
`name`	string	user name of the force. This is only used internally to define the name of the group of nodes.
`nodes`	[x,y,z] or list of [x,y,z] or filename	node(s) on which the force will be applied. It could be a point specified using its coordinates, or a list of coordinates, or the filename of a mesh (PLY or OFF) the vertices of which will be used.
`values`	[x,y,z]	the nodal force vector, as a 3-component vector. This vector will be applied to each node.

name

string

user name of the force. This is only used internally to define the name of the group of nodes.

nodes

[x,y,z] or

list of [x,y,z] or filename

node(s) on which the force will be applied. It could be a point specified using its coordinates, or a list of coordinates, or the filename of a mesh (PLY or OFF) the vertices of which will be used.

values

[x,y,z]

the nodal force vector, as a 3-component vector. This vector will be applied to each node.

extractors

name type description

name	type	description
`name`	string	user name of the extractor.
`nodes`	[x,y,z] or list of [x,y,z] or filename	node(s) on which the extractor will be applied. It could be a point specified using its coordinates, or a list of coordinates, or the filename of a mesh (PLY, STL or OFF) the vertices of which will be used.
`variables`	string or list of strings	a string among `x0`, `y0`, `z0` (initial position), `dx`, `dy`, `dz` (displacement), `fx`, `fy`, `fz` (external force), `sigxx`, `sigyy`, `sigzz`, `sigxy`, `sigyz`, `sigxz` (Cauchy-stress components), `sigvm` (Von-Mises stress), `epsxx`, `epsyy`, `epszz`, `epsxy`, `epsyz`, `epsxz` (strain tensor components)

name

string

user name of the extractor.

nodes

[x,y,z] or

list of [x,y,z] or filename

node(s) on which the extractor will be applied. It could be a point specified using its coordinates, or a list of coordinates, or the filename of a mesh (PLY, STL or OFF) the vertices of which will be used.

variables

string or list of strings

a string among x0, y0, z0 (initial position), dx, dy, dz (displacement), fx, fy, fz (external force), sigxx, sigyy, sigzz, sigxy, sigyz, sigxz (Cauchy-stress components), sigvm (Von-Mises stress), epsxx, epsyy, epszz, epsxy, epsyz, epsxz (strain tensor components)

The name and the value extracted is displayed after calculation if it concerns 1 single node. If several nodes are given, the values can be found in a text file in the workspace folder of the simulation.

In Metafor, the file is named (user name of the extractor)_(variable).ascii. Each line refers to a time increment (the last line is the final state). Each column refers to a node. Extracting x0 , y0 , z0 in addition to the wanted value can be useful to identify which value correspond to which node.

Additional notes

Relative paths

Prescribing the full path of mesh files can be done using a relative path built from the path of your input file:

As an example, if your script is located at c:\Users\Boman\Documents\Mywork\Panthera_pardus.py on your hard drive and the surface mesh is in the subfolder 150k in the same folder, instead of writing

def parms(d={}):
    p = {}
    p['bone'] = r'c:\Users\Boman\Documents\Mywork\150k\Panthera_pardus_mandible.stl'

which is not portable (Linux, macOS) and which makes the files not movable from one location to another one, you can retrieve the path of your script (c:\Users\Boman\Documents\Mywork) with os.path.dirname(__file__) (in python, __file__ is the full path to the current script and os.path.dirname extracts the folder part of a file name or folder name):

import os
path = os.path.join(os.path.dirname(__file__),'150k')
# from here, path=r'c:\Users\Boman\Documents\Mywork\150k'

The previous piece of code can thus be modified into:

def parms(d={}):
    p = {}
    import os
    path = os.path.join(os.path.dirname(__file__),'150k')
    p['bone'] = f'{path}/Panthera_pardus_mandible.stl'

What are these 'r' and 'f' in front of strings?

The r character in front of a python string means that the string is a "raw" string which means that it does not contain any "escaped characters" (it means that backslash characters are "real" backslash). If you don't use raw strings on windows the path separator which is a backslash will be sometimes merged with the next character to form an escaped character which has a special meaning (\n is a newline, \t is a tabulation, etc.).

For example:

'Users\Boman' means 'Users' + '\b' (the bell character) + 'oman'.
r'Users\Boman' == 'Users\\Boman' which is the correct set of characters.

The f character means that the string contains special formatting substrings between curly braces { ,}. these strings are called f-strings. A variable name between curly braces in a f-string is replaced by python by the value of the variable; thus f'{path}' is translated to 'c:\\Users\\Boman\\Documents\\Mywork\\150k' in the last example.