vibe-sketcherDocumentation
Source code for vibesketcher.agent.mcp_symmetry_ops
"""MCP tools for adopting symmetry, enantiomorphs and subgroup descent (#199).
Each tool is a call to the REST routes in
:mod:`vibesketcher.server.symmetry_ops`; :func:`tools` is joined to the list
in :func:`vibesketcher.agent.mcp.make_tools`.
"""
from __future__ import annotations
from collections.abc import Callable
from typing import TYPE_CHECKING, Any
from vibesketcher.agent.client import RestClient
if TYPE_CHECKING:
from vibesketcher.agent.mcp import Tool
[docs]
def tools(
client: RestClient,
document_id: Callable[[dict[str, Any]], str],
edit: Callable[[dict[str, Any], str, str, dict[str, Any]], Any],
) -> list[Tool]:
from vibesketcher.agent.mcp import Tool, _schema
document = {"type": "string", "description": "Document id; the open document when left out."}
number = {"type": "number"}
def base(arguments: dict[str, Any]) -> str:
return f"periodic/{arguments['structure']}/symmetry"
def pick(arguments: dict[str, Any], *keys: str) -> dict[str, Any]:
return {k: arguments[k] for k in keys if k in arguments}
def adopt_periodic_symmetry(arguments: dict[str, Any]) -> Any:
if arguments.get("undo"):
return edit(arguments, "POST", base(arguments) + "/undo", {})
options = pick(arguments, "symprec", "idealize", "diagnostic_symprec")
preview = client.call(
"POST", f"api/documents/{document_id(arguments)}/{base(arguments)}/adopt/preview",
options,
) # fmt: skip
if not arguments.get("apply"):
return preview
body = {**options, "source_sha256": preview["source_sha256"]}
return edit(arguments, "POST", base(arguments) + "/adopt", body)
def invert_periodic_structure(arguments: dict[str, Any]) -> Any:
options = pick(arguments, "symprec", "diagnostic_symprec")
if not arguments.get("identifier"):
return client.call(
"POST",
f"api/documents/{document_id(arguments)}/{base(arguments)}/enantiomorph/preview",
options,
)
body = {**options, "identifier": arguments["identifier"]}
return edit(arguments, "POST", base(arguments) + "/enantiomorph", body)
def descend_periodic_subgroup(arguments: dict[str, Any]) -> Any:
options = pick(arguments, "transformation", "subgroup", "symprec")
if not arguments.get("identifier"):
return client.call(
"POST",
f"api/documents/{document_id(arguments)}/{base(arguments)}/descend/preview",
options,
)
body = {**options, "identifier": arguments["identifier"]}
return edit(arguments, "POST", base(arguments) + "/descend", body)
def drop_periodic_displacements(arguments: dict[str, Any]) -> Any:
body = {"reason": arguments["reason"]}
return edit(arguments, "POST", base(arguments) + "/drop-displacements", body)
return [
Tool(
"drop_periodic_displacements",
"Drop a periodic structure's measured anisotropic displacement tensors (from a "
"CIF _atom_site_aniso loop) with a recorded reason; the dropped record is kept "
"under provenance displacement_parameters_dropped. Supercells, primitive, "
"conventional, standard, reduced and setting cells, slabs, defects, translations "
"and rotations carry the tensors; cell strain, idealised standardisation and "
"element changes on measured sites refuse until they are dropped with this tool.",
_schema(
{
"document": document,
"structure": {"type": "string"},
"reason": {"type": "string"},
},
("structure", "reason"),
), # fmt: skip
drop_periodic_displacements,
),
Tool(
"adopt_periodic_symmetry",
"Preview (default) or apply=true adoption of the space group spglib detects at "
"symprec (angstrom) as a 3-D structure's recorded symmetry: operations in the "
"structure's own basis, the tabulated setting if it matches, orbits with Wyckoff "
"letters, merges and splits against the previously recorded orbits, every site's "
"symmetrisation displacement, the cell change, and sites near a special position at "
"diagnostic_symprec (0.1 A). Nothing moves unless idealize=true (positions and "
"metric symmetrised; displacement tensors too). The apply step is revision-checked "
"against the preview's source digest; undo=true reverts the last adoption. "
"Disordered and magnetic structures are refused.",
_schema(
{
"document": document,
"structure": {"type": "string"},
"symprec": number,
"idealize": {"type": "boolean"},
"diagnostic_symprec": number,
"apply": {"type": "boolean"},
"undo": {"type": "boolean"},
},
("structure",),
), # fmt: skip
adopt_periodic_symmetry,
),
Tool(
"invert_periodic_structure",
"Invert a chiral 3-D structure through the origin (x -> -x) with its space group "
"transformed, (R, t) -> (R, -t): an enantiomorphic pair changes type (P3_121 <-> "
"P3_221, P4_1 <-> P4_3, P6_122 <-> P6_522, ...), other Sohncke groups keep theirs. "
"Achiral structures, and ones achiral within diagnostic_symprec (ambiguous "
"handedness), are refused. Without identifier it previews; with identifier it adds "
"the new structure (bonds and displacement tensors carried). Undo with "
"adopt_periodic_symmetry structure=<new id> undo=true.",
_schema(
{
"document": document,
"structure": {"type": "string"},
"identifier": {"type": "string"},
"symprec": number,
"diagnostic_symprec": number,
},
("structure",),
), # fmt: skip
invert_periodic_structure,
),
Tool(
"descend_periodic_subgroup",
"Describe a 3-D structure in a subgroup H of its space group: transformation is "
"the ITA setting (P, p), e.g. 'a,b,c' or '2a,2b,2c;0,0,0' or 'a-b,a+b,c;0,0,1/4', "
"subgroup H's Hall or Hermann-Mauguin symbol in that basis. Every operation of H "
"must be a symmetry in the new basis (verified by spglib detection). Reports the "
"index with its t and k parts, the type (translationengleiche or klassengleiche; "
"general subgroups are refused by Hermann's theorem), Wyckoff splitting of every "
"parent orbit and the changed independent sites. Automatic enumeration of maximal "
"subgroups is not offered yet. Without identifier it previews; with identifier it "
"adds the new structure.",
_schema(
{
"document": document,
"structure": {"type": "string"},
"transformation": {"type": "string"},
"subgroup": {"type": "string"},
"identifier": {"type": "string"},
"symprec": number,
},
("structure", "transformation", "subgroup"),
), # fmt: skip
descend_periodic_subgroup,
),
]