AtomEye atomistic configuration viewer

This module provides the AtomEyeViewer class, which is a high-level interface for interactive visualisation of Atoms objects using a modified version of the AtomEye atomistic configuration viewer.

Atoms and AtomsList objects can also be visualised with the qlab module.

For example, to create and visualise and 8-atom silicon bulk cell:

from quippy.structures import diamond, supercell
from atomeye import AtomEyeViewer

d = diamond(5.43, 14)
viewer = AtomEyeViewer(d)

A window will pop up containing the silicon unit cell, which you can manipulate with the mouse, by issuing commands in the the python console or with a variety of AtomEye keyboard shortcuts. To save an image in PNG format:

viewer.capture('si8.png')
_images/si8.png

Then, to change the display to a \(2 imes2 imes2\) supercell of bulk silicon, change the background colour to black, set the size and save an image you’d do the following:

at = supercell(d, 2, 2, 2)
viewer.show(at)

viewer.change_bgcolor((0, 0, 0))
viewer.resize(400,300)
viewer.capture('si2x2x2.png')
_images/si2x2x2.png

Module attributes:

atomeye.viewers

Dictionary mapping window_id to AtomEyeView instances. There is one entry for each currently open AtomEye view window.

atomeye.default_state

Dictionary of key/value pairs passed to AtomEyeView.update() when a new window is created. Change this dictionary to modfiy the properties of new windows. The initial value is as follows:

default_state = {
    'variables' : {'n->xtal_mode': 1,
                   'n->suppress_printout': 1,
                   'n->bond_mode': 1,
                   'n->atom_r_ratio': 0.5,
                   'n->small_cell_err_handler': 1,
                   'key->BackSpace': 'load_config_backward'
                   },
    'commands': ['xtal_origin_goto 0.5 0.5 0.5',
                 'toggle_parallel_projection'],
    'cutoff_lengths': []
}

Module contents for atomeye:

Classes

AtomEyeViewer([atoms, viewer_id, copy, ...]) View an atomic configuration or trajectory with AtomEye

Functions

view(atoms, **kwargs) Convenience wrapper to create/reuse a default AtomEyeViewer
redraw() Redraw current AtomEye window, keeping Atoms and settings the same.
run_command(command) Run a command in current AtomEye thread.
run_script(script) Run commands from the file script, in a blocking fashion.
close() Close the current viewer window.
setp(self, key, value) Run the AtomEye command “set key value”
save_script(filename) Save AtomEye viewer settings to a file.
toggle_coordination_coloring() Turn on or off colouring by coordination number (key “k”)
translate(axis, delta) Translate system along axis by an amount delta (key “Ctrl+left/right/up/down”)
shift_xtal(axis, delta) Shift crystal within periodic boundaries along axis by delta (key “Shift+left/right/up/down”).
rotate(axis, theta) Rotate around axis by angle theta.
advance(delta) Move the camera forward by delta.
shift_cutting_plane(delta) Shift the current cutting plane by an amount delta.
change_bgcolor(color) Change the viewer background colour to color, which should be a RGB tuple with three floats in range 0..1.
change_atom_r_ratio(delta) Change the size of the balls used to draw the atoms by delta.
change_bond_radius(delta) Change the radius of the cylinders used the draw bonds by delta.
change_view_angle_amplification(delta) Change the amplification of the view angle by delta.
toggle_parallel_projection() Toggle between parallel and perspective projections.
toggle_bond_mode() Turn on or off bonds.
toggle_small_cell_mode() Toggle between two different behaviours for when cell is smaller than r_cut/2: 1.
normal_coloring() Return to normal colouring of the atoms (key “o”).
aux_property_coloring(auxprop) Colour the currently viewed atoms according to auxprop.
central_symmetry_coloring() Colour atoms by centro-symmetry parameter.
change_aux_property_threshold(lower, upper) Change the lower and upper aux property thresholds.
reset_aux_property_thresholds() Reset aux property thresholds to automatic values.
toggle_aux_property_thresholds_saturation() Toggle between saturated colouring and invisibility for values outside aux prop thresholds.
toggle_aux_property_thresholds_rigid() Toggle between floating and rigid aux property thresholds when moving between frames
rcut_patch(sym1, sym2, value[, absolute]) Change the cutoff distance for sym1sym2 bonds by delta.
select_gear(gear) Change the AtomEye gear to gear
cutting_plane(n, d, s) Create a new cutting plane with index n, normal d, and fractional displacement s.
shift_cutting_plane_to_anchor(n) Move the cutting plane with index n to the anchor
delete_cutting_plane(n) Delete the cutting plane with index n
flip_cutting_plane(n) Flip the cutting plane with index n
capture(filename[, resolution]) Render the current view to image filename
change_wireframe_mode() Change the display mode for the unit cell box.
change_cutting_plane_wireframe_mode() Change the display mode for cutting planes
get_frame() Get index of frame currently being viewed
set_frame(frame) Set current frame index to frame
get_delta() Get frame increment rate
set_delta(delta) Set frame increment rate
first() Show the first frame (frame 0).
last() Show the last frame, i.e.
forward([delta]) Move forward by delta frames (default value is gcv().delta).
backward([delta]) Move backward by delta frames (default values is gcv().delta).
load_atom_color(filename) Load atom colours from a .clr file.
load_aux(filename) Load aux property values from a .aux file.
look_at_the_anchor() Equivalent to pressing the a key
observer_goto() Prompt for fractional position and move the observer there
xtal_origin_goto(s) Move the crystal origin to fractional coordinates s
find_atom(i) Set the anchor to the atom with index i.
resize(width, height) Resize the current window to width x height pixels.
change_aux_colormap(n) Select the n-th auxiliary property colourmap.
draw_arrows(property[, scale_factor, ...]) Draw arrows on each atom, based on a vector property
wait() Sleep until current AtomEye viewer has finished processing all queued events.
display() Display snapshot from current viewer in Jupyter notebook
class atomeye.AtomEyeViewer(atoms=None, viewer_id=None, copy=None, frame=0, delta=1, nowindow=False, echo=False, block=False, verbose=False, **showargs)[source]

