Mathematical and Physical Description of the BaseData Component in Sofa

Methods

{
  "name": "BaseData",
  "namespace": "sofa::core::objectmodel",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/objectmodel/BaseData.h",
  "doc": "Abstract base class for Data.",
  "inherits": [
    "DDGNode"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "setParent(BaseData*, string)",
      "description": "Links this data field to a parent data field. The value of this data will duplicate that of its parent."
    },
    {
      "name": "getParent()",
      "description": "Returns the BaseData that is set as the parent for automatic updates."
    },
    {
      "name": "update()",
      "description": "Updates the value of this data field, usually by copying from its parent if one is set."
    },
    {
      "name": "copyValueFrom(BaseData*)",
      "description": "Copies the value from another BaseData object into this instance in a one-time copy operation."
    },
    {
      "name": "getLinkPath()",
      "description": "Returns the path to this data field when used as a link."
    },
    {
      "name": "canBeLinked()",
      "description": "Checks whether this data field can be used for linking. By default returns true."
    },
    {
      "name": "setOwner(Base*)",
      "description": "Sets the owner component of this BaseData."
    },
    {
      "name": "isDisplayed()",
      "description": "Indicates if this data should be displayed in GUIs."
    },
    {
      "name": "isReadOnly()",
      "description": "Returns true if this data field is set to read-only."
    },
    {
      "name": "isPersistent()",
      "description": "Indicates whether the data contains persistent information which needs to be saved between sessions."
    },
    {
      "name": "getGroup()",
      "description": "Retrieves the group associated with this BaseData for organizational and display purposes in the UI."
    },
    {
      "name": "getWidget()",
      "description": "Gets the widget type used to interact with this data field in the user interface."
    },
    {
      "name": "decodeTypeName(type_info)",
      "description": "Returns a more readable version of the data's typename if possible."
    }
  ],
  "description": "The BaseData class represents a data field in Sofa (Simulation Open Framework Architecture) that can be linked, updated and modified within the simulation framework. It serves as an abstract base for specific data types like Vec3d, Real, etc., and provides common functionality needed across different types of data fields.",
  "attributes": [
    {
      "name": "help",
      "type": "string",
      "description": "A help message describing the purpose or function of this data field."
    },
    {
      "name": "ownerClass",
      "type": "string",
      "description": "The name of the owner class that this BaseData belongs to."
    },
    {
      "name": "group",
      "type": "string",
      "description": "The group this data field belongs to. Groups are used for organization and display purposes in the user interface."
    },
    {
      "name": "widget",
      "type": "string",
      "description": "Specifies which kind of widget should be used to interact with this data field in the user interface."
    },
    {
      "name": "m_counter",
      "type": "int",
      "description": "Keeps track of changes made since creation, useful for efficiently detecting modifications."
    },
    {
      "name": "m_isSet",
      "type": "bool",
      "description": "Indicates whether this data field is set (i.e., its value is different from the default)."
    },
    {
      "name": "m_dataFlags",
      "type": "DataFlags",
      "description": "Holds flags that indicate the purpose and behavior of the data field, such as whether it should be displayed in GUIs or if it contains persistent information."
    },
    {
      "name": "m_owner",
      "type": "Base*",
      "description": "Pointer to the Base component owning this data field."
    },
    {
      "name": "m_name",
      "type": "string",
      "description": "The name of this data field within its owner class."
    },
    {
      "name": "m_hasDefaultValue",
      "type": "bool",
      "description": "Indicates whether this data field has a default value set."
    },
    {
      "name": "parentData",
      "type": "DataLink<BaseData>",
      "description": "A link to the parent BaseData, used for setting up automatic updates based on changes in the parent data."
    }
  ],
  "details": "BaseData is an essential class within Sofa that provides a framework for managing different types of data fields. It includes common attributes and methods to support linking, updating, editing and displaying these fields in the user interface. Derived classes will implement specific functionality based on their type (e.g., integer, vector, matrix) while inheriting this shared base behavior.",
  "maths": "# Mathematical and Physical Description of the BaseData Component in Sofa\n\nThe `BaseData` class within the Sofa framework is an abstract base class that provides a common interface for managing data fields, including their values, links to parent data fields, updates, and modifications. This section offers both a mathematical and physical description of how the component operates.\n\n## Mathematical Description\n\n### Data Fields Representation\n\nEach `BaseData` instance represents a value that can be manipulated within a simulation framework. Mathematically, each data field is represented as a vector or scalar quantity depending on its type (e.g., Vec3d for 3D vectors and Real for real numbers). \n\nLet's denote the state of a `BaseData` object by $\\mathbf{v}$. The value of this data can be updated through various methods, such as setting it to a new value or copying from another data field.\n\n### Linking Mechanisms\n\nThe `setParent` method establishes a link between two data fields. If the child data field is linked to a parent, its value is automatically duplicated from the parent's value. This can be represented mathematically as:\n\\[\n\\mathbf{v}_{child} = \\mathbf{v}_{parent}\n\\]\n\n### Counting Updates and Modifications\n\nEach `BaseData` object maintains a counter $C$ that tracks the number of changes to its value since creation. This is useful for detecting modifications efficiently.\n\\[\nC_{new} = C_{old} + 1 \\quad \\text{if the data's value has changed}\n\\]\n\n### Setting and Unsetting Values\n\nThe `isSet` flag indicates whether the current value of the `BaseData` object is different from its default value. Mathematically, if $\\mathbf{v}_{default}$ denotes the default value:\n\\[\nisSet = \begin{cases} \n1 & \\text{if } \\mathbf{v} \\neq \\mathbf{v}_{default} \\\\ \n0 & \\text{otherwise}\n\\end{cases}\n\\]\n\n### Copying Values\n\nThe `copyValueFrom` method copies the value from another data field. If $\\mathbf{v}_s$ is the source data and $\\mathbf{v}_d$ is the destination (self):\n\\[\n\\mathbf{v}_d = \\mathbf{v}_s\n\\]\n\n## Physical Description\n\n### Data Field in Simulations\n\nIn physical simulations, `BaseData` objects represent various physical quantities such as positions, velocities, or forces. The data fields can be updated based on the physics engine's calculations.\n\n### Parent-Child Relationship\n\nWhen a child data field is linked to a parent, it ensures that any change in the parent’s value is propagated to the child, maintaining consistency across related data fields. This mechanism supports hierarchical and interconnected data structures within complex simulations.\n\n### Change Detection\n\nThe counter $C$ helps in detecting changes efficiently without having to check each value explicitly. In multi-threaded environments, this can be crucial for performance optimization.\n\n### Modification Tracking\n\nThe `isSet` flag is essential for tracking whether a particular data field has been modified from its default state, allowing the simulation engine to perform operations only on modified fields, thereby saving computational resources.",
  "abstract": "`BaseData` manages data fields within SOFA simulations by providing methods to link, update, and modify values.",
  "sheet": "# BaseData\n\n## Overview\n\nThe `BaseData` class serves as an abstract base for managing data fields in the SOFA framework. It provides common functionality needed across different types of data fields, including linking mechanisms, value updates, and modification tracking.\n\n## Parameters and Data\n\n- **Owner**: The owner object that holds this data field (`setOwner`, `getOwner`).\n- **Name**: The name of the data field (`setName`, `getName`).\n- **Value**: The current value of the data field (`getValueVoidPtr`, `beginEditVoidPtr`, `endEditVoidPtr`).\n- **Default Value**: The default value for the data field (`hasDefaultValue`, `forceSet`).\n- **Counter**: Tracks the number of changes to the data field's value since creation (`getCounter`).\n- **Flags**: Various flags indicating properties such as read-only, persistent, and displayed status (`isReadOnly`, `setReadOnly`, `isPersistent`, `setPersistent`, `isDisplayed`, `setDisplay`).\n- **Parent Link**: Establishes a link to a parent data field (`setParent`, `getParent`).\n- **Help Text**: Provides help text for the data field (`getHelp`, `setHelp`).\n- **Group and Widget**: Specifies group and widget settings (`getGroup`, `setGroup`, `getWidget`, `setWidget`)."
}