MechSystemSolver (Artisynth API documentation)

java.lang.Object
- artisynth.core.mechmodels.MechSystemSolver

public class MechSystemSolver
extends java.lang.Object

Implements implicit integration for MechSystem

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`MechSystemSolver.Integrator`
`static class`	`MechSystemSolver.PosStabilization` Indicates the method by which positions should be stabilized.

Field Summary

Fields
Modifier and Type	Field and Description
`boolean`	`alwaysProjectFriction`
`static boolean`	`DEFAULT_HYBRID_SOLVES_ENABLED`
`static boolean`	`myAlwaysAnalyze`
`static boolean`	`myDefaultHybridSolveP`
`boolean`	`myMurtyVelSolveRebuild`
`static double`	`myT1`
`boolean`	`myUseImplicitFriction`
`static int`	`NO_SYS_UPDATE` Flag for KKTSolverFactorAndSolve methods: do not update the system with the computed velocities and constraint forces.
`boolean`	`profileConstrainedBE`
`static boolean`	`profileConstraintSolves`
`boolean`	`profileImplicitFriction`
`boolean`	`profileKKTSolveTime`
`boolean`	`profileWholeSolve`
`static int`	`TRAPEZOIDAL` Flag for KKTSolverFactorAndSolve methods: indicates trapezoidal integration
`static boolean`	`useFictitousJacobianForces`

Constructor Summary

