{
  "name": "DifferenceEngine",
  "main": {
    "name": "DifferenceEngine",
    "namespace": "sofa::component::engine::transform",
    "module": "Sofa.Component.Engine.Transform",
    "include": "sofa/component/engine/transform/DifferenceEngine.h",
    "doc": "Computing the difference between two vector of dofs.\n\nComputing the difference between two vector of dofs\noutput = input - substractor",
    "inherits": [
      "DataEngine"
    ],
    "templates": [
      "Vec1",
      "Vec3"
    ],
    "data_fields": [
      {
        "name": "d_input",
        "type": "VecData",
        "xmlname": "input",
        "help": "input vector"
      },
      {
        "name": "d_substractor",
        "type": "VecData",
        "xmlname": "substractor",
        "help": "vector to subtract to input"
      },
      {
        "name": "d_output",
        "type": "VecData",
        "xmlname": "output",
        "help": "output vector = input-substractor"
      }
    ],
    "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 **DifferenceEngine** is a component in the `sofa::component::engine::transform` namespace, part of the Sofa.Component.Engine.Transform module. This engine computes the difference between two vectors of degrees-of-freedom (DOFs). Specifically, it calculates the output vector as the result of subtracting one input vector from another. The DifferenceEngine inherits from DataEngine and operates on templated types Vec1 and Vec3.\n\n### Role in SOFA Ecosystem:\nDifferenceEngine is used to perform basic arithmetic operations between vectors within a simulation setup. It computes `output = input - substractor`, where both the input and subtractor are vectors of DOFs.\n\n### Interactions with Other Components:\nThe DifferenceEngine interacts primarily through its data fields, which include:\n- **input**: The primary vector for the difference operation.\n- **substractor**: The vector to be subtracted from `input`.\n- **output**: The resulting difference vector after subtraction.\n\n### Practical Usage Guidance and Data Fields:\nThe component requires both input vectors (`input` and `substractor`) to have the same size. If they do not match, a warning message is logged, and the operation aborts. After initialization or reinitialization via `init()` and `reinit()`, the actual difference computation occurs in the `doUpdate()` method."
  },
  "maths": {
    "maths": "The **DifferenceEngine** in the `sofa::component::engine::transform` namespace is designed to perform element-wise subtraction between two vectors. The primary mathematical operation it performs can be described as follows:\n\n### Mathematical Operation\nGiven two input vectors \\(\boldsymbol{a}\\) and \\(\boldsymbol{b}\\), both of which are vectors with the same dimension, the DifferenceEngine computes a new vector \\(\boldsymbol{c}\\) such that:\n\n\begin{equation}\n\\boldsymbol{c} = \\boldsymbol{a} - \\boldsymbol{b},\n\tag{1}\n\text{where } c_i = a_i - b_i \text{ for each element } i.\n\tag{2}\n\text{Here, } i = 0, 1, ..., n-1 \text{ where } n \\text{ is the dimension of the vectors}.\n\tag{3}\n\text{The component ensures that both input vectors have the same size before performing the subtraction. If they do not match in size, an error message is logged and the operation aborts.}\n\tag{4}\n\n### Role in SOFA Ecosystem\n- **Input Vectors**: The DifferenceEngine takes two input vectors \\(\boldsymbol{a}\\) (denoted as `input`) and \\(\boldsymbol{b}\\) (denoted as `substractor`), both of which are expected to have the same size.\n- **Output Vector**: The output vector \\(\boldsymbol{c}\\) is computed as \\(\\boldsymbol{a} - \\boldsymbol{b}\\) and stored in the data field `output`.\n\n### Practical Usage Guidance and Data Fields\nThe component has three primary data fields:\n1. **input (\\(\boldsymbol{a}\\))**: The input vector from which another vector is subtracted.\n2. **substractor (\\(\boldsymbol{b}\\))**: The vector to be subtracted from the `input` vector.\n3. **output (\\(\boldsymbol{c}\\))**: The resulting difference vector after the subtraction operation.\n\n### Interactions with Other Components\nThe DifferenceEngine interacts through its data fields and methods:\n- **init()**: Marks the component as dirty, indicating that it needs to be updated.\n- **reinit()**: Calls `doUpdate()` to ensure the computation is performed again.\n- **doUpdate()**: The actual subtraction operation takes place here. It reads the input vectors, checks their sizes, and performs element-wise subtraction if they match in size.\n\n### Example Usage\nSuppose \\(\boldsymbol{a} = [1, 2, 3]\\) and \\(\boldsymbol{b} = [4, 5, 6]\\). The DifferenceEngine will compute:\n\begin{align*}\n\\boldsymbol{c} &= [1 - 4, 2 - 5, 3 - 6] \\\\\n&= [-3, -3, -3].\n\tag{5}\n\text{The resulting vector } \\boldsymbol{c} = [-3, -3, -3]\\) is stored in the `output` data field.\n\nThis component is useful for basic arithmetic operations within a simulation setup where element-wise subtraction of vectors is required."
  },
  "summary": {
    "abstract": "The DifferenceEngine computes the element-wise subtraction between two vectors of degrees-of-freedom (DOFs), storing the result in an output vector.",
    "sheet": "# DifferenceEngine\n\n## Overview\nDifferenceEngine is a component that performs element-wise subtraction between two input vectors of DOFs, producing an output vector. It inherits from DataEngine and operates on templated types Vec1 and Vec3.\n\n## Parameters and Data\nThe significant data fields are:\n- **input**: The primary vector for the difference operation.\n- **substractor**: The vector to be subtracted from `input`.\n- **output**: The resulting difference vector after subtraction.\n\n## Dependencies and Connections\nDifferenceEngine interacts through its data fields, requiring both input vectors (`input` and `substractor`) to have the same size. If they do not match in size, a warning message is logged, and the operation aborts.\n\n## Practical Notes\nThe component ensures that both input vectors have the same size before performing the subtraction. The actual computation occurs in the `doUpdate()` method after initialization or reinitialization via `init()` and `reinit()`. If the sizes of the input vectors do not match, an error message is logged and the operation aborts."
  }
}