@geotechcli/core 0.4.106 → 0.4.108

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

@@ -1,4 +1,5 @@
 import { DEFAULT_FEM_CONVERGENCE_POLICY } from './engineering-evidence.js';
+import { buildCsrFromTriplets, solveCsrConjugateGradient, } from './sparse-linear-algebra.js';
 const GAUSS_POINTS = [
     [-1 / Math.sqrt(3), -1 / Math.sqrt(3), 1],
     [1 / Math.sqrt(3), -1 / Math.sqrt(3), 1],
@@ -6,6 +7,8 @@ const GAUSS_POINTS = [
     [-1 / Math.sqrt(3), 1 / Math.sqrt(3), 1],
 ];
 const MAX_DENSE_DOF_COUNT = 800;
+const MAX_SPARSE_EXPERIMENTAL_DOF_COUNT = 5_000;
+const MAX_BIOT_TIME_STEP_GROWTH_RATIO = 8;
 function assertFinite(value, label) {
     if (!Number.isFinite(value))
         throw new Error(`${label} must be finite.`);
@@ -62,6 +65,26 @@ function validateConvergencePolicy(policy) {
         throw new Error('policy.minAcceptedSteps must be less than or equal to policy.maxIterations.');
     }
 }
+function validateBiotTransientStepPolicy(timeStepsSeconds, policy) {
+    if (timeStepsSeconds.length < policy.minAcceptedSteps) {
+        throw new Error(`timeStepsSeconds must include at least ${policy.minAcceptedSteps} accepted transient steps for the Biot consolidation preview.`);
+    }
+    let previousTimeSeconds = 0;
+    let previousDeltaTimeSeconds;
+    for (const [index, timeSeconds] of timeStepsSeconds.entries()) {
+        assertFinitePositive(timeSeconds, `timeStepsSeconds.${index}`);
+        if (timeSeconds <= previousTimeSeconds) {
+            throw new Error(`timeStepsSeconds.${index} must be strictly increasing.`);
+        }
+        const deltaTimeSeconds = timeSeconds - previousTimeSeconds;
+        if (previousDeltaTimeSeconds != null &&
+            deltaTimeSeconds / previousDeltaTimeSeconds > MAX_BIOT_TIME_STEP_GROWTH_RATIO) {
+            throw new Error(`timeStepsSeconds.${index} step growth ratio must not exceed ${MAX_BIOT_TIME_STEP_GROWTH_RATIO} for the Biot consolidation preview.`);
+        }
+        previousTimeSeconds = timeSeconds;
+        previousDeltaTimeSeconds = deltaTimeSeconds;
+    }
+}
 function round(value, digits = 10) {
     const factor = 10 ** digits;
     return Math.round(value * factor) / factor;
@@ -263,6 +286,9 @@ function matVec(matrix, vector) {
 function dot(a, b) {
     return a.reduce((sum, value, index) => sum + value * b[index], 0);
 }
+function vectorNorm(values) {
+    return Math.sqrt(values.reduce((sum, value) => sum + value * value, 0));
+}
 function elementMatrices(input) {
     const { nodes, material, thicknessM } = input;
     const d = planeStrainD(material);
@@ -654,6 +680,7 @@ export function runPlaneStrainBiotConsolidation(model) {
     assertUniqueIds(model.elements, 'element');
     const policy = model.policy ?? DEFAULT_FEM_CONVERGENCE_POLICY;
     validateConvergencePolicy(policy);
+    validateBiotTransientStepPolicy(model.timeStepsSeconds, policy);
     const nodeIndexById = new Map(model.nodes.map((node, index) => [node.id, index]));
     const materialById = new Map(model.materials.map((material) => [material.id, material]));
     const displacementDofCount = model.nodes.length * 2;
@@ -661,14 +688,6 @@ export function runPlaneStrainBiotConsolidation(model) {
     if (displacementDofCount + porePressureDofCount > MAX_DENSE_DOF_COUNT) {
         throw new Error(`Plane-strain Biot consolidation dense assembly is capped at ${MAX_DENSE_DOF_COUNT} coupled DOFs for benchmark-scale evidence runs.`);
     }
-    let previousTimeSeconds = 0;
-    for (const [index, timeSeconds] of model.timeStepsSeconds.entries()) {
-        assertFinitePositive(timeSeconds, `timeStepsSeconds.${index}`);
-        if (timeSeconds <= previousTimeSeconds) {
-            throw new Error(`timeStepsSeconds.${index} must be strictly increasing.`);
-        }
-        previousTimeSeconds = timeSeconds;
-    }
     for (const node of model.nodes) {
         assertFinite(node.xM, `node ${node.id} xM`);
         assertFinite(node.yM, `node ${node.id} yM`);
@@ -703,6 +722,9 @@ export function runPlaneStrainBiotConsolidation(model) {
             throw new Error(`Unknown Biot nodal flux node: ${flux.nodeId}.`);
         const flowM3PerS = flux.flowM3PerS ?? 0;
         assertFinite(flowM3PerS, `nodal flux ${flux.nodeId}.flowM3PerS`);
+        if (flowM3PerS < 0) {
+            throw new Error(`nodal flux ${flux.nodeId}.flowM3PerS must be non-negative; extraction-driven suction is unsupported by this saturated excess-pressure Biot evidence kernel.`);
+        }
         fluxes[nodeIndex] += flowM3PerS;
     }
     const elementGaussCache = [];
@@ -828,6 +850,11 @@ export function runPlaneStrainBiotConsolidation(model) {
         displacement[index] = value;
     for (const [index, value] of prescribedPressures)
         porePressure[index] = value;
+    const pressureUpperBoundKpa = Math.max(initialPorePressureKpa, ...Array.from(prescribedPressures.values()));
+    const averagePressure = (dofs) => dofs.length > 0
+        ? dofs.reduce((sum, index) => sum + porePressure[index], 0) / dofs.length
+        : 0;
+    const initialAverageFreePorePressureKpa = averagePressure(freePressureDofs);
     let previousDisplacement = [...displacement];
     let previousPorePressure = [...porePressure];
     let lastMechanicalResidual = new Array(displacementDofCount).fill(0);
@@ -846,6 +873,14 @@ export function runPlaneStrainBiotConsolidation(model) {
         couplingRateSumM3PerS: 0,
         darcyFlowRateSumM3PerS: 0,
     };
+    let lastPressureDiagnostics = {
+        averagePorePressureKpa: round(porePressure.reduce((sum, value) => sum + value, 0) / porePressure.length, 8),
+        averageFreePorePressureKpa: round(initialAverageFreePorePressureKpa, 8),
+        porePressureDissipationRatio: 0,
+        maxPorePressureChangeKpa: 0,
+        maxPorePressureChangeRateKpaPerS: 0,
+        pressureOvershootKpa: 0,
+    };
     let lastMinPorePressureKpa = Math.min(...porePressure);
     let lastMaxPorePressureKpa = Math.max(...porePressure);
     const timeSteps = [];
@@ -966,6 +1001,23 @@ export function runPlaneStrainBiotConsolidation(model) {
         const massBalanceErrorRatio = freePressureResidualSum / pressureScale;
         const minPorePressureKpa = Math.min(...porePressure);
         const maxPorePressureKpa = Math.max(...porePressure);
+        const pressureOvershootKpa = Math.max(0, maxPorePressureKpa - pressureUpperBoundKpa);
+        if (pressureOvershootKpa > 1e-6) {
+            throw new Error(`Plane-strain Biot step ${stepIndex + 1} pore pressure exceeded the initial/prescribed pressure envelope by ${pressureOvershootKpa} kPa.`);
+        }
+        const averagePorePressureKpa = porePressure.reduce((sum, value) => sum + value, 0) / porePressure.length;
+        const averageFreePorePressureKpa = averagePressure(freePressureDofs);
+        const dissipationReferenceKpa = Math.max(initialAverageFreePorePressureKpa, 1e-12);
+        const porePressureDissipationRatio = Math.min(1, Math.max(0, (initialAverageFreePorePressureKpa - averageFreePorePressureKpa) / dissipationReferenceKpa));
+        const maxPorePressureChangeKpa = Math.max(...porePressure.map((value, index) => Math.abs(value - previousPorePressure[index])));
+        const pressureDiagnostics = {
+            averagePorePressureKpa: round(averagePorePressureKpa, 8),
+            averageFreePorePressureKpa: round(averageFreePorePressureKpa, 8),
+            porePressureDissipationRatio: round(porePressureDissipationRatio, 12),
+            maxPorePressureChangeKpa: round(maxPorePressureChangeKpa, 8),
+            maxPorePressureChangeRateKpaPerS: Number((maxPorePressureChangeKpa / deltaTimeSeconds).toExponential(12)),
+            pressureOvershootKpa: round(pressureOvershootKpa, 8),
+        };
         const maxVerticalSettlementM = Math.max(0, -Math.min(...model.nodes.map((_, index) => displacement[dofIndex(index, 'uy')])));
         const converged = residualNormRatio <= policy.forceBalanceTolerance &&
             massBalanceErrorRatio <= policy.porePressureMassBalanceTolerance;
@@ -979,6 +1031,7 @@ export function runPlaneStrainBiotConsolidation(model) {
             freePorePressureResidualL1M3PerS: Number(freePressureResidualSum.toExponential(12)),
             massBalanceErrorRatio: round(massBalanceErrorRatio, 12),
             pressureAudit,
+            pressureDiagnostics,
             minPorePressureKpa: round(minPorePressureKpa, 8),
             maxPorePressureKpa: round(maxPorePressureKpa, 8),
             maxVerticalSettlementM: round(maxVerticalSettlementM, 12),
@@ -994,6 +1047,7 @@ export function runPlaneStrainBiotConsolidation(model) {
         lastMaxFreePorePressureResidualM3PerS = maxFreePorePressureResidualM3PerS;
         lastFreePorePressureResidualL1M3PerS = freePressureResidualSum;
         lastPressureAudit = pressureAudit;
+        lastPressureDiagnostics = pressureDiagnostics;
         lastMinPorePressureKpa = minPorePressureKpa;
         lastMaxPorePressureKpa = maxPorePressureKpa;
     }
@@ -1063,6 +1117,8 @@ export function runPlaneStrainBiotConsolidation(model) {
             totalStressRelation: 'sigma_total_xx_yy = sigma_effective_xx_yy - alpha_B * p; shear unchanged',
             darcyFluxRelation: 'q = -k/gamma_water * grad(p)',
             storageConvention: 'specificStorage1PerM is head-based; pressure storage uses Ss / gamma_water',
+            transientStepPolicy: 'fixed backward-Euler grid requires minAcceptedSteps and bounded step-growth ratio',
+            maxTimeStepGrowthRatio: MAX_BIOT_TIME_STEP_GROWTH_RATIO,
             gammaWaterKpaPerM: round(gammaWaterKpaPerM, 8),
         },
         nodes: model.nodes.map((node, index) => ({
@@ -1089,6 +1145,7 @@ export function runPlaneStrainBiotConsolidation(model) {
         maxFreePorePressureResidualM3PerS: Number(lastMaxFreePorePressureResidualM3PerS.toExponential(12)),
         freePorePressureResidualL1M3PerS: Number(lastFreePorePressureResidualL1M3PerS.toExponential(12)),
         pressureAudit: lastPressureAudit,
+        pressureDiagnostics: lastPressureDiagnostics,
         massBalanceErrorRatio: round(lastMassBalanceErrorRatio, 12),
         minPorePressureKpa: round(lastMinPorePressureKpa, 8),
         maxPorePressureKpa: round(lastMaxPorePressureKpa, 8),
@@ -1292,7 +1349,7 @@ export function runPlaneStrainQuad4Assembly(model) {
         policy,
     };
 }
-function assemblePlaneStrainSystem(model) {
+function assemblePlaneStrainSystem(model, options = {}) {
     if (model.schemaVersion !== 'fem-plane-strain-model.v1') {
         throw new Error('Only fem-plane-strain-model.v1 is supported.');
     }
@@ -1318,10 +1375,17 @@ function assemblePlaneStrainSystem(model) {
     const nodeIndexById = new Map(model.nodes.map((node, index) => [node.id, index]));
     const materialById = new Map(model.materials.map((material) => [material.id, material]));
     const dofCount = model.nodes.length * 2;
-    if (dofCount > MAX_DENSE_DOF_COUNT) {
+    const storage = options.storage ?? 'dense-and-triplets';
+    if (storage === 'dense-and-triplets' && dofCount > MAX_DENSE_DOF_COUNT) {
         throw new Error(`Plane-strain dense assembly is capped at ${MAX_DENSE_DOF_COUNT} DOFs for benchmark-scale evidence runs.`);
     }
-    const stiffness = Array.from({ length: dofCount }, () => new Array(dofCount).fill(0));
+    if (storage === 'triplets-only' && dofCount > MAX_SPARSE_EXPERIMENTAL_DOF_COUNT) {
+        throw new Error(`Plane-strain sparse experimental assembly is capped at ${MAX_SPARSE_EXPERIMENTAL_DOF_COUNT} DOFs until production solver benchmarks are approved.`);
+    }
+    const stiffness = storage === 'dense-and-triplets'
+        ? Array.from({ length: dofCount }, () => new Array(dofCount).fill(0))
+        : undefined;
+    const stiffnessTriplets = [];
     const loads = new Array(dofCount).fill(0);
     for (const node of model.nodes) {
         assertFinite(node.xM, `node ${node.id} xM`);
@@ -1370,7 +1434,12 @@ function assemblePlaneStrainSystem(model) {
         const globalDofs = nodeIndices.flatMap((index) => [dofIndex(index, 'ux'), dofIndex(index, 'uy')]);
         for (let localRow = 0; localRow < 8; localRow += 1) {
             for (let localCol = 0; localCol < 8; localCol += 1) {
-                stiffness[globalDofs[localRow]][globalDofs[localCol]] += elementData.stiffness[localRow][localCol];
+                const row = globalDofs[localRow];
+                const col = globalDofs[localCol];
+                const value = elementData.stiffness[localRow][localCol];
+                stiffnessTriplets.push({ row, col, value });
+                if (stiffness)
+                    stiffness[row][col] += value;
             }
         }
         elementGaussCache.push({
@@ -1411,6 +1480,7 @@ function assemblePlaneStrainSystem(model) {
         policy,
         materialById,
         stiffness,
+        stiffnessTriplets,
         loads,
         prescribed,
         freeDofs,
@@ -1528,10 +1598,131 @@ function normalizeLoadStepFractions(loadStepFractions) {
     }
     return fractions;
 }
+function isDruckerPragerStepConverged(evaluation, policy) {
+    return evaluation.residualNormRatio <= policy.forceBalanceTolerance &&
+        evaluation.maxYieldResidualRatio <= policy.residualTolerance;
+}
+function druckerPragerResidualHistoryEntry(iteration, evaluation, policy) {
+    return {
+        iteration,
+        maxFreeResidualKn: round(evaluation.maxFreeResidualKn, 12),
+        residualNormRatio: round(evaluation.residualNormRatio, 12),
+        forceBalanceTolerance: policy.forceBalanceTolerance,
+        reactionBalanceRatio: round(evaluation.reactionBalanceRatio, 12),
+        maxYieldResidualRatio: round(evaluation.maxYieldResidualRatio, 12),
+        yieldResidualTolerance: policy.residualTolerance,
+        converged: isDruckerPragerStepConverged(evaluation, policy),
+    };
+}
+function druckerPragerTerminationReason(evaluation, policy, converged, iterations, linearSolverFailure) {
+    if (converged)
+        return 'converged';
+    if (linearSolverFailure)
+        return 'linear_solver_nonconverged';
+    if (iterations >= policy.maxIterations)
+        return 'max_iterations';
+    if (evaluation.residualNormRatio > policy.forceBalanceTolerance)
+        return 'force_residual_exceeded';
+    return 'yield_residual_exceeded';
+}
+function normalizeLinearSolverKind(solver) {
+    const resolved = solver ?? 'dense-gaussian';
+    if (resolved !== 'dense-gaussian' && resolved !== 'sparse-csr-cg') {
+        throw new Error('linearSolver must be dense-gaussian or sparse-csr-cg.');
+    }
+    return resolved;
+}
+function denseNonzeroCount(matrix) {
+    return matrix.reduce((count, row) => count + row.filter((value) => Math.abs(value) > 0).length, 0);
+}
+function buildReducedCsr(input) {
+    const freeIndexByDof = new Map(input.freeDofs.map((dof, index) => [dof, index]));
+    const reducedTriplets = input.triplets.flatMap((entry) => {
+        const row = freeIndexByDof.get(entry.row);
+        const col = freeIndexByDof.get(entry.col);
+        return row != null && col != null ? [{ row, col, value: entry.value }] : [];
+    });
+    return buildCsrFromTriplets({
+        rowCount: input.freeDofs.length,
+        colCount: input.freeDofs.length,
+        triplets: reducedTriplets,
+        dropTolerance: 0,
+    });
+}
+function solveDenseDruckerPragerCorrection(input) {
+    const correction = solveDenseLinearSystem(input.reducedK, [...input.rhs]);
+    const solvedRhs = matVec(input.reducedK, correction);
+    const residual = solvedRhs.map((value, index) => value - input.rhs[index]);
+    const rhsNorm = Math.max(vectorNorm(input.rhs), 1);
+    const finalResidualNorm = vectorNorm(residual);
+    const correctionNorm = vectorNorm(correction);
+    return {
+        correction,
+        audit: {
+            schemaVersion: 'fem-plane-strain-linear-solver-audit.v1',
+            solver: 'dense-gaussian',
+            matrixDofCount: input.rhs.length,
+            nonzeroCount: denseNonzeroCount(input.reducedK),
+            iterations: input.rhs.length,
+            tolerance: input.tolerance,
+            maxIterations: input.maxIterations,
+            initialResidualNorm: vectorNorm(input.rhs),
+            finalResidualNorm,
+            residualNormRatio: finalResidualNorm / rhsNorm,
+            correctionNormM: correctionNorm,
+            correctionNormRatio: correctionNorm / Math.max(vectorNorm(input.currentFreeDisplacement), 1e-12),
+            converged: true,
+        },
+    };
+}
+function solveSparseDruckerPragerCorrection(input) {
+    const solved = solveCsrConjugateGradient(input.reducedK, input.rhs, {
+        tolerance: input.tolerance,
+        maxIterations: input.maxIterations,
+        preconditioner: 'jacobi',
+    });
+    const correctionNorm = vectorNorm(solved.solution);
+    return {
+        correction: solved.solution,
+        audit: {
+            schemaVersion: 'fem-plane-strain-linear-solver-audit.v1',
+            solver: 'sparse-csr-cg',
+            matrixDofCount: input.rhs.length,
+            nonzeroCount: input.reducedK.nonzeroCount,
+            iterations: solved.iterations,
+            tolerance: solved.tolerance,
+            maxIterations: solved.maxIterations,
+            initialResidualNorm: solved.initialResidualNorm,
+            finalResidualNorm: solved.finalResidualNorm,
+            residualNormRatio: solved.residualNormRatio,
+            correctionNormM: correctionNorm,
+            correctionNormRatio: correctionNorm / Math.max(vectorNorm(input.currentFreeDisplacement), 1e-12),
+            converged: solved.converged,
+            ...(solved.failureReason ? { failureReason: solved.failureReason } : {}),
+        },
+    };
+}
 export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
-    const system = assemblePlaneStrainSystem(model);
+    const linearSolver = normalizeLinearSolverKind(options.linearSolver);
+    const system = assemblePlaneStrainSystem(model, {
+        storage: linearSolver === 'sparse-csr-cg' ? 'triplets-only' : 'dense-and-triplets',
+    });
     const loadStepFractions = normalizeLoadStepFractions(options.loadStepFractions);
-    const reducedK = system.freeDofs.map((row) => system.freeDofs.map((col) => system.stiffness[row][col]));
+    const linearSolverTolerance = options.linearSolverTolerance ?? Math.min(1e-10, system.policy.forceBalanceTolerance / 10);
+    if (!Number.isFinite(linearSolverTolerance) || linearSolverTolerance <= 0) {
+        throw new Error('linearSolverTolerance must be a finite positive number.');
+    }
+    const linearSolverMaxIterations = options.linearSolverMaxIterations ?? Math.max(100, system.freeDofs.length * 10);
+    assertPositiveInteger(linearSolverMaxIterations, 'linearSolverMaxIterations');
+    const reducedDenseK = linearSolver === 'dense-gaussian'
+        ? system.freeDofs.map((row) => system.freeDofs.map((col) => system.stiffness[row][col]))
+        : undefined;
+    const reducedSparseK = linearSolver === 'sparse-csr-cg' && system.freeDofs.length > 0
+        ? buildReducedCsr({
+            freeDofs: system.freeDofs,
+            triplets: system.stiffnessTriplets,
+        })
+        : undefined;
     const displacement = new Array(system.dofCount).fill(0);
     let finalEvaluation;
     const loadSteps = [];
@@ -1540,24 +1731,51 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
             displacement[index] = value * loadFactor;
         let evaluation = evaluatePlaneStrainDruckerPragerState({ system, displacement, loadFactor });
         let iterations = 0;
-        let converged = evaluation.residualNormRatio <= system.policy.forceBalanceTolerance &&
-            evaluation.maxYieldResidualRatio <= system.policy.residualTolerance;
+        let converged = isDruckerPragerStepConverged(evaluation, system.policy);
+        const residualHistory = [
+            druckerPragerResidualHistoryEntry(iterations, evaluation, system.policy),
+        ];
+        const linearSolverAudits = [];
+        let linearSolverFailure;
         while (!converged && iterations < system.policy.maxIterations) {
             iterations += 1;
             if (system.freeDofs.length === 0)
                 break;
             const correctionRhs = system.freeDofs.map((index) => -evaluation.residual[index]);
-            const correction = solveDenseLinearSystem(reducedK, correctionRhs);
+            const currentFreeDisplacement = system.freeDofs.map((index) => displacement[index]);
+            const solved = linearSolver === 'sparse-csr-cg'
+                ? solveSparseDruckerPragerCorrection({
+                    reducedK: reducedSparseK,
+                    rhs: correctionRhs,
+                    currentFreeDisplacement,
+                    tolerance: linearSolverTolerance,
+                    maxIterations: linearSolverMaxIterations,
+                })
+                : solveDenseDruckerPragerCorrection({
+                    reducedK: reducedDenseK,
+                    rhs: correctionRhs,
+                    currentFreeDisplacement,
+                    tolerance: linearSolverTolerance,
+                    maxIterations: linearSolverMaxIterations,
+                });
+            linearSolverAudits.push(solved.audit);
+            if (!solved.audit.converged) {
+                linearSolverFailure = solved.audit;
+                break;
+            }
+            const correction = solved.correction;
             for (const [correctionIndex, dof] of system.freeDofs.entries()) {
                 displacement[dof] += correction[correctionIndex];
             }
             for (const [index, value] of system.prescribed)
                 displacement[index] = value * loadFactor;
             evaluation = evaluatePlaneStrainDruckerPragerState({ system, displacement, loadFactor });
-            converged = evaluation.residualNormRatio <= system.policy.forceBalanceTolerance &&
-                evaluation.maxYieldResidualRatio <= system.policy.residualTolerance;
+            converged = isDruckerPragerStepConverged(evaluation, system.policy);
+            residualHistory.push(druckerPragerResidualHistoryEntry(iterations, evaluation, system.policy));
         }
         finalEvaluation = evaluation;
+        const terminationReason = druckerPragerTerminationReason(evaluation, system.policy, converged, iterations, linearSolverFailure);
+        const lastLinearAudit = linearSolverAudits.at(-1);
         loadSteps.push({
             step: stepIndex + 1,
             loadFactor: round(loadFactor, 8),
@@ -1568,12 +1786,22 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
             maxYieldResidualRatio: round(evaluation.maxYieldResidualRatio, 12),
             maxEquivalentPlasticStrain: round(evaluation.maxEquivalentPlasticStrain, 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,
         });
     }
     if (!finalEvaluation) {
         throw new Error('Plane-strain nonlinear load-step solver requires at least one load step.');
     }
+    const failedStep = loadSteps.find((step) => !step.converged);
+    const status = failedStep ? 'nonconverged' : 'converged';
     return {
         schemaVersion: 'fem-plane-strain-drucker-prager-result.v1',
         method: 'quad4-plane-strain-drucker-prager-modified-newton',
@@ -1588,6 +1816,10 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
         dofCount: system.dofCount,
         freeDofCount: system.freeDofs.length,
         constrainedDofCount: system.prescribed.size,
+        linearSolver,
+        nonlinearAlgorithm: 'modified-newton',
+        globalTangent: 'elastic',
+        materialIntegration: 'total-strain-drucker-prager-projection',
         loadSteps,
         maxFreeResidualKn: round(finalEvaluation.maxFreeResidualKn, 12),
         residualNormRatio: round(finalEvaluation.residualNormRatio, 12),
@@ -1595,11 +1827,25 @@ export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
         maxYieldResidualRatio: round(finalEvaluation.maxYieldResidualRatio, 12),
         maxEquivalentPlasticStrain: round(finalEvaluation.maxEquivalentPlasticStrain, 12),
         plasticGaussPointCount: finalEvaluation.plasticGaussPointCount,
-        converged: loadSteps.every((step) => step.converged),
+        converged: status === 'converged',
+        status,
+        ...(failedStep ? {
+            failure: {
+                step: failedStep.step,
+                loadFactor: failedStep.loadFactor,
+                terminationReason: failedStep.terminationReason,
+                residualNormRatio: failedStep.residualNormRatio,
+                maxYieldResidualRatio: failedStep.maxYieldResidualRatio,
+                message: `Plane-strain Drucker-Prager load step ${failedStep.step} did not satisfy the configured convergence policy.`,
+            },
+        } : {}),
         policy: system.policy,
         limitations: [
             'Benchmark-scale modified-Newton plane-strain plasticity evidence kernel only.',
-            'Uses elastic global tangent with Gauss-point Drucker-Prager stress projection; no production consistent tangent, sparse solver, hardening calibration, staged activation, pore-pressure DOF, or route-backed result manifest is provided.',
+            ...(failedStep ? ['Nonconverged load-step result is reported fail-closed and must not be treated as an accepted engineering solve.'] : []),
+            linearSolver === 'sparse-csr-cg'
+                ? 'Uses an experimental CSR Conjugate Gradient linear solve audit, elastic global tangent, and Gauss-point Drucker-Prager stress projection; no production consistent tangent, hardening calibration, staged activation, pore-pressure DOF, or route-backed result manifest is provided.'
+                : 'Uses elastic global tangent with Gauss-point Drucker-Prager stress projection; no production consistent tangent, production sparse solver, hardening calibration, staged activation, pore-pressure DOF, or route-backed result manifest is provided.',
             'Use for deterministic evidence and regression tests only until independent published/commercial benchmark comparison and licensed production approval gates are complete.',
         ],
     };