Constructors
Constructor and Description
`MechSystemSolver(MechSystem system)` Create a new MechSystem solver for a specified MechSystem.
`MechSystemSolver(MechSystem system, MechSystemSolver solver)` Create a new MechSystem solver for a specified MechSystem, with settings imported from an existing MechSystemSolver.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addActiveMassMatrix(MechSystem sys, SparseBlockMatrix S)`
`void`	`addMassForces(VectorNd f, double t)`
`void`	`addSubVector(VectorNd vr, VectorNd v1, int off, int size)` Computes
`void`	`backwardEuler(double t0, double t1, StepAdjustment stepAdjust)`
`static double`	`brentRootFinder(double a, double fa, double b, double fb, double eps, double feps, Function1x1 func)` Implementation of Brent's root-finding method, guarantees that the final call to func is at the root
`void`	`computeParametricForces(double h)`
`void`	`constrainedBackwardEuler(double t0, double t1, StepAdjustment stepAdjust)`
`void`	`constrainedForwardEuler(double t0, double t1, StepAdjustment stepAdjust)`
`SparseBlockMatrix`	`createActiveBilateralMatrix(double t)`
`SparseBlockMatrix`	`createActiveDampingMatrix(double h)`
`SparseBlockMatrix`	`createActiveMassMatrix(double t)` Creates and returns a sparse block matrix consisting of the current active portion of the mass matrix.
`SparseBlockMatrix`	`createActiveStiffnessMatrix(double h)`
`void`	`dispose()`
`void`	`finalize()`
`void`	`fullBackwardEuler(double t0, double t1, StepAdjustment stepAdjust)`
`static boolean`	`getAlwaysAnalyze()`
`int`	`getFrictionIterations()`
`boolean`	`getHybridSolve()`
`static boolean`	`getHybridSolvesEnabled()` Queries whether hybrid sparse matrix solves are enabled by default.
`MechSystemSolver.Integrator`	`getIntegrator()`
`VectorNd`	`getLambda()`
`SparseSolverId`	`getMatrixSolver()`
`int`	`getMaxIterations()`
`SparseBlockMatrix`	`getSolveMatrix()` Returns the solve matrix.
`MechSystemSolver.PosStabilization`	`getStabilization()`
`int`	`getStaticIncrements()` Returns the number of load increments being used with the `MechSystemSolver.Integrator.StaticIncremental` integrator.
`double`	`getStaticTikhonovFactor()`
`double`	`getTolerance()`
`IterativeSolver.ToleranceType`	`getToleranceType()`
`boolean`	`getUpdateForcesAtStepEnd()`
`boolean`	`getUseImplicitFriction()`
`void`	`initialize()`
`void`	`KKTFactorAndSolve(VectorNd vel, VectorNd fpar, VectorNd bf, VectorNd btmp, VectorNd vel0, double h, double a0, double a1, double a2, double a3, int flags)` Solves a KKT system in which the Jacobian augmented M matrix and and force vectors are given by
`void`	`KKTFactorAndSolve(VectorNd vel, VectorNd fpar, VectorNd bf, VectorNd btmp, VectorNd vel0, double h, int flags)` Solves a KKT system in which the Jacobian augmented M matrix and and force vectors are given by
`void`	`KKTSolve(VectorNd vel, VectorNd lam, VectorNd the, VectorNd bf)` Solves the KKT system given a new right hand side `bf`.
`void`	`KKTStaticFactorAndSolve(VectorNd u, VectorNd bf, double beta, VectorNd btmp)` Solves a static KKT system of the form
`static double`	`modifiedGoldenSection(double a, double fa, double b, double fb, double eps, double feps, Function1x1 func)` Implementation of a modified Golden section search for minimizing \|f(s)\|, guaranteeing that the final call to func is at the returned minimum
`void`	`mulActiveInertias(VectorNd b, VectorNd v)`
`void`	`nonDynamicSolve(double t0, double t1, StepAdjustment stepAdjust)`
`void`	`projectPosConstraints(double t)`
`void`	`projectRigidBodyPosConstraints(double t)`
`static void`	`setAlwaysAnalyze(boolean enable)`
`void`	`setCrsFileName(java.lang.String name)`
`void`	`setFrictionIterations(int num)`
`void`	`setHybridSolve(boolean enable)`
`static void`	`setHybridSolvesEnabled(boolean enable)` Set hybrid sparse matrix solves to be enabled or disabled by default.
`void`	`setIntegrator(MechSystemSolver.Integrator integrator)`
`void`	`setIterativeSolver(IterativeSolver solver)`
`static void`	`setLogWriter(java.io.PrintWriter writer)`
`void`	`setMatrixSolver(SparseSolverId solver)`
`void`	`setMaxIterations(int max)`
`void`	`setParametricTargets(double s, double h)`
`void`	`setStabilization(MechSystemSolver.PosStabilization stabilization)`
`void`	`setStaticIncrements(int iters)` Sets the number of load increments to use with the `MechSystemSolver.Integrator.StaticIncremental` integrator.
`void`	`setStaticTikhonovFactor(double eps)` Applies Tiknonov regularization for static solves, minimizing
`void`	`setSubVector(VectorNd vr, VectorNd v1, int off, int size)` Sets
`void`	`setTolerance(double tol)`
`void`	`setToleranceType(IterativeSolver.ToleranceType type)`
`void`	`setUpdateForcesAtStepEnd(boolean enable)`
`void`	`setUseImplicitFriction(boolean enable)`
`void`	`solve(double t0, double t1, StepAdjustment stepAdjust)`
`void`	`staticIncremental(double t0, double t1, int nincrements, StepAdjustment stepAdjust)`
`void`	`staticIncrementalStep(double t0, double t1, double alpha, StepAdjustment stepAdjust)` Scales forces and constraints down by alpha, and solves the adjusted problem
`void`	`staticLineSearch(double t0, double t1, StepAdjustment stepAdjust)`
`void`	`trapezoidal(double t0, double t1, StepAdjustment stepAdjust)`
`void`	`updateConstraintMatrices(double h, boolean includeFriction)`
`void`	`updateMassMatrix(double t)`
`void`	`updateStateSizes()`
`boolean`	`usingImplicitFriction()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_SYS_UPDATE
```
public static int NO_SYS_UPDATE
```
Flag for KKTSolverFactorAndSolve methods: do not update the system with the computed velocities and constraint forces.

TRAPEZOIDAL
```
public static int TRAPEZOIDAL
```
Flag for KKTSolverFactorAndSolve methods: indicates trapezoidal integration

profileKKTSolveTime
```
public boolean profileKKTSolveTime
```

profileWholeSolve
```
public boolean profileWholeSolve
```

profileConstrainedBE
```
public boolean profileConstrainedBE
```

profileImplicitFriction
```
public boolean profileImplicitFriction
```

alwaysProjectFriction
```
public boolean alwaysProjectFriction
```

myMurtyVelSolveRebuild
```
public boolean myMurtyVelSolveRebuild
```

myUseImplicitFriction
```
public boolean myUseImplicitFriction
```

useFictitousJacobianForces

public static boolean useFictitousJacobianForces

myAlwaysAnalyze
```
public static boolean myAlwaysAnalyze
```

DEFAULT_HYBRID_SOLVES_ENABLED

