5 | [**Continuous Integration Platform**](https://ci.inria.fr/sofa-ci-dev/) 6 |
7 | 8 | A dashboard presents all the SOFA builds. 9 | You can find this interface here: 10 | 11 | 12 |13 | [**Dashboard**](http://www.sofa-framework.org/dash/) 14 |
-------------------------------------------------------------------------------- /30_Components/25_Engine/30_Transform/28_TransformPosition.md: -------------------------------------------------------------------------------- 1 | TransformPosition 2 | =============== 3 | 4 | This component belongs to the category of [Engines](../../../../simulation-principles/engine/). The TransformPosition engine transforms the positions of one DataFields into new positions after applying a transformation. This transformation can be either: 5 | 6 | - Projection on a plane (plane defined by an origin and a normal vector) 7 | - Translation, rotation, scale and some combinations of translation rotation and scale 8 | -------------------------------------------------------------------------------- /30_Components/48_IO/10_Mesh/50_MeshVTKLoader.md: -------------------------------------------------------------------------------- 1 | MeshVTKLoader 2 | ============= 3 | 4 | This component belongs to the category of the [MeshLoaders](../../../../simulation-principles/topology/#meshloaders). 5 | 6 | The MeshVTKLoader loads a mesh from a file under the format \*.vtk. Such a mesh file can be either surface or volumetric meshes. The \*.vtk meshes can be generated using the [Paraview](https://www.paraview.org) software. 7 | 8 | Usage 9 | ----- 10 | 11 | **No pre-requisite** in your scene to use a MeshLoader. 12 | -------------------------------------------------------------------------------- /30_Components/48_IO/10_Mesh/30_MeshOffLoader.md: -------------------------------------------------------------------------------- 1 | MeshOffLoader 2 | ============= 3 | 4 | This component belongs to the category of the [MeshLoaders](../../../../simulation-principles/topology/#meshloaders). 5 | 6 | The MeshOffLoader loads a mesh from a file under the format \*.off. Such a mesh file can be either surface or volumetric meshes. The \*.off meshes can be generated using software like [MeshLab](https://www.meshlab.net/). 7 | 8 | Usage 9 | ----- 10 | 11 | **No pre-requisite** in your scene to use a MeshLoader. 12 | 13 | -------------------------------------------------------------------------------- /35_Plugins/45_Suported_Plugins_List.md: -------------------------------------------------------------------------------- 1 | # Officially supported plugins 2 | 3 | This page aims at summarizing all plugins that are officially supported by the SOFA consortium. 4 | This means that the SOFA consortium commits to: 5 | 6 | 1. Including them in our continuous integration pipeline, thus assessing the compilation at every push in the SOFA master branch, at each new pull-request and at each nightly build 7 | 2. Including them in the official bi-annual SOFA binaries 8 | 3. Providing technical support on these plugins 9 | 10 | -------------------------------------------------------------------------------- /30_Components/25_Engine/20_Select/34_SubsetTopology.md: -------------------------------------------------------------------------------- 1 | SubsetTopology 2 | ============== 3 | 4 | This component belongs to the category of [Engines](../../../../simulation-principles/engine/). This engine separate topology in two parts, considering a ROI, a topology inside and a topology outside the ROI which can be a sphere or a box ROI used in this engine are similar to BoxROI and SphereROI. 5 | 6 | {.wp-image-1612 .alignright width="40%" height="auto"} 7 | -------------------------------------------------------------------------------- /30_Components/15_Collision/10_Detection/20_Intersection/10_IntersectionMethod.md: -------------------------------------------------------------------------------- 1 | Intersection Method 2 | =================== 3 | 4 | In SOFA, a proximity method can be used to detect contact when two objects are getting closer to another. 5 | Evaluating this proximity allows for a better anticipation of the contact, i.e. more stable contact. 6 | 7 | Examples of Components 8 | ====================== 9 | 10 | The following components are all intersection methods, and can be placed in a simulation scene: 11 | 12 | - [_MinProximityIntersection_](./../minproximityintersection) 13 | - [_LocalMinDistance_](./../localmindistance) 14 | -------------------------------------------------------------------------------- /10_Getting_Started/25_Video_Tutorials/40_Step_by_Step.md: -------------------------------------------------------------------------------- 1 | This video presents how to create a simulation in SOFA. Find the associated presentation [here (PDF version)](https://www.sofa-framework.org/wp-content/uploads/2016/08/2-Tutorial.pdf "Tutorial.pdf") 2 | 3 | 4 | 5 | We hope these videos helped you understand the basis of SOFA. If you want to provide us any [feedback](https://www.sofa-framework.org/users-feedback/ "Users' feedback"), do not hesitate. 6 | 7 | -------------------------------------------------------------------------------- /30_Components/48_IO/10_Mesh/40_MeshSTLLoader.md: -------------------------------------------------------------------------------- 1 | MeshSTLLoader 2 | ============= 3 | 4 | This component belongs to the category of the [MeshLoaders](../../../../simulation-principles/topology/#meshloaders). 5 | 6 | The MeshSTLLoader loads a mesh from a file under the [format \*.stl](https://en.wikipedia.org/wiki/STL_(file_format)). Such a mesh file **only supports surface meshes**. The \*.stl format is widely spread and such meshes can be generated using software like [MeshLab](https://www.meshlab.net/) or [Paraview](https://www.paraview.org) among many other solutions. 7 | 8 | Usage 9 | ----- 10 | 11 | **No pre-requisite** in your scene to use a MeshLoader. 12 | -------------------------------------------------------------------------------- /35_Plugins/50_Usual_plugins/MultiThreading/ParallelBruteForceBroadPhase.md: -------------------------------------------------------------------------------- 1 | # ParallelBruteForceBroadPhase 2 | 3 | This component is a parallel implementation of [BruteForceBroadPhase](../../../../components/collision/detection/algorithm/bruteforcebroadphase/) using a global thread pool. 4 | It means the result of a simulation with [BruteForceBroadPhase](../../../../components/collision/detection/algorithm/bruteforcebroadphase/) or with ParallelBruteForceBroadPhase is expected to be equal. 5 | ParallelBruteForceBroadPhase is the most efficient compared to [BruteForceBroadPhase](../../../../components/collision/detection/algorithm/bruteforcebroadphase/) when there is a lot of objects in the scene. 6 | -------------------------------------------------------------------------------- /30_Components/48_IO/10_Mesh/10_MeshGmshLoader.md: -------------------------------------------------------------------------------- 1 | MeshGmshLoader 2 | ============== 3 | 4 | This component belongs to the category of the [MeshLoaders](../../../../simulation-principles/topology/#meshloaders). 5 | 6 | The MeshGmshLoader loads a mesh from a file under the format \*.msh. Such a mesh file can be either surface or volumetric meshes. The \*.msh meshes can be generated using software like [Gmsh](https://gmsh.info/). 7 | To be noted, an interesting [project couples SOFA and Gmsh in python](https://github.com/sescaida/gmsh-sofa_tutorial) for applications such as parametric design or design optimization. 8 | 9 | Usage 10 | ----- 11 | 12 | **No pre-requisite** in your scene to use a MeshLoader. 13 | 14 | -------------------------------------------------------------------------------- /35_Plugins/50_Usual_plugins/60_Xitact.md: -------------------------------------------------------------------------------- 1 | Xitact are haptic device product by the company **Mentice**. Two models are handled in SOFA: 2 | 3 | - Xitact™ IHP: a haptic device designed to track the motion of a 4 | surgical instrument and to provide realistic force feedback during 5 | the simulation of a minimally invasive surgical procedure. 6 | - Xitact™ ITP: a device designed to track the motion of an instrument 7 | during the simulation of a minimally invasive surgical procedure. 8 | 9 | Install 10 | ------- 11 | 12 | Here is a walkthrough on how to install, compile and use in SOFA: 13 | 14 | - Activate the plugin Xitact: **SOFA-PLUGIN\_XITACT**, 15 | - Compile Sofa again, 16 | - This is it. 17 | 18 | -------------------------------------------------------------------------------- /10_Getting_Started/25_Video_Tutorials/30_Introduction_course.md: -------------------------------------------------------------------------------- 1 | In order to help you starting with SOFA, we recorded a video of the SOFA days. This first video presents an generic introduction to the main principles of SOFA. Find the associated presentation [here (PDF version)](https://www.sofa-framework.org/wp-content/uploads/2016/08/1-Presentation-SOFA-VRIPHYS2015.pdf "Presentation-SOFA-VRIPHYS2015.pdf"). 2 | 3 | 2023 Tutorial (using SOFA v23.06): 4 | 5 | 6 | 7 | 8 | All SOFA tutorials are available here on our YouTube channel: [Tutorial playlist](https://www.youtube.com/playlist?list=PLL2-UDGHPj0iLCieVkrv3OvAme0jsWl91). 9 | -------------------------------------------------------------------------------- /20_Simulation_Principles/50_Multi-Model_Representation/30_Visual_Model.md: -------------------------------------------------------------------------------- 1 | Visualization 2 | ============= 3 | 4 | To visualize an object in SOFA, the main component to use is the _OglModel_. 5 | Using OpenGL, this class will display the topology of its context. To display a mesh loaded with any MeshLoader, all you need to do is to connect the OglModel with the MeshLoader by writing (in case if an XML scene): 6 | 7 | ```xml 8 |
8 |
9 |
10 |
11 | Usage
12 | -----
13 |
14 | As a Forcefield, the ConstantForceField requires a **MechanicalObject** and the associated **solvers** (integration scheme and linear solver), as well as a **PointSetTopologyContainer**.
15 |
--------------------------------------------------------------------------------
/30_Components/20_Constraint/20_Lagrangian/Model/FixedLagrangianConstraint.md:
--------------------------------------------------------------------------------
1 | FixedLagrangianConstraint
2 | =========================
3 |
4 | This component belongs to the category of [Constraint Laws](../../../../../simulation-principles/constraint/lagrange-constraint/#constraint-laws) used for the Lagrange constraint resolution.
5 | The FixedLagrangianConstraint defines a [holonomic constraint](https://en.wikipedia.org/wiki/Holonomic_constraints) law applied on some degrees on freedom to fix them in space.
6 |
7 | The constraint equation can be written as:
8 |
9 | $$
10 | \Phi(q) = q - q_0
11 | $$
12 |
13 | where $q$ is the position and $q_0$ is the initial position.
14 |
15 | The constraint matrix $\mathbf{H}$ (derivative of the constraint law) is then filled with blocks of the identity matrix (of the dimension of the number of degrees of freedom per point) under each considered fixed index. If `fixAll` is selected, then this Jacobian is the identity matrix.
16 |
17 | $$
18 | \mathbf{H} = \mathbf{I}
19 | $$
20 |
--------------------------------------------------------------------------------
/30_Components/75_UI/10_Customizing_the_UI.md:
--------------------------------------------------------------------------------
1 | #### AttachBodyButtonSetting
2 |
3 | Tune the attachBody mouse operation, like which button is used for the
4 | operation and the stiffness of the spring.
5 |
6 | #### FixPickedParticleButtonSetting
7 |
8 | Specify the mouse button used for this particular operation.
9 |
10 | #### ViewerSetting
11 |
12 | Customize things like the resolution of the viewer, the camera
13 | projection, and the picking method. The picking can be done through ray
14 | casting (default) or can be imaged based by using a selection buffer. If
15 | you use the picking with the selection buffer you can only pick the
16 | surface primitives like triangles and spheres which belong to the
17 | collision layer of your models.
18 |
19 | #### BackgroundSetting
20 |
21 | Tune the color or the image used for the background of the viewer.
22 |
23 | #### SofaDefaultPathSetting
24 |
25 | Tell Sofa where to put your simulation records and gnuplot files.
26 |
27 | #### StatsSettings
28 |
29 | Give access to various logging options.
30 |
--------------------------------------------------------------------------------
/.github/workflows/trigger-doc.yml:
--------------------------------------------------------------------------------
1 | name: Trigger DocGenerateAndPublish Workflow
2 |
3 | on:
4 | workflow_dispatch:
5 | inputs:
6 | script-branch:
7 | description: 'Specify the branch on which the DocGenerateAndPublish action should run'
8 | default: 'gen'
9 | type: string
10 | schedule:
11 | - cron: '0 6 * * 1' # Every Monday morning
12 | push:
13 | branches:
14 | - master
15 |
16 | jobs:
17 | trigger_workflow:
18 | runs-on: ubuntu-latest
19 | steps:
20 | - uses: actions/checkout@v3
21 | - name: Run on dispatch
22 | if: ${{ github.event_name == 'workflow_dispatch' }}
23 | run: gh workflow run DocGenerateAndPublish --ref ${{ inputs.script-branch }}
24 | env:
25 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
26 | - name: Run on push and nightly
27 | if: ${{ github.event_name != 'workflow_dispatch' }}
28 | run: gh workflow run DocGenerateAndPublish --ref gen
29 | env:
30 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
31 |
--------------------------------------------------------------------------------
/35_Plugins/50_Usual_plugins/75_SofaCarving.md:
--------------------------------------------------------------------------------
1 | The SofaCarving plugin provides basic functionality for removing
2 | tetrahedra from a mesh. This can be used to simulate tissue destruction
3 | in medical simulations. []()
4 |
5 | Loading the Plugin
6 | ---------------------------------------------------
7 |
8 | To load the SofaCarving plugin, select **SOFA-PLUGIN\_SOFACARVING** in
9 | your Cmake configuration. Reconfigure, generate and build. []()
10 |
11 | CarvingManager
12 | -----------------------------------------------
13 |
14 | The plugin provides one component, the CarvingManager. When added to a
15 | scene, it automatically looks for a collision model that will act as
16 | the tool from removing tetrahedra, and a surface model that will have
17 | its tetrahedra removed by the tool. If your scene has many possible
18 | collision or surface models, you can specify the ones that the
19 | CarvingManager will use by giving those components the tags
20 | **CarvingTool** and **CarvingSurface**. See the example scene
21 | **SofaCarving/SimpleCarving.scn**.
22 |
--------------------------------------------------------------------------------
/30_Components/10_AnimationLoop/20_MultiStepAnimationLoop.md:
--------------------------------------------------------------------------------
1 | MultiStepAnimationLoop
2 | ======================
3 |
4 | This component belongs to the category of [AnimationLoop](../../../simulation-principles/animation-loop/).
5 |
6 | The MultiStepAnimationLoop derives from the [DefaultAnimationLoop](../../../components/animationloop/defaultanimationloop/). This animation loop is different due to the fact that it allows - at each iteration - for running several collision (_collisionSteps_), and within each of these collision steps, several integration sub-steps can be computed (_integrationSteps_).
7 |
8 | 
9 |
10 |
11 | Usage
12 | -----
13 |
14 | The MultiStepAnimationLoop has **no pre-requisite**.
15 |
16 | Note that this MultiStepAnimationLoop does not handle constraints solved using [Lagrange multipliers](../../../simulation-principles/constraint/lagrange-constraint/).
17 |
--------------------------------------------------------------------------------
/30_Components/65_Rendering/10_Different_Viewports.md:
--------------------------------------------------------------------------------
1 | Using different views in OpenGL
2 | -------------------------------
3 |
4 | You can get different points of view of your scene. It can be useful if
5 | you want to watch something for example. In order to get those
6 | viewports, you have to add :
7 |
8 | ```xml
9 | 
18 |
19 |
20 | The SparseCholeskySolver **requires** the use (above in the scene graph) of an integration scheme, and (below in the scene graph) of a MechanicalObject storing the state information that the SparseCholeskySolver will access.
21 |
--------------------------------------------------------------------------------
/50_Contributing_to_SOFA/50_Add_your_paper_on_HAL.md:
--------------------------------------------------------------------------------
1 | You want your papers, which rely on SOFA, to be listed on our website? Just follow the following explanations for HAL.
2 |
3 | 
4 |
5 | ## Case 1 - add a new paper on HAL
6 |
7 | First, go on the [HAL portal](https://hal.archives-ouvertes.fr/) and log in. Follow carefully the following steps: The upload process starts by clicking on "Submit":
8 |
9 | * choose the type of paper (poster, conference or journal ..)
10 | * upload the compulsory documents:
11 | * the PDF document,
12 | * videos, or others supplementary data, if any,
13 | * one or several images: do not forget to define one image as primary as shown in the following image.
14 |
15 | 
16 |
17 | 
9 |
10 |
11 | Usage
12 | -----
13 |
14 | The FreeMotionAnimationLoop must be used specifically for constraint resolution based on the Lagrange multiplier. It therefore **requires**:
15 |
16 | - a [ConstraintSolver](../../../simulation-principles/constraint/lagrange-constraint/#constraintsolver-in-sofa). If no constraint solver can be found, a LCPConstraintSolver is automatically created by default.
17 |
18 | Note that one or multiple [ConstraintCorrection](../../../simulation-principles/constraint/lagrange-constraint/#constraintcorrection) may be required by the [ConstraintSolver](../../../simulation-principles/constraint/lagrange-constraint/#constraintsolver-in-sofa).
19 |
20 |
--------------------------------------------------------------------------------
/40_Programming_with_SOFA/60_API_overview/45_Pause_the_animation.md:
--------------------------------------------------------------------------------
1 | Pause the Animation
2 | -------------------
3 |
4 | Sometimes, you would like the animation to be paused without pressing
5 | any button but from the **Simulation** itself. For example if solver
6 | does not converge, you might want to stop the animation to look
7 | at it carefully, or because the interesting part is over. This is now
8 | possible, using a **PauseAnimation** component. This component has a
9 | method *pause()* that tells the Simulation it should be paused using
10 | *setPaused()* a WriteAccessor on the Simulation field paused. The
11 | RealGUI step() we check the state of the Simulation to know if we should
12 | stop the Animation, pressing back the Animate button.
13 |
14 | #### PauseAnimationOnEvent
15 |
16 | **PauseAnimationOnEvent** is derived from **PauseAnimation** and handles
17 | *PauseEvent* event. When it receives this event, it calls the *pause()*
18 | method. Add the following component on your scene description:
19 |
20 | ```xml
21 | listening="true"
22 | ```
23 |
24 | Then launch the PauseEvent where you want to in your code. For example,
25 | when your solver does not succeed to converge, or when the simulated end
26 | time has been reached... (To learn how to launch a visitor).
27 |
28 | #### Quick component hierarchy overview
29 |
30 | \[caption id="attachment\_1551" align="aligncenter"
31 | width="350"\][{.size-full
33 | .wp-image-1551 width="350"
34 | height="239"}](https://www.sofa-framework.org/wp-content/uploads/2014/11/350px-PauseAnimation1.png)
35 | PauseAnimation architecture\[/caption\]
36 |
--------------------------------------------------------------------------------
/35_Plugins/10_What_is_a_plugin.md:
--------------------------------------------------------------------------------
1 | # What is a Plugin?
2 |
3 | SOFA allows to extend its feature with a plugin mechanism. A plugin is a shared library that can be loaded dynamically at run-time by SOFA. More features become available, such as new components or alternative scene loaders.
4 |
5 | # Online plugin list
6 |
7 | The [Online plugin list](https://www.sofa-framework.org/applications/plugins/) highlights some of the SOFA plugins. Never hesitate to request, inquire for one or to [submit your own plugin](https://www.sofa-framework.org/applications/submit/).
8 |
9 | # Plugin Loading
10 |
11 | In order to use the features of a plugin, it must be loaded first. SOFA offers multiple ways to load a plugin.
12 |
13 | ## Command-line Argument
14 |
15 | The application `runSofa` accepts an optional argument `-l,--load` to specify a list of plugins to load. A plugin can be provided as a full path, or as a name. In the latter case, the plugin library will be searched in known folders for a match.
16 |
17 | ## Automatic Loading
18 |
19 | By default, the application `runSofa` reads the content of a configuration file to load automatically a list of plugins. This list can be edited to add the plugin you need. The file is either `plugin_list.conf` or `plugin_list.conf.default`. `plugin_list.conf.default` is generated automatically at compile-time and is not meant to be edited. To edit a list of plugins, `plugin_list.conf` must be used. If the file does not exist, it must be created based on `plugin_list.conf.default`.
20 |
21 | ## GUI: Plugin Manager
22 |
23 | The GUI allows to load a plugin through a graphical user interface. Go to `Edit > Plugin Manager ...`. You will see the list of already loaded plugins. Click on `Add...` to load another plugin.
24 |
--------------------------------------------------------------------------------
/30_Components/15_Collision/10_Detection/10_Algorithm/33_RayTraceNarrowPhase.md:
--------------------------------------------------------------------------------
1 | Narrow Phase: Ray Trace Narrow Phase
2 | ====================================
3 |
4 | The RayTraceNarrowPhase component is a [narrow phase component](./../narrowphase), which is used in the detection phase of a [CollisionPipeline](../../collisionpipeline/#collision-detection).
5 | This method traces a ray for each point in one object following the opposite of the point's normal up to find a triangle in the other object.
6 | Both triangles are tested to evaluate if they are in a colliding state.
7 |
8 | It **must be used with a TriangleOctreeModel**, as an octree is used to traverse the object.
9 |
10 | The Algorithm
11 | =============
12 |
13 | The CollisionModel at the lowest level is saved, in this case it must be a TriangleOctreeModel. If the octree would not be constructed already, build it. Then, rays are traced against the TriangleOctreeModel. Distances computed with the ray indicates if a collision occurs between the pair of TriangleOctreeModels. Finally, the DetectionOutput vector containing elements of TriangleOctreeModels in collision is returned, as well as the contact points on the triangle of each model.
14 |
15 | Example of Usage
16 | ================
17 |
18 | This component can be used as follows in XML format:
19 |
20 | ```xml
21 | 
24 |
25 | The SparseLUSolver **requires** the use (above in the scene graph) of an integration scheme, and (below in the scene graph) of a MechanicalObject storing the state information that the SparseLUSolver will access.
26 |
27 | The SparseLUSolver is the most generic direct solver. It may be time consuming but it will be able compute the exact solution as soon as $$\mathbf{A}"> is invertible.
28 |
--------------------------------------------------------------------------------
/30_Components/10_AnimationLoop/10_DefaultAnimationLoop.md:
--------------------------------------------------------------------------------
1 | DefaultAnimationLoop
2 | ====================
3 |
4 | This component belongs to the category of [AnimationLoop](../../../simulation-principles/animation-loop/).
5 |
6 | The DefaultAnimationLoop is the component that rules the steps of the simulation in the default order. It consists in computing the collision (if any), the projective constraints, the physics, solving the resulting linear system and finally updating all data before another step begins.
7 |
8 | 
9 |
10 |
11 | Data
12 | ----
13 |
14 | The DefaultAnimationLoop has one data:
15 |
16 | - **parallelODESolving**: if true, solves all the ODEs in parallel
17 | - **computeBoundingBox**: a boolean defining whether the global bounding box of the scene is computed at each time step. Used mostly for rendering.
18 |
19 |
20 | Usage
21 | -----
22 |
23 | The DefaultAnimationLoop has **no pre-requisite**. If no AnimationLoop is specified in the scene, this animation loop is included by default at the root node of the graph.
24 |
25 | Note that this AnimationLoop does not support constraints solved using [Lagrange multipliers](../../../simulation-principles/constraint/lagrange-constraint/).
26 |
27 |
28 | Example
29 | -------
30 |
31 | This component is used as follows in XML format:
32 |
33 | ``` xml
34 | 
46 |
47 |
48 | Usage
49 | -----
50 |
51 | At each simulation step and each Newton Raphson iteration, the NewmarkImplicitSolver **requires**:
52 |
53 | - a [LinearSolver](../../../../simulation-principles/system-resolution/linear-solver/) to solve the linear system
54 | - and a MechanicalObject to store the state vectors.
55 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | SOFA Documentation
2 | ==================
3 |
4 | This section provides articles to help the community starting using SOFA and developing interactive applications.
5 |
6 |
7 | ### Content
8 | - **Getting Started**: instructions about building and installing SOFA.
9 | - **Main Principles**: everything you need to know about what is SOFA and how it works.
10 | - **Video Tutorials**: list videos helping new users starting with SOFA.
11 | - **Using SOFA**: how to use SOFA to build and run simulation scenes (user documentation).
12 | - **Programming with SOFA**: how to write your own code and then contribute it to SOFA (developer documentation).
13 |
14 |
15 | ### Support forum
16 |
17 | Feel free to leverage the [SOFA Discussions forum](http://github.com/sofa-framework/sofa/discussions/) to elaborate on your queries. The supportive SOFA community is eager to offer assistance and guidance.
18 |
19 | ### List of plugins
20 |
21 | Before crafting your own code, explore the [SOFA plugin list](https://www.sofa-framework.org/applications/plugins/). You might just find exactly what you are searching for!
22 |
23 | ### Cite SOFA
24 |
25 | Detailed introductions about SOFA and SOFA in soft-robotics were written:
26 |
27 | - SOFA Framework: **SOFA: A Multi-Model Framework for Interactive Physical Simulation**. F. Faure et al. _Soft Tissue Biomechanical Modeling for Computer Assisted Surgery_, 2012 \[[BibTex](https://hal.inria.fr/hal-00681539v1/bibtex)\]
28 | - SoftRobot: **Software toolkit for modeling, simulation and control of soft robots**. E. Coevoet et al. _Advanced Robotics_, 2017 \[[BibTex](https://hal.inria.fr/hal-01649355v1/bibtex)\]
29 |
30 | ### Contribution
31 | Everyone is very welcome to contribute to this documentation. This can be done by pull-requesting changes on the [documentation GitHub repository](https://github.com/sofa-framework/doc/) or by [reporting any missing information](https://github.com/sofa-framework/doc/issues/new) so that this documentation may constantly improve!
32 |
33 | Files are written in Markdown. If you don't understand the syntax, you can refer to [this useful cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
34 |
--------------------------------------------------------------------------------
/30_Components/30_SolidMechanics/10_FEM/HyperElastic/30_TetrahedronHyperelasticityFEMForceField.md:
--------------------------------------------------------------------------------
1 | TetrahedronHyperelasticityFEMForceField
2 | =======================================
3 |
4 | This component belongs to the category of [ForceField](../../../../../simulation-principles/multi-model-representation/forcefield/). The TetrahedronHyperelasticityFEMForceField implements - for tetrahedral topology only - several non-linear mechanical constitutive laws, also named as hyperelastic constitutive laws. The available models are:
5 |
6 | - [Arruda-Boyce model](https://en.wikipedia.org/wiki/Arruda%E2%80%93Boyce_model)
7 | - [Costa model](https://www.jstor.org/stable/pdf/3066567.pdf)
8 | - [Mooney-Rivlin model](https://en.wikipedia.org/wiki/Mooney%E2%80%93Rivlin_solid)
9 | - [Neo-Hookean model](https://en.wikipedia.org/wiki/Neo-Hookean_solid)
10 | - [Stable Neo-Hookean model](https://dl.acm.org/doi/10.1145/3180491)
11 | - [Ogden model](https://en.wikipedia.org/wiki/Ogden_hyperelastic_model) (order 1)
12 | - [St Venant-Kirchhoff model](https://en.wikipedia.org/wiki/Hyperelastic_material#Saint_Venant%E2%80%93Kirchhoff_model)
13 | - [Veronda-Westmann model](https://www.sciencedirect.com/science/article/pii/0021929070900552)
14 |
15 |
16 |
17 | Note that the **ParameterSet** data changes depending on the chosen material. It corresponds to:
18 |
19 | - for "ArrudaBoyce", two parameters are required: $\left[ \mu ,k_0\right]$
20 | - for "Costa", eight parameters are required: $\left[ a,k_{0},b_{ff},b_{fs},b_{ss},b_{fn},b_{sn},b_{nn}\right]$
21 | - for "MooneyRivlin", three parameters are required: $\left[ C_{01},C_{10},k_{0}\right]$
22 | - for "NeoHookean", two parameters are required: $\left[ \mu,\lambda \right]$
23 | - for "Ogden", three parameters are required: $\left[ k,\mu_1,\alpha_1\right]$
24 | - for "StVenantKirchhoff", two parameters are required: $\left[ \mu,\lambda \right]$
25 | - for "VerondaWestman", parameters are required: $\left[ C_{1},C_{2},k_0\right]$
26 |
27 |
28 | Usage
29 | -----
30 |
31 | As a Forcefield, the TetrahedronHyperelasticityFEMForceField requires a **MechanicalObject** and the associated **solvers** (integration scheme and linear solver), as well as a **TetrahedronSetTopologyContainer**.
32 |
33 |
--------------------------------------------------------------------------------
/30_Components/45_LinearSolver/10_Iterative/10_CGLinearSolver.md:
--------------------------------------------------------------------------------
1 | CGLinearSolver
2 | ==============
3 |
4 | This component belongs to the category of [LinearSolver](../../../../simulation-principles/system-resolution/linear-solver/). The role of the CGLinearSolver is to solve the linear system $\mathbf{A}x=b$ without any _a priori_ on this system.
5 |
6 | In SOFA, the CGLinearSolver follows the well-known [conjugate gradient method](https://en.wikipedia.org/wiki/Conjugate_gradient_method), which consists in iteratively solving $r=b-\mathbf{A}x^k$ where *r* is known as the residual. This residual will be used to compute mutually conjugate vectors *p* (see the sequence diagram below) which will be used as a basis to find a new approximated solution $x^{k+1}$.
7 |
8 | **Note**: the CGLinearSolver in SOFA assumes that the right hand side (RHS) vector *b* is already computed. The computation of *b* is usually called in the [integration scheme](../../../../simulation-principles/system-resolution/integration-scheme/) through the function `computeForce()`.
9 |
10 |
11 |
12 | Sequence diagram
13 | ----------------
14 |
15 | 
16 |
17 |
18 | Usage
19 | -----
20 |
21 | The CGLinearSolver **requires** the use (above in the scene graph) of an integration scheme, and (below in the scene graph) of a MechanicalObject storing the state information that the CGLinearSolver will access.
22 |
23 | When using a CGLinearSolver, make sure you carefully chose the value of the free data field iterations, tolerance and threshold. Both tolerance and threshold data must be chosen in accordance with the dimension of the degrees of freedom (DOFs). Usually, the value of these two data is close to the square of the expected error on the DOFs.
24 |
25 | Remember that when using an iterative linear solver like the CGLinearSolver, no exact solution can be found. The accuracy of your solution will always depend on the conditioning of your system and your input data (iterations, tolerance and threshold).
26 |
27 |
--------------------------------------------------------------------------------
/30_Components/45_LinearSolver/20_Direct/55_AsyncSparseLDLSolver.md:
--------------------------------------------------------------------------------
1 | AsyncSparseLDLSolver
2 | ====================
3 |
4 | AsyncSparseLDLSolver is based on [SparseLDLSolver](./../sparseldlsolver/).
5 | It follows some ideas presented in:
6 |
7 | > Courtecuisse, Hadrien, et al. "Asynchronous preconditioners for efficient solving of non-linear deformations." VRIPHYS-Virtual Reality Interaction and Physical Simulation. Eurographics Association, 2010.
8 | https://hal.inria.fr/hal-00688865/document
9 |
10 | ## Asynchronous Factorization
11 |
12 | The difference compared to SparseLDLSolver resides in the fact that the factorization of the matrix is performed in a different thread in order to speed up the simulation.
13 |
14 | The synchronous version performs the following operations (synchronously):
15 | 1) Build the matrix
16 | 2) Factorize the matrix
17 | 3) Solve the system based on the factorization
18 |
19 | In the asynchronous version, the factorization is performed asynchronously.
20 | A consequence is that the solving process uses a factorization which may not be up-to-date.
21 | In practice, the factorization is at least one time step old, but it can be an older factorization depending on the duration of the asynchronous factorization step.
22 | Because of this, the solver computes an approximation of the solution, based on an old factorization.
23 | It is therefore important to understand that using AsyncSparseLDLSolver changes the behavior of your simulation compared to a synchronous version.
24 | It may also introduce instabilities.
25 |
26 | ## A Preconditioner
27 |
28 | AsyncSparseLDLSolver can be used as a preconditioner of [ShewchukPCGLinearSolver](../../iterative/preconditioned-cg/).
29 |
30 | ## Performances
31 |
32 | The idea to have the factorization of the matrix in a different thread is to reduce the time taken to solve a linear system.
33 | However, building the matrix and solving a system based on a factorization will not be reduced.
34 | Since the factorization of a matrix is a time-consuming step of the simulation, this strategy greatly improves the performances.
35 | This speed up is at the price of an approximation of the solution, because solving the linear system relies on a factorization of a matrix from a previous time step.
36 |
--------------------------------------------------------------------------------
/40_Programming_with_SOFA/60_API_overview/13_DataTypes.md:
--------------------------------------------------------------------------------
1 | DataTypes
2 | =========
3 |
4 | As you may know, many SOFA C++ classes are templated, mostly on the type of DOF you want to simulate. Examples of templates can be found in the [MechanicalObject page](../../../simulation-principles/mechanicalobject/), in the [templates section](../../../simulation-principles/mechanicalobject/#templates). In the code, the use of templates can be confusing, especially when the type used in place of the template has itself many types. This page provides a short introduction to all these DOF types.
5 |
6 | All DOF Types must implement (or define) all the following types:
7 |
8 | - **Real**: corresponds to a double or float value, depending on the DataTypes used: a class templated in Vec3d will return a double, whereas a a class templated in Vec3f will return a float
9 |
10 | - **Coord**: standing for "coordinate", corresponds to a vector of _Real_ with a size given by the number of degrees of freedom: a class templated in Vec6d will return a vector of 6 doubles. This vector is homogeneous to your degrees of freedom.
11 |
12 | - **Deriv** standing for "derivative", corresponds to a vector of _Real_ with a size given by the number of degrees of freedom: a class templated in Vec6d will return a vector of 6 doubles
13 |
14 | - **VecCoord** or **VecDeriv**: correspond to a vector of respectively _Coord_ or _Deriv_
15 |
16 | - **DataVecCoord or DataVecDeriv**: correspond to a [Data](../../../simulation-principles/scene-graph/#data) containing a vector of respectively _Coord_ or _Deriv_. As noted in the associated article, the Data are variable of the class exposed to the user and other components in the scene
17 |
18 | - **MatrixCoord or MatrixDeriv**: correspond to a matrix of respectively _Coord_ or _Deriv_, this is more especially used by solvers and constraint algorithms
19 |
20 | - **VecCoordId, VecDerivId, MatrixCoordId or MatrixDerivId**: correspond to an identifiant value (int) pointing to a vector or matrix of respectively _Coord_ or _Deriv_. This is very useful to access specific vectors or matrix in the simulation. [State vectors](../../../simulation-principles/mechanicalobject/#state-vectors) for instance are managed with specific protected Ids by the solvers.
21 |
--------------------------------------------------------------------------------
/30_Components/40_ODESolver/20_Backward/NewtonRaphsonSolver.md:
--------------------------------------------------------------------------------
1 | NewtonRaphsonSolver
2 | ===================
3 |
4 | NewtonRaphsonSolver is a component able to solve nonlinear equations using [Newton-Raphson method](https://en.wikipedia.org/wiki/Newton%27s_method).
5 | From an initial guess, the algorithm successively computes better approximations of the root of the nonlinear function.
6 | At every iteration, multiple criteria are evaluated to decide to stop the algorithm (because it converged or the maximum number of iterations has been reached), or to continue.
7 |
8 | The algorithm relies on the derivative of the function and a linear system to solve.
9 | For a function $F : \mathbb{R}^k \rightarrow \mathbb{R}^k$, the new approximation of the root $x_{n+1}$ is computed as:
10 |
11 | $$
12 | \nabla_F(x_n) (x_{n+1} - x_n) = -F(x_n)
13 | $$
14 |
15 | where:
16 |
17 | - $x_i$ is the $i$-th approximation of the root
18 | - $x_0$ is the initial guess
19 | - $\nabla_F$ is the Jacobian matrix of the function
20 |
21 | If $dx$ is the solution of the previous linear system, then
22 |
23 | $$
24 | x_{n+1} = dx + x_n
25 | $$
26 |
27 | Example
28 | -------
29 |
30 | To solve a static equilibrium (see [StaticSolver](StaticSolver.md)), the nonlinear equation to solve is the sum of forces must be equal to zero ($\sum F = 0$). At each iteration, the linear system $K dx = -\sum F$ must be solved to compute the next approximation of the root. Here K is the derivative of the forces, also called the stiffness matrix.
31 |
32 | Usage
33 | -----
34 |
35 | This component must be linked by another component requiring to solve a nonlinear equation, such as an implicit ODE solver or a static solver.
36 |
37 | In XML format, the link may look like:
38 |
39 | ```xml
40 | | Name | 22 |Description | 23 |Default value | 24 |
|---|---|---|
| name | 29 |30 | object name 31 | | 32 |unnamed | 33 |
| printLog | 36 |37 | if true, emits extra messages at runtime. 38 | | 39 |0 | 40 |
| tags | 43 |44 | list of the subsets the objet belongs to 45 | | 46 |47 | |
| bbox | 50 |51 | this object bounding box 52 | | 53 |54 | |
| componentState | 57 |58 | The state of the component among (Dirty, Valid, Undefined, Loading, Invalid). 59 | | 60 |Undefined | 61 |
| listening | 64 |65 | if true, handle the events, otherwise ignore the events 66 | | 67 |0 | 68 |
| isCompliance | 71 |72 | Consider the component as a compliance, else as a stiffness 73 | | 74 |0 | 75 |
| rayleighStiffness | 78 |79 | Rayleigh damping - stiffness matrix coefficient 80 | | 81 |0 | 82 |
| coneCenter | 85 |86 | cone center 87 | | 88 |89 | |
| coneHeight | 92 |93 | cone height 94 | | 95 |96 | |
| coneAngle | 99 |100 | cone angle 101 | | 102 |10 | 103 |
| stiffness | 106 |107 | force stiffness 108 | | 109 |500 | 110 |
| damping | 113 |114 | force damping 115 | | 116 |5 | 117 |
| color | 120 |121 | cone color. (default=0.0,0.0,0.0,1.0,1.0) 122 | | 123 |0 0 1 1 | 124 |
18 |
19 | Although the method is working properly, the intersection might result in a high number of contacts. This works just fine for Penalty method (many springs will be generated). However, using a response method based on Lagrange multipliers, many constraints will be generated which might rapidly become computationally-demanding.
20 |
21 | Moreover, the contacts can be a bit degenerated: many contacts with different orientations. Again, using Penalty, it might only create some numerical friction but, using the Lagrange multiplier resolution, this can lead to contradictory constraints (worsening the convergence).
22 |
23 |
24 |
25 | Usage
26 | -----
27 |
28 | The MinProximityIntersection must be placed right after the CollisionPipeline and the associated Detection methods (usually [BruteForceBroadPhase](../../algorithm/bruteforcebroadphase/) and [BVHNarrowPhase](../../algorithm/bvhnarrowphase/)) on top the scene graph.
29 |
30 |
31 | Additional information
32 | ----------------------
33 |
34 | - collision models in the scene will have the data **proximity** corresponding to an enlargement of the collision model, i.e., value added to the alarmDistance and the contactDistance and also when building AABBs in the broad phase
35 | - a different alarmDistance and contactDistance can be specified for each CollisionModel by setting alarmDistance and contactDistance to zero and changing the proximity parameter
36 |
37 |
--------------------------------------------------------------------------------
/30_Components/20_Constraint/10_Projective/50_FixedProjectiveConstraint.md:
--------------------------------------------------------------------------------
1 | FixedProjectiveConstraint
2 | =========================
3 |
4 | This component belongs to the category of [Projective Constraint](../../../../simulation-principles/constraint/projective-constraint/).
5 | The FixedProjectiveConstraint projects a constant velocity. If the fixed points have a zero velocity at the simulation start, they will keep a zero velocity i.e. be fixed.
6 |
7 | As introduced in the page about the Projective Constraint, the FixedProjectiveConstraint corresponds to a projection matrix noted $\mathbf{P}$ which will multiply the system matrix $\mathbf{A}$ so that: $\mathbf{P}^T\mathbf{A}\mathbf{P}\Deltav=\mathbf{P}^Tb$. This projection matrix $\mathbf{P}$ is the identity matrix in which the diagonal value corresponding to the indices of the fixed points equals zero. These lines and columns equals 0. As a consequence, when the integration scheme (ODESolver) will call the ```projectResponse()``` or ```projectVelocity()``` the constraint will be applied, ensuring that the desired degrees of freedom remain fixed.
8 |
9 | Example of a system of size 6, with a fixed constraint at the index 5:
10 |
11 | $$
12 | \mathbf{P}=\begin{bmatrix}1&0&0&0&0&0\\0&1&0&0&0&0\\0&0&1&0&0&0\\0&0&0&1&0&0\\0&0&0&0&\mathbf{0}&0\\0&0&0&0&0&1\end{bmatrix}
13 | $$
14 |
15 | By projecting this $\mathbf{P}$ matrix on the right hand side vector we have $\mathbf{P}^Tb$. This ensures to have the projection $b[5]=0$, thus preventing any time evolution of the fifth degree of freedom. In such case, we function _projectResponse()_:
16 |
17 | ```cpp
18 | template 
19 | 
30 | 
35 |
36 |
37 |
38 | Usage
39 | -----
40 |
41 | The EulerExplicitSolver **requires** a MechanicalObject to store the state vectors. However, as explained above, no LinearSolver is needed and the EulerExplicitSolver is **only working using a [UniformMass](../../../mass/uniformmass/) or [DiagonalMass](../../../mass/diagonalmass/)**, which ensures to have a diagonal system matrix.
42 |
--------------------------------------------------------------------------------
/30_Components/45_LinearSolver/20_Direct/50_SparseLDLSolver.md:
--------------------------------------------------------------------------------
1 | SparseLDLSolver
2 | ===============
3 |
4 | This component belongs to the category of [LinearSolver](../../../../simulation-principles/system-resolution/linear-solver/). The role of the SparseLDLSolver is to solve the linear system $\mathbf{A}x=b$ assuming that the matrix $\mathbf{A}$ is symmetric and sparse.
5 |
6 |
7 | To do so, the SparseLDLSolver relies on the method of [LDL decomposition](https://en.wikipedia.org/wiki/Cholesky_decomposition#LDL_decomposition_2). The system matrix will be decomposed $\mathbf{A}=\mathbf{L}\mathbf{D}\mathbf{L}^T$, where $\mathbf{L}$ is a lower triangular matrix $\mathbf{A}$ and $\mathbf{D}$ is a diagonal matrix. This decomposition is an extension of the Cholesky decomposition which reduces its numerical inaccuracy.
8 |
9 | As a direct solver, the SparseLDLSolver computes at each simulation time step an exact solution as follows:
10 |
11 | $$
12 | \mathbf{L}\mathbf{D}\mathbf{L}^Tx=b
13 | $$
14 |
15 | Using a block forward substitution, we successively solve two triangular systems. Between those two resolutions, we need to inverse $\mathbf{D}$, which is trivial as it is a diagonal matrix that has no null value on its diagonal.
16 |
17 | $$
18 | \begin{cases}
19 | \mathbf{A}x=b \\
20 | \mathbf{A}=\mathbf{LDL^T}
21 | \end{cases}
22 | \Longleftrightarrow
23 | \begin{cases}
24 | \mathbf{L} z = b \\
25 | \mathbf{D} y = z \\
26 | \mathbf{L}^T x = y \\
27 | \end{cases}
28 | $$
29 |
30 | It is important to note that this decomposition considers that the system matrix $\mathbf{A}$ is symmetric.
31 |
32 | Note that using permutation, the SparseLDLSolver will apply fill reducing permutation on the rows and the columns of $\mathbf{A}$ in order to minimize the number of non null values in $\mathbf{L}$ . Instead of solving $\mathbf{A}x=b$, we will solve $\mathbf{(PAQ) (Q^{-1}}x) = Pb$. Moreover, $\mathbf{A}$ is symmetric, so we will use the same permutation on the rows and on the columns with $\mathbf{Q}=\mathbf{P}^T=\mathbf{P}^{-1}$. We will factorize $\tilde{\mathbf{A}} =\mathbf{PAP^T} $ and then we will solve
33 |
34 | $$
35 | \begin{cases}
36 | \tilde{\mathbf{A}} y = Pb \\
37 | \mathbf{Q}^{-1} x = y
38 | \end{cases}
39 | $$
40 |
41 | As the impact of the use of fill reducing permutations on the performances is highly influenced by the repartition of the nodes used to model an object, we advise the users to test which type of permutation is the best suited for their simulations.
42 |
43 |
44 |
45 | Sequence diagram
46 | ----------------
47 |
48 | 
49 |
50 |
51 | Usage
52 | -----
53 |
54 | The SparseLDLSolver **requires** the use (above in the scene graph) of an integration scheme, and (below in the scene graph) of a MechanicalObject storing the state information that the SparseLDLSolver will access.
55 |
56 | As a direct solver, the SparseLDLSolver might be extremely time consuming for large system. However, it will always give you an exact solution, **making the assumption that the system matrix $\mathbf{A}$ is symmetric**.
57 |
58 |
--------------------------------------------------------------------------------
/30_Components/15_Collision/10_Detection/10_Algorithm/30_NarrowPhase.md:
--------------------------------------------------------------------------------
1 | Narrow Phase Components
2 | ======================
3 |
4 | The narrow phase collision detection components are executed in a [collision pipeline](../../collisionpipeline).
5 |
6 | Introduction
7 | ============
8 |
9 | In SOFA, collision detection usually involves complex meshes (e.g. a set of triangles).
10 | For an accurate collision response, the collision detection detects which pairs of collision elements are in intersection.
11 |
12 | The naive approach would be to test every pair of collision elements.
13 | The number of tests depends on the number of objects, and the number of collision elements in each object.
14 | For performances reasons, this approach is never selected because of its quadratic complexity.
15 |
16 | Instead, the collision detection will be divided in two parts:
17 | 1. The [broad phase collision detection](../../broadphase)
18 | 2. The narrow phase collision detection
19 |
20 | The Narrow Phase
21 | ================
22 |
23 | The narrow phase is executed after the broad phase.
24 | The broad phase output is a list of collision models potentially in collision.
25 | The goal of the narrow phase is to examine the list more closely and determine if they are actually in intersection.
26 | If it is the case, it detects which elements are in intersection.
27 |
28 | Following the [DefaultPipeline](../../defaultpipeline), the output of the narrow phase is provided to the contact manager.
29 |
30 | The Implementation
31 | ------------------
32 |
33 | The narrow phase is executed in 3 functions:
34 |
35 | ```cpp
36 | /// Clear all the potentially colliding pairs detected in the previous simulation step
37 | void NarrowPhaseDetection::beginNarrowPhase()
38 | ```
39 |
40 | ```cpp
41 | /// Add a new list of potentially colliding pairs of models
42 | void NarrowPhaseDetection::addCollisionPairs(const sofa::helper::vector< std::pair
10 |
11 | All contact outputs which are outside these cones will be invalidated (even if they are below the contactDistance). Thus, only the geometrically closest contacts remain: for convex surfaces, this method even ensures to find one and only one contact point.
12 |
13 | 
14 |
15 | Degenerated cases can occur when, for instance, surfaces are perfectly parallel. If we think about configuration described below:
16 |
17 | The cones on the sides (no 1 and 3) are open with an 90 degree angle, while the middle cone (2) is closed. No contact will therefore be detected from the cone 2.
18 |
19 |
20 | 
21 |
22 | - In case our object is rigid, having the two cones exactly equal to 90 degrees may lead to instabilities: a small rotation would lead to the invalidation of one of the two corner contacts, and the object would start to oscillate. To prevent such cases, a data is available to open the cone: "coneFactor"
23 | - In case of a soft body, the LocalMinDistance would not detect the middle point as a contact since the cone is closed. The method would therefore fail to keep the object over the surface. To solve such a generated case, a data aiming at opening all existing cones is defined: "angleCone"
24 |
25 |
26 |
27 |
28 | Usage
29 | -----
30 |
31 | The MinProximityIntersection must be placed right after the CollisionPipeline and the associated Detection method (usually [BruteForce](../../algorithm/bruteforcebroadphase/)) on top the scene graph.
32 |
33 |
34 | Additional information
35 | ----------------------
36 |
37 | - collision models in the scene will have the data **proximity** corresponding to an enlargement of the collision model, i.e., value added to the alarmDistance and the contactDistance and also when building AABBs in the broad phase
38 | - a different alarmDistance and contactDistance can be specified for each CollisionModel by setting alarmDistance and contactDistance to zero and changing the proximity parameter
39 |
40 |
--------------------------------------------------------------------------------
/30_Components/55_Mass/10_UniformMass.md:
--------------------------------------------------------------------------------
1 | UniformMass
2 | ===========
3 |
4 |
5 | This component belongs to the category of [Masses](../../../simulation-principles/multi-model-representation/mass/). The UniformMass is a very **simplistic mass** component since it does not compute the volume integration of a density term. The mass is equally spread over the number of points, thus resulting in the following diagonal mass matrix:
6 |
7 | $$\mathbf{M}=\begin{bmatrix}m&0&\cdots&0\\&m&\cdots&0\\ \vdots&\vdots&\ddots&\vdots\\&0&\cdots&m\end{bmatrix}$$
8 |
9 | Each diagonal term equals the nodal mass $m=\frac{m_{\textnormal{total}}}{N}$ where $m_{\textnormal{total}}$ is the total mass of the objet and $N$ is the number of nodes of the object. Spreading the mass over the nodes without considering their connectivity results in this diagonal mass matrix $\mathbf{M}$.
10 |
11 |
12 | As all mass components, the UniformMass $\mathbf{M}$ will contribute to the main matrix $\mathbf{A}$ in the system $\mathbf{A}x=b$. Depending on the type of [LinearSolver](../../../simulation-principles/system-resolution/linear-solver/) used:
13 |
14 | - for iterative solvers, the result of the multiplication between the mass matrix $\mathbf{M}$ and an approximated solution is computed by the function:
15 |
16 | ``` cpp
17 | template 
29 |
30 |
31 | Usage
32 | -----
33 |
34 | At each simulation step and each Newton Raphson iteration, the StaticSolver **requires**:
35 |
36 | - a [LinearSolver](../../../../simulation-principles/system-resolution/linear-solver/) to solve the linear system
37 | - and a MechanicalObject to store the state vectors.
38 |
39 | A StaticSolver must be used in simulations where the dynamics has no or a negligible effect on the system. A StaticSolver would also be relevant for systems with low mass. In such case, we fall into the quasi-static analysis.
40 |
41 | In some loading configuration, applying the full forces and torques might not lead to any converging simulation. It is then relevant to go for an incremental loading, i.e. loads are applied incrementally at each simulation step $i$. This incremental loading has to be done in the associated ForceField. If you want to use this solver with Newton Raphson iterations, it is in the user's hand to make sure the external forces used in the scene (pressure, traction, etc.) only get incremented at each time step, and not at each calls to addForce (which is currently the case for most force fields).
42 |
--------------------------------------------------------------------------------
/30_Components/55_Mass/30_DiagonalMass.md:
--------------------------------------------------------------------------------
1 | DiagonalMass
2 | ============
3 |
4 | This component belongs to the category of [Masses](../../../simulation-principles/multi-model-representation/mass/). In the dynamic equation (see [Physics integration](../../../simulation-principles/multi-model-representation/physics-integration/) page), the mass density results from the first derivative in time of the momentum term. Like the MeshMatrixMass, the DiagonalMass computes the integral of this mass density over the volume of the object geometry. To do so and for any given topology (edges, triangles, quads, tetrahedra or hexahedra), the DiagonalMass integrates the mass density inside each elements and sums the mass matrix $\mathbf{M}$ in the system matrix $\mathbf{A}$.
5 |
6 | However, the DiagonalMass makes a strong simplification: it considers the mass matrix $\mathbf{M}$ as being diagonal. To build this diagonal mass matrix, the DiagonalMass relies on a numerical method called the mass lumping. It consists in summing all mass values of a line on the diagonal. This approach is already implemented in the MeshMatrixMass but the DiagonalMass proposes an optimized version of the mass lumping and extend it to edge topology.
7 |
8 | For details on the volume integration, please report to the [MeshMatrixMass](./../meshmatrixmass/) page. As demonstrated in the [MeshMatrixMass](./../meshmatrixmass/#case-of-a-linear-tetrahedron) page, in case of a topology using linear tetrahedra, the diagonal mass matrix corresponds to:
9 |
10 |
11 | $$
12 | \mathbf{M}\dot{v}=\sum_{e=0}^E \frac{\rho V_e}{4}\begin{bmatrix}1&0&0&0\\&1&0&0\\&0&1&0\\&0&0&1\\ \end{bmatrix}\begin{bmatrix}\dot{v}_1\\ \dot{v}_2\\ \dot{v}_3\\ \dot{v}_4\\ \end{bmatrix}
13 | $$
14 |
15 |
16 | By making the matrix diagonal (i.e. removing extra-diagonal terms), the lumping method removes the connectivity (neighborhood) information from the matrix. Due to this numerical approximation, the accuracy of the integration is decreased compared to the MeshMatrixMass integration. It is therefore advised to use the DiagonalMass carefully.
17 |
18 |
19 |
20 |
21 | ### API
22 |
23 | Depending on the type of [LinearSolver](../../../simulation-principles/system-resolution/linear-solver/) used:
24 |
25 | - for iterative solvers, the result of the multiplication between the mass matrix $\mathbf{M}$ and an approximated solution is computed by the function:
26 |
27 | ``` cpp
28 | template 
9 |
10 | DirectSAP corresponds to the implementation of SAP in its "direct" version, i.e. at each step it sorts all the primitives along an axis (**not checking the moving ones**) and computes overlapping pairs without saving it. But the memory used to save these primitives is created just once, the first time we add CollisionModels.
11 |
12 |
13 | ### Preliminary phase
14 |
15 | Before starting the broad phase, two steps are therefore required before the brute force detection starts:
16 |
17 | - all present collision models in the scene must be listed. This is done in the function ```void PipelineImpl::computeCollisionDetection()``` with:
18 | ```cpp
19 | root->getTreeObjects
--------------------------------------------------------------------------------