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

This is an old version of this page.

Go to most recent version Browse history

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.
`contact_pts`	list of [x,y,z], or list of filenames	List of coordinates of points where fixations are prescribed during the simulation (e.g.: 2 points: [ [x1,y1,z2], [x2, y2, z2] ]). Each point can also be entered as the filename of a PLY or OFF file containing a single point, instead of a [x,y,z] list.
`axis_pt1`	[x,y,z], or filename	Position of the node acting as the first point of the rotation axis of the bone. It can be introduced as a 3-component vector (a list of 3 scalars) or a full path to a PLY or OFF file containing a single point.
`axis_pt2`	[x,y,z], or filename	Second point of the rotation axis.
`muscles`	list of dict	A list of muscles. Each muscle is defined by a dictionary (see below).
`fixations`	dict (string=>list)	A dict (key=>value) which gives the components that are fixed (value), for the contact points and the 2 points of the axis (keys). The components to be fixed are given as a list of `x`, `y`, `z` characters.
`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.
`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. More mathematical details here.

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.