ANYsolver 0.1.0__py3-none-any.whl

anysolver/plasticity_qualification.py

@@ -0,0 +1,314 @@
+"""Plasticity and nonlinear tangent qualification metrics."""
+
+from __future__ import annotations
+
+import json
+import platform
+import time
+from pathlib import Path
+from typing import Any, Dict, Tuple
+
+import numpy as np
+
+from .elements import BeamElement, ShellElement
+from .fe_core import FEModel
+from .material_curves import DNVC208MaterialCurve, FiberSectionPlasticityConfig, dnv_c208_steel_curve
+from .plasticity import plane_stress_elastic_matrix, plane_stress_return_map
+
+DEFAULT_PLASTICITY_QUALIFICATION_PATH = Path("reports/plasticity_qualification/plasticity_qualification_report.json")
+
+E_STEEL = 210.0e9
+NU_STEEL = 0.3
+
+_P_MATRIX = np.array(
+    [[2.0, -1.0, 0.0], [-1.0, 2.0, 0.0], [0.0, 0.0, 6.0]],
+    dtype=float,
+) / 3.0
+
+
+def reference_plastic_curve() -> DNVC208MaterialCurve:
+    """Nearly elastic-perfectly plastic reference curve used by local checks."""
+    return DNVC208MaterialCurve(
+        sigma_prop=354.0e6,
+        sigma_yield=355.0e6,
+        sigma_yield_2=355.5e6,
+        eps_p_y1=0.004,
+        eps_p_y2=0.1,
+        K=400.0e6,
+        n=0.2,
+    )
+
+
+def yield_function_residual(stress: np.ndarray, alpha: float, curve: DNVC208MaterialCurve) -> float:
+    """Scaled plane-stress J2 yield residual."""
+    sigma = np.asarray(stress, dtype=float).reshape(3)
+    sy = float(curve.flow_stress(np.array([float(alpha)], dtype=float))[0])
+    residual = 0.5 * float(sigma @ _P_MATRIX @ sigma) - sy**2 / 3.0
+    return float(residual / max(sy**2, 1.0))
+
+
+def _material_tangent_fd_error(
+    strain: np.ndarray,
+    curve: DNVC208MaterialCurve,
+    plastic: np.ndarray | None = None,
+    alpha: np.ndarray | None = None,
+    step: float = 1.0e-7,
+) -> Dict[str, Any]:
+    strain = np.asarray(strain, dtype=float).reshape(1, 3)
+    plastic = np.zeros_like(strain) if plastic is None else np.asarray(plastic, dtype=float).reshape(1, 3)
+    alpha = np.zeros(1, dtype=float) if alpha is None else np.asarray(alpha, dtype=float).reshape(1)
+    stress, tangent, plastic_new, alpha_new = plane_stress_return_map(
+        strain, plastic, alpha, E_STEEL, NU_STEEL, curve
+    )
+    fd = np.zeros((3, 3), dtype=float)
+    for col in range(3):
+        perturb = np.zeros_like(strain)
+        perturb[0, col] = step
+        sp = plane_stress_return_map(strain + perturb, plastic, alpha, E_STEEL, NU_STEEL, curve)[0][0]
+        sm = plane_stress_return_map(strain - perturb, plastic, alpha, E_STEEL, NU_STEEL, curve)[0][0]
+        fd[:, col] = (sp - sm) / (2.0 * step)
+    error = float(np.linalg.norm(tangent[0] - fd) / max(np.linalg.norm(fd), 1.0))
+    return {
+        "stress": stress[0].tolist(),
+        "alpha": float(alpha_new[0]),
+        "max_plastic_strain_component": float(np.max(np.abs(plastic_new))),
+        "yield_residual": yield_function_residual(stress[0], float(alpha_new[0]), curve),
+        "tangent_fd_relative_error": error,
+        "tangent_status": "tight" if error < 1.0e-3 else "diagnostic_current_continuum_tangent",
+    }
+
+
+def material_point_path_metrics() -> Dict[str, Any]:
+    """Qualify return-map yield consistency over representative strain paths."""
+    curve = reference_plastic_curve()
+    elastic_curve = None
+    elastic_strain = np.array([[1.0e-4, -0.5e-4, 0.25e-4]], dtype=float)
+    elastic_stress, elastic_tangent, _, _ = plane_stress_return_map(
+        elastic_strain, np.zeros_like(elastic_strain), np.zeros(1), E_STEEL, NU_STEEL, elastic_curve
+    )
+    elastic_expected = elastic_strain @ plane_stress_elastic_matrix(E_STEEL, NU_STEEL).T
+
+    paths = {
+        "uniaxial": _material_tangent_fd_error(np.array([0.002, 0.0, 0.0]), curve),
+        "biaxial_shear": _material_tangent_fd_error(np.array([0.003, 0.001, 0.0005]), curve),
+        "pure_shear": _material_tangent_fd_error(np.array([0.0, 0.0, 0.004]), curve),
+    }
+
+    first = _material_tangent_fd_error(np.array([0.003, 0.0, 0.0]), curve)
+    plastic_old = np.asarray(first["stress"], dtype=float).reshape(1, 3) * 0.0
+    stress, _tangent, plastic_new, alpha_new = plane_stress_return_map(
+        np.array([[0.003, 0.0, 0.0]], dtype=float),
+        np.zeros((1, 3), dtype=float),
+        np.zeros(1, dtype=float),
+        E_STEEL,
+        NU_STEEL,
+        curve,
+    )
+    unload_stress, _, _, unload_alpha = plane_stress_return_map(
+        np.array([[0.001, 0.0, 0.0]], dtype=float),
+        plastic_new,
+        alpha_new,
+        E_STEEL,
+        NU_STEEL,
+        curve,
+    )
+    paths["unload_from_plastic"] = {
+        "stress": unload_stress[0].tolist(),
+        "alpha": float(unload_alpha[0]),
+        "alpha_change": float(unload_alpha[0] - alpha_new[0]),
+        "yield_residual": yield_function_residual(stress[0], float(alpha_new[0]), curve),
+    }
+
+    return {
+        "elastic": {
+            "stress_relative_error": float(np.linalg.norm(elastic_stress - elastic_expected) / max(np.linalg.norm(elastic_expected), 1.0)),
+            "tangent_relative_error": float(
+                np.linalg.norm(elastic_tangent[0] - plane_stress_elastic_matrix(E_STEEL, NU_STEEL))
+                / max(np.linalg.norm(plane_stress_elastic_matrix(E_STEEL, NU_STEEL)), 1.0)
+            ),
+        },
+        "plastic_paths": paths,
+        "max_abs_yield_residual": max(abs(path.get("yield_residual", 0.0)) for path in paths.values()),
+        "max_material_tangent_fd_error": max(
+            path.get("tangent_fd_relative_error", 0.0) for path in paths.values()
+        ),
+    }
+
+
+def _finite_difference_element_tangent(
+    element: Any,
+    model: FEModel,
+    u_elem: np.ndarray,
+    state: Any = None,
+    num_layers: int = 5,
+    step: float = 1.0e-7,
+) -> Dict[str, Any]:
+    material = model.get_material(element.material_name)
+    f, K, trial_state = element.compute_nonlinear_response(
+        model.mesh, material, u_elem, state, num_layers=num_layers, tangent=True
+    )
+    fd = np.zeros_like(K)
+    for col in range(K.shape[1]):
+        perturb = np.zeros_like(u_elem)
+        perturb[col] = step
+        fp = element.compute_nonlinear_response(
+            model.mesh, material, u_elem + perturb, state, num_layers=num_layers, tangent=False
+        )[0]
+        fm = element.compute_nonlinear_response(
+            model.mesh, material, u_elem - perturb, state, num_layers=num_layers, tangent=False
+        )[0]
+        fd[:, col] = (fp - fm) / (2.0 * step)
+    error = float(np.linalg.norm(K - fd) / max(np.linalg.norm(fd), 1.0))
+    return {
+        "tangent_fd_relative_error": error,
+        "force_norm": float(np.linalg.norm(f)),
+        "tangent_norm": float(np.linalg.norm(K)),
+        "fd_tangent_norm": float(np.linalg.norm(fd)),
+        "state_summary": _state_summary(trial_state),
+    }
+
+
+def _state_summary(state: Any) -> Dict[str, Any]:
+    if not isinstance(state, dict):
+        return {}
+    summary: Dict[str, Any] = {}
+    for key in ("alpha", "plastic_strain", "layer_strain", "fiber_strain"):
+        value = np.asarray(state.get(key, []), dtype=float)
+        if value.size:
+            summary[f"{key}_max"] = float(np.max(value))
+            summary[f"{key}_min"] = float(np.min(value))
+            summary[f"{key}_max_abs"] = float(np.max(np.abs(value)))
+    if "axial_force" in state:
+        summary["axial_force"] = float(state["axial_force"])
+    return summary
+
+
+def _beam_model(curve: DNVC208MaterialCurve | None = None, fiber: bool = False) -> Tuple[FEModel, BeamElement]:
+    model = FEModel("beam_tangent_metric")
+    model.add_material("steel", E_STEEL, NU_STEEL, hardening_curve=curve)
+    model.add_node(1, 0.0, 0.0, 0.0)
+    model.add_node(2, 1.0, 0.0, 0.0)
+    section = {"area": 0.01, "Iy": 1.0e-5, "Iz": 1.0e-5, "J": 1.0e-5}
+    if fiber:
+        section["fiber_plasticity"] = FiberSectionPlasticityConfig(5, 5)
+    element = BeamElement(1, [1, 2], "steel", section)
+    model.add_element(1, element)
+    return model, element
+
+
+def _shell_model(curve: DNVC208MaterialCurve | None = None) -> Tuple[FEModel, ShellElement]:
+    model = FEModel("shell_tangent_metric")
+    model.add_material("steel", E_STEEL, NU_STEEL, hardening_curve=curve)
+    for node_id, coord in enumerate(((0.0, 0.0, 0.0), (1.0, 0.0, 0.0), (1.0, 1.0, 0.0), (0.0, 1.0, 0.0)), start=1):
+        model.add_node(node_id, *coord)
+    element = ShellElement(1, [1, 2, 3, 4], "steel", 0.01)
+    model.add_element(1, element)
+    return model, element
+
+
+def element_tangent_metrics() -> Dict[str, Any]:
+    curve = reference_plastic_curve()
+
+    beam_elastic_model, beam_elastic = _beam_model()
+    u_beam_elastic = np.zeros(12, dtype=float)
+    u_beam_elastic[6] = 0.001
+    u_beam_elastic[7] = 0.0003
+    beam_elastic_metric = _finite_difference_element_tangent(beam_elastic, beam_elastic_model, u_beam_elastic)
+
+    beam_plastic_model, beam_plastic = _beam_model(curve, fiber=True)
+    u_beam_plastic = np.zeros(12, dtype=float)
+    u_beam_plastic[6] = 0.006
+    u_beam_plastic[7] = 0.0003
+    beam_plastic_metric = _finite_difference_element_tangent(beam_plastic, beam_plastic_model, u_beam_plastic)
+
+    shell_elastic_model, shell_elastic = _shell_model()
+    u_shell_elastic = np.zeros(24, dtype=float)
+    u_shell_elastic[2::6] = [0.0, 0.001, 0.001, 0.0]
+    u_shell_elastic[4::6] = [0.001, 0.001, 0.001, 0.001]
+    shell_elastic_metric = _finite_difference_element_tangent(
+        shell_elastic, shell_elastic_model, u_shell_elastic, step=1.0e-8
+    )
+
+    shell_plastic_model, shell_plastic = _shell_model(curve)
+    u_shell_plastic = np.zeros(24, dtype=float)
+    coords = shell_plastic.get_node_coordinates(shell_plastic_model.mesh)
+    for local, coord in enumerate(coords):
+        x, y, _ = coord
+        base = local * 6
+        u_shell_plastic[base + 0] = 0.003 * x
+        u_shell_plastic[base + 1] = -0.0008 * y
+        u_shell_plastic[base + 4] = 0.002 * x
+    shell_plastic_metric = _finite_difference_element_tangent(
+        shell_plastic, shell_plastic_model, u_shell_plastic, num_layers=5
+    )
+    shell_plastic_metric["tangent_status"] = (
+        "tight" if shell_plastic_metric["tangent_fd_relative_error"] < 1.0e-4 else "diagnostic_high_tangent_error"
+    )
+
+    max_algorithmic_error = max(
+        beam_elastic_metric["tangent_fd_relative_error"],
+        beam_plastic_metric["tangent_fd_relative_error"],
+        shell_elastic_metric["tangent_fd_relative_error"],
+        shell_plastic_metric["tangent_fd_relative_error"],
+    )
+    return {
+        "beam_elastic": beam_elastic_metric,
+        "beam_fiber_plastic": beam_plastic_metric,
+        "shell_elastic": shell_elastic_metric,
+        "shell_layered_plastic": shell_plastic_metric,
+        "max_tight_tangent_error": max(
+            beam_elastic_metric["tangent_fd_relative_error"],
+            beam_plastic_metric["tangent_fd_relative_error"],
+            shell_elastic_metric["tangent_fd_relative_error"],
+        ),
+        "max_algorithmic_tangent_error": max_algorithmic_error,
+    }
+
+
+def dnv_curve_metric() -> Dict[str, Any]:
+    curves = {}
+    for grade, thickness in (("S355", 0.010), ("S420", 0.020), ("S460", 0.050)):
+        curve = dnv_c208_steel_curve(grade, thickness)
+        curves[f"{grade}_{thickness:g}"] = {
+            "sigma_prop": curve.sigma_prop,
+            "sigma_yield": curve.sigma_yield,
+            "sigma_yield_2": curve.sigma_yield_2,
+            "eps_p_y1": curve.eps_p_y1,
+            "eps_p_y2": curve.eps_p_y2,
+            "K": curve.K,
+            "n": curve.n,
+        }
+    return curves
+
+
+def generate_plasticity_qualification_report() -> Dict[str, Any]:
+    material = material_point_path_metrics()
+    element = element_tangent_metrics()
+    return {
+        "schema_version": 1,
+        "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "environment": {
+            "platform": platform.platform(),
+            "python": platform.python_version(),
+            "numpy": np.__version__,
+        },
+        "dnv_curves": dnv_curve_metric(),
+        "material_point": material,
+        "element_tangents": element,
+        "status": "passed"
+        if material["max_abs_yield_residual"] < 1.0e-8 and element["max_algorithmic_tangent_error"] < 1.0e-4
+        else "diagnostic",
+        "known_limitations": [
+            "Plastic material tangents are now consistent numerical algorithmic tangents of the discrete return map.",
+            "The numerical tangent is intentionally correctness-first and more expensive than a closed-form analytical algorithmic tangent.",
+            "A future speed batch should replace the numerical tangent with an analytical derivative after preserving these finite-difference checks.",
+        ],
+    }
+
+
+def write_plasticity_qualification_report(path: Path | str = DEFAULT_PLASTICITY_QUALIFICATION_PATH) -> Dict[str, Any]:
+    report = generate_plasticity_qualification_report()
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return report

