PlaneProjectiveConstraint

sofa::component::constraint::projective::PlaneProjectiveConstraint

ProjectiveConstraintSet

Doc (from source)

Project particles to an affine plane. Project particles to an affine plane. @author Francois Faure, 2012 @todo Optimized versions for planes parallel to the main directions

Abstract (AI generated)

The `PlaneProjectiveConstraint` projects particles onto an affine plane defined by a normal vector and a point on the plane, ensuring they remain within the specified constraints during simulation.

Metadata

module

Sofa.Component.Constraint.Projective

namespace

sofa::component::constraint::projective

include

sofa/component/constraint/projective/PlaneProjectiveConstraint.h

inherits

ProjectiveConstraintSet

templates

sofa::defaulttype::Vec3Types

description

The Visitor class in the SOFA framework is not directly involved with the mathematical or physical models used for simulating deformable systems. Instead, it serves as a foundational mechanism to propagate behaviors and operations throughout the scene graph hierarchy. This class does not contribute any specific governing equations, constitutive laws, or discretization methods on its own but rather provides the infrastructure through which these aspects can be applied consistently across the simulation environment.

Role in the Global FEM Pipeline:

Assembly Phase: The

class facilitates the traversal of the scene graph to assemble contributions from various mechanical objects and components. It enables the execution of tasks that might involve assembling global matrices (like mass, stiffness) or computing internal forces.

Time Integration: While not directly involved in time integration methods like implicit Euler or Newmark schemes, Visitor can be used to execute custom logic that may influence how these steps are carried out. For example, operations performed during the traversal might affect state variables (positions, velocities) before and after each time step.

Nonlinear Solution: During nonlinear solution phases, visitors can help manage complex interactions by applying constraints or projecting forces between different components of the scene graph.

Numerical Methods:

The Visitor class itself does not implement any specific numerical methods. However, it enables the use of such methods through its traversal mechanisms. For instance, operations like matrix assembly or force computation can be applied consistently across nodes and objects during a visitation process.

Constraint Handling:

While not directly managing constraints, visitors can be used to apply constraint-related logic during their traversal. Methods like begin and end, along with optional debugging methods (debug_write_state_before, debug_write_state_after), allow for the tracking of state changes that might include enforcing constraints.

Mapping:

The visitor mechanism does not directly handle mappings, but it can be used to apply logic related to mappings during traversal. For example, visitors can manage operations involving multi-resolution coupling or force consistency through various components in the scene graph.

Variational / Lagrangian Mechanics Framework:

The Visitor class supports the variational and Lagrangian mechanics framework by providing a means to consistently apply operations that contribute to the overall simulation. It ensures that all relevant nodes and objects are processed correctly, supporting the consistent application of physical laws and numerical methods throughout the scene graph.

Summary:

The Visitor is primarily an infrastructure component in SOFA, designed to enable recursive traversal of the scenegraph for applying various operations uniformly across different components. It does not directly contribute any mathematical or physical content but provides a robust framework within which these aspects can be effectively managed and applied.

Data Fields

Name	Type	Help
`d_origin`	CPos	A point in the plane
`d_normal`	CPos	Normal vector to the plane
`d_drawSize`	SReal	Size of the rendered particles (0 -> point based rendering, >0 -> radius of spheres)

Links

Name	Type	Help
`l_topology`		link to the topology container

Methods

void clearConstraints ()

void addConstraint (int index)

void removeConstraint (int index)

void init ()

void reinit ()

void projectResponse (const core::MechanicalParams * mparams, DataVecDeriv & resData)

void projectVelocity (const core::MechanicalParams * mparams, DataVecDeriv & vData)

void projectPosition (const core::MechanicalParams * mparams, DataVecCoord & xData)

void projectJacobianMatrix (const core::MechanicalParams * mparams, DataMatrixDeriv & cData)

void applyConstraint (const core::MechanicalParams * mparams, const sofa::core::behavior::MultiMatrixAccessor * matrix)

void applyConstraint

(const core::MechanicalParams * mparams, linearalgebra::BaseVector * vector, const sofa::core::behavior::MultiMatrixAccessor * matrix)

void projectMatrix (sofa::linearalgebra::BaseMatrix * , unsigned int )

void draw (const core::visual::VisualParams * vparams)

