{
  "name": "BaseOpenSurfaceConstraint",
  "main": {
    "name": "BaseOpenSurfaceConstraint",
    "namespace": "sofa::component::constraintset",
    "module": "SofaTestPlugin",
    "include": "constraint/BaseOpenSurfaceConstraint.h",
    "doc": "Surf Constraint\n\nThis component implements a Lagrange constraint problem resolution\nwith integrated volume computation (dV as constraint Jacobian row).\nTopology is found automatically from the context via getMeshTopologyLink()\n(no link).",
    "inherits": [
      "LagrangianConstraint"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_volume",
        "type": "Real",
        "xmlname": "volume",
        "help": "Volume of the inner surface"
      },
      {
        "name": "d_dV",
        "type": "VecDeriv",
        "xmlname": "dV",
        "help": "Derivative of volume w.r.t. vertex positions"
      },
      {
        "name": "d_holes",
        "type": "Holes",
        "xmlname": "edges_on_border",
        "help": "List of boundary edge loops"
      },
      {
        "name": "d_flow",
        "type": "Real",
        "xmlname": "flow",
        "help": "Flow at the beginning of the time step"
      },
      {
        "name": "d_previous_flow",
        "type": "Real",
        "xmlname": "previous_flow",
        "help": "Flow at the previous time step"
      },
      {
        "name": "d_show_boundary_edges",
        "type": "bool",
        "xmlname": "show_boundary_edges",
        "help": "Draw boundary edges"
      },
      {
        "name": "d_show_dV",
        "type": "bool",
        "xmlname": "showdV",
        "help": "Draw dV vectors"
      },
      {
        "name": "d_dV_scale",
        "type": "Real",
        "xmlname": "dV_scale",
        "help": "Scale for dV vectors"
      },
      {
        "name": "d_flipNormal",
        "type": "bool",
        "xmlname": "flipNormal",
        "help": "Invert normal for constraint direction"
      },
      {
        "name": "d_next_Pv",
        "type": "Real",
        "xmlname": "nextPv",
        "help": "Pressure (lambda/dt) from constraint"
      },
      {
        "name": "d_Pv",
        "type": "Real",
        "xmlname": "Pv",
        "help": "Ventricular pressure at time t"
      },
      {
        "name": "d_Qtarget",
        "type": "Real",
        "xmlname": "Qtarget",
        "help": "Target flow in constraint law"
      }
    ],
    "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": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "vparams",
            "type": "const sofa::core::visual::VisualParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildConstraintMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "c_d",
            "type": "DataMatrixDeriv &"
          },
          {
            "name": "cIndex",
            "type": "unsigned int &"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          }
        ],
        "is_virtual": true,
        "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"
      },
      {
        "name": "storeLambda",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const ConstraintParams *"
          },
          {
            "name": "res",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "lambda",
            "type": "const sofa::linearalgebra::BaseVector *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getConstraintViolation",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "resV",
            "type": "linearalgebra::BaseVector *"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          },
          {
            "name": "v",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "update_volume",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "get_boundary_edges",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "compute_volume",
        "return_type": "Real",
        "params": [
          {
            "name": "x",
            "type": "const VecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "compute_volume_derivative",
        "return_type": "void",
        "params": [
          {
            "name": "x",
            "type": "const VecCoord &"
          },
          {
            "name": "dvol",
            "type": "VecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "all_used",
        "return_type": "bool",
        "params": [
          {
            "name": "x",
            "type": "const VecBool &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "get_first",
        "return_type": "int",
        "params": [
          {
            "name": "x",
            "type": "const VecBool &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `BaseOpenSurfaceConstraint` is a constraint component in the SOFA ecosystem, specifically designed to handle Lagrange constraints with integrated volume computation (dV as part of the Jacobian row). It is part of the `sofa::component::constraintset` namespace and included within the `SofaTestPlugin` module. This component does not require any explicit link to topology; instead, it retrieves the mesh topology automatically from its context via `getMeshTopologyLink()`.\n\n### Role and Purpose\nThe primary role of this component is to manage constraints on an open surface by computing volume and ensuring that volume changes are accounted for in constraint resolution. It updates the volume and computes derivatives with respect to vertex positions, which helps maintain the integrity of surface-based simulations involving flow or pressure constraints.\n\n### Interactions with Other Components\nThis component inherits from `LagrangianConstraint` and implements various methods required by its parent class (e.g., `buildConstraintMatrix`, `getConstraintResolution`, `storeLambda`, `getConstraintViolation`). It interacts with the mechanical state of the system via `MechanicalState` to retrieve positions, velocities, and topology information. The constraint resolution is handled through a custom `BaseOpenSurfaceConstraintResolution` object, which stores necessary data for each time step.\n\n### Practical Usage Guidance and Data Fields\n- **Volume Management:** This component computes and manages the volume of an open surface and its derivatives with respect to vertex positions (`d_volume`, `d_dV`). It also tracks flow and pressure values at different points in time (`d_flow`, `d_previous_flow`, `d_Pv`, `d_next_Pv`).\n- **Boundary Edges Handling:** The component identifies boundary edges of the surface, storing these as loops (`d_holes`), which are essential for maintaining topological consistency.\n- **Visualization Options:** Users can opt to visualize the boundary edges and dV vectors (`d_show_boundary_edges`, `d_show_dV`). Scaling factors for these visualizations can be set via `d_dV_scale`. The normal direction for constraints can also be flipped using `d_flipNormal`.\n- **Target Flow:** A target flow value is maintained (`d_Qtarget`) which influences the constraint resolution process. This value helps define the desired behavior of the system, particularly in contexts involving fluid dynamics or pressure-driven flows."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of BaseOpenSurfaceConstraint\n\n## Overview\nThe `BaseOpenSurfaceConstraint` is a Lagrange constraint component used in the SOFA (Simulation Open Framework Architecture) framework, specifically designed for managing constraints on an open surface. This component integrates volume computation into its operations by calculating the volume and its derivatives with respect to vertex positions. The primary role of this component is to maintain consistent topological properties while ensuring that pressure or flow constraints are accurately enforced.\n\n## Mathematical Formulation\n### Volume Computation\nThe volume $V$ of an open surface is computed as a function of vertex positions, denoted by the set of coordinates ${\\mathbf{x} = (x_1, x_2, \\ldots, x_n)}$. For each triangle in the mesh topology, the volume contribution is given by:\n\n$$\nV_{\\text{triangle}}(t) = \\frac{1}{6} \\left| \\vec{\times}(\\mathbf{x}_{t[0]}, \\mathbf{x}_{t[1]}) + \\vec{\times}(\\mathbf{x}_{t[1]}, \\mathbf{x}_{t[2]}) + \\vec{\times}(\\mathbf{x}_{t[2]}, \\mathbf{x}_{t[0]}) \\right|\n$$\n\nwhere $\\vec{\times}$ denotes the cross product. The total volume is then the sum of contributions from all triangles and holes (boundary edges):\n\n$$\nV = \\sum_{i} V_{\\text{triangle}}(i) + \\sum_{j} V_{\\text{hole}}(j)\n$$\n\n### Volume Derivative Computation\nThe derivative of the volume with respect to each vertex position is computed as follows. For a given point $\\mathbf{x}_i$, its contribution to the total volume derivative is:\n\n$$\ndV_i = \\sum_{t \\in T(i)} \\frac{1}{6} (\\vec{\times}(\\mathbf{x}_{t[0]}, \\mathbf{x}_{t[1]}) + \\vec{\times}(\\mathbf{x}_{t[1]}, \\mathbf{x}_{t[2]}) + \\vec{\times}(\\mathbf{x}_{t[2]}, \\mathbf{x}_{t[0]}))\n$$\n\nwhere $T(i)$ is the set of triangles that include vertex $i$. For holes (boundary edges), the contribution to the volume derivative includes additional terms accounting for contributions from boundary loops.\n\n### Constraint Resolution\nThe constraint resolution process involves constructing a Lagrange multiplier-based system. The Jacobian row corresponding to the volume constraint is computed using the derivatives calculated above. The constraint equation can be expressed as:\n\n$$\ng(\\mathbf{x}) = V(\\mathbf{x}) - V_{0} = 0\n$$\n\nwhere $V_0$ is a reference or target volume value.\n\n### Flow and Pressure Management\nThe component maintains flow ($Q$) and pressure ($P$) values at different time steps. The pressure $P$ can be related to the change in volume through the constraint equation, ensuring that the system adheres to specified flow rates ($\\dot{Q}$):\n\n$$\n\\dot{Q} = \\frac{dV}{dt}\n$$\n\nThe target flow rate is stored in `d_Qtarget` and influences the constraint resolution process.\n\n## Physical Description\n### Volume Changes and Constraint Enforcement\nThis component enforces constraints on an open surface by monitoring volume changes. The computed derivatives $dV$ are used to update Lagrange multipliers, which are then utilized to adjust vertex positions to maintain a consistent topology. This is particularly important in simulations involving fluid dynamics where maintaining pressure or flow constraints is critical.\n\n### Boundary Edges Handling\nThe component identifies boundary edges of the surface and stores them as loops (`d_holes`). These loops ensure that the topological consistency of the open surface is maintained, preventing self-intersections or other topological inconsistencies during simulation.\n\n### Visualization Options\nUsers can visualize the boundary edges and $dV$ vectors to better understand the behavior of the constrained system. The `d_show_boundary_edges` and `d_show_dV` options allow for visual inspection, while scaling factors (`d_dV_scale`) enable customization of visualization properties.\n\n## Summary\nThe `BaseOpenSurfaceConstraint` component ensures that an open surface remains topologically consistent and adheres to specified flow or pressure constraints. By integrating volume computation and its derivatives into the Lagrange constraint system, it provides a robust framework for simulating complex fluid dynamics scenarios in SOFA."
  },
  "summary": {
    "abstract": "The `BaseOpenSurfaceConstraint` manages Lagrange constraints on an open surface by computing volume and its derivatives, ensuring topological consistency while enforcing pressure or flow constraints.",
    "sheet": "# BaseOpenSurfaceConstraint\n\n## Overview\nThe `BaseOpenSurfaceConstraint` is a Lagrange constraint component in the SOFA framework designed to manage constraints on an open surface. It automatically retrieves mesh topology from its context and integrates volume computation into its operations, ensuring topological consistency while enforcing pressure or flow constraints.\n\n## Mathematical Model\n### Volume Computation\nThe volume $V$ of an open surface is computed as a function of vertex positions ${\\mathbf{x} = (x_1, x_2, \\ldots, x_n)}$. For each triangle in the mesh topology, the volume contribution is given by:\n\n$$\nV_{\\text{triangle}}(t) = \\frac{1}{6} \\left| \\vec{\\times}(\\mathbf{x}_{t[0]}, \\mathbf{x}_{t[1]}) + \\vec{\\times}(\\mathbf{x}_{t[1]}, \\mathbf{x}_{t[2]}) + \\vec{\\times}(\\mathbf{x}_{t[2]}, \\mathbf{x}_{t[0]}) \\right|\n$$\n\nwhere $\\vec{\\times}$ denotes the cross product. The total volume is then the sum of contributions from all triangles and holes (boundary edges):\n\n$$\nV = \\sum_{i} V_{\\text{triangle}}(i) + \\sum_{j} V_{\\text{hole}}(j)\n$$\n\n### Volume Derivative Computation\nThe derivative of the volume with respect to each vertex position is computed as follows. For a given point $\\mathbf{x}_i$, its contribution to the total volume derivative is:\n\n$$\ndV_i = \\sum_{t \\in T(i)} \\frac{1}{6} (\\vec{\\times}(\\mathbf{x}_{t[0]}, \\mathbf{x}_{t[1]}) + \\vec{\\times}(\\mathbf{x}_{t[1]}, \\mathbf{x}_{t[2]}) + \\vec{\\times}(\\mathbf{x}_{t[2]}, \\mathbf{x}_{t[0]}))\n$$\n\nwhere $T(i)$ is the set of triangles that include vertex $i$. For holes (boundary edges), the contribution to the volume derivative includes additional terms accounting for contributions from boundary loops.\n\n### Constraint Resolution\nThe constraint resolution process involves constructing a Lagrange multiplier-based system. The Jacobian row corresponding to the volume constraint is computed using the derivatives calculated above. The constraint equation can be expressed as:\n\n$$\ng(\\mathbf{x}) = V(\\mathbf{x}) - V_{0} = 0\n$$\n\nwhere $V_0$ is a reference or target volume value.\n\n### Flow and Pressure Management\nThe component maintains flow ($Q$) and pressure ($P$) values at different time steps. The pressure $P$ can be related to the change in volume through the constraint equation, ensuring that the system adheres to specified flow rates ($\\dot{Q}$):\n\n$$\n\\dot{Q} = \\frac{dV}{dt}\n$$\n\nThe target flow rate is stored in `d_Qtarget` and influences the constraint resolution process.\n\n## Parameters and Data\n- **Volume Management:** This component computes and manages the volume of an open surface (`d_volume`) and its derivatives with respect to vertex positions (`d_dV`). It also tracks flow and pressure values at different points in time (`d_flow`, `d_previous_flow`, `d_Pv`, `d_next_Pv`).\n- **Boundary Edges Handling:** The component identifies boundary edges of the surface, storing these as loops (`d_holes`), which are essential for maintaining topological consistency.\n- **Visualization Options:** Users can opt to visualize the boundary edges and dV vectors (`d_show_boundary_edges`, `d_show_dV`). Scaling factors for these visualizations can be set via `d_dV_scale`. The normal direction for constraints can also be flipped using `d_flipNormal`.\n- **Target Flow:** A target flow value is maintained (`d_Qtarget`) which influences the constraint resolution process. This value helps define the desired behavior of the system, particularly in contexts involving fluid dynamics or pressure-driven flows."
  }
}