Data Fields

Methods

{
  "name": "MapIndices",
  "namespace": "sofa::component::engine::transform",
  "module": "Sofa.Component.Engine.Transform",
  "include": "sofa/component/engine/transform/MapIndices.h",
  "doc": "Apply a permutation to a set of indices.\n\nThis class apply a permutation to a set of indices",
  "inherits": [
    "DataEngine"
  ],
  "templates": [
    "int",
    "unsigned int"
  ],
  "data_fields": [
    {
      "name": "f_in",
      "type": "VecValue",
      "xmlname": "in",
      "help": "input indices"
    },
    {
      "name": "f_indices",
      "type": "VecIndex",
      "xmlname": "indices",
      "help": "array containing in ith cell the input index corresponding to the output index i (or reversively if transpose=true)"
    },
    {
      "name": "f_out",
      "type": "VecValue",
      "xmlname": "out",
      "help": "Output indices"
    },
    {
      "name": "f_transpose",
      "type": "bool",
      "xmlname": "transpose",
      "help": "Should the transposed mapping be used ?"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "doUpdate",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyIndex",
      "return_type": "void",
      "params": [
        {
          "name": "v",
          "type": "V &"
        },
        {
          "name": "m",
          "type": "const MapIndex &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "apply",
      "return_type": "void",
      "params": [
        {
          "name": "v",
          "type": "Value &"
        },
        {
          "name": "m",
          "type": "const MapIndex &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MapIndices` component in the SOFA framework is an engine that applies a permutation to a set of indices. It inherits from `DataEngine`, indicating its role as a data processing element within the simulation pipeline.\n\nThis component has several key interactions:\n- **Input Data**: It takes input indices (`f_in`) and an array of indices (`f_indices`), which defines the mapping between old and new index positions.\n- **Configuration Control**: A boolean flag `f_transpose` determines whether to use a transposed version of the permutation mapping.\n- **Output Data**: The processed output indices are stored in `f_out`, with an optional string conversion available via `f_outStr`.\n\nThe component's core function, `doUpdate()`, processes the input indices according to the specified mapping and outputs the result. It supports various template types (e.g., int, unsigned int) for flexibility.\n\nIn practical usage:\n- **Data Fields**: \n  - `f_in`: Input indices to be permuted.\n  - `f_indices`: The permutation mapping array.\n  - `f_out`: Resulting output indices after applying the permutation.\n  - `f_transpose`: Boolean flag for using a transposed mapping.\n\nThis component is typically used in scenarios where index reordering or permutation is required, such as managing data structures during simulation updates.",
  "maths": "The `MapIndices` component in the SOFA framework is designed to apply a permutation to a set of indices. This operation does not directly contribute to the governing equations or operators such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(f_{int}\\), residual \\(R\\), etc., which are core components in finite element method (FEM) simulations. Instead, `MapIndices` is a utility component that manages index permutations and reorders data structures within the simulation pipeline.\n\n### Mathematical Description\n\nThe primary function of `MapIndices` is to perform an index permutation operation defined by a mapping array \\(\\mathbf{m}\\). Given input indices \\(\boldsymbol{i} = (i_1, i_2, \n\ndots, i_n)\\), the output indices \\(\boldsymbol{o} = (o_1, o_2, \n\ndots, o_n)\\) are computed based on the provided mapping array. The permutation can be either direct or transposed, controlled by a boolean flag `f_transpose`.\n\n#### Direct Mapping\nIf `f_transpose` is `false`, the mapping from input indices to output indices follows:\n\begin{align*}\n  o_j &= m_{i_j} \\\\ \\text{where } j &\\in [1, n]\n\ndot\nend{align*}\nHere, each element of the output index vector is determined by looking up the corresponding value in the mapping array based on the input indices.\n\n#### Transposed Mapping\nIf `f_transpose` is `true`, the transposed mapping from input indices to output indices follows:\n\begin{align*}\n  o_j &= m^{-1}_{i_j} \\\\ \\text{where } j &\\in [1, n]\n\ndot\nend{align*}\nIn this case, each element of the output index vector is determined by finding the inverse mapping in the array based on the input indices.\n\n### Role in the FEM Pipeline\nWhile `MapIndices` does not directly contribute to solving mechanical equations or applying constitutive laws, it plays a crucial role in managing data structures during various stages of the simulation. For example:\n- **Assembly Phase**: It can be used to reorder connectivity information before assembling global matrices.\n- **Time Integration**: Index permutations may be necessary when updating states between time steps.\n- **Nonlinear Solution and Linear Solve**: Permutations might be applied for preconditioning or reordering elements in linear solvers.\n\n### Numerical Methods and Discretization Choices\n`MapIndices` does not involve any numerical methods specific to FEM. Instead, it is a utility that operates on discrete index sets and applies permutations according to the specified mapping array.\n\n### Variational / Lagrangian Mechanics Framework\nThe `MapIndices` component itself does not fit directly into the variational or Lagrangian mechanics framework. However, its use can be part of broader numerical procedures where maintaining correct indexing is essential for consistency in simulations involving large deformations, contact interactions, and other complex mechanical phenomena.\n\n### Conclusion\nThe `MapIndices` component is an auxiliary tool that enables efficient index management within the SOFA simulation pipeline. It does not have intrinsic mathematical content related to FEM operators but is crucial for maintaining data integrity and enabling various numerical operations required by the simulation.",
  "abstract": "Applies a permutation to input indices based on a specified mapping array, with an option to use the transposed mapping.",
  "sheet": "# MapIndices\n\n**Overview**\nMapIndices is an engine that applies permutations to a set of indices. It inherits from `DataEngine` and manages index reordering within the SOFA simulation pipeline.\n\n**Parameters and Data**\nThe significant data fields are:\n- **f_in**: Input indices to be permuted (`VecValue`).\n- **f_indices**: The permutation mapping array (`VecIndex`). Each element at position `i` contains the input index corresponding to the output index `i`. If `transpose=true`, this is reversed.\n- **f_out**: Resulting output indices after applying the permutation (`VecValue`).\n- **f_transpose**: Boolean flag indicating whether to use a transposed mapping (`bool`; default: `false`).\n\n**Practical Notes**\nThe component operates on discrete index sets and applies permutations according to the specified mapping array. It is crucial for maintaining data integrity during various stages of the simulation, such as assembly phase, time integration, and nonlinear solution processes."
}