ANYsolver 0.1.0__py3-none-any.whl

anysolver/capacity_workflow.py

@@ -0,0 +1,350 @@
+"""Traceable nonlinear capacity workflow.
+
+The workflow composes existing solver pieces without changing nonlinear
+physics:
+
+1. linear static solve,
+2. prestress recovery,
+3. eigenvalue buckling,
+4. stress-free imperfection application,
+5. nonlinear static capacity solve.
+"""
+
+from __future__ import annotations
+
+import json
+import platform
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Dict, Mapping, Optional, Sequence, Tuple
+
+import numpy as np
+
+from .assembly import solve_linear
+from .buckling import BucklingResult, solve_eigenvalue_buckling
+from .imperfections import EigenmodeImperfection, ImperfectionField, apply_imperfection, to_imperfection_field
+from .nonlinear_static import (
+    NonlinearConvergenceSettings,
+    NonlinearLoadProgram,
+    NonlinearStaticResult,
+    solve_static_nonlinear,
+)
+from .recovery import ResourceConfig
+
+if TYPE_CHECKING:
+    from .boundary import LoadCase
+    from .fe_core import FEModel
+
+
+DEFAULT_CAPACITY_WORKFLOW_PATH = Path("reports/capacity_workflow/capacity_workflow_report.json")
+
+
+@dataclass(frozen=True)
+class CapacityWorkflowConfig:
+    """Settings for the nonlinear capacity workflow."""
+
+    num_buckling_modes: int = 3
+    buckling_mode_number: int = 1
+    eigenmode_imperfection_amplitude: float = 0.0
+    imperfection_dof_filter: str = "translations"
+    nonlinear_num_steps: int = 10
+    nonlinear_max_load_factor: float = 1.0
+    nonlinear_max_iterations: int = 25
+    nonlinear_tolerance: float = 1.0e-6
+    nonlinear_num_layers: int = 5
+    nonlinear_convergence_settings: Optional[NonlinearConvergenceSettings | str | Mapping[str, Any]] = None
+    nonlinear_resource_config: Optional[ResourceConfig] = None
+    mesh_min_elements_per_half_wave: int = 4
+    copy_model: bool = True
+
+
+@dataclass(frozen=True)
+class MeshModeAdequacy:
+    """Coarse diagnostic for whether a mode is represented by enough nodes."""
+
+    status: str
+    active_node_count: int
+    active_element_count: int
+    estimated_half_waves: int
+    elements_per_half_wave: float
+    warnings: Tuple[str, ...] = ()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "status": self.status,
+            "active_node_count": self.active_node_count,
+            "active_element_count": self.active_element_count,
+            "estimated_half_waves": self.estimated_half_waves,
+            "elements_per_half_wave": self.elements_per_half_wave,
+            "warnings": list(self.warnings),
+        }
+
+
+@dataclass
+class CapacityWorkflowResult:
+    """Complete result from the capacity workflow."""
+
+    status: str
+    static_displacements: np.ndarray
+    static_solver_info: Dict[str, Any]
+    prestress_states: Dict[int, Dict[str, float]]
+    prestress_summary: Dict[str, Any]
+    buckling_result: BucklingResult
+    imperfection: ImperfectionField
+    imperfect_model: "FEModel"
+    nonlinear_result: NonlinearStaticResult
+    mesh_adequacy: MeshModeAdequacy
+    diagnostics: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def critical_load_factor(self) -> Optional[float]:
+        return self.buckling_result.critical_load_factor
+
+    @property
+    def capacity_factor(self) -> float:
+        return float(self.nonlinear_result.peak_load_factor)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "status": self.status,
+            "static_solver_status": str((self.static_solver_info.get("convergence_info") or {}).get("status", "unknown")),
+            "critical_load_factor": self.critical_load_factor,
+            "buckling_solver_status": self.buckling_result.solver_status,
+            "capacity_factor": self.capacity_factor,
+            "nonlinear_status": self.nonlinear_result.status,
+            "last_converged_load_factor": self.nonlinear_result.last_converged_load_factor,
+            "failure_reason": self.nonlinear_result.failure_reason,
+            "imperfection": {
+                "name": self.imperfection.name,
+                "max_offset": self.imperfection.max_offset,
+                "metadata": dict(self.imperfection.metadata),
+            },
+            "mesh_adequacy": self.mesh_adequacy.to_dict(),
+            "prestress_summary": self.prestress_summary,
+            "diagnostics": self.diagnostics,
+            "buckling_result": self.buckling_result.to_dict(),
+            "nonlinear_result": self.nonlinear_result.to_dict(),
+        }
+
+
+def _git_sha() -> Optional[str]:
+    try:
+        result = subprocess.run(["git", "rev-parse", "HEAD"], text=True, capture_output=True, check=False)
+    except Exception:
+        return None
+    return result.stdout.strip() if result.returncode == 0 and result.stdout.strip() else None
+
+
+def _recover_prestress(model: "FEModel", displacements: np.ndarray) -> Tuple[Dict[int, Dict[str, float]], Dict[str, Any]]:
+    from .anystructure_fem_mode import recover_prestress_from_static_result
+
+    return recover_prestress_from_static_result(model, displacements)
+
+
+def _mode_shape_for(buckling_result: BucklingResult, mode_number: int) -> Optional[np.ndarray]:
+    mode = next((item for item in buckling_result.modes if int(item.mode_number) == int(mode_number)), None)
+    if mode is None:
+        return None
+    return np.asarray(mode.mode_shape, dtype=float).reshape(-1)
+
+
+def evaluate_mode_mesh_adequacy(
+    model: "FEModel",
+    buckling_result: BucklingResult,
+    mode_number: int = 1,
+    min_elements_per_half_wave: int = 4,
+    activity_tolerance: float = 0.05,
+) -> MeshModeAdequacy:
+    """Estimate whether the selected mode is adequately represented by the mesh.
+
+    The diagnostic is deliberately conservative and topology-agnostic.  It
+    counts nodes with translational mode amplitude above a fraction of the peak
+    and estimates half-waves from sign changes along the longest coordinate
+    axis among active nodes.
+    """
+    shape = _mode_shape_for(buckling_result, mode_number)
+    if shape is None or shape.size == 0:
+        return MeshModeAdequacy("no_mode", 0, 0, 0, 0.0, ("Selected buckling mode is unavailable.",))
+
+    node_values = []
+    for node_id, node in model.mesh.nodes.items():
+        translation = shape[node.dofs[:3]]
+        node_values.append((int(node_id), node.coords(), float(np.linalg.norm(translation)), float(translation[np.argmax(np.abs(translation))]) if translation.size else 0.0))
+    peak = max((item[2] for item in node_values), default=0.0)
+    if peak <= 0.0:
+        return MeshModeAdequacy("zero_mode_amplitude", 0, 0, 0, 0.0, ("Selected buckling mode has no translational amplitude.",))
+
+    active = [item for item in node_values if item[2] >= float(activity_tolerance) * peak]
+    active_ids = {item[0] for item in active}
+    active_element_count = sum(
+        1
+        for element in model.mesh.elements.values()
+        if any(int(node_id) in active_ids for node_id in getattr(element, "node_ids", ()))
+    )
+    if not active:
+        return MeshModeAdequacy("no_active_nodes", 0, active_element_count, 0, 0.0, ("No active nodes exceeded mode activity threshold.",))
+
+    coords = np.asarray([item[1] for item in active], dtype=float)
+    spans = np.ptp(coords, axis=0)
+    axis = int(np.argmax(spans))
+    active_sorted = sorted(active, key=lambda item: (item[1][axis], item[0]))
+    signs = []
+    for _node_id, _coord, _norm, signed_value in active_sorted:
+        if abs(signed_value) < 1.0e-12 * peak:
+            continue
+        signs.append(1 if signed_value > 0.0 else -1)
+    sign_changes = sum(1 for previous, current in zip(signs, signs[1:]) if previous != current)
+    estimated_half_waves = max(sign_changes + 1, 1 if signs else 0)
+    elements_per_half_wave = float(active_element_count / max(estimated_half_waves, 1))
+    warnings = []
+    if elements_per_half_wave < float(min_elements_per_half_wave):
+        warnings.append(
+            f"Mode mesh representation is coarse: {elements_per_half_wave:.2f} active elements per estimated half-wave "
+            f"(target {min_elements_per_half_wave})."
+        )
+    status = "ok" if not warnings else "warning"
+    return MeshModeAdequacy(
+        status=status,
+        active_node_count=len(active),
+        active_element_count=int(active_element_count),
+        estimated_half_waves=int(estimated_half_waves),
+        elements_per_half_wave=elements_per_half_wave,
+        warnings=tuple(warnings),
+    )
+
+
+def default_eigenmode_imperfection(
+    buckling_result: BucklingResult,
+    config: CapacityWorkflowConfig,
+) -> EigenmodeImperfection:
+    """Create the configured eigenmode imperfection."""
+    return EigenmodeImperfection(
+        buckling_result=buckling_result,
+        mode_number=config.buckling_mode_number,
+        amplitude=config.eigenmode_imperfection_amplitude,
+        dof_filter=config.imperfection_dof_filter,
+    )
+
+
+def run_nonlinear_capacity_workflow(
+    model: "FEModel",
+    reference_load_case: "LoadCase",
+    *,
+    nonlinear_load_case: Optional["LoadCase"] = None,
+    nonlinear_load_program: Optional[NonlinearLoadProgram] = None,
+    imperfection: Optional[Any] = None,
+    config: Optional[CapacityWorkflowConfig] = None,
+    status_callback: Optional[Callable[[str], None]] = None,
+) -> CapacityWorkflowResult:
+    """Run linear static -> buckling -> imperfection -> nonlinear capacity."""
+    config = config or CapacityWorkflowConfig()
+    start = time.perf_counter()
+    static_displacements, static_info = solve_linear(model, reference_load_case)
+    static_status = str((static_info.get("convergence_info") or {}).get("status", "unknown"))
+    if static_status != "converged":
+        raise RuntimeError(f"Static prestress solve did not converge: {static_status}")
+
+    prestress_states, prestress_summary = _recover_prestress(model, static_displacements)
+    buckling = solve_eigenvalue_buckling(model, prestress_states, num_modes=config.num_buckling_modes)
+    if not buckling.modes:
+        raise RuntimeError(f"Buckling solve returned no usable modes: {buckling.solver_status}")
+
+    mesh_adequacy = evaluate_mode_mesh_adequacy(
+        model,
+        buckling,
+        mode_number=config.buckling_mode_number,
+        min_elements_per_half_wave=config.mesh_min_elements_per_half_wave,
+    )
+    selected_imperfection = imperfection
+    if selected_imperfection is None:
+        selected_imperfection = default_eigenmode_imperfection(buckling, config)
+    imperfection_field = to_imperfection_field(model, selected_imperfection)
+    imperfect_model = apply_imperfection(model, imperfection_field, copy_model=config.copy_model)
+
+    if nonlinear_load_program is not None:
+        nonlinear_result = solve_static_nonlinear(
+            imperfect_model,
+            load_program=nonlinear_load_program,
+            max_load_factor=config.nonlinear_max_load_factor,
+            num_steps=config.nonlinear_num_steps,
+            max_iterations=config.nonlinear_max_iterations,
+            tolerance=config.nonlinear_tolerance,
+            num_layers=config.nonlinear_num_layers,
+            convergence_settings=config.nonlinear_convergence_settings,
+            resource_config=config.nonlinear_resource_config,
+            status_callback=status_callback,
+        )
+    else:
+        nonlinear_result = solve_static_nonlinear(
+            imperfect_model,
+            load_case=nonlinear_load_case or reference_load_case,
+            max_load_factor=config.nonlinear_max_load_factor,
+            num_steps=config.nonlinear_num_steps,
+            max_iterations=config.nonlinear_max_iterations,
+            tolerance=config.nonlinear_tolerance,
+            num_layers=config.nonlinear_num_layers,
+            convergence_settings=config.nonlinear_convergence_settings,
+            resource_config=config.nonlinear_resource_config,
+            status_callback=status_callback,
+        )
+
+    status = "completed" if nonlinear_result.converged else "nonlinear_not_converged"
+    diagnostics = {
+        "workflow_seconds": float(time.perf_counter() - start),
+        "model_name": model.name,
+        "node_count": int(model.mesh.num_nodes),
+        "element_count": int(model.mesh.num_elements),
+        "reference_load_case": getattr(reference_load_case, "name", None),
+        "nonlinear_load_case": getattr(nonlinear_load_case or reference_load_case, "name", None),
+        "config": config.__dict__,
+        "environment": {
+            "platform": platform.platform(),
+            "python": sys.version.split()[0],
+            "commit": _git_sha(),
+        },
+    }
+    if mesh_adequacy.warnings:
+        diagnostics["warnings"] = list(mesh_adequacy.warnings)
+
+    return CapacityWorkflowResult(
+        status=status,
+        static_displacements=static_displacements,
+        static_solver_info=static_info,
+        prestress_states=prestress_states,
+        prestress_summary=prestress_summary,
+        buckling_result=buckling,
+        imperfection=imperfection_field,
+        imperfect_model=imperfect_model,
+        nonlinear_result=nonlinear_result,
+        mesh_adequacy=mesh_adequacy,
+        diagnostics=diagnostics,
+    )
+
+
+def write_capacity_workflow_report(
+    result: CapacityWorkflowResult,
+    path: Path | str = DEFAULT_CAPACITY_WORKFLOW_PATH,
+) -> Path:
+    """Write a capacity workflow result report."""
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(result.to_dict(), indent=2, sort_keys=True, default=str) + "\n", encoding="utf-8")
+    return output
+
+
+def run_capacity_workflow_from_builder(
+    model_builder: Callable[[], "FEModel"],
+    load_case_builder: Callable[["FEModel"], "LoadCase"],
+    *,
+    config: Optional[CapacityWorkflowConfig] = None,
+    report_path: Path | str = DEFAULT_CAPACITY_WORKFLOW_PATH,
+) -> CapacityWorkflowResult:
+    """Convenience helper for scripted examples/tests."""
+    model = model_builder()
+    load_case = load_case_builder(model)
+    result = run_nonlinear_capacity_workflow(model, load_case, config=config)
+    write_capacity_workflow_report(result, report_path)
+    return result

