Module-level exporters

Module-level helpers for rendering finished supercells into self-contained HTML viewers that can be opened in any browser or embedded via <iframe>. See Visualization for the high-level descriptions and rendered examples.

Multi-cell overview

Supports multi-group polyhedra via the polyhedra_groups= kwarg, where each entry is a dict {kind, center_symbol, vertex_symbol, bond_length, ..., virtual_species, color, opacity} and kind is one of "triangles", "tetrahedra", "octahedra", "cuboctahedra". Use it for sp²/sp³ carbon blends where green triangle fans and navy tetrahedra render side-by-side; see the Multi-Cell Overview page.

tricor.export_overview_html(output_path, cells_and_labels, *, grid_cols=3, atom_scale=0.17, bond_radius=0.07, bond_color=(0.95, 0.1, 0.1), background_color='#f7f8f5', title='', subtitle='', bond_cutoff_scale=1.2, max_bonds_per_atom=4, bond_length_tol=0.1, ideal_angle_deg=109.47, bond_angle_tol_deg=18.0, tetrahedra=None, tetrahedra_color=(0.35, 0.45, 0.95), tetrahedra_opacity=0.45, octahedra=None, octahedra_color=(0.95, 0.55, 0.25), octahedra_opacity=0.4, cuboctahedra=None, cuboctahedra_color=(0.55, 0.35, 0.85), cuboctahedra_opacity=0.4, polyhedra_groups=None)[source]

Export a 3D grid of supercells as a self-contained, auto-rotating HTML viewer.

Each panel renders the final atom positions of one Supercell using ASE element colours and black outlines. All panels share a single auto-rotating camera; dragging any panel pauses the rotation and lets the user orbit manually. Bonds are rendered by default; passing one of the polyhedra kwargs (tetrahedra, octahedra, cuboctahedra, polyhedra_groups) replaces bonds with translucent polyhedra.

Parameters:

  • output_path (str) – Filesystem path for the written HTML file.

  • cells_and_labels (list of (Supercell, str)) – Pairs of supercells and their panel-title labels, rendered left-to-right then top-to-bottom into a grid_cols-wide grid.

  • grid_cols (int, optional) – Number of panels per row. Default 3.

  • atom_scale (float, optional) – Multiplier applied to ASE covalent radii when sizing atom spheres. Default 0.17.

  • bond_radius (float, optional) – Cylinder radius (Å) for rendered bonds. Default 0.07.

  • bond_color (tuple of float, optional) – RGB triplet (each in [0, 1]) for bond colour. Default red (0.95, 0.1, 0.1).

  • background_color (str, optional) – CSS colour string for the panel background. Default "#f7f8f5" (off-white).

  • title (str, optional) – Headline + sub-line text rendered above the grid.

  • subtitle (str, optional) – Headline + sub-line text rendered above the grid.

  • bond_cutoff_scale (float, optional) – Bond search radius is shell_target.pair_peak × bond_cutoff_scale. Default 1.2.

  • max_bonds_per_atom (int, optional) – Per-atom cap on bonds drawn (after the angle filter). Default 4.

  • bond_length_tol (float, optional) – Acceptance window around pair_peak for the bond filter (fraction). Default 0.10 (±10 %).

  • ideal_angle_deg (float, optional) – Reject bonds whose 4-NN angles deviate more than bond_angle_tol_deg from ideal_angle_deg. Default 109.47° ± 18° (tetrahedral). Set bond_angle_tol_deg=180 to disable the angle filter (e.g. FCC metals where 60°/90°/120° angles all matter).

  • bond_angle_tol_deg (float, optional) – Reject bonds whose 4-NN angles deviate more than bond_angle_tol_deg from ideal_angle_deg. Default 109.47° ± 18° (tetrahedral). Set bond_angle_tol_deg=180 to disable the angle filter (e.g. FCC metals where 60°/90°/120° angles all matter).

  • tetrahedra (dict, optional) – Switch panels to tetrahedron rendering. Dict keys: center_symbol (default "Si"), vertex_symbol (default "O"), bond_length (default auto-detected from atoms), bond_length_tol (default 0.15), ideal_angle_deg (default 109.47), angle_tol_deg (default 25.0), scale (vertex shrink factor; default 0.5 for same-element, 1.0 for cross-species).

  • tetrahedra_color (tuple of float, optional) – RGB triplet for tetrahedron faces. Default navy (0.35, 0.45, 0.95).

  • tetrahedra_opacity (float, optional) – Face opacity in [0, 1]. Default 0.45.

  • octahedra (dict / tuple / float, optional) – Octahedron variant — same dict keys as tetrahedra.

  • octahedra_color (dict / tuple / float, optional) – Octahedron variant — same dict keys as tetrahedra.

  • octahedra_opacity (dict / tuple / float, optional) – Octahedron variant — same dict keys as tetrahedra.

  • cuboctahedra (dict / tuple / float, optional) – Cuboctahedron variant (12-vertex FCC close-packed shell).

  • cuboctahedra_color (dict / tuple / float, optional) – Cuboctahedron variant (12-vertex FCC close-packed shell).

  • cuboctahedra_opacity (dict / tuple / float, optional) – Cuboctahedron variant (12-vertex FCC close-packed shell).

  • polyhedra_groups (list of dict, optional) – Multi-group polyhedra (e.g. sp²/sp³ carbon) — list of per-group dicts each with kind (one of "triangles", "tetrahedra", "octahedra", "cuboctahedra"), center_symbol, vertex_symbol, color, opacity, plus optional virtual_species for filtering by Supercell._atom_shell_species_index.

