vibe-sketcherDocumentation

vibesketcher.render.cyclic_topology

Cyclic-topology schematics: a ring for one periodic dimension, a torus for two (#247).

A cyclic cluster (and the AICCM torus of vibesketcher.inputs.aiccm) is the input cell repeated N1 x N2 x N3 times with Born-von Karman boundary conditions: cell N along an axis is cell 0. This module draws that identification from the unchanged model, in two panels:

  • the unrolled sheet: the N1 (x N2) cells laid flat in the true lattice geometry, every atom at its fractional position, bonds found across the cells, and the identified edges marked with matching arrows (one arrow for the edges parallel to the first drawn axis, two for the second), the usual notation for gluing a square into a torus;

  • the cyclic shape: a ring (one drawn axis) or a 2-D projection of the parametric torus ((R + r cos t) cos p, (R + r cos t) sin p, r sin t) with p = 2 pi u along the first axis and t = 2 pi v along the second, where u = (n1 + f1) / N1 and v = (n2 + f2) / N2. The cells are a grid on the surface, the seams u = 0 and v = 0 (where the identification happens) are drawn in the accent colour with the same arrow marks as the sheet, and every bond that crosses a seam, a wrap-around bond, is drawn in the accent colour in both panels.

The torus surface is shaded with a Lambert term and drawn back to front (painter’s algorithm) from its front-facing facets; a closed surface hides every facet that faces away. The torus is a schematic: its radii are chosen for legibility, not to scale, and the figure says so. The sheet is to scale.

Bonds are the structure’s stored bonds (suppressed ones excluded) when it has any, otherwise pairs closer than 1.15 times the sum of RDKit’s covalent radii (Cordero et al., Dalton Trans. 2832 (2008)), as in the periodic figures. Nothing here changes the structure; a figure drawn twice from the same model and options is byte-identical.

Functions

structure_from_record(record)

The input cell and torus repeats stored in an AICCM convention record.

topology_figure(structure, repeats[, ...])

SVG, or PDF/PNG through the publication extra, of a structure on its torus.

topology_figure_from_record(record[, ...])

The schematic of the torus an AICCM convention record describes.

topology_svg(structure, repeats[, options, ...])

The schematic as standalone SVG (UTF-8), sized in points.

Classes

TopologyOptions(*[, axes, atoms, bonds, ...])

What the cyclic-topology schematic shows; every choice is stated.

Exceptions

TopologyRefused

The structure, repeats or options cannot be drawn as a cyclic topology.

class vibesketcher.render.cyclic_topology.TopologyOptions(*, axes=None, atoms=True, bonds=True, seams=True, unrolled=True, cell_labels=None, elevation_deg=32.0, aspect=2.4, atom_scale=1.0, width=504.0, font_size=9.0, title=None, caption=True)[source]

Bases: BaseModel

What the cyclic-topology schematic shows; every choice is stated.

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

axes: tuple[int] | tuple[int, int] | None

one gives a ring, two a torus. Default: every periodic axis of the structure, which must be one or two; a 3-D structure names two.

Type:

The periodic axes drawn (0 = a, 1 = b, 2 = c)

atoms: bool
bonds: bool
seams: bool

Seams and wrap-around bonds in the accent colour, with identification arrows.

unrolled: bool

The unrolled sheet beside the ring or torus.

cell_labels: bool | None

when there are at most 36 cells.

Type:

Cell indices in the sheet (and around a ring); None

elevation_deg: float

the camera’s elevation above the torus plane, in degrees.

Type:

Torus view

aspect: float

Torus major radius over tube radius.

atom_scale: float
width: float

Figure width and text size in points (72 per inch).

font_size: float
title: str | None

Figure title; $...$ math is allowed (vibesketcher.render.mathtext).

caption: bool

Provenance lines under the panels.

exception vibesketcher.render.cyclic_topology.TopologyRefused[source]

Bases: ValueError

The structure, repeats or options cannot be drawn as a cyclic topology.

vibesketcher.render.cyclic_topology.structure_from_record(record)[source]

The input cell and torus repeats stored in an AICCM convention record.

The record is the vibesketcher.aiccm-record/1 file written beside every AICCM input (vibesketcher.inputs.aiccm.torus_record()); its Hamiltonian identity carries the cell and its sites.

Parameters:

record (dict[str, Any])

Return type:

tuple[PeriodicStructure, tuple[int, int, int]]

vibesketcher.render.cyclic_topology.topology_figure(structure, repeats, options=None, fmt='svg', *, dpi=300)[source]

SVG, or PDF/PNG through the publication extra, of a structure on its torus.

Parameters:
Return type:

bytes

vibesketcher.render.cyclic_topology.topology_figure_from_record(record, options=None, fmt='svg', *, dpi=300)[source]

The schematic of the torus an AICCM convention record describes.

Parameters:
Return type:

bytes

vibesketcher.render.cyclic_topology.topology_svg(structure, repeats, options=None, *, provenance=())[source]

The schematic as standalone SVG (UTF-8), sized in points.

Parameters:
Return type:

bytes