ShowCIF

ShowCIF#

Inspect a CIF or ASE structure with linked WebGPU atom, column, and potential views. Start with the crystal and its orientation:

from quantem.widget import ShowCIF

viewer = ShowCIF("crystal.cif", repeats=(4, 4, 8), zone_axis=(0, 0, 1))
viewer

Install quantem.widget[crystal] for ASE and the optional abTEM potential tables. Rendering requires WebGPU in a secure browser context (HTTPS or localhost).

Reference#

class quantem.widget.ShowCIF(*args: t.Any, **kwargs: t.Any)#

Show linked 3D atoms and an orthographic column projection.

Parameters:

  • structure (str, pathlib.Path or ase.Atoms) – CIF filename or ASE structure. CIF symmetry expansion is performed by ASE. Partially occupied or mixed sites require an explicit ordered model.

  • repeats (sequence of int, default (3, 3, 3)) – Number of unit cells along lattice vectors a, b, c. At most 250,000 atoms are displayed; choose a smaller inspection region for large cells.

  • zone_axis (sequence of int, default (0, 0, 1)) – Direct-lattice direction [uvw] for the projection, not a reciprocal plane normal. Rotating the 3D camera does not change this direction.

  • specimen_tilt_mrad (sequence of float, default (0, 0)) – Rigid specimen tilt (row, column), each from -15 to +15 mrad, about the inspection cell center relative to zone_axis. Positive row/column leans down/right with increasing beam depth. Components form a rotation vector in the nominal beam frame; the CIF and camera are unchanged.

  • title (str, optional) – Heading above the two views.

  • view_mode ({"unit_cells", "microscope"}, default "unit_cells") – Fit the inspection cell or show an exact square physical field of view.

  • orthogonal_views (bool, default False) – Show additional column-depth and row-depth atom projections, linked to the same beam frame, species visibility, and slab selection.

  • field_of_view_A (float, default 40) – Microscope projection width and height in Å. Does not add atoms.

  • magnification_calibration (sequence of float, optional) – Reference magnification and its field of view in Å, for a fixed camera and acquisition geometry. For example, (1_000_000, 100). The viewer uses inverse magnification scaling; no calibration is assumed.

  • energy_keV (float, default 300) – Electron kinetic energy from 0 to 300 keV. Zero disables phase display.

  • potential_colormap (str, default "viridis") – Shared Show3D colormap for every potential/phase panel, such as “viridis”, “magma”, “gray”, or “RdBu”.

  • potential_quantity ({"integrated", "average", "phase"}, default "average") – Display V Å, thickness-average V, or unwrapped projected-potential phase. Phase uses relativistic sigma(E) times the integrated potential; it is not a multislice exit-wave calculation.

  • num_slices (int, default 16) – Equal-width preview slabs along the selected beam, from 1 to 64.

  • potential (bool, default False) – Enable WebGPU independent-atom potential preview (requires abTEM). At most 8,192 atoms can contribute to this preview; the atom viewer supports up to 250,000. Reduce repeats if the preview is unavailable.

  • potential_sigma_A (float, default 0.08) – Explicit transverse Gaussian preview filter width, in Å. Not thermal displacement or fitted experimental resolution.

  • potential_pixels (int, default 256) – Preview grid width and height, one of 128, 256 or 512.

Notes

Species visibility, clipping and sphere radii are display settings only. The atom projection shows positions, not intensity or phase. Optional potential maps use neutral Lobato infinite atomic projections assigned by site depth; they are not finite-z potential integrals or reconstruction data. WebGPU is required for rendering. No structure editing is performed.

Examples

>>> viewer = ShowCIF("crystal.cif", repeats=(4, 4, 8))
>>> viewer.specimen_tilt_mrad = [5.0, -2.0]
>>> original = viewer.atoms()

Public constructor

atoms() → Atoms#

Return the original unit cell without display filters or specimen tilt.

Returns:

Independent copy of the supplied structure, before repeats.

Return type:

ase.Atoms

export_html(path: str | Path) → Path#

Save an interactive structure viewer with its current synced settings.

Parameters:

path (str or pathlib.Path) – Destination HTML file. Missing parent directories are created.

Returns:

The saved HTML path.

Return type:

pathlib.Path

Notes

Atomic coordinates and potential tables are embedded. The widget manager loads from a CDN, so opening the file requires network access and a WebGPU-capable secure browser context. Transient camera, playback, and panel-visibility choices are not serialized.

Structure and orientation#

repeats expands the original unit cell along lattice vectors a, b, c. ASE expands CIF symmetry; partial or mixed occupancies require an explicitly ordered model. The maximum inspection size is 250,000 atoms.

zone_axis is the direct-lattice direction u*a + v*b + w*c, including for oblique cells. It is not a reciprocal-plane normal. The 3D camera rotates independently of the projection direction. atoms() returns an independent copy of the original cell, before repeats, display filters, or specimen tilt.

viewer.zone_axis = [1, 1, 0]
viewer.specimen_tilt_mrad = [10, -5]  # (row, col)
original = viewer.atoms()

