MultiMapping

sofa::core::MultiMapping

BaseMapping

Doc (from source)

Specialized interface to describe many to many mapping. All the input must have the same type, and all the output must have the same type. See also class Multi2Mapping.

Abstract (AI generated)

`MultiMapping` handles many-to-many mappings between input and output models in SOFA, enabling consistent state updates across different representations within the simulation scene graph.

Metadata

module

Sofa.framework.Core

namespace

sofa::core

include

sofa/core/MultiMapping.h

inherits

BaseMapping

templates

sofa::sofa::defaulttype::Rigid3Types, sofa::sofa::defaulttype::Rigid3Types
sofa::sofa::defaulttype::Rigid3Types, sofa::sofa::defaulttype::Vec1Types
sofa::sofa::defaulttype::Vec1Types, sofa::sofa::defaulttype::Vec1Types

description

Governing Equations and Operators

The MultiMapping component in the SOFA framework is designed to handle many-to-many mappings between input and output models. It serves as a generalized interface for applying mappings such as position transformations, velocity transformations, and force transformations.

Mappings Implemented or Contributed To

The MultiMapping component implements the following operators:

Position Mapping (apply): This operator maps positions from input models to output models. Mathematically, if \(J\) is the mapping matrix, then this method computes:

\[ out = J imes in \]

Velocity Mapping (applyJ): This operator maps velocities from input models to output models. The tangent operator \(J\), which is the linear approximation of the mapping, is used:

\[ out = J imes in \]

Force Mapping (applyJT): This operator maps forces from input models to output models. The transpose of the tangent operator \(J^T\) is used:

\[ out += J^T imes in \]

Constitutive and Kinematic Laws

The MultiMapping component itself does not define any specific constitutive laws or strain measures. Instead, it is a generic framework for applying mappings based on the type of mapping implemented by derived classes.

Role in Global FEM Pipeline

In the broader context of the FEM simulation pipeline:

Assembly Phase: The MultiMapping is involved in assembling forces and positions between multiple input models and output models.
Mappings: It ensures that data from one set of models (e.g., high-resolution) can be projected onto another set of models (e.g., low-resolution), preserving consistency across different representations within the simulation scene graph.
Time Integration: The mappings are applied during time integration steps to ensure consistent state updates.

Numerical Methods and Discretization Choices

The MultiMapping component does not define specific numerical methods or discretization choices. Instead, it provides a framework for derived classes to implement their own mappings, which can include linear or nonlinear transformations as needed.

Fit into Variational / Lagrangian Mechanics Framework

The MultiMapping component fits into the broader variational and Lagrangian mechanics framework by enabling consistent state updates across different models within a simulation scene graph. The mappings it applies (position, velocity, force) can be seen as part of the larger process of preserving mechanical invariants and ensuring that physical consistency is maintained throughout the simulation.

In summary, MultiMapping provides a flexible mechanism for synchronizing multiple input models with output models through various mappings, which are crucial for maintaining consistency across different representations within complex simulations.

Data Fields

Name	Type	Default	Help
`f_applyRestPosition`	bool		set to true to apply this mapping to restPosition at init

Methods

void addInputModel (BaseState * model, const int & path)

void addOutputModel (BaseState * model, const int & path)

const VecFromModels & getFromModels ()

const VecToModels & getToModels ()

int getFrom ()

int getTo ()

int getMechFrom ()

int getMechTo ()

void apply (const MechanicalParams * mparams, MultiVecCoordId outPos, ConstMultiVecCoordId inPos) virtual

void apply (const MechanicalParams * mparams, const int & dataVecOutPos, const int & dataVecInPos) virtual

void applyJ (const MechanicalParams * mparams, MultiVecDerivId outVel, ConstMultiVecDerivId inVel) virtual

void applyJ (const MechanicalParams * mparams, const int & dataVecOutVel, const int & dataVecInVel) virtual

void applyJT (const MechanicalParams * mparams, MultiVecDerivId inForce, ConstMultiVecDerivId outForce) virtual

void applyJT (const MechanicalParams * mparams, const int & dataVecOutForce, const int & dataVecInForce) virtual

void applyJT (const ConstraintParams * cparams, MultiMatrixDerivId inConst, ConstMultiMatrixDerivId outConst) virtual

void applyJT (const ConstraintParams * , const int & , const int & ) virtual

void computeAccFromMapping (const MechanicalParams * mparams, MultiVecDerivId outAcc, ConstMultiVecDerivId inVel, ConstMultiVecDerivId inAcc) virtual

void computeAccFromMapping (const MechanicalParams * , const int & , const int & , const int & ) virtual

void init () virtual

void disable () virtual

int shortName (const T * ptr, objectmodel::BaseObjectDescription * arg)

bool canCreate (T *& obj, core::objectmodel::BaseContext * context, core::objectmodel::BaseObjectDescription * arg)

