LCPSolver (Artisynth API documentation)

All Known Implementing Classes:

DantzigLCPSolver, KellerLCPSolver, MurtyLCPSolver
```
public interface LCPSolver
```
General interface for linear complementarity problem (LCP) solvers. An LCP is defined by the linear system
```
 w = M z + q
 
```
and solving it entails finding w and z subject to the constraints
```
 w >= 0, z >= 0, w z = 0
 
```
Different solvers do this in different ways with varying restrictions on the matrix M. Some solves are also able to solve bounded linear complementarity problems (BLCPs), which take the form
```
 w = M z + q = wpos - wneg,
 0 ≤ hi - z perp wneg ≥ 0,
 0 ≤ z - lo perp wpos ≥ 0
 
```
Full details on the solution of LCPs can be found in The Linear Complementarity Problem, by Cottle, Pang, and Stone, in the review paper ``Algorithms for Linear Complementarity Problems'', by Joaquim Judice (1994), and in Claude Lacoursiere's Ph.D. thesis. Ghosts and Machines: Regularized Variational Methods for Interactive Simulations of Multibodies with Dry Frictional Contact.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class LCPSolver.Status
Solver return status

Nested Classes
Modifier and Type	Interface and Description
`static class`	`LCPSolver.Status` Solver return status

Field Summary

Fields
Modifier and Type	Field and Description
`static double`	`INF`
`static int`	`W_VAR_LOWER` Indicates that a variable is non-basic and at its lower bound.
`static int`	`W_VAR_UPPER` Indicates that a variable is non-basic and at its upper bound.
`static int`	`Z_VAR` Indicates that a variable is basic.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`static void`	`clearState(VectorNi state)` Set all elements in the specified state vector to `W_VAR_LOWER`.
`int`	`getIterationCount()` Returns the number of iterations that were used in the most recent solution operation.
`double`	`getLastSolveTol()` Returns the numeric tolerance used to determine complementarity for the most recent solution.
`int`	`getPivotCount()` Returns the number of pivots that were used in the most recent solution operation.
`boolean`	`isBLCPSupported()` Queries whether this solver supported the solution of bounded linear complementarity problems (BLCPs).
`boolean`	`isWarmStartSupported()` Queries whether this solver supports warm starts.
`int`	`numFailedPivots()` Returns the number of pivots that were attempted and rejected because they would have resulted in a basis matrix that was not SPD.
`LCPSolver.Status`	`solve(VectorNd z, VectorNd w, VectorNi state, MatrixNd M, VectorNd q, VectorNd lo, VectorNd hi, int nub)` If `isBLCPSupported()` returns `true`, solves the BLCP
`LCPSolver.Status`	`solve(VectorNd z, VectorNi state, MatrixNd M, VectorNd q)` Solves the LCP
`static char`	`stateToChar(int sval)` Returns a character representation of a state variable.
`static java.lang.String`	`stateToString(int[] state, int size)` Returns a string representation of a state vector.
`static java.lang.String`	`stateToString(VectorNi state)` Returns a string representation of a state vector.
`static java.lang.String`	`stateToString(VectorNi state, int size)` Returns a string representation of a state vector.
`static VectorNi`	`stringToState(java.lang.String str)` Creates a state vector from a string representation

- Field Detail
  - INF
```
static final double INF
```
    See Also:
    
    Constant Field Values
  - W_VAR_LOWER
```
static final int W_VAR_LOWER
```
    Indicates that a variable is non-basic and at its lower bound.
    
    See Also:
    
    Constant Field Values
  - W_VAR_UPPER
```
static final int W_VAR_UPPER
```
    Indicates that a variable is non-basic and at its upper bound.
    
    See Also:
    
    Constant Field Values
  - Z_VAR
```
static final int Z_VAR
```
    Indicates that a variable is basic.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - stateToChar
```
static char stateToChar(int sval)
```
    Returns a character representation of a state variable.
    
    Parameters:
    
    sval - state value to convert
    
    Returns:
    
    character representation
  - stateToString
```
static java.lang.String stateToString(VectorNi state)
```
    Returns a string representation of a state vector.
    
    Parameters:
    
    state - state vector to convert to string
    
    Returns:
    
    string representation of the state
  - stateToString