Returns:

The HTML written to output_path.

Return type:

str

Examples

>>> import tricor as tc
>>> cells = [(cell_amorphous, "amorphous"),
...          (cell_mro, "MRO"),
...          (cell_nc, "NC")]
>>> tc.export_overview_html("overview.html", cells, grid_cols=3,
...                          tetrahedra=dict(center_symbol="Si",
...                                          vertex_symbol="Si"))

g(r) comparison across supercells

Overlay the pair-correlation function g(r) from multiple supercells on a single axis, with a dropdown to switch species pair and an inline per-series label. The compare mode of the g(2) viewer stacks curves with a small vertical offset so the six-regime ladders shown on each example page stay legible.

tricor.export_g2_compare_html(cells_and_labels, output_path=None, *, r_max=10.0, r_step=0.05, background_color='#f7f8f5', title='', show_progress=False, sample_fraction=1.0, sample_rng_seed=None)[source]

Export a g(r) overlay viewer comparing multiple supercells.

Every cell must share the same set of species (same reference material). One g(r) curve is drawn per cell for the currently selected species pair; the dropdown in the viewer switches which pair is shown and a legend identifies each cell by its label.

Parameters:

  • cells_and_labels –

    Accepts any of:

    • dict[str, Supercell] - keys become legend labels

    • list[tuple[Supercell, str]]

    • list[Supercell] - each cell.label is used

  • output_path (str | None) – Path to write the HTML file. When None the HTML string is returned instead (for IPython.display.HTML() / inline display); see plot_g2_compare() for a ready-made Jupyter wrapper.

  • r_max (float) – Radial grid for the measurements. Finer r_step gives smoother curves; 0.05 A is a good default.

  • r_step (float) – Radial grid for the measurements. Finer r_step gives smoother curves; 0.05 A is a good default.

  • background_color (str) – Cosmetic.

  • title (str) – Cosmetic.

  • show_progress (bool) – Forwarded to each Supercell.measure_g3() call (used under the hood; phi_num_bins is set low for speed).

  • sample_fraction (float) –

  • sample_rng_seed (int | None) –

Returns:

Resolved output path when output_path was provided, otherwise the HTML source string.

Return type:

str

tricor.plot_g2_compare(cells_and_labels, *, r_max=10.0, r_step=0.05, title='', height=480, show_progress=False, sample_fraction=1.0, sample_rng_seed=None)[source]

Inline Jupyter display of the g(r) overlay-compare viewer.

Convenience wrapper around export_g2_compare_html() that packages the HTML as an IPython.display.HTML object so you can do tc.plot_g2_compare(cells) in a notebook cell.

Parameters:

  • cells_and_labels (list of (Supercell, str) or dict) – Either a list of (supercell, label) pairs or a {label: supercell} dict. Each cell’s g(r) becomes one curve in the overlay. See export_g2_compare_html() for full input-shape details.

  • r_max (float, optional) – Maximum radial distance (Å) plotted on the x-axis. Default 10.0.

  • r_step (float, optional) – Bin width (Å) of the g(r) histogram. Default 0.05.

  • title (str, optional) – Title text rendered above the viewer. Default "".

  • height (int, optional) – Iframe height (pixels) of the rendered viewer in Jupyter. Default 480.

  • show_progress (bool, optional) – Display a tqdm progress bar while the per-cell g(r) histograms are built. Default False.

  • sample_fraction (float) –

  • sample_rng_seed (int | None) –

Returns:

The viewer wrapped in an iframe and ready for inline display in a Jupyter cell.

Return type:

IPython.display.HTML