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