Data Fields

Methods

{
  "name": "MitchellSchaefferMonodomainForceField",
  "namespace": "sofa_ff",
  "module": "SofaMitchellSchaeffer",
  "include": "MitchellSchaefferMonodomainForceField.h",
  "doc": "MS model\n\nMonodomain reaction–diffusion model with Mitchell–Schaeffer ionic kinetics.\nThis ForceField extends TetrahedronDiffusionFEMForceField to provide:\n  - diffusion of the transmembrane potential u in a tetrahedral mesh,\n  - local Mitchell–Schaeffer reaction terms for u and for the gating\n    variable z,\n  - an optional external stimulus current J_stim.\nThe associated MechanicalObject is expected to store a 2-component state\nper node:\n  q_i = (u_i, z_i),\nwhere:\n  - u_i is the dimensionless transmembrane potential in [0, 1],\n  - z_i is the dimensionless gate variable in [0, 1].\nThe continuous monodomain equations implemented are (in non-dimensional\nform):\n  ∂u/∂t = ∇·(D ∇u)\n          + u^2 (1 - u) / τ_in  -  u z / τ_out  + J_stim,\n  ∂z/∂t =\n    (1 - z) / τ_open    if u < u_gate,\n    - z / τ_close       if u ≥ u_gate.\nIn the SOFA first-order formulation, the ForceField provides f(q) such that\n  M dq/dt = f(q),\nwhere q = (u, z). The diffusion term contributes only to the u-component,\nwhile the gate z follows a purely local ODE without spatial coupling.\nTemplate parameter DataTypes should typically be a 2-component type\n(e.g. sofa::defaulttype::Vec2Types). The first scalar component is assumed\nto correspond to u, the second one to z.",
  "inherits": [
    "TetrahedronDiffusionFEMForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec2Types"
  ],
  "data_fields": [
    {
      "name": "d_tauIn",
      "type": "Real",
      "xmlname": "tauIn",
      "help": "Mitchell–Schaeffer depolarization time constant τ_in."
    },
    {
      "name": "d_tauOut",
      "type": "Real",
      "xmlname": "tauOut",
      "help": "Mitchell–Schaeffer repolarization time constant τ_out."
    },
    {
      "name": "d_tauOpen",
      "type": "Real",
      "xmlname": "tauOpen",
      "help": "Mitchell–Schaeffer gate opening time constant τ_open."
    },
    {
      "name": "d_tauClose",
      "type": "Real",
      "xmlname": "tauClose",
      "help": "Mitchell–Schaeffer gate closing time constant τ_close."
    },
    {
      "name": "d_uGate",
      "type": "Real",
      "xmlname": "uGate",
      "help": "Mitchell–Schaeffer threshold u_gate separating gate dynamics."
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const sofa::core::visual::VisualParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const sofa::core::MechanicalParams *"
        },
        {
          "name": "dataF",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dataX",
          "type": "const DataVecCoord &"
        },
        {
          "name": "dataV",
          "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 sofa::core::MechanicalParams *"
        },
        {
          "name": "dataDF",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dataDX",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildStiffnessMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "matrix",
          "type": "sofa::core::behavior::StiffnessMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const sofa::core::MechanicalParams *"
        },
        {
          "name": "dataX",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getU",
      "return_type": "Real",
      "params": [
        {
          "name": "q",
          "type": "const Coord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "name": "getZ",
      "return_type": "Real",
      "params": [
        {
          "name": "q",
          "type": "const Coord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "name": "getPerPointParam",
      "return_type": "Real",
      "params": [
        {
          "name": "acc",
          "type": "const int &"
        },
        {
          "name": "i",
          "type": "int"
        },
        {
          "name": "nTarget",
          "type": "int"
        },
        {
          "name": "defaultValue",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    }
  ],
  "description": "The `MitchellSchaefferMonodomainForceField` is a specialized force field in the SOFA framework, designed for monodomain reaction-diffusion modeling with Mitchell-Schaeffer ionic kinetics. It extends `TetrahedronDiffusionFEMForceField`, providing both diffusion of the transmembrane potential and local reaction terms involving the gate variable. The associated MechanicalObject is expected to store a two-component state per node: the dimensionless transmembrane potential (u) and the dimensionless gate variable (z). This force field supports optional external stimulus currents. It integrates with other SOFA components through standard mechanical parameters, vertex positions, and deformation data. Practical usage involves configuring time constants (`tauIn`, `tauOut`, `tauOpen`, `tauClose`), threshold values (`uGate`), and specifying external stimuli (`Jstim`). The component assembles reaction forces in `addForce()`, linearized contributions in `addDForce()`, and stiffness matrices for implicit integration schemes.",
  "maths": "The `MitchellSchaefferMonodomainForceField` implements the monodomain reaction-diffusion model with Mitchell-Schaeffer ionic kinetics. The governing equations are given by:\n\n\begin{align*}\n\\frac{∂ u}{∂ t} &= ∇•(D ∇ u) + \\frac{u^2 (1-u)}{τ_\text{in}} - \\frac{u z}{τ_\text{out}} + J_\text{stim} \\\\[6pt]\n\\frac{∂ z}{∂ t} &= \\begin{cases}\n  \\frac{(1-z)}{τ_\text{open}}, & u < u_\text{gate}, \\\\[6pt]\n -\\frac{z}{τ_\text{close}}, & u ≥ u_\text{gate}.\n \\end{cases}\n\\end{align*}\n\nwhere:\n- $u$ is the dimensionless transmembrane potential, varying in $[0, 1]$,\n- $z$ is the dimensionless gate variable, also varying in $[0, 1]$, \n- $J_\text{stim}$ represents an optional external stimulus current density,\n- $τ_\text{in}$ and $τ_\text{out}$ are the depolarization and repolarization time constants, respectively,\n- $τ_\text{open}$ and $τ_\text{close}$ are the gate opening and closing time constants, \n- $u_\text{gate}$ is a threshold value that separates different behaviors of the gate variable.\n\nIn the SOFA first-order formulation, this ForceField contributes to the overall force equation as follows:\n\begin{align*}\nM \\frac{∂ q}{∂ t} = f(q), \\\\[6pt]\nq_i &= (u_i, z_i) \\\\[6pt]\nf_i &= (f_u(i), f_z(i)),\n\\end{align*}\nwhere $M$ is the mass matrix and $q$ is the state vector composed of $u$ and $z$. The force components are given by:\n\n\begin{align*}\nf_u(i) &= \text{{diffusion}}(u)_i + \\frac{z_i u_i^2 (1 - u_i)}{τ_\text{in}} - \\frac{u_i z_i}{τ_\text{out}} + J_\text{stim}(i) \\\\[6pt]\nf_z(i) &= \\begin{cases}\n  \\frac{(1-z_i)}{τ_\text{open}}, & u_i < u_\text{gate}, \\\\[6pt]\n -\\frac{z_i}{τ_\text{close}}, & u_i ≥ u_\text{gate}.\n \\end{cases}\n\\end{align*}\n\nThe component also handles the assembly of the nonlinear reaction terms in `addForce()` and provides a method to build the stiffness matrix for implicit integration schemes, contributing to both diffusion and reaction parts. The overall role is to simulate electrophysiological dynamics within a tetrahedral mesh using Mitchell-Schaeffer ionic kinetics.",
  "abstract": "The `MitchellSchaefferMonodomainForceField` implements a monodomain reaction-diffusion model with Mitchell-Schaeffer ionic kinetics, providing diffusion of transmembrane potential and local reaction terms for the gate variable in a tetrahedral mesh.",
  "sheet": "# MitchellSchaefferMonodomainForceField\n\n## Overview\nThe `MitchellSchaefferMonodomainForceField` is a specialized force field that extends `TetrahedronDiffusionFEMForceField`. It implements the monodomain reaction-diffusion model with Mitchell-Schaeffer ionic kinetics, providing diffusion of the transmembrane potential and local reaction terms for the gate variable. The associated MechanicalObject stores a two-component state per node: the dimensionless transmembrane potential $u$ and the dimensionless gate variable $z$. This component supports optional external stimulus currents.\n\n## Mathematical Model\nThe governing equations implemented by this force field are:\n\\begin{align*}\n  \\frac{∂ u}{∂ t} &= ∇•(D ∇ u) + \\frac{u^2 (1-u)}{τ_\\text{in}} - \\frac{u z}{τ_\\text{out}} + J_\\text{stim}, \\\\\n  \\frac{∂ z}{∂ t} &=\n    \\begin{cases}\n      \\frac{(1-z)}{τ_\\text{open}}, & u < u_\\text{gate}, \\\\\n      -\\frac{z}{τ_\\text{close}}, & u ≥ u_\\text{gate}.\n    \\end{cases}\n\\end{align*}\nIn the SOFA first-order formulation, this ForceField contributes to the overall force equation as follows:\n\\begin{align*}\n  M \\frac{∂ q}{∂ t} &= f(q), \\\\\n  q_i &= (u_i, z_i), \\\\\n  f_i &= (f_u(i), f_z(i)),\n\\end{align*}\nwhere $M$ is the mass matrix and $q$ is the state vector composed of $u$ and $z$. The force components are given by:\n\\begin{align*}\n  f_u(i) &= \\text{{diffusion}}(u)_i + \\frac{z_i u_i^2 (1 - u_i)}{τ_\\text{in}} - \\frac{u_i z_i}{τ_\\text{out}} + J_\\text{stim}(i), \\\\\n  f_z(i) &=\n    \\begin{cases}\n      \\frac{(1-z_i)}{τ_\\text{open}}, & u_i < u_\\text{gate}, \\\\\n      -\\frac{z_i}{τ_\\text{close}}, & u_i ≥ u_\\text{gate}.\n    \\end{cases}\n\\end{align*}\n\n## Parameters and Data\nThe significant parameters exposed by the component are:\n- `tauIn`: Mitchell-Schaeffer depolarization time constant $τ_\\text{in}$.\n- `tauOut`: Mitchell-Schaeffer repolarization time constant $τ_\\text{out}$.\n- `tauOpen`: Mitchell-Schaeffer gate opening time constant $τ_\\text{open}$.\n- `tauClose`: Mitchell-Schaeffer gate closing time constant $τ_\\text{close}$.\n- `uGate`: Mitchell-Schaeffer threshold $u_\\text{gate}$ separating gate dynamics."
}