public static boolean DEFAULT_HYBRID_SOLVES_ENABLED

myDefaultHybridSolveP

public static boolean myDefaultHybridSolveP

profileConstraintSolves

public static boolean profileConstraintSolves

myT1
```
public static double myT1
```

Constructor Detail
- MechSystemSolver
```
public MechSystemSolver(MechSystem system)
```
  Create a new MechSystem solver for a specified MechSystem.
- MechSystemSolver
```
public MechSystemSolver(MechSystem system,
                        MechSystemSolver solver)
```
  Create a new MechSystem solver for a specified MechSystem, with settings imported from an existing MechSystemSolver.

Method Detail

setUpdateForcesAtStepEnd

public void setUpdateForcesAtStepEnd(boolean enable)

getUpdateForcesAtStepEnd

public boolean getUpdateForcesAtStepEnd()

getAlwaysAnalyze

public static boolean getAlwaysAnalyze()

setAlwaysAnalyze

public static void setAlwaysAnalyze(boolean enable)

getHybridSolvesEnabled
```
public static boolean getHybridSolvesEnabled()
```
Queries whether hybrid sparse matrix solves are enabled by default.

Returns:

true if hybrid solves are enabled

setHybridSolvesEnabled
```
public static void setHybridSolvesEnabled(boolean enable)
```
Set hybrid sparse matrix solves to be enabled or disabled by default.

Parameters:

enable - if true, enables hybrid solves

getHybridSolve
```
public boolean getHybridSolve()
```

setHybridSolve

public void setHybridSolve(boolean enable)

getUseImplicitFriction

public boolean getUseImplicitFriction()

setUseImplicitFriction

public void setUseImplicitFriction(boolean enable)

usingImplicitFriction

public boolean usingImplicitFriction()

getFrictionIterations
```
public int getFrictionIterations()
```

setFrictionIterations

public void setFrictionIterations(int num)

setParametricTargets

public void setParametricTargets(double s,
                                 double h)

computeParametricForces

public void computeParametricForces(double h)

updateMassMatrix

public void updateMassMatrix(double t)

createActiveMassMatrix
```
public SparseBlockMatrix createActiveMassMatrix(double t)
```
Creates and returns a sparse block matrix consisting of the current active portion of the mass matrix. Used mainly for exporting information for analysis.

Parameters:

t - current time

Returns:

current active mass matrix

updateStateSizes
```
public void updateStateSizes()
```

setIntegrator

public void setIntegrator(MechSystemSolver.Integrator integrator)

setIterativeSolver

public void setIterativeSolver(IterativeSolver solver)

getIntegrator

public MechSystemSolver.Integrator getIntegrator()

getTolerance
```
public double getTolerance()
```

setTolerance
```
public void setTolerance(double tol)
```

getToleranceType

public IterativeSolver.ToleranceType getToleranceType()

setToleranceType

public void setToleranceType(IterativeSolver.ToleranceType type)

setMaxIterations

public void setMaxIterations(int max)

getMaxIterations
```
public int getMaxIterations()
```

setMatrixSolver

public void setMatrixSolver(SparseSolverId solver)

setStabilization

public void setStabilization(MechSystemSolver.PosStabilization stabilization)

getStabilization

public MechSystemSolver.PosStabilization getStabilization()

getMatrixSolver

public SparseSolverId getMatrixSolver()

nonDynamicSolve

public void nonDynamicSolve(double t0,
                            double t1,
                            StepAdjustment stepAdjust)

solve

public void solve(double t0,
                  double t1,
                  StepAdjustment stepAdjust)

getLambda
```
public VectorNd getLambda()
```

mulActiveInertias

public void mulActiveInertias(VectorNd b,
                              VectorNd v)

addActiveMassMatrix

public void addActiveMassMatrix(MechSystem sys,
                                SparseBlockMatrix S)

addMassForces

public void addMassForces(VectorNd f,
                          double t)

addSubVector

public void addSubVector(VectorNd vr,
                         VectorNd v1,
                         int off,
                         int size)

Computes

 vr += v1(off:off+size-1)

setSubVector

public void setSubVector(VectorNd vr,
                         VectorNd v1,
                         int off,
                         int size)

Sets

 vr = v1(off:off+size-1)

backwardEuler

public void backwardEuler(double t0,
                          double t1,
                          StepAdjustment stepAdjust)

updateConstraintMatrices