```
static java.lang.String stateToString(VectorNi state,
                                      int size)
```
    Returns a string representation of a state vector.
    
    Parameters:
    
    state - state vector to convert to string
    
    Returns:
    
    string representation of the state
  - stateToString
```
static java.lang.String stateToString(int[] state,
                                      int size)
```
    Returns a string representation of a state vector.
    
    Parameters:
    
    state - state vector to convert to string
    
    size - number of entries of state to convert
    
    Returns:
    
    string representation of the state
  - stringToState
```
static VectorNi stringToState(java.lang.String str)
```
    Creates a state vector from a string representation
    
    Parameters:
    
    str - string representation of the state
    
    Returns:
    
    state vector
  - clearState
```
static void clearState(VectorNi state)
```
    Set all elements in the specified state vector to W_VAR_LOWER.
    
    Parameters:
    
    state - state vector to clear
  - solve
```
LCPSolver.Status solve(VectorNd z,
                       VectorNi state,
                       MatrixNd M,
                       VectorNd q)
```
    Solves the LCP
```
 w = M z + q
 
```
    where M is a matrix whose characteristics should match the capabilities of the solver.
    Parameters:
    
    z - returns the solution for z
    
    state - optional argument, which if non-null, returns the state vector resulting from the LCP solve. For solvers capable of warm starts (i.e., if isWarmStartSupported() returns true), the value of this vector on input will also specify the initial starting state.
    
    M - system matrix
    
    q - system vector
    
    Returns:
    
    Status of the solution.
  - solve
```
LCPSolver.Status solve(VectorNd z,
                       VectorNd w,
                       VectorNi state,
                       MatrixNd M,
                       VectorNd q,
                       VectorNd lo,
                       VectorNd hi,
                       int nub)
```
    If isBLCPSupported() returns true, solves the BLCP
```
 w = M z + q = wpos - wneg,
 0 ≤ hi - z perp wneg ≥ 0,
 0 ≤ z - lo perp wpos ≥ 0,
 
```
    where M is a matrix whose characteristics should match the capabilities of the solver. If BLCPs are not supported, then this method returns LCPSolver.Status.UNIMPLEMENTED.
    Parameters:
    
    z - returns the solution for z
    
    w - returns the solution for w
    
    state - optional argument, which if non-null, returns the state vector resulting from the LCP solve. For solvers capable of warm starts (i.e., if isWarmStartSupported() returns true), the value of this vector on input will also specify the initial starting state.
    
    M - system matrix
    
    q - system vector
    
    lo - lower bounds for the z variables
    
    hi - upper bounds for the z variables
    
    nub - number of unbounded variables (corresponding to bilateral constraints). If nub > 0, then the first nub entries of lo and hi must be negative and positive infinity, respectively.
    
    Returns:
    
    Status of the solution.
  - isBLCPSupported
```
boolean isBLCPSupported()
```
    Queries whether this solver supported the solution of bounded linear complementarity problems (BLCPs).
    
    Returns:
    
    true if BLCPs are supported.
  - isWarmStartSupported
```
boolean isWarmStartSupported()
```
    Queries whether this solver supports warm starts.
    
    Returns:
    
    true if warm starts are supported.
  - getIterationCount
```
int getIterationCount()
```
    Returns the number of iterations that were used in the most recent solution operation.
    
    Returns:
    
    iteration count for last solution
  - getPivotCount
```
int getPivotCount()
```
    Returns the number of pivots that were used in the most recent solution operation. For solvers that support block pivoting and have block pivoting enabled, this will usually exceed the number of iterations. Otherwise, this number should be roughly equal to the number of iterations.
    
    Returns:
    
    pivot count for last solution
  - numFailedPivots
```
int numFailedPivots()
```
    Returns the number of pivots that were attempted and rejected because they would have resulted in a basis matrix that was not SPD.
  - getLastSolveTol
```
double getLastSolveTol()
```
    Returns the numeric tolerance used to determine complementarity for the most recent solution. These tolerances may be updated dynamically during the solution.

Interface LCPSolver

Nested Class Summary

Field Summary

Method Summary

Field Detail

INF

W_VAR_LOWER

W_VAR_UPPER

Z_VAR

Method Detail

stateToChar

stateToString

stateToString

stateToString

stringToState

clearState

solve

solve

isBLCPSupported

isWarmStartSupported

getIterationCount

getPivotCount

numFailedPivots

getLastSolveTol