{"id":15140740,"url":"https://github.com/superstar54/weas-widget","last_synced_at":"2026-01-02T20:18:28.449Z","repository":{"id":221324075,"uuid":"746922827","full_name":"superstar54/weas-widget","owner":"superstar54","description":"A widget to visualize and edit atomic structures in Jupyter Notebook","archived":false,"fork":false,"pushed_at":"2024-10-28T10:53:30.000Z","size":6545,"stargazers_count":21,"open_issues_count":14,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-29T21:26:36.786Z","etag":null,"topics":["3d","crystal","editor","jupyter-notebook","molecule","visualization"],"latest_commit_sha":null,"homepage":"https://weas-widget.readthedocs.io/en/latest/index.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/superstar54.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-22T23:14:39.000Z","updated_at":"2024-10-28T10:53:12.000Z","dependencies_parsed_at":"2024-05-16T03:03:11.549Z","dependency_job_id":"d52bd89d-585f-4c71-a99e-158e377a2bfe","html_url":"https://github.com/superstar54/weas-widget","commit_stats":{"total_commits":44,"total_committers":2,"mean_commits":22.0,"dds":"0.022727272727272707","last_synced_commit":"da7d9dabd5e35032776668a95c3d429b142c0ff3"},"previous_names":["superstar54/weas-widget"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstar54%2Fweas-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstar54%2Fweas-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstar54%2Fweas-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superstar54%2Fweas-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/superstar54","download_url":"https://codeload.github.com/superstar54/weas-widget/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237869036,"owners_count":19379250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","crystal","editor","jupyter-notebook","molecule","visualization"],"created_at":"2024-09-26T08:40:37.446Z","updated_at":"2026-01-02T20:18:28.443Z","avatar_url":"https://github.com/superstar54.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Welcome to WEAS Widget!\n[![PyPI version](https://badge.fury.io/py/weas-widget.svg)](https://badge.fury.io/py/weas-widget)\n[![Docs status](https://readthedocs.org/projects/weas-widget/badge)](http://weas-widget.readthedocs.io/)\n[![Unit test](https://github.com/superstar54/weas-widget/actions/workflows/ci.yml/badge.svg)](https://github.com/superstar54/weas-widget/actions/workflows/ci.yml)\n\nA widget to visualize and edit atomic structures in Jupyter Notebooks. It uses [WEAS](https://github.com/superstar54/weas) (Web Environment For Atomistic Structure) in the backend.\nInteract with the widget using LLM agents (e.g., LangChain) to guide edits and analysis from your notebook.\n\n\n\u003cimg src=\"docs/source/_static/images/example-adsorption.gif\"  width=\"100%\"/\u003e\n\n\nFeatures:\n\n- Model: space-filling, ball-stick, polyhedral.\n- Supports importing data from ASE and Pymatgen.\n- Edit structure: move, rotate, delete and replace atoms.\n- Supports periodic boundary conditions\n- Animations\n- Isosurfaces\n- Vector fields, e.g., magnetic moments, phonons, ...\n- Fermi surface\n- Lattice planes\n- Integrate with LLMs via LangChain Agent\n\n## Demo\nPlease try the widget in the following links:\n[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/superstar54/weas-widget/blob/main/examples/example.ipynb)\n\n## 🌟 Gallery: projects using `weas-widget`\n\n- **AiiDAlab Plugins:**\n    - [aiidalab-qe-vibroscopy](https://github.com/mikibonacci/aiidalab-qe-vibroscopy)\n    - [aiidalab-qe-pp](https://github.com/AndresOrtegaGuerrero/aiidalab-qe-pp)\n    - [aiidalab-qe-wannier90](https://github.com/superstar54/aiidalab-qe-wannier90)\n- [pack-mm](https://ddmms.github.io/pack-mm/tutorials/basic.html)\n- [ipyvasp](https://github.com/asaboor-gh/ipyvasp)\n\n### 📢 Want to Feature Your Project?\nIf your project uses `weas-widget`, we’d love to showcase it here!\n- Submit a **pull request (PR)** with a link to your project.\n- Need a project removed? Open a PR or issue, and we’ll take care of it.\n\n🚀 Let's build a growing community of `weas-widget` users!\n\n## Installation\n\nWith `pip`:\n\n```console\npip install weas-widget\n```\n\nTo install the latest version from source, first clone the repository and then install using `pip`:\n\n```console\ngit clone https://github.com/superstar54/weas-widget\ncd weas-widget\nnpm install\nnpm run build\npip install -e .\n```\n\n## How to use\n\n```python\nfrom ase.build import molecule\nfrom weas_widget import WeasWidget\natoms = molecule(\"C2H6SO\")\nviewer = WeasWidget()\nviewer.from_ase(atoms)\nviewer\n```\n\n\u003cimg src=\"docs/source/_static/images/example-c2h6so.png\"  width=\"300px\"/\u003e\n\n\nFull documentation at: https://weas-widget.readthedocs.io/en/latest/index.html\n\n\n## Reporting issues\nIf you encounter any problems, please first update the widget to the latest version.\n\n```console\n    pip install weas-widget  --upgrade\n```\n\nIf the problem persists, please open a [GitHub issue](https://github.com/superstar54/weas-widget/issues)\n\n\n## Features\n\n\n### Select Atoms\n- Pick Selection: Click directly on an atom to select it.\n- Range Selection: Hold the `Shift` key and drag the right mouse button to select a group of atoms.\n\n### Move, Rotate selected atoms\n\nPress the keyboard shortcut, and move your mouse.\n\n|Operation | Shortcut|\n|----------|---------|\n| Move     | `g`   |\n| Rotate   | `r`   |\n| Duplicate| `d`   |\n\n\n### Delete selected atoms\nPress the ``Delete`` key\n\n\n### Export\n- Export the modified atomic structure to ASE or Pymatgen\n```python\natoms = viewer.to_ase()\n```\n- Save image to a path by:\n```python\nviewer.save_image(\"/home/xing/filename.png\")\n```\n- Download image by:\n```python\nviewer.download_image(\"filename.png\")\n```\n\n### Different styles for the atoms.\n\n\n\u003cimg src=\"docs/source/_static/images/example-custom-model-style.png\"  width=\"500px\"/\u003e\n\n\n\n### Visualizing crystal structures\nFor a nice visualization of a crystal, show\n- unit cell\n- bonded atoms outside the cell\n- polyhedra\n\n```python\nfrom weas_widget import WeasWidget\nviewer1 = WeasWidget()\nviewer1.load_example(\"tio2.cif\")\nviewer1.avr.model_style = 2\nviewer1.avr.boundary = [[-0.1, 1.1], [-0.1, 1.1], [-0.1, 1.1]]\nviewer1.avr.show_bonded_atoms = True\nviewer1.avr.color_type = \"VESTA\"\nviewer1\n```\n\n\u003cimg src=\"docs/source/_static/images/example-tio2.png\"  width=\"300px\"/\u003e\n\n\n### Isosurfaces\n\n```python\nfrom ase.build import molecule\nfrom weas_widget import WeasWidget\nfrom ase.io.cube import read_cube_data\nvolume, atoms = read_cube_data(\"h2o-homo.cube\")\nviewer = WeasWidget()\nviewer.from_ase(atoms)\nviewer.avr.iso.volumetric_data = {\"values\": volume}\nviewer.avr.iso.settings = {\"positive\": {\"isovalue\": 0.001},\n                           \"negative\": {\"isovalue\": -0.001, \"color\": \"yellow\"}\n                           }\nviewer\n```\n\u003cimg src=\"docs/source/_static/images/example-isosurface.png\"  width=\"300px\"/\u003e\n\n\n### Fermi surface\n\n```python\nfrom weas_widget import WeasWidget\nviewer = WeasWidget()\nviewer.add_fermi_surface_from_bxsf(\"copper.bxsf\", clip_bz=True)\nviewer\n```\n\u003cimg src=\"docs/source/_static/images/fermi-surface.png\"  width=\"300px\"/\u003e\n\n\n### Magnetic moments\nShow the magnetic moments as a vector field.\n\n```python\nfrom ase.build import bulk\nfrom weas_widget import WeasWidget\nimport numpy as np\natoms = bulk(\"Fe\", cubic=True)\natoms*=[2, 2, 1]\natoms.set_array(\"moment\", np.ones(len(atoms)))\nviewer = WeasWidget()\nviewer.from_ase(atoms)\nviewer.avr.model_style = 1\nviewer\n```\n\u003cimg src=\"docs/source/_static/images/example-magnetic-moment.png\"  width=\"300px\"/\u003e\n\n\n### Phonons\nAnimate vibrational (phonon) modes (computed with external software).\n\n```python\nimport numpy as np\nfrom ase.build import bulk\nfrom weas_widget import WeasWidget\natoms = bulk(\"Fe\", cubic=True)\nphonon_setting = {\"eigenvectors\": np.array([[[0, 0], [0, 0],[0.5, 0]],\n                                    [[0, 0], [0, 0], [-0.5, 0]]]\n                                    ),\n        \"kpoint\": [0, 0, 0], # optional\n        \"amplitude\": 5, # scale the motion of the atoms\n        \"factor\": 1.5, # scale the length of the arrows\n        \"nframes\": 20,\n        \"repeat\": [4, 4, 1],\n        \"color\": \"blue\",\n        \"radius\": 0.1,\n        }\nviewer = WeasWidget()\nviewer.from_ase(atoms)\nviewer.avr.phonon_setting = phonon_setting\nviewer\n```\n\n\u003cimg src=\"docs/source/_static/images/example-phonon.gif\"  width=\"300px\"/\u003e\n\n### Lattice plane\nDraw a plane that is defined by the miller indices and distance from the origin or by selecting the atoms.\n\n```python\nviewer.avr.lp.add_plane_from_indices(name = \"111\",\n                                     indices = [1, 1, 1],\n                                     distance = 4,\n                                     scale = 1.0,\n                                     color = [0, 1, 1, 0.5])\nviewer.avr.lp.build_plane()\n```\n\n\u003cimg src=\"docs/source/_static/images/lattice_plane.png\"  width=\"300px\"/\u003e\n\n### Slice 2D\n```python\nfrom ase.build import molecule\nfrom weas_widget import WeasWidget\nfrom ase.io.cube import read_cube_data\nvolume, atoms = read_cube_data(\"h2o-homo.cube\")\nviewer = WeasWidget()\nviewer.from_ase(atoms)\nviewer.avr.model_style = 1\nviewer.avr.volume_slice.volumetric_data = {\"values\": volume}\nviewer.avr.volume_slice.settings = {\"Slice 1\": {\"h\": 0, \"k\": 1, \"l\": 0, \"distance\": 5.5, \"samplingDistance\": 0.1 },\n                                    \"Slice 2\": {\"h\": 1, \"k\": 1, \"l\": 0, \"distance\": 5.5, \"samplingDistance\": 0.1 },\n                                   }\nviewer.camera.setting = {\"direction\": [0.5, 1, 2], \"zoom\": 1.5}\nviewer\n```\n\u003cimg src=\"docs/source/_static/images/example-volume-slice.png\"  width=\"300px\"/\u003e\n\n### Save and restore state\n\n```python\nstate = viewer.export_state()\nviewer.save_state(\"snapshot.json\")\n\n# later\nviewer.load_state(\"snapshot.json\")\n\n# or create a viewer directly from a saved state\nviewer = WeasWidget.from_state_file(\"snapshot.json\")\n```\n\n### Integrate with LangChain Agent\n\n`WeasToolkit` provides agent-ready tools for inspection and editing (style controls, selection, structure loading, atom edits, camera, measurements, meshes, and more). You can also extend it with your own tools.\n\n```python\nfrom weas_widget import WeasWidget, WeasToolkit\nfrom langchain_openai import ChatOpenAI\nfrom langchain_widget import LangChainWidget\nfrom langchain_openai import ChatOpenAI\nfrom dotenv import load_dotenv\nimport ipywidgets as ipw\n\nload_dotenv()\n\nviewer = WeasWidget()\n\nchat_model = ChatOpenAI(model=\"gpt-4o-mini\")\n\nchat = LangChainWidget(\n    chat_model=chat_model,\n    tools=WeasToolkit(viewer=viewer),\n    title=\"WEAS Agent Chat\",\n    system_prompt=(\n        \"You are a scientific assistant. \"\n        \"Use the available tools to inspect and manipulate the 3D structure.\"\n    ),\n)\nipw.VBox([viewer, chat])\n```\n\nSee the agent tools reference in the docs: https://weas-widget.readthedocs.io/en/latest/agent_tools.html\n\n## Test\n\n### Unit test\n\n```console\npytest\n```\n\n### End-to-end test\n\nThe e2e test is similar to [ipywidgets](https://ipywidgets.readthedocs.io/en/latest/dev_testing.html).\n\nFor the first time, one needs to install the dependence.\n\n```\ncd tests/notebooks/\nyarn install\n```\n\nThen run in a terminal:\n\n```\nyarn start\n```\n\nIn another terminal:\n\n```\nyarn test\n```\n\nIf the snapshots need to be updated:\n\n```\nyarn test:update\n```\n\n## Contact\n* Xing Wang  \u003cxingwang1991@gmail.com\u003e\n\n## License\n[MIT](http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperstar54%2Fweas-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuperstar54%2Fweas-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperstar54%2Fweas-widget/lists"}