Methods

{
  "name": "IdentityContactMapper",
  "namespace": "sofa::component::collision::response::mapper",
  "module": "Sofa.Component.Collision.Response.Mapper",
  "include": "sofa/component/collision/response/mapper/IdentityContactMapper.h",
  "doc": "Base class for IdentityMapping based mappers",
  "inherits": [
    "BaseContactMapper"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "setCollisionModel",
      "return_type": "void",
      "params": [
        {
          "name": "model",
          "type": "MCollisionModel *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "cleanup",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "createMapping",
      "return_type": "MMechanicalState *",
      "params": [
        {
          "name": "name",
          "type": "const char *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "resize",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addPoint",
      "return_type": "int",
      "params": [
        {
          "name": "",
          "type": "const Coord &"
        },
        {
          "name": "index",
          "type": "int"
        },
        {
          "name": "",
          "type": "Real &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "update",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateXfree",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateX0",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": {
    "component_name": "IdentityContactMapper",
    "namespace": "sofa::component::collision::response::mapper",
    "purpose": "The IdentityContactMapper is used to map contact points from collision models to mechanical states within the SOFA framework, ensuring that collision points are correctly represented in the simulation. This component specializes in handling identity mappings where no additional transformations are needed.",
    "key_functions": [
      {
        "function_name": "setCollisionModel",
        "description": "Sets the collision model for which contact points will be mapped."
      },
      {
        "function_name": "cleanup",
        "description": "Cleans up resources associated with the mapping, such as removing child nodes and their objects from the scene graph."
      },
      {
        "function_name": "createMapping",
        "description": "Creates a mechanical state corresponding to the collision model's contact points and attaches it to the scene graph if applicable."
      },
      {
        "function_name": "update",
        "description": "Applies transformations (if any) from the collision model to the mechanical state, ensuring consistency between the two during simulation."
      },
      {
        "function_name": "addPoint",
        "description": "Adds a specific contact point from the collision model to the mechanical state and optionally sets its radius for certain models like spheres."
      }
    ],
    "specializations_and_inheritance": [
      {
        "specialization_for": "collision::geometry::SphereCollisionModel<sofa::defaulttype::Vec3Types>",
        "description": "This specialization handles sphere collision models, ensuring that the radius of each contact point is correctly set."
      },
      {
        "specialization_for": "collision::geometry::PointCollisionModel<sofa::defaulttype::Vec3Types>",
        "description": "This specialization handles point-based collision models, simplifying the mapping process by directly using the existing data types without additional transformations."
      }
    ],
    "usage_example": [
      {
        "example_code": "ContactMapperCreator<ContactMapper<SphereCollisionModel<Vec3f>>> SphereContactMapperClass('PenalityContactForceField', true);",
        "description": "Creates and registers a contact mapper for sphere collision models within the SOFA framework."
      }
    ],
    "note": "IdentityContactMapper is particularly useful when dealing with simple identity mappings between collision models and mechanical states, streamlining the simulation process by reducing unnecessary transformations."
  },
  "maths": "<p>The <code>IdentityContactMapper</code> in the SOFA framework is designed to map contact points from collision models to mechanical states, primarily handling identity mappings where no additional transformations are required. This ensures that the collision points are accurately represented within the simulation without introducing unnecessary complexity or computational overhead.</p>\n\n<h3>Governing Equations and Operators</h3>\n<ul>\n<li><strong>Identity Mapping:</strong> The <code>IdentityContactMapper</code> performs an identity mapping between contact points from a collision model (e.g., spheres, points) and the mechanical state. In mathematical terms, if \\( P_i \\) is the position of a contact point in the collision model and \\( x_i \\) represents its corresponding position in the mechanical state:</li>\n</ul>\n\\[\n    x_i = P_i\n\\]\n<ul>\n<li><strong>Update Operations:</strong> During each simulation step, the <code>update</code> method ensures that the positions and velocities of contact points are synchronized between the collision model and mechanical state. This can be expressed as:</li>\n</ul>\n\\[\n    x_{i}^{k+1} = P_i^k\n\\]\n\\[\n    v_{i}^{k+1} = \\frac{P_i^{k+1} - P_i^k}{Δt}\n\\]\n<p>where \\( x_i ⁿ, v_i ⁿ \\) are the updated positions and velocities of contact points in the mechanical state at time step \\( k+1 \\), and \\( P_i^k \\) is the position from the collision model at time step \\( k \\).</p>\n<ul>\n<li><strong>AddPoint Function:</strong> The <code>addPoint</code> method adds a contact point to the mechanical state. For sphere collision models, it also sets the radius of each contact point:</li>\n</ul>\n\\[\n    r_i = e.r(i)\n\\]\n<p>where \\( r_i \\) is the radius of the sphere at index \\( i \\).</p>\n\n<h3>Constitutive and Kinematic Laws</h3>\n<ul>\n<li><strong>Contact Points:</strong> The contact points are treated as rigid entities with no deformation. Therefore, their constitutive behavior remains constant throughout the simulation.</li>\n<li><strong>Sphere Models:</strong> For sphere collision models, each point is represented by a spherical geometry with a defined radius.</li>\n</ul>\n\n<h3>Role in FEM Pipeline</h3>\n<ul>\n<li>The <code>IdentityContactMapper</code> primarily operates within the assembly phase of the global FEM pipeline:</li>\n</ul>\n<ol>\n<li><strong>Mapping Creation:</strong> During initialization, it creates a mechanical state for collision points through the <code>createMapping</code> method.</li>\n<li><strong>Update Operations:</strong> In each time step, the <code>update</code>, <code>updateXfree</code>, and <code>updateX0</code> methods ensure that the positions and velocities are synchronized between the collision model and mechanical state.</li>\n<li><strong>Cleanup:</strong> The <code>cleanup</code> method ensures proper resource management by detaching child nodes from the scene graph.</li>\n</ol>\n\n<h3>Numerical Methods and Discretization Choices</h3>\n<ul>\n<li>The component primarily performs identity mapping, which does not involve complex numerical methods or discretizations. It relies on straightforward operations to maintain consistency between collision models and mechanical states.</li>\n<li>For sphere models, the radius is directly set during the <code>addPoint</code> operation, ensuring that each contact point has its associated geometric property accurately represented.</li>\n</ul>\n\n<h3>Fitting into Variational / Lagrangian Mechanics Framework</h3>\n<ul>\n<li>The <code>IdentityContactMapper</code> ensures consistency between the collision model and mechanical state, contributing to the overall variational mechanics framework. Specifically:</li>\n</ul>\n<ol>\n<li><strong>Variational Formulation:</strong> It does not directly participate in deriving or discretizing the weak form but ensures that contact points from collision models are correctly integrated into the simulation.</li>\n<li><strong>Lagrangian Mechanics:</strong> By maintaining consistency between positions and velocities of contact points, it indirectly supports the Lagrangian mechanics framework by ensuring accurate representation within the simulation pipeline.</li>\n</ol>",
  "abstract": "The IdentityContactMapper maps contact points from collision models to mechanical states, ensuring consistency without additional transformations.",
  "sheet": "# IdentityContactMapper\n\n**Overview**\n\nThe `IdentityContactMapper` is a component that handles identity mappings between contact points in collision models and their corresponding positions in the mechanical state. It ensures that no additional transformations are applied during this mapping process.\n\n**Mathematical Model**\n\nThe mathematical model for the `IdentityContactMapper` involves simple identity mappings:\n\n- Identity Mapping: \n  \\[ x_i = P_i \\]\n  where \\(x_i\\) is the position in the mechanical state and \\(P_i\\) is the contact point from the collision model.\n\n- Update Operations: During each simulation step, positions are synchronized:\n  \\[ x_{i}^{k+1} = P_i^k \\]\n  Velocities are updated as follows:\n  \\[ v_{i}^{k+1} = \\frac{P_i^{k+1} - P_i^k}{Δt} \\]\n\n- AddPoint Function: For sphere collision models, the radius is set directly:\n  \\[ r_i = e.r(i) \\]\n\n**Dependencies and Connections**\n\nThe `IdentityContactMapper` typically requires a collision model (e.g., SphereCollisionModel or PointCollisionModel) to provide contact points. It exchanges data with mechanical states to ensure consistency between the positions of these points in both models.\n\n**Practical Notes**\n\nThis component is particularly useful for simple identity mappings, streamlining simulations by avoiding unnecessary transformations. Ensure that collision models are correctly set and aligned with the mechanical state to maintain accuracy."
}