vibe-sketcherDocumentation
Source code for vibesketcher.server.cnt_junctions
"""REST routes for explicit CNT-linker-metal junction models (#240).
Building goes through ``POST /api/documents/{id}/periodic/build`` with a
``kind: cnt_junction`` recipe (revision-checked, recorded as an edit and undone
like any build). These routes list the explicit surface sites and tube
attachment carbons a recipe indexes, and preview a junction without storing it.
"""
from __future__ import annotations
from typing import Any, Literal
from fastapi import APIRouter, HTTPException
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from vibesketcher.server.store import NotFound, Store
[docs]
class JunctionSitesRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
metal: Literal["Cu", "Au"]
miller: tuple[int, int, int]
layers: int = Field(default=3, ge=2, le=12)
repeat: tuple[int, int] = (6, 6)
surface_atom: str | None = None
[docs]
class JunctionCarbonsRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
n: int = Field(default=8, ge=3, le=20)
m: int = Field(default=0, ge=0, le=20)
periods: int = Field(default=4, ge=1, le=12)
attachment: Literal["end_on", "sidewall"]
[docs]
class JunctionPreviewRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
recipe: dict[str, Any]
#: Include the built structure in the answer (it can be large).
structure: bool = False
[docs]
def router(store: Store) -> APIRouter:
routes = APIRouter(prefix="/api", tags=["cnt-junctions"])
@routes.post("/periodic/cnt-junction/sites")
def junction_sites(request: JunctionSitesRequest) -> dict[str, Any]:
"""Top, bridge and hollow sites around one surface atom of a Cu/Au template slab."""
from vibesketcher.document.cnt_junctions import surface_sites
try:
return surface_sites(
request.metal,
request.miller,
layers=request.layers,
repeat=request.repeat,
surface_atom=request.surface_atom,
)
except ValueError as error:
raise HTTPException(422, {"errors": [str(error)]}) from None
@routes.post("/periodic/cnt-junction/carbons")
def junction_carbons(request: JunctionCarbonsRequest) -> dict[str, Any]:
"""The tube carbons ``attachment_carbon`` indexes for end-on or sidewall bonding."""
from vibesketcher.document.cnt_junctions import attachment_candidates
try:
return attachment_candidates(request.n, request.m, request.periods, request.attachment)
except ValueError as error:
raise HTTPException(422, {"errors": [str(error)]}) from None
@routes.post("/documents/{identifier}/periodic/cnt-junction/preview")
def junction_preview(identifier: str, request: JunctionPreviewRequest) -> dict[str, Any]:
"""The junction record (bonds added, site, checks, charge/spin) or the coded refusal."""
from vibesketcher.document.cnt_junctions import CntJunctionRecipe, preview
try:
entry = store.get(identifier)
except NotFound:
raise HTTPException(404, f"no document {identifier!r}") from None
try:
recipe = CntJunctionRecipe.model_validate(request.recipe)
except ValidationError as error:
raise HTTPException(422, {"errors": [e["msg"] for e in error.errors()]}) from None
if recipe.identifier in {s.id for s in entry.document.periodic_structures}:
raise HTTPException(422, {"errors": [f"{recipe.identifier!r} already exists"]})
result = preview(recipe, entry.document)
if not request.structure:
result.pop("structure", None)
return {"revision": entry.document.revision, **result}
return routes