Data Fields

Methods

{
  "name": "SarcomereHuxleyModel",
  "namespace": "sofa::component",
  "module": "SofaTestPlugin",
  "include": "forcefield/sarcomere/SarcomereHuxleyModel.h",
  "doc": "Implement the Huxley model ODE to compute active stress along fiber",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec2Types"
  ],
  "data_fields": [
    {
      "name": "d_exponential_example",
      "type": "bool",
      "xmlname": "exponential",
      "help": "Boolean (true=solve toy example)"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "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": "addDForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "df",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dx",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildStiffnessMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "matrix",
          "type": "core::behavior::StiffnessMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildDampingMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "core::behavior::DampingMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `SarcomereHuxleyModel` is a force field in the SOFA framework designed to implement the Huxley model for computing active stress along muscle fibers. This model specifically addresses sarcomere contraction and is part of the `SofaTestPlugin`. It inherits from the `ForceField` class, indicating its role as a component that contributes forces to the mechanical system.\n\nThe primary interaction within SOFA involves linking with another force field (`contraction_forcefield`) via the `l_contraction_ff` link. This linkage is critical for accessing necessary data such as strain and stiffness information to compute active stress.\n\nKey methods include `init`, `addForce`, and `getPotentialEnergy`. The `addForce` method computes forces based on the Huxley model ODEs, with an option (`d_exponential_example`) to solve a toy example for testing purposes. The potential energy computation is set to return zero by default.\n\nThe component's role in SOFA is to simulate muscle fiber behavior under different mechanical conditions, contributing to more realistic simulations of soft tissue mechanics.",
  "maths": "The `SarcomereHuxleyModel` implements the Huxley model to compute active stress along muscle fibers, contributing forces to a mechanical system within the SOFA framework. This force field is part of the `SofaTestPlugin` module and inherits from the generic `ForceField` class. Its primary role is to simulate sarcomere contraction by utilizing data from another linked force field (`contraction_forcefield`) for strain, stiffness, and other mechanical parameters necessary for active stress computation.\n\n### Governing Equations and Operators\nThe component computes forces based on the Huxley model ODEs. The governing equations are formulated as follows:\n\n- **Strain Projection**: The strain projected along the fiber direction is given by $e_{1D}$, which represents the deformation in the fiber axis.\n\n- **Electrical Input**: An electrical input $u$ influences the mechanical behavior of the sarcomere. This electrical signal can be positive or negative and modulates both stiffness ($k_c$) and contractile stress ($\\tau_c$).\n\n- **Huxley Model ODEs**:\n  The Huxley model describes the evolution of strain $e$, stiffness $k$, and contractile stress $\\tau$. In this component, the following equations are used to compute the active forces:\n  \n  \\[\n  f = -coeff \\cdot k_c + n_0 \\cdot k_0 \\cdot u^+,\n  \\]\n  where\n  \\[ coeff = |u| + \\alpha \\cdot |\\dot{e}_{cp}|, \\quad u^+ = \\max(0, u), \\quad \\text{and} \\quad \\dot{e}_{cp} = (info.ec - info.old_ec) / dt.\n  \\]\n  Additionally,\n  \n  \\[\n  f = -coeff \\cdot \\tau_c + \\dot{e}_{cp} \\cdot k_c + n_0 \\sigma_0 u^+,\n  \\]\n  where $dt$ is the time step and $\\alpha$, $k_0$, $\\sigma_0$, $n_0$, and other parameters are derived from the `HuxleyODEInformation` struct.\n\n- **Potential Energy**: The potential energy computation is set to return zero by default, implying no additional stored energy in this model. This can be interpreted as a quasi-static assumption where dynamic effects are negligible or not considered explicitly.\n\n### Constitutive Laws and Kinematic Measures\nThe `SarcomereHuxleyModel` incorporates the following constitutive laws and kinematic measures:\n\n- **Strain**: The strain $e_{1D}$ is projected onto the fiber direction, indicating the deformation in that specific axis. This projection aligns with the physiological interpretation of sarcomere contraction along muscle fibers.\n\n- **Stiffness ($k_c$)**: Represents the stiffness of the sarcomere as influenced by both internal mechanics and external electrical input $u$. The term $coeff = |u| + \\alpha \\cdot |\\dot{e}_{cp}|$ modifies the stiffness based on the rate of strain change and the magnitude of electrical activity.\n\n- **Contractile Stress ($\\tau_c$)**: Represents the active stress generated by the sarcomere. This stress is modulated by $u$, $k_0$, and $\\sigma_0$, which are material parameters.\n\n### Role in FEM Pipeline\nThe `SarcomereHuxleyModel` plays a crucial role in contributing to the global force balance within the mechanical system:\n\n- **Force Assembly**: The component computes active forces via the `addForce` method, which updates the total internal forces $f$ based on the current state variables ($e_{1D}$, $u$, etc.). This contribution is added to the overall residual and affects the Newton iteration process during nonlinear solve.\n\n- **No Damping Matrix**: The `buildDampingMatrix` method is not implemented, indicating that no explicit damping forces are considered in this model. This simplification can be useful for specific simulations where inertial effects or energy dissipation mechanisms are not critical.\n\n- **Stiffness Matrix**: Similarly, the stiffness matrix contribution is minimal as it does not modify the overall system matrix beyond the forces computed by `addForce` method.\n\n### Numerical Methods and Discretization Choices\nThe component uses an implicit discretization approach to ensure stability. The time step $dt$ is used in computing rate-dependent quantities (e.g., $\\dot{e}_{cp}$), ensuring that the ODEs are solved consistently with respect to the temporal discretization.\n\n### Variational and Lagrangian Mechanics Framework\nThe Huxley model, implemented by this component, aligns with a variational mechanics framework. The active forces computed in `addForce` contribute to the potential energy landscape of the mechanical system, reflecting the principle that internal forces arise from the minimization of the total potential energy.\n\nIn summary, the `SarcomereHuxleyModel` provides a detailed simulation capability for muscle fiber behavior by integrating the Huxley model into the SOFA framework. This integration enhances the realism and accuracy of soft tissue simulations involving active muscle contractions.",
  "abstract": "The `SarcomereHuxleyModel` implements the Huxley model to compute active stress along muscle fibers, contributing forces to a mechanical system within SOFA simulations.",
  "sheet": "# SarcomereHuxleyModel\n\n## Overview\n\nThe `SarcomereHuxleyModel` is a force field component that implements the Huxley model for computing active stress along muscle fibers. It inherits from the generic `ForceField` class and contributes forces to the mechanical system within SOFA simulations.\n\n## Mathematical Model\n\nThe `SarcomereHuxleyModel` computes forces based on the Huxley model ODEs, which describe the evolution of strain $e$, stiffness $k$, and contractile stress $\\tau$. The governing equations are:\n\n- **Strain Projection**: The strain projected along the fiber direction is given by $e_{1D}$.\n- **Electrical Input**: An electrical input $u$ influences the mechanical behavior, modulating both stiffness ($k_c$) and contractile stress ($\\tau_c$).\n\nThe active forces are computed as follows:\n\n\begin{align*}\n  f &= -coeff \\cdot k_c + n_0 \\cdot k_0 \\cdot u^+, \\\\\n  coeff &= |u| + \\alpha \\cdot |\\dot{e}_{cp}|, \\\\\n  u^+ &= \\max(0, u), \\\\\n  \\dot{e}_{cp} &= (info.ec - info.old_ec) / dt.\n\ndisplay\nf &= -coeff \\cdot \\tau_c + \\dot{e}_{cp} \\cdot k_c + n_0 \\sigma_0 u^+,\n\\end{align*}\nwhere $dt$ is the time step and $\\alpha$, $k_0$, $\\sigma_0$, $n_0$, and other parameters are derived from the `HuxleyODEInformation` struct.\n\n## Parameters and Data\n\n- **d_exponential_example**: Boolean (true=solve toy example)\n  - Type: bool\n  - XML Name: exponential\n  - Default: Not specified\n\n## Practical Notes\n\nThe potential energy computation is set to return zero by default, implying a quasi-static assumption where dynamic effects are negligible. The `buildDampingMatrix` method is not implemented, indicating no explicit damping forces are considered in this model."
}