Metadata-Version: 2.4
Name: v_ase-gui
Version: 0.4.6
Summary: A local 3D viewer, editor, and analysis workspace for atomistic structures, trajectories, and DFT fields.
Author: v_ase contributors
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/lgyEthan/v_ase
Project-URL: Documentation, https://v-ase.readthedocs.io/
Project-URL: Repository, https://github.com/lgyEthan/v_ase
Project-URL: Issues, https://github.com/lgyEthan/v_ase/issues
Project-URL: Changelog, https://v-ase.readthedocs.io/en/latest/whats-new.html
Keywords: ase,atomistic-simulation,materials-science,molecular-visualization,trajectory-analysis,density-functional-theory,scientific-visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase>=3.26
Requires-Dist: matscipy<1.2.0,>=1.1.1; python_version < "3.13"
Requires-Dist: matscipy>=1.2.0; python_version >= "3.13"
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: numpy<2.0,>=1.24; python_version < "3.13"
Requires-Dist: numpy>=2.0; python_version >= "3.13"
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-image>=0.23
Requires-Dist: plotly>=5.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: imageio-ffmpeg>=0.5
Requires-Dist: Pillow>=10
Requires-Dist: requests>=2.31
Requires-Dist: jsonschema>=4.23
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.1.1; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: playwright>=1.40; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: rhino
Requires-Dist: rhino3dm>=8.0; extra == "rhino"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/v_ase-logo.png" width="720" alt="v_ase logo">
</p>

# v_ase

