vibe-viewerDocumentation

Tutorial: journal figures from the command line

This tutorial makes a complete set of journal figures with vibe-viewer commands only: structure panels that share one camera, composed into a two-column PDF; vector line art; a band structure beside its DOS; a cyclic cluster inside its Wigner–Seitz supercell; and a periodic pore channel with its numbers. Each step is one command, so the whole set is a script you can keep beside the manuscript and run again.

It takes about ten minutes. You need:

  • a vibe-viewer that includes the command-line figure options. They are on development main after 3.0.9; the 3.0.8 desktop app does not have them. If a command answers No such option, run a source checkout as shown in Troubleshooting;

  • an off-screen OpenGL context for the PNG captures (setting up a headless host); vibe-viewer capture-selftest checks it;

  • SciPy (the surfaces extra) for steps 5 and 6.

1. Get the inputs

Download make_inputs.py and figures.sh into an empty directory, then write the inputs:

python make_inputs.py

This writes seven small archives. They are illustrative inputs, not calculations: conventional cells of diamond, rock-salt MgO and zinc-blende ZnS with rounded lattice constants, three MgO(001) layers periodic in a and b, the two-atom primitive MgO cell, a pore channel between carbon rods, and model-bands.qvf. That last one holds bands and a DOS from a toy nearest-neighbour tight-binding model on an fcc lattice, written so the chart commands have something to draw; it is not a material. Replace any of them with your own archives: the commands only need the section kinds named below.

To make every figure at once, run sh figures.sh; it writes them into figures/. The steps below take the same commands one at a time and explain the choices.

2. Four structures, one camera, one PDF

Use the same camera flags for every panel, so the four structures are seen the same way:

CAMERA="--view 1,0.35,0.2 --orthographic --background white --publication --dpi 600 --width-mm 88 --size 4x3"
for name in diamond rocksalt zincblende slab; do
  vibe-viewer capture "$name.qvf" $CAMERA -o "figures/$name.png"
done
vibe-viewer figure figures/diamond.png figures/rocksalt.png figures/zincblende.png \
    figures/slab.png --width-mm 178 -o figures/structures.pdf
  • --view 1,0.35,0.2 places the camera along that Cartesian direction. --uvw and --hkl would use crystal directions, but they need a 3D cell and the slab has none, so a set that includes a slab shares a Cartesian view.

  • --orthographic uses a parallel projection, the usual choice for crystals.

  • --dpi 600 --width-mm 88 captures each panel at 2079 pixels, its printed width at 600 dpi. Two 88 mm panels and the default 2 mm gap fill a 178 mm two-column figure.

  • --publication --background white gives outlined atoms on white.

figure reports the grid, size and font, and each panel’s effective resolution:

4 panels, 2 x 2: 178 x 134.0 mm, Arial 9 pt, PDF
(a) diamond.png: 2079 x 1559 px at 88.0 mm, 600 dpi
...

It flags any panel below 300 dpi, so a panel captured too small is caught before submission. The PDF embeds each panel with its own pixels and keeps the (a)–(d) labels as text.

Four crystal structures labelled (a) to (d): diamond, rock-salt MgO, zinc-blende ZnS and an MgO slab, all seen from the same direction

3. Vector line art

Some journals ask for structures as line art. An .svg or .pdf output draws the structure as vector circles and sticks instead of a rendered image, using the same camera flags:

vibe-viewer capture zincblende.qvf --uvw 1,1,0 --background white --width-mm 85 \
    -o figures/zincblende-110.svg

Here --uvw 1,1,0 looks down the [110] lattice direction of the 3D cell, with the b axis up, as the browser’s crystal-direction control does. The projection is always orthographic. Atoms are drawn far to near, so nearer atoms and bonds cover the ones behind. Along [110] the zinc-blende cell shows its Zn–S dumbbell columns:

Zinc-blende ZnS as vector line art, seen down [110]: outlined yellow S and blue Zn circles joined by grey sticks inside the cell outline

4. Band structure and DOS

A bands section or a DOS section is drawn as a static chart at a printed width, in a journal font, as PDF, SVG or PNG:

vibe-viewer capture model-bands.qvf -s bands --dos dos --width-mm 85 --size 3x2 \
    -o figures/bands-dos.pdf
vibe-viewer capture model-bands.qvf -s dos --font serif --font-size 9 --width-mm 60 \
    -o figures/dos.svg

