v_ase

v_ase brings ASE's convenient terminal and Python workflow together with direct, Blender-style 3D structure editing. Open a structure or trajectory with one command, inspect and measure it in a local browser, edit it manually or ask an AI agent to perform verified multi-step changes from natural language, then export publication images, videos, and reusable 3D scenes.

The animation builds a phosphorene nanoribbon twist one ridge at a time. Each amber box selects the remaining ridges, the Transform controls apply an exact X-axis rotation, and the sequence reaches a 13.85 degree twist before the completed structure is inspected from above and below.

Quick Start

Install from PyPI:

python -m pip install v_ase-gui

Or install the current GitHub source:

git clone https://github.com/lgyEthan/v_ase.git
cd v_ase
python -m pip install -e .

Start an empty workspace or open a file:

v_ase gui
v_ase gui FILE

Examples:

v_ase gui POSCAR
v_ase gui trajectory.extxyz
v_ase gui relaxation.traj
v_ase gui project.vase

The default View mode is optimized for visualization, trajectories, measurement, appearance, bonds, supercells, and export. Use the top-bar mode switch or start directly in Edit when atomic coordinates must change:

v_ase gui structure.vasp --interactive

No Node.js installation or hosted account is required. Closing the v_ase browser document releases the blocking terminal process.

Everyday Workflow

Viewport tip: after selecting atoms, press Esc to close the control panel before using G or R. The selection is preserved and keyboard focus returns to the 3D viewport.

Ask An AI To Edit A Structure

Give an AI the bundled v_ase agent skill, then describe the scientific result rather than a sequence of mouse actions:

From this pristine 6 x 6 graphene sheet, remove the carbon nearest the cell center, convert its three nearest neighbors to pyridinic nitrogen, add a Li_site atom 2.15 A above the vacancy, preserve PBC and bonds, use a clean oblique studio-shadow view, and render a 4K image.

The agent reads atom identities, coordinates, cell, PBC, selection, and camera directly from v_ase's semantic state. It finds the central site, resolves and remaps neighbor indices after deletion, changes three ASE elements and labels, creates Li at a measured height, verifies the 72-atom result, and renders the same document a human can continue editing. This combines geometry search, topology editing, atom creation, styling, and export in one request. No screenshot OCR or coordinate guessing is required. The final validation checks three N_pyridinic labels and one Li_site label against ASE elements.

This example is generated entirely from ase.build.graphene, so it contains no copied structure or private data:

• source graphene CIF
• intermediate pyridinic N3 CIF
• final N3/Li-site CIF
• ASE trajectory preserving labels

Structure Manipulation

Use Edit when atom coordinates must change. Selection, measurement, appearance, bonds, replication, wrapping, visual translation, and export remain available in the default View mode.

Select

• Left-click selects one atom; Shift + click extends or removes selection.
• Left-drag draws a visible selection box.
• Appearance rows select complete label groups without merging distinct labels.
• Ordered single-atom selections are retained for geometry measurement.

Move

Press G after selecting atoms. Lock the move with X, Y, or Z, type an exact displacement in angstrom, then confirm with left-click or Enter. Configured ASE constraints remain authoritative when Apply constraints is enabled.

Rotate

Press R after selecting atoms. Choose Selection COM, Origin, or Unit-cell center as the pivot, lock an axis if needed, and enter an exact angle. For a panel-driven edit, use Structure > Transform > Exact selection rotation to choose the axis and angle, then click Rotate Selection. Both methods honor the current constraint and undo settings. Every active rotation shows:

• the rotation axis through the chosen pivot;
• a neutral line fixed at the direction where the operation started;
• an amber line that follows the current structure;
• cyan candidate lines only when the commensurate guide is enabled.

Ferrocene: Choose The Pivot

The GIF contains both operations needed to understand the pivot:

1. Rotate pivot = Origin, then R, Z: the selected upper cyclopentadienyl ring rotates around an axis through Fe.
2. Rotate pivot = Selection COM, then R, X: the same ring folds about its own center instead of orbiting the external Fe pivot.

The selected ring is unchanged between the two passes, so the different motion comes only from the pivot and axis settings.

Phosphorene: Build The Twist One Edit At A Time

The animation records a sequence of normal v_ase edits:

1. Keep the first puckered ridge fixed. Left-drag the visible amber box from the second ridge through the end of the ribbon, then release to commit the yellow outlined selection.
2. Open Structure > Transform, keep Selection COM, choose axis X, enter 1.538889 degrees, and click Rotate Selection.
3. Close the panel, left-drag a new box from the third ridge through the end, enter the same exact angle, and rotate again from the edited coordinates.
4. Continue advancing the box-selection boundary by one 12-atom ridge. After 9 rotations, the final ridge is rotated by exactly 13.85 degrees.
5. Orbit the completed structure from above to below to inspect the full three-dimensional twist.