View an atomic configuration or trajectory with AtomEye

Class to represent an AtomEye viewer window. Each viewer class communicates with one AtomEye thread.

There are wrapper methods for most of the AtomEye 3 commands. The names of these methods match the names of the correspondning commands, and the arguments follow the syntax given on the AtomEye 3 help page.

Additional keyword arguments are passed along to the show() method.

Import AtomEyeView attributes:

atoms

Atoms object or sequence being viewed. This will be set to None if this instance was created without an obj parameter, which means we’re viewing the A3 logo.

frame

Current frame, in range 1 to len(self.atoms).

delta

Frame increment rate when Delete and Insert are preseed. Equivalent to AtomEye n->glob_advance setting.

echo

If set to True, echo all AtomEye commands to stdout

block

If set to True, wait for all AtomEye command to finish executing before returning from function calls. Default is False.

verbose

If set to True (default), print frame paramters on each redraw(), and print information about each atom when it is right clicked.

Parameters:

atoms : quippy.atoms.Atoms or ase.atoms.Atoms object, or a list of objects.

Configuration or trajectory to view.

viewer_id : integer or None

If None, open a new viewer. Otherwise call the :meth:show() method in the existing viewer with this ID.

copy : integer or None

Viewer ID of another viewer from which to copy the viewpoint and other default settings.

frame : integer

Initial frame to show (should be in range 0..len(atoms)-1)

delta : integer

Increment/decrement rate for frames when [Insert] and [Delete] are pressed

nowindow : bool

If True, open AtomEye without a visible window. Useful for faster rendering of movies

echo : bool

If True, echo all commands to the screen. Useful mainly for debugging.

block : bool

If True, wait for commands to finish executing in AtomEye thread before returning (i.e. run asynchronously)

verbose : bool

If True, print information when changing frame and when an atom is clicked

Attributes

frame Get or set the current frame

Methods