{
  "name": "PlaneProjectiveConstraint",
  "namespace": "sofa::component::constraint::projective",
  "module": "Sofa.Component.Constraint.Projective",
  "include": "sofa/component/constraint/projective/PlaneProjectiveConstraint.h",
  "doc": "Project particles to an affine plane.\n\nProject particles to an affine plane.\n  @author Francois Faure, 2012\n  @todo Optimized versions for planes parallel to the main directions",
  "inherits": [
    "ProjectiveConstraintSet"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_origin",
      "type": "CPos",
      "xmlname": "origin",
      "help": "A point in the plane"
    },
    {
      "name": "d_normal",
      "type": "CPos",
      "xmlname": "normal",
      "help": "Normal vector to the plane"
    },
    {
      "name": "d_drawSize",
      "type": "SReal",
      "xmlname": "drawSize",
      "help": "Size of the rendered particles (0 -> point based rendering, >0 -> radius of spheres)"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "clearConstraints",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "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": "reinit",
      "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": "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": "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": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `PlaneProjectiveConstraint` is a SOFA component that projects particles to an affine plane, ensuring they remain within the defined plane constraints during simulation. This constraint enforces that specified particles are projected onto a specific plane characterized by its normal vector and a point on the plane.\n\n### Role in the SOFA Ecosystem:\nThe `PlaneProjectiveConstraint` is part of the projective constraint set, which includes various constraints that impose conditions directly onto the degrees of freedom (DoFs) of mechanical objects. It inherits from `ProjectiveConstraintSet`, meaning it applies projection-based constraints directly to particle positions and velocities.\n\n### Interactions with Other Components:\nThe component interacts with the topology container via a single link, ensuring proper handling of topological changes. The constraint is applied during various simulation steps through methods such as `projectPosition` and `projectVelocity`. It also supports rendering the projected particles for visualization purposes through the `draw` method.\n\n### Practical Usage Guidance:\nThe component requires setting up key data fields: `origin` (a point on the plane), `normal` (the normal vector to the plane), and optionally, `indices` (the indices of the particles to constrain). The `drawSize` field controls the rendering style for visualization. Users can initialize and manage constraints through methods like `addConstraint`, `removeConstraint`, and `clearConstraints`.",
  "maths": "The `PlaneProjectiveConstraint` component in the SOFA framework enforces that specified particles are projected onto an affine plane defined by a normal vector and a point on the plane. This constraint modifies both position and velocity to ensure that particles remain within the defined constraints.\n\n### Governing Equations:\n\n#### Projection of Position:\nThe projection of a particle's position $x_i$ onto the plane is given by:\n\begin{equation}\n    x_i' = x_i - n ((x_i - o) \bullet n)\n\\end{equation}\nwhere:\n- $x_i'$ is the projected position,\n- $x_i$ is the original particle position,\n- $o$ is a point on the plane,\n- $n$ is the normal vector to the plane.\n\nThis equation ensures that the component of the displacement in the direction of the normal vector is removed, thus projecting the particle onto the plane.\n\n#### Projection of Velocity:\nThe projection of velocity works similarly. Given an initial velocity $v_i$, its projection onto the plane can be written as:\n\begin{equation}\n    v_i' = v_i - n ((v_i \bullet n))\n\\end{equation}\nwhere $v_i'$ is the projected velocity.\n\n### Constitutive Laws and Kinematic Constraints:\nThe `PlaneProjectiveConstraint` does not involve constitutive laws that define stress-strain relationships. Instead, it enforces kinematic constraints directly on particle positions and velocities by projecting them onto a specified plane.\n\n#### Constraint Jacobian Matrix:\nThe projection is implemented using a sparse matrix $J$, which acts as the projection operator. The matrix $J$ has block diagonal structure where each block is either an identity matrix for unconstrained particles or a projection matrix $P$ given by:\n\begin{equation}\n    P = I - nn^T\n\\end{equation}\nwhere $I$ is the identity matrix.\n\n### Role in FEM Pipeline:\nThe `PlaneProjectiveConstraint` fits into the global FEM simulation pipeline as follows:\n- **Assembly Phase**: During assembly, the constraint matrix $J$ is constructed based on the specified indices of particles to be constrained and their projection blocks.\n- **Time Integration**: The constraint is applied during time integration steps by projecting positions and velocities onto the plane at each step.\n- **Nonlinear Solve**: As a projective constraint, it directly modifies the mechanical state without requiring an additional nonlinear solve; instead, it enforces constraints through direct projections.\n\n### Numerical Methods:\nThe component uses sparse matrix operations to efficiently handle large systems. The projection operation is performed via matrix multiplication with $J$ for both positions and velocities.\n\n### Variational / Lagrangian Mechanics Framework:\nThe constraint does not directly contribute to the variational formulation of the FEM problem but ensures that certain kinematic constraints are satisfied. By projecting particles onto a plane, it enforces boundary conditions that can be essential in ensuring physical consistency within the simulation context.\n\nIn summary, `PlaneProjectiveConstraint` provides a mechanism for enforcing planar constraints on particle positions and velocities by direct projection, ensuring that specified particles remain within a predefined affine plane during the simulation.",
  "abstract": "The `PlaneProjectiveConstraint` projects particles onto an affine plane defined by a normal vector and a point on the plane, ensuring they remain within the specified constraints during simulation.",
  "sheet": "# PlaneProjectiveConstraint\n\n## Overview\nThe `PlaneProjectiveConstraint` is part of the projective constraint set in SOFA. It enforces that specified particles are projected onto an affine plane characterized by its normal vector and a point on the plane, ensuring they remain within these constraints during simulation.\n\n## Mathematical Model\nThe projection of particle positions $x_i$ and velocities $v_i$ onto the plane is given by:\n\\begin{align}\n    x_i' &= x_i - n ((x_i - o) \\cdot n), \\\\\n    v_i' &= v_i - n (v_i \\cdot n),\n\\end{align}\nwhere $o$ is a point on the plane, and $n$ is the normal vector to the plane. The projection matrix $P = I - nn^T$ ensures that particles remain within the defined constraints.\n\n## Parameters and Data\n- **origin**: A point in the plane (`CPos`, default: none).\n- **normal**: Normal vector to the plane (`CPos`, default: none).\n- **drawSize**: Size of the rendered particles (0 for points, >0 for spheres) (`SReal`, default: 0).\n\n## Dependencies and Connections\nThe component requires a link to the topology container (`BaseMeshTopology`) to manage topological changes. It interacts with various simulation steps through methods such as `projectPosition` and `projectVelocity`. The constraint is applied during time integration by projecting positions and velocities onto the plane."
}