The amber box shows the current selection area, the yellow outline identifies the atoms affected by the next edit, and bonds update after each rotation.

Black phosphorene has two puckered sublayers in one armchair unit cell. The 5 x 6 model contains 10 puckered ridges with 12 atoms per ridge. Green and purple distinguish the upper and lower P sublayers; both remain phosphorus in the ASE structure.

The relaxed source coordinates come from the supporting information of Villegas et al.. The 13.85 degree target is one of the H-APNR angles tabulated by Jang et al., and the green/purple sublayer convention follows published phosphorene structure diagrams such as Zhang et al.. The example demonstrates geometry editing and is not an energy-minimized final structure.

Graphene/hBN: Find A Commensurate Rotation

Select the hBN layer, enable Commensurate guide, then use R, Z. The top view intentionally hides the world X/Y/Z axes so the neutral start line, amber current line, and labeled cyan cell-match candidates remain distinct. Magnetic angle snap can pull the active rotation to a candidate within the configured tolerance.

Normal R rotates selected atoms. Cell Transform is a separate periodic operation that applies an integer matrix to the cell and every trajectory frame. Its equations and assumptions are documented in unit_cell_aware_rotate.md.

Measurement And Analysis

The numbered a1 to a4 markers record selection order and are deliberately different from atom indices.

The connector, angle arc, torsion axis, and compact value badge stay attached to the selected atoms. Hover information is independent, so moving the pointer does not replace a saved measurement.

For trajectories, Analysis > Displacement compares the current frame with the previous frame or a chosen reference. Minimum-image correction, vector scale, thickness, color, and 2D/3D style are configurable. Displayed supercells repeat the vectors, and visual translation moves both endpoints without changing the physical displacement.

Constraints

ASE remains authoritative when Apply constraints is enabled. Constraint visualization is local to each atom rather than merged at a group center.

FixedLine

A short cyan line passes through each constrained atom and remains visible without selection. Starting G displays a longer guide through the atom's original position while ASE restricts movement to that direction. FixedLine does not use a ring or plane disc.

v_ase gui examples/readme_scene_assets/fixedline.traj --interactive

FixedPlane And FixScaled

Each constrained atom keeps its own local ring, crosshair, and normal marker. When G starts, a larger translucent guide plane appears at that atom's original position so the permitted surface remains visible while the atom moves. Multiple selected atoms retain independent planes; no center-of-mass plane is substituted.

VASP selective dynamics read as FixScaled are displayed from their allowed fractional directions.

v_ase gui examples/readme_scene_assets/fixedplane.traj --interactive

FixAtoms

Fixed atoms keep their element color but use a distinct constrained surface treatment. They remain identifiable without looking selected.

Hookean

Hookean constraints show their inactive cutoff and engaged state separately. After the constrained distance passes rt, a shaded 3D helical spring appears between the constrained atoms.

v_ase gui examples/readme_scene_assets/hookean.traj --interactive

Relaxation

Structure > Relaxation places every optimization step on a dedicated timeline. A single loaded structure gains a relaxation movie after the first run. If a source trajectory is already open, source and relaxation timelines remain separate and the active timeline is clearly selected.

The included example starts from a deliberately compressed C60 geometry and runs ASE FIRE with v_ase's repulsive fallback calculator:

• crowded initial C60
• relaxed C60
• optimization trajectory

v_ase gui examples/readme_scene_assets/crowded_c60_initial.cif --interactive

The fallback calculator is intended for removing obvious close contacts, not for predictive chemistry. Its cutoff scale and strength are editable. Attach a scientific ASE calculator when the optimized energy or forces will be used as physical results.

Trajectories

Multi-frame inputs add a timeline below the viewport. Scrubbing updates the frame continuously, selected atom indices persist when topology permits, FPS changes apply during playback, and Skip advances by skip + 1 source frames per tick.

Bond topology is evaluated for each frame, so bonds form or break when a pair crosses its cutoff. Appearance, pair settings, supercell display, camera, and analysis settings remain active across the movie.

Video export uses FPS as playback speed. Optional N x interpolation creates (source_frames - 1) * N + 1 output frames. Minimum-image interpolation uses periodic cells to avoid jumps across a boundary. Interpolation takes longer because more frames are rendered.

Appearance, Bonds, And Rendering

Structure > Appearance controls each stable atom label:

• ASE chemical TYPE and independent visual label;
• visibility and selection availability;
• color and radius;
• Standard, Metal, or Rubber material;
• all/partial/none selection checkbox.

