jupytermind 0.3.0

package/src/ai_materials_scientist/classical_monte_carlo.py

@@ -0,0 +1,165 @@
+"""Classical Monte Carlo lattice sampling module (DES-AIMS-030 / REQ-AIMS-030)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ai_materials_scientist.evidence import record_run
+from ai_materials_scientist.validation import (
+    check_finite_array,
+    register_validator,
+    validate_parameters,
+)
+
+_MODULE_NAME = "classical-monte-carlo"
+
+
+def _total_energy_per_site(spins: np.ndarray, J: float) -> float:
+    """-J * sum over unique nearest-neighbor bonds, divided by N sites."""
+    n = spins.size
+    right = np.roll(spins, -1, axis=1)
+    down = np.roll(spins, -1, axis=0)
+    bond_sum = np.sum(spins * right) + np.sum(spins * down)
+    return float(-J * bond_sum / n)
+
+
+def _local_field(spins: np.ndarray, i: int, j: int, L: int) -> int:
+    return (
+        spins[(i + 1) % L, j]
+        + spins[(i - 1) % L, j]
+        + spins[i, (j + 1) % L]
+        + spins[i, (j - 1) % L]
+    )
+
+
+def _sweep(spins: np.ndarray, L: int, J: float, T: float, rng: np.random.Generator) -> None:
+    """One raster-order full-lattice sweep of single-site Metropolis trial moves."""
+    random_values = rng.random((L, L))
+    for i in range(L):
+        for j in range(L):
+            s = spins[i, j]
+            neighbor_sum = _local_field(spins, i, j, L)
+            delta_e = 2.0 * J * s * neighbor_sum
+            if delta_e <= 0 or random_values[i, j] < np.exp(-delta_e / T):
+                spins[i, j] = -s
+
+
+def _mc_validator(params: dict) -> dict:
+    """DES-AIMS-002 registered validator for module_name='classical-monte-carlo'."""
+    if params["L"] <= 0:
+        return {"ok": False, "parameter": "L", "constraint": "L > 0"}
+    if params["J"] <= 0:
+        return {"ok": False, "parameter": "J", "constraint": "J > 0"}
+    if params["T"] <= 0:
+        return {"ok": False, "parameter": "T", "constraint": "T > 0"}
+    if params["equilibration_sweeps"] < 0:
+        return {
+            "ok": False,
+            "parameter": "equilibration_sweeps",
+            "constraint": "equilibration_sweeps >= 0",
+        }
+    if params["sampling_sweeps"] <= 0:
+        return {
+            "ok": False,
+            "parameter": "sampling_sweeps",
+            "constraint": "sampling_sweeps > 0",
+        }
+    initial_spins = params["initial_spins"]
+    finite_check = check_finite_array("initial_spins", initial_spins)
+    if not finite_check["ok"]:
+        return finite_check
+    if initial_spins.shape != (params["L"], params["L"]):
+        return {
+            "ok": False,
+            "parameter": "initial_spins",
+            "constraint": "initial_spins.shape == (L, L)",
+        }
+    if not np.all(np.isin(initial_spins, (-1, 1))):
+        return {
+            "ok": False,
+            "parameter": "initial_spins",
+            "constraint": "every spin must be +1 or -1",
+        }
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _mc_validator)
+
+
+def _validate(L, J, T, equilibration_sweeps, sampling_sweeps, initial_spins) -> None:
+    result = validate_parameters(
+        _MODULE_NAME,
+        {
+            "L": L,
+            "J": J,
+            "T": T,
+            "equilibration_sweeps": equilibration_sweeps,
+            "sampling_sweeps": sampling_sweeps,
+            "initial_spins": initial_spins,
+        },
+    )
+    if not result["ok"]:
+        raise ValueError(f"{result['parameter']}: {result['constraint']}")
+
+
+# @id CODE-AIMS-030
+# @implements REQ-AIMS-030 REQ-AIMS-003
+# @design DES-AIMS-030
+def run_classical_monte_carlo(
+    L: int,
+    J: float,
+    T: float,
+    equilibration_sweeps: int,
+    sampling_sweeps: int,
+    seed: int,
+    initial_spins: np.ndarray,
+) -> dict:
+    """Run Metropolis-criterion single-site Ising sweeps (REQ-AIMS-030).
+
+    Rejects any out-of-domain parameter (REQ-AIMS-003) before any spin-flip
+    trial move, and never mutates ``initial_spins``.
+    """
+    _validate(L, J, T, equilibration_sweeps, sampling_sweeps, initial_spins)
+
+    spins = initial_spins.astype(np.int64).copy()
+    rng = np.random.default_rng(seed)
+
+    for _ in range(equilibration_sweeps):
+        _sweep(spins, L, J, T, rng)
+
+    history = []
+    for _ in range(sampling_sweeps):
+        _sweep(spins, L, J, T, rng)
+        energy_per_site = _total_energy_per_site(spins, J)
+        magnetization_per_site = float(np.sum(spins)) / spins.size
+        history.append(
+            {"energy_per_site": energy_per_site, "magnetization_per_site": magnetization_per_site}
+        )
+
+    mean_energy = float(np.mean([h["energy_per_site"] for h in history]))
+    mean_abs_magnetization = float(np.mean([abs(h["magnetization_per_site"]) for h in history]))
+
+    return {
+        "mean_energy": mean_energy,
+        "mean_abs_magnetization": mean_abs_magnetization,
+        "history": history,
+    }
+
+
+# @id CODE-AIMS-901
+# @implements REQ-AIMS-030 REQ-AIMS-004 REQ-AIMS-005
+# @design DES-AIMS-030
+def run_classical_monte_carlo_with_evidence(**kwargs) -> dict:
+    """Run classical Monte Carlo and wrap the result as a reproducible RunRecord."""
+    result = run_classical_monte_carlo(**kwargs)
+    energies = np.array([h["energy_per_site"] for h in result["history"]], dtype=np.float64)
+    magnetizations = np.array(
+        [h["magnetization_per_site"] for h in result["history"]], dtype=np.float64
+    )
+    return record_run(
+        module_name=_MODULE_NAME,
+        unit_system="ising-reduced",
+        params={k: v for k, v in kwargs.items() if k != "initial_spins"},
+        arrays={"energy_history": energies, "magnetization_history": magnetizations},
+        seed=kwargs["seed"],
+    )

package/src/ai_materials_scientist/crystal_plasticity.py

@@ -0,0 +1,184 @@
+"""Single-point crystal plasticity slip activation module (DES-AIMS-050 / REQ-AIMS-050)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ai_materials_scientist.evidence import record_run
+from ai_materials_scientist.validation import (
+    check_finite_array,
+    register_validator,
+    validate_parameters,
+)
+
+_MODULE_NAME = "crystal-plasticity"
+
+# Table CP-12: fixed ordered (plane normal, slip direction) pairs, crystal frame.
+_SLIP_SYSTEMS = [
+    ((1, 1, 1), (0, 1, -1)),
+    ((1, 1, 1), (1, 0, -1)),
+    ((1, 1, 1), (1, -1, 0)),
+    ((1, 1, -1), (0, 1, 1)),
+    ((1, 1, -1), (1, 0, 1)),
+    ((1, 1, -1), (1, -1, 0)),
+    ((1, -1, 1), (0, 1, 1)),
+    ((1, -1, 1), (1, 0, -1)),
+    ((1, -1, 1), (1, 1, 0)),
+    ((-1, 1, 1), (0, 1, -1)),
+    ((-1, 1, 1), (1, 0, 1)),
+    ((-1, 1, 1), (1, 1, 0)),
+]
+
+_ORTHOGONALITY_TOL = 1e-6
+_DETERMINANT_TOL = 1e-6
+_SYMMETRY_TOL = 1e-6
+_MIN_STRESS_NORM = 1e-12
+
+
+def _cp_validator(params: dict) -> dict:
+    """DES-AIMS-002 registered validator for module_name='crystal-plasticity'."""
+    q = params["orientation_q"]
+    stress = params["stress_tensor"]
+    crss = params["crss"]
+    gamma_dot_0 = params["gamma_dot_0"]
+    n = params["n"]
+
+    q_check = check_finite_array("orientation_q", q)
+    if not q_check["ok"]:
+        return q_check
+    if q.shape != (3, 3):
+        return {"ok": False, "parameter": "orientation_q", "constraint": "shape == (3, 3)"}
+    if np.max(np.abs(q.T @ q - np.eye(3))) > _ORTHOGONALITY_TOL:
+        return {
+            "ok": False,
+            "parameter": "orientation_q",
+            "constraint": "Q must be orthogonal (Q^T Q == I within 1e-6)",
+        }
+    if abs(np.linalg.det(q) - 1.0) > _DETERMINANT_TOL:
+        return {
+            "ok": False,
+            "parameter": "orientation_q",
+            "constraint": "det(Q) == 1 within 1e-6",
+        }
+
+    stress_check = check_finite_array("stress_tensor", stress)
+    if not stress_check["ok"]:
+        return stress_check
+    if stress.shape != (3, 3):
+        return {"ok": False, "parameter": "stress_tensor", "constraint": "shape == (3, 3)"}
+    if np.max(np.abs(stress - stress.T)) > _SYMMETRY_TOL:
+        return {
+            "ok": False,
+            "parameter": "stress_tensor",
+            "constraint": "stress_tensor must be symmetric within 1e-6",
+        }
+    if np.linalg.norm(stress) < _MIN_STRESS_NORM:
+        return {
+            "ok": False,
+            "parameter": "stress_tensor",
+            "constraint": "Frobenius norm must be >= 1e-12",
+        }
+
+    if crss <= 0 or not np.isfinite(crss):
+        return {"ok": False, "parameter": "crss", "constraint": "crss > 0 and finite"}
+    if gamma_dot_0 <= 0 or not np.isfinite(gamma_dot_0):
+        return {
+            "ok": False,
+            "parameter": "gamma_dot_0",
+            "constraint": "gamma_dot_0 > 0 and finite",
+        }
+    if n <= 0 or not np.isfinite(n):
+        return {"ok": False, "parameter": "n", "constraint": "n > 0 and finite"}
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _cp_validator)
+
+
+def _validate(orientation_q, stress_tensor, crss, gamma_dot_0, n) -> None:
+    result = validate_parameters(
+        _MODULE_NAME,
+        {
+            "orientation_q": orientation_q,
+            "stress_tensor": stress_tensor,
+            "crss": crss,
+            "gamma_dot_0": gamma_dot_0,
+            "n": n,
+        },
+    )
+    if not result["ok"]:
+        raise ValueError(f"{result['parameter']}: {result['constraint']}")
+
+
+# @id CODE-AIMS-050
+# @implements REQ-AIMS-050 REQ-AIMS-003
+# @design DES-AIMS-050
+def run_crystal_plasticity(
+    orientation_q: np.ndarray,
+    stress_tensor: np.ndarray,
+    crss: float,
+    gamma_dot_0: float,
+    n: float,
+) -> dict:
+    """Evaluate Schmid factors, resolved shear stresses, and slip activation.
+
+    Rejects any out-of-domain parameter (REQ-AIMS-003) before any
+    Schmid-factor computation (REQ-AIMS-050).
+    """
+    _validate(orientation_q, stress_tensor, crss, gamma_dot_0, n)
+
+    stress_norm = np.linalg.norm(stress_tensor)
+    stress_hat = stress_tensor / stress_norm
+
+    schmid_factors = []
+    resolved_shear_stresses = []
+    active_systems = []
+    shear_strain_rates = []
+
+    for plane_normal, slip_direction in _SLIP_SYSTEMS:
+        n_crystal = np.array(plane_normal, dtype=np.float64)
+        d_crystal = np.array(slip_direction, dtype=np.float64)
+        n_sample = orientation_q @ n_crystal
+        d_sample = orientation_q @ d_crystal
+        n_hat = n_sample / np.linalg.norm(n_sample)
+        d_hat = d_sample / np.linalg.norm(d_sample)
+
+        schmid_tensor = np.outer(n_hat, d_hat)
+        schmid_factor = float(np.sum(schmid_tensor * stress_hat))
+        tau = schmid_factor * stress_norm
+
+        is_active = bool(abs(tau) >= crss)
+        shear_rate = gamma_dot_0 * np.sign(tau) * abs(tau / crss) ** n if is_active else 0.0
+
+        schmid_factors.append(schmid_factor)
+        resolved_shear_stresses.append(tau)
+        active_systems.append(is_active)
+        shear_strain_rates.append(float(shear_rate))
+
+    return {
+        "schmid_factors": schmid_factors,
+        "resolved_shear_stresses": resolved_shear_stresses,
+        "active_systems": active_systems,
+        "shear_strain_rates": shear_strain_rates,
+    }
+
+
+# @id CODE-AIMS-902
+# @implements REQ-AIMS-050 REQ-AIMS-004 REQ-AIMS-005
+# @design DES-AIMS-050
+def run_crystal_plasticity_with_evidence(**kwargs) -> dict:
+    """Run crystal plasticity and wrap the result as a reproducible RunRecord."""
+    result = run_crystal_plasticity(**kwargs)
+    return record_run(
+        module_name=_MODULE_NAME,
+        unit_system="stress-units-as-supplied",
+        params={k: v for k, v in kwargs.items() if k not in ("orientation_q", "stress_tensor")},
+        arrays={
+            "schmid_factors": np.array(result["schmid_factors"], dtype=np.float64),
+            "resolved_shear_stresses": np.array(
+                result["resolved_shear_stresses"], dtype=np.float64
+            ),
+            "shear_strain_rates": np.array(result["shear_strain_rates"], dtype=np.float64),
+        },
+        seed=None,
+    )

