Implicit flex elasticity in the CG constraint solver via an effective metric

This CL replaces the post-hoc implicit flex correction (`flexInterp_cgsolve`) with a **linearly-implicit effective metric** `M̃ = M + (h² + h·damping)·K` carried by the CG constraint solver itself. Contact/friction forces and implicit flex elasticity are now computed against one consistent metric, instead of the solver seeing `M` and a post-solve correction changing `qacc` behind its back.

Gate (unchanged semantics): `solver="CG"` + implicit/implicitfast integrator + pyramidal cones + flex stiffness present. Newton and PGS are untouched. `solver="CG"` remains the user-facing contract — the factorization is an implementation detail of the preconditioner.

### What's in the metric

- **mjData `efm_*`** (arena, efc-like lifetime/skip semantics; built in `mj_fwdPosition`, value-refreshed in `mj_fwdVelocity`): the per-step stiffness CSR `efm_B_*`, its reverse-Cholesky factor `efm_dofid` + `efm_L_*` (nested-dissection ordered, separators-first for the reverse factorization), and the smooth-force shift `efm_c = h·K·qvel`.
- **`mjd_flexStiff_assemble`** now assembles stretch (Gauss–Newton), standard dim-2 bending, and — via the cached corotated stiffness `d->flexelem_krot` — interp stiffness (all node bodies on simple sliders: point Jacobian is I₃, `flex_centered` not required; fixed nodes drop like pins) into one dof-level CSR. `mjd_effMulAdd`/`mjd_effSolve` apply the metric, with matrix-free operator fallbacks where assembly does not apply.
- **mjModel `efm0_*`** (`nefm0dof`/`nefm0L`): the constant part of the metric factor — currently the dim-2 bending factor, computed once in `mj_setConst` — so bending-only models pay zero per-step factorization cost. Naming mirrors mjData's `efm_*` with the standard `0`-suffix (reference/constant) idiom, and is deliberately not bending-specific: future constant contributors extend it without renames.
- The solver consumes the metric through pre-shifted `qfrc_smooth` and the metric products `Ma`/`Mv`/`Mgrad`; `qacc_smooth` becomes the unconstrained minimizer of the implicit dynamics, which makes the no-constraint shortcut and the warmstart choice consistent by construction.
- **`mj_inverse` adds `B·qacc − c`**, making inverse dynamics discrete-consistent with the gated forward dynamics — exact, since the gated path has no qDeriv term (new test `ForwardTest.GatedFlexInverseConsistency`).

### Performance

All numbers: ms/step over the same 2000-step window, models as shipped on each side (old code with the old model settings vs this CL with the new ones).

The new solver path activates on exactly two shipped models — the ponchos, the only flex models that need an implicit integrator (poncho on Euler degenerates to >200 ms/step). For them, this CL trades speed for consistency: the implicit bending solve now runs inside every solver iteration, where the contact solve can see the stiffness, instead of once after the solve. Solver iterations drop because the curvature is visible, but each iteration pays for the implicit solve:

| model | before | after | solver iters/step |
|---|---|---|---|
| poncho | 2.47 | 3.30 (1.33×) | 16.8 → 11.8 |
| poncho_edgeequality | 1.96 | 2.72 (1.39×) | 13.2 → 10.0 |

What that price buys: contact forces consistent with the implicit elasticity (previously the post-hoc correction changed `qacc` after the constraint solve), discrete-consistent inverse dynamics, and the removal of the post-hoc special case from the integration path. Raising poncho's timestep from 2 to 5 ms leaves its per-step cost nearly flat, so the consistency price can be recovered by taking fewer steps where accuracy allows.

Every other flex model was measured stable on Euler at its shipped timestep and switches to it (these models predate the post-hoc integrator; implicit was never load-bearing for them). They end up equal or faster than before: bunny_multicell 0.47 → 0.40, trampoline 0.28 → 0.25, plate 1.02 → 0.99, pancake 0.34 → 0.33.

Finally, the per-step factorization makes configurations practical that the old code could only integrate explicitly: implicit stretch elasticity (`elastic2d="stretch"`/`"both"`, dim-3 solids) and factorized interp stiffness. No before/after exists for these — stock has no implicit treatment of stretch at all.

### Behavior changes

- With the post-hoc correction deleted, interp/bending models running `solver="Newton"` (or elliptic cones, or islands) now integrate flex elasticity **explicitly** (previously: post-hoc implicit). Affects e.g. `gripper_trilinear` (stable, and faster, but different semantics). Follow-up options: Newton-side metric support, or a documented fallback.
- With the gate on, `mj_forward` outputs are timestep-dependent for gated models (they answer the linearly-implicit discrete problem); `qacc_smooth` and `mj_inverse` change accordingly. Non-gated models are bit-identical (full suite green throughout).

### Validation

- 1737/1737 tests, including new: `FlexStretchDerivatives` (FD-validated GN operator), `FlexStiffAssemble`/`FlexStiffAssembleInterp` (CSR ≡ operators), `GatedFlexInverseConsistency` (fails pre-change), equivalence tests vs the old post-hoc treatment (bending matches to 2e-11).
- Fingerprint discipline throughout: bending-only models bit-exact across every refactor; permutation/kernel changes verified iteration-identical.

### Known follow-ups (not in this CL)

3×3-block sparse Cholesky kernel (the numeric factorization is index-bound; projected ~3× on the factor); mjModel persistence of the factor's symbolic pattern (rest-pose ND makes sizes compile-time); the general effective-metric mode (all solvers, all PSD-safe force classes, behind an enable flag).

