WriteState

sofa::component::playback::WriteState

BaseObject

Doc (from source)

Write State vectors to file at each timestep. Write State vectors to file at a given set of time instants A period can be established at the last time instant The DoFs to print can be chosen using DOFsX and DOFsV Stop to write the state if the kinematic energy reach a given threshold (stopAt) The energy will be measured at each period determined by keperiod

Abstract (AI generated)

`WriteState` outputs state vectors (position, velocity, force) to file at specified times or periodically during a simulation run.

Metadata

module

Sofa.Component.Playback

namespace

sofa::component::playback

include

sofa/component/playback/WriteState.h

inherits

BaseObject

description

The WriteState component in the SOFA framework is designed to output state vectors (position, velocity, force) to file at specified time instants or at periodic intervals during a simulation run. It writes these data points into files for later analysis or playback. This component does not contribute directly to any governing equations or operators such as mass matrix $M$, stiffness matrix $K$, internal forces $f_{int}$, residual $R$, etc., but rather serves as an output mechanism that interacts with the mechanical state of a simulation to retrieve and write these vectors at specified times. Here is a detailed description of its role and functionality within the broader FEM pipeline:

Role in the Global FEM Pipeline

Assembly: WriteState does not participate directly in the assembly phase, as it does not contribute to constructing the global mass matrix $M$, internal force vector $f_{int}$, or residual $R$.
Time Integration: It interacts with time integration schemes by listening for events such as AnimateBeginEvent, which indicate that a new simulation step has begun. At these times, it checks if state vectors should be written to file based on predefined conditions (e.g., periodic intervals or at specific time instants).
Nonlinear Solve: It does not influence the nonlinear solution process but can provide outputs from the current state after each iteration.
Linear Solve: Similarly, it does not participate in the linear solve phase, only retrieving and writing state vectors post-solve.
Constraint Handling: Although WriteState itself does not handle constraints directly, it retrieves data that may include constraint information if present in the mechanical state.

Numerical Methods or Discretization Choices

The WriteState component primarily handles output operations. It provides functionality for writing state vectors to a file at predefined times or periodically based on specified intervals. The discretization choices are not directly involved, as this is more about logging and exporting data than numerical simulation.

Mathematical Description of State Vectors

Position Vector $X$: Represents the current displacement vector of the nodes in the mechanical model.
Rest Position Vector $X_0$: The reference or rest configuration position vector used to define initial conditions.
Velocity Vector $V$: The time derivative of the position vector, representing the velocity at each node.
Force Vector $F$: External forces acting on the nodes, which can include both internal and external forces applied through various force fields in SOFA.

Variational / Lagrangian Mechanics Framework

Although WriteState does not directly influence variational mechanics or the formulation of the equations of motion, it plays a crucial role in providing detailed state information from the simulation. This data can be used for post-processing and analysis to validate the numerical solution against theoretical expectations derived from variational principles.

Summary

The WriteState component is an output mechanism within the SOFA framework that writes state vectors (position, velocity, force) to file at specified time instants or periodically. It does not contribute directly to any governing equations but facilitates post-simulation analysis and validation.

Data Fields

Name	Type	Help
`d_writeX`	bool	flag enabling output of X vector
`d_writeX0`	bool	flag enabling output of X0 vector
`d_writeV`	bool	flag enabling output of V vector
`d_writeF`	bool	flag enabling output of F vector
`d_period`	double	period between outputs
`d_stopAt`	double	stop the simulation when the given threshold is reached
`d_keperiod`	double	set the period to measure the kinetic energy increase

Methods

void init () virtual

void reinit () virtual

void reset () virtual

void handleEvent (sofa::core::objectmodel::Event * event) virtual

bool canCreate (T *& obj, core::objectmodel::BaseContext * context, core::objectmodel::BaseObjectDescription * arg)

