Data Fields

Links

Methods

{
  "name": "LinearMovementProjectiveConstraint",
  "namespace": "sofa::component::constraint::projective",
  "module": "Sofa.Component.Constraint.Projective",
  "include": "sofa/component/constraint/projective/LinearMovementProjectiveConstraint.h",
  "doc": "Impose a motion to given DOFs (translation and rotation).\n\nimpose a motion to given DOFs (translation and rotation)\n\tThe motion between 2 key times is linearly interpolated\n    Rigid version doesn't handle Topology change.",
  "inherits": [
    "ProjectiveConstraintSet"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_keyMovements",
      "type": "VecDeriv",
      "xmlname": "movements",
      "help": "movements corresponding to the key times"
    },
    {
      "name": "d_relativeMovements",
      "type": "bool",
      "xmlname": "relativeMovements",
      "help": "If true, movements are relative to first position, absolute otherwise"
    },
    {
      "name": "d_showMovement",
      "type": "bool",
      "xmlname": "showMovement",
      "help": "Visualization of the movement to be applied to constrained dofs."
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "clearIndices",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addIndex",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeIndex",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "clearKeyMovements",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKeyMovement",
      "return_type": "void",
      "params": [
        {
          "name": "time",
          "type": "Real"
        },
        {
          "name": "movement",
          "type": "Deriv"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reset",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectResponse",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "resData",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectVelocity",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "vData",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectPosition",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "xData",
          "type": "DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectJacobianMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "cData",
          "type": "DataMatrixDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "matrix",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "vector",
          "type": "linearalgebra::BaseVector *"
        },
        {
          "name": "matrix",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "matrix",
          "type": "sofa::core::behavior::ZeroDirichletCondition *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectResponseT",
      "return_type": "void",
      "params": [
        {
          "name": "dx",
          "type": "DataDeriv &"
        },
        {
          "name": "clear",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "interpolatePosition",
      "return_type": "void",
      "params": [
        {
          "name": "cT",
          "type": "Real"
        },
        {
          "name": "",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `LinearMovementProjectiveConstraint` is a component in the SOFA framework designed to impose motion (translation and rotation) on specific degrees of freedom (DOFs). It achieves this by defining key movements at specific times, which are then linearly interpolated between these key times. The constraint supports both relative and absolute movements with respect to initial positions or absolute coordinates.\n\n### Role in the SOFA Ecosystem:\n- **Constraint Application:** This component inherits from `ProjectiveConstraintSet` and provides methods for applying constraints within a mechanical simulation, such as projecting responses, velocities, and positions onto DOFs. It also handles matrix projections and zero Dirichlet conditions.\n- **Motion Control:** By defining key movements at specific times, the constraint can control the motion of certain parts of the simulated object in a precise manner, making it useful for scenarios where controlled movement is necessary (e.g., simulating surgical tools or robotic actuators).\n\n### Interactions with Other Components:\n- **Topology Linkage:** The component links to a `BaseMeshTopology` container, ensuring that topological changes are handled correctly. This linkage allows the constraint to interact with other components responsible for managing mesh topology.\n- **Mechanical State Interaction:** Through various methods (e.g., `projectResponse`, `projectVelocity`, and `projectPosition`), it interacts with the mechanical state of the system, influencing how forces and positions evolve over time.\n\n### Practical Usage Guidance:\n- **Key Movements Definition:** Users can add key movements using the `addKeyMovement` method, specifying a time and corresponding movement vector (e.g., translation or rotation). These movements are interpolated linearly between defined times.\n- **Relative/Absolute Movements:** The component allows users to specify whether movements are relative to an initial position (`relativeMovements`) or absolute. This flexibility makes it suitable for different simulation scenarios.\n- **Visualization:** The `showMovement` flag enables visualization of the constrained DOFs' movement path, aiding in debugging and understanding the motion imposed by the constraint.\n\n### Data Fields:\n- **Indices (d_indices):** Specifies which DOFs are affected by the constraint. Indices can be added or removed using methods like `addIndex`, `removeIndex`, and `clearIndices`.\n- **Key Movements (`d_keyMovements`):** Stores movement vectors corresponding to key times, defining how DOFs should move over time.\n- **Relative Movements (`d_relativeMovements`):** Boolean indicating whether movements are relative or absolute with respect to initial positions.\n- **Show Movement (`d_showMovement`):** Controls the visualization of constrained DOF movements.",
  "maths": "The `LinearMovementProjectiveConstraint` in the SOFA framework imposes motion (translation and rotation) on specific degrees of freedom (DOFs). This is achieved by defining key movements at specified times, which are then linearly interpolated between these key time points. The component supports both relative and absolute movements with respect to initial positions or absolute coordinates. Here is a detailed mathematical and physical description of the component's operations within the FEM pipeline.\n\n### Governing Equations and Operators:\n- **Mass Matrix ($M$):** Not directly involved in the constraint as it primarily modifies DOF values through position, velocity, and response projections.\n- **Stiffness Matrix ($K$):** Also not directly influenced by this component, but the imposed motion can indirectly affect the stiffness terms when integrated into a larger system.\n- **Internal Force ($f_{int}$):** The constraint does not contribute directly to internal forces; however, it modifies the DOFs that may influence $f_{int}$ in other components of the simulation pipeline.\n- **Residual ($R$):** The residual is indirectly affected as the constraint enforces specific positions and velocities at certain times.\n\n### Constitutive or Kinematic Laws Involved:\n- **Key Movements:** Movements are defined at key time points $t_i$, where each movement corresponds to a vector in the displacement space. Let $M(t)$ be the movement function, which is linearly interpolated between these key movements.\n  - Given two key times $t_{prev}$ and $t_{next}$ with corresponding movements $m_{prev}$ and $m_{next}$:\n    \n  \\[ M(t) = m_{prev} + (t - t_{prev})\\frac{m_{next} - m_{prev}}{t_{next} - t_{prev}}. \\]\n\n- **Relative Movements:** If `relativeMovements` is true, the movement vector $M(t)$ is added to the initial position of the DOFs.\n  - Initial positions are stored in $x_0$ and updated as:\n    \n  \\[ x(t) = x_0 + M(t).\\]\n\n- **Absolute Movements:** If `relativeMovements` is false, the movement vector directly defines the absolute position of the DOFs.\n  - Positions are set to:\n    \n  \\[ x(t) = M(t).\\]\n\n### Role in the Global FEM Pipeline:\n1. **Assembly Phase: Not Directly Involved:** The `LinearMovementProjectiveConstraint` does not contribute to the assembly of global mass or stiffness matrices, but it modifies DOF values that can influence these matrices.\n2. **Time Integration:** During time integration steps (e.g., Backward Euler), the constraint updates the positions and velocities according to predefined movements at specific times.\n3. **Nonlinear Solve:** Not directly involved in solving nonlinear equations, but enforces constraints on the DOFs that may affect the solution process indirectly.\n4. **Linear Solve:** Modifies the linear system by ensuring certain DOFs adhere to specified motions, effectively reducing degrees of freedom for the solver.\n5. **Constraint Handling:** Enforces projective constraints on specific DOFs at each time step, ensuring they follow predefined paths or positions.\n6. **Mapping:** Ensures consistent application of movements across different types of topologies and geometries through its methods like `projectResponse`, `projectVelocity`, and `projectPosition`.\n\n### Numerical Methods or Discretization Choices:\n- The component employs linear interpolation to determine the movement between key time points, ensuring smooth transitions in motion over time.\n- It handles discrete sets of indices for DOFs that are affected by these movements, allowing fine-grained control over which parts of the system follow prescribed paths.\n\n### Fitting into the Variational / Lagrangian Mechanics Framework:\nThe `LinearMovementProjectiveConstraint` fits within a broader variational mechanics framework by imposing constraints directly on DOF values rather than modifying variational principles. It effectively introduces external forces or boundary conditions that enforce specific kinematic behaviors, aligning with the projective constraint methodology in SOFA.\n\nIn summary, this component provides precise control over motion for specified DOFs within a simulation, ensuring they follow predefined paths while integrating seamlessly into the broader FEM and variational mechanics pipeline of SOFA.",
  "abstract": "Imposes motion on specific degrees of freedom (DOFs) by defining key movements at specified times and linearly interpolating between them. Supports both relative and absolute movements with respect to initial positions or absolute coordinates.",
  "sheet": "<h1>LinearMovementProjectiveConstraint</h1>\n\n<h2>Overview</h2>\n<p>The `LinearMovementProjectiveConstraint` is a component in the SOFA framework designed to impose motion (translation and rotation) on specific degrees of freedom (DOFs). It achieves this by defining key movements at specified times, which are then linearly interpolated between these key time points. The constraint supports both relative and absolute movements with respect to initial positions or absolute coordinates.</p>\n\n<h2>Mathematical Model</h2>\n<p>The component imposes motion on specific DOFs through predefined key movements at specified times. Given two key times $t_{prev}$ and $t_{next}$ with corresponding movements $m_{prev}$ and $m_{next}$, the movement function $M(t)$ is linearly interpolated as:</p>\n\\[ M(t) = m_{prev} + (t - t_{prev}) \\frac{m_{next} - m_{prev}}{t_{next} - t_{prev}}. \\]\n<p>If `relativeMovements` is true, the movement vector $M(t)$ is added to the initial position of the DOFs:</p>\n\\[ x(t) = x_0 + M(t). \\]\n<p>Otherwise, if `relativeMovements` is false, the movement vector directly defines the absolute position of the DOFs:</p>\n\\[ x(t) = M(t). \\]\n\n<h2>Parameters and Data</h2>\n<ul>\n<li><strong>d_keyMovements (VecDeriv)</strong>: Movements corresponding to key times.</li>\n<li><strong>d_relativeMovements (bool)</strong>: If true, movements are relative to the first position; absolute otherwise. Default: false.</li>\n<li><strong>d_showMovement (bool)</strong>: Controls visualization of the movement applied to constrained DOFs. Default: false.</li>\n</ul>\n\n<h2>Dependencies and Connections</h2>\n<p>The component links to a `BaseMeshTopology` container, ensuring that topological changes are handled correctly. It interacts with other components responsible for managing mesh topology and mechanical state through methods such as `projectResponse`, `projectVelocity`, and `projectPosition`.</p>"
}