@geotechcli/core 0.4.98 → 0.4.100

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

@@ -76,6 +76,128 @@ function planeStrainD(material) {
         [0, 0, factor * (1 - 2 * nu) / 2],
     ];
 }
+function planeStrainSigmaZ(material, strain) {
+    const e = material.elasticModulusKpa;
+    const nu = material.poissonRatio;
+    const factor = e / ((1 + nu) * (1 - 2 * nu));
+    return factor * nu * (strain[0] + strain[1]);
+}
+function elasticModuli(material) {
+    return {
+        bulkModulusKpa: material.elasticModulusKpa / (3 * (1 - 2 * material.poissonRatio)),
+        shearModulusKpa: material.elasticModulusKpa / (2 * (1 + material.poissonRatio)),
+    };
+}
+function degToRad(degrees) {
+    return (degrees * Math.PI) / 180;
+}
+function druckerPragerRhoFromAngle(angleDeg) {
+    if (!Number.isFinite(angleDeg) || angleDeg < 0 || angleDeg >= 50) {
+        throw new Error('friction and dilation angles must be finite and between 0 and 50 degrees.');
+    }
+    const angle = degToRad(angleDeg);
+    const sinAngle = Math.sin(angle);
+    if (sinAngle === 0)
+        return 0;
+    return (2 * Math.SQRT2 * sinAngle) / (Math.sqrt(3) * (3 - sinAngle));
+}
+function druckerPragerParameters(material) {
+    const frictionAngleDeg = material.frictionAngleDeg ?? 30;
+    const cohesionKpa = material.cohesionKpa ?? 0;
+    const dilationAngleDeg = material.dilationAngleDeg ?? frictionAngleDeg;
+    if (!Number.isFinite(frictionAngleDeg) || frictionAngleDeg <= 0 || frictionAngleDeg >= 50) {
+        throw new Error(`material ${material.id} frictionAngleDeg must be finite and between 0 and 50 degrees.`);
+    }
+    assertFiniteNonNegative(cohesionKpa, `material ${material.id} cohesionKpa`);
+    assertFiniteNonNegative(material.hardeningModulusKpa ?? 0, `material ${material.id} hardeningModulusKpa`);
+    const rho = druckerPragerRhoFromAngle(frictionAngleDeg);
+    const rhoBar = Math.min(rho, druckerPragerRhoFromAngle(dilationAngleDeg));
+    const phi = degToRad(frictionAngleDeg);
+    const sinPhi = Math.sin(phi);
+    const cohesionContributionToQ = (2 * cohesionKpa * Math.cos(phi)) / (1 - sinPhi);
+    const deviatoricNormFactor = Math.sqrt(2 / 3);
+    return {
+        rho,
+        rhoBar,
+        compressionInterceptKpa: cohesionContributionToQ * (deviatoricNormFactor - rho),
+    };
+}
+function principalCompressionFromPlaneStress(stress, sigmaZKpa) {
+    const a = -stress[0];
+    const c = -stress[1];
+    const b = -stress[2];
+    const mean = (a + c) / 2;
+    const radius = Math.hypot((a - c) / 2, b);
+    const angleRad = 0.5 * Math.atan2(2 * b, a - c);
+    return {
+        values: [mean + radius, mean - radius, -sigmaZKpa],
+        angleRad,
+    };
+}
+function planeStressFromPrincipalCompression(values, angleRad) {
+    const [p1, p2, p3] = values;
+    const c = Math.cos(angleRad);
+    const s = Math.sin(angleRad);
+    const compressionX = p1 * c * c + p2 * s * s;
+    const compressionY = p1 * s * s + p2 * c * c;
+    const compressionXY = (p1 - p2) * s * c;
+    return {
+        stress: [-compressionX, -compressionY, -compressionXY],
+        sigmaZKpa: -p3,
+    };
+}
+function deviatoricNorm(values) {
+    const mean = (values[0] + values[1] + values[2]) / 3;
+    return Math.hypot(values[0] - mean, values[1] - mean, values[2] - mean);
+}
+function projectDruckerPragerStress(input) {
+    const { material, strain } = input;
+    const params = druckerPragerParameters(material);
+    const principal = principalCompressionFromPlaneStress(input.stress, input.sigmaZKpa);
+    const principalStress = principal.values;
+    const trace = principalStress[0] + principalStress[1] + principalStress[2];
+    const mean = trace / 3;
+    const q = deviatoricNorm(principalStress);
+    const intercept = params.compressionInterceptKpa;
+    const yieldValue = q - params.rho * trace - intercept;
+    const yieldScale = Math.max(q, Math.abs(params.rho * trace), Math.abs(intercept), 1);
+    if (yieldValue <= 0 || Math.abs(yieldValue) / yieldScale <= input.policy.residualTolerance) {
+        return {
+            strain,
+            stressKpa: input.stress,
+            outOfPlaneStressKpa: input.sigmaZKpa,
+            compressionPositivePrincipalStressKpa: principalStress,
+            yieldValueKpa: yieldValue,
+            yieldResidualRatio: Math.max(0, yieldValue) / yieldScale,
+            plasticMultiplier: 0,
+            equivalentPlasticStrain: 0,
+            state: 'elastic',
+        };
+    }
+    const targetQ = Math.max(0, params.rho * trace + intercept);
+    const scale = q > 0 ? targetQ / q : 0;
+    const correctedPrincipal = principalStress.map((value) => mean + (value - mean) * scale);
+    const corrected = planeStressFromPrincipalCompression(correctedPrincipal, principal.angleRad);
+    const correctedQ = deviatoricNorm(correctedPrincipal);
+    const correctedYieldValue = correctedQ - params.rho * trace - intercept;
+    const correctedScale = Math.max(correctedQ, Math.abs(params.rho * trace), Math.abs(intercept), 1);
+    const moduli = elasticModuli(material);
+    const denominator = 2 * moduli.shearModulusKpa +
+        9 * moduli.bulkModulusKpa * params.rho * params.rhoBar +
+        (material.hardeningModulusKpa ?? 0);
+    const plasticMultiplier = Math.max(0, yieldValue / Math.max(denominator, 1e-12));
+    return {
+        strain,
+        stressKpa: corrected.stress,
+        outOfPlaneStressKpa: corrected.sigmaZKpa,
+        compressionPositivePrincipalStressKpa: correctedPrincipal,
+        yieldValueKpa: correctedYieldValue,
+        yieldResidualRatio: Math.abs(correctedYieldValue) / correctedScale,
+        plasticMultiplier,
+        equivalentPlasticStrain: plasticMultiplier,
+        state: 'plastic',
+    };
+}
 function shapeDerivativesNatural(xi, eta) {
     return [
         [-(1 - eta) / 4, -(1 - xi) / 4],
@@ -84,6 +206,14 @@ function shapeDerivativesNatural(xi, eta) {
         [-(1 + eta) / 4, (1 - xi) / 4],
     ];
 }
+function shapeFunctions(xi, eta) {
+    return [
+        ((1 - xi) * (1 - eta)) / 4,
+        ((1 + xi) * (1 - eta)) / 4,
+        ((1 + xi) * (1 + eta)) / 4,
+        ((1 - xi) * (1 + eta)) / 4,
+    ];
+}
 function solveDenseLinearSystem(matrix, rhs) {
     const n = rhs.length;
     const a = matrix.map((row, index) => [...row, rhs[index]]);
@@ -173,6 +303,73 @@ function elementMatrices(input) {
     }
     return { stiffness: k, areaM2, gauss };
 }
+function validateHydraulicMaterial(material) {
+    const kxMPerS = material.hydraulicConductivityXMPerS;
+    if (kxMPerS == null) {
+        throw new Error(`material ${material.id} hydraulicConductivityXMPerS is required for plane-strain seepage.`);
+    }
+    assertFinitePositive(kxMPerS, `material ${material.id} hydraulicConductivityXMPerS`);
+    const kyMPerS = material.hydraulicConductivityYMPerS ?? kxMPerS;
+    assertFinitePositive(kyMPerS, `material ${material.id} hydraulicConductivityYMPerS`);
+    const biotCoefficient = material.biotCoefficient ?? 1;
+    if (!Number.isFinite(biotCoefficient) || biotCoefficient < 0 || biotCoefficient > 1) {
+        throw new Error(`material ${material.id} biotCoefficient must be finite and between 0 and 1.`);
+    }
+    return { kxMPerS, kyMPerS, biotCoefficient };
+}
+function hydraulicElementMatrices(input) {
+    const { nodes, material, thicknessM } = input;
+    const { kxMPerS, kyMPerS, biotCoefficient } = validateHydraulicMaterial(material);
+    const conductivity = Array.from({ length: 4 }, () => new Array(4).fill(0));
+    const gauss = [];
+    let areaM2 = 0;
+    for (const [xi, eta, weight] of GAUSS_POINTS) {
+        const derivatives = shapeDerivativesNatural(xi, eta);
+        let j11 = 0;
+        let j12 = 0;
+        let j21 = 0;
+        let j22 = 0;
+        for (let i = 0; i < 4; i += 1) {
+            j11 += derivatives[i][0] * nodes[i].xM;
+            j12 += derivatives[i][0] * nodes[i].yM;
+            j21 += derivatives[i][1] * nodes[i].xM;
+            j22 += derivatives[i][1] * nodes[i].yM;
+        }
+        const detJ = j11 * j22 - j12 * j21;
+        if (!Number.isFinite(detJ) || detJ <= 0) {
+            throw new Error('Plane-strain seepage quad4 element has non-positive Jacobian; check node order and geometry.');
+        }
+        const invJ = [
+            [j22 / detJ, -j12 / detJ],
+            [-j21 / detJ, j11 / detJ],
+        ];
+        const dNdx = [];
+        const dNdy = [];
+        for (let i = 0; i < 4; i += 1) {
+            dNdx.push(invJ[0][0] * derivatives[i][0] + invJ[0][1] * derivatives[i][1]);
+            dNdy.push(invJ[1][0] * derivatives[i][0] + invJ[1][1] * derivatives[i][1]);
+        }
+        for (let row = 0; row < 4; row += 1) {
+            for (let col = 0; col < 4; col += 1) {
+                conductivity[row][col] += (dNdx[row] * kxMPerS * dNdx[col] +
+                    dNdy[row] * kyMPerS * dNdy[col]) * detJ * weight * thicknessM;
+            }
+        }
+        areaM2 += detJ * weight;
+        gauss.push({
+            xi,
+            eta,
+            detJ,
+            shape: shapeFunctions(xi, eta),
+            dNdx,
+            dNdy,
+            kxMPerS,
+            kyMPerS,
+            biotCoefficient,
+        });
+    }
+    return { conductivity, areaM2, gauss };
+}
 export function buildPlaneStrainRectangularMesh(input) {
     assertFinitePositive(input.widthM, 'widthM');
     assertFinitePositive(input.heightM, 'heightM');
@@ -207,6 +404,206 @@ export function buildPlaneStrainRectangularMesh(input) {
     }
     return { nodes, elements };
 }
+export function runPlaneStrainSteadySeepage(model) {
+    if (model.schemaVersion !== 'fem-plane-strain-seepage-model.v1') {
+        throw new Error('Only fem-plane-strain-seepage-model.v1 is supported.');
+    }
+    assertArray(model.nodes, 'nodes');
+    assertArray(model.elements, 'elements');
+    assertArray(model.materials, 'materials');
+    assertArray(model.headBoundaryConditions, 'headBoundaryConditions');
+    if (model.nodes.length < 4)
+        throw new Error('Plane-strain seepage model requires at least four nodes.');
+    if (model.elements.length < 1)
+        throw new Error('Plane-strain seepage model requires at least one element.');
+    if (model.materials.length < 1)
+        throw new Error('Plane-strain seepage model requires at least one material.');
+    if (model.defaultThicknessM != null)
+        assertFinitePositive(model.defaultThicknessM, 'defaultThicknessM');
+    if (model.nodalFluxes != null)
+        assertArray(model.nodalFluxes, 'nodalFluxes');
+    const gammaWaterKpaPerM = model.gammaWaterKpaPerM ?? 9.81;
+    assertFinitePositive(gammaWaterKpaPerM, 'gammaWaterKpaPerM');
+    assertUniqueIds(model.nodes, 'node');
+    assertUniqueIds(model.materials, 'material');
+    assertUniqueIds(model.elements, 'element');
+    const policy = model.policy ?? DEFAULT_FEM_CONVERGENCE_POLICY;
+    validateConvergencePolicy(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 headDofCount = model.nodes.length;
+    if (headDofCount > MAX_DENSE_DOF_COUNT) {
+        throw new Error(`Plane-strain seepage dense assembly is capped at ${MAX_DENSE_DOF_COUNT} head DOFs for benchmark-scale evidence runs.`);
+    }
+    for (const node of model.nodes) {
+        assertFinite(node.xM, `node ${node.id} xM`);
+        assertFinite(node.yM, `node ${node.id} yM`);
+    }
+    for (const material of model.materials) {
+        validateHydraulicMaterial(material);
+    }
+    const conductivity = Array.from({ length: headDofCount }, () => new Array(headDofCount).fill(0));
+    const loads = new Array(headDofCount).fill(0);
+    for (const flux of model.nodalFluxes ?? []) {
+        const nodeIndex = nodeIndexById.get(flux.nodeId);
+        if (nodeIndex == null)
+            throw new Error(`Unknown nodal seepage flux node: ${flux.nodeId}.`);
+        const flowM3PerSPerM = flux.flowM3PerSPerM ?? 0;
+        assertFinite(flowM3PerSPerM, `nodal seepage flux ${flux.nodeId}.flowM3PerSPerM`);
+        loads[nodeIndex] += flowM3PerSPerM;
+    }
+    const elementGaussCache = [];
+    for (const element of model.elements) {
+        if (!Array.isArray(element.nodeIds) || element.nodeIds.length !== 4) {
+            throw new Error(`Plane-strain seepage element ${element.id} must reference exactly four nodes.`);
+        }
+        if (new Set(element.nodeIds).size !== 4) {
+            throw new Error(`Plane-strain seepage element ${element.id} has duplicate node references.`);
+        }
+        assertNonEmptyId(element.materialId, `element ${element.id} material`);
+        const nodeIndices = element.nodeIds.map((id) => {
+            const index = nodeIndexById.get(id);
+            if (index == null)
+                throw new Error(`Unknown seepage element node: ${id}.`);
+            return index;
+        });
+        const material = materialById.get(element.materialId);
+        if (!material)
+            throw new Error(`Unknown seepage element material: ${element.materialId}.`);
+        const thicknessM = element.thicknessM ?? model.defaultThicknessM ?? 1;
+        assertFinitePositive(thicknessM, `element ${element.id} thicknessM`);
+        const nodes = nodeIndices.map((index) => model.nodes[index]);
+        const elementData = hydraulicElementMatrices({ nodes, material, thicknessM });
+        for (let localRow = 0; localRow < 4; localRow += 1) {
+            for (let localCol = 0; localCol < 4; localCol += 1) {
+                conductivity[nodeIndices[localRow]][nodeIndices[localCol]] += elementData.conductivity[localRow][localCol];
+            }
+        }
+        elementGaussCache.push({
+            element,
+            globalNodes: nodeIndices,
+            areaM2: elementData.areaM2,
+            thicknessM,
+            gauss: elementData.gauss,
+        });
+    }
+    const prescribed = new Map();
+    for (const bc of model.headBoundaryConditions) {
+        const nodeIndex = nodeIndexById.get(bc.nodeId);
+        if (nodeIndex == null)
+            throw new Error(`Unknown hydraulic head boundary node: ${bc.nodeId}.`);
+        assertFinite(bc.headM, `head boundary ${bc.nodeId}.headM`);
+        const existing = prescribed.get(nodeIndex);
+        if (existing != null && Math.abs(existing - bc.headM) > 1e-12) {
+            throw new Error(`Conflicting hydraulic head boundary condition for ${bc.nodeId}.`);
+        }
+        prescribed.set(nodeIndex, bc.headM);
+    }
+    if (prescribed.size < 2) {
+        throw new Error('Plane-strain seepage model requires at least two hydraulic head boundary conditions.');
+    }
+    const freeDofs = Array.from({ length: headDofCount }, (_, index) => index).filter((index) => !prescribed.has(index));
+    const heads = new Array(headDofCount).fill(0);
+    for (const [index, value] of prescribed)
+        heads[index] = value;
+    if (freeDofs.length > 0) {
+        const reducedK = freeDofs.map((row) => freeDofs.map((col) => conductivity[row][col]));
+        const reducedF = freeDofs.map((row) => loads[row] - [...prescribed.entries()]
+            .reduce((sum, [col, value]) => sum + conductivity[row][col] * value, 0));
+        const solved = solveDenseLinearSystem(reducedK, reducedF);
+        for (const [index, dof] of freeDofs.entries())
+            heads[dof] = solved[index];
+    }
+    const internal = matVec(conductivity, heads);
+    const residual = internal.map((value, index) => value - loads[index]);
+    const maxFreeMassResidualM3PerS = freeDofs.length > 0
+        ? Math.max(...freeDofs.map((index) => Math.abs(residual[index])))
+        : 0;
+    const boundaryResiduals = Array.from(prescribed.keys()).map((index) => residual[index]);
+    const totalPositiveBoundaryFluxM3PerS = boundaryResiduals
+        .filter((value) => value > 0)
+        .reduce((sum, value) => sum + value, 0);
+    const totalNegativeBoundaryFluxM3PerS = -boundaryResiduals
+        .filter((value) => value < 0)
+        .reduce((sum, value) => sum + value, 0);
+    const boundaryFluxSum = boundaryResiduals.reduce((sum, value) => sum + value, 0);
+    const netNodalFluxM3PerS = loads.reduce((sum, value) => sum + value, 0);
+    const massScale = Math.max(totalPositiveBoundaryFluxM3PerS, totalNegativeBoundaryFluxM3PerS, Math.abs(netNodalFluxM3PerS), 1e-12);
+    const massBalanceErrorRatio = Math.abs(boundaryFluxSum + netNodalFluxM3PerS) / massScale;
+    let maxPorePressureKpa = 0;
+    let maxEffectiveStressReductionKpa = 0;
+    const elementOutputs = elementGaussCache.map((entry) => {
+        const gaussPoints = entry.gauss.map((point, index) => {
+            const localHeads = entry.globalNodes.map((nodeIndex) => heads[nodeIndex]);
+            const localNodes = entry.globalNodes.map((nodeIndex) => model.nodes[nodeIndex]);
+            const headM = point.shape.reduce((sum, shape, node) => sum + shape * localHeads[node], 0);
+            const elevationM = point.shape.reduce((sum, shape, node) => sum + shape * localNodes[node].yM, 0);
+            const gradientX = point.dNdx.reduce((sum, dNdx, node) => sum + dNdx * localHeads[node], 0);
+            const gradientY = point.dNdy.reduce((sum, dNdy, node) => sum + dNdy * localHeads[node], 0);
+            const porePressureKpa = Math.max(0, (headM - elevationM) * gammaWaterKpaPerM);
+            const effectiveStressReductionKpa = point.biotCoefficient * porePressureKpa;
+            maxPorePressureKpa = Math.max(maxPorePressureKpa, porePressureKpa);
+            maxEffectiveStressReductionKpa = Math.max(maxEffectiveStressReductionKpa, effectiveStressReductionKpa);
+            return {
+                elementId: entry.element.id,
+                gaussPoint: index + 1,
+                xi: round(point.xi, 10),
+                eta: round(point.eta, 10),
+                detJ: round(point.detJ, 10),
+                headM: round(headM, 10),
+                elevationM: round(elevationM, 10),
+                porePressureKpa: round(porePressureKpa, 8),
+                hydraulicGradient: [round(gradientX, 12), round(gradientY, 12)],
+                darcyFluxMPerS: [
+                    Number((-point.kxMPerS * gradientX).toExponential(12)),
+                    Number((-point.kyMPerS * gradientY).toExponential(12)),
+                ],
+                biotCoefficient: round(point.biotCoefficient, 8),
+                effectiveStressReductionKpa: round(effectiveStressReductionKpa, 8),
+            };
+        });
+        return {
+            id: entry.element.id,
+            areaM2: round(entry.areaM2, 10),
+            thicknessM: round(entry.thicknessM, 10),
+            gaussPoints,
+        };
+    });
+    const nodes = model.nodes.map((node, index) => {
+        const porePressureKpa = Math.max(0, (heads[index] - node.yM) * gammaWaterKpaPerM);
+        maxPorePressureKpa = Math.max(maxPorePressureKpa, porePressureKpa);
+        return {
+            ...node,
+            headM: round(heads[index], 10),
+            porePressureKpa: round(porePressureKpa, 8),
+            hydraulicResidualM3PerS: Number(residual[index].toExponential(12)),
+        };
+    });
+    return {
+        schemaVersion: 'fem-plane-strain-seepage-result.v1',
+        method: 'quad4-plane-strain-steady-darcy-seepage',
+        nodes,
+        elements: elementOutputs,
+        headDofCount,
+        freeHeadDofCount: freeDofs.length,
+        constrainedHeadDofCount: prescribed.size,
+        maxFreeMassResidualM3PerS: Number(maxFreeMassResidualM3PerS.toExponential(12)),
+        totalPositiveBoundaryFluxM3PerS: Number(totalPositiveBoundaryFluxM3PerS.toExponential(12)),
+        totalNegativeBoundaryFluxM3PerS: Number(totalNegativeBoundaryFluxM3PerS.toExponential(12)),
+        netNodalFluxM3PerS: Number(netNodalFluxM3PerS.toExponential(12)),
+        massBalanceErrorRatio: round(massBalanceErrorRatio, 12),
+        maxPorePressureKpa: round(maxPorePressureKpa, 8),
+        maxEffectiveStressReductionKpa: round(maxEffectiveStressReductionKpa, 8),
+        converged: maxFreeMassResidualM3PerS <= policy.porePressureMassBalanceTolerance &&
+            massBalanceErrorRatio <= policy.porePressureMassBalanceTolerance,
+        policy,
+        limitations: [
+            'Benchmark-scale steady saturated Darcy seepage evidence kernel only.',
+            'Solves hydraulic head on the Quad4 mesh and reports pore-pressure/effective-stress reduction metadata, but it does not add pore-pressure DOFs to the mechanical stiffness matrix.',
+            'No transient 2D/3D Biot consolidation, unsaturated flow, uplift/piping design acceptance, production sparse solver, or route-backed result manifest is provided.',
+        ],
+    };
+}
 export function runPlaneStrainQuad4Assembly(model) {
     if (model.schemaVersion !== 'fem-plane-strain-model.v1') {
         throw new Error('Only fem-plane-strain-model.v1 is supported.');
@@ -397,4 +794,316 @@ export function runPlaneStrainQuad4Assembly(model) {
         policy,
     };
 }
+function assemblePlaneStrainSystem(model) {
+    if (model.schemaVersion !== 'fem-plane-strain-model.v1') {
+        throw new Error('Only fem-plane-strain-model.v1 is supported.');
+    }
+    assertArray(model.nodes, 'nodes');
+    assertArray(model.elements, 'elements');
+    assertArray(model.materials, 'materials');
+    assertArray(model.boundaryConditions, 'boundaryConditions');
+    if (model.nodes.length < 4)
+        throw new Error('Plane-strain model requires at least four nodes.');
+    if (model.elements.length < 1)
+        throw new Error('Plane-strain model requires at least one element.');
+    if (model.materials.length < 1)
+        throw new Error('Plane-strain model requires at least one material.');
+    if (model.defaultThicknessM != null)
+        assertFinitePositive(model.defaultThicknessM, 'defaultThicknessM');
+    if (model.nodalLoads != null)
+        assertArray(model.nodalLoads, 'nodalLoads');
+    assertUniqueIds(model.nodes, 'node');
+    assertUniqueIds(model.materials, 'material');
+    assertUniqueIds(model.elements, 'element');
+    const policy = model.policy ?? DEFAULT_FEM_CONVERGENCE_POLICY;
+    validateConvergencePolicy(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 dofCount = model.nodes.length * 2;
+    if (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));
+    const loads = new Array(dofCount).fill(0);
+    for (const node of model.nodes) {
+        assertFinite(node.xM, `node ${node.id} xM`);
+        assertFinite(node.yM, `node ${node.id} yM`);
+    }
+    for (const material of model.materials) {
+        planeStrainD(material);
+        druckerPragerParameters(material);
+        if (material.unitWeightKnM3 != null) {
+            assertFiniteNonNegative(material.unitWeightKnM3, `material ${material.id} unitWeightKnM3`);
+        }
+    }
+    for (const load of model.nodalLoads ?? []) {
+        const nodeIndex = nodeIndexById.get(load.nodeId);
+        if (nodeIndex == null)
+            throw new Error(`Unknown nodal load node: ${load.nodeId}.`);
+        const fxKn = load.fxKn ?? 0;
+        const fyKn = load.fyKn ?? 0;
+        assertFinite(fxKn, `nodal load ${load.nodeId}.fxKn`);
+        assertFinite(fyKn, `nodal load ${load.nodeId}.fyKn`);
+        loads[dofIndex(nodeIndex, 'ux')] += fxKn;
+        loads[dofIndex(nodeIndex, 'uy')] += fyKn;
+    }
+    const elementGaussCache = [];
+    for (const element of model.elements) {
+        if (!Array.isArray(element.nodeIds) || element.nodeIds.length !== 4) {
+            throw new Error(`Plane-strain element ${element.id} must reference exactly four nodes.`);
+        }
+        if (new Set(element.nodeIds).size !== 4) {
+            throw new Error(`Plane-strain element ${element.id} has duplicate node references.`);
+        }
+        assertNonEmptyId(element.materialId, `element ${element.id} material`);
+        const nodeIndices = element.nodeIds.map((id) => {
+            const index = nodeIndexById.get(id);
+            if (index == null)
+                throw new Error(`Unknown element node: ${id}.`);
+            return index;
+        });
+        const material = materialById.get(element.materialId);
+        if (!material)
+            throw new Error(`Unknown element material: ${element.materialId}.`);
+        const thicknessM = element.thicknessM ?? model.defaultThicknessM ?? 1;
+        assertFinitePositive(thicknessM, `element ${element.id} thicknessM`);
+        const nodes = nodeIndices.map((index) => model.nodes[index]);
+        const elementData = elementMatrices({ nodes, material, thicknessM });
+        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];
+            }
+        }
+        elementGaussCache.push({
+            element,
+            globalDofs,
+            gauss: elementData.gauss,
+            areaM2: elementData.areaM2,
+            thicknessM,
+        });
+    }
+    const prescribed = new Map();
+    for (const bc of model.boundaryConditions) {
+        const nodeIndex = nodeIndexById.get(bc.nodeId);
+        if (nodeIndex == null)
+            throw new Error(`Unknown boundary-condition node: ${bc.nodeId}.`);
+        if (bc.dof !== 'ux' && bc.dof !== 'uy') {
+            throw new Error(`Boundary condition ${bc.nodeId} dof must be ux or uy.`);
+        }
+        const index = dofIndex(nodeIndex, bc.dof);
+        const value = bc.valueM ?? 0;
+        assertFinite(value, `boundary condition ${bc.nodeId}.${bc.dof}`);
+        const existing = prescribed.get(index);
+        if (existing != null && Math.abs(existing - value) > 1e-12) {
+            throw new Error(`Conflicting boundary condition for ${bc.nodeId}.${bc.dof}.`);
+        }
+        prescribed.set(index, value);
+    }
+    if (prescribed.size === 0)
+        throw new Error('Plane-strain model requires at least one displacement boundary condition.');
+    const constrainedNodeIds = new Set(model.boundaryConditions.map((bc) => bc.nodeId));
+    const hasUxConstraint = model.boundaryConditions.some((bc) => bc.dof === 'ux');
+    const hasUyConstraint = model.boundaryConditions.some((bc) => bc.dof === 'uy');
+    if (prescribed.size < 3 || constrainedNodeIds.size < 2 || !hasUxConstraint || !hasUyConstraint) {
+        throw new Error('Plane-strain model has insufficient displacement constraints to restrain rigid-body modes.');
+    }
+    const freeDofs = Array.from({ length: dofCount }, (_, index) => index).filter((index) => !prescribed.has(index));
+    return {
+        policy,
+        materialById,
+        stiffness,
+        loads,
+        prescribed,
+        freeDofs,
+        dofCount,
+        elementGaussCache,
+    };
+}
+function evaluatePlaneStrainDruckerPragerState(input) {
+    const { system, displacement, loadFactor } = input;
+    const internal = new Array(system.dofCount).fill(0);
+    let maxYieldResidualRatio = 0;
+    let maxEquivalentPlasticStrain = 0;
+    let plasticGaussPointCount = 0;
+    const elements = system.elementGaussCache.map((entry) => {
+        const material = system.materialById.get(entry.element.materialId);
+        const d = planeStrainD(material);
+        const elementDisplacement = entry.globalDofs.map((index) => displacement[index]);
+        const gaussPoints = entry.gauss.map((point, index) => {
+            const strain = point.b.map((row) => row.reduce((sum, value, col) => sum + value * elementDisplacement[col], 0));
+            const elasticStress = d.map((row) => row.reduce((sum, value, col) => sum + value * strain[col], 0));
+            const projected = projectDruckerPragerStress({
+                material,
+                policy: system.policy,
+                strain,
+                stress: elasticStress,
+                sigmaZKpa: planeStrainSigmaZ(material, strain),
+            });
+            maxYieldResidualRatio = Math.max(maxYieldResidualRatio, projected.yieldResidualRatio);
+            maxEquivalentPlasticStrain = Math.max(maxEquivalentPlasticStrain, projected.equivalentPlasticStrain);
+            if (projected.state === 'plastic')
+                plasticGaussPointCount += 1;
+            for (let localDof = 0; localDof < 8; localDof += 1) {
+                const force = point.b.reduce((sum, bRow, component) => sum + bRow[localDof] * projected.stressKpa[component], 0) * point.detJ * entry.thicknessM;
+                internal[entry.globalDofs[localDof]] += force;
+            }
+            return {
+                elementId: entry.element.id,
+                gaussPoint: index + 1,
+                xi: round(point.xi, 10),
+                eta: round(point.eta, 10),
+                detJ: round(point.detJ, 10),
+                strain: [
+                    round(projected.strain[0], 12),
+                    round(projected.strain[1], 12),
+                    round(projected.strain[2], 12),
+                ],
+                stressKpa: [
+                    round(projected.stressKpa[0], 8),
+                    round(projected.stressKpa[1], 8),
+                    round(projected.stressKpa[2], 8),
+                ],
+                outOfPlaneStressKpa: round(projected.outOfPlaneStressKpa, 8),
+                compressionPositivePrincipalStressKpa: [
+                    round(projected.compressionPositivePrincipalStressKpa[0], 8),
+                    round(projected.compressionPositivePrincipalStressKpa[1], 8),
+                    round(projected.compressionPositivePrincipalStressKpa[2], 8),
+                ],
+                yieldValueKpa: round(projected.yieldValueKpa, 10),
+                yieldResidualRatio: round(projected.yieldResidualRatio, 12),
+                plasticMultiplier: round(projected.plasticMultiplier, 12),
+                equivalentPlasticStrain: round(projected.equivalentPlasticStrain, 12),
+                state: projected.state,
+            };
+        });
+        return {
+            id: entry.element.id,
+            areaM2: round(entry.areaM2, 10),
+            thicknessM: round(entry.thicknessM, 10),
+            gaussPoints,
+        };
+    });
+    const loadsAtStep = system.loads.map((load) => load * loadFactor);
+    const residual = internal.map((value, index) => value - loadsAtStep[index]);
+    const maxFreeResidualKn = system.freeDofs.length > 0
+        ? Math.max(...system.freeDofs.map((index) => Math.abs(residual[index])))
+        : 0;
+    const loadNorm = Math.max(Math.hypot(...loadsAtStep), Math.hypot(...internal), Math.hypot(...Array.from(system.prescribed.keys()).map((index) => residual[index])), 1);
+    const residualNormRatio = maxFreeResidualKn / loadNorm;
+    const externalLoadSumX = loadsAtStep.filter((_, index) => index % 2 === 0).reduce((sum, value) => sum + value, 0);
+    const externalLoadSumY = loadsAtStep.filter((_, index) => index % 2 === 1).reduce((sum, value) => sum + value, 0);
+    const reactionSumX = Array.from(system.prescribed.keys())
+        .filter((index) => index % 2 === 0)
+        .reduce((sum, index) => sum + residual[index], 0);
+    const reactionSumY = Array.from(system.prescribed.keys())
+        .filter((index) => index % 2 === 1)
+        .reduce((sum, index) => sum + residual[index], 0);
+    const balanceError = Math.hypot(reactionSumX + externalLoadSumX, reactionSumY + externalLoadSumY);
+    const balanceScale = Math.max(Math.hypot(reactionSumX, reactionSumY), Math.hypot(externalLoadSumX, externalLoadSumY), 1);
+    const reactionBalanceRatio = 1 - balanceError / balanceScale;
+    return {
+        internal,
+        residual,
+        maxFreeResidualKn,
+        residualNormRatio,
+        reactionBalanceRatio,
+        maxYieldResidualRatio,
+        maxEquivalentPlasticStrain,
+        plasticGaussPointCount,
+        elements,
+    };
+}
+function normalizeLoadStepFractions(loadStepFractions) {
+    const fractions = loadStepFractions && loadStepFractions.length > 0
+        ? [...loadStepFractions]
+        : [0.25, 0.5, 0.75, 1];
+    let previous = 0;
+    for (const [index, fraction] of fractions.entries()) {
+        if (!Number.isFinite(fraction) || fraction <= previous || fraction > 1) {
+            throw new Error(`loadStepFractions.${index} must be finite, increasing, and between 0 and 1.`);
+        }
+        previous = fraction;
+    }
+    if (fractions[fractions.length - 1] !== 1) {
+        throw new Error('loadStepFractions must end at 1.');
+    }
+    return fractions;
+}
+export function runPlaneStrainDruckerPragerLoadSteps(model, options = {}) {
+    const system = assemblePlaneStrainSystem(model);
+    const loadStepFractions = normalizeLoadStepFractions(options.loadStepFractions);
+    const reducedK = system.freeDofs.map((row) => system.freeDofs.map((col) => system.stiffness[row][col]));
+    const displacement = new Array(system.dofCount).fill(0);
+    let finalEvaluation;
+    const loadSteps = [];
+    for (const [stepIndex, loadFactor] of loadStepFractions.entries()) {
+        for (const [index, value] of system.prescribed)
+            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;
+        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);
+            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;
+        }
+        finalEvaluation = evaluation;
+        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),
+            plasticGaussPointCount: evaluation.plasticGaussPointCount,
+            converged,
+        });
+    }
+    if (!finalEvaluation) {
+        throw new Error('Plane-strain nonlinear load-step solver requires at least one load step.');
+    }
+    return {
+        schemaVersion: 'fem-plane-strain-drucker-prager-result.v1',
+        method: 'quad4-plane-strain-drucker-prager-modified-newton',
+        nodes: model.nodes.map((node, index) => ({
+            ...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),
+        })),
+        elements: finalEvaluation.elements,
+        dofCount: system.dofCount,
+        freeDofCount: system.freeDofs.length,
+        constrainedDofCount: system.prescribed.size,
+        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),
+        plasticGaussPointCount: finalEvaluation.plasticGaussPointCount,
+        converged: loadSteps.every((step) => step.converged),
+        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.',
+            'Use for deterministic evidence and regression tests only until independent published/commercial benchmark comparison and licensed production approval gates are complete.',
+        ],
+    };
+}
 //# sourceMappingURL=plane-strain-assembly.js.map