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>
Python API
ZnDraw supports multiple clients connecting to the same visualization. Each visualization session is identified by a room name visible in the URL.
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.
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 zndraw import Extension
from molify import smiles2atoms
class AddMolecule(Extension):
smiles: str
def run(self, vis, **kwargs) -> None:
vis.append(smiles2atoms(self.smiles))
vis.step = len(vis) - 1
vis.register(AddMolecule, public=True)
vis.wait()
Extensions can be registered as public (available to all clients) or private (only to the registering client).
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.
Metadata
Release files for zndraw 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| zndraw-0.6.0.tar.gz | 24.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| zndraw-0.6.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 35.5 MB
Release files / zndraw-0.6.0.tar.gz
| Download URL | zndraw-0.6.0.tar.gz |
|---|---|
| Size | 24.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8dc8b3efe3f33ab3442810c9300dcfe1e2b864923d90fb83548f8133d1c01382
|
|
BLAKE2b-256 checksum How to use checksums |
1280cad6fd7b905ebc560dfc1e0e34af1cfb51d953d2e07e8f59a32a3150db7e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 16, 2026.
Transparency logRelease files / zndraw-0.6.0-py3-none-any.whl
| Download URL | zndraw-0.6.0-py3-none-any.whl |
|---|---|
| Size | 11.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
acd9f9b683cd1e0b514b3d2b82142c5cd3b4aa253c5c1e3e26cc09326c1f596f
|
|
BLAKE2b-256 checksum How to use checksums |
c526f80dbbe689936cea046b0ae1e4d200923b8bdfabbfb247325c03497188b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 16, 2026.
Transparency log