View mode applies appearance by label. Edit mode can keep per-atom material overrides. Relabeling does not reorder the table or merge otherwise distinct atom types accidentally.

The comparison uses three identical Cu13 clusters with the same element color and radius, so only the optical material changes:

Materials affect rendering only. ASE elements, coordinates, calculators, and constraints are unchanged.

Structure > Bonding provides automatic inference, explicit label-pair cutoffs, and manual index pairs. A pair cutoff of zero disables that pair. Changes apply immediately. Bonds support:

• cell-local or periodic minimum-image display;
• cylinder or flat 2D geometry;
• custom color or two half-bonds using the atom colors;
• configurable diameter;
• live formation and breaking during Edit transforms.

The top view shows a 6 x 6 Cu2O(111) film on 7 x 7 Cu(111), with one interfacial oxygen positioned over a substrate Cu top site. The Cu(111) substrate uses a nearest-neighbor touching-sphere radius. Cu_oxide-O_oxide and Cu_substrate-O_oxide bonds are enabled, while Cu_substrate-Cu_substrate, Cu_oxide-Cu_oxide, cross-region Cu-Cu, and O-O pairs are disabled. Separate oxide and substrate labels let each interaction be enabled or assigned its own cutoff independently.

v_ase gui examples/readme_scene_assets/cu2o111_on_cu111_pairwise_bonds.traj

View controls projection, atomic scale, anti-aliasing, sphere smoothness, background, 2D/3D display, grid, axes, unit cell, overlays, and cell material. The Axes and Unit Cell switches update the working viewport immediately; they are not export-only settings. Hiding world axes does not remove the compact orientation gizmo. New documents use orthographic projection and a true-white background.

The top-bar renderer switches between fast modeling light and Sun/soft-shadow rendering. Sun source, target, intensity, and direction can be manipulated in the viewport and carried into Blender export.

Export And Save

The Preview Area is the authoritative image/video frame. Its aspect ratio, camera, crop, lighting, atom scale, and included overlays match the export. Cell, grid, axes, and background can be included or excluded independently.

The system save picker is opened before expensive rendering or scene generation when the browser supports it. Canceling the picker cancels the export. Chrome may then show This site can view changes you make to this file. That message is Chrome's File System Access permission notice: v_ase can write only to the destination selected in that picker. Browser code cannot hide the notice while retaining destination selection before rendering.

Image export uses one determinate progress bar for rendering, pixel capture, upload, encoding, download, and the final file write. It reports estimated remaining time and reaches 100% once, only after the destination is complete. Video export follows the same monotonic rule across all frames and encoding. Every source frame is retained exactly once at 1x; interpolation adds in-between frames. Visible displacement vectors and other selected scene overlays are recalculated for each rendered frame.

Project Or Shareable HTML

Under Export > v_ase Project, use Save .vase for the smallest complete project. It contains every loaded frame, coordinates, cells, PBC, labels, constraints, safe calculator results, camera, appearance, bonds, lighting, analysis, and export settings. It is self-contained and never references the original input file.

Use Save HTML or Export HTML View when the result should open directly in a browser. Before saving, choose whether to enable Embed editable .vase project. The save dialog previews the rendered structure that will initialize the standalone viewer. Every generated HTML:

• opens offline without v_ase, Python, a server, or a CDN;
• restores the saved camera, viewport styling, bonds, constraint overlays, displacement vectors, supercell, visual translation, and trajectory;
• allows orbit, pan, zoom, frame stepping, and movie playback;
• exposes no atom, structure, appearance, or project editing controls.

With project embedding enabled, the HTML also includes the complete .vase. The viewer exposes Download .vase, and either command restores the full editable project:

v_ase gui project.vase
v_ase gui project.html

With project embedding disabled, the file is smaller and remains a portable view-only document. It cannot be restored as an editable v_ase project. v_ase reports this explicitly if that lightweight HTML is opened as input.

HTML is larger than .vase because it contains the browser renderer and immediately readable scene data. Embedding adds a Base64 copy of .vase on top of that. Keep .vase as the compact editable source of truth.

Opening an ordinary structure in an existing tab keeps the current visual settings; opening .vase or project-embedded HTML restores the saved project.

Rhino export requires the optional dependency:

python -m pip install "v_ase-gui[rhino]"

OBJ export has no optional Python dependency.

AI And Agent Use

Install v_ase normally and give the AI the bundled skill. The AI starts the machine-readable session itself when the task requires it; a person does not need to launch a separate AI mode.

v_ase gui STRUCTURE --cli

