CompareState

abstract: The `CompareState` component compares the current state (positions or velocities) of nodes in a mechanical model with reference states stored in a file at each timestep.
sheet: # CompareState ## Overview The `CompareState` component is used to compare the current positions and velocities of nodes in a mechanical model against reference values read from a file. This comparison helps validate simulations by quantifying discrepancies between expected and actual states. ## Mathematical Model The component calculates errors between the current state vectors \$\mathbf{A}\$ (positions or velocities) and the reference state vectors \$\mathbf{B}\$. The error is computed as: $$ e = \|\mathbf{A} - \mathbf{B}\| $$ The total errors are aggregated over time and across different nodes, with average per degree of freedom (DOF) errors calculated as: $$ \text{dofError}_X = \frac{\sum_{i=1}^{N} e_i}{N} $$ where \$N\$ is the number of degrees of freedom. The `draw` method provides a visual representation by drawing lines between current and reference positions, aiding in identifying discrepancies visually.

Component

{
  "Dependencies": [
    {
      "Component": "MechanicalModel",
      "Description": "Required for obtaining the state data (position and velocity) of degrees of freedom."
    }
  ],
  "Description": "The CompareState component is designed to compare the state (position and velocity) of a mechanical model against a reference stored in a file at each simulation step. This comparison can be useful for validation purposes, debugging, or assessing the accuracy of a simulation.",
  "Inheritance": [
    "ReadState"
  ],
  "Methods": {
    "draw": {
      "Description": "Visualizes differences between the reference state (\u0027X=\u0027 lines from the file) and the current simulation state. Lines connecting corresponding points are drawn, allowing visual inspection of discrepancies during a simulation run."
    },
    "handleEvent": {
      "Description": "Handles events such as \u0027AnimateBegin\u0027 and \u0027AnimateEnd\u0027. The primary action taken in response to an \u0027AnimateBegin\u0027 event is calling processCompareState() for state comparison at each simulation step."
    },
    "processCompareState": {
      "Description": "Performs the core comparison operation. It reads data from the specified file according to the current time (adjusted by any shift value) and compares this reference data with the actual position and velocity of the mechanical model\u0027s degrees of freedom. The results are accumulated in error metrics."
    }
  },
  "Name": "CompareState",
  "Namespace": "sofa::component::statecontainer",
  "Properties": {
    "filename": {
      "Description": "Path to the file containing the reference state data.",
      "Type": "string"
    },
    "listening": {
      "Default": false,
      "Description": "Whether this component should listen for events and update its state accordingly. By default, it\u0027s set to false since CompareState is typically used in conjunction with external functions.",
      "Type": "bool"
    },
    "shift": {
      "Default": 0.0,
      "Description": "Time shift applied when reading the reference data from the file.",
      "Type": "Real"
    }
  },
  "Usage": "This component is particularly useful for simulations where you need to validate the behavior against known or expected states. It can be used in conjunction with other components that generate or modify mechanical states."
}

