@geotechcli/core 0.4.109 → 0.4.111

package/dist/fem/plane-strain-assembly.js

@@ -1093,7 +1093,7 @@ export function runPlaneStrainBiotConsolidation(model) {
             pressureOvershootKpa: round(pressureOvershootKpa, 8),
         };
         const maxVerticalSettlementM = Math.max(0, -Math.min(...model.nodes.map((_, index) => displacement[dofIndex(index, 'uy')])));
-        const converged = residualNormRatio <= policy.forceBalanceTolerance &&
+        const acceptedByPolicy = residualNormRatio <= policy.forceBalanceTolerance &&
             massBalanceErrorRatio <= policy.porePressureMassBalanceTolerance;
         timeSteps.push({
             step: stepIndex + 1,
@@ -1109,7 +1109,8 @@ export function runPlaneStrainBiotConsolidation(model) {
             minPorePressureKpa: round(minPorePressureKpa, 8),
             maxPorePressureKpa: round(maxPorePressureKpa, 8),
             maxVerticalSettlementM: round(maxVerticalSettlementM, 12),
-            converged,
+            acceptedByPolicy,
+            converged: acceptedByPolicy,
         });
         previousDisplacement = [...displacement];
         previousPorePressure = [...porePressure];
@@ -1125,6 +1126,69 @@ export function runPlaneStrainBiotConsolidation(model) {
         lastMinPorePressureKpa = minPorePressureKpa;
         lastMaxPorePressureKpa = maxPorePressureKpa;
     }
+    let monotonicAverageFreePressureDissipation = true;
+    let monotonicMaxPressureEnvelope = true;
+    let previousAverageFreePressure = initialAverageFreePorePressureKpa;
+    let previousMaxPressure = pressureUpperBoundKpa;
+    let maxPressureOvershootKpa = 0;
+    let maxResidualNormRatio = 0;
+    let maxMassBalanceErrorRatio = 0;
+    const pressureMonotonicToleranceKpa = 1e-8;
+    for (const step of timeSteps) {
+        maxResidualNormRatio = Math.max(maxResidualNormRatio, step.residualNormRatio);
+        maxMassBalanceErrorRatio = Math.max(maxMassBalanceErrorRatio, step.massBalanceErrorRatio);
+        maxPressureOvershootKpa = Math.max(maxPressureOvershootKpa, step.pressureDiagnostics.pressureOvershootKpa);
+        if (step.pressureDiagnostics.averageFreePorePressureKpa >
+            previousAverageFreePressure + pressureMonotonicToleranceKpa) {
+            monotonicAverageFreePressureDissipation = false;
+        }
+        if (step.maxPorePressureKpa > previousMaxPressure + pressureMonotonicToleranceKpa) {
+            monotonicMaxPressureEnvelope = false;
+        }
+        previousAverageFreePressure = step.pressureDiagnostics.averageFreePorePressureKpa;
+        previousMaxPressure = step.maxPorePressureKpa;
+    }
+    const acceptedStepCount = timeSteps.filter((step) => step.acceptedByPolicy).length;
+    const monotonicAverageFreePressureDissipationRequired = Array.from(prescribedPressures.values()).every((value) => value <= pressureMonotonicToleranceKpa) &&
+        fluxes.every((value) => Math.abs(value) <= 1e-15);
+    const dissipationCheckMode = monotonicAverageFreePressureDissipationRequired
+        ? 'drained-dissipation'
+        : 'prescribed-gradient-relaxation';
+    const transientBlockerCodes = [
+        ...(acceptedStepCount < policy.minAcceptedSteps
+            ? ['accepted-step-count-less-than-policy']
+            : []),
+        ...(maxResidualNormRatio > policy.forceBalanceTolerance
+            ? ['force-residual-tolerance-exceeded']
+            : []),
+        ...(maxMassBalanceErrorRatio > policy.porePressureMassBalanceTolerance
+            ? ['pore-pressure-mass-balance-tolerance-exceeded']
+            : []),
+        ...(maxPressureOvershootKpa > 1e-6
+            ? ['pressure-overshoot-nonzero']
+            : []),
+        ...(monotonicAverageFreePressureDissipationRequired && !monotonicAverageFreePressureDissipation
+            ? ['average-free-pore-pressure-dissipation-not-monotonic']
+            : []),
+        ...(!monotonicMaxPressureEnvelope
+            ? ['max-pore-pressure-envelope-not-monotonic']
+            : []),
+    ];
+    const transientAcceptance = {
+        schemaVersion: 'fem-plane-strain-biot-transient-acceptance.v1',
+        accepted: transientBlockerCodes.length === 0,
+        dissipationCheckMode,
+        acceptedStepCount,
+        requiredStepCount: policy.minAcceptedSteps,
+        maxResidualNormRatio: round(maxResidualNormRatio, 12),
+        maxMassBalanceErrorRatio: round(maxMassBalanceErrorRatio, 12),
+        maxPressureOvershootKpa: round(maxPressureOvershootKpa, 8),
+        monotonicAverageFreePressureDissipation,
+        monotonicAverageFreePressureDissipationRequired,
+        monotonicMaxPressureEnvelope,
+        finalPorePressureDissipationRatio: round(lastPressureDiagnostics.porePressureDissipationRatio, 12),
+        blockerCodes: transientBlockerCodes,
+    };
     let maxBiotCouplingKpa = 0;
     const elementOutputs = elementGaussCache.map((entry) => {
         const material = materialById.get(entry.element.materialId);
@@ -1220,10 +1284,11 @@ export function runPlaneStrainBiotConsolidation(model) {
         freePorePressureResidualL1M3PerS: Number(lastFreePorePressureResidualL1M3PerS.toExponential(12)),
         pressureAudit: lastPressureAudit,
         pressureDiagnostics: lastPressureDiagnostics,
+        transientAcceptance,
         massBalanceErrorRatio: round(lastMassBalanceErrorRatio, 12),
         minPorePressureKpa: round(lastMinPorePressureKpa, 8),
         maxPorePressureKpa: round(lastMaxPorePressureKpa, 8),
-        converged: timeSteps.every((step) => step.converged),
+        converged: transientAcceptance.accepted,
         productionReady: false,
         policy,
         limitations: [
@@ -1708,6 +1773,42 @@ function normalizeLoadStepFractions(options) {
     }
     return fractions;
 }
+function normalizeAdaptiveDruckerPragerLoadStepping(value) {
+    if (value == null || value === false) {
+        return {
+            enabled: false,
+            strategy: 'explicit-only',
+            minLoadFactorIncrement: 0,
+            maxCutbacks: 0,
+        };
+    }
+    const options = value === true ? {} : value;
+    const enabled = options.enabled ?? true;
+    if (!enabled) {
+        return {
+            enabled: false,
+            strategy: 'explicit-only',
+            minLoadFactorIncrement: 0,
+            maxCutbacks: 0,
+        };
+    }
+    const strategy = options.strategy ?? 'cutback-bisection';
+    if (strategy !== 'cutback-bisection') {
+        throw new Error('adaptiveLoadStepping.strategy must be cutback-bisection.');
+    }
+    const minLoadFactorIncrement = options.minLoadFactorIncrement ?? 1 / 64;
+    if (!Number.isFinite(minLoadFactorIncrement) || minLoadFactorIncrement <= 0 || minLoadFactorIncrement >= 1) {
+        throw new Error('adaptiveLoadStepping.minLoadFactorIncrement must be finite and between 0 and 1.');
+    }
+    const maxCutbacks = Math.floor(options.maxCutbacks ?? 24);
+    assertPositiveInteger(maxCutbacks, 'adaptiveLoadStepping.maxCutbacks');
+    return {
+        enabled: true,
+        strategy,
+        minLoadFactorIncrement,
+        maxCutbacks,
+    };
+}
 function isDruckerPragerStepConverged(evaluation, policy) {
     return evaluation.residualNormRatio <= policy.forceBalanceTolerance &&
         evaluation.maxYieldResidualRatio <= policy.residualTolerance;
@@ -1715,6 +1816,19 @@ function isDruckerPragerStepConverged(evaluation, policy) {
 function createInitialDruckerPragerStateGrid(system) {
     return system.elementGaussCache.map((entry) => entry.gauss.map(() => initialDruckerPragerState()));
 }
+function druckerPragerStateSignature(states) {
+    return states
+        .flatMap((elementStates) => elementStates)
+        .map((state) => [
+        ...state.strain,
+        ...state.stressKpa,
+        state.sigmaZKpa,
+        state.equivalentPlasticStrain,
+        ...state.plasticStrainPrincipal,
+        state.volumetricPlasticStrain,
+    ].map((value) => round(value, 12)).join(','))
+        .join('|');
+}
 function druckerPragerResidualHistoryEntry(iteration, evaluation, policy) {
     return {
         iteration,
@@ -1830,6 +1944,7 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
     }
     const linearSolverMaxIterations = options.linearSolverMaxIterations ?? Math.max(100, system.freeDofs.length * 10);
     assertPositiveInteger(linearSolverMaxIterations, 'linearSolverMaxIterations');
+    const adaptiveOptions = normalizeAdaptiveDruckerPragerLoadStepping(options.adaptiveLoadStepping);
     const reducedDenseK = linearSolver === 'dense-gaussian'
         ? system.freeDofs.map((row) => system.freeDofs.map((col) => system.stiffness[row][col]))
         : undefined;
@@ -1843,14 +1958,22 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
     let committedStates = createInitialDruckerPragerStateGrid(system);
     let finalEvaluation;
     const loadSteps = [];
-    for (const [stepIndex, loadFactor] of loadStepFractions.entries()) {
+    let currentLoadFactor = 0;
+    let attemptedStepCount = 0;
+    let cutbackCount = 0;
+    let maxCutbackDepth = 0;
+    const acceptedLoadFactors = [];
+    const adaptiveAttemptAudits = [];
+    const adaptiveBlockerCodes = [];
+    function solveDruckerPragerStepAttempt(input) {
+        const trialDisplacement = [...input.startingDisplacement];
         for (const [index, value] of system.prescribed)
-            displacement[index] = value * loadFactor;
+            trialDisplacement[index] = value * input.loadFactor;
         let evaluation = evaluatePlaneStrainDruckerPragerState({
             system,
-            displacement,
-            loadFactor,
-            committedStates,
+            displacement: trialDisplacement,
+            loadFactor: input.loadFactor,
+            committedStates: input.startingCommittedStates,
         });
         let iterations = 0;
         let converged = isDruckerPragerStepConverged(evaluation, system.policy);
@@ -1864,7 +1987,7 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
             if (system.freeDofs.length === 0)
                 break;
             const correctionRhs = system.freeDofs.map((index) => -evaluation.residual[index]);
-            const currentFreeDisplacement = system.freeDofs.map((index) => displacement[index]);
+            const currentFreeDisplacement = system.freeDofs.map((index) => trialDisplacement[index]);
             const solved = linearSolver === 'sparse-csr-cg'
                 ? solveSparseDruckerPragerCorrection({
                     reducedK: reducedSparseK,
@@ -1887,51 +2010,155 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
             }
             const correction = solved.correction;
             for (const [correctionIndex, dof] of system.freeDofs.entries()) {
-                displacement[dof] += correction[correctionIndex];
+                trialDisplacement[dof] += correction[correctionIndex];
             }
             for (const [index, value] of system.prescribed)
-                displacement[index] = value * loadFactor;
+                trialDisplacement[index] = value * input.loadFactor;
             evaluation = evaluatePlaneStrainDruckerPragerState({
                 system,
-                displacement,
-                loadFactor,
-                committedStates,
+                displacement: trialDisplacement,
+                loadFactor: input.loadFactor,
+                committedStates: input.startingCommittedStates,
             });
             converged = isDruckerPragerStepConverged(evaluation, system.policy);
             residualHistory.push(druckerPragerResidualHistoryEntry(iterations, evaluation, system.policy));
         }
-        finalEvaluation = evaluation;
-        if (converged)
-            committedStates = evaluation.trialStates;
         const terminationReason = druckerPragerTerminationReason(evaluation, system.policy, converged, iterations, linearSolverFailure);
         const lastLinearAudit = linearSolverAudits.at(-1);
-        loadSteps.push({
-            step: stepIndex + 1,
-            loadFactor: round(loadFactor, 8),
-            iterations,
-            maxFreeResidualKn: round(evaluation.maxFreeResidualKn, 12),
-            residualNormRatio: round(evaluation.residualNormRatio, 12),
-            reactionBalanceRatio: round(evaluation.reactionBalanceRatio, 12),
-            maxYieldResidualRatio: round(evaluation.maxYieldResidualRatio, 12),
-            maxEquivalentPlasticStrain: round(evaluation.maxEquivalentPlasticStrain, 12),
-            maxEquivalentPlasticStrainIncrement: round(evaluation.maxEquivalentPlasticStrainIncrement, 12),
-            plasticGaussPointCount: evaluation.plasticGaussPointCount,
-            linearSolver,
-            linearIterations: linearSolverAudits.reduce((sum, audit) => sum + audit.iterations, 0),
-            linearResidualNormRatio: round(lastLinearAudit?.residualNormRatio ?? 0, 12),
-            correctionNormRatio: round(lastLinearAudit?.correctionNormRatio ?? 0, 12),
-            linearSolverAudits,
+        return {
+            evaluation,
+            displacement: trialDisplacement,
             converged,
-            terminationReason,
-            ...(linearSolverFailure?.failureReason ? { failureReason: linearSolverFailure.failureReason } : {}),
-            residualHistory,
+            step: {
+                step: input.step,
+                loadFactor: round(input.loadFactor, 8),
+                ...(Math.abs(input.requestedLoadFactor - input.loadFactor) > 1e-12
+                    ? { requestedLoadFactor: round(input.requestedLoadFactor, 8) }
+                    : {}),
+                ...(input.cutbackDepth > 0 ? { cutbackDepth: input.cutbackDepth, adaptiveCutback: true } : {}),
+                iterations,
+                maxFreeResidualKn: round(evaluation.maxFreeResidualKn, 12),
+                residualNormRatio: round(evaluation.residualNormRatio, 12),
+                reactionBalanceRatio: round(evaluation.reactionBalanceRatio, 12),
+                maxYieldResidualRatio: round(evaluation.maxYieldResidualRatio, 12),
+                maxEquivalentPlasticStrain: round(evaluation.maxEquivalentPlasticStrain, 12),
+                maxEquivalentPlasticStrainIncrement: round(evaluation.maxEquivalentPlasticStrainIncrement, 12),
+                plasticGaussPointCount: evaluation.plasticGaussPointCount,
+                linearSolver,
+                linearIterations: linearSolverAudits.reduce((sum, audit) => sum + audit.iterations, 0),
+                linearResidualNormRatio: round(lastLinearAudit?.residualNormRatio ?? 0, 12),
+                correctionNormRatio: round(lastLinearAudit?.correctionNormRatio ?? 0, 12),
+                linearSolverAudits,
+                converged,
+                terminationReason,
+                ...(linearSolverFailure?.failureReason ? { failureReason: linearSolverFailure.failureReason } : {}),
+                residualHistory,
+            },
+        };
+    }
+    function solveToLoadFactor(targetLoadFactor, requestedLoadFactor, cutbackDepth) {
+        const startLoadFactor = currentLoadFactor;
+        const committedStateSignatureBefore = druckerPragerStateSignature(committedStates);
+        const attempt = solveDruckerPragerStepAttempt({
+            step: loadSteps.length + 1,
+            loadFactor: targetLoadFactor,
+            requestedLoadFactor,
+            cutbackDepth,
+            startingDisplacement: displacement,
+            startingCommittedStates: committedStates,
+        });
+        attemptedStepCount += 1;
+        maxCutbackDepth = Math.max(maxCutbackDepth, cutbackDepth);
+        if (attempt.converged) {
+            adaptiveAttemptAudits.push({
+                attempt: adaptiveAttemptAudits.length + 1,
+                startLoadFactor: round(startLoadFactor, 8),
+                targetLoadFactor: round(targetLoadFactor, 8),
+                requestedLoadFactor: round(requestedLoadFactor, 8),
+                cutbackDepth,
+                accepted: true,
+                rollbackApplied: false,
+                terminationReason: attempt.step.terminationReason,
+                committedStateSignatureBefore,
+                committedStateSignatureAfter: druckerPragerStateSignature(attempt.evaluation.trialStates),
+            });
+            displacement.splice(0, displacement.length, ...attempt.displacement);
+            committedStates = attempt.evaluation.trialStates;
+            finalEvaluation = attempt.evaluation;
+            currentLoadFactor = targetLoadFactor;
+            acceptedLoadFactors.push(round(targetLoadFactor, 8));
+            loadSteps.push({
+                ...attempt.step,
+                step: loadSteps.length + 1,
+            });
+            return true;
+        }
+        adaptiveAttemptAudits.push({
+            attempt: adaptiveAttemptAudits.length + 1,
+            startLoadFactor: round(startLoadFactor, 8),
+            targetLoadFactor: round(targetLoadFactor, 8),
+            requestedLoadFactor: round(requestedLoadFactor, 8),
+            cutbackDepth,
+            accepted: false,
+            rollbackApplied: adaptiveOptions.enabled,
+            terminationReason: attempt.step.terminationReason,
+            committedStateSignatureBefore,
+            committedStateSignatureAfter: committedStateSignatureBefore,
         });
+        if (adaptiveOptions.enabled) {
+            const increment = targetLoadFactor - startLoadFactor;
+            const midpoint = startLoadFactor + increment / 2;
+            if (cutbackCount >= adaptiveOptions.maxCutbacks) {
+                adaptiveBlockerCodes.push('adaptive-load-step-max-cutbacks-exhausted');
+            }
+            else if (Math.abs(midpoint - startLoadFactor) < adaptiveOptions.minLoadFactorIncrement) {
+                adaptiveBlockerCodes.push('adaptive-load-step-min-increment-reached');
+            }
+            else if (Math.abs(midpoint - targetLoadFactor) < 1e-12) {
+                adaptiveBlockerCodes.push('adaptive-load-step-cutback-stalled');
+            }
+            else {
+                cutbackCount += 1;
+                const firstHalfAccepted = solveToLoadFactor(midpoint, requestedLoadFactor, cutbackDepth + 1);
+                if (!firstHalfAccepted)
+                    return false;
+                return solveToLoadFactor(targetLoadFactor, requestedLoadFactor, cutbackDepth + 1);
+            }
+        }
+        displacement.splice(0, displacement.length, ...attempt.displacement);
+        finalEvaluation = attempt.evaluation;
+        loadSteps.push({
+            ...attempt.step,
+            step: loadSteps.length + 1,
+        });
+        return false;
+    }
+    for (const loadFactor of loadStepFractions) {
+        const accepted = solveToLoadFactor(loadFactor, loadFactor, 0);
+        if (!accepted && adaptiveOptions.enabled)
+            break;
     }
     if (!finalEvaluation) {
         throw new Error('Plane-strain nonlinear load-step solver requires at least one load step.');
     }
+    const acceptedFinalEvaluation = finalEvaluation;
     const failedStep = loadSteps.find((step) => !step.converged);
     const status = failedStep ? 'nonconverged' : 'converged';
+    const adaptiveLoadStepping = {
+        schemaVersion: 'fem-plane-strain-dp-adaptive-load-stepping.v1',
+        enabled: adaptiveOptions.enabled,
+        strategy: adaptiveOptions.strategy,
+        requestedStepCount: loadStepFractions.length,
+        attemptedStepCount,
+        acceptedStepCount: loadSteps.filter((step) => step.converged).length,
+        cutbackCount,
+        maxCutbackDepth,
+        minLoadFactorIncrement: round(adaptiveOptions.minLoadFactorIncrement, 12),
+        requestedLoadFactors: loadStepFractions.map((factor) => round(factor, 8)),
+        acceptedLoadFactors,
+        attempts: adaptiveAttemptAudits,
+        blockerCodes: [...new Set(adaptiveBlockerCodes)],
+    };
     return {
         schemaVersion: 'fem-plane-strain-drucker-prager-result.v1',
         method: 'quad4-plane-strain-drucker-prager-modified-newton',
@@ -1939,10 +2166,10 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
             ...node,
             uxM: round(displacement[dofIndex(index, 'ux')], 12),
             uyM: round(displacement[dofIndex(index, 'uy')], 12),
-            rxnXKn: round(finalEvaluation.residual[dofIndex(index, 'ux')], 8),
-            rxnYKn: round(finalEvaluation.residual[dofIndex(index, 'uy')], 8),
+            rxnXKn: round(acceptedFinalEvaluation.residual[dofIndex(index, 'ux')], 8),
+            rxnYKn: round(acceptedFinalEvaluation.residual[dofIndex(index, 'uy')], 8),
         })),
-        elements: finalEvaluation.elements,
+        elements: acceptedFinalEvaluation.elements,
         dofCount: system.dofCount,
         freeDofCount: system.freeDofs.length,
         constrainedDofCount: system.prescribed.size,
@@ -1951,14 +2178,15 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
         globalTangent: 'elastic',
         materialIntegration: 'incremental-committed-drucker-prager-return-mapping',
         stateStorage: 'committed-gauss-point-history',
+        adaptiveLoadStepping,
         loadSteps,
-        maxFreeResidualKn: round(finalEvaluation.maxFreeResidualKn, 12),
-        residualNormRatio: round(finalEvaluation.residualNormRatio, 12),
-        reactionBalanceRatio: round(finalEvaluation.reactionBalanceRatio, 12),
-        maxYieldResidualRatio: round(finalEvaluation.maxYieldResidualRatio, 12),
-        maxEquivalentPlasticStrain: round(finalEvaluation.maxEquivalentPlasticStrain, 12),
-        maxEquivalentPlasticStrainIncrement: round(finalEvaluation.maxEquivalentPlasticStrainIncrement, 12),
-        plasticGaussPointCount: finalEvaluation.plasticGaussPointCount,
+        maxFreeResidualKn: round(acceptedFinalEvaluation.maxFreeResidualKn, 12),
+        residualNormRatio: round(acceptedFinalEvaluation.residualNormRatio, 12),
+        reactionBalanceRatio: round(acceptedFinalEvaluation.reactionBalanceRatio, 12),
+        maxYieldResidualRatio: round(acceptedFinalEvaluation.maxYieldResidualRatio, 12),
+        maxEquivalentPlasticStrain: round(acceptedFinalEvaluation.maxEquivalentPlasticStrain, 12),
+        maxEquivalentPlasticStrainIncrement: round(acceptedFinalEvaluation.maxEquivalentPlasticStrainIncrement, 12),
+        plasticGaussPointCount: acceptedFinalEvaluation.plasticGaussPointCount,
         converged: status === 'converged',
         status,
         ...(failedStep ? {
@@ -1975,6 +2203,9 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
         limitations: [
             'Benchmark-scale modified-Newton plane-strain plasticity evidence kernel only.',
             ...(failedStep ? ['Nonconverged load-step result is reported fail-closed and must not be treated as an accepted engineering solve.'] : []),
+            ...(adaptiveOptions.enabled
+                ? ['Adaptive cutback-bisection load stepping can subdivide rejected nonlinear increments with rollback audit, but it is still not an arc-length or production consistent-tangent strategy.']
+                : []),
             linearSolver === 'sparse-csr-cg'
                 ? 'Uses an experimental CSR Conjugate Gradient linear solve audit, elastic global tangent, and committed Gauss-point Drucker-Prager return mapping; no production consistent tangent, hardening calibration, staged activation, pore-pressure DOF, or route-backed result manifest is provided.'
                 : 'Uses elastic global tangent with committed Gauss-point Drucker-Prager return mapping; no production consistent tangent, production sparse solver, hardening calibration, staged activation, pore-pressure DOF, or route-backed result manifest is provided.',