package/src/ai_materials_scientist/dispatch.py

@@ -0,0 +1,100 @@
+"""Request dispatcher for ai_materials_scientist (DES-AIMS-001)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ai_data_scientist.language_router import detect_language as _detect_language
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_MANIFEST_PATH = (
+    REPO_ROOT / ".github" / "skills" / "ai-materials-scientist" / "manifest.json"
+)
+
+
+def load_manifest(manifest_path: Path | None = None) -> dict:
+    """Load the static method-name-to-module manifest (DES-AIMS-001)."""
+    path = manifest_path or DEFAULT_MANIFEST_PATH
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _matched_methods(request_text: str, manifest: dict) -> list[str]:
+    lowered = request_text.lower()
+    matched = []
+    for method, entry in manifest.items():
+        names = entry.get("names", {})
+        candidates = list(names.get("en", [])) + list(names.get("ja", []))
+        if any(
+            (candidate.lower() in lowered) if candidate.isascii() else (candidate in request_text)
+            for candidate in candidates
+        ):
+            matched.append(method)
+    return matched
+
+
+# @id CODE-AIMS-001
+# @implements REQ-AIMS-001 REQ-AIMS-002
+# @design DES-AIMS-001
+def dispatch(
+    request_text: str,
+    language: str | None = None,
+    manifest_path: Path | None = None,
+) -> dict:
+    """Classify ``request_text`` and dispatch to exactly one matched module.
+
+    ``language`` may be supplied explicitly; otherwise it is detected from
+    ``request_text`` (REQ-AIMS-001) and propagated into the result so every
+    downstream (module handler, clarification, rejection) path can render
+    its user-facing text in that language.
+    """
+    if not isinstance(request_text, str):
+        raise ValueError("request_text: must be a str")  # noqa: TRY004
+    if language is not None and language not in ("en", "ja"):
+        raise ValueError("language: must be 'en' or 'ja' when explicitly supplied")
+    detected_language = language or _detect_language(request_text)
+    manifest = load_manifest(manifest_path)
+    matched = _matched_methods(request_text, manifest)
+
+    if len(matched) == 1:
+        return {
+            "outcome": "dispatch",
+            "module": matched[0],
+            "language": detected_language,
+            # Populated once the matched module's handler is implemented and
+            # wired in (DES-AIMS-010..070); absent any handler yet, this is
+            # explicitly None rather than an omitted key, per DES-AIMS-001's
+            # DispatchResult {module, handler_result} contract.
+            "handler_result": None,
+        }
+    if len(matched) > 1:
+        return {
+            "outcome": "clarification",
+            "candidates": matched,
+            "language": detected_language,
+            "clarification_question": _render_clarification(matched, detected_language),
+        }
+    return {
+        "outcome": "rejected",
+        "language": detected_language,
+        "rejected_method": _render_rejection(detected_language),
+    }
+
+
+def _render_clarification(candidates: list[str], language: str) -> str:
+    """Render a single-sentence clarification question in ``language``.
+
+    Method names (e.g. ``phase-field``) are the only permitted non-``language``
+    tokens, per REQ-AIMS-001's acceptance.
+    """
+    names = "、".join(candidates) if language == "ja" else ", ".join(candidates)
+    if language == "ja":
+        return f"{names} のどちらを意図していますか。明確にしてください。"
+    return f"Did you mean {names}? Please clarify which method you want."
+
+
+def _render_rejection(language: str) -> str:
+    """Render a single-sentence rejection message in ``language``."""
+    if language == "ja":
+        return "対応するシミュレーション手法が要求から認識されませんでした。"
+    return "No supported simulation method was recognized in your request."

package/src/ai_materials_scientist/evidence.py

@@ -0,0 +1,84 @@
+"""Run evidence recording and JSON-safe codec (DES-AIMS-003 / REQ-AIMS-004/005)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+SCHEMA_VERSION = 1
+
+
+# @id CODE-AIMS-003
+# @implements REQ-AIMS-004 REQ-AIMS-005
+# @design DES-AIMS-003
+def record_run(
+    module_name: str,
+    unit_system: str,
+    params: dict[str, Any],
+    arrays: dict[str, np.ndarray],
+    seed: int | None,
+    *,
+    allow_integer_arrays: frozenset[str] = frozenset(),
+) -> dict:
+    """Build a RunRecord with exactly `metadata`, `parameters`, `arrays`.
+
+    ``seed`` is the explicit integer seed for a stochastic module, or
+    ``None`` for a deterministic module (REQ-AIMS-004). Every array must be
+    ``float64`` unless its name is listed in ``allow_integer_arrays`` (a
+    module's own requirement explicitly stating an integer array).
+    """
+    for name, array in arrays.items():
+        if name in allow_integer_arrays:
+            continue
+        if array.dtype != np.float64:
+            raise ValueError(
+                f"array '{name}' must be float64 unless explicitly declared integer "
+                f"(REQ-AIMS-004), got dtype={array.dtype}"
+            )
+    return {
+        "metadata": {
+            "module": module_name,
+            "unit_system": unit_system,
+            "schema_version": SCHEMA_VERSION,
+            "seed": seed,
+        },
+        "parameters": dict(params),
+        "arrays": dict(arrays),
+    }
+
+
+# @id CODE-AIMS-903
+# @implements REQ-AIMS-004
+# @design DES-AIMS-003
+def to_json(run_record: dict) -> dict:
+    """Encode a RunRecord's `arrays` ndarrays as {dtype, shape, data}."""
+    encoded_arrays = {}
+    for name, array in run_record["arrays"].items():
+        encoded_arrays[name] = {
+            "dtype": str(array.dtype),
+            "shape": list(array.shape),
+            "data": array.tolist(),
+        }
+    return {
+        "metadata": dict(run_record["metadata"]),
+        "parameters": dict(run_record["parameters"]),
+        "arrays": encoded_arrays,
+    }
+
+
+# @id CODE-AIMS-904
+# @implements REQ-AIMS-004
+# @design DES-AIMS-003
+def from_json(json_safe_record: dict) -> dict:
+    """Reconstruct a RunRecord from its JSON-safe encoding (inverse of to_json)."""
+    decoded_arrays = {}
+    for name, encoded in json_safe_record["arrays"].items():
+        decoded_arrays[name] = np.array(encoded["data"], dtype=encoded["dtype"]).reshape(
+            encoded["shape"]
+        )
+    return {
+        "metadata": dict(json_safe_record["metadata"]),
+        "parameters": dict(json_safe_record["parameters"]),
+        "arrays": decoded_arrays,
+    }