This page was generated from docs/source/user_guide/tutorial_intro.ipynb.

Interactive online version:

ase-notebook by example

The classes of ase-notebook are:

• ViewConfig, which validates and stores the initialisation configuration.

• AseView, which uses a ViewConfig to create a visualisation, via one of the backends.

from ase_notebook import AseView, ViewConfig, get_example_atoms

An AseView can be initialised with a ViewConfig, or create the ViewConfig via keyword arguments.

config = ViewConfig()
ase_view = AseView(config)

ase_view = AseView(
    rotations="45x,45y,45z",
    atom_font_size=16,
    axes_length=30,
    canvas_size=(400, 400),
    zoom=1.2,
    show_bonds=True
)
ase_view.config.uc_dash_pattern=(.6,.4)
ase_view.add_miller_plane(
    1, 0, 0, color="green")
ase_view.config

ViewConfig(rotations='45x,45y,45z', element_colors='ase', element_radii='ase', radii_scale=0.89, atom_show_label=True, atom_label_by='element', atom_label_array='', atom_font_size=16, atom_font_color='black', atom_stroke_width=1.0, atom_stroke_opacity=0.95, atom_color_by='element', atom_color_array='', atom_colormap='jet', atom_colormap_range=(None, None), atom_lighten_by_depth=0.0, atom_opacity=0.95, force_vector_scale=1.0, velocity_vector_scale=1.0, ghost_stroke_width=0.0, ghost_lighten=0.0, ghost_opacity=0.4, ghost_stroke_opacity=0.4, ghost_show_label=False, ghost_cross_out=False, show_unit_cell=True, show_uc_repeats=False, uc_dash_pattern=(0.6, 0.4), uc_color='black', show_bonds=True, bond_radii_scale=1.5, bond_array_name=None, bond_pairs_filter=None, bond_opacity=0.8, bond_color_by='atoms', bond_colormap='jet', bond_colormap_range=(None, None), show_miller_planes=True, miller_planes=({'h': 1, 'k': 0, 'l': 0, 'fill_color': 'green', 'stroke_color': 'green', 'stroke_width': 1, 'fill_opacity': 0.5, 'stroke_opacity': 0.9},), miller_as_lines=False, show_axes=True, axes_uc=False, axes_length=30, axes_font_size=14, axes_line_color='black', axes_offset=(20, 20), canvas_size=(400, 400), canvas_color_foreground='#000000', canvas_color_background='#ffffff', canvas_background_opacity=0.0, canvas_crop=None, zoom=1.2, camera_fov=10.0, gui_swap_mouse=False)

atoms = get_example_atoms()
atoms

Atoms(symbols='Fe4S8', pbc=False, cell=[[5.38932639, 0.0, 3.30001065653693e-16], [-3.30001065653693e-16, 5.38932639, 3.30001065653693e-16], [0.0, 0.0, 5.38932639]])

ase.Atoms or pymatgen.Structures can be parsed to one of the AseView visualisation methods:

• make_gui() opens a (blocking) GUI window, similar to the ase.visualize.view() default.

• launch_gui_subprocess() opens the GUI in a subprocess, allowing multiple windows to be opened at once.

• make_svg() creates an svgwrite.drawing.Drawing, which will automatically be displayed in the notebook.

• make_render() creates a RenderContainer, which contains a pythreejs Renderer and ipywidget controls, that will automatically be displayed in the notebook.

threejs (3D)

ase_view.config.canvas_color_background = "blue"
ase_view.config.canvas_background_opacity = 0.2
gui = ase_view.make_render(
    atoms, center_in_uc=True)
gui

Note

The world axes are currently synced to the main scene viathe python kernel, so will only move when it is running. Also double-clicking an atom will display information about it.

Important

To use make_render, the package must have been installed via Conda or with the threejs extra: pip install ase-notebook[threejs].

Any component of the above GUI can be accessed and displayed separately, as an additional view of the widget.

gui.element_renderer

To create additional controls, any element of the scene can be linked to an ipywidget.

from ipywidgets import FloatSlider, jslink
slider = FloatSlider(
    min=0.1, max=10
)
jslink((gui.element_renderer.camera, 'zoom'),
       (slider, 'value'))
slider

If make_render is called with reuse_objects=True, then a single atom texture is used for all atoms with the same visual properties (color, opacity, …). This widget, for example, will change the color of all Fe atoms above.

from ipywidgets import ColorPicker, jslink
material = gui.atom_arrays[0]["material_body"]
picker = ColorPicker()
jslink((material, 'color'), (picker, 'value'))
picker

Pythreejs currently can be slow to load, if the scene contains 1000’s of elements (see this issue). To improve this, if use_atom_arrays=True then atoms with the same radius and visual properties, will be concatenated into a single element.

Note

The atom information picker will not work with this option.

ase_view.config.atom_show_label = False
ase_view.make_render(
    atoms, center_in_uc=True,
    repeat_uc=(4,4,4), use_atom_arrays=True,
    create_gui=False
)

SVG (2D)

ase_view.config.atom_show_label = True
ase_view.config.canvas_background_opacity = 0.0
svg = ase_view.make_svg(atoms, center_in_uc=True)
svg

Code Cell Output

To aide with depth perception, the atom_lighten_by_depth option will lighten atom colors, based on their relative distance along the z-direction.

ase_view.config.atom_lighten_by_depth = 0.7
ase_view.make_svg(atoms, center_in_uc=True)

Code Cell Output

concatenate_svgs() can also be used to create an of multiple scenes.

Important

To use concatenate_svgs, the package must have been installed via Conda or with the svgconcat extra: pip install ase-notebook[svgconcat].

from ase_notebook import concatenate_svgs

svgs = []
for rot in ["45x,45y,45z", "0x", "90x"]:
    ase_view.config.rotations = rot
    svgs.append(
        ase_view.make_svg(atoms, center_in_uc=True)
    )
concatenate_svgs(
    svgs, max_columns=2, scale=0.5, label=True
)

Code Cell Output

Finally, if you wish to convert the SVG to a PDF:

from ase_notebook.backend.svg import svg_to_pdf
# pdf = svg_to_pdf(svg, "save_file.pdf")