aseview 0.0.4

A molecular viewer for ASE (Atomic Simulation Environment) data

aseview

Molecular structure viewer for ASE (Atomic Simulation Environment).

 · 

Installation

pip install aseview

For development:

git clone https://github.com/kangmg/aseview.git
cd aseview
pip install -e .

CLI Usage

# Basic usage
aseview molecule.xyz

# View trajectory (all frames)
aseview trajectory.xyz -i :

# View specific frames
aseview trajectory.xyz -i 0:10    # frames 0-9
aseview trajectory.xyz -i -1      # last frame
aseview trajectory.xyz -i ::2     # every 2nd frame

# Specify file format
aseview POSCAR -f vasp

# Custom port
aseview molecule.xyz -p 9000

# Overlay multiple structures
aseview reactant.xyz product.xyz

# Overlay with colormap
aseview trajectory.xyz -v overlay --cmap viridis

# Normal mode visualization with ORCA Hessian
aseview molecule.xyz --hess orca.hess

# Save as HTML file
aseview molecule.xyz -o output.html

# Kill existing server on port
aseview molecule.xyz -k

# Help
aseview -h

SSH Port Forwarding

When running on a remote server (e.g., HPC cluster, Docker container):

# 1. On remote server
aseview molecule.xyz -p 8080

# 2. On local machine (separate terminal)
ssh -L 8080:localhost:8080 user@remote-server

# 3. Open in local browser
# http://localhost:8080

For Docker with custom SSH port:

# Connect with port forwarding
ssh user@localhost -p 10011 -L 8080:localhost:8080

# Then run aseview inside container
aseview molecule.xyz -p 8080

Jupyter Notebook

Quick Start

from ase.io import read
from aseview import MolecularViewer

atoms = read('molecule.xyz')
viewer = MolecularViewer(atoms)
viewer.show()

With Trajectory

from ase.io import read
from aseview import MolecularViewer

# Read all frames
trajectory = read('trajectory.xyz', index=':')
viewer = MolecularViewer(trajectory)
viewer.show()

Overlay Multiple Structures

from ase.io import read
from aseview import OverlayViewer

reactant = read('reactant.xyz')
product = read('product.xyz')
viewer = OverlayViewer([reactant, product])
viewer.show()

Overlay with Colormap

from ase.io import read
from aseview import OverlayViewer

trajectory = read('optimization.xyz', index=':')
viewer = OverlayViewer(
    trajectory,
    colorBy='Colormap',
    colormap='viridis'  # viridis, plasma, coolwarm, jet, rainbow, grayscale
)
viewer.show()

Align Molecules (RMSD Minimization)

from ase.io import read
from aseview import OverlayViewer

structures = [read(f'conf{i}.xyz') for i in range(5)]
viewer = OverlayViewer(
    structures,
    alignMolecules=True,  # Kabsch rotation + Hungarian reordering
    colorBy='Molecule'
)
viewer.show()

Normal Mode Visualization

From ASE Vibrations

from ase import Atoms
from ase.calculators.emt import EMT
from ase.optimize import BFGS
from ase.vibrations import Vibrations
from aseview import NormalViewer

# Create or load molecule
atoms = Atoms('H2O', positions=[[0, 0, 0], [0.96, 0, 0], [-0.24, 0.93, 0]])
atoms.calc = EMT()

# Optimize structure
opt = BFGS(atoms)
opt.run(fmax=0.01)

# Calculate vibrations
vib = Vibrations(atoms, name='vib')
vib.run()
vib.summary()

# Visualize normal modes
viewer = NormalViewer(atoms, vibrations=vib)
viewer.show()

From ORCA Hessian File

from ase.io import read
from aseview import NormalViewer

atoms = read('molecule.xyz')
viewer = NormalViewer.from_orca(atoms, 'orca.hess')
viewer.show()

Features:

• Mode selector dropdown with frequencies
• Sinusoidal animation of atomic displacements
• Amplitude slider to control displacement magnitude
• Show Vectors toggle to display mode displacement arrows
• Imaginary frequencies (transition states) shown in red

Using view_molecule Helper

from aseview.jupyter import view_molecule
from ase.io import read

atoms = read('molecule.xyz')
view_molecule(atoms, viewer_type='molecular', height=600)

Custom Settings

from aseview import MolecularViewer

viewer = MolecularViewer(
    atoms,
    style='neon',           # default, cartoon, neon, glossy, metallic, rowan, grey
    bondThreshold=1.2,      # bond detection scale factor
    atomSize=0.5,
    showCell=False,
    backgroundColor='#000000',
    showPolyhedron=True,    # coordination polyhedra (solid-state, CN >= 4)
    polyhedronOpacity=0.25,
    showRings=True,         # ring face highlighting (molecules, 4-8 atom rings)
    ringOpacity=0.35,
)
viewer.show(width='100%', height=800)

Save to HTML

viewer.save_html('output.html')

Fragment Selector (Interactive Atom Selection)

from ase.build import molecule
from aseview import FragSelector

atoms = molecule('CH3OH')  # or read('molecule.xyz')
FragSelector(atoms).show()

The Fragment Selector shows a synchronized 2D + 3D view for picking atom subsets. Selected atoms are highlighted in yellow in both panels.

Interaction modes (keyboard shortcuts: N / C / R / L):

Mode	How to activate	2D action
Navigate	N key	drag to pan, scroll to zoom
Click	C key	click individual atoms to toggle
Rect	R key	drag a rectangle to select atoms
Lasso	L key	draw a freeform region to select atoms

Hold Shift while releasing to add to the existing selection instead of replacing it.

# Save selected indices after interactive picking:
viewer = FragSelector(atoms, bondThreshold=1.2, style='cartoon')
viewer.save_html('selector.html')

# CLI usage (opens in browser):
# aseview molecule.xyz -v frag

Viewer Types

Viewer	Description
MolecularViewer	Single structure or trajectory animation
NormalViewer	Normal mode vibration visualization
OverlayViewer	Compare multiple structures overlaid
FragSelector	Interactive 2D+3D atom selection with rect/lasso

JavaScript Module

Use aseview in any web page without Python:

<div id="viewer" style="width:100%; height:500px;"></div>

<script src="https://raw.githack.com/kangmg/aseview/main/aseview/static/js/aseview.js"></script>
<script>
    const viewer = new ASEView.MolecularViewer('#viewer');
    viewer.setData({
        symbols: ['O', 'H', 'H'],
        positions: [
            [0.0, 0.0, 0.117],
            [0.0, 0.757, -0.469],
            [0.0, -0.757, -0.469]
        ]
    });
</script>

See the JavaScript Module documentation for full API reference.

Supported Formats

All formats supported by ASE: xyz, cif, pdb, POSCAR, extxyz, etc.

License

MIT