zndraw 0.7.0a8

ZnDraw - Interactive visualization for atomistic simulations

ZnDraw

A Python-first visualization and editing tool for atomic structures with real-time collaboration.

Installation

You can install zndraw into your Python environment via pip:

pip install zndraw

or set it up as uv tool to run anywhere:

uvx zndraw <file>

Quick Start

Visualize your trajectories with a single command:

zndraw <file>

[!NOTE] ZnDraw's webapp-based approach allows you to use port forwarding to work with trajectories on remote systems.

Python API

ZnDraw supports multiple clients connecting to the same visualization. Each visualization session is identified by a room name visible in the URL.

[!TIP] Server settings can be configured via environment variables (ZNDRAW_SERVER_PORT, ZNDRAW_SERVER_HOST, etc.) or in your pyproject.toml:

[tool.zndraw.server]
port = 8000
storage = "/data/frames.lmdb"

from zndraw import ZnDraw

vis = ZnDraw(url="http://localhost:1234", room="my-room")

Authentication

For protected deployments, provide credentials:

vis = ZnDraw(
    url="http://localhost:1234",
    room="my-room",
    user="username",
    password="password"
)

If no credentials are provided, the server assigns a guest user.

Working with Frames

The vis object behaves like a Python list of ase.Atoms objects. Changes are synchronized in real-time across all connected clients.

from ase.collections import s22

# Add structures
vis.extend(list(s22))

# Access current frame
atoms = vis[vis.step]

# Iterate over frames
for atoms in vis:
    print(atoms)

# Slice operations
subset = vis[10:20]

Scene Properties

Control various aspects of the visualization:

vis.selection   # Currently selected atoms
vis.step        # Current frame index
vis.figures     # Plotly figures
vis.bookmarks   # Saved frame annotations
vis.geometries  # 3D geometry overlays (dict-like)
vis.sessions    # Session configuration

Geometries

Add 3D geometry overlays to your visualization:

from zndraw.geometries import Box, Sphere, Arrow, Camera, Curve

vis.geometries["box"] = Box(position=(0, 1, 2))

Available geometry types: Sphere, Arrow, Bond, Curve, Cell, Floor, Box, Plane, Shape, Camera, Isosurface.

Isosurface

Visualize volumetric data (e.g. molecular orbitals) as 3D isosurfaces:

from zndraw.geometries import Isosurface

# atoms.info["orbital_homo"] must contain:
# {"grid": np.ndarray (Nx,Ny,Nz), "origin": np.ndarray (3,), "cell": np.ndarray (3,3)}
vis.geometries["homo"] = Isosurface(cube_key="info.orbital_homo", isovalue=0.02)

Analysis

ZnDraw integrates with Plotly for interactive data visualization. It automatically detects available properties and provides selection menus.

Extensions

Create custom tools accessible via the ZnDraw UI:

from molify import smiles2atoms
from zndraw import ZnDraw, Extension, Category

class AddMolecule(Extension):
    category = Category.MODIFIER
    smiles: str

    def run(self, vis, **kwargs) -> None:
        vis.append(smiles2atoms(self.smiles))
        vis.step = len(vis) - 1

vis = ZnDraw()
vis.register_job(AddMolecule)  # room-scoped (default)
vis.wait()

Extensions can be registered as room-scoped (default, visible only in the current room) or global (vis.register_job(cls, room="@global"), admin-only, visible in all rooms).

Pass heavy, pre-loaded objects (e.g. ML models) via run_kwargs — they stay in worker memory and are forwarded to run() on every task:

model = torch.load("model.pt")
vis.register_job(Predict, run_kwargs={"model": model})

Register filesystem providers so users can load files from the UI:

import fsspec
vis.register_fs(fsspec.filesystem("file"), name="local")

Hosted Version

A hosted version is available at https://zndraw.icp.uni-stuttgart.de

zndraw <file> --url https://zndraw.icp.uni-stuttgart.de

Self-Hosting

ZnDraw can be deployed using Docker:

See the docker/ directory for complete deployment configurations:

• Standalone - Simple single-instance deployment for personal use or small teams
• Production - Horizontal scaling with nginx load balancer for high load

References

If you use ZnDraw in your research, please cite:

@article{elijosius2025zero,
  title = {Zero-shot molecular generation via similarity kernels},
  author = {Elijo{\v s}ius, Rokas and Zills, Fabian and Batatia, Ilyes and Norwood, Sam Walton and Kov{\'a}cs, D{\'a}vid P{\'e}ter and Holm, Christian and Cs{\'a}nyi, G{\'a}bor},
  journal = {Nature Communications},
  volume = {16},
  pages = {5479},
  year = {2025},
  doi = {10.1038/s41467-025-60963-3},
  url = {https://doi.org/10.1038/s41467-025-60963-3},
}

Acknowledgements

The creation of ZnDraw was supported by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) in the framework of the priority program SPP 2363, "Utilization and Development of Machine Learning for Molecular Applications - Molecular Machine Learning" Project No. 497249646. Further funding through the DFG under Germany's Excellence Strategy - EXC 2075 - 390740016 and the Stuttgart Center for Simulation Science (SimTech) was provided.