Data Fields

Methods

{
  "name": "PartialFixedProjectiveConstraint",
  "namespace": "sofa::component::constraint::projective",
  "module": "Sofa.Component.Constraint.Projective",
  "include": "sofa/component/constraint/projective/PartialFixedProjectiveConstraint.h",
  "doc": "Attach given particles to their initial positions, in some directions only.\n\nAttach given particles to their initial positions, in some directions only.\nThe fixed and free directioons are the same for all the particles, defined  in the fixedDirections attribute.",
  "inherits": [
    "FixedProjectiveConstraint"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_fixedDirections",
      "type": "VecBool",
      "xmlname": "fixedDirections",
      "help": "Defines the directions in which the particles are fixed: true (or 1) for fixed, false (or 0) for free"
    },
    {
      "name": "d_projectVelocity",
      "type": "bool",
      "xmlname": "projectVelocity",
      "help": "activate project velocity to maintain a constant velocity"
    }
  ],
  "links": [],
  "methods": [
    {
      "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": "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": "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": "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": "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": "matrix",
          "type": "sofa::core::behavior::ZeroDirichletCondition *"
        }
      ],
      "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"
    }
  ],
  "description": "The `PartialFixedProjectiveConstraint` is a SOFA component designed to attach specific particles to their initial positions in certain directions, leaving other directions free to move. This component inherits from the `FixedProjectiveConstraint` and operates within the SOFA framework's constraint projective module.\n\nIts primary role is to enforce constraints on particle movements based on user-defined fixed directions specified through the `fixedDirections` attribute. The `projectVelocity` option can be enabled to maintain a constant velocity for these fixed points, preventing any drift that might occur otherwise.\n\nThe component interacts with other SOFA components via its API, which includes methods like `reinit`, `projectResponse`, `applyConstraint`, and others related to projective constraint operations. These interactions are primarily within the mechanical subsystems of SOFA, affecting how particle positions and velocities are updated during simulation steps.\n\nFor practical usage, the user needs to set the `fixedDirections` attribute with a boolean array indicating which directions should be fixed for each particle. The `projectVelocity` field can also be adjusted if maintaining constant velocity is necessary. This component is particularly useful in scenarios where partial fixations are required to simulate specific physical constraints within a simulation.",
  "maths": "<maths>\n## Mathematical and Physical Description of `PartialFixedProjectiveConstraint`\n\n### Governing Equations and Operators Contributed\n\nThe `PartialFixedProjectiveConstraint` component enforces constraints on specific particles in a simulation to keep them fixed along certain directions. This constraint can be represented mathematically as follows:\n\nGiven the initial positions of particles \\(\\mathbf{x}_0\\) and their current positions \\(\\mathbf{x}\\), the constraint equation for each particle can be written as:\n\n\begin{equation}\n  (\\mathbf{x} - \\mathbf{x}_0)_i = 0, \\quad \\text{for } i \notin \\mathcal{F},\n\\end{equation}\n\nwhere \\(\\mathcal{F}\\) is the set of indices corresponding to fixed directions as defined by the `fixedDirections` attribute. This implies that the displacements along the fixed directions are constrained to be zero.\n\n### Constitutive or Kinematic Laws Involved\n\n- **Fixed Directions**: The constraint is applied based on a user-defined boolean array `d_fixedDirections`, where each element indicates whether a direction should be fixed (`true`) or free (`false`). This can be expressed as:\n  \n\begin{equation}\n  \\mathbf{b} = [b_1, b_2, ..., b_n], \\quad b_i \\in \\{0, 1\\},\n\\end{equation}\n\nwhere each \\(b_i\\) specifies whether the corresponding direction is fixed.\n\n- **Velocity Projection**: The `d_projectVelocity` flag enables the projection of velocities to zero in the fixed directions. This ensures that particles remain at their initial positions with no movement along the constrained directions:\n  \n\begin{equation}\n  (\\mathbf{v})_i = 0, \\quad \\text{for } i \notin \\mathcal{F}.\n\\end{equation}\n\n### Role in the Global FEM Pipeline\n\nThe `PartialFixedProjectiveConstraint` component plays a role in enforcing boundary conditions and constraints within the FEM simulation pipeline. Specifically:\n\n- **Assembly Phase**: The component contributes to assembling the constraint Jacobian matrix \\(J\\), which enforces the constraints on particle positions.\n  \n\begin{equation}\n  J = \\frac{\\partial (\\mathbf{x} - \\mathbf{x}_0)}{\\partial \\mathbf{x}}, \\quad \\text{with } (\\mathbf{x} - \\mathbf{x}_0)_i = 0, \\forall i \notin \\mathcal{F}.\n\\end{equation}\n\n- **Nonlinear Resolution**: The constraints are enforced during the nonlinear solve by modifying the residual vector \\(R\\) and Jacobian matrix \\(J\\).\n  \n\begin{equation}\n  R = M\\ddot{x}(t) + f_{int}(x(t)) - f_{ext}(t),\n\\end{equation}\n\nwhere the internal force term \\(f_{int}\\) includes contributions from constraints.\n\n- **Time Integration**: The constraint is enforced in each time step to ensure that particles remain fixed along specified directions during implicit time integration.\n  \n### Numerical Methods and Discretization Choices\n\nThe component uses projective methods to enforce constraints, which involve modifying the system matrices (mass matrix \\(M\\), stiffness matrix \\(K\\)) and residual vector \\(R\\) at each iteration:\n\n- **Project Response**: The `projectResponse` method modifies the response of particles by setting their displacements in fixed directions to zero.\n  \n\begin{equation}\n  (\\mathbf{x} - \\mathbf{x}_0)_i = 0, \\quad \\text{for } i \notin \\mathcal{F}.\n\\end{equation}\n\n- **Project Velocity**: The `projectVelocity` method ensures that velocities in fixed directions are set to zero if the `d_projectVelocity` flag is enabled.\n  \n\begin{equation}\n  (\\mathbf{v})_i = 0, \\quad \\text{for } i \notin \\mathcal{F}.\n\\end{equation}\n\n### Integration into Variational / Lagrangian Mechanics Framework\n\nThe `PartialFixedProjectiveConstraint` integrates seamlessly into the variational mechanics framework by modifying the system's equations of motion to include constraints. This is achieved through the following steps:\n\n- **Weak Form**: The weak form of the governing equation incorporates Lagrange multipliers \\(\\lambda\\) to enforce the constraint conditions.\n  \n\begin{equation}\n  \\int_\\Omega \\rho \\ddot{u} \\cdot w \\, d\\Omega + \\int_\\Omega \\sigma : \\varepsilon(w) \\, d\\Omega = \\int_\\Omega \\rho b \\cdot w \\, d\\Omega + \\int_{\\Gamma_N} \\bar{t} \\cdot w \\, d\\Gamma,\n\\end{equation}\n\nwhere the constraint is enforced as a boundary condition on \\(u\\).\n\n- **Lagrangian Multiplier Method**: The Lagrangian multiplier method is used to enforce constraints by introducing additional terms into the system equations. This ensures that the constraints are satisfied at each step of the simulation.\n  \n\begin{equation}\n  M\\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t), \\quad \\text{with } J(x)\\lambda = 0,\n\\end{equation}\n\nwhere \\(J(x)\\) is the Jacobian matrix derived from the constraint equations.\n</maths>",
  "abstract": "The `PartialFixedProjectiveConstraint` enforces partial fixations on particle movements by attaching particles to their initial positions in specified directions while allowing movement in others. It uses projective methods to enforce constraints and supports velocity projection for maintaining constant velocities in fixed directions.",
  "sheet": "# PartialFixedProjectiveConstraint\n\n## Overview\nThe `PartialFixedProjectiveConstraint` is a SOFA component that enforces partial fixations on particle movements by attaching particles to their initial positions in specified directions while allowing movement in others. It inherits from the `FixedProjectiveConstraint` and operates within the constraint projective module.\n\n## Mathematical Model\nGiven the initial positions of particles \\(\\mathbf{x}_0\\) and their current positions \\(\\mathbf{x}\\), the constraint equation for each particle can be written as:\n\n\\[ (\\mathbf{x} - \\mathbf{x}_0)_i = 0, \\quad \\text{for } i \\notin \\mathcal{F}, \\]\n\nwhere \\(\\mathcal{F}\\) is the set of indices corresponding to fixed directions. This implies that the displacements along the fixed directions are constrained to be zero.\n\nThe `d_projectVelocity` flag enables the projection of velocities to zero in the fixed directions, ensuring particles remain at their initial positions with no movement along the constrained directions:\n\n\\[ (\\mathbf{v})_i = 0, \\quad \\text{for } i \\notin \\mathcal{F}. \\]\n\n## Parameters and Data\n- **fixedDirections**: Defines the directions in which the particles are fixed: `true` (or `1`) for fixed, `false` (or `0`) for free. Type: `VecBool`\n- **projectVelocity**: Activates project velocity to maintain a constant velocity. Type: `bool`, Default: `false`\n\n## Practical Notes\nThe component uses projective methods to enforce constraints by modifying the system matrices and residual vector at each iteration. The `reinit` method initializes the constraint, while `projectResponse` modifies particle displacements in fixed directions to zero. If `d_projectVelocity` is enabled, velocities are also projected to zero in these directions."
}