Specimen tilt ranges from −15 to +15 mrad per component. Positive row tilt leans a nominal beam column downward with depth; positive column tilt leans it right. The components define a rigid rotation vector about the nominal beam frame’s right and up axes, centered on the inspection cell. At nonzero tilt, [uvw] continues to label the nominal starting direction. Atom projections, depth bounds, slice membership, and potential maps use this same geometry.

Microscope field of view#

viewer = ShowCIF(
    "crystal.cif",
    view_mode="microscope",
    field_of_view_A=40,
    magnification_calibration=(1_000_000, 100),
)
viewer

Microscope mode sets a physical square field of view; it does not add atoms. The optional calibration is (reference magnification, reference FOV in Å) for one fixed camera/acquisition geometry. Magnification scales that FOV inversely. No universal magnification calibration is assumed.

Orthogonal views show column–depth and row–depth in the selected beam frame, including oblique cells. They are not necessarily crystallographic a/b/c planes. In microscope mode they fit the specimen depth while the main projection retains its entered FOV. Every atom and potential panel has a physical scale bar.

Potential and expected phase#

viewer = ShowCIF(
    "crystal.cif",
    potential=True,
    num_slices=16,
    energy_keV=300,
    potential_quantity="phase",
    potential_colormap="magma",
)
viewer

Enable Potential / phase maps in the settings gear. This optional preview supports up to 8,192 atoms. Larger structures remain available in the atom viewer; reduce repeats to enable their potential preview. No atoms are silently removed to meet the limit.

Maps use neutral abTEM Lobato infinite atomic projections, assigned to depth slabs by atomic-site position. They are not finite-z potential integrals, bonded charge density, or a multislice propagation. A finite inspection patch is used; there are no periodic images beyond the explicit repeats.

Quantity

Meaning

Integrated · V Å

Sum of projected atomic potentials in the slab

Thickness Average · V

Integrated potential divided by that slab’s thickness

Expected Phase · rad

Relativistic interaction constant σ(E) × integrated V Å

Phase uses the positive exp(i*phi) convention and is unwrapped. At 300 keV, σ is approximately 0.000652616 rad/(V Å). The energy control spans 0–300 keV; zero explicitly disables phase, which is undefined there. Individual slab phases sum to the full projected phase. This is not thick-specimen exit-wave phase: propagation, channeling, aberrations, and partial coherence are absent.

potential_sigma_A is the explicit transverse Gaussian regularization of the atomic tables (default 0.08 Å, range 0.04–0.5 Å). It is not thermal displacement or a fitted experimental resolution. Blur σ applies an additional WebGPU display filter, with zero extension outside the finite patch and a three-sigma kernel. It preserves the original potential planes. The preview grid is explicit (128, 256, or 512 pixels); FOV changes alter its Å/px readout and show an undersampling warning where appropriate. Max changes color limits only.

Interactive controls#

ShowCIF shares Show3D/Show3DSlices sliders, colormap selection, play/pause icons, and light/dark colors. Controls have square corners. The settings gear hides less-used panels until needed.

Control

State or behavior

Unit Cells

repeats; updates atom instances and the physical cell

Species

visible_species; hides atoms and excludes them from the potential preview

Beam

zone_axis; changes projections, not the 3D camera

Row / Col tilt

specimen_tilt_mrad; animation-frame-coalesced preview, saved on release

View / FOV

view_mode, field_of_view_A; fits the cell or an explicit physical field

Settings gear

Toggles column projection, orthogonal views, slice controls, and potential maps

Atom slice / Avg

One zero-based slice center and a moving slab width; atoms are not averaged

Potential Depth / Avg / Play

Independent potential slice center, arithmetic mean width, and playback

Color / Quantity / Energy

potential_colormap, potential_quantity, energy_keV

Columns / Blur / Max

Preview layout and display-only image controls

Atom radius / Zoom

Schematic markers and camera scale; coordinates remain unchanged

The atom and potential slicers both start with num_slices. Potential slicing and playback settings can subsequently use their own 1–64 plane count. Averaging uses Show3D’s centered window, shifted inward at the ends: with 16 planes and Avg 3, centers 0 and 1 use planes 0–2, center 2 uses 1–3, and center 15 uses 13–15. It neither wraps nor shortens the edge mean.

The potential moving average is an arithmetic mean per plane, not a sum. For thickness-average V it divides by one plane’s thickness; for phase it multiplies the mean integrated potential by σ(E). Full Projection continues to show the full-depth sum (or full-depth thickness average for V). Atom panels show the selected slab union, without averaging atomic coordinates.

The optional gallery shows individual planes. Hover or keyboard focus previews a plane; leaving restores the committed selection, and clicking commits it. Playback loops at 5 fps by default and pauses during scrubbing, gallery preview, when hidden, or at invalid phase energy. GPU-resident averaging and filtering avoid image readback; geometry changes recompute the potential planes.

HTML export#

viewer.export_html("structure.html")

The export embeds atomic coordinates, potential tables, and synced settings (including repeats, tilt, FOV, energy, colormap, and orthogonal visibility). Transient camera, panel-visibility, playback, blur, and slice selections reset when reopened. The widget manager loads from a CDN: the export requires network access and WebGPU, and is not an offline simulation package.