Back

BaseMapping

The `BaseMapping` class in the SOFA (Simulation Open-Framework Architecture) framework serves as an abstract base for mapping components that define relationships between different parts of a simulation, typically transforming coordinates or forces from one part to another.

abstract
`BaseMapping` defines an interface for mapping between different states in SOFA simulations, handling transformations of coordinates, forces, and other physical quantities from one part to another.
sheet
# BaseMapping ## Overview `BaseMapping` is an abstract base class that defines the interface for mapping between different states in SOFA simulations. It handles transformations of coordinates, forces, and other physical quantities from a parent (master) state to a child (slave) state. ## Mathematical Model The Jacobian matrix $J$ is central in defining how changes in coordinates or forces are propagated between components. If we consider the mapping from parent state $x_p$ to child state $x_c$, this relationship can be expressed as: \[ x_c = f(x_p) \] The Jacobian matrix $J$ is defined as the derivative of this function with respect to the parent coordinates: \[ J = \frac{\partial f}{\partial x_p} \]For nonlinear mappings, an additional term called the geometric stiffness matrix $K$ is introduced. This matrix accounts for changes in the Jacobian with respect to coordinate changes and can be represented as: \[ K = \frac{\partial J^T}{\partial x_p} \cdot F_c \]where $F_c$ denotes forces acting on the child state. ## Parameters and Data The significant Data fields exposed by `BaseMapping` control whether various physical properties are mapped: - **mapForces**: Are forces mapped? (default: false) - **mapConstraints**: Are constraints mapped? (default: false) - **mapMasses**: Are masses mapped? (default: false) - **mapMatrices**: Are explicit matrices mapped? (default: false) ## Dependencies and Connections `BaseMapping` must be implemented by derived classes to provide specific mappings for different types of simulation components. It typically requires a parent (`from`) and child (`to`) state, and fits into the scene graph between these states. ## Practical Notes Derived classes must implement methods such as `applyJ`, `applyJT`, and `buildGeometricStiffnessMatrix` to ensure proper mapping behavior. Proper configuration of the mapping parameters is crucial for maintaining physical consistency in complex simulations.
description
The `BaseMapping` class in the SOFA (Simulation Open-Framework Architecture) framework serves as an abstract base for mapping components that define relationships between different parts of a simulation, typically transforming coordinates or forces from one part to another.
details
{
  "key_features": [
    "Provides methods for setting up mappings between source (upper) and destination (lower/mapped) mechanical states, allowing the transformation of coordinates or forces from one part of the simulation to another.",
    "Includes virtual methods such as `applyJ`, `applyJT` that need to be implemented by derived classes to define how the mapping should work.",
    "Supports enabling/disabling of mappings for specific purposes like disabling a constraint temporarily without removing it from the scene graph.",
    "Offers functionality for managing mechanical properties of mapped states, including whether forces, constraints, and masses are considered in the mapping process through methods such as `areForcesMapped`, `setConstraintsMapped` etc.",
    "Incorporates support for assembling geometric stiffness matrices which is useful for advanced simulations involving non-linear mappings and geometric stiffness effects.",
    "Provides utility methods like `insertInNode` and `removeInNode` to manage the mapping\u0027s lifecycle within the SOFA scene graph."
  ],
  "programming_notes": [
    "The class is part of the SOFA framework\u0027s core and relies on several internal classes like `BaseNode`, `BaseState` for integration into a larger simulation setup.",
    "It uses the default constructor to initialize data fields (`f_mapForces`, `f_mapConstraints`, etc.) that control how mechanical properties are mapped, with initial values set to `true` unless otherwise specified by derived classes or user configuration."
  ],
  "purpose": "This component is designed to be inherited by concrete mapping implementations. It provides a standardized interface and some default behavior.",
  "usage": [
    "`BaseMapping` itself is not intended for direct instantiation or use in a simulation. Instead, it must be inherited by concrete classes that implement specific mappings according to the simulation requirements.",
    "Derived classes are expected to provide implementations for pure virtual methods like `applyJ`, `applyJT` and optionally override other methods to customize mapping behavior.",
    "These derived mappings can then be used within SOFA scenes to enforce relationships between different components, such as applying constraints or transferring forces."
  ]
}
maths
The `BaseMapping` class in the SOFA framework is designed to handle mappings between different components within a simulation. It provides an abstract interface for transforming coordinates, forces, and other physical quantities from one part of the system (the parent) to another (the child). This transformation can be crucial for maintaining consistency across various parts of a complex simulation. ### Mathematical Representation: - **Jacobian Matrix:** The Jacobian matrix `J` is central in defining how changes in coordinates or forces are propagated between components. If we consider the mapping from parent state `x_p` to child state `x_c`, this relationship can be expressed as: \[ x_c = f(x_p) \] where `f` represents some transformation function. The Jacobian matrix `J` is defined as the derivative of this function with respect to the parent coordinates: \[ J = \frac{\partial f}{\partial x_p} \] - **Geometric Stiffness Matrix:** For nonlinear mappings, an additional term called the geometric stiffness matrix `K` is introduced. This matrix accounts for changes in the Jacobian with respect to coordinate changes and can be represented as: \[ K = \frac{\partial J^T}{\partial x_p} \cdot F_c \] where `F_c` denotes forces acting on the child state. This term is essential for maintaining stability in nonlinear simulations. ### Physical Interpretation: - **Force Mapping:** Forces acting on the child part are often mapped back to the parent using the transpose of the Jacobian matrix, denoted as `J^T`. This ensures that forces are properly distributed and accounted for across different parts of the system. \[ F_p = J^T \cdot F_c \] - **Mass Mapping:** Similarly, masses can be mapped between components to ensure proper dynamic behavior. This involves transforming mass properties from the child state to the parent state using the Jacobian matrix: \[ M_p = J^T \cdot M_c \cdot J \] where `M` represents the mass matrix. ### Implementation Details in SOFA Framework: - **Abstract Base Class:** The `BaseMapping` class is an abstract base class that defines virtual methods such as `applyJ`, `applyJT`, and `buildGeometricStiffnessMatrix`. These methods must be implemented by derived classes to provide specific mappings for different types of simulation components. - **Mechanical Properties Management:** Methods like `setForcesMapped` and `isMechanical` allow users to control whether forces, constraints, or masses are mapped between the parent and child states. This is critical for maintaining physical consistency in complex simulations involving multiple interconnected parts. 
{
  "name": "BaseMapping",
  "main": {
    "name": "BaseMapping",
    "namespace": "sofa::core",
    "module": "Sofa.framework.Core",
    "include": "sofa/core/BaseMapping.h",
    "doc": "An interface to convert a model state to an other model state.\nThe model states are positions and velocities or generalizations of these (class sofa::core::BaseState).\nThe source is denoted using various names: from, input, master, parent…\nThe target is denoted using various names: to, output, slave, child…\nThe mapping must be located somewhere between the master and the slave, so that the visitors traverse it after the master and before the slave during the top-down traversals, and the other way round during the bottom-up traversals.\nIt is typically located in the same graph node as the slave, with the master in the parent node, but this is not a must.\nMappings typically store constant local coordinates of the output points, and update the output points by applying input displacements to the local coordinates.",
    "inherits": [
      "BaseObject"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "f_mapForces",
        "type": "bool",
        "xmlname": "mapForces",
        "help": "Are forces mapped ?"
      },
      {
        "name": "f_mapConstraints",
        "type": "bool",
        "xmlname": "mapConstraints",
        "help": "Are constraints mapped ?"
      },
      {
        "name": "f_mapMasses",
        "type": "bool",
        "xmlname": "mapMasses",
        "help": "Are masses mapped ?"
      },
      {
        "name": "f_mapMatrices",
        "type": "bool",
        "xmlname": "mapMatrices",
        "help": "Are matrix explicit mapped?"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "toBaseMapping",
        "return_type": "const BaseMapping *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "isLinear",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "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": 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": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getFrom",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "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": "getTo",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "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": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "inForce",
            "type": "MultiVecDerivId"
          },
          {
            "name": "outForce",
            "type": "ConstMultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyDJT",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "inForce",
            "type": "MultiVecDerivId"
          },
          {
            "name": "outForce",
            "type": "ConstMultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const ConstraintParams *"
          },
          {
            "name": "inConst",
            "type": "MultiMatrixDerivId"
          },
          {
            "name": "outConst",
            "type": "ConstMultiMatrixDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "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": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "areForcesMapped",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "areConstraintsMapped",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "areMassesMapped",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "areMatricesMapped",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setForcesMapped",
        "return_type": "void",
        "params": [
          {
            "name": "b",
            "type": "bool"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setConstraintsMapped",
        "return_type": "void",
        "params": [
          {
            "name": "b",
            "type": "bool"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setMassesMapped",
        "return_type": "void",
        "params": [
          {
            "name": "b",
            "type": "bool"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setMatricesMapped",
        "return_type": "void",
        "params": [
          {
            "name": "b",
            "type": "bool"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setNonMechanical",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "isMechanical",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "sameTopology",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getJ",
        "return_type": "const sofa::linearalgebra::BaseMatrix *",
        "params": [
          {
            "name": "",
            "type": "const MechanicalParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getJ",
        "return_type": "const sofa::linearalgebra::BaseMatrix *",
        "params": [],
        "is_virtual": true,
        "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": "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": "disable",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getJs",
        "return_type": "const int *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "updateK",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const MechanicalParams *"
          },
          {
            "name": "",
            "type": "ConstMultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getK",
        "return_type": "const linearalgebra::BaseMatrix *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildGeometricStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrices",
            "type": "sofa::core::GeometricStiffnessMatrix *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "testMechanicalState",
        "return_type": "bool",
        "params": [
          {
            "name": "state",
            "type": "BaseState *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "insertInNode",
        "return_type": "bool",
        "params": [
          {
            "name": "node",
            "type": "objectmodel::BaseNode *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "removeInNode",
        "return_type": "bool",
        "params": [
          {
            "name": "node",
            "type": "objectmodel::BaseNode *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `BaseMapping` class in the SOFA (Simulation Open-Framework Architecture) framework serves as an abstract base for mapping components that define relationships between different parts of a simulation, typically transforming coordinates or forces from one part to another.",
    "details": {
      "purpose": "This component is designed to be inherited by concrete mapping implementations. It provides a standardized interface and some default behavior.",
      "key_features": [
        "Provides methods for setting up mappings between source (upper) and destination (lower/mapped) mechanical states, allowing the transformation of coordinates or forces from one part of the simulation to another.",
        "Includes virtual methods such as `applyJ`, `applyJT` that need to be implemented by derived classes to define how the mapping should work.",
        "Supports enabling/disabling of mappings for specific purposes like disabling a constraint temporarily without removing it from the scene graph.",
        "Offers functionality for managing mechanical properties of mapped states, including whether forces, constraints, and masses are considered in the mapping process through methods such as `areForcesMapped`, `setConstraintsMapped` etc.",
        "Incorporates support for assembling geometric stiffness matrices which is useful for advanced simulations involving non-linear mappings and geometric stiffness effects.",
        "Provides utility methods like `insertInNode` and `removeInNode` to manage the mapping's lifecycle within the SOFA scene graph."
      ],
      "usage": [
        "`BaseMapping` itself is not intended for direct instantiation or use in a simulation. Instead, it must be inherited by concrete classes that implement specific mappings according to the simulation requirements.",
        "Derived classes are expected to provide implementations for pure virtual methods like `applyJ`, `applyJT` and optionally override other methods to customize mapping behavior.",
        "These derived mappings can then be used within SOFA scenes to enforce relationships between different components, such as applying constraints or transferring forces."
      ],
      "programming_notes": [
        "The class is part of the SOFA framework's core and relies on several internal classes like `BaseNode`, `BaseState` for integration into a larger simulation setup.",
        "It uses the default constructor to initialize data fields (`f_mapForces`, `f_mapConstraints`, etc.) that control how mechanical properties are mapped, with initial values set to `true` unless otherwise specified by derived classes or user configuration."
      ]
    }
  },
  "maths": {
    "maths": "The `BaseMapping` class in the SOFA framework is designed to handle mappings between different components within a simulation. It provides an abstract interface for transforming coordinates, forces, and other physical quantities from one part of the system (the parent) to another (the child). This transformation can be crucial for maintaining consistency across various parts of a complex simulation.\n\n### Mathematical Representation:\n\n- **Jacobian Matrix:** The Jacobian matrix `J` is central in defining how changes in coordinates or forces are propagated between components. If we consider the mapping from parent state `x_p` to child state `x_c`, this relationship can be expressed as:\n  \\[\n  x_c = f(x_p)\n  \\]\n  where `f` represents some transformation function. The Jacobian matrix `J` is defined as the derivative of this function with respect to the parent coordinates:\n  \\[\n  J = \\frac{\\partial f}{\\partial x_p}\n  \\]\n\n- **Geometric Stiffness Matrix:** For nonlinear mappings, an additional term called the geometric stiffness matrix `K` is introduced. This matrix accounts for changes in the Jacobian with respect to coordinate changes and can be represented as:\n  \\[\n  K = \\frac{\\partial J^T}{\\partial x_p} \\cdot F_c\n  \\]\n  where `F_c` denotes forces acting on the child state. This term is essential for maintaining stability in nonlinear simulations.\n\n### Physical Interpretation:\n\n- **Force Mapping:** Forces acting on the child part are often mapped back to the parent using the transpose of the Jacobian matrix, denoted as `J^T`. This ensures that forces are properly distributed and accounted for across different parts of the system.\n\n  \\[\n  F_p = J^T \\cdot F_c\n  \\]\n\n- **Mass Mapping:** Similarly, masses can be mapped between components to ensure proper dynamic behavior. This involves transforming mass properties from the child state to the parent state using the Jacobian matrix:\n  \\[\n  M_p = J^T \\cdot M_c \\cdot J\n  \\]\n  where `M` represents the mass matrix.\n\n### Implementation Details in SOFA Framework:\n- **Abstract Base Class:** The `BaseMapping` class is an abstract base class that defines virtual methods such as `applyJ`, `applyJT`, and `buildGeometricStiffnessMatrix`. These methods must be implemented by derived classes to provide specific mappings for different types of simulation components.\n\n- **Mechanical Properties Management:** Methods like `setForcesMapped` and `isMechanical` allow users to control whether forces, constraints, or masses are mapped between the parent and child states. This is critical for maintaining physical consistency in complex simulations involving multiple interconnected parts."
  },
  "summary": {
    "abstract": "`BaseMapping` defines an interface for mapping between different states in SOFA simulations, handling transformations of coordinates, forces, and other physical quantities from one part to another.",
    "sheet": "# BaseMapping\n\n## Overview\n`BaseMapping` is an abstract base class that defines the interface for mapping between different states in SOFA simulations. It handles transformations of coordinates, forces, and other physical quantities from a parent (master) state to a child (slave) state.\n\n## Mathematical Model\nThe Jacobian matrix $J$ is central in defining how changes in coordinates or forces are propagated between components. If we consider the mapping from parent state $x_p$ to child state $x_c$, this relationship can be expressed as:\n\\[\nx_c = f(x_p)\n\\]\nThe Jacobian matrix $J$ is defined as the derivative of this function with respect to the parent coordinates:\n\\[\nJ = \\frac{\\partial f}{\\partial x_p}\n\\]For nonlinear mappings, an additional term called the geometric stiffness matrix $K$ is introduced. This matrix accounts for changes in the Jacobian with respect to coordinate changes and can be represented as:\n\\[\nK = \\frac{\\partial J^T}{\\partial x_p} \\cdot F_c\n\\]where $F_c$ denotes forces acting on the child state.\n\n## Parameters and Data\nThe significant Data fields exposed by `BaseMapping` control whether various physical properties are mapped:\n- **mapForces**: Are forces mapped? (default: false)\n- **mapConstraints**: Are constraints mapped? (default: false)\n- **mapMasses**: Are masses mapped? (default: false)\n- **mapMatrices**: Are explicit matrices mapped? (default: false)\n\n## Dependencies and Connections\n`BaseMapping` must be implemented by derived classes to provide specific mappings for different types of simulation components. It typically requires a parent (`from`) and child (`to`) state, and fits into the scene graph between these states.\n\n## Practical Notes\nDerived classes must implement methods such as `applyJ`, `applyJT`, and `buildGeometricStiffnessMatrix` to ensure proper mapping behavior. Proper configuration of the mapping parameters is crucial for maintaining physical consistency in complex simulations."
  }
}