advance(delta) Move the camera forward by delta.
aux_property_coloring(auxprop) Colour the atoms by the auxiliary property with name or index auxprop.
backward([delta]) Move backward by delta frames (default values is self.delta).
capture(filename[, resolution]) Render the current view to image filename
central_symmetry_coloring() Colour atoms by centro-symmetry parameter.
change_atom_r_ratio(delta) Change the size of the balls used to draw the atoms by delta.
change_aux_colormap(n) Select the n-th auxiliary property colourmap.
change_aux_property_threshold(lower, upper) Change the lower and upper aux property thresholds.
change_bgcolor(color) Change the viewer background colour to color, which should be a RGB tuple with three floats in range 0..1.
change_bond_radius(delta) Change the radius of the cylinders used the draw bonds by delta.
close() Close this viewer window.
cutting_plane(n, d, s) Create a new cutting plane with index n, normal d, and fractional displacement s.
display() Display snapshot from AtomEye session in IPython notebook
draw_arrows(property[, scale_factor, ...]) Draw arrows on each atom, based on a vector property
find_atom(i) Set the anchor to the atom with index i.
first() Show the first frame (frame 0).
forward([delta]) Move forward by delta frames (default value is self.delta).
gcat([update]) Get current atoms - return Atoms object currently being visualised.
get_size_angstrom([state]) Return (width, height) in Angstrom of currently projected view
get_size_pixels([state]) Return (width, height) in pixels of this viewer
get_visible() Return list of indices of atoms currently visible in this viewer.
key(key) Simulate pressing key on the keyboard.
last() Show the last frame, i.e.
load_atom_color(filename) Load atom colours from a .clr file.
load_aux(filename) Load aux property values from a .aux file.
load_script(filename) Load AtomEye viewer settings from a file using the AtomEye load_script command
normal_coloring() Return to normal colouring of the atoms (key “o”).
rcut_patch(sym1, sym2, value[, absolute]) Change the cutoff distance for sym1sym2 bonds by delta.
redraw() Redraw this AtomEye window, keeping Atoms and settings the same.
reset_aux_property_thresholds() Reset aux property thresholds to automatic values.
resize(width, height) Resize the current window to width x height pixels.
rotate(axis, theta) Rotate around axis by angle theta.
run_command(command) Run a command in this AtomEye thread.
run_script(script) Run commands from the file script, in a blocking fashion.
save(filename) Save AtomEye viewer settings to a file.
scat(atoms[, frame]) Set current atoms (and optionally also current frame)
setp(key, value) Run the AtomEye command “set key value”.
shift_cutting_plane(delta) Shift the current cutting plane by an amount delta.
shift_xtal(axis, delta) Shift crystal within periodic boundaries along axis by delta (key “Shift+left/right/up/down”).
show([atoms, property, frame, arrows]) Update what is shown in this AtomEye viewer window.
start([copy, nowindow]) Start the AtomEye thread, wait for it to load and apply default commands.
toggle_aux_property_thresholds_rigid() Toggle between floating and rigid aux property thresholds when moving between frames
toggle_aux_property_thresholds_saturation() Toggle between saturated colouring and invisibility for values outside aux prop thresholds.
toggle_bond_mode() Turn on or off bonds.
toggle_coordination_coloring() Turn on or off colouring by coordination number (key “k”)
toggle_parallel_projection() Toggle between parallel and perspective projections.
toggle_small_cell_mode() Toggle between two different behaviours for when cell is smaller than r_cut/2: 1.
translate(axis, delta) Translate system along axis by an amount delta (key “Ctrl+left/right/up/down”)
update(state) Update settings from the dictionary state.
wait() Sleep until this AtomEye viewer has finished processing all queued events.
xtal_origin_goto(s) Move the crystal origin to fractional coordinates s
advance(delta)[source]

Move the camera forward by delta.

aux_property_coloring(auxprop)[source]

Colour the atoms by the auxiliary property with name or index auxprop.

backward(delta=None)[source]

Move backward by delta frames (default values is self.delta).

capture(filename, resolution=None)[source]

Render the current view to image filename

Format is determined from file extension: .png, .jpeg, or .eps.

central_symmetry_coloring()[source]

Colour atoms by centro-symmetry parameter.

change_atom_r_ratio(delta)[source]

Change the size of the balls used to draw the atoms by delta.

change_aux_colormap(n)[source]

Select the n-th auxiliary property colourmap.

change_aux_property_threshold(lower, upper)[source]

Change the lower and upper aux property thresholds.

change_bgcolor(color)[source]

Change the viewer background colour to color, which should be a RGB tuple with three floats in range 0..1.

change_bond_radius(delta)[source]

Change the radius of the cylinders used the draw bonds by delta.

close()[source]

Close this viewer window.

cutting_plane(n, d, s)[source]

