|
|
|
### 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](http://metafor.ltas.ulg.ac.be/) or [fossils](https://gitlab.uliege.be/rboman/fossils).
|
|
|
|
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](http://metafor.ltas.ulg.ac.be/) or [fossils](https://gitlab.uliege.be/rboman/fossils).
|
|
|
|
|
|
|
|
As an example, let us analyze [dolicorhynchops_10k.py](https://gitlab.uliege.be/rboman/fossils/-/blob/master/models/dolicorhynchops/dolicorhynchops_10k.py).
|
|
|
|
|
|
|
|
This python file contains 3 parts.
|
|
|
|
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.
|
|
|
|
|
| ... | ... | @@ -21,43 +20,185 @@ def parms(d={}): |
|
|
|
```
|
|
|
|
|
|
|
|
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](https://gitlab.uliege.be/rboman/fossils/-/blob/master/models/bonemodel.py) which defines the Metafor model.
|
|
|
|
|
|
|
|
```python
|
|
|
|
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](https://gitlab.uliege.be/rboman/fossils/-/blob/master/models/bonemodel2.py) which is the "fossils" version of `bonemodel.py`. Then, the function named `solve` is called with the parameters as arguments.
|
|
|
|
|
|
|
|
```python
|
|
|
|
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](#muscles)). |
|
|
|
|
| `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. |
|
|
|
|
| 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](#muscles)). |
|
|
|
|
| `fixations` | list of dict | A list of fixations (displacements prescribed to 0 along a direction). Each fixation is defined by a dictionary (see [below](#fixations)) |
|
|
|
|
| `loads` | list of dict | A list of additional nodal loads. Each fixation is defined by a dictionary (see [below](#loads)) |
|
|
|
|
| `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: <ul><li>`U` (uniform loading): the load is uniformly distributed on the surface; </li><li>`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, </li><li>`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.</li></ul><br />More mathematical details [here](boneload). |
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
|
|
<th>name</th>
|
|
|
|
<th>type</th>
|
|
|
|
<th>description</th>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`file`
|
|
|
|
</td>
|
|
|
|
<td>filename</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
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).
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`force`
|
|
|
|
</td>
|
|
|
|
<td>scalar</td>
|
|
|
|
<td>Amplitude of the muscle force. The distributed forces will be scaled such that the norm of their sum equals to this value.</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`focalpt`
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
\[x,y,z\], or filename
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
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`.
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`method`
|
|
|
|
</td>
|
|
|
|
<td>string</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
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](boneload).
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
#### fixations
|
|
|
|
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
|
|
<th>name</th>
|
|
|
|
<th>type</th>
|
|
|
|
<th>description</th>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`name`
|
|
|
|
</td>
|
|
|
|
<td>string</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
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.
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`nodes`
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
\[x,y,z\] or
|
|
|
|
|
|
|
|
list of \[x,y,z\] or filename
|
|
|
|
</td>
|
|
|
|
<td>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 or OFF) the vertices of which will be used.</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`direction`
|
|
|
|
</td>
|
|
|
|
<td>list of chars</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
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.
|
|
|
|
</td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
#### loads
|
|
|
|
|
|
|
|
<table>
|
|
|
|
<tr>
|
|
|
|
<th>name</th>
|
|
|
|
<th>type</th>
|
|
|
|
<th>description</th>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`name`
|
|
|
|
</td>
|
|
|
|
<td>string</td>
|
|
|
|
<td>user name of the force. This is only used internally to define the name of the group of nodes. </td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`nodes`
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
\[x,y,z\] or
|
|
|
|
|
|
|
|
list of \[x,y,z\] or filename
|
|
|
|
</td>
|
|
|
|
<td>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.</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
`values`
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
|
|
|
|
\[x,y,z\]
|
|
|
|
</td>
|
|
|
|
<td>the nodal force vector, as a 3-component vector. This vector will be applied to each node.</td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
### Additional notes
|
|
|
|
|
| ... | ... | @@ -73,7 +214,7 @@ def parms(d={}): |
|
|
|
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):
|
|
|
|
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):
|
|
|
|
|
|
|
|
```python
|
|
|
|
import os
|
| ... | ... | @@ -100,8 +241,4 @@ 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](https://realpython.com/python-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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The `f` character means that the string contains special formatting substrings between curly braces `{` ,`}`. these strings are called [f-strings](https://realpython.com/python-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. |
|
|
\ No newline at end of file |
