{
  "name": "ElecPMJCouplingForceField",
  "main": {
    "name": "ElecPMJCouplingForceField",
    "namespace": "sofa_ff",
    "module": "SofaMitchellSchaeffer",
    "include": "ElecPMJCouplingForceField.h",
    "doc": "Bidirectional explicit electrical coupling between the 3D\n\nElecPMJCouplingForceField\n-------------------------\nExplicit, bidirectional electrical coupling between:\n  - the 3D myocardium monodomain Mitchell–Schaeffer model (Vec2, u–z),\n  - and the 1D Purkinje network (Vec1, u_P),\nat a set of Purkinje–myocardium junctions (PMJs).\nDesign:\n  * This force field is attached to the Purkinje electrical node\n    (MechanicalObject<Vec1> under `elec_purk`), so its template\n    parameter `DataTypes` is typically `Vec1Types`.\n  * The myocardium is accessed indirectly through a link to the\n    `MitchellSchaefferMonodomainForceField` (`msModel`), where\n    the global source term `Jstim` is written.\n  * The geometric embedding of the Purkinje graph into the 3D\n    myocardium is inferred from the existing `BarycentricMapping`\n    between myocardial and Purkinje mechanical states (`purkMapping`).",
    "inherits": [
      "ForceField"
    ],
    "templates": [
      "sofa::defaulttype::Vec1Types"
    ],
    "data_fields": [
      {
        "name": "d_gPMJ",
        "type": "Real",
        "xmlname": "gPMJ",
        "help": "Gap-junction conductance (1/s) between Purkinje and myocardium at PMJs."
      }
    ],
    "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 sofa::core::MechanicalParams *"
          },
          {
            "name": "dataF",
            "type": "typename Inherited::DataVecDeriv &"
          },
          {
            "name": "dataX",
            "type": "const typename Inherited::DataVecCoord &"
          },
          {
            "name": "dataV",
            "type": "const typename Inherited::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": "typename Inherited::DataVecDeriv &"
          },
          {
            "name": "dataDX",
            "type": "const typename Inherited::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 typename Inherited::DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computePMJEmbedding",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `ElecPMJCouplingForceField` is a SOFA component designed for bidirectional explicit electrical coupling between the three-dimensional (3D) myocardium modeled using the Mitchell-Schaeffer monodomain model and the one-dimensional (1D) Purkinje network at Purkinje-myocardium junctions (PMJs). This force field, which inherits from `ForceField`, is typically attached to the Purkinje electrical node represented as a `MechanicalObject<Vec1>`. The component interacts with other SOFA components via links to the `MitchellSchaefferMonodomainForceField` for accessing myocardial electrical DOFs and the global source term `Jstim`, and a `BarycentricMapping` that embeds Purkinje mechanical states into the 3D myocardial mesh. During initialization, it computes the geometric embedding of PMJs using tetrahedral barycentric coordinates. The coupling is explicitly handled in time without Jacobian contributions. It requires parameters like gap junction conductance (`gPMJ`)."
  },
  "maths": {
    "maths": "The `ElecPMJCouplingForceField` is designed to model explicit bidirectional electrical coupling between the three-dimensional (3D) myocardium, modeled using the Mitchell-Schaeffer monodomain model, and a one-dimensional (1D) Purkinje network at specific junction points called Purkinje-myocardium junctions (PMJs). This component provides an essential mechanism for simulating how electrical signals propagate between these two domains within a heart simulation framework.\n\n### Mathematical Model:\n\n#### 1. Mitchell-Schaeffer Monodomain Model on the Myocardium:\n\nThe myocardium is represented using the Mitchell-Schaeffer monodomain model, which consists of the following system of partial differential equations (PDEs):\n\n\\[\n\\frac{\\partial u}{\\partial t} = D \\nabla^2 u + I_{ion}(u, z) - J_{stim},\n\\]\n\\[\n\\frac{\\partial z}{\\partial t} = f(u, z),\n\\]\n\nwhere:\n- $u$ is the transmembrane potential,\n- $z$ represents gating variables (such as ionic channel states),\n- $D$ is the diffusion coefficient for electrical conduction,\n- $I_{ion}$ is the ionic current density, which depends on both $u$ and $z$, \n- $f(u, z)$ describes the kinetics of the gating variables,\n- $J_{stim}$ is the global source term that represents external stimuli.\n\n#### 2. Purkinje Network:\n\nThe Purkinje network is modeled as a 1D system where each point on the network has a single electrical potential $u_P$ (modeled with `MechanicalObject<Vec1>`).\n\n\\[\n\\frac{\\partial u_P}{\\partial t} = D_P \\frac{d^2 u_P}{dx^2} + I_{ion}(u_P) - J_{PMJ},\n\\]\n\nwhere:\n- $D_P$ is the diffusion coefficient for Purkinje fibers,\n- $I_{ion}$ represents ionic current in the Purkinje network, and \n- $J_{PMJ}$ accounts for the coupling currents at PMJs.\n\n#### 3. Purkinje-myocardium Junctions (PMJs):\n\nAt each PMJ, a bidirectional electrical coupling is introduced through gap junction conductance $g_{PMJ}$. The coupling mechanism can be described as follows:\n\nFor the myocardial side (at nodes affected by PMJ):\n\\[\nJ_{stim}(x_i) = g_{PMJ} \\left( u_P(x_j) - u(x_i) \\right),\n\\]\nwhere $u(x_i)$ is the transmembrane potential at the myocardium node, and $u_P(x_j)$ is the potential at the corresponding Purkinje node.\n\nFor the Purkinje side (at nodes connected to PMJ):\n\\[\nJ_{PMJ}(x_j) = g_{PMJ} \\left( u(x_i) - u_P(x_j) \\right),\n\\]\nwhere $u_P(x_j)$ is the potential at the Purkinje node, and $u(x_i)$ is the transmembrane potential at the myocardium node.\n\n#### 4. Embedding of PMJs:\n\nThe geometric embedding of each PMJ into the myocardial mesh is computed using tetrahedral barycentric coordinates. This process involves mapping each Purkinje point to a corresponding region in the myocardial mesh and computing weights for the contributing vertices (myocardium nodes).\n\n#### 5. Initialization and Embedding Computation:\n\nDuring initialization, the component computes the embedding of PMJs by associating each Purkinje node with tetrahedral barycentric coordinates that define its position relative to the myocardial mesh. This is achieved through a `BarycentricMapping` which ensures the Purkinje network is geometrically embedded in the 3D myocardium.\n\n### Physical Interpretation:\n\nThe component facilitates the exchange of electrical signals between the complex, spatially distributed myocardium and the fast-conducting Purkinje network. By introducing bidirectional coupling at PMJs, it ensures that changes in potential in one domain can influence the other, effectively simulating realistic cardiac electrophysiology.\n\n- **Bidirectional Coupling:** The coupling allows for feedback from the myocardial tissue to influence the Purkinje network and vice versa, which is crucial for understanding arrhythmias or conduction abnormalities.\n- **Explicit Treatment:** The coupling is treated explicitly in time without Jacobian contributions, making it computationally efficient while still accurately modeling complex interactions.\n\nBy integrating these mathematical formulations into a SOFA-based simulation framework, `ElecPMJCouplingForceField` provides a robust tool for cardiac electrophysiology research and medical applications."
  },
  "summary": {
    "abstract": "The `ElecPMJCouplingForceField` provides bidirectional explicit electrical coupling between the 3D myocardium (Mitchell-Schaeffer model) and the 1D Purkinje network at Purkinje-myocardium junctions (PMJs).",
    "sheet": "\n# ElecPMJCouplingForceField\n\n## Overview\nThe `ElecPMJCouplingForceField` is a specialized force field component in SOFA that handles bidirectional explicit electrical coupling between the three-dimensional (3D) myocardium modeled using the Mitchell-Schaeffer monodomain model and the one-dimensional (1D) Purkinje network at Purkinje-myocardium junctions (PMJs). This component is attached to the Purkinje electrical node represented as a `MechanicalObject<Vec1>` and interacts with other SOFA components via links to the `MitchellSchaefferMonodomainForceField` for accessing myocardial electrical DOFs and the global source term `Jstim`, and a `BarycentricMapping` that embeds Purkinje mechanical states into the 3D myocardial mesh.\n\n## Mathematical Model\nThe component models bidirectional explicit electrical coupling between the three-dimensional (3D) myocardium, modeled using the Mitchell-Schaeffer monodomain model, and a one-dimensional (1D) Purkinje network at specific junction points called Purkinje-myocardium junctions (PMJs).\n\n#### 1. Mitchell-Schaeffer Monodomain Model on the Myocardium:\nThe myocardium is represented using the following system of partial differential equations (PDEs):\n\begin{align*}\n\\frac{\\partial u}{\\partial t} &= D \\nabla^2 u + I_{ion}(u, z) - J_{stim}, \\\\\n\\frac{\\partial z}{\\partial t} &= f(u, z),\n\\end{align*}\nwhere $u$ is the transmembrane potential, $z$ represents gating variables (such as ionic channel states), $D$ is the diffusion coefficient for electrical conduction, $I_{ion}$ is the ionic current density, and $f(u, z)$ describes the kinetics of the gating variables.\n\n#### 2. Purkinje Network:\nThe Purkinje network is modeled as a 1D system where each point on the network has a single electrical potential $u_P$ (modeled with `MechanicalObject<Vec1>`):\n\begin{align*}\n\\frac{\\partial u_P}{\\partial t} &= D_P \\frac{d^2 u_P}{dx^2} + I_{ion}(u_P) - J_{PMJ},\n\\end{align*}\nwhere $D_P$ is the diffusion coefficient for Purkinje fibers, and $I_{ion}$ represents ionic current in the Purkinje network.\n\n#### 3. Purkinje-myocardium Junctions (PMJs):\nThe bidirectional electrical coupling at PMJs is introduced through gap junction conductance $g_{PMJ}$. The coupling mechanism can be described as follows:\nFor the myocardial side (at nodes affected by PMJ):\n\begin{align*}\nJ_{stim}(x_i) &= g_{PMJ} \\left( u_P(x_j) - u(x_i) \\right),\n\\end{align*}\nwhere $u(x_i)$ is the transmembrane potential at the myocardium node, and $u_P(x_j)$ is the potential at the corresponding Purkinje node.\n\nFor the Purkinje side (at nodes connected to PMJ):\n\begin{align*}\nJ_{PMJ}(x_j) &= g_{PMJ} \\left( u(x_i) - u_P(x_j) \\right),\n\\end{align*}\nwhere $u_P(x_j)$ is the potential at the Purkinje node, and $u(x_i)$ is the transmembrane potential at the myocardium node.\n\n#### 4. Embedding of PMJs:\nThe geometric embedding of each PMJ into the myocardial mesh is computed using tetrahedral barycentric coordinates. This process involves mapping each Purkinje point to a corresponding region in the myocardial mesh and computing weights for the contributing vertices (myocardium nodes).\n\n#### 5. Initialization and Embedding Computation:\nDuring initialization, the component computes the embedding of PMJs by associating each Purkinje node with tetrahedral barycentric coordinates that define its position relative to the myocardial mesh.\n\n## Parameters and Data\n- **`gPMJ`:** Gap-junction conductance (1/s) between Purkinje and myocardium at PMJs. Type: `Real`, Default: Not specified.\n\n## Dependencies and Connections\nThe component requires links to:\n- `MitchellSchaefferMonodomainForceField` for accessing the global source term `Jstim` in the myocardial model.\n- `BarycentricMapping` that embeds Purkinje mechanical states into the 3D myocardial mesh."
  }
}