Create a new cutting plane with index n, normal d, and fractional displacement s.

display()[source]

Display snapshot from AtomEye session in IPython notebook

draw_arrows(property, scale_factor=0.0, head_height=0.1, head_width=0.05, up=(0.0, 1.0, 0.0))[source]

Draw arrows on each atom, based on a vector property

Parameters:

property : string

Name of the array to use for arrow vectors. Use None to turn off previous arrows.

scale_factor : float

Override length of arrows. 1 unit = 1 Angstrom; default value of 0.0 means autoscale.

head_height : float

Specify height of arrow heads in Angstrom.

head_width : float

up : 3-vector (tuple, list or array)

Specify the plane in which the arrow heads are drawn. Arrows are drawn in the plane which is common to their direction and this vector. Default is [0.,1.,0.].

find_atom(i)[source]

Set the anchor to the atom with index i.

first()[source]

Show the first frame (frame 0).

forward(delta=None)[source]

Move forward by delta frames (default value is self.delta).

gcat(update=False)[source]

Get current atoms - return Atoms object currently being visualised.

If update=False (the default), we return what is currently being visualised, even if this is not in sync with self.atoms[self.frame].

get_size_angstrom(state=None)[source]

Return (width, height) in Angstrom of currently projected view

Assumes object lies in plane z=0

get_size_pixels(state=None)[source]

Return (width, height) in pixels of this viewer

get_visible()[source]

Return list of indices of atoms currently visible in this viewer.

key(key)[source]

Simulate pressing key on the keyboard.

The syntax for keystrokes is described on the AtomEye 3 commands help page

last()[source]

Show the last frame, i.e. len(self.atoms)-1

load_atom_color(filename)[source]

Load atom colours from a .clr file.

load_aux(filename)[source]

Load aux property values from a .aux file.

load_script(filename)[source]

Load AtomEye viewer settings from a file using the AtomEye load_script command

run_script() is more robust as the script is run line by line in a blocking sense.

normal_coloring()[source]

Return to normal colouring of the atoms (key “o”).

rcut_patch(sym1, sym2, value, absolute=False)[source]

Change the cutoff distance for sym1sym2 bonds by delta.

e.g. to increase cutoff for Si-Si bonds by 0.5 A use:

viewer.rcut_patch('Si', 'Si', 0.5)

With absolute set to True, value is used to set the absolute cutoff distance for sym1sym2 bonds, e.g.:

viewer.rcut_patch('Si', 'Si', 2.50, True)
redraw()[source]

Redraw this AtomEye window, keeping Atoms and settings the same.

reset_aux_property_thresholds()[source]

Reset aux property thresholds to automatic values.

resize(width, height)[source]

Resize the current window to width x height pixels.

rotate(axis, theta)[source]

Rotate around axis by angle theta.

run_command(command)[source]

Run a command in this AtomEye thread.

The command is queued for later execution, unless block is True.

This functionality is also available by calling an instance directly, i.e. the following commands are equivalent:

viewer.run_command('toggle_coordination_coloring')
viewer('toggle_coordination_coloring')
Parameters:

command : string

The command to pass to AtomEye

run_script(script)[source]

Run commands from the file script, in a blocking fashion.

save(filename)[source]

Save AtomEye viewer settings to a file.

scat(atoms, frame=None)[source]

Set current atoms (and optionally also current frame)

setp(key, value)[source]

Run the AtomEye command “set key value”.

shift_cutting_plane(delta)[source]

Shift the current cutting plane by an amount delta.

shift_xtal(axis, delta)[source]

Shift crystal within periodic boundaries along axis by delta (key “Shift+left/right/up/down”).

show(atoms=None, property=None, frame=None, arrows=None)[source]

Update what is shown in this AtomEye viewer window.

When called with no arguments, show() is equivalent to redraw().

Parameters:

