Methods

{
  "name": "NumericTest",
  "namespace": "sofa::testing",
  "module": "Sofa.framework.Testing",
  "include": "sofa/testing/NumericTest.h",
  "doc": "Helper functions to compare scalars, vectors, matrices, etc.",
  "inherits": [
    "BaseTest"
  ],
  "templates": [
    "double",
    "float"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "epsilon",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "infinity",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "isSmall",
      "return_type": "bool",
      "params": [
        {
          "name": "r",
          "type": "Real"
        },
        {
          "name": "ratio",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "vectorMaxDiff",
      "return_type": "Real",
      "params": [
        {
          "name": "m1",
          "type": "const sofa::type::Vec<N, Real> &"
        },
        {
          "name": "m2",
          "type": "const Vector2 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "vectorMaxDiff",
      "return_type": "Real",
      "params": [
        {
          "name": "m1",
          "type": "const sofa::type::Vec<N, Real> &"
        },
        {
          "name": "m2",
          "type": "const sofa::type::Vec<N, Real> &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "vectorMaxDiff",
      "return_type": "Real",
      "params": [
        {
          "name": "c1",
          "type": "const Container1 &"
        },
        {
          "name": "c2",
          "type": "const Container2 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "vectorMaxAbs",
      "return_type": "Real",
      "params": [
        {
          "name": "c",
          "type": "const Container &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "matrixMaxDiff",
      "return_type": "Real",
      "params": [
        {
          "name": "m1",
          "type": "const Matrix1 &"
        },
        {
          "name": "m2",
          "type": "const Matrix2 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "matrixMaxDiff",
      "return_type": "Real",
      "params": [
        {
          "name": "m1",
          "type": "const sofa::type::Mat<M, N, Real> &"
        },
        {
          "name": "m2",
          "type": "const Matrix2 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "norm",
      "return_type": "float",
      "params": [
        {
          "name": "a",
          "type": "float"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "name": "norm",
      "return_type": "double",
      "params": [
        {
          "name": "a",
          "type": "double"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "name": "norm",
      "return_type": "Real",
      "params": [
        {
          "name": "a",
          "type": "T"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    }
  ],
  "component": {
    "name": "NumericTest",
    "description": "The NumericTest is a C++ template class used for numerical comparison and testing in the SofaPhysics framework, which is a physics simulation library. This class provides methods to compare matrices and vectors with floating-point values within a certain tolerance level, facilitating unit tests for numerical computations.",
    "properties": {
      "template_class": "NumericTest is defined as a template class that can work with different data types. It accepts a single type parameter, _DataTypes, which determines the precision (float or double) used for comparisons.",
      "static_methods": [
        {
          "name": "matrixMaxDiff",
          "description": "A static method that calculates and returns the maximum difference between corresponding elements of two matrices. It also checks if the sizes of both matrices are equal; if not, it logs a failure message.",
          "parameters": [
            "const Matrix1& m1",
            "const Matrix2& m2"
          ],
          "return_type": "Real"
        },
        {
          "name": "matrixMaxDiff",
          "description": "Another static method that calculates the maximum difference between elements of two matrices. This version specifically works with matrices defined as sofa::type::Mat<M,N,Real> and another generic matrix type.",
          "parameters": [
            "const sofa::type::Mat<M,N,Real>& m1",
            "const Matrix2& m2"
          ],
          "return_type": "Real"
        },
        {
          "name": "vecCoord_to_vector",
          "description": "A static method that converts a vector of coordinates (VecCoord) into a one-dimensional vector of scalars. It resizes the output vector and copies all elements from VecCoord to the scalar vector.",
          "parameters": [
            "VectorOfScalars& vec",
            "const VecCoord& vcoord"
          ],
          "return_type": "void"
        },
        {
          "name": "vecDeriv_to_vector",
          "description": "A static method that converts a vector of derivatives (VecDeriv) into a one-dimensional vector of scalars. It resizes the output vector and copies all elements from VecDeriv to the scalar vector.",
          "parameters": [
            "VectorOfScalars& vec",
            "const VecDeriv vderiv"
          ],
          "return_type": "void"
        }
      ],
      "macros": [
        {
          "name": "EXPECT_FLOATINGPOINT_EQ",
          "description": "A macro that checks if two floating-point numbers are equal within a certain tolerance. It's a generic version of Google Test's EXPECT_FLOAT_EQ and EXPECT_DOUBLE_EQ macros, making it suitable for use with template mechanisms.",
          "parameters": [
            "val1",
            "val2"
          ]
        },
        {
          "name": "ASSERT_FLOATINGPOINT_EQ",
          "description": "A macro that asserts if two floating-point numbers are equal within a certain tolerance. Similar to the EXPECT_FLOATINGPOINT_EQ macro, this is used for ensuring conditions in tests and fails when the condition isn't met.",
          "parameters": [
            "val1",
            "val2"
          ]
        }
      ],
      "template_specializations": [
        {
          "name": "NumericTest<float>",
          "description": "A template specialization of NumericTest for floating-point precision."
        },
        {
          "name": "NumericTest<double>",
          "description": "A template specialization of NumericTest for double precision."
        }
      ]
    }
  },
  "maths": "The `NumericTest` component is part of the SOFA testing framework, designed to provide helper functions for comparing scalars, vectors, matrices, and other numerical containers. This component does not directly contribute to the governing equations or operators typically found in a FEM simulation pipeline (such as mass matrix M, stiffness matrix K, internal force f_int, residual R, etc.). Instead, it serves a utility role within the broader framework by providing functions to assess the accuracy and consistency of numerical computations. Here is a detailed description of its mathematical and physical content:\n\n### Governing Equations or Operators\n- **None**: The `NumericTest` component does not directly implement any governing equations or operators relevant to FEM simulations.\n\n### Constitutive or Kinematic Laws Involved\n- **None**: There are no constitutive or kinematic laws involved in the `NumericTest` component.\n\n### Role in the Global FEM Pipeline\n- The `NumericTest` component does not play a role in the standard stages of an FEM pipeline (assembly, time integration, nonlinear solve, linear solve, constraint handling, mapping). It is primarily used for testing purposes and ensuring numerical consistency across various containers such as vectors and matrices.\n\n### Numerical Methods or Discretization Choices\n- **Comparison Functions**: The component provides functions to compute differences between scalar values, vectors, and matrices:\n  - `epsilon()`: Returns the smallest representable floating-point number (machine epsilon).\n  - `infinity()`: Returns positive infinity.\n  - `isSmall(r, ratio=1.)`: Determines if a given value `r` is small relative to machine epsilon (`std::numeric_limits<Real>::epsilon()`), scaled by an optional ratio.\n  - `vectorMaxDiff(m1, m2)`: Computes the maximum difference between corresponding entries of two vectors or containers. Issues a failure if sizes are different.\n  - `vectorMaxAbs(c)`: Returns the maximum absolute value within a container.\n  - `matrixMaxDiff(m1, m2)`: Computes the maximum difference between corresponding entries of two matrices. Issues a failure if dimensions do not match.\n\n### How the Component Fits into the Broader Variational / Lagrangian Mechanics Framework\n- **Testing Utility**: The `NumericTest` component serves as a utility for testing and validating numerical computations within SOFA simulations. It ensures that various containers (scalars, vectors, matrices) are correctly handled in terms of their values and comparisons.\n\n### Summary\nThe `NumericTest` is purely a helper class designed to facilitate the comparison of numerical data types within the SOFA framework. It does not contribute directly to any FEM-specific equations or physical laws but plays an essential role in ensuring the accuracy and consistency of numerical computations used throughout the simulation.",
  "abstract": "`NumericTest` provides helper functions for comparing scalars, vectors, matrices, and other numerical containers to ensure accuracy and consistency in numerical computations within SOFA simulations.",
  "sheet": "# NumericTest\n\n**Overview**\n\nThe `NumericTest` component is part of the SOFA testing framework. It serves as a utility class designed to facilitate the comparison of various numerical data types (scalars, vectors, matrices) to ensure accuracy and consistency in numerical computations within simulations.\n\n**Parameters and Data**\n\n- **epsilon()**: Returns the smallest representable floating-point number (machine epsilon).\n- **infinity()**: Returns positive infinity.\n- **isSmall(r, ratio=1.)**: Determines if a given value `r` is small relative to machine epsilon (`std::numeric_limits<Real>::epsilon()`), scaled by an optional ratio.\n- **vectorMaxDiff(m1, m2)**: Computes the maximum difference between corresponding entries of two vectors or containers. Issues a failure if sizes are different.\n- **vectorMaxAbs(c)**: Returns the maximum absolute value within a container.\n- **matrixMaxDiff(m1, m2)**: Computes the maximum difference between corresponding entries of two matrices. Issues a failure if dimensions do not match.\n\n**Dependencies and Connections**\n\nThe `NumericTest` component is primarily used for testing purposes and does not directly interact with other components in the SOFA scene graph. It inherits from the `BaseTest` class, which provides foundational testing utilities.\n\n**Practical Notes**\n\n- The `epsilon()` function returns machine epsilon, which is crucial for determining numerical precision limits.\n- The `infinity()` function can be used to represent unbounded values in tests.\n- The `isSmall(r, ratio=1.)` function helps in assessing whether a value is negligible relative to the machine's floating-point precision."
}