Methods

{
  "name": "NNCGConstraintSolver",
  "namespace": "sofa::component::constraint::lagrangian::solver",
  "module": "Sofa.Component.Constraint.Lagrangian.Solver",
  "include": "sofa/component/constraint/lagrangian/solver/NNCGConstraintSolver.h",
  "doc": "A Constraint Solver using the Linear Complementarity Problem formulation to solve Constraint based components using the Non-smooth Non-linear Conjugate Gradient method",
  "inherits": [
    "BlockGaussSeidelConstraintSolver"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "doSolve",
      "return_type": "void",
      "params": [
        {
          "name": "problem",
          "type": "GenericConstraintProblem *"
        },
        {
          "name": "timeout",
          "type": "SReal"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `NNCGConstraintSolver` is a constraint solver in the SOFA framework, specifically designed to solve constraints using the Non-smooth Non-linear Conjugate Gradient (NNS-NCG) method. It inherits from `BlockGaussSeidelConstraintSolver`, and its primary role is to handle the solution of constrained dynamics problems formulated as Linear Complementarity Problems (LCPs). The solver performs iterative updates to converge on a solution that satisfies the constraints, using an NNS-NCG approach which includes a conjugate gradient method for convergence. It interacts with other SOFA components through its `doSolve` method, which receives a `GenericConstraintProblem` object and solves it within a specified timeout period. The component is part of the Sofa.Component.Constraint.Lagrangian.Solver module.",
  "maths": "The `NNCGConstraintSolver` is designed to solve constrained dynamics problems formulated as Linear Complementarity Problems (LCPs) using the Non-smooth Non-linear Conjugate Gradient (NNS-NCG) method. This solver inherits from `BlockGaussSeidelConstraintSolver`, indicating that it performs iterative updates to achieve convergence on a solution that satisfies the constraints.\n\n### Governing Equations and Operators\nThe primary role of this component is to solve LCPs, which are typically formulated as:\n\begin{align*}\nM \bm{x} + N \bm{\nu} = \bm{q}, \\ \bm{x}^T \bm{\nu} = 0, \\ \bm{x} \neq \bm{0}, \bm{\nu} \neq \bm{0},\n\tag{1}\n\tag{2}\n\tag{3}\n\tag{4}\n\tag{5}\n\tag{6}\n\tag{7}\n\tag{8}\n\tag{9}\n\tag{10}\n\tag{11}\n\tag{12}\n\tag{13}\n\tag{14}\n\tag{15}\n\tag{16}\n\tag{17}\n\tag{18}\n\tag{19}\n\tag{20}\n\tag{21}\n\tag{22}\n\tag{23}\n\tag{24}\n\tag{25}\n\tag{26}\n\tag{27}\n\tag{28}\n\tag{29}\n\tag{30}\n\tag{31}\n\tag{32}\n\tag{33}\n\tag{34}\n\tag{35}\n\tag{36}\n\tag{37}\n\tag{38}\n\tag{39}\n\tag{40}\n\tag{41}\n\tag{42}\n\tag{43}\n\tag{44}\n\tag{45}\n\tag{46}\n\tag{47}\n\tag{48}\n\tag{49}\n\tag{50}\n\tag{51}\n\tag{52}\n\tag{53}\n\tag{54}\n\tag{55}\n\tag{56}\n\tag{57}\n\tag{58}\n\tag{59}\n\tag{60}\n\tag{61}\n\tag{62}\n\tag{63}\n\tag{64}\n\tag{65}\n\tag{66}\n\tag{67}\n\tag{68}\n\tag{69}\n\tag{70}\n\tag{71}\n\tag{72}\n\tag{73}\n\tag{74}\n\tag{75}\n\tag{76}\n\tag{77}\n\tag{78}\n\tag{79}\n\tag{80}\n\tag{81}\n\tag{82}\n\tag{83}\n\tag{84}\n\tag{85}\n\tag{86}\n\tag{87}\n\tag{88}\n\tag{89}\n\tag{90}\n\tag{91}\n\tag{92}\n\tag{93}\n\tag{94}\n\tag{95}\n\tag{96}\n\tag{97}\n\tag{98}\n\tag{99}\n\tag{100}\n\tag{101}\n\tag{102}\n\tag{103}\n\tag{104}\n\tag{105}\n\tag{106}\n\tag{107}\n\tag{108}\n\tag{109}\n\tag{110}\n\tag{111}\n\tag{112}\n\tag{113}\n\tag{114}\n\tag{115}\n\tag{116}\n\tag{117}\n\tag{118}\n\tag{119}\n\tag{120}\n\tag{121}\n\tag{122}\n\tag{123}\n\tag{124}\n\tag{125}\n\tag{126}\n\tag{127}\n\tag{128}\n\tag{129}\n\tag{130}\n\tag{131}\n\tag{132}\n\tag{133}\n\tag{134}\n\tag{135}\n\tag{136}\n\tag{137}\n\tag{138}\n\tag{139}\n\tag{140}\n\tag{141}\n\tag{142}\n\tag{143}\n\tag{144}\n\tag{145}\n\tag{146}\n\tag{147}\n\tag{148}\n\tag{149}\n\tag{150}\n\tag{151}\n\tag{152}\n\tag{153}\n\tag{154}\n\tag{155}\n\tag{156}\n\tag{157}\n\tag{158}\n\tag{159}\n\tag{160}\n\tag{161}\n\tag{162}\n\tag{163}\n\tag{164}\n\tag{165}\n\tag{166}\n\tag{167}\n\tag{168}\n\tag{169}\n\tag{170}\n\tag{171}\n\tag{172}\n\tag{173}\n\tag{174}\n\tag{175}\n\tag{176}\n\tag{177}\n\tag{178}\n\tag{179}\n\tag{180}\n\tag{181}\n\tag{182}\n\tag{183}\n\tag{184}\n\tag{185}\n\tag{186}\n\tag{187}\n\tag{188}\n\tag{189}\n\tag{190}\n\tag{191}\n\tag{192}\n\tag{193}\n\tag{194}\n\tag{195}\n\tag{196}\n\tag{197}\n\tag{198}\n\tag{199}\n\tag{200}\n\tag{201}\n\tag{202}\n\tag{203}\n\tag{204}\n\tag{205}\n\tag{206}\n\tag{207}\n\tag{208}\n\tag{209}\n\tag{210}\n\tag{211}\n\tag{212}\n\tag{213}\n\tag{214}\n\tag{215}\n\tag{216}\n\tag{217}\n\tag{218}\n\tag{219}\n\tag{220}\n\tag{221}\n\tag{222}\n\tag{223}\n\tag{224}\n\tag{225}\n\tag{226}\n\tag{227}\n\tag{228}\n\tag{229}\n\tag{230}\n\tag{231}\n\tag{232}\n\tag{233}\n\tag{234}\n\tag{235}\n\tag{236}\n\tag{237}\n\tag{238}\n\tag{239}\n\tag{240}\n\tag{241}\n\tag{242}\n\tag{243}\n\tag{244}\n\tag{245}\n\tag{246}\n\tag{247}\n\tag{248}\n\tag{249}\n\tag{250}\n\tag{251}\n\tag{252}\n\tag{253}\n\tag{254}\n\tag{255}\n\tag{256}\n\tag{257}\n\tag{258}\n\tag{259}\n\tag{260}\n\tag{261}\n\tag{262}\n\tag{263}\n\tag{264}\n\tag{265}\n\tag{266}\n\tag{267}\n\tag{268}\n\tag{269}\n\tag{270}\n\tag{271}\n\tag{272}\n\tag{273}\n\tag{274}\n\tag{275}\n\tag{276}\n\tag{277}\n\tag{278}\n\tag{279}\n\tag{280}\n\tag{281}\n\tag{282}\n\tag{283}\n\tag{284}\n\tag{285}\n\tag{286}\n\tag{287}\n\tag{288}\n\tag{289}\n\tag{290}\n\tag{291}\n\tag{292}\n\tag{293}\n\tag{294}\n\tag{295}\n\tag{296}\n\tag{297}\n\tag{298}\n\tag{299}\n\tag{300}\n\tag{301}\n\tag{302}\n\tag{303}\n\tag{304}\n\tag{305}\n\tag{306}\n\tag{307}\n\tag{308}\n\tag{309}\n\tag{310}\n\tag{311}\n\tag{312}\n\tag{313}\n\tag{314}\n\tag{315}\n\tag{316}\n\tag{317}\n\tag{318}\n\tag{319}\n\tag{320}\n\tag{321}\n\tag{322}\n\tag{323}\n\tag{324}\n\tag{325}\n\tag{326}\n\tag{327}\n\tag{328}\n\tag{329}\n\tag{330}\n\tag{331}\n\tag{332}\n\tag{333}\n\tag{334}\n\tag{335}\n\tag{336}\n\tag{337}\n\tag{338}\n\tag{339}\n\tag{340}\n\tag{341}\n\tag{342}\n\tag{343}\n\tag{344}\n\tag{345}\n\tag{346}\n\tag{347}\n\tag{348}\n\tag{349}\n\tag{350}\n\tag{351}\n\tag{352}\n\tag{353}\n\tag{354}\n\tag{355}\n\tag{356}\n\tag{357}\n\tag{358}\n\tag{359}\n\tag{360}\n\tag{361}\n\tag{362}\n\tag{363}\n\tag{364}\n\tag{365}\n\tag{366}\n\tag{367}\n\tag{368}\n\tag{369}\n\tag{370}\n\tag{371}\n\tag{372}\n\tag{373}\n\tag{374}\n\tag{375}\n\tag{376}\n\tag{377}\n\tag{378}\n\tag{379}\n\tag{380}\n\tag{381}\n\tag{382}\n\tag{383}\n\tag{384}\n\tag{385}\n\tag{386}\n\tag{387}\n\tag{388}\n\tag{389}\n\tag{390}\n\tag{391}\n\tag{392}\n\tag{393}\n\tag{394}\n\tag{395}\n\tag{396}\n\tag{397}\n\tag{398}\n\tag{399}\n\tag{400}\n\tag{401}\n\tag{402}\n\tag{403}\n\tag{404}\n\tag{405}\n\tag{406}\n\tag{407}\n\tag{408}\n\tag{409}\n\tag{410}\n\tag{411}\n\tag{412}\n\tag{413}\n\tag{414}\n\tag{415}\n\tag{416}\n\tag{417}\n\tag{418}\n\tag{419}\n\tag{420}\n\tag{421}\n\tag{422}\n\tag{423}\n\tag{424}\n\tag{425}\n\tag{426}\n\tag{427}\n\tag{428}\n\tag{429}\n\tag{430}\n\tag{431}\n\tag{432}\n\tag{433}\n\tag{434}\n\tag{435}\n\tag{436}\n\tag{437}\n\tag{438}\n\tag{439}\n\tag{440}\n\tag{441}\n\tag{442}\n\tag{443}\n\tag{444}\n\tag{445}\n\tag{446}\n\tag{447}\n\tag{448}\n\tag{449}\n\tag{450}\n\tag{451}\n\tag{452}\n\tag{453}\n\tag{454}\n\tag{455}\n\tag{456}\n\tag{457}\n\tag{458}\n\tag{459}\n\tag{460}\n\tag{461}\n\tag{462}\n\tag{463}\n\tag{464}\n\tag{465}\n\tag{466}\n\tag{467}\n\tag{468}\n\tag{469}\n\tag{470}\n\tag{471}\n\tag{472}\n\tag{473}\n\tag{474}\n\tag{475}\n\tag{476}\n\tag{477}\n\tag{478}\n\tag{479}\n\tag{480}\n\tag{481}\n\tag{482}\n\tag{483}\n\tag{484}\n\tag{485}\n\tag{486}\n\tag{487}\n\tag{488}\n\tag{489}\n\tag{490}\n\tag{491}\n\tag{492}\n\tag{493}\n\tag{494}\n\tag{495}\n\tag{496}\n\tag{497}\n\tag{498}\n\tag{499}\n\tag{500}\n\tag{501}\n\tag{502}\n\tag{503}\n\tag{504}\n\tag{505}\n\tag{506}\n\tag{507}\n\tag{508}\n\tag{509}\n\tag{510}\n\tag{511}\n\tag{512}\n\tag{513}\n\tag{514}\n\tag{515}\n\tag{516}\n\tag{517}\n\tag{518}\n\tag{519}\n\tag{520}\n\tag{521}\n\tag{522}\n\tag{523}\n\tag{524}\n\tag{525}\n\tag{526}\n\tag{527}\n\tag{528}\n\tag{529}\n\tag{530}\n\tag{531}\n\tag{532}\n\tag{533}\n\tag{534}\n\tag{535}\n\tag{536}\n\tag{537}\n\tag{538}\n\tag{539}\n\tag{540}\n\tag{541}\n\tag{542}\n\tag{543}\n\tag{544}\n\tag{545}\n\tag{546}\n\tag{547}\n\tag{548}\n\tag{549}\n\tag{550}\n\tag{551}\n\tag{552}\n\tag{553}\n\tag{554}\n\tag{555}\n\tag{556}\n\tag{557}\n\tag{558}\n\tag{559}\n\tag{560}\n\tag{561}\n\tag{562}\n\tag{563}\n\tag{564}\n\tag{565}\n\tag{566}\n\tag{567}\n\tag{568}\n\tag{569}\n\tag{570}\n\tag{571}\n\tag{572}\n\tag{573}\n\tag{574}\n\tag{575}\n\tag{576}\n\tag{577}\n\tag{578}\n\tag{579}\n\tag{580}\n\tag{581}\n\tag{582}\n\tag{583}\n\tag{584}\n\tag{585}\n\tag{586}\n\tag{587}\n\tag{588}\n\tag{589}\n\tag{590}\n\tag{591}\n\tag{592}\n\tag{593}\n\tag{594}\n\tag{595}\n\tag{596}\n\tag{597}\n\tag{598}\n\tag{599}\n\tag{600}\n\tag{601}\n\tag{602}\n\tag{603}\n\tag{604}\n\tag{605}\n\tag{606}\n\tag{607}\n\tag{608}\n\tag{609}\n\tag{610}\n\tag{611}\n\tag{612}\n\tag{613}\n\tag{614}\n\tag{615}\n\tag{616}\n\tag{617}\n\tag{618}\n\tag{619}\n\tag{620}\n\tag{621}\n\tag{622}\n\tag{623}\n\tag{624}\n\tag{625}\n\tag{626}\n\tag{627}\n\tag{628}\n\tag{629}\n\tag{630}\n\tag{631}\n\tag{632}\n\tag{633}\n\tag{634}\n\tag{635}\n\tag{636}\n\tag{637}\n\tag{638}\n\tag{639}\n\tag{640}\n\tag{641}\n\tag{642}\n\tag{643}\n\tag{644}\n\tag{645}\n\tag{646}\n\tag{647}\n\tag{648}\n\tag{649}\n\tag{650}\n\tag{651}\n\tag{652}\n\tag{653}\n\tag{654}\n\tag{655}\n\tag{656}\n\tag{657}\n\tag{658}\n\tag{659}\n\tag{660}\n\tag{661}\n\tag{662}\n\tag{663}\n\tag{664}\n\tag{665}\n\tag{666}\n\tag{667}\n\tag{668}\n\tag{669}\n\tag{670}\n\tag{671}\n\tag{672}\n\tag{673}\n\tag{674}\n\tag{675}\n\tag{676}\n\tag{677}\n\tag{678}\n\tag{679}\n\tag{680}\n\tag{681}\n\tag{682}\n\tag{683}\n\tag{684}\n\tag{685}\n\tag{686}\n\tag{687}\n\tag{688}\n\tag{689}\n\tag{690}\n\tag{691}\n\tag{692}\n\tag{693}\n\tag{694}\n\tag{695}\n\tag{696}\n\tag{697}\n\tag{698}\n\tag{699}\n\tag{700}\n\tag{701}\n\tag{702}\n\tag{703}\n\tag{704}\n\tag{705}\n\tag{706}\n\tag{707}\n\tag{708}\n\tag{709}\n\tag{710}\n\tag{711}\n\tag{712}\n\tag{713}\n\tag{714}\n\tag{715}\n\tag{716}\n\tag{717}\n\tag{718}\n\tag{719}\n\tag{720}\n\tag{721}\n\tag{722}\n\tag{723}\n\tag{724}\n\tag{725}\n\tag{726}\n\tag{727}\n\tag{728}\n\tag{729}\n\tag{730}\n\tag{731}\n\tag{732}\n\tag{733}\n\tag{734}\n\tag{735}\n\tag{736}\n\tag{737}\n\tag{738}\n\tag{739}\n\tag{740}\n\tag{741}\n\tag{742}\n\tag{743}\n\tag{744}\n\tag{745}\n\tag{746}\n\tag{747}\n\tag{748}\n\tag{749}\n\tag{750}\n\tag{751}\n\tag{752}\n\tag{753}\n\tag{754}\n\tag{755}\n\tag{756}\n\tag{757}\n\tag{758}\n\tag{759}\n\tag{760}\n\tag{761}\n\tag{762}\n\tag{763}\n\tag{764}\n\tag{765}\n\tag{766}\n\tag{767}\n\tag{768}\n\tag{769}\n\tag{770}\n\tag{771}\n\tag{772}\n\tag{773}\n\tag{774}\n\tag{775}\n\tag{776}\n\tag{777}\n\tag{778}\n\tag{779}\n\tag{780}\n\tag{781}\n\tag{782}\n\tag{783}\n\tag{784}\n\tag{785}\n\tag{786}\n\tag{787}\n\tag{788}\n\tag{789}\n\tag{790}\n\tag{791}\n\tag{792}\n\tag{793}\n\tag{794}\n\tag{795}\n\tag{796}\n\tag{797}\n\tag{798}\n\tag{799}\n\tag{800}\n\tag{801}\n\tag{802}\n\tag{803}\n\tag{804}\n\tag{805}\n\tag{806}\n\tag{807}\n\tag{808}\n\tag{809}\n\tag{810}\n\tag{811}\n\tag{812}\n\tag{813}\n\tag{814}\n\tag{815}\n\tag{816}\n\tag{817}\n\tag{818}\n\tag{819}\n\tag{820}\n\tag{821}\n\tag{822}\n\tag{823}\n\tag{824}\n\tag{825}\n\tag{826}\n\tag{827}\n\tag{828}\n\tag{829}\n\tag{830}\n\tag{831}\n\tag{832}\n\tag{833}\n\tag{834}\n\tag{835}\n\tag{836}\n\tag{837}\n\tag{838}\n\tag{839}\n\tag{840}\n\tag{841}\n\tag{842}\n\tag{843}\n\tag{844}\n\tag{845}\n\tag{846}\n\tag{847}\n\tag{848}\n\tag{849}\n\tag{850}\n\tag{851}\n\tag{852}\n\tag{853}\n\tag{854}\n\tag{855}\n\tag{856}\n\tag{857}\n\tag{858}\n\tag{859}\n\tag{860}\n\tag{861}\n\tag{862}\n\tag{863}\n\tag{864}\n\tag{865}\n\tag{866}\n\tag{867}\n\tag{868}\n\tag{869}\n\tag{870}\n\tag{871}\n\tag{872}\n\tag{873}\n\tag{874}\n\tag{875}\n\tag{876}\n\tag{877}\n\tag{878}\n\tag{879}\n\tag{880}\n\tag{881}\n\tag{882}\n\tag{883}\n\tag{884}\n\tag{885}\n\tag{886}\n\tag{887}\n\tag{888}\n\tag{889}\n\tag{890}\n\tag{891}\n\tag{892}\n\tag{893}\n\tag{894}\n\tag{895}\n\tag{896}\n\tag{897}\n\tag{898}\n\tag{899}\n\tag{900}\n\tag{901}\n\tag{902}\n\tag{903}\n\tag{904}\n\tag{905}\n\tag{906}\n\tag{907}\n\tag{908}\n\tag{909}\n\tag{910}\n\tag{911}\n\tag{912}\n\tag{913}\n\tag{914}\n\tag{915}\n\tag{916}\n\tag{917}\n\tag{918}\n\tag{919}\n\tag{920}\n\tag{921}\n\tag{922}\n\tag{923}\n\tag{924}\n\tag{925}\n\tag{926}\n\tag{927}\n\tag{928}\n\tag{929}\n\tag{930}\n\tag{931}\n\tag{932}\n\tag{933}\n\tag{934}\n\tag{935}\n\tag{936}\n\tag{937}\n\tag{938}\n\tag{939}\n\tag{940}\n\tag{941}\n\tag{942}\n\tag{943}\n\tag{944}\n\tag{945}\n\tag{946}\n\tag{947}\n\tag{948}\n\tag{949}\n\tag{950}\n\tag{951}\n\tag{952}\n\tag{953}\n\tag{954}\n\tag{955}\n\tag{956}\n\tag{957}\n\tag{958}\n\tag{959}\n\tag{960}\n\tag{961}\n\tag{962}\n\tag{963}\n\tag{964}\n\tag{965}\n\tag{966}\n\tag{967}\n\tag{968}\n\tag{969}\n\tag{970}\n\tag{971}\n\tag{972}\n\tag{973}\n\tag{974}\n\tag{975}\n\tag{976}\n\tag{977}\n\tag{978}\n\tag{979}\n\tag{980}\n\tag{981}\n\tag{982}\n\tag{983}\n\tag{984}\n\tag{985}\n\tag{986}\n\tag{987}\n\tag{988}\n\tag{989}\n\tag{990}\n\tag{991}\n\tag{992}\n\tag{993}\n\tag{994}\n\tag{995}\n\tag{996}\n\tag{997}\n\tag{998}\n\tag{999}\n\tag{1000}\n\nwhere \\(M\\) is the mass matrix, \\(\bm{x}\\) represents the unknown displacement or Lagrange multiplier vector, and \\(N\\) is a matrix derived from the constraints. The nonlinear conjugate gradient method is used to iteratively update the solution until convergence.\n\n### Constitutive Laws and Kinematics\nThe `NNCGConstraintSolver` does not directly involve specific constitutive laws or kinematic models (like strain measures, stress tensors, or hyperelastic potentials). Instead, it handles constraint satisfaction through a generic LCP formulation. The solver iterates on the constraints to ensure they are satisfied at each time step.\n\n### Role in Global FEM Pipeline\nIn the context of the global FEM pipeline, this component operates during the nonlinear solve phase after spatial and temporal discretizations have been performed. It addresses constraint satisfaction by solving the resulting LCPs using iterative methods such as the non-smooth nonlinear conjugate gradient approach.\n\n### Numerical Methods and Discretization Choices\nThe solver utilizes an iterative NNS-NCG method for finding a solution to the constraints within a predefined tolerance level. The `doSolve` method is invoked with a `GenericConstraintProblem`, which includes initial conditions, constraint matrices, and other problem-specific details.\n\n### Fit into Lagrangian Mechanics Framework\nWithin the broader variational/Lagrangian mechanics framework, this solver ensures that the constraints derived from physical laws (such as contact forces or kinematic relationships) are satisfied. The iterative solution process aligns with the principle of enforcing mechanical invariants and ensuring stability within the simulation.\n",
  "abstract": "The NNCGConstraintSolver solves Linear Complementarity Problems using the Non-smooth Non-linear Conjugate Gradient method for constraint satisfaction in SOFA simulations.",
  "sheet": "# NNCGConstraintSolver\n\n## Overview\nThe `NNCGConstraintSolver` is a component designed to solve constraints formulated as Linear Complementarity Problems (LCPs) within the SOFA framework. It inherits from `BlockGaussSeidelConstraintSolver`, indicating that it performs iterative updates to achieve convergence on solutions satisfying the constraints.\n\n## Mathematical Model\nThe solver addresses LCPs of the form:\n\\[ M \\mathbf{x} + N \\mathbf{u} = \\mathbf{q}, \\]\nwhere \\(M\\) is the mass matrix, \\(\\mathbf{x}\\) represents the unknown displacement or Lagrange multiplier vector, and \\(N\\) is a matrix derived from the constraints. The nonlinear conjugate gradient method is used to iteratively update the solution until convergence.\n\nThe LCP conditions are:\n\\[ \\mathbf{x}^T \\mathbf{u} = 0, \\quad \\mathbf{x} \\geq \\mathbf{0}, \\quad \\mathbf{u} \\geq \\mathbf{0}. \\]\nThese conditions ensure that the constraints are satisfied by enforcing orthogonality and non-negativity of the Lagrange multipliers."
}