vibe-sketcherDocumentation
Source code for vibesketcher.server.porous_carbon
"""REST routes for net-derived porous and negative-curvature carbon models (#204).
Building goes through ``POST /api/documents/{id}/periodic/build`` with a
``kind: porous_carbon`` recipe (revision-checked, recorded as an edit and
undone like any build). These routes list the model plan, preview a build
and report the graph checks of a stored structure; none changes a document.
"""
from __future__ import annotations
from typing import Any
from fastapi import APIRouter, HTTPException
from pydantic import BaseModel, ConfigDict, Field, ValidationError
from vibesketcher.server.store import NotFound, Store
[docs]
class PorousCarbonPreviewRequest(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]
class PorousCarbonReportRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
structure: str = Field(min_length=1, max_length=64)
max_ring_size: int = Field(default=12, ge=6, le=16)
#: Plan (never run) a porosity analysis with this probe radius (angstrom).
probe_radius: float | None = Field(default=None, ge=0, le=10, allow_inf_nan=False)
probe_species: str = Field(default="He", min_length=1, max_length=40)
[docs]
def router(store: Store) -> APIRouter:
routes = APIRouter(prefix="/api", tags=["porous-carbon"])
@routes.get("/periodic/porous-carbon-models")
def porous_carbon_models() -> dict[str, Any]:
"""The model plan: constructions built or planned, bounds, checks and status."""
from vibesketcher.chem.porous_carbon import model_catalog
return model_catalog()
@routes.post("/documents/{identifier}/periodic/porous-carbon/preview")
def porous_carbon_preview(
identifier: str, request: PorousCarbonPreviewRequest
) -> dict[str, Any]:
"""The model record (topology, rings, coordination, defect map) or coded refusals."""
from vibesketcher.chem.porous_carbon import PorousCarbonRecipe, preview
try:
entry = store.get(identifier)
except NotFound:
raise HTTPException(404, f"no document {identifier!r}") from None
try:
recipe = PorousCarbonRecipe.model_validate({"kind": "porous_carbon", **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)
if not request.structure:
result.pop("structure", None)
return {"revision": entry.document.revision, **result}
@routes.post("/documents/{identifier}/periodic/porous-carbon/report")
def porous_carbon_report(identifier: str, request: PorousCarbonReportRequest) -> dict[str, Any]:
"""Graph checks of a stored carbon structure and, optionally, a porosity plan."""
from vibesketcher.chem.porous_carbon import PorousCarbonRefused, structure_report
try:
entry = store.get(identifier)
except NotFound:
raise HTTPException(404, f"no document {identifier!r}") from None
found = {s.id: s for s in entry.document.periodic_structures}
if request.structure not in found:
raise HTTPException(404, f"no periodic structure {request.structure!r}")
try:
result = structure_report(
found[request.structure],
max_ring_size=request.max_ring_size,
probe_radius=request.probe_radius,
probe_species=request.probe_species,
)
except PorousCarbonRefused as error:
raise HTTPException(422, {"errors": [error.detail], "codes": [error.code]}) from None
return {"revision": entry.document.revision, **result}
return routes