anysolver/cases.py

@@ -0,0 +1,173 @@
+"""Analysis/result provenance containers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import hashlib
+import json
+from typing import Any, Dict, Mapping, Optional, Sequence, Tuple
+
+
+@dataclass(frozen=True)
+class LoadCaseRef:
+    """Stable reference to an input load case or combination."""
+
+    name: str
+    factor: float = 1.0
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AnalysisCase:
+    """Minimal traceable analysis-case descriptor."""
+
+    name: str
+    analysis_type: str
+    load_cases: Sequence[LoadCaseRef] = field(default_factory=tuple)
+    settings: Mapping[str, Any] = field(default_factory=dict)
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class PrestressCase:
+    """Reference to a prestress source used by KG or stress-stiffened analyses."""
+
+    name: str
+    source_result_case: str
+    sign_convention: str = "tension_positive_resultants_to_destabilizing_KG"
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ResultCase:
+    """Traceable result provenance for an analysis run."""
+
+    name: str
+    analysis_case: AnalysisCase
+    matrix_signature: Optional[str] = None
+    load_signature: Optional[str] = None
+    solver_backend: Optional[str] = None
+    recovery: Mapping[str, Any] = field(default_factory=dict)
+    warnings: Tuple[str, ...] = ()
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "analysis_case": {
+                "name": self.analysis_case.name,
+                "analysis_type": self.analysis_case.analysis_type,
+                "load_cases": [
+                    {"name": item.name, "factor": item.factor, "metadata": dict(item.metadata)}
+                    for item in self.analysis_case.load_cases
+                ],
+                "settings": dict(self.analysis_case.settings),
+                "metadata": dict(self.analysis_case.metadata),
+            },
+            "matrix_signature": self.matrix_signature,
+            "load_signature": self.load_signature,
+            "solver_backend": self.solver_backend,
+            "recovery": dict(self.recovery),
+            "warnings": list(self.warnings),
+            "metadata": dict(self.metadata),
+        }
+
+
+def load_case_ref(load_case: Any, factor: float = 1.0, metadata: Optional[Mapping[str, Any]] = None) -> LoadCaseRef:
+    """Build a stable provenance reference from a load-case-like object."""
+    name = "none" if load_case is None else str(getattr(load_case, "name", load_case))
+    return LoadCaseRef(name=name, factor=float(factor), metadata=dict(metadata or {}))
+
+
+def _json_signature(payload: Any) -> str:
+    text = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def matrix_signature_from_info(assembly_info: Mapping[str, Any]) -> Optional[str]:
+    """Hash matrix topology/revision data from assembly diagnostics."""
+    if not assembly_info:
+        return None
+    payload: Dict[str, Any] = {}
+    for key in ("stiffness", "mass", "geometric_stiffness", "damping"):
+        info = assembly_info.get(key)
+        if isinstance(info, Mapping):
+            payload[key] = {
+                "sparsity_signature": info.get("sparsity_signature"),
+                "revision_signature": info.get("revision_signature"),
+                "matrix_type": info.get("matrix_type"),
+                "total_dofs": info.get("total_dofs"),
+                "num_elements": info.get("num_elements"),
+            }
+    if not payload and isinstance(assembly_info.get("revision_signature"), Mapping):
+        payload["revision_signature"] = assembly_info.get("revision_signature")
+    return _json_signature(payload) if payload else None
+
+
+def load_signature_from_info(load_info: Mapping[str, Any]) -> Optional[str]:
+    """Hash load provenance data without storing the load vector itself."""
+    if not load_info:
+        return None
+    payload = {
+        "vector_type": load_info.get("vector_type"),
+        "load_case": load_info.get("load_case"),
+        "load_cases": load_info.get("load_cases"),
+        "load_norm": load_info.get("load_norm"),
+        "load_norms": load_info.get("load_norms"),
+        "revision_signature": load_info.get("revision_signature"),
+    }
+    return _json_signature(payload)
+
+
+def solver_backend_from_info(solver_info: Mapping[str, Any]) -> Optional[str]:
+    """Extract the sparse backend name from standard solver diagnostics."""
+    backend = solver_info.get("backend")
+    if isinstance(backend, Mapping):
+        return backend.get("backend")
+    convergence = solver_info.get("convergence_info")
+    if isinstance(convergence, Mapping):
+        backend = convergence.get("backend")
+        if isinstance(backend, Mapping):
+            return backend.get("backend")
+    return None
+
+
+def make_result_case(
+    *,
+    name: str,
+    analysis_type: str,
+    load_cases: Sequence[Any] = (),
+    assembly_info: Optional[Mapping[str, Any]] = None,
+    solver_info: Optional[Mapping[str, Any]] = None,
+    recovery: Optional[Mapping[str, Any]] = None,
+    settings: Optional[Mapping[str, Any]] = None,
+    metadata: Optional[Mapping[str, Any]] = None,
+    warnings: Sequence[str] = (),
+) -> ResultCase:
+    """Create a ResultCase from existing solver metadata."""
+    assembly_info = assembly_info or {}
+    load_info = assembly_info.get("load_matrix", assembly_info.get("load", {}))
+    analysis_case = AnalysisCase(
+        name=name,
+        analysis_type=analysis_type,
+        load_cases=tuple(load_case_ref(item) for item in load_cases),
+        settings=dict(settings or {}),
+        metadata=dict(metadata or {}),
+    )
+    return ResultCase(
+        name=name,
+        analysis_case=analysis_case,
+        matrix_signature=matrix_signature_from_info(assembly_info),
+        load_signature=load_signature_from_info(load_info if isinstance(load_info, Mapping) else {}),
+        solver_backend=solver_backend_from_info(solver_info or {}),
+        recovery=dict(recovery or {}),
+        warnings=tuple(str(item) for item in warnings),
+        metadata={
+            "matrix_revisions": {
+                key: value.get("revision_signature")
+                for key, value in assembly_info.items()
+                if isinstance(value, Mapping) and value.get("revision_signature") is not None
+            },
+            **dict(metadata or {}),
+        },
+    )