vibe-sketcherDocumentation

Source code for vibesketcher.document.periodic_capabilities

"""What the vibe-qc engine can do for periodic tasks, pinned to one engine release (#208).

Recipe planners in :mod:`vibesketcher.document.periodic_recipes` consult this
table before they write anything. A task the pinned engine does not offer on a
route is refused with the engine's own reason and the tracker item that owns
the missing capability; it is never mapped to a nearby route. The table is
read from the engine's front door (``vibeqc.run_periodic_job`` and the
library entry points it names), not inferred from method names: a model
name that is not listed here (ORB, MatterSim, UFF4MOF, DFTB+ and so on) is
not an admission, and molecular MACE admissions do not carry over to
periodic cells or the other way round.

Statuses:

- ``admitted``: the pinned engine runs the task on that route and the
  sketcher writes the input;
- ``library``: the engine has a library function for the task but the
  sketcher writes no input for it (the reason says what to call);
- ``refused``: the engine refuses the task on that route.

Update ``ENGINE`` and the rows together when the pinned engine changes.
"""

from __future__ import annotations

from typing import Any, Literal

from pydantic import BaseModel, ConfigDict

#: The engine release the table was read from. ``source`` names the commit.
ENGINE: dict[str, str] = {
    "program": "vibe-qc",
    "version": "0.18.12",
    "source": "vibe-qc main at c9ba9cd6 (2026-11-10)",
    "front_door": "vibeqc.run_periodic_job",
}

Task = Literal[
    "energy",
    "forces",
    "relax_positions",
    "relax_positions_frozen",
    "stress",
    "relax_cell",
    "hessian",
    "phonons",
    "ir_intensities",
    "free_energy",
]
Status = Literal["admitted", "library", "refused"]
MODELS = ("pbc", "seccm", "aiccm", "mace")