void getVecInCoord (const MultiVecCoordId id, int & v)

void getConstVecInCoord (const ConstMultiVecCoordId id, int & v)

void getVecInDeriv (const MultiVecDerivId id, int & v)

void getConstVecInDeriv (const ConstMultiVecDerivId id, int & v)

void getMatInDeriv (const MultiMatrixDerivId id, int & v)

void getConstMatInDeriv (const ConstMultiMatrixDerivId id, int & v)

void getVecOutCoord (const MultiVecCoordId id, int & v)

void getConstVecOutCoord (const ConstMultiVecCoordId id, int & v)

void getVecOutDeriv (const MultiVecDerivId id, int & v)

void getConstVecOutDeriv (const ConstMultiVecDerivId id, int & v)

void getMatOutDeriv (const MultiMatrixDerivId id, int & v)

void getConstMatOutDeriv (const ConstMultiMatrixDerivId id, int & v)

{
  "name": "MultiMapping",
  "namespace": "sofa::core",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/MultiMapping.h",
  "doc": "Specialized interface to describe many to many mapping.\n  All the input must have the same type, and all the output must have the same type. See also class Multi2Mapping.",
  "inherits": [
    "BaseMapping"
  ],
  "templates": [
    "sofa::sofa::defaulttype::Rigid3Types, sofa::sofa::defaulttype::Rigid3Types",
    "sofa::sofa::defaulttype::Rigid3Types, sofa::sofa::defaulttype::Vec1Types",
    "sofa::sofa::defaulttype::Vec1Types, sofa::sofa::defaulttype::Vec1Types"
  ],
  "data_fields": [
    {
      "name": "f_applyRestPosition",
      "type": "bool",
      "xmlname": "applyRestPosition",
      "help": "set to true to apply this mapping to restPosition at init"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "addInputModel",
      "return_type": "void",
      "params": [
        {
          "name": "model",
          "type": "BaseState *"
        },
        {
          "name": "path",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addOutputModel",
      "return_type": "void",
      "params": [
        {
          "name": "model",
          "type": "BaseState *"
        },
        {
          "name": "path",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFromModels",
      "return_type": "const VecFromModels &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getToModels",
      "return_type": "const VecToModels &",
      "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": "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": "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": "dataVecOutPos",
          "type": "const int &"
        },
        {
          "name": "dataVecInPos",
          "type": "const int &"
        }
      ],
      "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": "dataVecOutVel",
          "type": "const int &"
        },
        {
          "name": "dataVecInVel",
          "type": "const int &"
        }
      ],
      "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": "dataVecOutForce",
          "type": "const int &"
        },
        {
          "name": "dataVecInForce",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "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": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "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": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "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": "disable",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "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"
    },
    {
      "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": "getVecInCoord",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const MultiVecCoordId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getConstVecInCoord",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const ConstMultiVecCoordId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getVecInDeriv",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const MultiVecDerivId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getConstVecInDeriv",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const ConstMultiVecDerivId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getMatInDeriv",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const MultiMatrixDerivId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getConstMatInDeriv",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const ConstMultiMatrixDerivId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getVecOutCoord",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const MultiVecCoordId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getConstVecOutCoord",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const ConstMultiVecCoordId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getVecOutDeriv",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const MultiVecDerivId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getConstVecOutDeriv",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const ConstMultiVecDerivId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getMatOutDeriv",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const MultiMatrixDerivId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getConstMatOutDeriv",
      "return_type": "void",
      "params": [
        {
          "name": "id",
          "type": "const ConstMultiMatrixDerivId"
        },
        {
          "name": "v",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `MultiMapping` component in the SOFA framework specializes in describing many-to-many mappings where all input models must have the same type, and all output models also share the same type. This class inherits from `BaseMapping`, which is an essential part of SOFA's architecture for handling mappings between different representations or states within a simulation scene graph.\n\n**Role and Purpose:**\nThe primary role of `MultiMapping` is to synchronize multiple input models with multiple output models by applying mapping operations such as position, velocity, and force transformations. This component enables complex interactions and data synchronization across various parts of the simulation, facilitating multi-resolution or reduced-order modeling scenarios where different representations need to be consistently updated.\n\n**Interactions:**\nThe `MultiMapping` interacts extensively with other SOFA components through its API, particularly those involved in mechanical state management (e.g., `State`, `BaseMechanicalState`). Key interactions include:\n- Adding input and output models using the `addInputModel` and `addOutputModel` methods.\n- Retrieving model lists through `getFromModels` and `getToModels`.\n- Applying mappings through virtual methods like `apply`, `applyJ`, and `applyJT`, which are overridden by derived classes to implement specific mapping logic.\n\n**Practical Usage:**\nThe component can be used to synchronize multiple models (e.g., different representations of a deformable object) within the same scene. Users must ensure that all input models have compatible types with the output models. The `f_applyRestPosition` data field allows applying this mapping to rest positions at initialization if set to true.\n\n**Data Fields:**\nThe only public data field is:\n- **applyRestPosition**: A boolean flag indicating whether the mapping should be applied to rest positions during initialization.",
  "maths": "<h2>Governing Equations and Operators</h2>\n\n<p>The <code>MultiMapping</code> component in the SOFA framework is designed to handle many-to-many mappings between input and output models. It serves as a generalized interface for applying mappings such as position transformations, velocity transformations, and force transformations.</p>\n\n<h3>Mappings Implemented or Contributed To</h3>\n\n<p>The <code>MultiMapping</code> component implements the following operators:</p>\n<ul>\n<li><strong>Position Mapping (apply)</strong>: This operator maps positions from input models to output models. Mathematically, if \\(J\\) is the mapping matrix, then this method computes:</li>\n</ul>\n\n\\[ out = J \times in \\]\n\n<ul>\n<li><strong>Velocity Mapping (applyJ)</strong>: This operator maps velocities from input models to output models. The tangent operator \\(J\\), which is the linear approximation of the mapping, is used:</li>\n</ul>\n\n\\[ out = J \times in \\]\n\n<ul>\n<li><strong>Force Mapping (applyJT)</strong>: This operator maps forces from input models to output models. The transpose of the tangent operator \\(J^T\\) is used:</li>\n</ul>\n\n\\[ out += J^T \times in \\]\n\n<h3>Constitutive and Kinematic Laws</h3>\n\n<p>The <code>MultiMapping</code> component itself does not define any specific constitutive laws or strain measures. Instead, it is a generic framework for applying mappings based on the type of mapping implemented by derived classes.</p>\n\n<h3>Role in Global FEM Pipeline</h3>\n\n<p>In the broader context of the FEM simulation pipeline:</p>\n<ul>\n<li><strong>Assembly Phase</strong>: The <code>MultiMapping</code> is involved in assembling forces and positions between multiple input models and output models.</li>\n<li><strong>Mappings</strong>: It ensures that data from one set of models (e.g., high-resolution) can be projected onto another set of models (e.g., low-resolution), preserving consistency across different representations within the simulation scene graph.</li>\n<li><strong>Time Integration</strong>: The mappings are applied during time integration steps to ensure consistent state updates.</li>\n</ul>\n\n<h3>Numerical Methods and Discretization Choices</h3>\n\n<p>The <code>MultiMapping</code> component does not define specific numerical methods or discretization choices. Instead, it provides a framework for derived classes to implement their own mappings, which can include linear or nonlinear transformations as needed.</p>\n\n<h3>Fit into Variational / Lagrangian Mechanics Framework</h3>\n\n<p>The <code>MultiMapping</code> component fits into the broader variational and Lagrangian mechanics framework by enabling consistent state updates across different models within a simulation scene graph. The mappings it applies (position, velocity, force) can be seen as part of the larger process of preserving mechanical invariants and ensuring that physical consistency is maintained throughout the simulation.</p>\n\n<p>In summary, <code>MultiMapping</code> provides a flexible mechanism for synchronizing multiple input models with output models through various mappings, which are crucial for maintaining consistency across different representations within complex simulations.</p>",
  "abstract": "`MultiMapping` handles many-to-many mappings between input and output models in SOFA, enabling consistent state updates across different representations within the simulation scene graph.",
  "sheet": "# MultiMapping\n\n**Overview:**\n\nThe `MultiMapping` component specializes in describing many-to-many mappings where all input models must have the same type, and all output models also share the same type. It inherits from `BaseMapping`, providing methods to add input/output models, retrieve model lists, and apply various types of mappings such as position, velocity, and force transformations.\n\n**Mathematical Model:**\n\nThe `MultiMapping` component implements several operators for mapping between input and output models:\n\n- **Position Mapping (apply):** This operator maps positions from input models to output models. Mathematically, if \\(J\\) is the mapping matrix, then this method computes:\n  \n  \\[ out = J \\times in \\]\n\n- **Velocity Mapping (applyJ):** This operator maps velocities from input models to output models using the tangent operator \\(J\\):\n  \n  \\[ out = J \\times in \\]\n\n- **Force Mapping (applyJT):** This operator maps forces from input models to output models using the transpose of the tangent operator \\(J^T\\):\n  \n  \\[ out += J^T \\times in \\]\n\n**Parameters and Data:**\n\nThe `MultiMapping` component has one significant data field:\n\n- **applyRestPosition**: A boolean flag indicating whether the mapping should be applied to rest positions during initialization.\n\n**Dependencies and Connections:**\n\nThis component typically requires other SOFA components such as input/output models (e.g., `State`, `BaseMechanicalState`) to function correctly. It fits into the scene graph by enabling consistent state updates across different representations within complex simulations."
}