Mathematical and Physical Description of the Context Component

Data Fields

Methods

{
  "name": "Context",
  "namespace": "sofa::core::objectmodel",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/objectmodel/Context.h",
  "doc": "Implementation of BaseContext, storing all shared parameters in Datas.",
  "inherits": [
    "BaseContext"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "is_activated",
      "type": "bool",
      "xmlname": "activated",
      "help": "To Activate a node"
    },
    {
      "name": "worldGravity_",
      "type": "Vec3",
      "xmlname": "gravity",
      "help": "Gravity in the world coordinate system"
    },
    {
      "name": "dt_",
      "type": "SReal",
      "xmlname": "dt",
      "help": "Time step"
    },
    {
      "name": "time_",
      "type": "SReal",
      "xmlname": "time",
      "help": "Current time"
    },
    {
      "name": "animate_",
      "type": "bool",
      "xmlname": "animate",
      "help": "Animate the Simulation(applied at initialization only)"
    },
    {
      "name": "d_isSleeping",
      "type": "bool",
      "xmlname": "sleeping",
      "help": "The node is sleeping, and thus ignored by visitors."
    },
    {
      "name": "d_canChangeSleepingState",
      "type": "bool",
      "xmlname": "canChangeSleepingState",
      "help": "The node can change its sleeping state."
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "isActive",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setActive",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isSleeping",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "canChangeSleepingState",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getGravity",
      "return_type": "const Vec3 &",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setGravity",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const Vec3 &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getDt",
      "return_type": "SReal",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTime",
      "return_type": "SReal",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAnimate",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDt",
      "return_type": "void",
      "params": [
        {
          "name": "dt",
          "type": "SReal"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTime",
      "return_type": "void",
      "params": [
        {
          "name": "t",
          "type": "SReal"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setAnimate",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setSleeping",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setChangeSleepingState",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDisplayWorldGravity",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "copyContext",
      "return_type": "void",
      "params": [
        {
          "name": "c",
          "type": "const Context &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "copySimulationContext",
      "return_type": "void",
      "params": [
        {
          "name": "c",
          "type": "const Context &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": {
    "brief": "The `Context` class in the SOFA framework is an implementation of `BaseContext`, which stores all shared parameters as Data objects.",
    "details": [
      "### Purpose",
      "- The `Context` class manages simulation and visualization context variables such as activation state, sleeping state, gravity, time step, current time, and animation flag.",
      "",
      "### Parameters",
      "- **Activation State**: Controls whether the node is active or not using `is_activated` (boolean Data object). This can be queried and set via `isActive()` and `setActive()`, respectively.",
      "- **Sleeping State**: Indicates if the node is sleeping and ignored by visitors, managed through `d_isSleeping` (boolean Data object), accessed with `isSleeping()` and modified using `setSleeping()`. The ability to change its sleeping state is controlled by `d_canChangeSleepingState`, queried with `canChangeSleepingState()` and set via `setChangeSleepingState()`.",
      "- **Gravity**: Represents gravity in the world coordinate system, stored as a `Vec3` Data object (`worldGravity_`). It can be retrieved using `getGravity()` and updated with `setGravity()`. The default value is `(0, -9.81, 0)` representing standard Earth gravity.",
      "- **Time Step (dt)**: Defines the simulation time step as an SReal (scalar real) Data object (`dt_`). It can be queried using `getDt()` and set with `setDt()`. The default value is `0.01`.",
      "- **Current Time**: Tracks the current simulation time, also stored as an SReal Data object (`time_`). Accessible via `getTime()` and modifiable through `setTime()`. It defaults to `0.`.",
      "- **Animation Flag**: Indicates whether the simulation should animate (boolean Data object `animate_`), which can be queried with `getAnimate()` but cannot be set directly due to its read-only state after initialization.",
      "",
      "### State Management Functions",
      "- The class provides methods for querying and setting activation (`isActive()`, `setActive()`), sleeping (`isSleeping()`, `setSleeping()`), and the ability to change the sleeping state (`canChangeSleepingState()`, `setChangeSleepingState()`). Additionally, gravity, time step, current time, and animation flag can be queried and set using their respective getter and setter methods.",
      "",
      "### Context Copy Functions",
      "- **copyContext**: Copies all context variables from another instance of `Context` to the current one. This function calls `copySimulationContext`, which specifically copies simulation-related parameters including gravity, time step, current time, and animation flag.",
      "- **copySimulationContext**: Specifically handles copying only the simulation context parameters (gravity, dt, time, animate) from another `Context` instance.",
      "",
      "### Constructor and Destructor",
      "- The constructor initializes all Data objects with default values. Activation (`is_activated`) is set to true by default. Gravity (`worldGravity_`) defaults to `(0, -9.81, 0)` (Earth gravity). Time step (`dt_`) and current time (`time_`) are initialized to `0.01` and `0.` respectively.",
      "- The destructor is empty but virtual to ensure proper cleanup in derived classes."
    ]
  },
  "maths": "# Mathematical and Physical Description of the Context Component\n\n## Overview\nThe `Context` class in the SOFA framework manages various simulation context parameters, including activation state, sleeping state, gravity, time step, current time, and animation flag. These parameters are essential for controlling the behavior of physical simulations within the framework.\n\n## Parameters and Their Mathematical Representations\n1. **Activation State (`is_activated`)**:\n   - This boolean parameter controls whether the simulation node is active or not. Mathematically, this can be represented as a binary variable \\( A \\) where:\n     \\[ A =\n     \\begin{cases}\n       1 & \\text{if the context is activated} \\\\\n       0 & \\text{otherwise}\n     \\end{cases}\\]\n   - This variable can be queried using `isActive()` and set via `setActive()`. For instance, setting \\( A = 1 \\) activates the node.\n\n2. **Sleeping State (`d_isSleeping`)**:\n   - This boolean parameter indicates whether the context is in a sleeping state where it is ignored by visitors during simulation. Mathematically, this can be represented as another binary variable \\( S \\):\n     \\[ S =\n     \\begin{cases}\n       1 & \\text{if the context is sleeping} \\\\\n       0 & \\text{otherwise}\n     \\end{cases}\\]\n   - This state can be checked using `isSleeping()` and set via `setSleeping()`. For example, setting \\( S = 1 \\) puts the node to sleep.\n\n3. **Ability to Change Sleeping State (`d_canChangeSleepingState`)**:\n   - Another boolean parameter that controls whether the sleeping state can be changed during the simulation. This is represented as a binary variable \\( C \\):\n     \\[ C =\n     \\begin{cases}\n       1 & \\text{if the context can change its sleeping state} \\\\\n       0 & \\text{otherwise}\n     \\end{cases}\\]\n   - This state can be checked using `canChangeSleepingState()` and set via `setChangeSleepingState()`. For instance, setting \\( C = 1 \\) allows changes to the sleeping state.\n\n4. **Gravity (`worldGravity_`)**:\n   - Gravity is represented as a vector in three-dimensional space with components along the x, y, and z axes. The gravity vector \\( G \\) can be expressed as:\n     \\[ G = (G_x, G_y, G_z)\\]\n   - By default, gravity on Earth at sea level is approximated by \\( G = (0, -9.81, 0) \\), where \\( G_y = -9.81 \text{ m/s}^2 \\) represents the standard gravitational acceleration.\n   - The gravity vector can be retrieved using `getGravity()` and updated with `setGravity()`. For example, setting \\( G = (0, -9.81, 0) \\) simulates Earth's gravity.\n\n5. **Time Step (`dt_`)**:\n   - This parameter represents the simulation time step, which is a scalar real number denoted as \\( \triangle t \\). It controls how finely the time is divided in the simulation.\n     \\[ \triangle t = dt\\]\n   - By default, \\( \triangle t = 0.01 \\) seconds. This parameter can be queried using `getDt()` and set with `setDt()`. For instance, setting \\( \triangle t = 0.01 \\) divides the simulation into steps of 0.01 seconds.\n\n6. **Current Time (`time_`)**:\n   - Represents the current time in the simulation as a scalar real number denoted by \\( T \\). This variable can be retrieved using `getTime()` and updated with `setTime()`. For example, setting \\( T = t \\) updates the current time to \\( t \\).\n     \\[ T = time\\]\n\n7. **Animation Flag (`animate_`)**:\n   - A boolean parameter that indicates whether the simulation should animate or not. This is represented as a binary variable \\( An \\):\n     \\[ An =\n     \\begin{cases}\n       1 & \\text{if the context animates} \\\\\n       0 & \\text{otherwise}\n     \\end{cases}\\]\n   - The animation flag can be queried using `getAnimate()`. Note that this parameter is read-only after initialization, meaning it cannot be directly set.\n\n## Context Copy Functions\n- **copyContext**: This function copies all context variables from another instance of the `Context` class to the current one. It ensures consistency between different contexts by copying parameters such as gravity, time step, and animation flag.\n   - Mathematically, if \\( C_1 = (A_1, S_1, C_1, G_1, \triangle t_1, T_1) \\) is the context of instance 1 and \\( C_2 = (A_2, S_2, C_2, G_2, \triangle t_2, T_2) \\) is the current context, then:\n     \\[ C_2 \\leftarrow C_1\\]\n- **copySimulationContext**: This function specifically copies only the simulation-related parameters (gravity, time step, and animation flag) from another instance.\n   - Mathematically, if \\( S_1 = (\triangle t_1, T_1, G_1) \\) is the simulation context of instance 1 and \\( S_2 = (\triangle t_2, T_2, G_2) \\) is the current context's simulation context:\n     \\[ S_2 \\leftarrow S_1\\]\n\n## Constructor and Destructor\n- **Constructor**: Initializes all parameters to their default values. For example:\n   - Activation state: \\( A = 1 \\)\n   - Gravity: \\( G = (0, -9.81, 0) \\)\n   - Time step: \\( \triangle t = 0.01 \\)\n   - Current time: \\( T = 0 \\)\n- **Destructor**: Ensures proper cleanup of the instance. Since it is virtual, derived classes can extend and customize the destructor to clean up their specific resources.\n\n## Summary\nThe `Context` class in SOFA provides a comprehensive management system for simulation context parameters using mathematical representations that are essential for controlling physical simulations.",
  "abstract": "`Context` manages simulation context parameters including activation state, sleeping state, gravity, time step, current time, and animation flag in SOFA simulations.",
  "sheet": "# Context\n\n## Overview\nThe `Context` class is an implementation of `BaseContext`, managing essential simulation context parameters such as activation state, sleeping state, gravity, time step, current time, and animation flag. It provides methods to query and set these parameters.\n\n## Parameters and Data\n- **Activation State (`is_activated`)**: Controls whether the node is active or not (default: `true`).\n- **Sleeping State (`d_isSleeping`)**: Indicates if the node is sleeping and ignored by visitors (default: `false`).\n- **Ability to Change Sleeping State (`d_canChangeSleepingState`)**: Determines if the sleeping state can be changed during simulation (default: `true`).\n- **Gravity (`worldGravity_`)**: Represents gravity in the world coordinate system, default value is `(0, -9.81, 0)`.\n- **Time Step (`dt_`)**: Defines the simulation time step (default: `0.01`).\n- **Current Time (`time_`)**: Tracks the current simulation time (default: `0.`).\n- **Animation Flag (`animate_`)**: Indicates whether the simulation should animate (read-only after initialization, default: `true`).\n\n## Practical Notes\nThe animation flag is read-only after initialization and cannot be directly set. The gravity vector defaults to Earth's standard gravitational acceleration."
}