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],
}