jupytermind 0.3.0

package/src/ai_materials_scientist/fem.py

@@ -0,0 +1,279 @@
+"""Simplified finite-element field solver module (DES-AIMS-060 / REQ-AIMS-060)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ai_materials_scientist.evidence import record_run
+from ai_materials_scientist.validation import register_validator, validate_parameters
+
+_MODULE_NAME = "finite-element"
+_ALLOWED_MESH_TYPES = ("line", "quad2d")
+_ALLOWED_ELEMENT_ORDER = "linear"
+_RECIPROCAL_CONDITION_TOL = 1e-10
+_GAUSS_POINT = 1.0 / np.sqrt(3.0)
+_GAUSS_POINTS = [
+    (-_GAUSS_POINT, -_GAUSS_POINT),
+    (_GAUSS_POINT, -_GAUSS_POINT),
+    (_GAUSS_POINT, _GAUSS_POINT),
+    (-_GAUSS_POINT, _GAUSS_POINT),
+]
+
+
+def _quad_shape_derivs(xi: float, eta: float) -> tuple[np.ndarray, np.ndarray]:
+    dN_dxi = 0.25 * np.array([-(1 - eta), (1 - eta), (1 + eta), -(1 + eta)])
+    dN_deta = 0.25 * np.array([-(1 - xi), -(1 + xi), (1 + xi), (1 - xi)])
+    return dN_dxi, dN_deta
+
+
+def _plane_strain_constitutive(E: float, nu: float) -> np.ndarray:
+    factor = E / ((1 + nu) * (1 - 2 * nu))
+    return factor * np.array(
+        [
+            [1 - nu, nu, 0],
+            [nu, 1 - nu, 0],
+            [0, 0, (1 - 2 * nu) / 2],
+        ]
+    )
+
+
+def _assemble_line_heat(mesh: dict, conductivity: float) -> tuple[np.ndarray, np.ndarray]:
+    node_coords = np.asarray(mesh["node_coords"], dtype=np.float64)
+    n = len(node_coords)
+    K = np.zeros((n, n))
+    f = np.zeros(n)
+    for i, j in mesh["elements"]:
+        length = abs(node_coords[j] - node_coords[i])
+        k_local = (conductivity / length) * np.array([[1, -1], [-1, 1]])
+        for a, node_a in enumerate((i, j)):
+            for b, node_b in enumerate((i, j)):
+                K[node_a, node_b] += k_local[a, b]
+    return K, f
+
+
+def _assemble_quad_heat(mesh: dict, conductivity: float) -> tuple[np.ndarray, np.ndarray]:
+    node_coords = np.asarray(mesh["node_coords"], dtype=np.float64)
+    n = len(node_coords)
+    K = np.zeros((n, n))
+    f = np.zeros(n)
+    for element in mesh["elements"]:
+        coords = node_coords[list(element)]
+        k_local = np.zeros((4, 4))
+        for xi, eta in _GAUSS_POINTS:
+            dN_dxi, dN_deta = _quad_shape_derivs(xi, eta)
+            jacobian = np.array([dN_dxi, dN_deta]) @ coords
+            det_j = np.linalg.det(jacobian)
+            jacobian_inv = np.linalg.inv(jacobian)
+            grads = jacobian_inv @ np.array([dN_dxi, dN_deta])
+            k_local += conductivity * (grads.T @ grads) * det_j
+        for a, node_a in enumerate(element):
+            for b, node_b in enumerate(element):
+                K[node_a, node_b] += k_local[a, b]
+    return K, f
+
+
+def _assemble_quad_elasticity(
+    mesh: dict, youngs_modulus: float, poisson_ratio: float
+) -> tuple[np.ndarray, np.ndarray]:
+    node_coords = np.asarray(mesh["node_coords"], dtype=np.float64)
+    n_nodes = len(node_coords)
+    n_dofs = n_nodes * 2
+    K = np.zeros((n_dofs, n_dofs))
+    f = np.zeros(n_dofs)
+    D = _plane_strain_constitutive(youngs_modulus, poisson_ratio)
+    for element in mesh["elements"]:
+        coords = node_coords[list(element)]
+        k_local = np.zeros((8, 8))
+        for xi, eta in _GAUSS_POINTS:
+            dN_dxi, dN_deta = _quad_shape_derivs(xi, eta)
+            jacobian = np.array([dN_dxi, dN_deta]) @ coords
+            det_j = np.linalg.det(jacobian)
+            jacobian_inv = np.linalg.inv(jacobian)
+            grads = jacobian_inv @ np.array([dN_dxi, dN_deta])
+            dN_dx, dN_dy = grads[0], grads[1]
+            B = np.zeros((3, 8))
+            for a in range(4):
+                B[0, 2 * a] = dN_dx[a]
+                B[1, 2 * a + 1] = dN_dy[a]
+                B[2, 2 * a] = dN_dy[a]
+                B[2, 2 * a + 1] = dN_dx[a]
+            k_local += B.T @ D @ B * det_j
+        dofs = [2 * node + c for node in element for c in (0, 1)]
+        for a, dof_a in enumerate(dofs):
+            for b, dof_b in enumerate(dofs):
+                K[dof_a, dof_b] += k_local[a, b]
+    return K, f
+
+
+def _ndof_per_node(physics: str) -> int:
+    return 2 if physics == "plane_strain_elasticity" else 1
+
+
+def _fem_validator(params: dict) -> dict:
+    """DES-AIMS-002 registered validator for module_name='finite-element'."""
+    mesh = params["mesh"]
+    material_properties = params["material_properties"]
+    physics = params["physics"]
+
+    if physics not in ("heat_conduction", "plane_strain_elasticity"):
+        return {
+            "ok": False,
+            "parameter": "physics",
+            "constraint": "physics in ('heat_conduction', 'plane_strain_elasticity')",
+        }
+    if mesh["mesh_type"] not in _ALLOWED_MESH_TYPES:
+        return {
+            "ok": False,
+            "parameter": "mesh",
+            "constraint": f"mesh_type in {_ALLOWED_MESH_TYPES} (unstructured mesh rejected)",
+        }
+    if mesh["element_order"] != _ALLOWED_ELEMENT_ORDER:
+        return {
+            "ok": False,
+            "parameter": "element_order",
+            "constraint": "element_order == 'linear' (higher-order element rejected)",
+        }
+    if material_properties.get("nonlinear", False):
+        return {
+            "ok": False,
+            "parameter": "material_properties",
+            "constraint": "material law must be linear",
+        }
+    if physics == "plane_strain_elasticity" and mesh["mesh_type"] == "line":
+        return {
+            "ok": False,
+            "parameter": "physics",
+            "constraint": "plane_strain_elasticity is not supported on a 1D line mesh",
+        }
+
+    if physics == "heat_conduction":
+        conductivity = material_properties["conductivity"]
+        if conductivity <= 0:
+            return {
+                "ok": False,
+                "parameter": "conductivity",
+                "constraint": "conductivity > 0",
+            }
+    elif physics == "plane_strain_elasticity":
+        youngs_modulus = material_properties["youngs_modulus"]
+        poisson_ratio = material_properties["poisson_ratio"]
+        if youngs_modulus <= 0:
+            return {
+                "ok": False,
+                "parameter": "youngs_modulus",
+                "constraint": "youngs_modulus > 0",
+            }
+        if not (-1 < poisson_ratio < 0.5):
+            return {
+                "ok": False,
+                "parameter": "poisson_ratio",
+                "constraint": "-1 < poisson_ratio < 0.5",
+            }
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _fem_validator)
+
+
+def _validate(mesh, material_properties, boundary_conditions, physics) -> None:
+    result = validate_parameters(
+        _MODULE_NAME,
+        {
+            "mesh": mesh,
+            "material_properties": material_properties,
+            "boundary_conditions": boundary_conditions,
+            "physics": physics,
+        },
+    )
+    if not result["ok"]:
+        raise ValueError(f"{result['parameter']}: {result['constraint']}")
+
+
+# @id CODE-AIMS-060
+# @implements REQ-AIMS-060 REQ-AIMS-003
+# @design DES-AIMS-060
+def assemble_and_check(
+    mesh: dict, material_properties: dict, boundary_conditions: dict, physics: str
+) -> dict:
+    """Assemble K, partition DOFs, and verify constrained_stiffness is well-posed.
+
+    Rejects an empty free-DOF set or a singular/underconstrained
+    constrained_stiffness (REQ-AIMS-003) before any solve is attempted.
+    """
+    _validate(mesh, material_properties, boundary_conditions, physics)
+
+    if physics == "heat_conduction":
+        if mesh["mesh_type"] == "line":
+            K, f = _assemble_line_heat(mesh, material_properties["conductivity"])
+        else:
+            K, f = _assemble_quad_heat(mesh, material_properties["conductivity"])
+    else:  # plane_strain_elasticity
+        K, f = _assemble_quad_elasticity(
+            mesh, material_properties["youngs_modulus"], material_properties["poisson_ratio"]
+        )
+
+    n_dofs = K.shape[0]
+    prescribed = boundary_conditions.get("prescribed", {})
+    loads = boundary_conditions.get("loads", {})
+    for dof, value in loads.items():
+        f[dof] += value
+
+    prescribed_dofs = sorted(prescribed.keys())
+    free_dofs = [d for d in range(n_dofs) if d not in prescribed]
+
+    if len(free_dofs) == 0:
+        return {"ok": False, "violated_condition": "free_dofs set is empty"}
+
+    u_prescribed = np.array([prescribed[d] for d in prescribed_dofs])
+    f_adjusted = f[free_dofs] - K[np.ix_(free_dofs, prescribed_dofs)] @ u_prescribed
+    constrained_stiffness = K[np.ix_(free_dofs, free_dofs)]
+
+    reciprocal_cond = 1.0 / np.linalg.cond(constrained_stiffness, 2)
+    if reciprocal_cond < _RECIPROCAL_CONDITION_TOL:
+        return {
+            "ok": False,
+            "violated_condition": "constrained_stiffness is singular/underconstrained",
+        }
+
+    return {
+        "ok": True,
+        "constrained_stiffness": constrained_stiffness,
+        "free_dofs": free_dofs,
+        "prescribed_dofs": prescribed_dofs,
+        "u_prescribed": u_prescribed,
+        "rhs_adjusted": f_adjusted,
+        "n_dofs": n_dofs,
+    }
+
+
+# @id CODE-AIMS-905
+# @implements REQ-AIMS-060
+# @design DES-AIMS-060
+def run_fem(mesh: dict, material_properties: dict, boundary_conditions: dict, physics: str) -> dict:
+    """Assemble and solve the FEM system for the nodal field (REQ-AIMS-060)."""
+    assembly = assemble_and_check(mesh, material_properties, boundary_conditions, physics)
+    if not assembly["ok"]:
+        raise ValueError(f"free_dofs: {assembly['violated_condition']}")
+
+    u = np.zeros(assembly["n_dofs"])
+    u[assembly["prescribed_dofs"]] = assembly["u_prescribed"]
+    u[assembly["free_dofs"]] = np.linalg.solve(
+        assembly["constrained_stiffness"], assembly["rhs_adjusted"]
+    )
+
+    return {"nodal_values": u, "mesh": mesh}
+
+
+# @id CODE-AIMS-906
+# @implements REQ-AIMS-060 REQ-AIMS-004 REQ-AIMS-005
+# @design DES-AIMS-060
+def run_fem_with_evidence(**kwargs) -> dict:
+    """Run FEM and wrap the result as a reproducible RunRecord (temperatures in Kelvin)."""
+    result = run_fem(**kwargs)
+    return record_run(
+        module_name=_MODULE_NAME,
+        unit_system="si-kelvin-meter" if kwargs["physics"] == "heat_conduction" else "si",
+        params={k: v for k, v in kwargs.items() if k != "mesh"},
+        arrays={"nodal_values": np.asarray(result["nodal_values"], dtype=np.float64)},
+        seed=None,
+    )

package/src/ai_materials_scientist/kinetic_monte_carlo.py

@@ -0,0 +1,145 @@
+"""Kinetic Monte Carlo event-driven evolution module (DES-AIMS-040 / REQ-AIMS-040)."""
+
+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 = "kinetic-monte-carlo"
+_NUM_REALIZATIONS = 200
+_HOP_DIRECTIONS = np.array([[1, 0], [-1, 0], [0, 1], [0, -1]])
+
+
+def _kmc_validator(params: dict) -> dict:
+    """DES-AIMS-002 registered validator for module_name='kinetic-monte-carlo'."""
+    gamma = params["gamma"]
+    a = params["a"]
+    total_time = params["total_time"]
+    output_times = params["output_times"]
+
+    if gamma <= 0:
+        return {"ok": False, "parameter": "gamma", "constraint": "gamma > 0"}
+    if a <= 0:
+        return {"ok": False, "parameter": "a", "constraint": "a > 0"}
+    if total_time <= 0:
+        return {"ok": False, "parameter": "total_time", "constraint": "total_time > 0"}
+    if len(output_times) == 0:
+        return {
+            "ok": False,
+            "parameter": "output_times",
+            "constraint": "output_times must be non-empty",
+        }
+    finite_check = check_finite_array("output_times", np.asarray(output_times, dtype=np.float64))
+    if not finite_check["ok"]:
+        return finite_check
+    for output_time in output_times:
+        if not (0 < output_time <= total_time):
+            return {
+                "ok": False,
+                "parameter": "output_time",
+                "constraint": "0 < output_time <= total_time",
+            }
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _kmc_validator)
+
+
+def _validate(gamma, a, total_time, output_times) -> None:
+    result = validate_parameters(
+        _MODULE_NAME,
+        {"gamma": gamma, "a": a, "total_time": total_time, "output_times": output_times},
+    )
+    if not result["ok"]:
+        raise ValueError(f"{result['parameter']}: {result['constraint']}")
+
+
+# @id CODE-AIMS-040
+# @implements REQ-AIMS-040
+# @design DES-AIMS-040
+def run_kmc_single_realization(
+    gamma: float, a: float, total_time: float, seed: int
+) -> list[tuple[float, np.ndarray]]:
+    """Run one rejection-free (BKL) realization; never advances past total_time.
+
+    Returns the list of (event_time, unwrapped_position) pairs, starting
+    with the step-zero event (0.0, origin).
+    """
+    rng = np.random.default_rng(seed)
+    total_rate = 4.0 * gamma
+    t = 0.0
+    pos = np.zeros(2)
+    events: list[tuple[float, np.ndarray]] = [(t, pos.copy())]
+
+    while True:
+        dt = rng.exponential(1.0 / total_rate)
+        if t + dt > total_time:
+            break
+        t = t + dt
+        direction = rng.integers(0, 4)
+        pos = pos + _HOP_DIRECTIONS[direction] * a
+        events.append((t, pos.copy()))
+
+    return events
+
+
+def _displacement_at(events: list[tuple[float, np.ndarray]], query_time: float) -> np.ndarray:
+    """Displacement after the last event at or before query_time."""
+    last_position = events[0][1]
+    for event_time, position in events:
+        if event_time > query_time:
+            break
+        last_position = position
+    return last_position
+
+
+# @id CODE-AIMS-907
+# @implements REQ-AIMS-040 REQ-AIMS-003
+# @design DES-AIMS-040
+def run_kinetic_monte_carlo(
+    gamma: float, a: float, total_time: float, output_times: list[float], base_seed: int
+) -> dict:
+    """Run 200 independent BKL realizations and report displacements (REQ-AIMS-040).
+
+    Rejects any out-of-domain parameter (REQ-AIMS-003) before any hop event
+    is drawn.
+    """
+    _validate(gamma, a, total_time, output_times)
+
+    realization_seeds = [base_seed + i for i in range(_NUM_REALIZATIONS)]
+    displacements = np.zeros((len(output_times), _NUM_REALIZATIONS, 2))
+
+    for realization_index, seed in enumerate(realization_seeds):
+        events = run_kmc_single_realization(gamma, a, total_time, seed)
+        for time_index, query_time in enumerate(output_times):
+            displacements[time_index, realization_index] = _displacement_at(events, query_time)
+
+    return {
+        "displacements": displacements,
+        "times": list(output_times),
+        "realization_seeds": realization_seeds,
+    }
+
+
+# @id CODE-AIMS-908
+# @implements REQ-AIMS-040 REQ-AIMS-004 REQ-AIMS-005
+# @design DES-AIMS-040
+def run_kinetic_monte_carlo_with_evidence(**kwargs) -> dict:
+    """Run kinetic Monte Carlo and wrap the result as a reproducible RunRecord."""
+    result = run_kinetic_monte_carlo(**kwargs)
+    return record_run(
+        module_name=_MODULE_NAME,
+        unit_system="lattice-hop-reduced",
+        params={k: v for k, v in kwargs.items() if k != "output_times"},
+        arrays={
+            "displacements": result["displacements"],
+            "times": np.array(result["times"], dtype=np.float64),
+        },
+        seed=kwargs["base_seed"],
+    )

package/src/ai_materials_scientist/molecular_dynamics.py

@@ -0,0 +1,240 @@
+"""Molecular dynamics trajectory integration module (DES-AIMS-020 / REQ-AIMS-020)."""
+
+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,
+    check_positive_output_interval,
+    check_positive_step_count,
+    register_validator,
+    validate_parameters,
+)
+
+_MODULE_NAME = "molecular-dynamics"
+_MIN_SEPARATION_SIGMA = 0.8
+
+
+# @id CODE-AIMS-020
+# @implements REQ-AIMS-020
+# @design DES-AIMS-020
+def compute_dt_bound(epsilon: float, sigma: float, mass: float) -> float:
+    """Conservative explicit stability bound dt_bound = 0.005*sigma*sqrt(mass/epsilon)."""
+    return 0.005 * sigma * (mass / epsilon) ** 0.5
+
+
+def _minimum_image_displacements(positions: np.ndarray, box_length: float) -> np.ndarray:
+    """Pairwise displacement[i, j] = positions[i] - positions[j] under min-image."""
+    diff = positions[:, None, :] - positions[None, :, :]
+    return diff - box_length * np.round(diff / box_length)
+
+
+def _pair_distances(positions: np.ndarray, box_length: float) -> np.ndarray:
+    disp = _minimum_image_displacements(positions, box_length)
+    dist = np.sqrt(np.sum(disp**2, axis=-1))
+    np.fill_diagonal(dist, np.inf)
+    return dist
+
+
+def _lj_potential(r: np.ndarray, epsilon: float, sigma: float) -> np.ndarray:
+    sr6 = (sigma / r) ** 6
+    return 4 * epsilon * (sr6**2 - sr6)
+
+
+def _lj_radial_force_magnitude(r: np.ndarray, epsilon: float, sigma: float) -> np.ndarray:
+    """F(r) = -dU/dr; positive is repulsive."""
+    sr6 = (sigma / r) ** 6
+    return 24 * epsilon / r * (2 * sr6**2 - sr6)
+
+
+def _forces_and_potential(
+    positions: np.ndarray, box_length: float, cutoff: float, epsilon: float, sigma: float
+) -> tuple[np.ndarray, float]:
+    """Shifted-force Lennard-Jones forces (per particle) and total pair potential."""
+    n = positions.shape[0]
+    disp = _minimum_image_displacements(positions, box_length)
+    dist = np.sqrt(np.sum(disp**2, axis=-1))
+    np.fill_diagonal(dist, np.inf)
+
+    within_cutoff = dist < cutoff
+    f_cutoff = _lj_radial_force_magnitude(np.array(cutoff), epsilon, sigma)
+    u_cutoff = _lj_potential(np.array(cutoff), epsilon, sigma)
+
+    forces = np.zeros_like(positions)
+    total_potential = 0.0
+    for i in range(n):
+        for j in range(i + 1, n):
+            if not within_cutoff[i, j]:
+                continue
+            r = dist[i, j]
+            f_shifted = _lj_radial_force_magnitude(r, epsilon, sigma) - f_cutoff
+            u_shifted = _lj_potential(r, epsilon, sigma) - u_cutoff - (r - cutoff) * (-f_cutoff)
+            unit_vec = disp[i, j] / r
+            force_on_i = f_shifted * unit_vec
+            forces[i] += force_on_i
+            forces[j] -= force_on_i
+            total_potential += u_shifted
+    return forces, total_potential
+
+
+def _md_validator(params: dict) -> dict:
+    """DES-AIMS-002 registered validator for module_name='molecular-dynamics'."""
+    lj_params = params["lj_params"]
+    mass = lj_params["mass"]
+    epsilon = lj_params["epsilon"]
+    sigma = lj_params["sigma"]
+    box_length = params["box_length"]
+    cutoff = params["cutoff"]
+    dt = params["dt"]
+
+    if mass <= 0:
+        return {"ok": False, "parameter": "mass", "constraint": "mass > 0"}
+    if epsilon <= 0:
+        return {"ok": False, "parameter": "epsilon", "constraint": "epsilon > 0"}
+    if sigma <= 0:
+        return {"ok": False, "parameter": "sigma", "constraint": "sigma > 0"}
+    if box_length <= 0:
+        return {"ok": False, "parameter": "box_length", "constraint": "box_length > 0"}
+    if dt <= 0:
+        return {"ok": False, "parameter": "dt", "constraint": "dt > 0"}
+    if cutoff <= 0:
+        return {"ok": False, "parameter": "cutoff", "constraint": "cutoff > 0"}
+
+    positions_check = check_finite_array("positions0", params["positions0"])
+    if not positions_check["ok"]:
+        return positions_check
+    velocities_check = check_finite_array("velocities0", params["velocities0"])
+    if not velocities_check["ok"]:
+        return velocities_check
+    steps_check = check_positive_step_count(params["steps"])
+    if not steps_check["ok"]:
+        return steps_check
+    interval_check = check_positive_output_interval(params["output_every"])
+    if not interval_check["ok"]:
+        return interval_check
+
+    if cutoff > box_length / 2:
+        return {
+            "ok": False,
+            "parameter": "cutoff",
+            "constraint": "cutoff <= box_length / 2",
+        }
+
+    distances = _pair_distances(params["positions0"], box_length)
+    min_separation = _MIN_SEPARATION_SIGMA * sigma
+    if np.any(distances < min_separation):
+        return {
+            "ok": False,
+            "parameter": "positions0",
+            "constraint": f"every pairwise separation >= {min_separation} (0.8*sigma)",
+        }
+
+    dt_bound = compute_dt_bound(epsilon, sigma, mass)
+    if dt > dt_bound:
+        return {
+            "ok": False,
+            "parameter": "dt",
+            "constraint": f"dt <= dt_bound ({dt_bound})",
+        }
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _md_validator)
+
+
+def _validate(positions0, velocities0, lj_params, box_length, cutoff, dt, steps, output_every):
+    result = validate_parameters(
+        _MODULE_NAME,
+        {
+            "positions0": positions0,
+            "velocities0": velocities0,
+            "lj_params": lj_params,
+            "box_length": box_length,
+            "cutoff": cutoff,
+            "dt": dt,
+            "steps": steps,
+            "output_every": output_every,
+        },
+    )
+    if not result["ok"]:
+        raise ValueError(f"{result['parameter']}: {result['constraint']}")
+
+
+# @id CODE-AIMS-909
+# @implements REQ-AIMS-020 REQ-AIMS-003
+# @design DES-AIMS-020
+def run_molecular_dynamics(
+    positions0: np.ndarray,
+    velocities0: np.ndarray,
+    lj_params: dict,
+    box_length: float,
+    cutoff: float,
+    dt: float,
+    steps: int,
+    output_every: int,
+) -> dict:
+    """Integrate Newton's equations of motion with velocity-Verlet (REQ-AIMS-020).
+
+    Rejects any out-of-domain parameter (REQ-AIMS-003) before performing any
+    integration step or mutating ``positions0``/``velocities0``.
+    """
+    _validate(positions0, velocities0, lj_params, box_length, cutoff, dt, steps, output_every)
+
+    epsilon = lj_params["epsilon"]
+    sigma = lj_params["sigma"]
+    mass = lj_params["mass"]
+
+    positions = positions0.astype(np.float64).copy()
+    velocities = velocities0.astype(np.float64).copy()
+
+    def _kinetic(v: np.ndarray) -> float:
+        return float(0.5 * mass * np.sum(v**2))
+
+    forces, potential = _forces_and_potential(positions, box_length, cutoff, epsilon, sigma)
+    accel = forces / mass
+
+    snapshots = [{"positions": positions.copy(), "velocities": velocities.copy()}]
+    energies = [_kinetic(velocities) + potential]
+    times = [0.0]
+
+    for step in range(1, steps + 1):
+        velocities_half = velocities + 0.5 * dt * accel
+        positions = positions + dt * velocities_half
+        forces, potential = _forces_and_potential(positions, box_length, cutoff, epsilon, sigma)
+        accel = forces / mass
+        velocities = velocities_half + 0.5 * dt * accel
+
+        if step % output_every == 0:
+            snapshots.append({"positions": positions.copy(), "velocities": velocities.copy()})
+            energies.append(_kinetic(velocities) + potential)
+            times.append(step * dt)
+
+    dt_bound = compute_dt_bound(epsilon, sigma, mass)
+    return {
+        "snapshots": snapshots,
+        "energies": energies,
+        "times": times,
+        "dt_bound": dt_bound,
+    }
+
+
+# @id CODE-AIMS-910
+# @implements REQ-AIMS-020 REQ-AIMS-004 REQ-AIMS-005
+# @design DES-AIMS-020
+def run_molecular_dynamics_with_evidence(**kwargs) -> dict:
+    """Run molecular dynamics and wrap the result as a reproducible RunRecord."""
+    result = run_molecular_dynamics(**kwargs)
+    return record_run(
+        module_name=_MODULE_NAME,
+        unit_system="lennard-jones-reduced",
+        params={k: v for k, v in kwargs.items() if k not in ("positions0", "velocities0")},
+        arrays={
+            "positions": np.stack([s["positions"] for s in result["snapshots"]]),
+            "velocities": np.stack([s["velocities"] for s in result["snapshots"]]),
+            "energies": np.array(result["energies"], dtype=np.float64),
+            "times": np.array(result["times"], dtype=np.float64),
+        },
+        seed=None,
+    )