maths: # Mathematical and Physical Description of the Compare State Component ## Overview The `CompareState` component in SOFA (Simulation Open Framework Architecture) is used to compare the current state of a mechanical model with reference states stored in a file. The comparison can be performed on position (`X`) or velocity (`V`) vectors, which are read from the file and compared with the current values within the simulation context. ## Mathematical Formulation The component performs two types of comparisons: 1. **Position Comparison**: This involves comparing the current positions of nodes in a mechanical model against reference positions stored in a file. 2. **Velocity Comparison**: Similarly, this compares the current velocities with reference velocities from the file. ### Position and Velocity Vectors - The position vector $\mathbf{X}$ is an array where each element represents the spatial coordinates of a node or point in the mechanical model. $$ \mathbf{X} = (x_1, y_1, z_1), (x_2, y_2, z_2), ..., (x_n, y_n, z_n) $$(where each triplet represents a node's position). - The velocity vector $\mathbf{V}$ is an array where each element represents the velocities of nodes in the mechanical model. $$ \mathbf{V} = (v_{x1}, v_{y1}, v_{z1}), (v_{x2}, v_{y2}, v_{z2}), ..., (v_{xn}, v_{yn}, v_{zn}) $$(where each triplet represents a node's velocity). ### Error Calculation The `CompareState` component calculates the error between the current state and the reference state. This is done by computing the difference between the current vector (position or velocity) $\mathbf{A}$ and the reference vector $\mathbf{B}$, where: $$ e = \|\mathbf{A} - \mathbf{B}\| $$ The norm used for computing the error can vary depending on the specific implementation, but typically involves element-wise differences. ### Error Aggregation The overall error is aggregated over time and across different nodes. The total errors are stored in `totalError_X` and `totalError_V`, while the average per degree of freedom (DOF) errors are calculated as: $$ \text{dofError}_X = \frac{\sum_{i=1}^{N} e_i}{N} $$ where $N$ is the number of degrees of freedom. ### Visualization The `draw` method provides a visual representation of the comparison by drawing lines between current and reference positions. This visualization helps in identifying discrepancies visually: $$ \text{lines} = \{(p_X, p_{RefX})\} $$ where $p_X$ is the position vector and $p_{RefX}$ is the corresponding reference position. ## Physical Interpretation The `CompareState` component serves as a diagnostic tool to ensure that a simulation's states (positions and velocities) match expected values from a file. This can be particularly useful in validating simulations against known datasets or comparing different simulation scenarios. The error metrics provide quantitative measures of the discrepancies, while the visualization helps users identify areas where significant differences exist.