atoms : class:quippy.atoms.Atoms or `ase.atoms.Atoms

instance, or a list of instances

property : name of the quippy :~quippy.atoms.properties

entry or ASE ase.atoms.arrays entry used to colour the atoms (e.g. "charge")

frame : Zero-based index of the frame to show

(applies only when atoms is a list of Atoms objects)

arrows : is the name of a vector property to use to draw arrows

on the atoms (e.g. "force")

start(copy=None, nowindow=False)[source]

Start the AtomEye thread, wait for it to load and apply default commands.

Parameters:

copy : integer

Viewer ID of another AtomEye window from which to copy settings

nowindow : bool

If True, create an AtomEye thread without a visible window. Useful for rendering movies.

toggle_aux_property_thresholds_rigid()[source]

Toggle between floating and rigid aux property thresholds when moving between frames

toggle_aux_property_thresholds_saturation()[source]

Toggle between saturated colouring and invisibility for values outside aux prop thresholds.

toggle_bond_mode()[source]

Turn on or off bonds.

toggle_coordination_coloring()[source]

Turn on or off colouring by coordination number (key “k”)

toggle_parallel_projection()[source]

Toggle between parallel and perspective projections.

toggle_small_cell_mode()[source]
Toggle between two different behaviours for when cell is smaller than r_cut/2:
  1. clip cell - some neigbours may be lost (default)
  2. replicate cell along narrow directions
translate(axis, delta)[source]

Translate system along axis by an amount delta (key “Ctrl+left/right/up/down”)

update(state)[source]

Update settings from the dictionary state.

Runs the AtomEye command set key value for each pair. Valid settings are listed on the AtomEye 3 settings help page

wait()[source]

Sleep until this AtomEye viewer has finished processing all queued events.

xtal_origin_goto(s)[source]

Move the crystal origin to fractional coordinates s

For example, use s=[0.5, 0.5, 0.5] to shift by half the cell along the \(\mathbf{a}\), \(\mathbf{b}\) and \(\mathbf{c}\) lattice vectors.

frame

Get or set the current frame

atomeye.view(atoms, **kwargs)[source]

Convenience wrapper to create/reuse a default AtomEyeViewer

atomeye.redraw()[source]

Redraw current AtomEye window, keeping Atoms and settings the same.

atomeye.run_command(command)[source]

Run a command in current AtomEye thread.

The command is queued for later execution, unless block is True.

Parameters:

command : string

The command to pass to AtomEye

atomeye.run_script(script)[source]

Run commands from the file script, in a blocking fashion.

atomeye.close()[source]

Close the current viewer window.

atomeye.setp(self, key, value)[source]

Run the AtomEye command “set key value”

atomeye.save_script(filename)[source]

Save AtomEye viewer settings to a file.

atomeye.toggle_coordination_coloring()[source]

Turn on or off colouring by coordination number (key “k”)

atomeye.translate(axis, delta)[source]

Translate system along axis by an amount delta (key “Ctrl+left/right/up/down”)

atomeye.shift_xtal(axis, delta)[source]

Shift crystal within periodic boundaries along axis by delta (key “Shift+left/right/up/down”).

atomeye.rotate(axis, theta)[source]

Rotate around axis by angle theta.

atomeye.advance(delta)[source]

Move the camera forward by delta.

atomeye.shift_cutting_plane(delta)[source]

Shift the current cutting plane by an amount delta.

atomeye.change_bgcolor(color)[source]

Change the viewer background colour to color, which should be a RGB tuple with three floats in range 0..1.

atomeye.change_atom_r_ratio(delta)[source]

Change the size of the balls used to draw the atoms by delta.

atomeye.change_bond_radius(delta)[source]

Change the radius of the cylinders used the draw bonds by delta.

atomeye.change_view_angle_amplification(delta)[source]

Change the amplification of the view angle by delta.

atomeye.toggle_parallel_projection()[source]

Toggle between parallel and perspective projections.

atomeye.toggle_bond_mode()[source]

Turn on or off bonds.

atomeye.toggle_small_cell_mode()[source]
Toggle between two different behaviours for when cell is smaller than r_cut/2:
  1. clip cell - some neigbours may be lost (default)
  2. replicate cell along narrow directions
atomeye.normal_coloring()[source]

Return to normal colouring of the atoms (key “o”).

atomeye.aux_property_coloring(auxprop)[source]

Colour the currently viewed atoms according to auxprop.

Overloaded to allow See Custom Atom Colouring for more details and examples.

Parameters:

auxprop : str, array_like, int or list

Values to use to colour the atoms. Should be either the name of a scalar field entry in properties (or equivalently, arrays) such as "charge", a float, int or bool array of shape (len(gcat()),), or an atom index or list of atom indices to highlight particular atoms.

atomeye.central_symmetry_coloring()[source]

Colour atoms by centro-symmetry parameter.

atomeye.change_aux_property_threshold(lower, upper)[source]

Change the lower and upper aux property thresholds.

atomeye.reset_aux_property_thresholds()[source]

Reset aux property thresholds to automatic values.

atomeye.toggle_aux_property_thresholds_saturation()[source]

Toggle between saturated colouring and invisibility for values outside aux prop thresholds.

atomeye.toggle_aux_property_thresholds_rigid()[source]

Toggle between floating and rigid aux property thresholds when moving between frames

atomeye.rcut_patch(sym1, sym2, value, absolute=False)[source]

Change the cutoff distance for sym1sym2 bonds by delta.

e.g. to increase cutoff for Si-Si bonds by 0.5 A use:

viewer.rcut_patch('Si', 'Si', 0.5)

With absolute set to True, value is used to set the absolute cutoff distance for sym1sym2 bonds, e.g.:

viewer.rcut_patch('Si', 'Si', 2.50, True)
atomeye.select_gear(gear)[source]

Change the AtomEye gear to gear

Equivalent to pressing the one of the numeric keys 0..9

atomeye.cutting_plane(n, d, s)[source]

Create a new cutting plane with index n, normal d, and fractional displacement s.

atomeye.shift_cutting_plane_to_anchor(n)[source]

Move the cutting plane with index n to the anchor

atomeye.delete_cutting_plane(n)[source]

Delete the cutting plane with index n

atomeye.flip_cutting_plane(n)[source]

Flip the cutting plane with index n

atomeye.capture(filename, resolution=None)[source]

Render the current view to image filename

Format is determined from file extension: .png, .jpeg, or .eps.

atomeye.change_wireframe_mode()[source]

Change the display mode for the unit cell box.

Equivalent to pressing the i key.

atomeye.change_cutting_plane_wireframe_mode()[source]

Change the display mode for cutting planes

atomeye.get_frame()[source]

Get index of frame currently being viewed

atomeye.set_frame(frame)[source]

Set current frame index to frame

atomeye.get_delta()[source]

Get frame increment rate

atomeye.set_delta(delta)[source]

Set frame increment rate

atomeye.first()[source]

Show the first frame (frame 0).

atomeye.last()[source]

Show the last frame, i.e. len(gcv())-1

atomeye.forward(delta=None)[source]

Move forward by delta frames (default value is gcv().delta).

atomeye.backward(delta=None)[source]

Move backward by delta frames (default values is gcv().delta).

atomeye.load_atom_color(filename)[source]

Load atom colours from a .clr file.

atomeye.load_aux(filename)[source]

Load aux property values from a .aux file.

atomeye.look_at_the_anchor()[source]

Equivalent to pressing the a key

atomeye.observer_goto()[source]

Prompt for fractional position and move the observer there

Equivalent to pressing the g key.

atomeye.xtal_origin_goto(s)[source]

Move the crystal origin to fractional coordinates s

For example, use s=[0.5, 0.5, 0.5] to shift by half the cell along the \(\mathbf{a}\), \(\mathbf{b}\) and \(\mathbf{c}\) lattice vectors.

atomeye.find_atom(i)[source]

Set the anchor to the atom with index i.

atomeye.resize(width, height)[source]

Resize the current window to width x height pixels.

atomeye.change_aux_colormap(n)[source]

Select the n-th auxiliary property colourmap.

atomeye.draw_arrows(property, scale_factor=0.0, head_height=0.1, head_width=0.05, up=(0.0, 1.0, 0.0))[source]

Draw arrows on each atom, based on a vector property

Parameters:

property : string

Name of the array to use for arrow vectors. Use None to turn off previous arrows.

scale_factor : float

Override length of arrows. 1 unit = 1 Angstrom; default value of 0.0 means autoscale.

head_height : float

Specify height of arrow heads in Angstrom.

head_width : float

up : 3-vector (tuple, list or array)

Specify the plane in which the arrow heads are drawn. Arrows are drawn in the plane which is common to their direction and this vector. Default is [0.,1.,0.].

atomeye.wait()[source]

Sleep until current AtomEye viewer has finished processing all queued events.

atomeye.display()[source]

Display snapshot from current viewer in Jupyter notebook