[![PyPI version](https://img.shields.io/pypi/v/v_ase-gui.svg)](https://pypi.org/project/v-ase-gui/)
[![Python versions](https://img.shields.io/pypi/pyversions/v_ase-gui.svg)](https://pypi.org/project/v-ase-gui/)
[![Documentation Status](https://readthedocs.org/projects/v-ase/badge/?version=latest)](https://v-ase.readthedocs.io/en/latest/?badge=latest)
[![License: AGPL v3+](https://img.shields.io/badge/license-AGPL--3.0--or--later-2f855a.svg)](LICENSE)

[Documentation](https://v-ase.readthedocs.io/en/latest/) ·
[PyPI](https://pypi.org/project/v-ase-gui/) ·
[Changelog](https://v-ase.readthedocs.io/en/latest/whats-new.html) ·
[Issues](https://github.com/lgyEthan/v_ase/issues)

**v_ase 0.4.6 — live atom styling and stable camera framing** ·
[Changes](https://v-ase.readthedocs.io/en/latest/whats-new.html)

An ASE-native workspace for building, editing and visualizing atomic structures,
trajectories and volumetric data.

![Phosphorene nanoribbon manipulation](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_phosphorene_twist.gif)

Trajectory navigation retains double-precision coordinates and committed edits
through frame switches, animation output and scientific project exports.
Animation export restores the current frame and selection; an empty colorscale
target maps no atoms and does not block export. GUI and agent project saves
both retain the document's mode and presentation.
Agent revision snapshots wait for pending change notifications to finish.
Renderer scale and atom radius remain independent.

## Installation And Launch

macOS and Windows users can install the self-contained
[desktop app](https://v-ase.readthedocs.io/en/latest/desktop.html) from
[GitHub Releases](https://github.com/lgyEthan/v_ase/releases/tag/v0.4.6).
It runs the same GUI with native Command/Ctrl shortcuts and file dialogs;
Python installation is not required. Python and Jupyter remain available
independently. Drag a desktop tab out to detach it into another window.
**Help → About this runtime** shows the installed desktop version.
Dropped structures offer trajectory, new-tab and new-window destinations. Saved
`.vase` projects open immediately in their saved Edit/View mode and presentation,
using a new tab when the current document has content. Each
window closes independently; Windows Alt+F4 closes the active window, while
explicit Quit checks all windows. The app icon now features the full atomic-bead
castle with its small Pinocchio detail and no projecting red foundation board.

| Desktop download (0.4.6) | Install and launch |
| --- | --- |
| [Mac, Apple silicon](https://github.com/lgyEthan/v_ase/releases/download/v0.4.6/v_ase-0.4.6-mac-arm64.dmg) | macOS 15+: open the DMG, drag **v_ase** to **Applications**, eject the disk image, then launch the Applications copy. |
| [Mac, Intel](https://github.com/lgyEthan/v_ase/releases/download/v0.4.6/v_ase-0.4.6-mac-x64.dmg) | Same steps; choose Intel when **About This Mac** shows an Intel processor. |
| [Windows, Intel/AMD x64](https://github.com/lgyEthan/v_ase/releases/download/v0.4.6/v_ase-0.4.6-win-x64.exe) | Windows 10/11, 64-bit: run the EXE installer, complete installation, then launch **v_ase** from Start. |

The Mac downloads are **Developer ID signed and Apple-notarized**, with
stapled tickets for the app and DMG. macOS may show its normal first-open
confirmation for an internet download. The Windows build is **not yet
publisher-signed**; after verifying its source and checksum, a SmartScreen
prompt may offer **More info → Run anyway**. Do not disable OS protection.
[Step-by-step installation, ZIPs, checksums and troubleshooting](https://v-ase.readthedocs.io/en/latest/desktop.html).
Maintainer build, signing and notarization steps are in
[the desktop build guide](desktop/README.md).

`.vase` is registered as a project type. To make double-click use v_ase, choose
**Get Info → Open with → v_ase → Change All** on Mac, or **Open with → Choose
another app → v_ase → Always** on Windows. You can also select v_ase for
`.vasp`, `.xyz` and `.cif`; browse to the installed application if it is not
listed. Extensionless `POSCAR`/`CONTCAR` can be opened using **File → Open**.
[Complete file-association instructions](https://v-ase.readthedocs.io/en/latest/desktop.html#open-vase-by-default).

For the Python/browser/Jupyter installation:

```bash
python -m pip install v_ase-gui
v_ase gui POSCAR
```

Use `v_ase gui` for an empty workspace or `--interactive` to edit a file.
[Installation](https://v-ase.readthedocs.io/en/latest/installation.html) · [First session](https://v-ase.readthedocs.io/en/latest/quickstart.html) ·
[Supported formats](https://v-ase.readthedocs.io/en/latest/formats.html) · [Troubleshooting](https://v-ase.readthedocs.io/en/latest/troubleshooting.html)

## Explore

| Work with | Guide |
| --- | --- |
| Atoms and molecules | [Move](https://v-ase.readthedocs.io/en/latest/move.html) · [Rotate](https://v-ase.readthedocs.io/en/latest/rotate.html) · [Build](https://v-ase.readthedocs.io/en/latest/build-atoms.html) |
| Periodic interfaces | [Cells, matching, registry](https://v-ase.readthedocs.io/en/latest/cell-tools.html) |
| Trajectories and fields | [Analysis](https://v-ase.readthedocs.io/en/latest/trajectories.html) · [Volumetric data](https://v-ase.readthedocs.io/en/latest/field-processing.html) |
| Figures and projects | [Appearance](https://v-ase.readthedocs.io/en/latest/appearance.html) · [Export](https://v-ase.readthedocs.io/en/latest/save-projects.html) |
| AI agents | [MCP setup](https://v-ase.readthedocs.io/en/latest/ai-tools.html) · [GUI/MCP comparison](https://v-ase.readthedocs.io/en/latest/agent-material-evaluation.html) |
| Numerical methods | [Validation](https://v-ase.readthedocs.io/en/latest/scientific-validation.html) · [Source audit](docs/scientific-source-audit.md) |

## Save And Share

One HTML file for offline viewing and project recovery.
[Project HTML](https://v-ase.readthedocs.io/en/latest/save-projects.html#project-html) · [Export HTML View](https://v-ase.readthedocs.io/en/latest/save-projects.html#html-view)

The editor keeps the atomic viewport wide, with no permanent left navigator.
The optional **Objects** drawer overlays the scene, while the right workbench
has **Style / Build / Analyze / Render** tabs. An icon bookmark strip sits above
the selected section title; hover or keyboard-focus an icon to see its name.
Each section has its own symbol, including selection Transform, Cell matrix and
energy-minimization Relax. Search in the header finds existing controls.
The left icon toolbar separates selection/measurement, transforms of selected
objects, camera orbit and object creation. Move/Rotate/Scale require an editable
selection; click one and drag in the viewport, or enter an axis and value.
Apply/Enter confirms, Cancel/Escape restores the original, and switching tools
cancels a provisional transform. Keyboard G/R/S retains its modal workflow.
Saved per-atom colorscales are applied before a reopened project is ready to render.
Atom appearance uses compact per-label rows with horizontal scrolling, distinct
scope headings, and explicit property/range/target controls. Scrollable tables
keep their headers flush with the top border, including Relaxation cutoffs. **Apply to → Selected atoms** captures colorscale targets until you choose
**Use current selection**; label choices capture the indices belonging to that label.
Later selection, element changes and shorter trajectory frames never redirect or
clear these targets. Indices absent from a frame resume their mapping when present
again. Property menus are preloaded without fetching unused scalar arrays.
Trajectory coordinates, colors and radii are presented together.
Selected appearance is live: committing a new label separates the selection;
changing color, material, opacity or size first creates an unused `Element_2`
label (`Element_3`, etc.). The label table immediately shows the same settings,
including the resulting radius in Å. Undo restores the initial split and its
first adjustment together. Reusing an existing label asks to merge and inherit
its settings. Surface materials live only in the per-label table.
**Render → Render area & scale → Show render area** draws a crop guide over the
editable canvas. **Lock camera to → World** keeps the camera at its coordinates;
**Viewport** keeps the render area on screen while navigation changes the
composition. Switching locks preserves output framing. The camera-view icon
beside the axis presets indicates **Look through camera**; orbiting away in
World mode turns it off, while pan/zoom keep it on. Clicking it returns to the
saved camera without changing locks. **Align camera to current view** is a
separate action that deliberately replaces the output pose.
Select the outlined **Camera** badge or the oriented wire camera for **G** move,
**R** rotation about the render center and **S** area scaling. Enter applies and
Escape cancels. In Viewport lock the area stays still and the scene moves;
X/Y/Z retain the area immediately. Initial framing accounts for the right panel,
without recentering when panels open or overriding saved/user framing.
**Objects** controls visible guides and scientific overlays in both the viewport
and output. **Constraints** hides constraint marks without disabling ASE
constraints. Flat 2D uses crisp fixed-atom crosses and disables materials and
lighting controls. Both Renderer and Viewport offer 2D/3D. Image and video use
the same saved render area; video supports inclusive frame ranges, MOV/AVI and
GIF with **Loop forever** or **Play once**. Analysis and property mapping show
activity while asynchronous work is pending.
Desktop project and structure files have paper-shaped document icons bearing
the castle; the application keeps its full castle icon. Only `.vase` is registered
as the native default type. Structure formats including `.extxyz`, `.xyz`, `.vasp`
and `.cif` remain optional handlers: select v_ase explicitly in Open With / Get
Info. macOS never automatically chooses it for these secondary types. Generic
`.json`, `.xml`, `.html`, `.md` and `.log` associations are not registered;
project HTML and specialized files are still importable through File → Open.
An empty workspace opens its first file without replacement/append choices.
The right panel overlays the scene without shifting the camera and expands up
to 900 px when the window permits. Bonds opens editable pair specifications by
default; **Reset to suggested cutoffs** restores radius-derived suggestions.
Ctrl+A selects the entire number in an input on Mac as well as Windows; Tab and
Shift+Tab move through successive bond cutoffs. The visible Reset menu offers
coordinates-only and full reset. Open uses Command+O on Mac / Ctrl+O on Windows. **Fit view** or F frames the structure when the viewport has focus.
Save
reuses an approved writable project target; Save As chooses a new one. When
the browser only supports downloads, v_ase labels the result a copy rather
than implying it can overwrite the original. Closing a changed document
offers Save, Discard and Cancel. On desktop, Command/Ctrl+W closes the active
tab, or its window when it is the last tab; closing the last window quits.
An empty desktop window also closes. Native shutdown issues a single quit
request after its save/cancel checks. Browser/notebook editors retain a blank
internal tab and never intentionally close the host browser tab. Direct and notebook editors adopt tabs in place without
reloading the original document. Pending physical edits settle before Save,
Close or Replace can discard anything; invalid scientific inputs block Save
before a file destination is chosen. Uploaded project tabs retain their
format and writable target after an internal-tab reload, including after
Save As. Clean saved appearance and the latest unsaved visual edits survive
child-tab reloads. Exact delivered Command shortcuts on macOS and Ctrl
shortcuts on Windows/Linux are listed in
[Keyboard shortcuts](https://v-ase.readthedocs.io/en/latest/shortcuts.html).
Plain arrow keys orbit or tilt the structure view; Option+Left/Right on macOS
or Alt+Left/Right on Windows/Linux steps the selected trajectory. A single selected atom's footer shows its current label, Cartesian X/Y/Z, custom
properties (including existence) and stored forces. It omits chemical-element,
mass and fractional-coordinate boilerplate; no floating note covers the canvas.
The Supercell shortcut selects the first value so `2 Tab 2` enters 2 × 2 directly.
Navigation shortcuts discard an invalid draft and retain the last valid value;
invalid edits still cannot be committed with Enter, Tab or Save.
Analysis plots open in a resizable dock below the canvas, with a full-work-area
Back view on short windows.

Render → Renderer exposes lighting, quality, output dimensions and an
independent physical output scale (px/Å); changing that scale does not zoom the
live viewport or resize atom glyphs. Image, Video and Interactive HTML each
have format-specific settings next to their export action; changing an
export draft and canceling its dialog leaves the project profile unchanged.
Saved GUI image/video guide choices synchronize with Objects; hidden objects
cannot be reintroduced by export settings. Enabling stored force vectors through
a scene preset also loads the current frame before reporting the scene ready.
Objects lists loaded field objects and opens their actual isosurface and plane
property controls; Analyze retains field import, processing and combinations.
Objects also links vector layers and their live style controls, while Build
separates selection transforms from periodic-cell
matching and rigid translation from Analyze's translation map. Command search
can reveal a matching control directly. Replacing a dirty tab asks Save,
Discard or Cancel; uploaded HTML projects keep their HTML save profile when
opened in a new tab. Fullscreen editing requests Keyboard Lock where the browser
permits it; the status distinguishes active, denied and unsupported capture.
File-menu controls remain available when reserved keys cannot be captured.


## Work With An AI Agent

You and an external agent edit the same live document.
[Connect MCP](https://v-ase.readthedocs.io/en/latest/ai-tools.html#install-and-connect-an-mcp-client) ·
[Scene workflow](https://v-ase.readthedocs.io/en/latest/ai-scene.html) · [CLI compatibility](https://v-ase.readthedocs.io/en/latest/ai-cli.html)

[ChatGPT Chat setup](https://v-ase.readthedocs.io/en/latest/chatgpt-local.html) · personal connection.

![Human and external AI agent working in one live v_ase document](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_ai_collaboration.png)

```bash
python -m pip install "v_ase-gui[mcp]"
v_ase mcp
```

**60-run comparison:** MCP completed 30/30 strict targets; GUI completed 24/30.
[Images, token usage and success criteria](https://v-ase.readthedocs.io/en/latest/agent-material-evaluation.html)

**Cu₈O₄ extension:** both completed 10/10; MCP used 90.9% fewer median tokens.
[Images and methods](https://v-ase.readthedocs.io/en/latest/agent-material-evaluation.html#cu8o4-prepared-scene-extension)

![A natural-language request passing through an external AI Agent into the same live revisioned v_ase GUI](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_ai_collaboration.gif)

Exact atom edits from a natural-language request.
[Agent workflow](https://v-ase.readthedocs.io/en/latest/ai-agents.html#share-one-document) ·
[Bundled Skill](v_ase/skills/visualizing-atomic-structures-with-v-ase/SKILL.md)

![Natural-language pyridinic N3 graphene edit in the shared GUI](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_ai_edit.gif)

## Edit Structures

Select atoms, then use `G` to move, `R` to rotate and `S` to scale coordinates.
[Editing guide](https://v-ase.readthedocs.io/en/latest/editing.html#move-rotate-and-scale-coordinates) · [Controls](https://v-ase.readthedocs.io/en/latest/shortcuts.html)

### Build From Scratch

Define a cell and distribute atoms; refine overlaps with repulsion.
[Atomic distributions](https://v-ase.readthedocs.io/en/latest/atomic-distributions.html) · [ASE crystal builder](https://v-ase.readthedocs.io/en/latest/build-atoms.html#build-a-periodic-bulk-crystal-with-ase)

![Building an amorphous structure from an empty v_ase document](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_scratch_amorphous.gif)

### Add Atoms

Set composition, density, placement and allowed regions.
[Insertion workflow](https://v-ase.readthedocs.io/en/latest/insertion-regions.html)

![Oxygen distributed through a bulk-like Cu(111) insertion region](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_add_atoms_allowed.gif)

### Add Molecules

Place rigid molecules around an existing structure.
[Molecular insertion](https://v-ase.readthedocs.io/en/latest/atomic-distributions.html#insert-rigid-molecules)

![Rigid water molecules placed around edge- and basal-hydroxylated graphene-oxide layers](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_add_molecules.gif)

### Rotate Selected Atoms

Rotate around an active atom, center of mass or explicit pivot.
[Pivot controls](https://v-ase.readthedocs.io/en/latest/rotate.html)

![Ferrocene pivot rotation](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_ferrocene_pivot.gif)

Build a phosphorene twist through successive selections and rotations.
[Worked examples](https://v-ase.readthedocs.io/en/latest/worked-examples.html)

![Cumulative phosphorene manipulation](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_phosphorene_twist.gif)

## Periodic Cells And Interfaces

### Commensurate Cells

Find compatible 2D cells within declared strain and search limits.
[Same-lattice matching](https://v-ase.readthedocs.io/en/latest/commensurate.html#commensurate-same-lattice-rotation)

![Graphene hBN commensurate rotation](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_commensurate.gif)

Match separate host and guest lattices.
[Host/guest workflow](https://v-ase.readthedocs.io/en/latest/commensurate.html)

![Graphene and MoS2 host/guest common-cell search with a live angle plane](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_commensurate_host_guest.gif)

### Rigid Translation

Map registry or relax a selected rigid component.
[Registry maps](https://v-ase.readthedocs.io/en/latest/registry.html#registry-maps) · [Rigid relaxation](https://v-ase.readthedocs.io/en/latest/registry.html#rigid-registry-relaxation)

![Periodic planar translation scan with current and optimum translations](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_registry_map.png)

![Rigid planar translation trials without a precomputed colorscale map](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_registry_relax.gif)

## Analyze Structures And Fields

### Ordered Geometry

Click 2, 3 or 4 atoms deliberately in order for distance, angle or torsion.
Marquee, label and Select all selections show a count without incidental geometry.
[Measurements](https://v-ase.readthedocs.io/en/latest/selection.html#ordered-geometry-through-a-trajectory)

### Property-based atom size

The Atom appearance controls include a global-size slider with a numeric input
and an independent per-atom property radius mapping. Select an available
numeric field, input range, minimum/maximum size multipliers and exponent.
Enabling the mapping first reveals the field picker; it does not apply a
placeholder property. Custom and charge presets fit the displayed frame's
finite values, including signed data and the frozen atom scope.
The mapping multiplies existing label and selected-atom sizing; a zero factor
hides the glyph, not its scientific atom or bonds. Current and trajectory fits
lock their resulting limits until fitted again.
[Field, scope, fit and export details](https://v-ase.readthedocs.io/en/latest/property-radius.html).

![Ordered distance angle and torsion measurement](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_measurement.gif)

### Trajectories And Displacement

Scrub frames and inspect displacement against a reference.
[Trajectory analysis](https://v-ase.readthedocs.io/en/latest/vectors.html#displacement-analysis)

![Trajectory displacement analysis](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_displacement.png)

### Map Per-Atom Data

Color atoms by stored properties and display force vectors.
[Colorscales](https://v-ase.readthedocs.io/en/latest/scalar-colors.html#map-numeric-per-atom-data) · [Forces](https://v-ase.readthedocs.io/en/latest/vectors.html#stored-force-vectors)

![Trajectory-wide force-magnitude colorscale with locked limits and matching Cartesian force vectors](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_atom_colorscale.gif)

### Volumetric Fields

Inspect charge, potential and orbital grids as isosurfaces or planar sections.
[Isosurfaces](https://v-ase.readthedocs.io/en/latest/isosurfaces.html#create-an-isosurface) · [Planes](https://v-ase.readthedocs.io/en/latest/field-planes.html#add-planar-sections) ·
[Combine fields](https://v-ase.readthedocs.io/en/latest/field-processing.html#combine-compatible-datasets)

![Signed isosurface threshold moving across a fixed volumetric distribution](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_volumetric.gif)

![Interactive hkl scalar-field plane clipped to the displayed cell](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_volumetric_plane.gif)

### Radial And Pair-distribution Functions

Plot periodic RDFs or finite pair distributions with the appropriate normalization.
[RDF guide](https://v-ase.readthedocs.io/en/latest/rdf.html)

![Pairwise amorphous Cu-Zr RDF curves approaching the bulk limit](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_rdf.png)

## Constraints And Relaxation

Constrain physical motion using ASE constraints.
[Constraint guide](https://v-ase.readthedocs.io/en/latest/constraints.html#supported-constraint-state)

### FixedLine

Restrict motion to a line. [Details](https://v-ase.readthedocs.io/en/latest/constraints.html#fixedline)

![FixedLine movement](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_fixedline.gif)

### FixedPlane And FixScaled

Restrict motion in Cartesian or fractional directions.
[FixedPlane](https://v-ase.readthedocs.io/en/latest/constraints.html#fixedplane) · [FixScaled](https://v-ase.readthedocs.io/en/latest/constraints.html#fixscaled-and-fixcartesian)

![FixedPlane movement and guide plane](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_fixedplane.gif)

### Hookean

Apply spring-like restraints. [Details](https://v-ase.readthedocs.io/en/latest/constraints.html#hookean)

![Hookean constraint](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_hookean.png)

![Hookean motion](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_hookean.gif)

### Relaxation

Reduce overlaps or optimize with a configured calculator.
[Repulsion](https://v-ase.readthedocs.io/en/latest/relaxation.html#built-in-repulsion-calculator) · [Run relaxation](https://v-ase.readthedocs.io/en/latest/relaxation.html#run-an-ordinary-relaxation)

![Repulsive relaxation trajectory](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_relaxation.gif)

## Coordination Polyhedra

Show coordination faces, ligand atoms and connectors in 2D/3D, with per-group color and opacity.
[Polyhedra guide](https://v-ase.readthedocs.io/en/latest/polyhedra.html)

![IrO2 coordination polyhedra with independent colors and face opacity](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_polyhedra.gif)

## Style Atoms, Bonds, And Rendering

Control colors, radii and visibility by label or atom index.
[Appearance](https://v-ase.readthedocs.io/en/latest/appearance.html#per-atom-overrides)

![View-mode label and appearance editing on Cu5O4](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_cu5o4_view_appearance.gif)

Choose Standard, Metal, Rubber or flat 2D rendering.
[Materials and rendering](https://v-ase.readthedocs.io/en/latest/appearance.html#d-and-flat-2d-rendering)

![Standard Metal and Rubber atom materials](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_materials.png)

Set bond topology and appearance by pair or exact atom indices.
[Bond controls](https://v-ase.readthedocs.io/en/latest/bonds.html)

![Pairwise Cu O bonds in a Cu2O(111) film on Cu(111)](https://raw.githubusercontent.com/lgyEthan/v_ase/main/docs/assets/github/readme_bonds.png)

## Export And Save

[Images and video](https://v-ase.readthedocs.io/en/latest/render-images.html#image-output) ·
[Render Area](https://v-ase.readthedocs.io/en/latest/render-images.html#render-area) ·
[Blender / OBJ / Rhino](https://v-ase.readthedocs.io/en/latest/export-structures.html#d-scene-output) ·
[Projects and presets](https://v-ase.readthedocs.io/en/latest/save-projects.html#save-project)

## Python And Remote Systems

```python
from ase.build import molecule
from v_ase import view

view(molecule("H2O"))
```

[Python API](https://v-ase.readthedocs.io/en/latest/python-api.html) · [Jupyter](https://v-ase.readthedocs.io/en/latest/notebooks-remote.html#jupyter-auto-detection) ·
[SSH / remote files](https://v-ase.readthedocs.io/en/latest/notebooks-remote.html#one-command-remote-files)

## License And Citation

[AGPL-3.0-or-later](LICENSE) · [Three.js MIT license](v_ase/static/vendor/THREE_LICENSE) · [Cite v_ase](CITATION.cff)