{
  "name": "CompareState",
  "main": {
    "name": "CompareState",
    "namespace": "sofa::component::playback",
    "module": "Sofa.Component.Playback",
    "include": "sofa/component/playback/CompareState.h",
    "doc": "Compare State vectors from a reference frame to the associated Mechanical State.\n\nCompare State vectors from file at each timestep",
    "inherits": [
      "ReadState"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "handleEvent",
        "return_type": "void",
        "params": [
          {
            "name": "event",
            "type": "sofa::core::objectmodel::Event *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "processCompareState",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "canCreate",
        "return_type": "bool",
        "params": [
          {
            "name": "obj",
            "type": "T *&"
          },
          {
            "name": "context",
            "type": "core::objectmodel::BaseContext *"
          },
          {
            "name": "arg",
            "type": "core::objectmodel::BaseObjectDescription *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "getTotalError",
        "return_type": "double",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getErrorByDof",
        "return_type": "double",
        "params": [],
        "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": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "Component": {
      "Name": "CompareState",
      "Namespace": "sofa::component::statecontainer",
      "Description": "The CompareState component is designed to compare the state (position and velocity) of a mechanical model against a reference stored in a file at each simulation step. This comparison can be useful for validation purposes, debugging, or assessing the accuracy of a simulation.",
      "Inheritance": [
        "ReadState"
      ],
      "Properties": {
        "filename": {
          "Type": "string",
          "Description": "Path to the file containing the reference state data."
        },
        "listening": {
          "Type": "bool",
          "Default": false,
          "Description": "Whether this component should listen for events and update its state accordingly. By default, it's set to false since CompareState is typically used in conjunction with external functions."
        },
        "shift": {
          "Type": "Real",
          "Default": 0.0,
          "Description": "Time shift applied when reading the reference data from the file."
        }
      },
      "Methods": {
        "handleEvent": {
          "Description": "Handles events such as 'AnimateBegin' and 'AnimateEnd'. The primary action taken in response to an 'AnimateBegin' event is calling processCompareState() for state comparison at each simulation step."
        },
        "processCompareState": {
          "Description": "Performs the core comparison operation. It reads data from the specified file according to the current time (adjusted by any shift value) and compares this reference data with the actual position and velocity of the mechanical model's degrees of freedom. The results are accumulated in error metrics."
        },
        "draw": {
          "Description": "Visualizes differences between the reference state ('X=' lines from the file) and the current simulation state. Lines connecting corresponding points are drawn, allowing visual inspection of discrepancies during a simulation run."
        }
      },
      "Usage": "This component is particularly useful for simulations where you need to validate the behavior against known or expected states. It can be used in conjunction with other components that generate or modify mechanical states.",
      "Dependencies": [
        {
          "Component": "MechanicalModel",
          "Description": "Required for obtaining the state data (position and velocity) of degrees of freedom."
        }
      ]
    }
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of the Compare State Component\n\n## Overview\nThe `CompareState` component in SOFA (Simulation Open Framework Architecture) is used to compare the current state of a mechanical model with reference states stored in a file. The comparison can be performed on position (`X`) or velocity (`V`) vectors, which are read from the file and compared with the current values within the simulation context.\n\n## Mathematical Formulation\nThe component performs two types of comparisons:\n1. **Position Comparison**: This involves comparing the current positions of nodes in a mechanical model against reference positions stored in a file.\n2. **Velocity Comparison**: Similarly, this compares the current velocities with reference velocities from the file.\n\n### Position and Velocity Vectors\n- The position vector \\(\\mathbf{X}\\) is an array where each element represents the spatial coordinates of a node or point in the mechanical model.\n  $$\n  \\mathbf{X} = (x_1, y_1, z_1), (x_2, y_2, z_2), ..., (x_n, y_n, z_n)\n  $$(where each triplet represents a node's position).\n- The velocity vector \\(\\mathbf{V}\\) is an array where each element represents the velocities of nodes in the mechanical model.\n  $$\n  \\mathbf{V} = (v_{x1}, v_{y1}, v_{z1}), (v_{x2}, v_{y2}, v_{z2}), ..., (v_{xn}, v_{yn}, v_{zn})\n  $$(where each triplet represents a node's velocity).\n\n### Error Calculation\nThe `CompareState` component calculates the error between the current state and the reference state. This is done by computing the difference between the current vector (position or velocity) \\(\\mathbf{A}\\) and the reference vector \\(\\mathbf{B}\\), where:\n$$\n  e = \\|\\mathbf{A} - \\mathbf{B}\\|\n$$\nThe norm used for computing the error can vary depending on the specific implementation, but typically involves element-wise differences.\n\n### Error Aggregation\nThe overall error is aggregated over time and across different nodes. The total errors are stored in `totalError_X` and `totalError_V`, while the average per degree of freedom (DOF) errors are calculated as:\n$$\n  \\text{dofError}_X = \\frac{\\sum_{i=1}^{N} e_i}{N}\n$$\nwhere \\(N\\) is the number of degrees of freedom.\n\n### Visualization\nThe `draw` method provides a visual representation of the comparison by drawing lines between current and reference positions. This visualization helps in identifying discrepancies visually:\n$$\n  \\text{lines} = \\{(p_X, p_{RefX})\\}\n$$\nwhere \\(p_X\\) is the position vector and \\(p_{RefX}\\) is the corresponding reference position.\n\n## Physical Interpretation\nThe `CompareState` component serves as a diagnostic tool to ensure that a simulation's states (positions and velocities) match expected values from a file. This can be particularly useful in validating simulations against known datasets or comparing different simulation scenarios. The error metrics provide quantitative measures of the discrepancies, while the visualization helps users identify areas where significant differences exist."
  },
  "summary": {
    "abstract": "The `CompareState` component compares the current state (positions or velocities) of nodes in a mechanical model with reference states stored in a file at each timestep.",
    "sheet": "# CompareState\n\n## Overview\nThe `CompareState` component is used to compare the current positions and velocities of nodes in a mechanical model against reference values read from a file. This comparison helps validate simulations by quantifying discrepancies between expected and actual states.\n\n## Mathematical Model\nThe component calculates errors between the current state vectors \\\\(\\mathbf{A}\\\\) (positions or velocities) and the reference state vectors \\\\(\\mathbf{B}\\\\). The error is computed as:\n$$\ne = \\|\\mathbf{A} - \\mathbf{B}\\|\n$$\nThe total errors are aggregated over time and across different nodes, with average per degree of freedom (DOF) errors calculated as:\n$$\n\\text{dofError}_X = \\frac{\\sum_{i=1}^{N} e_i}{N}\n$$\nwhere \\\\(N\\\\) is the number of degrees of freedom. The `draw` method provides a visual representation by drawing lines between current and reference positions, aiding in identifying discrepancies visually."
  }
}