anysolver/production_readiness.py

@@ -0,0 +1,304 @@
+"""Production-readiness artifacts tied to verification release gates.
+
+These helpers implement the safe part of the post-verification production plan:
+capability and scope reporting.  They deliberately do not create a qualification
+tag or claim a production release while verification gates remain blocked.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+from .beam_shell_verification import run_beam_shell_verification
+
+
+DEFAULT_PRODUCTION_READINESS_DIR = Path("reports/production_readiness/current")
+
+
+@dataclass(frozen=True)
+class CapabilityEntry:
+    feature: str
+    status: str
+    release_gate: str
+    verification_cases: List[str]
+    limits: Dict[str, Any] = field(default_factory=dict)
+    limitations: List[str] = field(default_factory=list)
+    required_solver_configuration: Dict[str, Any] = field(default_factory=dict)
+    gate_blockers: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+def _gate(report: Mapping[str, Any], name: str) -> Mapping[str, Any]:
+    gates = report.get("release_gates") or {}
+    value = gates.get(name) or {}
+    return value if isinstance(value, Mapping) else {}
+
+
+def _gate_blockers(report: Mapping[str, Any], name: str) -> List[str]:
+    return [str(item.get("case_id")) for item in (_gate(report, name).get("blockers") or []) if item.get("case_id")]
+
+
+def _status_from_gate(report: Mapping[str, Any], name: str) -> str:
+    status = str(_gate(report, name).get("status", "not_evaluated"))
+    if status == "passed":
+        return "qualified"
+    if status == "blocked":
+        return "not_qualified"
+    return "not_evaluated"
+
+
+def build_capability_matrix(report: Optional[Mapping[str, Any]] = None) -> List[CapabilityEntry]:
+    """Return production capability entries derived from verification gates."""
+
+    report = report or run_beam_shell_verification()
+    flat_shell = _status_from_gate(report, "flat_thin_shell")
+    flat_stiffened = _status_from_gate(report, "flat_thin_stiffened_shell")
+    curved_stiffened = _status_from_gate(report, "curved_thin_stiffened_shell")
+    nonlinear = _status_from_gate(report, "nonlinear_capacity")
+    contact = _status_from_gate(report, "contact")
+    fracture = _status_from_gate(report, "simplified_fracture")
+    full_release = _status_from_gate(report, "fully_documented_verified_release")
+
+    return [
+        CapabilityEntry(
+            feature="flat_thin_shell_linear_static_modal_buckling",
+            status=flat_shell,
+            release_gate="flat_thin_shell",
+            verification_cases=["SHELL-009", "SHELL-010", "SHELL-011"],
+            limits={
+                "shell_formulations": ["Q4", "Q8"],
+                "units": "SI",
+                "geometry": "flat thin plates within verified mesh and thickness ranges",
+            },
+            limitations=[
+                "Q8R is experimental pending thickness-robust hourglass and inertia qualification.",
+                "Follower pressure, arbitrary contact and unverified material laws are unsupported.",
+            ],
+            required_solver_configuration={"analysis": ["linear_static", "modal", "linear_buckling"]},
+            gate_blockers=_gate_blockers(report, "flat_thin_shell"),
+        ),
+        CapabilityEntry(
+            feature="flat_thin_stiffened_shell_beam_shell_mpc",
+            status=flat_stiffened,
+            release_gate="flat_thin_stiffened_shell",
+            verification_cases=["COUP-012", "COUP-013", "COUP-014", "COUP-015", "COUP-016", "COUP-017"],
+            limits={
+                "shell_formulations": ["Q4", "Q8"],
+                "beam_formulations": ["B2"],
+                "coupling": "interpolated eccentric MPC",
+                "stiffeners": "beam stiffeners inside verified eccentricity and mesh-ratio ranges",
+            },
+            limitations=[
+                "Q8R is experimental pending thickness-robust hourglass and inertia qualification.",
+                "Equivalent all-shell model-pair checks must pass before production qualification.",
+            ],
+            required_solver_configuration={"member_model": "plates as shell, stiffeners/girders as beams"},
+            gate_blockers=_gate_blockers(report, "flat_thin_stiffened_shell"),
+        ),
+        CapabilityEntry(
+            feature="curved_thin_stiffened_shell",
+            status=curved_stiffened,
+            release_gate="curved_thin_stiffened_shell",
+            verification_cases=["SHELL-008", "COUP-020", "COUP-021", "CYL-001", "CYL-002", "CYL-003"],
+            limits={"geometry": "cylindrical and ring-stiffened shells within verified curvature ranges"},
+            limitations=[
+                "Curved scope is qualified only for the V3 cylindrical/curved-panel fixtures and documented mesh/curvature ranges."
+            ],
+            required_solver_configuration={"geometry": ["cylinder", "curved_panel"]},
+            gate_blockers=_gate_blockers(report, "curved_thin_stiffened_shell"),
+        ),
+        CapabilityEntry(
+            feature="nonlinear_capacity_and_buckling_stop",
+            status=nonlinear,
+            release_gate="nonlinear_capacity",
+            verification_cases=["NLG-006", "NLG-007", "NLG-008", "MAT-008", "DYN-001"],
+            limits={"nonlinear_scope": "monotonic ultimate capacity with verified buckling-stop diagnostics"},
+            limitations=[
+                "Unrestricted post-buckling continuation is not a production target.",
+                "Follower pressure is unsupported unless NLG-008 passes.",
+            ],
+            required_solver_configuration={"buckling_stop": "required", "post_buckling_target": False},
+            gate_blockers=_gate_blockers(report, "nonlinear_capacity"),
+        ),
+        CapabilityEntry(
+            feature="limited_rigid_sphere_shell_contact",
+            status=contact,
+            release_gate="contact",
+            verification_cases=["CONTACT-001", "CONTACT-002", "CONTACT-003", "CONTACT-004", "CONTACT-005", "CONTACT-006", "CONTACT-007", "CONTACT-008", "CONTACT-009", "CONTACT-010", "CONTACT-011", "CONTACT-012"],
+            limits={
+                "contact_scope": "single rigid sphere to shell midsurface or shell-thickness offset surface",
+                "contact_law": "frictionless normal penalty",
+                "beam_contact": "not direct; beams respond through existing shell-beam coupling",
+                "impact_damage": "optional engineering shell damage/erosion; capacity-based mode is gated by FRACT-007..012",
+            },
+            limitations=[
+                "Arbitrary contact, shell-shell contact, direct beam contact, friction, spin, rolling, crack propagation, material nonlinear impact fracture and FSI are unsupported.",
+                "Contact remains linear structural transient dynamics plus nonlinear contact-force iteration.",
+            ],
+            required_solver_configuration={"analysis": "sphere_impact_transient", "contact_gate": "CONTACT-001..012"},
+            gate_blockers=_gate_blockers(report, "contact"),
+        ),
+        CapabilityEntry(
+            feature="simplified_element_erosion_and_impact_damage",
+            status=fracture,
+            release_gate="simplified_fracture",
+            verification_cases=[
+                "FRACT-001",
+                "FRACT-002",
+                "FRACT-003",
+                "FRACT-004",
+                "FRACT-005",
+                "FRACT-006",
+                "FRACT-007",
+                "FRACT-008",
+                "FRACT-009",
+                "FRACT-010",
+                "FRACT-011",
+                "FRACT-012",
+            ],
+            limits={
+                "static_fracture_scope": "nonlinear static equivalent-plastic-strain erosion only",
+                "impact_damage_scope": "linear sphere-shell transient with engineering capacity-based shell softening/erosion",
+                "erosion": "post-converged-increment or post-converged-contact-substep residual-stiffness element erosion",
+            },
+            limitations=[
+                "Not crack propagation, cohesive fracture, remeshing or validated fracture mechanics.",
+                "Direct member separation, node deletion, MPC deletion and material nonlinear impact fracture are unsupported.",
+            ],
+            required_solver_configuration={"analysis": ["nonlinear_static", "sphere_impact_transient"], "fracture_gate": "FRACT-001..012"},
+            gate_blockers=_gate_blockers(report, "simplified_fracture"),
+        ),
+        CapabilityEntry(
+            feature="fully_documented_verified_release",
+            status=full_release,
+            release_gate="fully_documented_verified_release",
+            verification_cases=["V1:*", "V2:*", "V3:*", "V4:*", "V5:*", "MLBC:*", "CONTACT:*", "FRACTURE:*"],
+            limits={"claim": "documented ANYsolver beam-shell analysis scope only"},
+            limitations=[
+                "General-purpose commercial-solver replacement claims are prohibited.",
+                "External-reference decks are reproducible handoff artifacts unless executed external-solver result files are supplied.",
+            ],
+            required_solver_configuration={"qualification_evidence": "complete immutable release package"},
+            gate_blockers=_gate_blockers(report, "fully_documented_verified_release"),
+        ),
+        CapabilityEntry(
+            feature="unsupported_general_purpose_fe",
+            status="unsupported",
+            release_gate="none",
+            verification_cases=[],
+            limits={},
+            limitations=[
+                "Arbitrary CAD topology, arbitrary contact beyond limited sphere-shell impact, fluid-structure interaction, unsupported residual-stress fields and unverified element distortion levels are outside scope.",
+            ],
+            required_solver_configuration={"expert_override": "not sufficient for production qualification"},
+        ),
+    ]
+
+
+def build_verification_scope_statement(report: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
+    """Return a concise production scope statement from the live capability matrix."""
+
+    report = report or run_beam_shell_verification()
+    matrix = build_capability_matrix(report)
+    by_status: Dict[str, List[str]] = {}
+    for entry in matrix:
+        by_status.setdefault(entry.status, []).append(entry.feature)
+    return {
+        "schema_version": 1,
+        "production_release_status": "qualified"
+        if _status_from_gate(report, "fully_documented_verified_release") == "qualified"
+        else "not_qualified",
+        "verified": by_status.get("qualified", []),
+        "conditionally_supported": by_status.get("not_qualified", []) + by_status.get("not_evaluated", []),
+        "experimental": [],
+        "unsupported": by_status.get("unsupported", []),
+        "explicit_limitations": [
+            "Follower pressure unless implemented and verified.",
+            "Arbitrary contact beyond limited rigid-sphere-to-shell contact.",
+            "Fracture outside simplified nonlinear-static erosion and limited sphere-impact shell damage.",
+            "Fluid-structure interaction.",
+            "Unrestricted post-buckling continuation.",
+            "Arbitrary general-purpose CAD topology.",
+            "Unverified material laws.",
+            "Unsupported residual-stress fields.",
+            "Unsupported element distortion levels.",
+            "External-reference decks without executed external-solver result comparisons.",
+        ],
+        "release_gates": {
+            name: {
+                "status": gate.get("status"),
+                "blockers": [item.get("case_id") for item in (gate.get("blockers") or [])],
+            }
+            for name, gate in (report.get("release_gates") or {}).items()
+            if name != "thin_stiffened_shell"
+        },
+    }
+
+
+def _markdown_list(items: Iterable[str]) -> List[str]:
+    values = [str(item) for item in items]
+    return [f"- {item}" for item in values] if values else ["- None"]
+
+
+def scope_statement_markdown(scope: Mapping[str, Any]) -> str:
+    lines = [
+        "# ANYsolver Production Scope Statement",
+        "",
+        f"- Production release status: {scope.get('production_release_status')}",
+        "",
+        "## Verified",
+        "",
+        *_markdown_list(scope.get("verified") or []),
+        "",
+        "## Conditionally Supported",
+        "",
+        *_markdown_list(scope.get("conditionally_supported") or []),
+        "",
+        "## Experimental",
+        "",
+        *_markdown_list(scope.get("experimental") or []),
+        "",
+        "## Unsupported",
+        "",
+        *_markdown_list(scope.get("unsupported") or []),
+        "",
+        "## Explicit Limitations",
+        "",
+        *_markdown_list(scope.get("explicit_limitations") or []),
+        "",
+    ]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def write_production_readiness_artifacts(
+    output_dir: Path | str = DEFAULT_PRODUCTION_READINESS_DIR,
+    *,
+    report: Optional[Mapping[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Write capability matrix and scope-statement artifacts."""
+
+    report = report or run_beam_shell_verification()
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+    matrix = [entry.to_dict() for entry in build_capability_matrix(report)]
+    scope = build_verification_scope_statement(report)
+
+    matrix_path = output_path / "capability_matrix.json"
+    scope_json_path = output_path / "verification_scope.json"
+    scope_md_path = output_path / "verification_scope.md"
+    matrix_path.write_text(json.dumps(matrix, indent=2, sort_keys=True), encoding="utf-8")
+    scope_json_path.write_text(json.dumps(scope, indent=2, sort_keys=True), encoding="utf-8")
+    scope_md_path.write_text(scope_statement_markdown(scope), encoding="utf-8")
+    return {
+        "output_dir": str(output_path),
+        "capability_matrix": str(matrix_path),
+        "verification_scope_json": str(scope_json_path),
+        "verification_scope_markdown": str(scope_md_path),
+        "production_release_status": scope["production_release_status"],
+        "capability_count": len(matrix),
+    }