--cli does not bundle an LLM or make v_ase an AI model. It is a terminal-oriented local API mode that suppresses automatic browser launch and prints a JSON handshake. The agent uses that handshake to inspect coordinates, cell, constraints, trajectory frames, selection, measurements, camera, materials, lighting, and export state without interpreting screenshots. Its human_url opens the same document whenever a person wants to take over.

Use the complete v_ase agent skill. It is vendor-neutral and can be used by Codex, Claude Code, ChatGPT desktop agents, Gemini-based agents, agentic IDEs, or another model that can run local commands or control a browser. The agent setup reference explains each integration path.

What To Give The AI

Prefer the complete skill directory. If the client accepts only individual files, provide the following:

The agent launches the document and parses the first JSON line itself:

v_ase gui STRUCTURE --cli

That line contains the live GUI URL, semantic state URL, command schema URL, browser API name, and installed skill path. Do not paste screenshots or manually transcribe coordinates when the semantic state is available.

This bootstrap instruction works for clients without a native skill loader:

Read SKILL.md and agent-setup.md first. Load only the reference files needed
for this task. Start v_ase with --cli, inspect capabilities() and describe()
before editing, execute semantic operations one at a time, verify state after
each physical change, inspect the decoded final render, and give me human_url
for manual takeover.

The compatibility document skills_v_ase.md points existing integrations to the same canonical skill and reference set.

Installing The Skill

Clients with skill-folder support should install the complete directory:

# Codex
cp -R v_ase/skills/visualizing-atomic-structures-with-v-ase "$CODEX_HOME/skills/"

# Claude Code, from a project root
mkdir -p .claude/skills
cp -R v_ase/skills/visualizing-atomic-structures-with-v-ase .claude/skills/

For another AI, use its documented local skill directory if it supports the same SKILL.md convention. Otherwise attach the files listed above or make them readable in the project and include the bootstrap instruction. The live semantic protocol is the same regardless of model vendor.

Documents And File Opening

The top-bar Open button starts with the operating system file picker. A selected file can:

1. replace the active document;
2. append structures to its current trajectory;
3. open in a new independent v_ase tab.

If the active document is empty, the selected file opens there immediately; the destination chooser is shown only when a document already contains a structure or trajectory.

The + beside the document tabs creates an empty independent document. Each tab owns its structure, trajectory, camera, selection, history, settings, calculator, and .vase output.

Adding .vase to an existing trajectory imports only its structures and keeps the current tab's visual state. Replacing a tab or opening a new one restores the complete .vase project.

Python

from ase.build import molecule
from v_ase.visualize import view

atoms = molecule("H2O")
view(atoms)  # View mode

Return an edited ASE object:

edited = view(atoms, viz_only=False)
print(edited.positions)

view() accepts one ASE Atoms, a sequence of frames, or a supported file path. view_edit() remains a compatibility alias for Edit mode.

File Formats

Common inputs include POSCAR/CONTCAR, VASP files, XDATCAR, vasprun.xml, XYZ/extxyz, ASE .traj, LAMMPS dump/data, CIF, and .vase. ASE readers cover additional formats.

Use --format when an ambiguous filename does not identify the reader:

v_ase gui ABCD --format POSCAR
v_ase gui ABCD --format vasprun.xml
v_ase gui ABCD --format lammpstrj
v_ase gui ABCD --format data

Use --index : for every frame, --index -1 for the last frame, or an integer for one frame.

Repeated POSCAR/CONTCAR species blocks remain separate visual labels. For example, O Cu O with counts 1 14 5 becomes O1, Cu, and O2 while all oxygen atoms remain ASE element O.

Controls

The ? button contains the complete shortcut table.

Remote Servers

Install v_ase on both the local computer and remote host, then run one command locally:

v_ase gui USER@SERVER:/absolute/path/to/STRUCTURE

An SSH config alias works:

v_ase gui physics:/absolute/path/to/trajectory.extxyz

v_ase selects private ports automatically, starts the backend beside the remote file, creates the SSH tunnel, and opens the local browser. The source file and full trajectory cache remain on the server; only the current frame data required for local Three.js rendering crosses the tunnel. Use ProxyJump in ~/.ssh/config when a login node is required.

Troubleshooting

python -m pip install --upgrade v_ase-gui
python -m v_ase.cli --version

(base) giyeok@DESKTOP-XXXX:~$ v_ase gui
gio: http://127.0.0.1:58039/workspace?workspace_id=xxxx&session_id=xxxx: Operation not supported

v_ase gui FILE --format POSCAR
v_ase gui FILE --format vasprun.xml
v_ase gui FILE --format lammpstrj
v_ase gui FILE --format data

python -m venv .venv
python -m pip install --upgrade pip
python -m pip install v_ase-gui

Run v_ase --help or v_ase gui --help for all CLI options. Report reproducible problems at GitHub Issues.