Data Fields

Links

Methods

{
  "name": "Mapping",
  "namespace": "sofa::core",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/Mapping.h",
  "doc": "Specialized interface to convert a model state of type TIn to a model state of type TOut.\nThis is basically a sofa::core::BaseMapping with given input and output types.",
  "inherits": [
    "BaseMapping"
  ],
  "templates": [
    "sofa::sofa::defaulttype::Rigid2Types, sofa::sofa::defaulttype::Rigid2Types",
    "sofa::sofa::defaulttype::Rigid2Types, sofa::sofa::defaulttype::Vec2Types",
    "sofa::sofa::defaulttype::Rigid3Types, sofa::sofa::defaulttype::Rigid3Types",
    "sofa::sofa::defaulttype::Rigid3Types, sofa::sofa::defaulttype::Vec6Types",
    "sofa::sofa::defaulttype::Vec1Types, sofa::sofa::defaulttype::Vec1Types",
    "sofa::sofa::defaulttype::Vec3Types, sofa::sofa::defaulttype::Rigid3Types"
  ],
  "data_fields": [
    {
      "name": "f_applyRestPosition",
      "type": "bool",
      "xmlname": "applyRestPosition",
      "help": "set to true to apply this mapping to restPosition at init"
    }
  ],
  "links": [
    {
      "name": "fromModel",
      "target": "State<In>",
      "kind": "single",
      "xmlname": "input",
      "help": "Input object to map"
    },
    {
      "name": "toModel",
      "target": "State<Out>",
      "kind": "single",
      "xmlname": "output",
      "help": "Output object to map"
    }
  ],
  "methods": [
    {
      "name": "setModels",
      "return_type": "void",
      "params": [
        {
          "name": "from",
          "type": "State<In> *"
        },
        {
          "name": "to",
          "type": "State<Out> *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setFrom",
      "return_type": "bool",
      "params": [
        {
          "name": "from",
          "type": "BaseState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTo",
      "return_type": "bool",
      "params": [
        {
          "name": "to",
          "type": "BaseState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setPathInputObject",
      "return_type": "void",
      "params": [
        {
          "name": "o",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setPathOutputObject",
      "return_type": "void",
      "params": [
        {
          "name": "o",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFromModel",
      "return_type": "State<In> *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getToModel",
      "return_type": "State<Out> *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFrom",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTo",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "apply",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "outPos",
          "type": "MultiVecCoordId"
        },
        {
          "name": "inPos",
          "type": "ConstMultiVecCoordId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "apply",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "out",
          "type": "OutDataVecCoord &"
        },
        {
          "name": "in",
          "type": "const InDataVecCoord &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyJ",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "outVel",
          "type": "MultiVecDerivId"
        },
        {
          "name": "inVel",
          "type": "ConstMultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyJ",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "out",
          "type": "OutDataVecDeriv &"
        },
        {
          "name": "in",
          "type": "const InDataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyJT",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "inForce",
          "type": "MultiVecDerivId"
        },
        {
          "name": "outForce",
          "type": "ConstMultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyJT",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "out",
          "type": "InDataVecDeriv &"
        },
        {
          "name": "in",
          "type": "const OutDataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyDJT",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "",
          "type": "MultiVecDerivId"
        },
        {
          "name": "",
          "type": "ConstMultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyJT",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const ConstraintParams *"
        },
        {
          "name": "inConst",
          "type": "MultiMatrixDerivId"
        },
        {
          "name": "outConst",
          "type": "ConstMultiMatrixDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyJT",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const ConstraintParams *"
        },
        {
          "name": "",
          "type": "InDataMatrixDeriv &"
        },
        {
          "name": "",
          "type": "const OutDataMatrixDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeAccFromMapping",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "outAcc",
          "type": "MultiVecDerivId"
        },
        {
          "name": "inVel",
          "type": "ConstMultiVecDerivId"
        },
        {
          "name": "inAcc",
          "type": "ConstMultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeAccFromMapping",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "",
          "type": "OutDataVecDeriv &"
        },
        {
          "name": "",
          "type": "const InDataVecDeriv &"
        },
        {
          "name": "",
          "type": "const InDataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMechFrom",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMechTo",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "createMappedMatrix",
      "return_type": "sofa::linearalgebra::BaseMatrix *",
      "params": [
        {
          "name": "state1",
          "type": "const behavior::BaseMechanicalState *"
        },
        {
          "name": "state2",
          "type": "const behavior::BaseMechanicalState *"
        },
        {
          "name": "",
          "type": "func_createMappedMatrix"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "disable",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "canCreate",
      "return_type": "bool",
      "params": [
        {
          "name": "obj",
          "type": "T *&"
        },
        {
          "name": "context",
          "type": "core::objectmodel::BaseContext *"
        },
        {
          "name": "arg",
          "type": "core::objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "shortName",
      "return_type": "int",
      "params": [
        {
          "name": "ptr",
          "type": "const T *"
        },
        {
          "name": "arg",
          "type": "objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    }
  ],
  "description": "The `Mapping` class in SOFA is designed to convert the state of one model (input) into another state (output). This conversion can be represented as a transformation matrix J, where output = J * input. The Mapping class inherits from `BaseMapping`, enabling it to handle various types of data conversions, particularly between different mechanical states such as rigid and vector types.\n\n### Role in SOFA Ecosystem\nThe role of the `Mapping` component is critical for inter-model synchronization within a simulation scene. It facilitates multi-resolution modeling, where high-resolution models can be mapped onto lower-resolution representations, or vice versa. Additionally, it allows different models to interact with each other by converting their states into compatible formats.\n\n### Interactions and API\n- **Input and Output Models**: The `Mapping` class establishes links to an input model (`fromModel`) and an output model (`toModel`). These are specified through the template parameters TIn and TOut, representing the input and output data types respectively. Methods like `setModels`, `getFromModel`, and `getToModel` manage these connections.\n\n- **Transformation Methods**: Core methods such as `apply`, `applyJ`, and `applyJT` are pure virtual functions that must be implemented in derived classes to define the specific transformation logic for positions, velocities, and forces. These transformations include applying mappings to position vectors (`out = J * in`), transforming velocity or displacement vectors, and reversing mapping for force vectors.\n\n- **Initialization**: The `init` method initializes the mapping by setting up mechanical states and propagating rest positions if needed. This ensures that the output model is appropriately initialized based on the input model's state.\n\n### Practical Usage Guidance\n- Use the `f_applyRestPosition` data field to control whether rest positions should be applied at initialization.\n- Ensure that both `fromModel` and `toModel` are correctly set up with compatible types, as verified by methods like `canCreate`, which checks if input and output attributes point to valid mechanical states of appropriate data types.\n- Implement specific mapping logic in derived classes for different types of transformations (e.g., rigid bodies, vectors).\n\n### Data Fields\n- **f_applyRestPosition**: A boolean field to indicate whether rest positions should be applied at initialization. Default is `false`.",
  "maths": "<p>The <code>Mapping</code> class in the SOFA framework is designed to convert the state of one model (input) into another state (output). This conversion can be represented as a transformation matrix $J$, where:</p>\n\n\begin{equation}\n\\text{Output} = J \\cdot \\text{Input}\n\\end{equation}\n\n<p>This class is crucial for inter-model synchronization within a simulation scene, facilitating multi-resolution modeling and interactions between different models.</p>\n\n<h3 id=\"governing-equations-and-operators\">Governing Equations and Operators</h3>\n\n<ul>\n<li><strong>Mapping Operator:</strong> The core of the <code>Mapping</code> is its ability to apply a transformation $J$ from input state vectors to output state vectors. This can be expressed in various forms:\n<ul>\n<li><em>Position Mapping:</em></li>\n\n\begin{equation}\nx_{\\text{out}} = J \\cdot x_{\\text{in}}\n\\end{equation}\n\n<li><em>Jacobian Operator for Velocities and Displacements:</em></li>\n\n\begin{equation}\nv_{\\text{out}} = J \\cdot v_{\\text{in}}\n\\end{equation}\n\n<li><em>Adjoint Jacobian Operator for Forces:</em></li>\n\n\begin{equation}\nf_{\\text{out}} += J^T \\cdot f_{\\text{in}}\n\\end{equation}\n</ul>\n</li>\n<li><strong>Damping and Geometric Stiffness:</strong> The <code>Mapping</code> can also contribute to geometric stiffness, which accounts for the change in force due to the nonlinearity of the mapping. This is computed as:\n\n\begin{equation}\nf_p += dJ^T \\cdot f_c\n\\end{equation}\n\n<p>where $dJ$ represents the derivative of the transformation matrix with respect to displacements.</p>\n</li>\n<li><strong>Acceleration Transformation:</strong> The acceleration in the output model can be derived from the input model's velocity and acceleration as follows:\n\n\begin{equation}\na_{\\text{out}} = J \\cdot a_{\\text{in}} + dJ \\cdot v_{\\text{in}}\n\\end{equation}\n</li>\n</ul>\n\n<h3 id=\"constitutive-and-kinematic-laws\">Constitutive and Kinematic Laws</h3>\n\n<p>The <code>Mapping</code> class can handle different types of mappings, including:</p>\n\n<ul>\n<li><strong>Rigid Transformations:</strong> Mapping rigid body states to other rigid or vector representations.</li>\n<li><strong>Vector-to-Vector Mappings:</strong> Converting between various vector data types (e.g., 1D, 2D, and 3D vectors).</li>\n</ul>\n\n<h3 id=\"role-in-the-global-fem-pipeline\">Role in the Global FEM Pipeline</h3>\n\n<ul>\n<li><strong>Assembly:</strong> The <code>Mapping</code> class facilitates assembly of global system matrices and forces by converting states between different models.</li>\n<li><strong>Time Integration:</strong> It ensures consistency during time integration by transforming velocities, positions, and accelerations.</li>\n<li><strong>Nonlinear Solve:</strong> Mapping operations are used to project constraints and update state variables in nonlinear solvers.</li>\n</ul>\n\n<h3 id=\"numerical-methods-and-discretization\">Numerical Methods and Discretization Choices</h3>\n\n<ul>\n<li><strong>Jacobian Matrix:</strong> The <code>Mapping</code> class computes the Jacobian matrix $J$ that represents the local linear approximation of the mapping function.</li>\n<li><strong>Adjoint Jacobian Matrix:</strong> It also computes the adjoint Jacobian matrix $J^T$, which is used in force transformations and constraint handling.</li>\n</ul>\n\n<h3 id=\"fit-into-the-broader-variational-lagrangian-mechanics-framework\">Fit into the Broader Variational / Lagrangian Mechanics Framework</h3>\n\n<ul>\n<li><strong>Variational Consistency:</strong> The mapping operations ensure that variational principles are respected, meaning the transformed states preserve physical consistency across different models.</li>\n<li><strong>Mechanical State Propagation:</strong> By applying mappings to mechanical states (positions, velocities, accelerations), it maintains consistent dynamics between interconnected models within the simulation scene graph.</li>\n</ul>",
  "abstract": "The `Mapping` class converts the state of one model into another, enabling inter-model synchronization within simulations through transformation matrices.",
  "sheet": "# Mapping\n\n## Overview\nThe `Mapping` component in SOFA is designed to convert the state of one model (input) into another state (output). This conversion can be represented as a transformation matrix $J$, where output = J * input. The class facilitates inter-model synchronization within simulations by defining specific transformation logic through methods such as `apply`, `applyJ`, and `applyJT`. It supports various data conversions, particularly for mechanical states like rigid bodies and vectors.\n\n## Mathematical Model\nThe core of the `Mapping` is its ability to apply a transformation $J$ from input state vectors to output state vectors. This can be expressed in several forms:\n\n- **Position Mapping**:\n\\[ x_{\text{out}} = J \times x_{\text{in}} \\]\n\n- **Jacobian Operator for Velocities and Displacements**:\n\\[ v_{\text{out}} = J \times v_{\text{in}} \\]\n\n- **Adjoint Jacobian Operator for Forces**:\n\\[ f_{\text{out}} += J^T \times f_{\text{in}} \\]\n\nAdditionally, the `Mapping` can contribute to geometric stiffness and acceleration transformation as follows:\n\n- **Geometric Stiffness Contribution**:\n\\[ f_p += dJ^T \times f_c \\]\nwhere $dJ$ represents the derivative of the transformation matrix with respect to displacements.\n\n- **Acceleration Transformation**:\n\\[ a_{\text{out}} = J \times a_{\text{in}} + dJ \times v_{\text{in}} \\]\n\n## Parameters and Data\nThe `Mapping` class includes the following significant data fields:\n\n- **f_applyRestPosition**: A boolean field to indicate whether rest positions should be applied at initialization. Default is `false`."
}