--dos dos puts the DOS section beside the bands on one energy axis, which is why the bands must carry a Fermi energy. --size 3x2 sets the aspect ratio, so the chart is 85 × 56.7 mm. The PDF embeds its font and the SVG keeps its labels as editable text. Neither records a creation date, so running the command again gives the same file.

Band structure along Γ–X–W–L–Γ–K of the toy model beside its DOS, sharing the energy axis E − E_F

5. A cyclic cluster and its Wigner–Seitz supercell

For cyclic-cluster calculations, draw the Wigner–Seitz supercell around a reference atom and the weights of its boundary sites:

vibe-viewer capture mgo-primitive.qvf --wigner-seitz 3,3,3 --ws-center "element Mg" \
    --ws-weights colour --ws-cluster --background white --no-cell \
    --view 1,0.35,0.2 --orthographic --dpi 600 --width-mm 85 -o figures/mgo-cluster.png
  • --wigner-seitz 3,3,3 takes the (3,3,3) supercell of the primitive cell, the 54-atom cluster, and --ws-center "element Mg" centres it on the Mg atom.

  • --ws-weights colour draws every site on the closed supercell, coloured by its weight 1/n, where n counts how often the site appears on the surface. For this rhombic dodecahedron the weights are 1, 1/2, 1/3 and 1/6, and they add up to 27 Mg and 27 O.

  • --ws-cluster adds the neighbouring copies of the cluster, faded, and its translation vectors T1–T3 as arrows.

The 54-atom MgO cyclic cluster coloured by boundary weight, surrounded by faded periodic copies, with translation-vector arrows T1, T2 and T3

If your calculation treated a near-boundary atom differently, pass its weights with --ws-weight-table. --ws-labels image labels each site with its atom and image translation, the numbers a weight-table line takes:

vibe-viewer capture mgo-primitive.qvf --wigner-seitz 2,2,2 --ws-center "element Mg" \
    --ws-weights colour --ws-labels image --background white --no-cell \
    --view 1,0.35,0.2 --orthographic --size 1400x1000 -o figures/mgo-labels.png

The smaller (2,2,2) MgO supercell with each site labelled by atom and image, for example Mg1 (1 1 -1)

Labels crowd on large supercells. Use image labels to identify sites, and --ws-labels name (Mg1, O2) or none for print.

6. A pore channel with its numbers

--pores runs the periodic pore estimate on the structure, prints its summary and draws channels, cavities and the largest spheres:

vibe-viewer capture rods.qvf --pores --pore-probe 1.8 --pore-convergence \
    --pore-report figures/rods-pores.json --background white \
    --view 0.3,-1,0.6 --size 900x700 -o figures/rods-pores.png

The summary states the probe, grid resolution and whether the result converged when the grid was halved; for this channel the probe percolates along c. The JSON report keeps every number and setting beside the image.

An open pore channel along c between carbon rods: a green channel surface, a blue sphere for the largest included sphere and an orange sphere at the narrowest point

Keep the figures reproducible

  • Keep figures.sh, the input archives and vibe-viewer --version with the manuscript. The commands carry every camera, size and style choice.

  • PDF and SVG output records no creation date, so a rerun with the same software and fonts gives identical files.

  • Named fonts must be installed: --font "Times New Roman" is refused rather than substituted when the font is missing. sans-serif and serif take the first installed of a list of journal fonts.

  • Keep the pore and loading numbers from their JSON reports, not from the images.

Troubleshooting

No such option: --wigner-seitz (or --view, --pores, --font)

The installed vibe-viewer predates these options. Run a source checkout of main instead, for example VV="env PYTHONPATH=/path/to/vibe-viewer/src python -m vibeviewer" sh figures.sh.

Path 'x.qvf' does not exist

Run the commands in the directory where make_inputs.py wrote the archives, or give full paths.

Crystal directions require a 3D periodic cell

--uvw and --hkl need a cell periodic in all three directions. Use --view X,Y,Z for slabs and molecules.

... selects 4 atoms, not one

--ws-center must name exactly one atom. In a conventional cell use --ws-center "index 1".

A blank or failed PNG

Check the off-screen context with vibe-viewer capture-selftest; see Figures without a display.

Reference

Every option is described in Figures without a display: camera and print size, vector line art, band structures and DOS for print, multi-panel figures, pore networks and Wigner–Seitz supercells and cyclic-cluster weights. Publication figures covers labelled browser figures, scripted recipes and morph movies.