{
  "name": "WriteState",
  "namespace": "sofa::component::playback",
  "module": "Sofa.Component.Playback",
  "include": "sofa/component/playback/WriteState.h",
  "doc": "Write State vectors to file at each timestep.\n\nWrite State vectors to file at a given set of time instants\nA period can be established at the last time instant\nThe DoFs to print can be chosen using DOFsX and DOFsV\nStop to write the state if the kinematic energy reach a given threshold (stopAt)\nThe energy will be measured at each period determined by keperiod",
  "inherits": [
    "BaseObject"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_writeX",
      "type": "bool",
      "xmlname": "writeX",
      "help": "flag enabling output of X vector"
    },
    {
      "name": "d_writeX0",
      "type": "bool",
      "xmlname": "writeX0",
      "help": "flag enabling output of X0 vector"
    },
    {
      "name": "d_writeV",
      "type": "bool",
      "xmlname": "writeV",
      "help": "flag enabling output of V vector"
    },
    {
      "name": "d_writeF",
      "type": "bool",
      "xmlname": "writeF",
      "help": "flag enabling output of F vector"
    },
    {
      "name": "d_period",
      "type": "double",
      "xmlname": "period",
      "help": "period between outputs"
    },
    {
      "name": "d_stopAt",
      "type": "double",
      "xmlname": "stopAt",
      "help": "stop the simulation when the given threshold is reached"
    },
    {
      "name": "d_keperiod",
      "type": "double",
      "xmlname": "keperiod",
      "help": "set the period to measure the kinetic energy increase"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reset",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "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": "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"
    }
  ],
  "description": "The `WriteState` component in the SOFA framework is designed to output state vectors (position, velocity, force) to file at specified time instants or at periodic intervals during a simulation run. It writes these data points into files for later analysis or playback. This component inherits from `BaseObject`, indicating its role as an object within the scene graph that can be interacted with through events and methods.\n\n**Interactions:**\n- Interacts with mechanical states (`MechanicalState`) to obtain state vectors.\n- Listens to events for triggering writes at specific simulation times, including handling `AnimateBeginEvent` to periodically check for output conditions.\n- Can stop the simulation when a specified kinetic energy threshold is reached.\n\n**Data Fields:*\n- `writeX`: Flag enabling output of position vector (default true).\n- `writeX0`: Flag enabling output of rest positions (default false).\n- `writeV`: Flag enabling output of velocity vector (default false).\n- `writeF`: Flag enabling output of force vector (default false).\n- `period`: Period between outputs, for periodic writing.\n- `stopAt`: Threshold for kinetic energy to stop the simulation.\n- `keperiod`: Interval for measuring increases in kinetic energy.\n\n**Usage Guidance:**\nConfigure `WriteState` by setting appropriate flags and periods. Ensure a filename is provided. It can be used to periodically export state vectors, helping with post-simulation analysis or debugging.",
  "maths": "The `WriteState` component in the SOFA framework is designed to output state vectors (position, velocity, force) to file at specified time instants or at periodic intervals during a simulation run. It writes these data points into files for later analysis or playback. This component does not contribute directly to any governing equations or operators such as mass matrix $M$, stiffness matrix $K$, internal forces $f_{int}$, residual $R$, etc., but rather serves as an output mechanism that interacts with the mechanical state of a simulation to retrieve and write these vectors at specified times. Here is a detailed description of its role and functionality within the broader FEM pipeline:\n\n### Role in the Global FEM Pipeline\n- **Assembly**: `WriteState` does not participate directly in the assembly phase, as it does not contribute to constructing the global mass matrix $M$, internal force vector $f_{int}$, or residual $R$.\n- **Time Integration**: It interacts with time integration schemes by listening for events such as `AnimateBeginEvent`, which indicate that a new simulation step has begun. At these times, it checks if state vectors should be written to file based on predefined conditions (e.g., periodic intervals or at specific time instants).\n- **Nonlinear Solve**: It does not influence the nonlinear solution process but can provide outputs from the current state after each iteration.\n- **Linear Solve**: Similarly, it does not participate in the linear solve phase, only retrieving and writing state vectors post-solve.\n- **Constraint Handling**: Although `WriteState` itself does not handle constraints directly, it retrieves data that may include constraint information if present in the mechanical state.\n\n### Numerical Methods or Discretization Choices\nThe `WriteState` component primarily handles output operations. It provides functionality for writing state vectors to a file at predefined times or periodically based on specified intervals. The discretization choices are not directly involved, as this is more about logging and exporting data than numerical simulation.\n\n### Mathematical Description of State Vectors\n- **Position Vector $X$**: Represents the current displacement vector of the nodes in the mechanical model.\n- **Rest Position Vector $X_0$**: The reference or rest configuration position vector used to define initial conditions.\n- **Velocity Vector $V$**: The time derivative of the position vector, representing the velocity at each node.\n- **Force Vector $F$**: External forces acting on the nodes, which can include both internal and external forces applied through various force fields in SOFA.\n\n### Variational / Lagrangian Mechanics Framework\nAlthough `WriteState` does not directly influence variational mechanics or the formulation of the equations of motion, it plays a crucial role in providing detailed state information from the simulation. This data can be used for post-processing and analysis to validate the numerical solution against theoretical expectations derived from variational principles.\n\n### Summary\nThe `WriteState` component is an output mechanism within the SOFA framework that writes state vectors (position, velocity, force) to file at specified time instants or periodically. It does not contribute directly to any governing equations but facilitates post-simulation analysis and validation.",
  "abstract": "`WriteState` outputs state vectors (position, velocity, force) to file at specified times or periodically during a simulation run.",
  "sheet": "# WriteState\n\n## Overview\nThe `WriteState` component in SOFA writes state vectors (position $X$, rest position $X_0$, velocity $V$, and force $F$) to file at specified time instants or periodically. It interacts with the mechanical state of a simulation to retrieve these vectors and write them for post-simulation analysis.\n\n## Parameters and Data\n- `writeX`: Flag enabling output of position vector (default true).\n- `writeX0`: Flag enabling output of rest positions (default false).\n- `writeV`: Flag enabling output of velocity vector (default false).\n- `writeF`: Flag enabling output of force vector (default false).\n- `period`: Period between outputs, for periodic writing.\n- `stopAt`: Threshold for kinetic energy to stop the simulation.\n- `keperiod`: Interval for measuring increases in kinetic energy.\n\n## Practical Notes\nConfigure `WriteState` by setting appropriate flags and periods. Ensure a filename is provided. It can be used to periodically export state vectors, helping with post-simulation analysis or debugging."
}