public void updateConstraintMatrices(double h,
                                     boolean includeFriction)

KKTFactorAndSolve
```
public void KKTFactorAndSolve(VectorNd vel,
                              VectorNd fpar,
                              VectorNd bf,
                              VectorNd btmp,
                              VectorNd vel0,
                              double h,
                              int flags)
```
Solves a KKT system in which the Jacobian augmented M matrix and and force vectors are given by
```
 M' = M - h df/dv - h^2 df/dx 

 bf' = bf + (-h df/dv) vel0
 
```
When used to solve for velocities in an implicit integrator, then on input, bf is assumed to be given by
```
 bf = M vel0 + h f
 
```
where h is the time step and f is the generalized forces, while on output bf is modified to include the Jacobian terms described above. XXX question about which time do we want? t0 or t1? Right now it is set to t1; setting it to t0 seems to cause a small difference in the inverse tongue model.
Parameters:

vel - returns the computed velocity

fpar - if useFictitousJacobianForces is true, returns fictitious Jacobian forces for parametric components

bf - right side offset

btmp - temporary vector

vel0 - right side velocity

h - interval time step

flags - NO_SYS_UPDATE

KKTFactorAndSolve
```
public void KKTFactorAndSolve(VectorNd vel,
                              VectorNd fpar,
                              VectorNd bf,
                              VectorNd btmp,
                              VectorNd vel0,
                              double h,
                              double a0,
                              double a1,
                              double a2,
                              double a3,
                              int flags)
```
Solves a KKT system in which the Jacobian augmented M matrix and and force vectors are given by
```
 M' = M + a0 df/dv + a1 df/dx 

 bf' = bf + (a2 df/dv + a3 df/dx) vel0
 
```
It is assumed that a0 and a1 are both non-zero. It is also assumed that the a0 = -alpha h, where h is the step size and alpha indicates the propertion of implicitness for the solve; i.e., for regular backward euler, alpha=1, while for trapezoidal solves, alpha = 0.5; When used to solve for velocities in an implicit integrator, then on input, bf is assumed to be given by
```
 bf = M vel0 + h f
 
```
where h is the time step and f is the generalized forces, while on output bf is modified to include the Jacobian terms described above.
Parameters:

vel - returns the computed velocity

fpar - if useFictitousJacobianForces is true, returns fictitious Jacobian forces for parametric components

bf - right side offset

btmp - temporary vector

vel0 - right side velocity

h - interval time step - used to scale constraint offsets and impulses

a0 - left side df/dv coefficient

a1 - left side df/dx coefficient

a2 - right side df/dv coefficient

a3 - right side df/dx coefficient

flags - NO_SYS_UPDATE, TRAPEZOIDAL

KKTStaticFactorAndSolve

public void KKTStaticFactorAndSolve(VectorNd u,
                                    VectorNd bf,
                                    double beta,
                                    VectorNd btmp)

Solves a static KKT system of the form


 -df/dx*Delta(x) -G^T*lambda - N^T*theta = f
 G*Delta(x) + g = 0, N*Delta(x) + n >= 0

Parameters:: u - returned displacement Delta(x); bf - right-hand side net force; beta - scale factor for any additional forces such as fictitious forces; btmp - temporary vector

setCrsFileName

public void setCrsFileName(java.lang.String name)

setLogWriter

public static void setLogWriter(java.io.PrintWriter writer)

KKTSolve
```
public void KKTSolve(VectorNd vel,
                     VectorNd lam,
                     VectorNd the,
                     VectorNd bf)
```
Solves the KKT system given a new right hand side bf. It is assumed that KKTFactorAndSolve() has already been called once, and that the initial velocity vel0 is unchanged from that call. The updated value for bf should be based on the value returned by KKTFactorAndSolve(), as described below.
Recall that on input to KKTFactorAndSolve(), bf is assumed to be of the form
```
 bf = M vel0 + h f1
 
```
where M is the mass matrix, h is the time step, and f1 are the force values. On return, bf is modified by adding values that depend on vel0 and the position and velocity Jacobians of the system. These additional values are needed on subsequent calls to KKTSolve(). Therefore, when using KKTSolve() to compute velocities for different force values f2, one should use the bf returned by KKTFactorAndSolve() and simply adjust it to reflect f2 instead of f1:
```
 bf1 = M vel0 + h f1
 KKTFactorAndSolve (vel1, bf1, btmp, vel0, ...)
 bf2 = bf1 - h f1 + h f2
 KKTSolve (vel2, myLam, the, bf2)
 
```

