Mathematical and Physical Description of BatchGUI Component

Methods

{
  "name": "BatchGUI",
  "namespace": "sofa::gui::batch",
  "module": "Sofa.GUI.Batch",
  "include": "sofa/gui/batch/BatchGUI.h",
  "doc": "",
  "inherits": [
    "BaseGUI"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "setScene",
      "return_type": "void",
      "params": [
        {
          "name": "groot",
          "type": "sofa::simulation::NodeSPtr"
        },
        {
          "name": "filename",
          "type": "const char *"
        },
        {
          "name": "temporaryFile",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "resetScene",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "mainLoop",
      "return_type": "int",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "redraw",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "closeGUI",
      "return_type": "int",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "currentSimulation",
      "return_type": "sofa::simulation::Node *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "CreateGUI",
      "return_type": "BaseGUI *",
      "params": [
        {
          "name": "name",
          "type": "const char *"
        },
        {
          "name": "groot",
          "type": "sofa::simulation::NodeSPtr"
        },
        {
          "name": "filename",
          "type": "const char *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "RegisterGUIParameters",
      "return_type": "int",
      "params": [
        {
          "name": "argumentParser",
          "type": "common::ArgumentParser *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "OnNbIterChange",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const common::ArgumentParser *"
        },
        {
          "name": "strValue",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "canBeDefaultGUI",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "startDumpVisitor",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "stopDumpVisitor",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "canExportJson",
      "return_type": "bool",
      "params": [
        {
          "name": "timerOutputStr",
          "type": "const int &"
        },
        {
          "name": "timerId",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "name": "exportJson",
      "return_type": "void",
      "params": [
        {
          "name": "timerOutputStr",
          "type": "const int &"
        },
        {
          "name": "iterationNumber",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `BatchGUI` component in SOFA is designed for batch processing simulations without graphical user interface interaction. It inherits from the `BaseGUI` class and is part of the `Sofa.GUI.Batch` module, providing functionality to set up scenes, execute simulation iterations, and manage timers and progress bars.\n\n### Role and Purpose\nThe primary role of `BatchGUI` is to enable non-interactive batch processing of SOFA simulations. It allows setting the scene with a root node and a filename for input data, iterating through the simulation steps without visual output, and handling timer and JSON export functionalities.\n\n### Interactions with Other Components\n- **BaseGUI Interface**: `BatchGUI` implements methods from the `BaseGUI` interface such as `mainLoop`, `redraw`, and `closeGUI` to ensure compatibility and consistency within SOFA's architecture.\n- **ArgumentParser**: It registers GUI parameters for the number of iterations (`nbIter`) and controls hiding progress bar via the `common::ArgumentParser` class.\n- **Simulation Node**: The component interacts with the simulation node through methods like `setScene`, `resetScene`, and accessing the current simulation to manage the state of the scene during batch processing.\n\n### Practical Usage Guidance\nTo use `BatchGUI`, initialize it by setting the scene with a root node and filename. Use the `mainLoop` method to execute the specified number of iterations (or infinite if set). The component also allows exporting timer data in JSON format at specific intervals and provides progress bar functionality.\n\n### Data Fields\n- **groot**: A shared pointer to the simulation node, representing the root of the scene hierarchy.\n- **filename**: String for specifying input or output file names.\n- **nbIter**: Number of iterations for batch processing (default is 1000; -1 indicates infinite iteration).\n- **m_dumpVisitorStream**: Stream for dumping visitor information.",
  "maths": "# Mathematical and Physical Description of BatchGUI Component\n\n## Overview\nThe `BatchGUI` component in the SOFA (Simulation Open-Framework Architecture) framework is designed for non-interactive batch processing simulations. It allows users to run multiple iterations of a simulation without requiring a graphical user interface, enabling efficient execution on high-performance computing resources.\n\n### Mathematical Model\n#### Simulation Iterations\nThe core functionality of `BatchGUI` revolves around executing multiple iterations of the simulation. Let's denote:\n- $t$ as the current time step,\n- $N_{iter}$ as the number of iterations to run (default is 1000 or can be set to -1 for infinite iteration).\n\nThe primary loop in `BatchGUI::mainLoop()` executes a series of steps for each iteration:\n\n1. **Scene Reset**: At the beginning, if the scene needs to be reset, it sets the simulation time $t$ back to 0 and resets all state variables (e.g., positions, velocities) using:\n   \\[ t = 0 \\]\n2. **Simulation Update**:\n   - For each iteration $i$, from 1 to $N_{iter}$, it advances the simulation by calling `sofa::simulation::node::reset(root)` and updates the scene state.\n3. **Progress Tracking**: A progress bar can be optionally enabled to track the progress of iterations.\n\n#### JSON Export Mechanism\nFor each iteration, if timer data needs to be exported in JSON format, it follows these steps:\n1. **JSON Output Type Check**:\n   - The method `canExportJson(timerOutputStr, timerId)` checks whether the timer output is configured for JSON export and verifies that the output string is not empty.\n2. **File Creation**:\n   - If the conditions are met, a JSON file named with an iteration-specific identifier (e.g., `filename_000001.json`) is created and written using the method `exportJson(timerOutputStr, iterationNumber)`.\n\n### Physical Model\n#### Scene Management\nThe scene management involves setting up and manipulating simulation nodes. The component interacts with a root node of the scene hierarchy (denoted as `groot`), which can be defined by the user or loaded from an input file (`filename`).\n- **setScene** method sets the simulation context by assigning the root node to `groot` and storing the filename.\n\n#### Timer Management\nTimers are used for performance monitoring. The component supports dumping timer information using:\n1. **Start Dumping Visitor Information**: Begins capturing visitor statistics in a stream (`m_dumpVisitorStream`) via `startDumpVisitor()` method.\n2. **Stop Dumping Visitor Information**: Stops capturing and flushes the captured data to ensure proper logging of performance metrics during each iteration.\n\n### Interaction with Other Components\n- **ArgumentParser**: Used for registering GUI parameters such as `nbIter` (number of iterations) and hiding progress bar functionality via user-defined arguments.\n- **Simulation Node**: Interacts with the simulation node through methods like `setScene`, `resetScene`, and accessing the current simulation to manage scene state during batch processing.",
  "abstract": "`BatchGUI` enables non-interactive batch processing of SOFA simulations by setting up scenes, executing iterations, and managing timers and JSON exports.",
  "sheet": "# BatchGUI\n\n## Overview\nThe `BatchGUI` component in the SOFA framework is designed for non-interactive batch processing of simulations. It inherits from the `BaseGUI` class and provides methods to set up scenes, execute simulation iterations, manage timers, and export timer data in JSON format.\n\n## Parameters and Data\n- **groot**: A shared pointer to the root node of the scene hierarchy (`sofa::simulation::NodeSPtr`).\n- **filename**: String for specifying input or output file names (`const char *`).\n- **nbIter**: Number of iterations for batch processing (default is 1000; -1 indicates infinite iteration) (`int`).\n\n## Dependencies and Connections\n- **BaseGUI Interface**: Implements methods from the `BaseGUI` interface such as `mainLoop`, `redraw`, and `closeGUI`.\n- **ArgumentParser**: Registers GUI parameters for the number of iterations (`nbIter`) and controls hiding progress bar functionality via the `common::ArgumentParser` class.\n- **Simulation Node**: Interacts with the simulation node through methods like `setScene`, `resetScene`, and accessing the current simulation to manage scene state during batch processing."
}