PiperOrigin-RevId: 948561856
Change-Id: I8b8e32ebd0428042af71647d0470d10773bf6daf
This commit is contained in:
Alessio Quaglino
2026-07-15 14:56:57 -07:00
committed by Copybara-Service
parent f0fa3d8260
commit ea230a950c
39 changed files with 2501 additions and 203 deletions
File diff suppressed because it is too large Load Diff
+33
View File
@@ -65,6 +65,39 @@ MJAPI void mjd_flexInterp_cacheKrot(const mjModel* m, mjData* d, mjtNum* K_rot_o
MJAPI void mjd_flexBend_mul(const mjModel* m, mjData* d, mjtNum* res, const mjtNum* vec,
mjtNum s1, mjtNum s2);
// compute res += scale * K_stretch * vec for standard (non-interp) flex stretch,
// K_stretch the Gauss-Newton Hessian of the passive stretch force at the current state
// scale = s1 + s2 * flex_damping[f] per flex
MJAPI void mjd_flexStretch_mul(const mjModel* m, mjData* d, mjtNum* res, const mjtNum* vec,
mjtNum s1, mjtNum s2);
// assemble the standard-flex implicit stiffness (s1 + s2*damping)*(K_bend + K_stretch) into
// dof-level CSR; phase 1 (colind==NULL) fills rownnz/rowadr and returns total nnz, phase 2
// fills colind/val. Interp flexes are assembled iff Krot (mjd_flexInterp_cacheKrot cache) is
// non-NULL and the centered fast path applies (check mjd_flexInterpAssemblable first).
MJAPI int mjd_flexStiff_assemble(const mjModel* m, mjData* d, int* rownnz, int* rowadr,
int* colind, mjtNum* val, mjtNum s1, mjtNum s2,
int flg_bend, int flg_stretch, const mjtNum* Krot);
// can all interp flexes be assembled to dof-level CSR? (centered fast path everywhere)
MJAPI mjtBool mjd_flexInterpAssemblable(const mjModel* m);
// does any flex contribute assemblable implicit stiffness? (existence check)
MJAPI mjtBool mjd_flexStiff_any(const mjModel* m, int flg_interp);
// implicit effective metric Mtilde = M + (h^2+h*d)*K: per-step arena object (see mjdata.h efm_*)
// build (or deactivate, active==0); the gate decision belongs to the caller
MJAPI void mjd_effBuild(const mjModel* m, mjData* d, int active, int flg_factor);
// refresh the metric's smooth-force shift c = h*K*qvel (values only, velocity stage)
MJAPI void mjd_effShift(const mjModel* m, mjData* d);
// res += B*vec (the stiffness part of the metric; caller supplies the M part)
MJAPI void mjd_effMulAdd(const mjModel* m, mjData* d, mjtNum* res, const mjtNum* vec);
// x = (M + B)^-1 b to 1e-10 relative; x = M^-1 b when the metric is inactive
MJAPI void mjd_effSolve(const mjModel* m, mjData* d, mjtNum* x, const mjtNum* b);
#ifdef __cplusplus
}
+65 -121
View File
@@ -168,6 +168,11 @@ void mj_fwdPosition(const mjModel* m, mjData* d) {
mj_transmission(m, d);
TM_ADD(mjTIMER_POS_KINEMATICS);
// implicit effective metric Mtilde = M + K: build (or deactivate) for this step. Arena
// lifetime and skip semantics mirror the constraint data: built once per position stage,
// value-refreshed in the velocity stage, consumed downstream.
mjd_effBuild(m, d, mj_flexCG(m), /*flg_factor=*/1);
TM_END1(mjTIMER_POSITION);
}
@@ -214,6 +219,8 @@ void mj_fwdVelocity(const mjModel* m, mjData* d) {
// add bias force due to tendon armature
mj_tendonBias(m, d, d->qfrc_bias);
mjd_effShift(m, d);
TM_END(mjTIMER_VELOCITY);
}
@@ -786,6 +793,18 @@ void mj_fwdAcceleration(const mjModel* m, mjData* d) {
// qfrc_smooth += project(xfrc_applied)
mj_xfrcAccumulate(m, d, d->qfrc_smooth);
// implicit effective metric (built in mj_fwdPosition): the smooth acceleration is that of
// the linearly-implicit dynamics, (M + K)*qacc_smooth = qfrc_smooth + c, so the constraint
// solver, the no-constraint shortcut and the warmstart all see one consistent metric.
if (d->efm_active) {
mj_markStack(d);
mjtNum* qfrc_eff = mjSTACKALLOC(d, nv, mjtNum);
mju_add(qfrc_eff, d->qfrc_smooth, d->efm_c, nv);
mjd_effSolve(m, d, d->qacc_smooth, qfrc_eff);
mj_freeStack(d);
return;
}
// copy for in-place solve: qacc_smooth = qfrc_smooth
if (!sleep_filter) {
mju_copy(d->qacc_smooth, d->qfrc_smooth, nv);
@@ -900,6 +919,7 @@ void mj_fwdConstraint(const mjModel* m, mjData* d) {
mju_zero(d->qfrc_constraint, nv);
// no constraints: copy unconstrained acc, clear forces, return
// (with the effective metric active, qacc_smooth is already the implicit answer)
if (!nefc) {
mju_copy(d->qacc, d->qacc_smooth, nv);
mju_zeroInt(d->solver_niter, mjNISLAND);
@@ -921,7 +941,16 @@ void mj_fwdConstraint(const mjModel* m, mjData* d) {
mju_zeroInt(d->solver_niter, mjNISLAND);
// check if islands are supported
int islands_supported = !mjDISABLED(mjDSBL_ISLAND) && nisland > 0;
// TODO: support islands with the implicit effective metric and remove the mj_flexCG
// condition. It is here because the metric machinery is monolithic: the efm_c shift and
// the Ma/Mv/Mgrad operators (mjd_effMulAdd, mjd_effSolve) act on global dof vectors with
// no island-local form. Discovery is already handled: findEdges unions the trees of every
// stiffness-active flex, so a flex always lands in one island together with everything it
// touches. Removal therefore needs only the solver side: apply the efm_c shift to that
// island's dofs, gather/scatter its island-local vectors around the covered-compact
// factor solves (the factors themselves need no change), and enable the metric path
// (flg_flex) for the flex-containing island alone.
int islands_supported = !mjDISABLED(mjDSBL_ISLAND) && nisland > 0 && !mj_flexCG(m);
// run solver over constraint islands
if (islands_supported) {
@@ -1298,7 +1327,7 @@ void mj_RungeKutta(const mjModel* m, mjData* d, int N) {
// return 1 if any flex needs implicit stiffness treatment (interp or bending)
static int flex_has_implicit_stiffness(const mjModel* m) {
static mjtBool flex_has_implicit_stiffness(const mjModel* m) {
for (int f=0; f < m->nflex; f++) {
if (m->flex_rigid[f]) {
continue;
@@ -1316,120 +1345,32 @@ static int flex_has_implicit_stiffness(const mjModel* m) {
m->flex_bendingadr[f] >= 0) {
return 1;
}
// standard flex with stretch
if (!m->flex_interp[f] && m->flex_dim[f] >= 2 &&
m->flex_stiffnessadr[f] >= 0 &&
m->flex_stiffness[m->flex_stiffnessadr[f]] != 0) {
return 1;
}
}
return 0;
}
// preconditioned CG solve for implicit flex interp
// solves (M - h*qDeriv - (h^2+h*d)*K) * qacc = qfrc - h*K*qvel
// where K is the flex stiffness, using the already-factored standard system
// (M - h*qDeriv) as a preconditioner
static void flexInterp_cgsolve(const mjModel* m, mjData* d,
mjtNum* qacc, const mjtNum* qfrc, int nv) {
mjtNum h = m->opt.timestep;
int implicit = (m->opt.integrator == mjINT_IMPLICIT);
mj_markStack(d);
// allocate CG work vectors
mjtNum* rhs = mjSTACKALLOC(d, nv, mjtNum);
mjtNum* r = mjSTACKALLOC(d, nv, mjtNum);
mjtNum* z = mjSTACKALLOC(d, nv, mjtNum);
mjtNum* p = mjSTACKALLOC(d, nv, mjtNum);
mjtNum* Ap = mjSTACKALLOC(d, nv, mjtNum);
mjtNum* temp = mjSTACKALLOC(d, nv, mjtNum);
// precompute K_rot cache: same layout as m->flex_stiffness
int krot_size = m->nflexstiffness;
mjtNum* K_rot_cache = mjSTACKALLOC(d, krot_size, mjtNum);
mju_zero(K_rot_cache, krot_size);
mjd_flexInterp_cacheKrot(m, d, K_rot_cache);
// build RHS: rhs = qfrc
mju_copy(rhs, qfrc, nv);
// flex_interp velocity correction: rhs += h*K_interp*qvel (K_interp is NSD)
mjd_flexInterp_mul(m, d, rhs, d->qvel, h, 0, K_rot_cache);
// standard flex bending velocity correction: rhs -= h*K_bend*qvel
mjd_flexBend_mul(m, d, rhs, d->qvel, -h, 0); // rhs -= h*K_bend*v
// --- helper: compute Ap = A*x ---
// A*x = (M - h*qDeriv)*x - (h^2+h*d)*K_interp*x + (h^2+h*d)*K_bend*x
#define FLEX_CG_MATVEC(Ap_out, x_in) \
mju_mulMatVecSparse(Ap_out, d->qDeriv, x_in, nv, m->D_rownnz, m->D_rowadr, \
m->D_colind, NULL); \
mju_mulSymVecSparse(temp, d->M, x_in, nv, m->M_rownnz, m->M_rowadr, \
m->M_colind); \
mju_addScl(Ap_out, temp, Ap_out, -h, nv); \
mjd_flexInterp_mul(m, d, Ap_out, x_in, -(h*h), -h, K_rot_cache); \
mjd_flexBend_mul(m, d, Ap_out, x_in, h*h, h)
// --- helper: preconditioner solve z = (M - h*qDeriv)^{-1} * r ---
#define FLEX_CG_PRECOND(z_out, r_in) \
if (implicit) { \
mju_solveLUSparse(z_out, d->qLU, r_in, nv, m->D_rownnz, m->D_rowadr, \
m->D_diag, m->D_colind, NULL); \
} else { \
mju_copy(z_out, r_in, nv); \
mj_solveLD(z_out, d->qH, d->qHDiagInv, nv, 1, m->M_rownnz, m->M_rowadr, \
m->M_colind, NULL); \
}
// initial residual: r = rhs - A*qacc
FLEX_CG_MATVEC(Ap, qacc);
mju_sub(r, rhs, Ap, nv);
// check if already converged
mjtNum rnorm = mju_dot(r, r, nv);
mjtNum tol = 1e-10 * mju_dot(rhs, rhs, nv);
if (rnorm < tol || rnorm < mjMINVAL) {
mj_freeStack(d);
return;
}
// z = precond(r), p = z
FLEX_CG_PRECOND(z, r);
mju_copy(p, z, nv);
mjtNum rz = mju_dot(r, z, nv);
// CG iterations
int maxiter = 50;
for (int iter=0; iter < maxiter; iter++) {
FLEX_CG_MATVEC(Ap, p);
// alpha = rz / dot(p, Ap)
mjtNum pAp = mju_dot(p, Ap, nv);
if (mju_abs(pAp) < mjMINVAL) break;
mjtNum alpha = rz / pAp;
// qacc += alpha * p
mju_addToScl(qacc, p, alpha, nv);
// r -= alpha * Ap
mju_addToScl(r, Ap, -alpha, nv);
// check convergence
rnorm = mju_dot(r, r, nv);
if (rnorm < tol || rnorm < mjMINVAL) break;
// z = precond(r)
FLEX_CG_PRECOND(z, r);
// beta = rz_new / rz
mjtNum rz_new = mju_dot(r, z, nv);
mjtNum beta = rz_new / mju_max(mjMINVAL, rz);
// p = z + beta * p
mju_addScl(p, z, p, beta, nv);
rz = rz_new;
}
#undef FLEX_CG_MATVEC
#undef FLEX_CG_PRECOND
mj_freeStack(d);
// implicit-flex solve gate: with the CG solver, an implicit integrator and flex stiffness
// present, the CG solve carries the implicit flex stiffness itself -- K = (h^2+h*d) times the flex stiffness enters
// the objective/gradient/linesearch, and the preconditioned gradient becomes (M+K)\grad by
// linear matrix-free CG against the existing M factor (the in-solver form of the old post-hoc
// flexInterp_cgsolve treatment, no factorization anywhere); mj_implicitSkip then folds the
// implicit flex force of the solver's qacc into qfrc. When active with islands
// enabled, mj_fwdConstraint forces a monolithic solve (flex mesh coupling is invisible to
// constraint islanding). solver="Newton" keeps its exact-factorization semantics untouched.
// Models outside the gate integrate flex elasticity explicitly.
int mj_flexCG(const mjModel* m) {
return m->opt.solver == mjSOL_CG &&
(m->opt.integrator == mjINT_IMPLICIT || m->opt.integrator == mjINT_IMPLICITFAST) &&
m->opt.cone != mjCONE_ELLIPTIC && !mjENABLED(mjENBL_SLEEP) &&
flex_has_implicit_stiffness(m);
}
@@ -1454,11 +1395,16 @@ void mj_implicitSkip(const mjModel* m, mjData* d, int skipfactor) {
mju_add(qfrc, d->qfrc_smooth, d->qfrc_constraint, nv);
}
// check for flex_interp that needs implicit treatment
int has_flex_stiffness = !sleep_filter && flex_has_implicit_stiffness(m);
// implicit flex stiffness is carried by the constraint solver (see mj_flexCG): use the
// solver's qacc directly. The qDeriv treatment is skipped for these models -- flex damping
// is already implicit inside the solve (the s2 terms of B), joint damping and other velocity
// derivatives integrate explicitly. This avoids both the qDeriv machinery and the
// sequential flex-vs-qDeriv splitting. Models outside the gate (non-Newton solver, elliptic
// cones, islands, sleep) integrate flex elasticity explicitly.
int flexcg = !sleep_filter && mj_flexCG(m);
// factorization
if (!skipfactor) {
if (!skipfactor && !flexcg) {
// implicit
if (m->opt.integrator == mjINT_IMPLICIT) {
// compute analytical derivative qDeriv
@@ -1495,7 +1441,10 @@ void mj_implicitSkip(const mjModel* m, mjData* d, int skipfactor) {
}
// standard sparse solve
if (m->opt.integrator == mjINT_IMPLICIT) {
if (flexcg) {
// constraint solver's qacc already carries the implicit flex force
mju_copy(qacc, d->qacc, m->nv);
} else if (m->opt.integrator == mjINT_IMPLICIT) {
mju_solveLUSparse(qacc, d->qLU, qfrc, nv, m->D_rownnz, m->D_rowadr, m->D_diag, m->D_colind,
dof_awake_ind);
} else {
@@ -1508,16 +1457,11 @@ void mj_implicitSkip(const mjModel* m, mjData* d, int skipfactor) {
mj_solveLD(qacc, d->qH, d->qHDiagInv, nv, 1, m->M_rownnz, m->M_rowadr, m->M_colind, dof_awake_ind);
}
// flex: CG correction for implicit flex stiffness
if (has_flex_stiffness) {
flexInterp_cgsolve(m, d, qacc, qfrc, m->nv);
}
// implicitfast: local unsymmetric solve for standalone free bodies
// adds the bias (gyroscopic) derivative, dropped from the global symmetric solve; the
// 6x6 block of M - h*D is decoupled from the rest of the system (D sparsity is tree-local),
// so overwriting these rows of qacc leaves all other DOFs unaffected
if (m->opt.integrator == mjINT_IMPLICITFAST) {
if (m->opt.integrator == mjINT_IMPLICITFAST && !flexcg) {
for (int j=0; j < m->njnt; j++) {
mjtNum A[36];
if (!mjd_freeMhat(m, d, j, m->opt.timestep, A)) {
+4
View File
@@ -64,6 +64,10 @@ MJAPI void mj_implicit(const mjModel *m, mjData *d);
// fully implicit in velocity, possibly skipping factorization
MJAPI void mj_implicitSkip(const mjModel *m, mjData *d, int skipfactor);
// implicit-flex solve gate: with solver=CG, an implicit integrator and flex stiffness present,
// the constraint solve is dispatched to the flex-augmented primal solver (monolithic,
// pyramidal cones only); solver=Newton keeps its exact-factorization semantics
int mj_flexCG(const mjModel* m);
//-------------------------------- solver components -----------------------------------------------
+13
View File
@@ -70,6 +70,9 @@ void mj_invPosition(const mjModel* m, mjData* d) {
mj_transmission(m, d);
TM_ADD(mjTIMER_POS_KINEMATICS);
// implicit effective metric: multiply-only build (no factorization) for the inverse
mjd_effBuild(m, d, mj_flexCG(m), /*flg_factor=*/0);
TM_END1(mjTIMER_POSITION);
}
@@ -177,6 +180,9 @@ static void mj_discreteAcc(const mjModel* m, mjData* d) {
mj_solveM(m, d, qacc, qfrc, 1);
mj_freeStack(d);
// refresh the effective-metric velocity shift
mjd_effShift(m, d);
}
@@ -262,6 +268,13 @@ void mj_inverseSkip(const mjModel* m, mjData* d,
mjtNum* Ma = mjSTACKALLOC(d, nv, mjtNum);
mj_mulM(m, d, Ma, d->qacc);
// implicit effective metric (built in mj_invPosition): the forward dynamics solved
// (M+K)*qacc = qfrc + c + J'*f, so the discrete-consistent inverse adds K*qacc - c
if (d->efm_active) {
mjd_effMulAdd(m, d, Ma, d->qacc);
mju_subFrom(Ma, d->efm_c, nv);
}
// qfrc_inverse += Ma - qfrc_passive - qfrc_constraint
for (int i=0; i < nv; i++) {
d->qfrc_inverse[i] += Ma[i] - d->qfrc_passive[i] - d->qfrc_constraint[i];
+11 -3
View File
@@ -230,7 +230,8 @@ void mj_makeModel(mjModel** dest,
mjtSize nbvhdynamic, mjtSize noct, mjtSize njnt, mjtSize ntree, mjtSize nM, mjtSize nB,
mjtSize nC, mjtSize nD, mjtSize ngeom, mjtSize nsite, mjtSize ncam, mjtSize nlight,
mjtSize nflex, mjtSize nflexnode, mjtSize nflexvert, mjtSize nflexedge, mjtSize nflexelem,
mjtSize nflexelemdata, mjtSize nflexstiffness, mjtSize nflexbending, mjtSize nflexelemedge,
mjtSize nflexelemdata, mjtSize nflexstiffness, mjtSize nflexbending,
mjtSize nefm0dof, mjtSize nefm0L, mjtSize nflexelemedge,
mjtSize nflexshelldata, mjtSize nflexevpair, mjtSize nflextexcoord, mjtSize nJfe, mjtSize nJfv,
mjtSize nmesh, mjtSize nmeshvert, mjtSize nmeshnormal, mjtSize nmeshtexcoord, mjtSize nmeshface,
mjtSize nmeshgraph, mjtSize nmeshpoly, mjtSize nmeshpolyvert, mjtSize nmeshpolymap,
@@ -324,6 +325,8 @@ void mj_makeModel(mjModel** dest,
m->nflexelemdata = nflexelemdata;
m->nflexstiffness = nflexstiffness;
m->nflexbending = nflexbending;
m->nefm0dof = nefm0dof;
m->nefm0L = nefm0L;
m->nflexelemedge = nflexelemedge;
m->nflexshelldata = nflexshelldata;
m->nflexevpair = nflexevpair;
@@ -436,7 +439,7 @@ mjModel* mj_copyModel(mjModel* dest, const mjModel* src) {
src->nbvhdynamic, src->noct, src->njnt, src->ntree, src->nM, src->nB, src->nC, src->nD,
src->ngeom, src->nsite, src->ncam, src->nlight, src->nflex, src->nflexnode, src->nflexvert,
src->nflexedge, src->nflexelem, src->nflexelemdata, src->nflexstiffness,
src->nflexbending, src->nflexelemedge, src->nflexshelldata, src->nflexevpair,
src->nflexbending, src->nefm0dof, src->nefm0L, src->nflexelemedge, src->nflexshelldata, src->nflexevpair,
src->nflextexcoord, src->nJfe, src->nJfv, src->nmesh, src->nmeshvert, src->nmeshnormal,
src->nmeshtexcoord, src->nmeshface, src->nmeshgraph, src->nmeshpoly, src->nmeshpolyvert,
src->nmeshpolymap, src->nskin, src->nskinvert, src->nskintexvert, src->nskinface,
@@ -615,7 +618,8 @@ mjModel* mj_loadModelBuffer(const void* buffer, int buffer_sz) {
sizes[56], sizes[57], sizes[58], sizes[59], sizes[60], sizes[61], sizes[62],
sizes[63], sizes[64], sizes[65], sizes[66], sizes[67], sizes[68], sizes[69],
sizes[70], sizes[71], sizes[72], sizes[73], sizes[74], sizes[75], sizes[76],
sizes[77], sizes[78], sizes[79], sizes[80], sizes[81]);
sizes[77], sizes[78], sizes[79], sizes[80], sizes[81],
sizes[82], sizes[83]);
// mj_makeModel may fail if the input buffer has invalid sizes
if (!m) {
@@ -1343,6 +1347,10 @@ static void _resetData(const mjModel* m, mjData* d, unsigned char debug_value) {
d->nA = 0;
d->nisland = 0;
d->nidof = 0;
d->efm_active = 0;
d->nefmK = 0;
d->nefmdof = 0;
d->nefmL = 0;
// clear global properties
d->time = 0;
+2 -1
View File
@@ -53,7 +53,8 @@ void mj_makeModel(mjModel** dest,
mjtSize nbvhdynamic, mjtSize noct, mjtSize njnt, mjtSize ntree, mjtSize nM, mjtSize nB,
mjtSize nC, mjtSize nD, mjtSize ngeom, mjtSize nsite, mjtSize ncam, mjtSize nlight,
mjtSize nflex, mjtSize nflexnode, mjtSize nflexvert, mjtSize nflexedge, mjtSize nflexelem,
mjtSize nflexelemdata, mjtSize nflexstiffness, mjtSize nflexbending, mjtSize nflexelemedge,
mjtSize nflexelemdata, mjtSize nflexstiffness, mjtSize nflexbending,
mjtSize nefm0dof, mjtSize nefm0L, mjtSize nflexelemedge,
mjtSize nflexshelldata, mjtSize nflexevpair, mjtSize nflextexcoord, mjtSize nJfe, mjtSize nJfv,
mjtSize nmesh, mjtSize nmeshvert, mjtSize nmeshnormal, mjtSize nmeshtexcoord, mjtSize nmeshface,
mjtSize nmeshgraph, mjtSize nmeshpoly, mjtSize nmeshpolyvert, mjtSize nmeshpolymap,
+41
View File
@@ -371,6 +371,47 @@ static int findEdges(const mjModel* m, const mjData* d,
}
}
// flex stiffness couples all vertices (nodes for interpolated flexes) of a flex without any
// constraint row representing the coupling: union the trees of every stiffness-active flex
// (star around the first dynamic tree). This keeps the partition valid when the implicit
// effective metric (mj_flexCG) carries the stiffness inside the constraint solve. Awake
// trees only: sleeping trees must stay out of islands (mj_sleep invariant, matching the
// constraint filter); waking a flex as a unit remains the wake machinery's job.
for (int f=0; f < m->nflex; f++) {
// mirror the stiffness-activity conditions of engine_derivative's flexStiff_active /
// flexInterp_processed: deformable dim>=2 flex with bending or nonzero stiffness
if (m->flex_rigid[f] || m->flex_dim[f] < 2) {
continue;
}
int sadr = m->flex_stiffnessadr[f];
if (m->flex_bendingadr[f] < 0 && (sadr < 0 || m->flex_stiffness[sadr] == 0)) {
continue;
}
int num, adr;
const int* bodyid;
if (m->flex_interp[f]) {
num = m->flex_nodenum[f];
adr = m->flex_nodeadr[f];
bodyid = m->flex_nodebodyid;
} else {
num = m->flex_vertnum[f];
adr = m->flex_vertadr[f];
bodyid = m->flex_vertbodyid;
}
int tree1 = -1;
for (int j=0; j < num; j++) {
int treeid = m->body_treeid[bodyid[adr+j]];
if (treeid < 0 || treeid == tree1 || !d->tree_awake[treeid]) {
continue;
}
if (tree1 < 0) {
tree1 = treeid;
} else {
nnz += addEdge(rownnz, colind, tree_tree, ntree, tree1, treeid);
}
}
}
return nnz;
}
+164
View File
@@ -23,11 +23,13 @@
#include <mujoco/mjsan.h> // IWYU pragma: keep
#include "engine/engine_core_smooth.h"
#include "engine/engine_core_util.h"
#include "engine/engine_derivative.h"
#include "engine/engine_forward.h"
#include "engine/engine_io.h"
#include "engine/engine_memory.h"
#include "engine/engine_util_blas.h"
#include "engine/engine_util_errmem.h"
#include "engine/engine_util_solve.h"
#include "engine/engine_util_misc.h"
#include "engine/engine_util_sparse.h"
#include "engine/engine_util_spatial.h"
@@ -1320,6 +1322,165 @@ static void setSpring(mjModel* m, mjData* d) {
// entry point: set all remaining constant fields of mjModel, except for lengthrange
// constant part of the implicit effective metric factor (currently dim-2 bending): sparse
// reverse-Cholesky of M + (h^2 + h*damping)*K_bend over
// the dofs of unpinned vertices of standard dim-2 flexes with bending. The matrix is constant
// (flat-rest bending stiffness, point masses), so the factor is computed here once and reused
// by the implicit-flex constraint solve every step. Bending couples only same-coordinate dofs,
// so the pattern is three interleaved copies of the vertex flap adjacency. Row order (flex
// order, vertex order, coordinate fastest) and the resulting fill count must match the
// compiler's symbolic sizing (checked below).
static void setEfm0Factor(mjModel* m, mjData* d) {
int nbd = m->nefm0dof;
if (!nbd) {
return;
}
mj_markStack(d);
mjtNum h = m->opt.timestep;
// enumerate covered vertices: compact slot per unpinned vertex of qualifying flexes
// (filter matches the compiler's sizing and, for bending, flexStiff_active in
// engine_derivative.c: bending data exists only for dim-2 flexes)
int* vslot = mjSTACKALLOC(d, m->nflexvert > 0 ? m->nflexvert : 1, int);
for (int i=0; i < m->nflexvert; i++) {
vslot[i] = -1;
}
int nfree = 0;
for (int f=0; f < m->nflex; f++) {
if (m->flex_interp[f] || m->flex_rigid[f] || m->flex_dim[f] != 2 ||
m->flex_bendingadr[f] < 0) {
continue;
}
for (int lv=0; lv < m->flex_vertnum[f]; lv++) {
int gv = m->flex_vertadr[f] + lv;
if (m->body_dofnum[m->flex_vertbodyid[gv]] == 3) {
vslot[gv] = nfree;
nfree++;
}
}
}
if (3*nfree != nbd) {
mj_freeStack(d);
mjERROR("constant metric factor dof count mismatch: compiler sized %d, engine found %d",
nbd, 3*nfree);
}
// fill row -> dof address (row 3*slot + k, coordinate fastest)
for (int gv=0; gv < m->nflexvert; gv++) {
if (vslot[gv] >= 0) {
int da = m->body_dofadr[m->flex_vertbodyid[gv]];
for (int k=0; k < 3; k++) {
m->efm0_dofid[3*vslot[gv] + k] = da + k;
}
}
}
// assemble the bending-only stiffness K = (h^2 + h*damping)*K_bend over all dofs with the
// shared stencil walker from engine_derivative: bending values are configuration-independent
// and stretch/interp are gated off, so the call is valid at set-constants time (d is used
// for stack scratch only)
int nv = m->nv;
int* K_rownnz = mjSTACKALLOC(d, nv, int);
int* K_rowadr = mjSTACKALLOC(d, nv, int);
int nK = mjd_flexStiff_assemble(m, d, K_rownnz, K_rowadr, NULL, NULL, h*h, h,
/*flg_bend=*/1, /*flg_stretch=*/0, NULL);
int* K_colind = mjSTACKALLOC(d, nK > 0 ? nK : 1, int);
mjtNum* K_val = mjSTACKALLOC(d, nK > 0 ? nK : 1, mjtNum);
mjd_flexStiff_assemble(m, d, K_rownnz, K_rowadr, K_colind, K_val, h*h, h, 1, 0, NULL);
// inverse map: dof address -> compact factor row (monotone: slots follow dof order)
int* dofrow = mjSTACKALLOC(d, nv, int);
for (int i=0; i < nv; i++) {
dofrow[i] = -1;
}
for (int r=0; r < nbd; r++) {
dofrow[m->efm0_dofid[r]] = r;
}
// compact B to covered rows, keeping same-coordinate entries only: bending blocks are
// isotropic (q * I3), so the off-coordinate entries of assemble's 3x3 block pattern are
// structurally zero and dropping them preserves the pattern the compiler sized.
// H = M + (h^2+h*d)*K_bend in compact dof indices: lower CSR (values) + upper CSR (pattern)
int nHl = 0, nHu = 0;
for (int r=0; r < nbd; r++) {
int dof = m->efm0_dofid[r];
for (int c=0; c < K_rownnz[dof]; c++) {
int rc = dofrow[K_colind[K_rowadr[dof] + c]];
if (rc < 0 || (rc - r) % 3 != 0) continue; // uncovered or off-coordinate
if (rc < r) nHl++;
else if (rc > r) nHu++;
}
}
nHl += nbd; // diagonals: always present, also for rows without bending entries
int* Hl_rownnz = mjSTACKALLOC(d, nbd, int);
int* Hl_rowadr = mjSTACKALLOC(d, nbd, int);
int* Hl_colind = mjSTACKALLOC(d, nHl, int);
mjtNum* Hl_val = mjSTACKALLOC(d, nHl, mjtNum);
int* Hu_rownnz = mjSTACKALLOC(d, nbd, int);
int* Hu_rowadr = mjSTACKALLOC(d, nbd, int);
int* Hu_colind = mjSTACKALLOC(d, nHu > 0 ? nHu : 1, int);
int ladr = 0, uadr = 0;
for (int r=0; r < nbd; r++) {
int dof = m->efm0_dofid[r];
Hl_rowadr[r] = ladr;
Hu_rowadr[r] = uadr;
mjtNum diag = 0;
// B columns are dof-ascending, so filtered lower/upper columns stay ascending
for (int c=0; c < K_rownnz[dof]; c++) {
int adr = K_rowadr[dof] + c;
int rc = dofrow[K_colind[adr]];
if (rc < 0 || (rc - r) % 3 != 0) continue;
if (rc < r) {
Hl_colind[ladr] = rc;
Hl_val[ladr++] = K_val[adr];
} else if (rc > r) {
Hu_colind[uadr++] = rc;
} else {
diag = K_val[adr];
}
}
// diagonal last: point mass + armature + bending diagonal
Hl_colind[ladr] = r;
Hl_val[ladr++] = m->body_mass[m->dof_bodyid[dof]] + m->dof_armature[dof] + diag;
Hl_rownnz[r] = ladr - Hl_rowadr[r];
Hu_rownnz[r] = uadr - Hu_rowadr[r];
}
// symbolic factorization: counting phase (from the upper-triangle pattern)
int* LT_rownnz = mjSTACKALLOC(d, nbd, int);
int* LT_rowadr = mjSTACKALLOC(d, nbd, int);
int nnz = mju_cholFactorSymbolic(NULL, m->efm0_L_rownnz, m->efm0_L_rowadr,
NULL, LT_rownnz, LT_rowadr, NULL,
Hu_rownnz, Hu_rowadr, Hu_colind, nbd, d);
if (nnz != m->nefm0L) {
mj_freeStack(d);
mjERROR("constant metric factor size mismatch: compiler sized %d, symbolic found %d",
(int)m->nefm0L, nnz);
}
// symbolic factorization: filling phase
int* LT_colind = mjSTACKALLOC(d, nnz, int);
int* LT_map = mjSTACKALLOC(d, nnz, int);
mju_cholFactorSymbolic(m->efm0_L_colind, m->efm0_L_rownnz, m->efm0_L_rowadr,
LT_colind, LT_rownnz, LT_rowadr, LT_map,
Hu_rownnz, Hu_rowadr, Hu_colind, nbd, d);
// numeric factorization
int rank = mju_cholFactorNumeric(m->efm0_L, nbd, mjMINVAL,
m->efm0_L_rownnz, m->efm0_L_rowadr, m->efm0_L_colind,
LT_rownnz, LT_rowadr, LT_colind, LT_map,
Hl_val, Hl_rownnz, Hl_rowadr, Hl_colind, d);
if (rank != nbd) {
mj_freeStack(d);
mjERROR("constant metric factor is rank-deficient (%d of %d)", rank, nbd);
}
mj_freeStack(d);
}
void mj_setConst(mjModel* m, mjData* d) {
// compute npolygonmax and nmeshdegmax
m->npolygonmax = 0;
@@ -1354,6 +1515,9 @@ void mj_setConst(mjModel* m, mjData* d) {
// set quantities that depend qpos_spring
setSpring(m, d);
// precompute the constant part of the implicit effective metric factor
setEfm0Factor(m, d);
}
+44 -6
View File
@@ -24,6 +24,7 @@
#include <mujoco/mjsan.h> // IWYU pragma: keep
#include "engine/engine_core_constraint.h"
#include "engine/engine_core_smooth.h"
#include "engine/engine_derivative.h"
#include "engine/engine_core_util.h"
#include "engine/engine_memory.h"
#include "engine/engine_macro.h"
@@ -1068,6 +1069,13 @@ typedef struct {
mjtNum* L; // Cholesky factor (nL x 1)
mjtNum* Lcone; // Cholesky factor with cone contributions (nL x 1)
// implicit effective metric for flex: Mtilde = M + K (built per step in mj_fwdPosition): when
// active, ctx.qfrc_smooth is pre-shifted by +c and Ma/Mv carry the B term, so the stock
// objective/gradient/linesearch formulas below operate in the Mtilde metric unchanged
int flg_flex; // effective metric active for this solve
const mjModel* fm; // model, for the metric calls
mjData* fd; // data, for the metric calls
// globals
mjtNum cost; // constraint + Gauss cost
mjtNum quadGauss[3]; // quadratic polynomial for Gauss cost
@@ -1331,10 +1339,29 @@ static void PrimalAllocate(const mjModel* m, mjData* d, mjPrimalContext* ctx, in
// sparse: compute Jacobian transpose
if (is_sparse) {
int offset = ctx->J_rowadr[0];
mju_transposeSparse(ctx->JT, ctx->J + offset, nefc, nv,
ctx->JT_rownnz, ctx->JT_rowadr, ctx->JT_colind, ctx->JT_rowsuper,
ctx->J_rownnz, ctx->J_rowadr, ctx->J_colind + offset);
if (nefc) {
int offset = ctx->J_rowadr[0];
mju_transposeSparse(ctx->JT, ctx->J + offset, nefc, nv,
ctx->JT_rownnz, ctx->JT_rowadr, ctx->JT_colind, ctx->JT_rowsuper,
ctx->J_rownnz, ctx->J_rowadr, ctx->J_colind + offset);
} else {
// no constraints (reachable via the flex CG dispatch): valid empty transpose structures
mju_zeroInt(ctx->JT_rownnz, nv);
mju_zeroInt(ctx->JT_rowadr, nv);
mju_zeroInt(ctx->JT_rowsuper, nv);
}
}
// implicit effective metric (built in mj_fwdPosition): route Ma/Mv/Mgrad through the
// metric operators and shift the smooth force, so the stock objective/gradient/linesearch
// formulas operate in the Mtilde = M+K metric
if (ctx->island < 0 && !is_elliptic && !flg_Newton && d->efm_active) {
ctx->flg_flex = 1;
ctx->fm = m;
ctx->fd = d;
mjtNum* qfrc_eff = mjSTACKALLOC(d, nv, mjtNum);
mju_add(qfrc_eff, ctx->qfrc_smooth, d->efm_c, nv);
ctx->qfrc_smooth = qfrc_eff;
}
}
@@ -1399,6 +1426,11 @@ static void PrimalUpdateMgrad(mjPrimalContext* ctx, int flg_Newton) {
}
}
// CG: Mgrad = Mtilde \ grad
else if (ctx->flg_flex) {
mjd_effSolve(ctx->fm, ctx->fd, ctx->Mgrad, ctx->grad);
}
// CG: Mgrad = M \ grad
else {
mju_copy(ctx->Mgrad, ctx->grad, nv);
@@ -1843,9 +1875,12 @@ static mjtNum PrimalSearch(mjPrimalContext* ctx, mjtNum tolerance, mjtNum ls_ite
mjtNum gtol = tolerance * snorm / ctx->scale;
mjtNum slopescl = ctx->scale / snorm;
// compute Mv = M * v
// compute Mv = Mtilde * v
mju_mulSymVecSparse(ctx->Mv, ctx->M, ctx->search, nv,
ctx->M_rownnz, ctx->M_rowadr, ctx->M_colind);
if (ctx->flg_flex) {
mjd_effMulAdd(ctx->fm, ctx->fd, ctx->Mv, ctx->search);
}
// compute Jv = J * search (dense or sparse)
if (!ctx->is_sparse) {
@@ -2321,9 +2356,12 @@ static void mj_solPrimal(const mjModel* m, mjData* d, int island, int maxiter, i
int nefc = ctx.nefc;
int* oldstate = ctx.oldstate;
// compute Ma = M * qacc
// compute Ma = Mtilde * qacc
mju_mulSymVecSparse(ctx.Ma, ctx.M, ctx.qacc, nv,
ctx.M_rownnz, ctx.M_rowadr, ctx.M_colind);
if (ctx.flg_flex) {
mjd_effMulAdd(m, d, ctx.Ma, ctx.qacc);
}
// compute Jaref = J * qacc - aref (dense or sparse)
+16 -6
View File
@@ -192,16 +192,19 @@ int mju_cholFactorSymbolic(int* restrict L_colind, int* restrict L_rownnz, int*
int* restrict LT_rowadr, int* restrict LT_map,
const int* rownnz, const int* rowadr, const int* colind, int n,
mjData* d) {
mj_markStack(d);
int* restrict parent = mjSTACKALLOC(d, n, int);
int* restrict flag = mjSTACKALLOC(d, n, int);
// d supplies stack scratch; if NULL, scratch is heap-allocated
if (d) {
mj_markStack(d);
}
int* restrict parent = d ? mjSTACKALLOC(d, n, int) : (int*) mju_malloc(sizeof(int)*n);
int* restrict flag = d ? mjSTACKALLOC(d, n, int) : (int*) mju_malloc(sizeof(int)*n);
int* restrict cursor = NULL;
int* LT_write = NULL;
// filling phase: initialize write positions
if (L_colind) {
cursor = mjSTACKALLOC(d, n, int);
LT_write = mjSTACKALLOC(d, n, int);
cursor = d ? mjSTACKALLOC(d, n, int) : (int*) mju_malloc(sizeof(int)*n);
LT_write = d ? mjSTACKALLOC(d, n, int) : (int*) mju_malloc(sizeof(int)*n);
for (int r = 0; r < n; r++) {
cursor[r] = L_rowadr[r] + L_rownnz[r] - 2; // end of row r (before diagonal)
LT_write[r] = LT_rowadr[r]; // start of LT row r
@@ -270,7 +273,14 @@ int mju_cholFactorSymbolic(int* restrict L_colind, int* restrict L_rownnz, int*
}
}
mj_freeStack(d);
if (d) {
mj_freeStack(d);
} else {
mju_free(parent);
mju_free(flag);
mju_free(cursor);
mju_free(LT_write);
}
// counting phase: compute row addresses, add up total non-zeros
int nnz = 0;
+1
View File
@@ -41,6 +41,7 @@ MJAPI int mju_cholFactorSparse(mjtNum* mat, int n, mjtNum mindiag,
// if L_colind is NULL, perform counting logic (fill rownnz/rowadr arrays and return total nnz)
// if L_colind is not NULL, assume rownnz/rowadr are precomputed and fill colind/map arrays
// reads pattern from upper triangle
// d may be NULL: scratch is then heap-allocated
// based on ldl_symbolic from 'Algorithm 8xx: a concise sparse Cholesky factorization package'
MJAPI int mju_cholFactorSymbolic(int* L_colind, int* L_rownnz, int* L_rowadr,
int* LT_colind, int* LT_rownnz, int* LT_rowadr, int* LT_map,