projectPosConstraints

public void projectPosConstraints(double t)

projectRigidBodyPosConstraints

public void projectRigidBodyPosConstraints(double t)

constrainedForwardEuler

public void constrainedForwardEuler(double t0,
                                    double t1,
                                    StepAdjustment stepAdjust)

constrainedBackwardEuler

public void constrainedBackwardEuler(double t0,
                                     double t1,
                                     StepAdjustment stepAdjust)

fullBackwardEuler

public void fullBackwardEuler(double t0,
                              double t1,
                              StepAdjustment stepAdjust)

trapezoidal

public void trapezoidal(double t0,
                        double t1,
                        StepAdjustment stepAdjust)

setStaticTikhonovFactor
```
public void setStaticTikhonovFactor(double eps)
```
Applies Tiknonov regularization for static solves, minimizing
```
 L(dx) = W(x+dx) + eps*|dx|^2
 
```
where W is the energy potential function (including constraints) for the static system. If eps is less than zero, then we try to estimate the optimal parameter based on the Frobenius norm of the stiffness matrix.
Parameters:

eps - tikhonov regularization factor

getStaticTikhonovFactor

public double getStaticTikhonovFactor()

setStaticIncrements
```
public void setStaticIncrements(int iters)
```
Sets the number of load increments to use with the MechSystemSolver.Integrator.StaticIncremental integrator.

Parameters:

iters - number of load increments

getStaticIncrements
```
public int getStaticIncrements()
```
Returns the number of load increments being used with the MechSystemSolver.Integrator.StaticIncremental integrator.

Returns:

number of load increments for MechSystemSolver.Integrator.StaticIncremental

staticIncrementalStep

public void staticIncrementalStep(double t0,
                                  double t1,
                                  double alpha,
                                  StepAdjustment stepAdjust)

Scales forces and constraints down by alpha, and solves the adjusted problem

Parameters:: t0 - start time for solve; t1 - stop time for solve; alpha - step factor; stepAdjust - step adjustment description

staticIncremental

public void staticIncremental(double t0,
                              double t1,
                              int nincrements,
                              StepAdjustment stepAdjust)

brentRootFinder

public static double brentRootFinder(double a,
                                     double fa,
                                     double b,
                                     double fb,
                                     double eps,
                                     double feps,
                                     Function1x1 func)

Implementation of Brent's root-finding method, guarantees that the final call to func is at the root

Parameters:: a - left-side of interval; fa - function evaluated at a; b - right-side of interval; fb - function evaluated at b; eps - tolerance for interval [a,b]; feps - tolerance for function value |f| < feps considered root; func - function to evaluate
Returns:: root

modifiedGoldenSection

public static double modifiedGoldenSection(double a,
                                           double fa,
                                           double b,
                                           double fb,
                                           double eps,
                                           double feps,
                                           Function1x1 func)

Implementation of a modified Golden section search for minimizing |f(s)|, guaranteeing that the final call to func is at the returned minimum

Parameters:: a - left-side of search interval; fa - f(a); b - right-side of search interval; fb - f(b); eps - tolerance for interval [a,b]; feps - tolerance for function evaluation, |f(s)| < feps considered a root; func - function to evaluate
Returns:: function minimizer

staticLineSearch

public void staticLineSearch(double t0,
                             double t1,
                             StepAdjustment stepAdjust)

createActiveStiffnessMatrix

public SparseBlockMatrix createActiveStiffnessMatrix(double h)

createActiveDampingMatrix

public SparseBlockMatrix createActiveDampingMatrix(double h)

createActiveBilateralMatrix

public SparseBlockMatrix createActiveBilateralMatrix(double t)

getSolveMatrix
```
public SparseBlockMatrix getSolveMatrix()
```
Returns the solve matrix. For debugging and testing only.

dispose
```
public void dispose()
```

finalize
```
public void finalize()
```
Overrides:

finalize in class java.lang.Object

initialize
```
public void initialize()
```

Class MechSystemSolver

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NO_SYS_UPDATE

TRAPEZOIDAL

profileKKTSolveTime

profileWholeSolve

profileConstrainedBE

profileImplicitFriction

alwaysProjectFriction

myMurtyVelSolveRebuild

myUseImplicitFriction