{
  "name": "IndexValueMapper",
  "main": {
    "name": "IndexValueMapper",
    "namespace": "sofa::component::engine::transform",
    "module": "Sofa.Component.Engine.Transform",
    "include": "sofa/component/engine/transform/IndexValueMapper.h",
    "doc": "Input values to output values mapper. Includes indices rules, such as replacement, resize.",
    "inherits": [
      "DataEngine"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "f_value",
        "type": "Real",
        "xmlname": "value",
        "help": "Value to map indices on"
      },
      {
        "name": "p_defaultValue",
        "type": "Real",
        "xmlname": "defaultValue",
        "help": "Default value for indices without any value"
      }
    ],
    "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"
      }
    ]
  },
  "desc": {
    "description": "The `IndexValueMapper` is a component in the SOFA framework that serves as an engine for mapping input values to output values based on specified indices. It inherits from `DataEngine`, indicating its role as a data processing unit within the simulation pipeline. The primary function of this mapper includes rules for index replacement and resizing, which are crucial operations when transforming or manipulating datasets in simulations.\n\nIn terms of interactions with other SOFA components, `IndexValueMapper` primarily relies on input data fields (`f_inputValues`, `f_indices`, `f_value`) and provides an output field (`f_outputValues`). It does not have explicit links to other components but can be connected through the scene graph structure for data flow management. The component operates by initializing itself with default values and updating its outputs based on incoming inputs.\n\nFor practical usage, users should configure the `value` and `defaultValue` fields appropriately according to their simulation needs. The `f_inputValues` field can hold existing values that need transformation, while `f_indices` specifies which indices these transformations will affect. The output is then stored in `f_outputValues`. This component is useful for tasks requiring precise control over the mapping of index-based data within simulations."
  },
  "maths": {
    "maths": "The `IndexValueMapper` is a data processing unit within the SOFA framework that serves to map input values to output values based on specified indices. This component does not directly involve governing equations or operators such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(f_{int}\\), residual \\(R\\), etc., which are typical in finite element simulations. Instead, its role is primarily related to the manipulation of data fields within the simulation pipeline.\n\n### Governing Equations or Operators\nThe `IndexValueMapper` does not contribute directly to any specific governing equations or operators typically associated with FEM. Its primary function is to handle index-based transformations and mappings on input datasets.\n\n### Constitutive or Kinematic Laws Involved\nThere are no constitutive or kinematic laws involved in the functionality of the `IndexValueMapper`. It operates purely at the data level, manipulating values based on specified indices without invoking any physical or mechanical principles.\n\n### Role in the Global FEM Pipeline\nIn the context of the broader FEM pipeline, the `IndexValueMapper` plays a role in the assembly phase, specifically dealing with data manipulation and transformation. It can be used to update datasets during the simulation loop, ensuring that certain indices are mapped to specified values.\n\n### Numerical Methods or Discretization Choices Encoded\nThe component does not encode any specific numerical methods or discretization choices associated with FEM. Instead, it focuses on basic operations such as resizing and updating vectors based on index rules:\n\n1. **Copying Existing Values**: It copies the existing values from `f_inputValues` to `f_outputValues`.\n2. **Adding New Values**: For each specified index in `f_indices`, it maps a new value (`f_value`) onto these indices in `f_outputValues`. If an index is beyond the current size of `f_outputValues`, it resizes the vector and fills any gaps with the default value (`p_defaultValue`).\n\n### How the Component Fits into the Broader Variational / Lagrangian Mechanics Framework\nThe `IndexValueMapper` does not directly fit into the variational or Lagrangian mechanics framework, as its functionality is purely data-related. It can be seen as a utility component that supports the overall simulation by providing mechanisms for precise control over index-based data transformations.\n\n### Mathematical Description of the Mapping Process\nGiven an input vector \\(\\mathbf{V}_{in}\\) and specified indices \\(I = \\{i_1, i_2, ..., i_n\\}\\), the `IndexValueMapper` processes these as follows:\n\n1. **Initialization**: Initialize the output vector \\(\\mathbf{V}_{out}\\) with default values.\n2. **Copy Values**: Copy existing values from \\(\\mathbf{V}_{in}\\) to \\(\\mathbf{V}_{out}\\).\n3. **Mapping Indices**: For each index \\(i_k \\in I\\), map the value \\(v_{map}\\) (from `f_value`) onto \\(\\mathbf{V}_{out}[i_k]\\). If \\(i_k\\) exceeds the size of \\(\\mathbf{V}_{out}\\), resize and fill gaps with the default value \\(v_{def}\\) (from `p_defaultValue`).\n\nIn summary, the mathematical description can be formulated as:\n\\[ \\mathbf{V}_{out}[i_k] = v_{map} \\quad \\text{for each } i_k \\in I \\]\nwith resizing and filling gaps when necessary.\n"
  },
  "summary": {
    "abstract": "The `IndexValueMapper` maps input values to output values based on specified indices, handling index replacement and vector resizing in the SOFA simulation pipeline.",
    "sheet": "\n# IndexValueMapper\n\n## Overview\n\nThe `IndexValueMapper` is a component within the SOFA framework that serves as an engine for mapping input values to output values based on specified indices. It inherits from `DataEngine`, indicating its role as a data processing unit within the simulation pipeline.\n\n## Parameters and Data\n\n- **f_value**: Value to map indices on (type: Real, default: none).\n- **p_defaultValue**: Default value for indices without any value (type: Real, default: none).\n\n## Practical Notes\n\nUsers should configure `value` and `defaultValue` fields appropriately according to their simulation needs. The component operates by initializing itself with default values and updating its outputs based on incoming inputs."
  }
}