{
  "name": "DistanceMultiMapping",
  "main": {
    "name": "DistanceMultiMapping",
    "namespace": "sofa::component::mapping::nonlinear",
    "module": "Sofa.Component.Mapping.NonLinear",
    "include": "sofa/component/mapping/nonlinear/DistanceMultiMapping.h",
    "doc": "Mapping point positions from several mechanical states to distances (in distance unit).\n\nMaps point positions from several mstates to distances (in distance unit).\n@tparam TIn parent point positions\n@tparam TOut corresponds to a scalar value: distance between point pairs, minus a rest distance.\nThe pairs are given in a topology with edges in the same node.\nThe points index are given as pair(mstate_index,dof_index) in the Data indexPairs.\nIf the rest lengths are not defined, they are set using the initial values.\nIf computeDistance is set to true, the rest lengths are set to 0.\n@author Matthieu Nesme",
    "inherits": [
      "MultiMapping"
    ],
    "templates": [
      "sofa::defaulttype::Rigid3Types, sofa::defaulttype::Vec1Types",
      "sofa::defaulttype::Vec3Types, sofa::defaulttype::Vec1Types"
    ],
    "data_fields": [
      {
        "name": "d_computeDistance",
        "type": "bool",
        "xmlname": "computeDistance",
        "help": "if 'computeDistance = true', then rest length of each element equal 0, otherwise rest length is the initial length of each of them"
      },
      {
        "name": "d_showObjectScale",
        "type": "Real",
        "xmlname": "showObjectScale",
        "help": "Scale for object display"
      },
      {
        "name": "d_color",
        "type": "sofa::type::RGBAColor",
        "xmlname": "showColor",
        "help": "Color for object display. (default=[1.0,1.0,0.0,1.0])"
      }
    ],
    "links": [
      {
        "name": "l_topology",
        "target": "BaseMeshTopology",
        "kind": "single",
        "xmlname": "topology",
        "help": "link to the topology container"
      }
    ],
    "methods": [
      {
        "name": "addPoint",
        "return_type": "void",
        "params": [
          {
            "name": "fromModel",
            "type": "const core::BaseState *"
          },
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addPoint",
        "return_type": "void",
        "params": [
          {
            "name": "fromModel",
            "type": "int"
          },
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "apply",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "dataVecOutPos",
            "type": "const int &"
          },
          {
            "name": "dataVecInPos",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJ",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "dataVecOutVel",
            "type": "const int &"
          },
          {
            "name": "dataVecInVel",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "dataVecOutForce",
            "type": "const int &"
          },
          {
            "name": "dataVecInForce",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "apply",
        "return_type": "void",
        "params": [
          {
            "name": "outPos",
            "type": "const int &"
          },
          {
            "name": "inPos",
            "type": "const vecConstInVecCoord &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJ",
        "return_type": "void",
        "params": [
          {
            "name": "outDeriv",
            "type": "const int &"
          },
          {
            "name": "inDeriv",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "outDeriv",
            "type": "const int &"
          },
          {
            "name": "inDeriv",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyJT",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "",
            "type": "const int &"
          },
          {
            "name": "",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyDJT",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "inForce",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "outForce",
            "type": "core::ConstMultiVecDerivId"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "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": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "childForce",
            "type": "core::ConstMultiVecDerivId"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getK",
        "return_type": "const linearalgebra::BaseMatrix *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildGeometricStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrices",
            "type": "sofa::core::GeometricStiffnessMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "vparams",
            "type": "const core::visual::VisualParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeCoordPositionDifference",
        "return_type": "void",
        "params": [
          {
            "name": "r",
            "type": "Direction &"
          },
          {
            "name": "a",
            "type": "const InCoord &"
          },
          {
            "name": "b",
            "type": "const InCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `DistanceMultiMapping` component in the SOFA framework is designed to map point positions from several mechanical states (mstates) to distances in distance units. It supports the mapping of points from multiple input models (each with its own set of degrees-of-freedom) and calculates the scalar output, which represents the distance between pairs of points minus a rest distance. The component uses topology information provided by edges within a BaseMeshTopology container to determine the point pairs for distance computation. It also supports setting initial rest lengths or using the initial distances between points as rest lengths, depending on user-defined parameters.\n\n**Interactions with other SOFA components:**\n- Inherits from `MultiMapping` and is specialized for non-linear mappings.\n- Interacts with multiple mechanical states (`BaseState`) to gather point positions.\n- Relies on a BaseMeshTopology container for topology information about edges that define the pairs of points used in distance calculations.\n\n**Practical Usage Guidance: Fields**\n- **computeDistance:** Boolean parameter (`d_computeDistance`) to determine whether rest lengths are set to zero or initial distances. If `true`, then each element's rest length is set to 0; otherwise, it uses the initial distances.\n- **showObjectScale:** Real number (`d_showObjectScale`) to adjust the scale for visual display of object mappings.\n- **showColor:** RGBAColor (`d_color`) to specify a color for displaying object mappings. Default value is yellow ([1.0, 1.0, 0.0, 1.0]).\n\n**Links**\n- The `topology` link points to the BaseMeshTopology container that provides topology data (edges) necessary for defining point pairs.\n"
  },
  "maths": {
    "maths": "# Mathematical Description of the DistanceMultiMapping Component\n\n## Overview\nThe `DistanceMultiMapping` component in the SOFA (Simulation Open Framework Architecture) framework is designed to map point positions from multiple mechanical states into scalar distances. This mapping involves calculating the distance between pairs of points, which are defined by edges within a given topology container (`BaseMeshTopology`). The output represents these distances minus a rest length, enabling non-linear mappings and dynamic interaction analysis.\n\n## Mathematical Formulation\n\n### Notation\n- Let $P_i$ be the position vector of point $i$ in one of the input mechanical states.\n- Let $(a_j, b_j)$ represent pairs of points defined by edges $j$ within the topology container.\n- Let $d_{ij}$ denote the distance between points $a_j$ and $b_j$, i.e., $d_{ij} = \\| P_{a_j} - P_{b_j} \\|$ where $\\| \\cdot \\|$ denotes the Euclidean norm.\n\n### Calculation of Distances\nThe component calculates the distances between pairs of points $(a_j, b_j)$:\n\\[\nd_{ij} = \\sqrt{ (P_{a_jx} - P_{b_jx})^2 + (P_{a_jy} - P_{b_jy})^2 + (P_{a_jz} - P_{b_jz})^2 }\n\\]\nwhere $P_{ax}$, $P_{ay}$, and $P_{az}$ denote the coordinates of point $a$ along the x-, y-, and z-axes respectively.\n\n### Rest Lengths\nThe rest lengths ($l_0$) are either set to zero if `d_computeDistance` is `true`, or initialized using initial distances between points $(a_j, b_j)$ at simulation start:\n\\[\nl_{0j} = \begin{cases}\n   0 & \\text{if } d_\\text{computeDistance} = \\text{true}, \\\\\n   d_{ij}(t=0) & \\text{otherwise}\n\\end{cases}\n\\]\n\n### Output Scalar Value\nThe scalar output value for each pair $(a_j, b_j)$ is given by the difference between the current distance and the rest length:\n\\[\nd'_j = d_{ij} - l_{0j}\n\\]\nThis output $d'_j$ represents a non-linear transformation that can be used in subsequent calculations or visualizations.\n\n## Physical Interpretation\nThe `DistanceMultiMapping` component models physical systems where distances between pairs of points are crucial, such as in the simulation of springs, elastic materials, or constraint-based dynamics. The rest length acts as an equilibrium distance, and deviations from this rest length can be used to model forces that arise due to deformation or displacement.\n\n### Example: Elastic Rod Simulation\nIn a simulation of an elastic rod with points $a_j$ and $b_j$, the distance between these points changes over time. The `DistanceMultiMapping` component calculates $d'_j = d_{ij} - l_{0j}$, where $l_{0j}$ is the rest length. This value can be used to compute elastic forces based on Hooke's law:\n\\[\nF_j = k (d_{ij} - l_{0j})\n\\]\nwhere $k$ is the spring constant.\n\n### Visualization and Display Parameters\nThe `showObjectScale` parameter adjusts the scale for visual display, while the `showColor` parameter specifies a color for displaying object mappings. These parameters are useful for debugging and visualization purposes to ensure that the mapping results are correctly interpreted in the context of the simulation environment."
  },
  "summary": {
    "abstract": "The `DistanceMultiMapping` component maps point positions from multiple mechanical states into scalar distances based on Euclidean norms between pairs of points defined by edges in a topology container. It calculates these distances minus rest lengths for non-linear mappings and provides visualization parameters.",
    "sheet": "# DistanceMultiMapping\n\n## Overview\nThe `DistanceMultiMapping` component in the SOFA framework maps point positions from multiple mechanical states into scalar distances based on Euclidean norms between pairs of points defined by edges within a topology container (`BaseMeshTopology`). It calculates these distances minus rest lengths for non-linear mappings and provides visualization parameters.\n\n## Mathematical Model\n### Notation\n- Let $P_i$ be the position vector of point $i$ in one of the input mechanical states.\n- Let $(a_j, b_j)$ represent pairs of points defined by edges $j$ within the topology container.\n- Let $d_{ij}$ denote the distance between points $a_j$ and $b_j$, i.e., $d_{ij} = \\| P_{a_j} - P_{b_j} \\|$ where $\\| \\cdot \\|$ denotes the Euclidean norm.\n\n### Calculation of Distances\nThe component calculates the distances between pairs of points $(a_j, b_j)$:\n\nd_{ij} = \\sqrt{ (P_{a_jx} - P_{b_jx})^2 + (P_{a_jy} - P_{b_jy})^2 + (P_{a_jz} - P_{b_jz})^2 }\n\nwhere $P_{ax}$, $P_{ay}$, and $P_{az}$ denote the coordinates of point $a$ along the x-, y-, and z-axes respectively.\n\n### Rest Lengths\nThe rest lengths ($l_0$) are either set to zero if `d_computeDistance` is `true`, or initialized using initial distances between points $(a_j, b_j)$ at simulation start:\n\nl_{0j} = \\begin{cases}\n   0 & \\text{if } d_\\text{computeDistance} = \\text{true}, \\\\\n   d_{ij}(t=0) & \\text{otherwise}\n\\end{cases}\n\n### Output Scalar Value\nThe scalar output value for each pair $(a_j, b_j)$ is given by the difference between the current distance and the rest length:\n\nd'_j = d_{ij} - l_{0j}\n\nThis output $d'_j$ represents a non-linear transformation that can be used in subsequent calculations or visualizations.\n\n## Parameters and Data\n- **computeDistance:** Boolean parameter (`d_computeDistance`) to determine whether rest lengths are set to zero or initial distances. If `true`, then each element's rest length is set to 0; otherwise, it uses the initial distances.\n- **showObjectScale:** Real number (`d_showObjectScale`) to adjust the scale for visual display of object mappings.\n- **showColor:** RGBAColor (`d_color`) to specify a color for displaying object mappings. Default value is yellow ([1.0, 1.0, 0.0, 1.0]).\n\n## Dependencies and Connections\nThe `DistanceMultiMapping` component requires multiple mechanical states (`BaseState`) to gather point positions and relies on a BaseMeshTopology container for topology information about edges that define the pairs of points used in distance calculations."
  }
}