[](https://github.com/zincware)
[](https://badge.fury.io/py/zndraw)
[](https://arxiv.org/abs/2402.08708)
[](https://codecov.io/gh/zincware/ZnDraw)
# ZnDraw
Welcome to ZnDraw, a powerful tool for visualizing and interacting with your trajectories.
## Installation
It is recommended to install ZnDraw from PyPi via:
```bash
pip install zndraw
```
## Quick Start
Visualize your trajectories with a single command:
```bash
zndraw <file>
```
> [!NOTE]
> ZnDraw's webapp-based approach allows you to use port forwarding to work with trajectories on remote systems.
## Multi-User and Multi-Client Support
ZnDraw supports multiple users and clients. Connect one or more Python clients to your ZnDraw instance:
1. Click on `Python access` in the ZnDraw UI.
2. Connect using the following code:
```python
from zndraw import ZnDraw
vis = ZnDraw(url="http://localhost:1234", token="<your-token>")
```
The `vis` object provides direct access to your visualized scene. It inherits from `abc.MutableSequence`, so any changes you make are reflected for all connected clients.
```python
from ase.collections import s22
vis.extend(list(s22))
```
## Additional Features
You can modify various aspects of the visualization:
- `vis.camera`
- `vis.points`
- `vis.selection`
- `vis.step`
- `vis.figures`
- `vis.bookmarks`
- `vis.geometries`
For example, to add a geometry:
```python
from zndraw import Box
vis.geometries = [Box(position=[0, 1, 2])]
```
## Analyzing Data
ZnDraw enables you to analyze your data and generate plots using [Plotly](https://plotly.com/). It automatically detects available properties and offers a convenient drop-down menu for selection.
ZnDraw will look for the `step` and `atom` index in the [customdata](https://plotly.com/python/reference/scatter/#scatter-customdata)`[0]` and `[1]` respectively to highlight the steps and atoms.
## Writing Extensions
Make your tools accessible via the ZnDraw UI by writing an extension:
```python
from zndraw import Extension
class AddMolecule(Extension):
name: str
def run(self, vis, **kwargs) -> None:
structures = kwargs["structures"]
vis.append(structures[self.name])
vis.step = len(vis) - 1
vis.register(AddMolecule, run_kwargs={"structures": s22}, public=True)
vis.socket.wait() # This can be ignored when using Jupyter
```
The `AddMolecule` extension will appear for all `tokens` and can be used by any client.
# Hosted Version
A hosted version of ZnDraw is available at https://zndraw.icp.uni-stuttgart.de . To upload data, use:
```bash
zndraw <file> --url https://zndraw.icp.uni-stuttgart.de
```
## Self-Hosting
To host your own version of ZnDraw, use the following `docker-compose.yaml` setup:
```yaml
version: "3.9"
services:
zndraw:
image: pythonf/zndraw:latest
command: --no-standalone /src/file.xyz
volumes:
- /path/to/files:/src
restart: unless-stopped
ports:
- 5003:5003
depends_on:
- redis
- worker
environment:
- FLASK_STORAGE=redis://redis:6379/0
- FLASK_AUTH_TOKEN=super-secret-token
worker:
image: pythonf/zndraw:latest
entrypoint: celery -A zndraw_app.make_celery worker --loglevel=info -P eventlet
volumes:
- /path/to/files:/src
restart: unless-stopped
depends_on:
- redis
environment:
- FLASK_STORAGE=redis://redis:6379/0
- FLASK_SERVER_URL="http://zndraw:5003"
- FLASK_AUTH_TOKEN=super-secret-token
redis:
image: redis:latest
restart: always
environment:
- REDIS_PORT=6379
```
If you want to host zndraw as subdirectory `domain.com/zndraw` you need to adjust the environmental variables as well as update `base: "/",` in the `app/vite.config.ts` before building the ap..
# References
If you use ZnDraw in your research and find it helpful please cite us.
```bibtex
@misc{elijosiusZeroShotMolecular2024,
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},
year = {2024},
eprint = {2402.08708},
archiveprefix = {arxiv},
}
```
# 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 though the DFG under Germany's Excellence Strategy - EXC 2075 - 390740016 and the Stuttgart Center for Simulation Science (SimTech) was provided.
Raw data
{
"_id": null,
"home_page": null,
"name": "zndraw",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "zincwarecode",
"author_email": "zincwarecode@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8e/f2/2214b6c4efb7747426a934cf79b75273a03fa74815374d18a2da9438a679/zndraw-0.5.3.tar.gz",
"platform": null,
"description": "[](https://github.com/zincware)\n[](https://badge.fury.io/py/zndraw)\n[](https://arxiv.org/abs/2402.08708)\n[](https://codecov.io/gh/zincware/ZnDraw)\n\n\n# ZnDraw\n\nWelcome to ZnDraw, a powerful tool for visualizing and interacting with your trajectories.\n\n## Installation\n\nIt is recommended to install ZnDraw from PyPi via:\n\n```bash\npip install zndraw\n```\n\n## Quick Start\n\nVisualize your trajectories with a single command:\n\n```bash\nzndraw <file>\n```\n\n> [!NOTE]\n> ZnDraw's webapp-based approach allows you to use port forwarding to work with trajectories on remote systems.\n\n![ZnDraw UI](https://raw.githubusercontent.com/zincware/ZnDraw/main/misc/darkmode/overview.png#gh-dark-mode-only \"ZnDraw UI\")\n![ZnDraw UI](https://raw.githubusercontent.com/zincware/ZnDraw/main/misc/lightmode/overview.png#gh-light-mode-only \"ZnDraw UI\")\n\n## Multi-User and Multi-Client Support\n\nZnDraw supports multiple users and clients. Connect one or more Python clients to your ZnDraw instance:\n\n1. Click on `Python access` in the ZnDraw UI.\n2. Connect using the following code:\n\n```python\nfrom zndraw import ZnDraw\n\nvis = ZnDraw(url=\"http://localhost:1234\", token=\"<your-token>\")\n```\n\n![ZnDraw UI](https://raw.githubusercontent.com/zincware/ZnDraw/main/misc/darkmode/python.png#gh-dark-mode-only \"ZnDraw Python Client\")\n![ZnDraw UI](https://raw.githubusercontent.com/zincware/ZnDraw/main/misc/lightmode/python.png#gh-light-mode-only \"ZnDraw Python Client\")\n\nThe `vis` object provides direct access to your visualized scene. It inherits from `abc.MutableSequence`, so any changes you make are reflected for all connected clients.\n\n```python\nfrom ase.collections import s22\nvis.extend(list(s22))\n```\n\n## Additional Features\n\nYou can modify various aspects of the visualization:\n\n- `vis.camera`\n- `vis.points`\n- `vis.selection`\n- `vis.step`\n- `vis.figures`\n- `vis.bookmarks`\n- `vis.geometries`\n\nFor example, to add a geometry:\n\n```python\nfrom zndraw import Box\n\nvis.geometries = [Box(position=[0, 1, 2])]\n```\n\n![ZnDraw UI](https://raw.githubusercontent.com/zincware/ZnDraw/main/misc/darkmode/box.png#gh-dark-mode-only \"ZnDraw Geometries\")\n![ZnDraw UI](https://raw.githubusercontent.com/zincware/ZnDraw/main/misc/lightmode/box.png#gh-light-mode-only \"ZnDraw Geometries\")\n\n## Analyzing Data\n\nZnDraw enables you to analyze your data and generate plots using [Plotly](https://plotly.com/). It automatically detects available properties and offers a convenient drop-down menu for selection.\n\n![ZnDraw UI](https://raw.githubusercontent.com/zincware/ZnDraw/main/misc/darkmode/analysis.png#gh-dark-mode-only \"ZnDraw Analysis\")\n![ZnDraw UI](https://raw.githubusercontent.com/zincware/ZnDraw/main/misc/lightmode/analysis.png#gh-light-mode-only \"ZnDraw Analysis\")\n\nZnDraw will look for the `step` and `atom` index in the [customdata](https://plotly.com/python/reference/scatter/#scatter-customdata)`[0]` and `[1]` respectively to highlight the steps and atoms.\n\n## Writing Extensions\n\nMake your tools accessible via the ZnDraw UI by writing an extension:\n\n```python\nfrom zndraw import Extension\n\nclass AddMolecule(Extension):\n name: str\n\n def run(self, vis, **kwargs) -> None:\n structures = kwargs[\"structures\"]\n vis.append(structures[self.name])\n vis.step = len(vis) - 1\n\nvis.register(AddMolecule, run_kwargs={\"structures\": s22}, public=True)\nvis.socket.wait() # This can be ignored when using Jupyter\n```\n\nThe `AddMolecule` extension will appear for all `tokens` and can be used by any client.\n\n# Hosted Version\n\nA hosted version of ZnDraw is available at https://zndraw.icp.uni-stuttgart.de . To upload data, use:\n\n```bash\nzndraw <file> --url https://zndraw.icp.uni-stuttgart.de\n```\n\n## Self-Hosting\n\nTo host your own version of ZnDraw, use the following `docker-compose.yaml` setup:\n\n```yaml\nversion: \"3.9\"\n\nservices:\n zndraw:\n image: pythonf/zndraw:latest\n command: --no-standalone /src/file.xyz\n volumes:\n - /path/to/files:/src\n restart: unless-stopped\n ports:\n - 5003:5003\n depends_on:\n - redis\n - worker\n environment:\n - FLASK_STORAGE=redis://redis:6379/0\n - FLASK_AUTH_TOKEN=super-secret-token\n\n worker:\n image: pythonf/zndraw:latest\n entrypoint: celery -A zndraw_app.make_celery worker --loglevel=info -P eventlet\n volumes:\n - /path/to/files:/src\n restart: unless-stopped\n depends_on:\n - redis\n environment:\n - FLASK_STORAGE=redis://redis:6379/0\n - FLASK_SERVER_URL=\"http://zndraw:5003\"\n - FLASK_AUTH_TOKEN=super-secret-token\n\n redis:\n image: redis:latest\n restart: always\n environment:\n - REDIS_PORT=6379\n```\n\nIf you want to host zndraw as subdirectory `domain.com/zndraw` you need to adjust the environmental variables as well as update `base: \"/\",` in the `app/vite.config.ts` before building the ap..\n\n# References\n\nIf you use ZnDraw in your research and find it helpful please cite us.\n\n```bibtex\n@misc{elijosiusZeroShotMolecular2024,\n title = {Zero {{Shot Molecular Generation}} via {{Similarity Kernels}}},\n 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},\n year = {2024},\n eprint = {2402.08708},\n archiveprefix = {arxiv},\n}\n```\n\n# Acknowledgements\n\nThe creation of ZnDraw was supported by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) in the framework of the priority program SPP 2363, \u201cUtilization and Development of Machine Learning for Molecular Applications - Molecular Machine Learning\u201d Project No. 497249646. Further funding though the DFG under Germany's Excellence Strategy - EXC 2075 - 390740016 and the Stuttgart Center for Simulation Science (SimTech) was provided.\n",
"bugtrack_url": null,
"license": "License :: OSI Approved :: Eclipse Public License 2.0 (EPL-2.0)",
"summary": "Display and Edit Molecular Structures and Trajectories in the Browser.",
"version": "0.5.3",
"project_urls": {
"repository": "https://github.com/zincware/ZnDraw"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "841612fd61198ed33b07c5afc4d72f905212ec833c1f8a16096c4a1d5e3b3e57",
"md5": "c3815ca85ccff40f1152409d792229ad",
"sha256": "f11017d6e9a960d490fce6ae0efe219ca4d0a4a655ecde9834916209b5af789f"
},
"downloads": -1,
"filename": "zndraw-0.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3815ca85ccff40f1152409d792229ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 3409087,
"upload_time": "2024-11-15T09:45:15",
"upload_time_iso_8601": "2024-11-15T09:45:15.168480Z",
"url": "https://files.pythonhosted.org/packages/84/16/12fd61198ed33b07c5afc4d72f905212ec833c1f8a16096c4a1d5e3b3e57/zndraw-0.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ef22214b6c4efb7747426a934cf79b75273a03fa74815374d18a2da9438a679",
"md5": "4a2271d48f882e764ceb8adc54ed2320",
"sha256": "37d0f69347c0a9a428512d9233207bc95bf7ba6cebe2ab5769941c666467e913"
},
"downloads": -1,
"filename": "zndraw-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "4a2271d48f882e764ceb8adc54ed2320",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 3365857,
"upload_time": "2024-11-15T09:45:17",
"upload_time_iso_8601": "2024-11-15T09:45:17.559325Z",
"url": "https://files.pythonhosted.org/packages/8e/f2/2214b6c4efb7747426a934cf79b75273a03fa74815374d18a2da9438a679/zndraw-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 09:45:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zincware",
"github_project": "ZnDraw",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zndraw"
}
JSON
