{
  "name": "EjectionConstraint",
  "main": {
    "name": "EjectionConstraint",
    "namespace": "sofa::component::constraintset",
    "module": "SofaTestPlugin",
    "include": "constraint/phases/EjectionConstraint.h",
    "doc": "Surf Constraint",
    "inherits": [
      "BaseOpenSurfaceConstraint"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_Par",
        "type": "Real",
        "xmlname": "Par",
        "help": "Current state at time t"
      },
      {
        "name": "d_Kar",
        "type": "Real",
        "xmlname": "Kar",
        "help": "Valve param"
      },
      {
        "name": "d_Rc",
        "type": "Real",
        "xmlname": "Rc",
        "help": "Windkessel param (Rc)"
      },
      {
        "name": "d_C",
        "type": "Real",
        "xmlname": "C",
        "help": "Windkessel param (C)"
      },
      {
        "name": "d_Rp",
        "type": "Real",
        "xmlname": "Rp",
        "help": "Windkessel param (Rp)"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getConstraintResolution",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const ConstraintParams *"
          },
          {
            "name": "resTab",
            "type": "int &"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "component": {
      "name": "EjectionConstraint",
      "description": "The `EjectionConstraint` is a custom constraint designed for hemodynamics simulations, particularly focusing on the dynamics of blood flow through valves, such as the aortic valve during ventricular systole. This constraint component handles the computation and application of forces to simulate the opening and closing behavior of a valve based on pressure differences across it.",
      "parameters": [
        {
          "name": "Kar",
          "type": "float",
          "description": "Valve parameter that influences the flow rate through the valve. It is related to the valve's stiffness or resistance."
        },
        {
          "name": "Par",
          "type": "float",
          "description": "The current state (pressure) of the system at time t. This represents the pressure threshold that determines whether the valve should be open or closed."
        },
        {
          "name": "Rc",
          "type": "float",
          "description": "Windkessel parameter representing the resistance in the systemic circulation circuit, affecting blood flow dynamics."
        },
        {
          "name": "C",
          "type": "float",
          "description": "Capacitance of the Windkessel model. It represents how much pressure can change for a given amount of volume change and affects the elastic properties of the circulatory system."
        },
        {
          "name": "Rp",
          "type": "float",
          "description": "Peripheral resistance representing the total vascular resistance in the circulatory system, impacting blood flow rates."
        }
      ],
      "methods": [
        {
          "method_name": "init",
          "description": "Initializes the component by calling the parent's initialization method (`Inherit::init()`). It also sets up internal data and prepares for simulation."
        },
        {
          "method_name": "getConstraintResolution",
          "parameters": [
            {
              "name": "cParams",
              "type": "const ConstraintParams*",
              "description": "Defines state vectors to use for positions and velocities, and sets the order of constraints (position, velocity, acceleration)."
            },
            {
              "name": "resTab",
              "type": "std::vector<ConstraintResolution*> &",
              "description": "Result vector that contains constraint resolution algorithms."
            },
            {
              "name": "offset",
              "type": "unsigned int &",
              "description": "Offset used to position the current constraint within the result table (`resTab`)."
            }
          ],
          "return_value": "void",
          "description": "This method computes and adds a new `EjectionConstraintResolution` object to `resTab`. It updates internal states based on simulation time, current pressure (Pv), target flow rate (Qtarget), and valve parameters. This ensures the constraint reflects the dynamic state of the system for each simulation step."
        },
        {
          "method_name": "storeLambda",
          "description": "(Commented out in the provided code) Used to store the lambda value which represents Lagrange multipliers used in enforcing constraints, particularly useful for post-processing or debugging purposes to see how much force is applied at each constraint point. The method also updates `Par`, representing the new state of pressure based on the flow conditions and valve parameters."
        }
      ],
      "notes": "The component is specialized for use with `Vec3Types` floating-point types. It utilizes template specialization to optimize performance by avoiding code generation in multiple compilation units, following best practices for C++ templates as recommended by Stroustrup (see [http://www.stroustrup.com/C++11FAQ.html#extern-templates](http://www.stroustrup.com/C++11FAQ.html#extern-templates)).",
      "internals": {
        "fields": [
          {
            "name": "m_ejection_container",
            "type": "EjectionContainer",
            "description": "Holds internal state information such as `Kar`, `Rc`, `C`, `Rp`, and calculated pressures (`Par`). This container is used to pass necessary parameters for constraint resolution."
          },
          {
            "name": "d_Kar, d_Par, d_Rc, d_C, d_Rp",
            "type": "DataTypes::Real",
            "description": "Internal data fields representing the component's configurable parameters. These are initialized during construction and reflect values like valve stiffness (`Kar`), current state pressure (`Par`), resistances (`Rc`, `Rp`) and capacitance (`C`)."
          }
        ]
      },
      "constraints_resolution_logic": {
        "a1_and_a2_computation": "The constants `a1` and `a2` are computed using the provided parameters to determine how valve dynamics evolve over time. Specifically, they are used in determining whether new pressure values should be computed based on the current flow conditions.",
        "lambda_calculation": "Lambda calculation involves evaluating the difference between current state (`dfree`) and updated pressures considering resistances and capacitance. Depending on the pressure condition (if `Pv < Par`), different formulas are applied to ensure accurate constraint resolution."
      }
    }
  },
  "maths": {
    "maths": "The **EjectionConstraint** is designed to model the behavior of a valve in a fluid dynamics simulation, specifically focusing on the ejection phase. The component handles various parameters related to the valve's state and interactions with the surrounding fluid, such as pressure and flow rates.\n\n### Parameters:\n- **Par (P_{ar})**: Current state parameter at time t that represents the arterial pressure reference for the valve's closure behavior.\n- **Kar (K_{ar})**: Valve opening coefficient or stiffness which determines how open or closed the valve is.\n- **Rc (R_c)**: Resistance parameter of the artery downstream from the valve, affecting the fluid dynamics within this segment.\n- **C (C)**: Compliance of the artery downstream from the valve, indicating its ability to expand and contract in response to pressure changes.\n- **Rp (R_p)**: Resistance parameter upstream from the valve, representing the resistance to flow through the valve itself.\n\n### Mathematical Description:\n1. **Initialization**:\n   - The parameters `Kar`, `Par`, `Rc`, `C`, and `Rp` are initialized during object construction.\n\n2. **Simulation State Update (init method)**:\n   - At each simulation step, the component updates internal state variables such as `time`, `dt`, `Pv`, `Qtarget`, and sets the valve parameters from user-defined values (`Kar`, `Rc`, `C`, `Rp`, `Qt`).\n\n3. **Constraint Resolution (getConstraintResolution method)**:\n   - The component creates an instance of `EjectionConstraintResolution` to manage constraints related to the valve's dynamics.\n   - For calculating the new value of `Par`, the following equation is used:\n     \\[ a_1 = dt \times \\left(\\frac{R_p + R_c}{\\tau}\\right) + R_c \\]\n     \\[ a_2 = 1 + \\frac{dt}{\\tau} \\]\n     where \\(\\tau = R_p \\times C\\).\n   - The new arterial pressure reference `Par` is updated using the following formula:\n     \\[ P_{ar}(t+dt) = \\frac{a_1 Q_{ar} - R_c Q_{ar,prev} + Par(t)}{a_2} \\]\n\n4. **Valve Dynamics (lambda computation)**:\n   - The lambda value in the constraint resolution method calculates the reaction force based on various parameters and current state.\n   - If `Pv < Par`, then the valve closes (`lambda = -dfree / W`).\n   - Otherwise, the lambda is calculated as:\n     \\[ A = K_{ar} (\\tau P_{ar} + \\tau R_c Q_t) \\]\n     \\[ \\alpha = \\left(\\frac{dt + \\tau}{dt}\\right) K_{ar} \\]\n     \\[ B = \\frac{dt}{dt + \\tau + dt(R_p + R_c)K_{ar} + K_{ar}\\tau R_c} \\]\n     and the lambda becomes:\n     \\[ \\lambda = \\frac{A - B dfree}{W B + \\alpha} \\]"
  },
  "summary": {
    "abstract": "The EjectionConstraint manages the dynamics of a valve during ejection phases in fluid simulations by updating arterial pressure and calculating reaction forces based on specified parameters.",
    "sheet": "# EjectionConstraint\n\n## Overview\nEjectionConstraint is part of the SofaTestPlugin module and inherits from BaseOpenSurfaceConstraint. It handles the dynamics of a valve during ejection phases, focusing on updating arterial pressure and calculating reaction forces.\n\n## Mathematical Model\nThe component updates internal state variables at each simulation step using the following equations:\n- Initialization parameters: `Kar`, `Par`, `Rc`, `C`, and `Rp` are set during object construction.\n- Simulation State Update (init method):\n  - At each time step, update internal state variables such as `time`, `dt`, `Pv`, `Qtarget`, and valve parameters from user-defined values (`Kar`, `Rc`, `C`, `Rp`, `Qt`).\n\nFor constraint resolution (getConstraintResolution method), the following equations are used:\n- Calculate new value of `Par` using:\n  \\\\[ a_1 = dt \\times \\left(\\frac{R_p + R_c}{\\tau}\\right) + R_c \\\\]\n  \\\\[ a_2 = 1 + \\frac{dt}{\\tau} \\\\]\n  where \\\\(\\tau = R_p \\times C\\\\).\n- Update arterial pressure reference `Par` using:\n  \\\\[ P_{ar}(t+dt) = \\frac{a_1 Q_{ar} - R_c Q_{ar,prev} + Par(t)}{a_2} \\\\]\n\nFor valve dynamics (lambda computation):\n- If \\\\(Pv < Par\\\\), the valve closes (`lambda = -dfree / W`).\n- Otherwise, calculate lambda as:\n  \\\\[ A = K_{ar} (\\tau P_{ar} + \\tau R_c Q_t) \\\\]\n  \\\\[ \\alpha = \\left(\\frac{dt + \\tau}{dt}\\right) K_{ar} \\\\]\n  \\\\[ B = \\frac{dt}{dt + \\tau + dt(R_p + R_c)K_{ar} + K_{ar}\\tau R_c} \\\\]\n  and the lambda becomes:\n  \\\\[ \\lambda = \\frac{A - B dfree}{W B + \\alpha} \\\\]\n\n## Parameters and Data\n- **Par (P_{ar})**: Current state parameter at time t representing arterial pressure reference for valve closure behavior.\n- **Kar (K_{ar})**: Valve opening coefficient or stiffness determining how open or closed the valve is.\n- **Rc (R_c)**: Resistance parameter of the artery downstream from the valve, affecting fluid dynamics within this segment.\n- **C (C)**: Compliance of the artery downstream from the valve, indicating its ability to expand and contract in response to pressure changes.\n- **Rp (R_p)**: Resistance parameter upstream from the valve, representing resistance to flow through the valve itself.\n\n## Practical Notes\nThe component requires careful configuration of parameters such as `Kar`, `Par`, `Rc`, `C`, and `Rp` for numerical stability. The lambda value calculation ensures proper reaction forces are applied based on current state and user-defined values."
  }
}