{
  "name": "DebugMSContraction",
  "main": {
    "name": "DebugMSContraction",
    "namespace": "sofa::component",
    "module": "SofaTestPlugin",
    "include": "forcefield/active/DebugMSContraction.h",
    "doc": "Applies contraction force along fiber directions in tetrahedral meshes, coupling with a MS model",
    "inherits": [
      "BaseTetraForceField"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_contractionStress",
        "type": "Real",
        "xmlname": "contractionStress",
        "help": "Stress magnitude (max)"
      },
      {
        "name": "d_kContract",
        "type": "Real",
        "xmlname": "kContract",
        "help": "Contraction rate"
      },
      {
        "name": "d_kRelax",
        "type": "Real",
        "xmlname": "kRelax",
        "help": "Relaxation rate"
      },
      {
        "name": "d_mechMS",
        "type": "VecCoord2",
        "xmlname": "mechMS",
        "help": "MS MechanicalObject positions (u, v)"
      },
      {
        "name": "d_activeStress",
        "type": "Real",
        "xmlname": "activeStress",
        "help": "Active stress for the tetrahedron 42 (debug)"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "handleEvent",
        "return_type": "void",
        "params": [
          {
            "name": "event",
            "type": "sofa::core::objectmodel::Event *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "f",
            "type": "DataVecDeriv &"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          },
          {
            "name": "v",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeContractionStress",
        "return_type": "Matrix3",
        "params": [
          {
            "name": "deformationGradient",
            "type": "const Matrix3 &"
          },
          {
            "name": "fiberDir",
            "type": "const Coord &"
          },
          {
            "name": "stressMagnitude",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "action_potential",
        "return_type": "double",
        "params": [
          {
            "name": "time",
            "type": "double"
          },
          {
            "name": "depol",
            "type": "double"
          },
          {
            "name": "apd",
            "type": "double"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `DebugMSContraction` component in the SOFA framework applies contraction forces along fiber directions in tetrahedral meshes, coupling with a Mitchell-Schaeffer (MS) model. It inherits from `BaseTetraForceField`, indicating it operates on tetrahedral elements and provides force calculations for them.\n\n### Role and Purpose:\nThe primary role of `DebugMSContraction` is to simulate the contraction behavior of soft tissues in response to active stress, such as muscle contractions. This component calculates forces based on deformation gradients and fiber directions within the mesh. The coupling with an MS model allows for the simulation of active mechanical effects.\n\n### Interactions:\nThe component interacts primarily through its inherited methods from `BaseTetraForceField`, particularly `addForce` to apply force contributions to the system. It also handles events via `handleEvent` method, allowing it to update internal state during runtime. The `computeContractionStress` and `action_potential` methods are used internally for calculating stress and action potential dynamics.\n\n### Practical Usage:\nThe component requires several data fields for configuration:\n- **contractionStress**: Maximum stress magnitude (Real).\n- **kContract**: Contraction rate (Real).\n- **kRelax**: Relaxation rate (Real).\n- **mechMS**: Positions of the MS model (VecCoord2).\n- **activeStress**: Debug field for active stress in tetrahedron 42 (Real).\n\nThese fields help tune the contraction behavior and coupling with the MS model. The component is particularly useful in debugging scenarios where detailed control over stress application in specific tetrahedra is required."
  },
  "maths": {
    "maths": "The `DebugMSContraction` component simulates contraction forces in tetrahedral meshes, incorporating active mechanical effects via coupling with a Mitchell-Schaeffer (MS) model. The primary mathematical and physical operations can be described as follows:\n\n### Force Calculation:\nThe component calculates the force contribution to each node of the tetrahedra using the following steps:\n1. **Deformation Gradient Calculation**:\n   - For each tetrahedron, the deformation gradient tensor $\\mathbf{F}$ is computed based on the nodal positions and their rest state configuration.\n\n2. **Contraction Stress Tensor**:\n   - The contraction stress tensor $\\sigma$ is calculated using the fiber direction vector $\\mathbf{a}$ and the current active stress magnitude. Given a maximum stress magnitude $S_{max}$, the effective stress $S_i(t)$ for each tetrahedron at time $t$ is determined by:\n     \n     $$\n     S_i(t) = m_{activeStress}[i] \\cdot S_{max}\n     $$\n   - The contraction stress tensor is computed as a second-order tensor:\n     \n     $$\n     \\sigma = S_i(t) \\cdot (\\mathbf{a} \\otimes \\mathbf{a})\n     $$\n\n3. **Force Contribution**:\n   - The force contribution $\\mathbf{f}$ to each node is then derived from the stress tensor and the shape functions associated with the tetrahedron. For a tetrahedron with nodes indexed by $j$, the nodal forces are updated as:\n     \n     $$\n     \\mathbf{f}_j = -\\mathbf{F} \\cdot (\\sigma \\cdot \\mathbf{N}_j) \\cdot V_0\n     $$\n   where $\\mathbf{N}_j$ is the shape function for node $j$, and $V_0$ is the rest volume of the tetrahedron.\n\n### Active Stress Dynamics:\nThe active stress dynamics are modeled as a simple kinetics process, governed by the following differential equation:\n\n$$\n\\frac{d \\text{Ta}}{dt} = k_{Contract} \\cdot u(t) \\cdot (1 - Ta) - k_{Relax} \\cdot Ta\n$$\nwhere $u(t)$ is the average value of a quantity (e.g., voltage or action potential) associated with the tetrahedron, and $k_{Contract}$ and $k_{Relax}$ are contraction and relaxation rates, respectively.\n\n### Event Handling:\nThe `handleEvent` method updates the active stress values based on input from the MS model positions (`mechMS`). For each tetrahedron, it calculates an average value of a quantity associated with its vertices and uses this to update the internal state representing the active stress dynamics.\n\nIn summary, `DebugMSContraction` operates by combining deformation-based forces with time-varying active stresses, allowing for detailed simulation of tissue contraction dynamics."
  },
  "summary": {
    "abstract": "`DebugMSContraction` applies contraction forces along fiber directions in tetrahedral meshes, coupling with a Mitchell-Schaeffer (MS) model to simulate tissue contraction dynamics.",
    "sheet": "# DebugMSContraction\n\n## Overview\nThe `DebugMSContraction` component simulates the contraction behavior of soft tissues by applying forces along fiber directions within tetrahedral meshes. It inherits from `BaseTetraForceField`, indicating it operates on tetrahedral elements and provides force calculations for them.\n\n## Mathematical Model\nThe primary mathematical operations involve calculating the deformation gradient tensor $\\mathbf{F}$, contraction stress tensor $\\sigma$, and updating nodal forces based on these tensors. The effective stress $S_i(t)$ is determined by:\n$$\nS_i(t) = m_{activeStress}[i] \\cdot S_{max}\n$$\nThe contraction stress tensor is computed as a second-order tensor:\n$$\n\\sigma = S_i(t) \\cdot (\\mathbf{a} \\otimes \\mathbf{a})\n$$\nThe force contribution $\\mathbf{f}_j$ to each node is derived from the stress tensor and shape functions associated with the tetrahedron:\n$$\n\\mathbf{f}_j = -\\mathbf{F} \\cdot (\\sigma \\cdot \\mathbf{N}_j) \\cdot V_0\n$$\nThe active stress dynamics are modeled by the differential equation:\n$$\n\\frac{d \\text{Ta}}{dt} = k_{Contract} \\cdot u(t) \\cdot (1 - Ta) - k_{Relax} \\cdot Ta\n$$\nwhere $u(t)$ is an average value of a quantity associated with the tetrahedron, and $k_{Contract}$ and $k_{Relax}$ are contraction and relaxation rates, respectively.\n\n## Parameters and Data\n- **contractionStress**: Maximum stress magnitude (Real).\n- **kContract**: Contraction rate (Real).\n- **kRelax**: Relaxation rate (Real).\n- **mechMS**: Positions of the MS model (VecCoord2).\n- **activeStress**: Debug field for active stress in tetrahedron 42 (Real)."
  }
}