ConstantForceField
The ConstantForceField is a force field component in the Sofa physics engine that applies constant forces to specified degrees of freedom (DOFs) within a simulated object or system.
- abstract
- The ConstantForceField applies constant forces to specified degrees of freedom using predefined vectors or a single summed force distributed across points.
- sheet
- <h1>ConstantForceField</h1> <h2>Overview</h2> <p>The <strong>ConstantForceField</strong> is a component in the Sofa physics engine that applies constant forces to specified degrees of freedom (DOFs). It supports three methods for defining these forces: single force vector, individual forces per point, and total summed force distributed equally. The component links to a topology container to specify the DOFs.</p> <h2>Mathematical Model</h2> <p>The mathematical formulation involves applying constant forces directly without any dynamic changes:</p> <ul> <li><strong>Single Force Vector:</strong> If \\( \mathbf{f} \\), a single force vector, is provided and there are \\( N \\) indices: \[ \mathbf{f_i} = \frac{1}{N} \sum_{j=0}^{N} \mathbf{f} \]</li> <li><strong>Forces Vector per Point:</strong> If individual forces are specified for each index, the force applied at a given index \\( i \\) is denoted by \\( \mathbf{F_i} \\): \[ \mathbf{F} = [\mathbf{f_1}, \mathbf{f_2}, \dots , \mathbf{f_N}] \]</li> </ul> <h2>Parameters and Data</h2> <table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>d_indexFromEnd</code></td> <td><code>bool</code></td> <td>Indicates if DOF indices are numbered from the end of the MState DOFs vector (default=false).</td> </tr> <tr> <td><code>d_forces</code></td> <td><code>VecDeriv</code></td> <td>Vector containing the force amplitude applied at each node.</td> </tr> <tr> <td><code>d_totalForce</code></td> <td><code>Deriv</code></td> <td>Total force for all points, distributed uniformly over points.</td> </tr> <tr> <td><code>d_showArrowSize</code></td> <td><code>SReal</code></td> <td>Size of the drawn arrows (0->no arrows, sign->direction of drawing. Default=0).</td> </tr> <tr> <td><code>d_color</code></td> <td><code>sofa::type::RGBAColor</code></td> <td>Color for object display (default: [0.2, 0.9, 0.3, 1.0]).</td> </tr> </tbody> </table> <h2>Dependencies and Connections</h2> <p>The component requires a link to the topology container (<code>BaseMeshTopology</code>) to specify the DOFs.</p>
- description
- The ConstantForceField is a force field component in the Sofa physics engine that applies constant forces to specified degrees of freedom (DOFs) within a simulated object or system.
- parameters
-
- {'name': 'd_indices', 'type': 'SetIndex', 'description': 'Indices of the points on which the forces are applied.'}
- {'name': 'd_indexFromEnd', 'type': 'Data<bool>', 'description': 'If true, concerned DOFs indices are numbered from the end of the MState DOFs vector. Default is false.'}
- {'name': 'd_forces', 'type': 'Data<VecDeriv>', 'description': 'Per-point forces to be applied at each specified index. This data overrides d_totalForce if both are defined.'}
- {'name': 'd_totalForce', 'type': 'Data<Deriv>', 'description': 'Sum of the forces applied at each point. If per-point forces (d_forces) are not specified, this force is equally distributed among all points in d_indices.'}
- {'name': 'd_showArrowSize', 'type': 'Data<SReal>', 'description': 'Size for drawing the force arrows during visualization. The sign changes direction; 0 means no arrow is drawn.'}
- {'name': 'd_color', 'type': 'Data<RGBAColor>', 'description': 'Color used to display the forces graphically in the simulation environment.'}
- methods
-
- {'name': 'init()', 'parameters': [], 'return_type': 'void', 'description': 'Initializes the component and its internal state.'}
- {'name': 'addForce()', 'parameters': ['core::MechanicalParams*', 'DataVecDeriv&', 'const DataVecCoord&', 'const DataVecDeriv&'], 'return_type': 'void', 'description': "Adds the constant forces to the system's force vector."}
- {'name': 'addDForce()', 'parameters': ['core::MechanicalParams*', 'DataVecDeriv&', 'const DataVecDeriv&'], 'return_type': 'void', 'description': 'Does nothing, as constant forces have no derivative (they are not influenced by changes in position or velocity).'}
- {'name': 'addKToMatrix()', 'parameters': ['sofa::linearalgebra::BaseMatrix*', 'SReal', 'unsigned int&'], 'return_type': 'void', 'description': 'Does nothing, as constant forces do not contribute to the stiffness matrix.'}
- {'name': 'getPotentialEnergy()', 'parameters': ['const core::MechanicalParams*', 'const DataVecCoord&'], 'return_type': 'SReal', 'description': 'Returns the potential energy associated with the applied constant forces.'}
- {'name': 'draw()', 'parameters': ['core::visual::VisualParams*'], 'return_type': 'void', 'description': 'Renders the force field graphically based on d_showArrowSize and d_color settings.'}
- {'name': 'setForce()', 'parameters': ['unsigned int', 'const Deriv&'], 'return_type': 'void', 'description': 'Sets a specific force to be applied at a given index.'}
- notes
-
- The ConstantForceField is useful for simulating scenarios where constant external forces need to be applied, such as gravity or wind.
- It can work with various types of data (e.g., Vec3Types for 3D vectors), making it versatile for different simulation needs.
- maths
- ## Mathematical and Physical Description of the ConstantForceField Component ### Overview The **ConstantForceField** is a force field component used in the Simulation Open-Framework Architecture (Sofa) to apply constant forces to specified degrees of freedom (DOFs). It allows users to define static force vectors that are consistently applied throughout the simulation, providing a means to simulate external loads or constraints. ### Degrees of Freedom (DOFs) The DOFs refer to the independent displacements and rotations that can occur at individual points within the simulated object. The ConstantForceField applies these forces either directly on specified indices or through predefined vectors associated with each point. ### Forces Application Mechanism The component supports three main methods for defining constant forces: 1. **Single Force Vector**: A single force vector applied uniformly to all selected DOFs. 2. **Forces Vector per Point**: Individual force vectors defined for each specified index, allowing localized application of different forces. 3. **Total Summed Force**: The total sum of forces distributed equally across the indices if no individual forces are explicitly given. ### Mathematical Formulation Let \(\mathbf{f}\) be a vector representing the applied force in a 3D space, where \(\mathbf{f} = (f_x, f_y, f_z)\). The force is applied to each specified DOF indexed by \(i\). - **Single Force Vector**: If \(\mathbf{f}\) is provided as the total summed force and there are \(N\) indices: \[ \mathbf{f_i} = \frac{1}{N} \sum_{j=0}^{N} \mathbf{f} \] - **Forces Vector per Point**: If individual forces are specified for each index, the force applied at a given index \(i\) is denoted by \(\mathbf{F_i}\): \[ \mathbf{F} = [\mathbf{f_1}, \mathbf{f_2}, \dots , \mathbf{f_N}] \] ### Potential Energy The potential energy associated with a constant force field is generally not considered, as it does not vary over time. Therefore, the potential energy in this context is assumed to be zero or negligible. \[ U = 0 \] ### Force Contribution Calculation During each simulation step, the total force contribution \(\mathbf{F_{total}}\) for a specified DOF index is computed and added to the forces acting on that point. The process involves iterating through the indices and applying the corresponding force vector. ### Example Usage The component can be used in various scenarios such as simulating gravitational forces, external loads on structures, or any scenario where constant forces need to be applied over time. ```cpp // Example of setting up a ConstantForceField in Sofa ConstantForceField<Vec3Types> constantForce; constantForce.setIndices(indices); // Specify indices for DOFs constantForce.setForces(forcesVector); // Set individual force vectors per index constantForce.init(); ``` ### Limitations and Considerations - The forces are static, meaning they do not change over time. - Individual points must be specified explicitly; otherwise, the force is uniformly distributed across all selected indices. - This component does not account for dynamic changes in force application or varying magnitudes.
{
"name": "ConstantForceField",
"main": {
"name": "ConstantForceField",
"namespace": "sofa::component::mechanicalload",
"module": "Sofa.Component.MechanicalLoad",
"include": "sofa/component/mechanicalload/ConstantForceField.h",
"doc": "Constant forces applied to given degrees of freedom.\n\nApply constant forces to given degrees of freedom.",
"inherits": [
"ForceField"
],
"templates": [
"sofa::defaulttype::Rigid2Types",
"sofa::defaulttype::Rigid3Types",
"sofa::defaulttype::Vec3Types"
],
"data_fields": [
{
"name": "d_indexFromEnd",
"type": "bool",
"xmlname": "indexFromEnd",
"help": "Concerned DOFs indices are numbered from the end of the MState DOFs vector. (default=false)"
},
{
"name": "d_forces",
"type": "VecDeriv",
"xmlname": "forces",
"help": "vector containing the force amplitude applied at each node"
},
{
"name": "d_totalForce",
"type": "Deriv",
"xmlname": "totalForce",
"help": "total force for all points, will be distributed uniformly over points"
},
{
"name": "d_showArrowSize",
"type": "SReal",
"xmlname": "showArrowSize",
"help": "Size of the drawn arrows (0->no arrows, sign->direction of drawing. (default=0)"
},
{
"name": "d_color",
"type": "sofa::type::RGBAColor",
"xmlname": "showColor",
"help": "Color for object display (default: [0.2,0.9,0.3,1.0])"
}
],
"links": [
{
"name": "l_topology",
"target": "BaseMeshTopology",
"kind": "single",
"xmlname": "topology",
"help": "link to the topology container"
}
],
"methods": [
{
"name": "init",
"return_type": "void",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addForce",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const core::MechanicalParams *"
},
{
"name": "f",
"type": "DataVecDeriv &"
},
{
"name": "x",
"type": "const DataVecCoord &"
},
{
"name": "v",
"type": "const DataVecDeriv &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addDForce",
"return_type": "void",
"params": [
{
"name": "mparams",
"type": "const core::MechanicalParams *"
},
{
"name": "d_df",
"type": "DataVecDeriv &"
},
{
"name": "d_dx",
"type": "const DataVecDeriv &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addKToMatrix",
"return_type": "void",
"params": [
{
"name": "mat",
"type": "sofa::linearalgebra::BaseMatrix *"
},
{
"name": "k",
"type": "SReal"
},
{
"name": "offset",
"type": "unsigned int &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addKToMatrix",
"return_type": "void",
"params": [
{
"name": "",
"type": "const sofa::core::behavior::MultiMatrixAccessor *"
},
{
"name": "",
"type": "SReal"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "buildStiffnessMatrix",
"return_type": "void",
"params": [
{
"name": "matrix",
"type": "core::behavior::StiffnessMatrix *"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPotentialEnergy",
"return_type": "SReal",
"params": [
{
"name": "params",
"type": "const core::MechanicalParams *"
},
{
"name": "x",
"type": "const DataVecCoord &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "draw",
"return_type": "void",
"params": [
{
"name": "vparams",
"type": "const core::visual::VisualParams *"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setForce",
"return_type": "void",
"params": [
{
"name": "i",
"type": "unsigned int"
},
{
"name": "force",
"type": "const Deriv &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "buildDampingMatrix",
"return_type": "void",
"params": [
{
"name": "",
"type": "core::behavior::DampingMatrix *"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "updateFromIndices",
"return_type": "sofa::core::objectmodel::ComponentState",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "updateFromForcesVector",
"return_type": "sofa::core::objectmodel::ComponentState",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "updateFromTotalForce",
"return_type": "sofa::core::objectmodel::ComponentState",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "checkForce",
"return_type": "bool",
"params": [
{
"name": "force",
"type": "const Deriv &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "checkForces",
"return_type": "bool",
"params": [
{
"name": "forces",
"type": "const VecDeriv &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "computeForceFromSingleForce",
"return_type": "sofa::core::objectmodel::ComponentState",
"params": [
{
"name": "singleForce",
"type": "const Deriv"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "computeForceFromForcesVector",
"return_type": "sofa::core::objectmodel::ComponentState",
"params": [
{
"name": "forces",
"type": "const VecDeriv &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "computeForceFromTotalForce",
"return_type": "sofa::core::objectmodel::ComponentState",
"params": [
{
"name": "totalForce",
"type": "const Deriv &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
}
]
},
"desc": {
"description": "The ConstantForceField is a force field component in the Sofa physics engine that applies constant forces to specified degrees of freedom (DOFs) within a simulated object or system.",
"parameters": [
{
"name": "d_indices",
"type": "SetIndex",
"description": "Indices of the points on which the forces are applied."
},
{
"name": "d_indexFromEnd",
"type": "Data<bool>",
"description": "If true, concerned DOFs indices are numbered from the end of the MState DOFs vector. Default is false."
},
{
"name": "d_forces",
"type": "Data<VecDeriv>",
"description": "Per-point forces to be applied at each specified index. This data overrides d_totalForce if both are defined."
},
{
"name": "d_totalForce",
"type": "Data<Deriv>",
"description": "Sum of the forces applied at each point. If per-point forces (d_forces) are not specified, this force is equally distributed among all points in d_indices."
},
{
"name": "d_showArrowSize",
"type": "Data<SReal>",
"description": "Size for drawing the force arrows during visualization. The sign changes direction; 0 means no arrow is drawn."
},
{
"name": "d_color",
"type": "Data<RGBAColor>",
"description": "Color used to display the forces graphically in the simulation environment."
}
],
"methods": [
{
"name": "init()",
"parameters": [],
"return_type": "void",
"description": "Initializes the component and its internal state."
},
{
"name": "addForce()",
"parameters": [
"core::MechanicalParams*",
"DataVecDeriv&",
"const DataVecCoord&",
"const DataVecDeriv&"
],
"return_type": "void",
"description": "Adds the constant forces to the system's force vector."
},
{
"name": "addDForce()",
"parameters": [
"core::MechanicalParams*",
"DataVecDeriv&",
"const DataVecDeriv&"
],
"return_type": "void",
"description": "Does nothing, as constant forces have no derivative (they are not influenced by changes in position or velocity)."
},
{
"name": "addKToMatrix()",
"parameters": [
"sofa::linearalgebra::BaseMatrix*",
"SReal",
"unsigned int&"
],
"return_type": "void",
"description": "Does nothing, as constant forces do not contribute to the stiffness matrix."
},
{
"name": "getPotentialEnergy()",
"parameters": [
"const core::MechanicalParams*",
"const DataVecCoord&"
],
"return_type": "SReal",
"description": "Returns the potential energy associated with the applied constant forces."
},
{
"name": "draw()",
"parameters": [
"core::visual::VisualParams*"
],
"return_type": "void",
"description": "Renders the force field graphically based on d_showArrowSize and d_color settings."
},
{
"name": "setForce()",
"parameters": [
"unsigned int",
"const Deriv&"
],
"return_type": "void",
"description": "Sets a specific force to be applied at a given index."
}
],
"notes": [
"The ConstantForceField is useful for simulating scenarios where constant external forces need to be applied, such as gravity or wind.",
"It can work with various types of data (e.g., Vec3Types for 3D vectors), making it versatile for different simulation needs."
]
},
"maths": {
"maths": "## Mathematical and Physical Description of the ConstantForceField Component\n\n### Overview\nThe **ConstantForceField** is a force field component used in the Simulation Open-Framework Architecture (Sofa) to apply constant forces to specified degrees of freedom (DOFs). It allows users to define static force vectors that are consistently applied throughout the simulation, providing a means to simulate external loads or constraints.\n\n### Degrees of Freedom (DOFs)\nThe DOFs refer to the independent displacements and rotations that can occur at individual points within the simulated object. The ConstantForceField applies these forces either directly on specified indices or through predefined vectors associated with each point.\n\n### Forces Application Mechanism\nThe component supports three main methods for defining constant forces:\n1. **Single Force Vector**: A single force vector applied uniformly to all selected DOFs.\n2. **Forces Vector per Point**: Individual force vectors defined for each specified index, allowing localized application of different forces.\n3. **Total Summed Force**: The total sum of forces distributed equally across the indices if no individual forces are explicitly given.\n\n### Mathematical Formulation\nLet \\(\\mathbf{f}\\) be a vector representing the applied force in a 3D space, where \\(\\mathbf{f} = (f_x, f_y, f_z)\\). The force is applied to each specified DOF indexed by \\(i\\).\n- **Single Force Vector**: If \\(\\mathbf{f}\\) is provided as the total summed force and there are \\(N\\) indices:\n \n \\[ \\mathbf{f_i} = \\frac{1}{N} \\sum_{j=0}^{N} \\mathbf{f} \\]\n\n- **Forces Vector per Point**: If individual forces are specified for each index, the force applied at a given index \\(i\\) is denoted by \\(\\mathbf{F_i}\\):\n \n \\[ \\mathbf{F} = [\\mathbf{f_1}, \\mathbf{f_2}, \\dots , \\mathbf{f_N}] \\]\n\n### Potential Energy\nThe potential energy associated with a constant force field is generally not considered, as it does not vary over time. Therefore, the potential energy in this context is assumed to be zero or negligible.\n\n\\[ U = 0 \\]\n\n### Force Contribution Calculation\nDuring each simulation step, the total force contribution \\(\\mathbf{F_{total}}\\) for a specified DOF index is computed and added to the forces acting on that point. The process involves iterating through the indices and applying the corresponding force vector.\n\n### Example Usage\nThe component can be used in various scenarios such as simulating gravitational forces, external loads on structures, or any scenario where constant forces need to be applied over time.\n\n```cpp\n// Example of setting up a ConstantForceField in Sofa\nConstantForceField<Vec3Types> constantForce;\nconstantForce.setIndices(indices); // Specify indices for DOFs\nconstantForce.setForces(forcesVector); // Set individual force vectors per index\nconstantForce.init();\n```\n\n### Limitations and Considerations\n- The forces are static, meaning they do not change over time.\n- Individual points must be specified explicitly; otherwise, the force is uniformly distributed across all selected indices.\n- This component does not account for dynamic changes in force application or varying magnitudes.\n"
},
"summary": {
"abstract": "The ConstantForceField applies constant forces to specified degrees of freedom using predefined vectors or a single summed force distributed across points.",
"sheet": "<h1>ConstantForceField</h1>\n\n<h2>Overview</h2>\n<p>The <strong>ConstantForceField</strong> is a component in the Sofa physics engine that applies constant forces to specified degrees of freedom (DOFs). It supports three methods for defining these forces: single force vector, individual forces per point, and total summed force distributed equally. The component links to a topology container to specify the DOFs.</p>\n\n<h2>Mathematical Model</h2>\n<p>The mathematical formulation involves applying constant forces directly without any dynamic changes:</p>\n<ul>\n<li><strong>Single Force Vector:</strong> If \\\\( \\mathbf{f} \\\\), a single force vector, is provided and there are \\\\( N \\\\) indices:\n\\[ \\mathbf{f_i} = \\frac{1}{N} \\sum_{j=0}^{N} \\mathbf{f} \\]</li>\n<li><strong>Forces Vector per Point:</strong> If individual forces are specified for each index, the force applied at a given index \\\\( i \\\\) is denoted by \\\\( \\mathbf{F_i} \\\\):\n\\[ \\mathbf{F} = [\\mathbf{f_1}, \\mathbf{f_2}, \\dots , \\mathbf{f_N}] \\]</li>\n</ul>\n\n<h2>Parameters and Data</h2>\n<table>\n<thead>\n<tr>\n<th>Name</th>\n<th>Type</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>d_indexFromEnd</code></td>\n<td><code>bool</code></td>\n<td>Indicates if DOF indices are numbered from the end of the MState DOFs vector (default=false).</td>\n</tr>\n<tr>\n<td><code>d_forces</code></td>\n<td><code>VecDeriv</code></td>\n<td>Vector containing the force amplitude applied at each node.</td>\n</tr>\n<tr>\n<td><code>d_totalForce</code></td>\n<td><code>Deriv</code></td>\n<td>Total force for all points, distributed uniformly over points.</td>\n</tr>\n<tr>\n<td><code>d_showArrowSize</code></td>\n<td><code>SReal</code></td>\n<td>Size of the drawn arrows (0->no arrows, sign->direction of drawing. Default=0).</td>\n</tr>\n<tr>\n<td><code>d_color</code></td>\n<td><code>sofa::type::RGBAColor</code></td>\n<td>Color for object display (default: [0.2, 0.9, 0.3, 1.0]).</td>\n</tr>\n</tbody>\n</table>\n\n<h2>Dependencies and Connections</h2>\n<p>The component requires a link to the topology container (<code>BaseMeshTopology</code>) to specify the DOFs.</p>"
}
}