[docs] class Capability(BaseModel): """One task on one model and route of the pinned engine.""" model_config = ConfigDict(extra="forbid", frozen=True) task: Task model: str route: str dims: tuple[int, ...] status: Status entry_point: str reason: str issue: str | None = None
def _row( task: Task, model: str, route: str, dims: tuple[int, ...], status: Status, entry_point: str, reason: str, issue: str | None = None, ) -> Capability: return Capability( task=task, model=model, route=route, dims=dims, status=status, entry_point=entry_point, reason=reason, issue=issue, ) _HESSIAN_REFUSAL = ( "run_periodic_job(hessian=True) raises NotImplementedError on every route: no periodic " "force-constant route is wired to the front door; the former fallback computed the " "isolated unit-cell molecule's gas-phase Hessian and printed it as the periodic one, and " "was removed" ) CAPABILITIES: tuple[Capability, ...] = ( _row("energy", "pbc", "bipole", (3,), "admitted", "run_periodic_job(jk_method='bipole')", "bulk Ewald/Madelung J/K; dim = 3 only"), _row("energy", "pbc", "auto/gdf", (1, 2, 3), "admitted", "run_periodic_job(jk_method='auto')", "rigorous low-dimensional Coulomb for slabs and wires"), _row("energy", "seccm", "msindo-ccm", (1, 2, 3), "admitted", "run_job(method='seccm')", "experimental semiempirical cyclic cluster; closed shell"), _row("energy", "aiccm", "aiccm", (3,), "admitted", "run_periodic_job(method='aiccm')", "experimental; explicit variant and torus", "vibe-qc#1089"), _row("energy", "mace", "mace", (1, 2, 3), "admitted", "run_periodic_job(method='mace')", "periodic MACE potential; no wavefunction", "vibe-qc#745"), _row("forces", "pbc", "bipole/gdf", (1, 2, 3), "admitted", "run_periodic_job(optimize=True)", "atomic gradients are used inside the fixed-cell optimiser; BIPOLE production forces " "are finite differences of the energy"), _row("forces", "mace", "mace", (1, 2, 3), "admitted", "run_periodic_job(method='mace')", "energy and gradient of a point evaluation"), _row("forces", "seccm", "msindo-ccm", (1, 2, 3), "refused", "run_job(method='seccm')", "the sketcher writes SECCM single points only"), _row("forces", "aiccm", "aiccm", (3,), "refused", "run_periodic_job(method='aiccm')", "AICCM inputs are single points"), _row("relax_positions", "pbc", "bipole/gdf", (1, 2, 3), "admitted", "run_periodic_job(optimize=True)", "fixed-cell atomic relaxation on BIPOLE and the captured analytic-gradient GDF route; " "other J/K routes refuse geometry optimisation"), _row("relax_positions", "mace", "mace", (1, 2, 3), "admitted", "run_periodic_job(method='mace', optimize=True)", "fixed-cell atomic relaxation"), _row("relax_positions", "seccm", "msindo-ccm", (1, 2, 3), "refused", "run_job(method='seccm')", "SECCM (MSINDO) runs single points only"), _row("relax_positions", "aiccm", "aiccm", (3,), "refused", "run_periodic_job(method='aiccm')", "AICCM inputs are single points"), _row("relax_positions_frozen", "mace", "mace", (1, 2, 3), "admitted", "run_periodic_job(method='mace', optimize=True, optimize_frozen_indices=...)", "atoms held fixed during the relaxation"), _row("relax_positions_frozen", "pbc", "bipole", (3,), "library", "vibeqc.relax_atoms(freeze_indices=...) or vibeqc.relaxed_scan", "run_periodic_job refuses optimize_frozen_indices outside method='mace'; the BIPOLE " "library optimiser freezes atoms, but the sketcher writes no input for it"), _row("stress", "mace", "mace", (3,), "admitted", "run_periodic_job(method='mace')", "stress for dim = 3 point evaluations (tensile positive)"), _row("stress", "pbc", "bipole/gdf", (3,), "refused", "run_periodic_job", "no certified SCF stress on the front door: GDF has no analytic stress and the BIPOLE " "strain convention is not certified", "vibe-qc#773"), _row("relax_cell", "mace", "mace", (3,), "admitted", "run_periodic_job(method='mace', optimize=True, optimize_cell=True)", "atoms and cell together, dim = 3, no frozen atoms"), _row("relax_cell", "pbc", "bipole", (3,), "refused", "run_periodic_job(optimize_cell=True)", "BIPOLE variable-cell optimisation is unavailable: the strain convention and coupled " "atom/cell convergence were not certified", "vibe-qc#773"), _row("relax_cell", "pbc", "gdf", (2, 3), "refused", "run_periodic_job(optimize_cell=True)", "no GDF analytic stress (bulk or slab)"), _row("relax_cell", "pbc", "geomopt", (1, 2, 3), "refused", "run_periodic_geomopt", "run_geomopt refuses cell relaxation unless relax_cell=False", "vibe-qc#774"), *( _row("hessian", model, "all", (1, 2, 3), "refused", "run_periodic_job(hessian=True)", _HESSIAN_REFUSAL, "vibe-qc#968, vibe-qc#838") for model in MODELS ), *( _row("phonons", model, "all", (1, 2, 3), "refused", "run_periodic_job(hessian=True)", "finite-displacement phonons need periodic force constants; " + _HESSIAN_REFUSAL, "vibe-qc#968, vibe-qc#838") for model in MODELS ), _row("phonons", "pbc", "bipole-gamma", (3,), "library", "vibeqc.bipole_phonons.gamma_phonons", "a Gamma-point (q = 0) energy-difference Hessian of the fixed cell for zero-point " "estimates; not cross-route gated, no q-mesh, no dispersion; the sketcher writes no " "input for it and never reports it as a phonon spectrum"), *( _row("ir_intensities", model, "all", (1, 2, 3), "refused", "run_periodic_job", "no periodic Hessian and no Born effective charges on the front door", "vibe-qc#838") for model in MODELS ), *( _row("free_energy", model, "all", (1, 2, 3), "refused", "run_periodic_job", "harmonic and quasi-harmonic free energies need phonon frequencies, which the " "engine refuses", "vibe-qc#968, vibe-qc#838") for model in MODELS ), ) # fmt: skip
[docs] def table() -> dict[str, Any]: """The pinned engine and every row, for the SDK, CLI, REST and MCP.""" return { "engine": dict(ENGINE), "statuses": { "admitted": "the engine runs it and the sketcher writes the input", "library": "an engine library function exists; the sketcher writes no input", "refused": "the engine refuses it on this route", }, "capabilities": [row.model_dump(mode="json") for row in CAPABILITIES], }
[docs] def lookup(task: str, model: str, dim: int) -> list[Capability]: """The rows for ``task`` on ``model`` that cover a ``dim``-periodic cell.""" return [ row for row in CAPABILITIES if row.task == task and row.model == model and dim in row.dims ]
[docs] def admitted(task: str, model: str, dim: int) -> Capability | None: """The admitting row, or None when the engine (or the sketcher) does not run it.""" if model not in MODELS: return None return next((row for row in lookup(task, model, dim) if row.status == "admitted"), None)
[docs] def refusal(task: str, model: str, dim: int) -> dict[str, Any]: """An engine-refusal report: what was asked, what the engine says and who owns it.""" rows = lookup(task, model, dim) if model not in MODELS: reason = ( f"{model!r} is not an admitted periodic engine model; a model name is not an " f"admission (admitted: {', '.join(MODELS)})" ) return {"task": task, "model": model, "dim": dim, "engine": dict(ENGINE), "status": "refused", "reasons": [reason], "rows": []} # fmt: skip if not rows: rows_text = [f"the pinned engine lists no {task} route for {model} at dim = {dim}"] else: rows_text = [ ("library only, no input written: " if row.status == "library" else "") + f"{row.entry_point}: {row.reason}" + (f" ({row.issue})" if row.issue else "") for row in rows if row.status != "admitted" ] return { "task": task, "model": model, "dim": dim, "engine": dict(ENGINE), "status": "refused", "reasons": rows_text, "rows": [row.model_dump(mode="json") for row in rows], }