aseview 0.0.1__tar.gz

aseview-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'aseview/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material pymdown-extensions
+          pip install numpy ase
+          pip install -e .
+
+      - name: Generate example viewers
+        run: |
+          python docs/generate_examples.py
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

aseview-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Publish target'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

aseview-0.0.1/.gitignore

@@ -0,0 +1,90 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints/
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Project specific
+*.html
+!aseview/templates/*.html
+!docs/*.html
+*.xyz
+*.cif
+*.json
+!pyproject.toml

aseview-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mingi Kang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aseview-0.0.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include aseview/templates *.html
+recursive-include aseview/static *.css *.js

aseview-0.0.1/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: aseview
+Version: 0.0.1
+Summary: A molecular viewer for ASE (Atomic Simulation Environment) data
+Author-email: Mingi Kang <kangmg@kentech.ac.kr>
+License: MIT License
+        
+        Copyright (c) 2024 Mingi Kang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/kangmg/aseview
+Project-URL: Repository, https://github.com/kangmg/aseview
+Project-URL: Documentation, https://kangmg.github.io/aseview
+Project-URL: Bug Tracker, https://github.com/kangmg/aseview/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: ase
+Requires-Dist: ipywidgets
+Requires-Dist: jupyter
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: license-file
+
+# aseview
+
+Molecular structure viewer for ASE (Atomic Simulation Environment).
+
+**Status: pre-alpha**
+
+## Installation
+
+```bash
+pip install aseview
+```
+
+For development:
+
+```bash
+git clone https://github.com/kangmg/aseview.git
+cd aseview
+pip install -e .
+```
+
+## CLI Usage
+
+```bash
+# Basic usage
+aseview molecule.xyz
+
+# View trajectory (all frames)
+aseview trajectory.xyz -i :
+
+# View specific frames
+aseview trajectory.xyz -i 0:10    # frames 0-9
+aseview trajectory.xyz -i -1      # last frame
+aseview trajectory.xyz -i ::2     # every 2nd frame
+
+# Specify file format
+aseview POSCAR -f vasp
+
+# Custom port
+aseview molecule.xyz -p 9000
+
+# Overlay multiple structures
+aseview reactant.xyz product.xyz
+
+# Overlay with colormap
+aseview trajectory.xyz -v overlay --cmap viridis
+
+# Normal mode visualization with ORCA Hessian
+aseview molecule.xyz --hess orca.hess
+
+# Save as HTML file
+aseview molecule.xyz -o output.html
+
+# Kill existing server on port
+aseview molecule.xyz -k
+
+# Help
+aseview -h
+```
+
+## SSH Port Forwarding
+
+When running on a remote server (e.g., HPC cluster, Docker container):
+
+```bash
+# 1. On remote server
+aseview molecule.xyz -p 8080
+
+# 2. On local machine (separate terminal)
+ssh -L 8080:localhost:8080 user@remote-server
+
+# 3. Open in local browser
+# http://localhost:8080
+```
+
+For Docker with custom SSH port:
+
+```bash
+# Connect with port forwarding
+ssh user@localhost -p 10011 -L 8080:localhost:8080
+
+# Then run aseview inside container
+aseview molecule.xyz -p 8080
+```
+
+## Jupyter Notebook
+
+### Quick Start
+
+```python
+from ase.io import read
+from aseview import MolecularViewer
+
+atoms = read('molecule.xyz')
+viewer = MolecularViewer(atoms)
+viewer.show()
+```
+
+### With Trajectory
+
+```python
+from ase.io import read
+from aseview import MolecularViewer
+
+# Read all frames
+trajectory = read('trajectory.xyz', index=':')
+viewer = MolecularViewer(trajectory)
+viewer.show()
+```
+
+### Overlay Multiple Structures
+
+```python
+from ase.io import read
+from aseview import OverlayViewer
+
+reactant = read('reactant.xyz')
+product = read('product.xyz')
+viewer = OverlayViewer([reactant, product])
+viewer.show()
+```
+
+### Overlay with Colormap
+
+```python
+from ase.io import read
+from aseview import OverlayViewer
+
+trajectory = read('optimization.xyz', index=':')
+viewer = OverlayViewer(
+    trajectory,
+    colorBy='Colormap',
+    colormap='viridis'  # viridis, plasma, coolwarm, jet, rainbow, grayscale
+)
+viewer.show()
+```
+
+### Align Molecules (RMSD Minimization)
+
+```python
+from ase.io import read
+from aseview import OverlayViewer
+
+structures = [read(f'conf{i}.xyz') for i in range(5)]
+viewer = OverlayViewer(
+    structures,
+    alignMolecules=True,  # Kabsch rotation + Hungarian reordering
+    colorBy='Molecule'
+)
+viewer.show()
+```
+
+### Normal Mode Visualization
+
+#### From ASE Vibrations
+
+```python
+from ase import Atoms
+from ase.calculators.emt import EMT
+from ase.optimize import BFGS
+from ase.vibrations import Vibrations
+from aseview import NormalViewer
+
+# Create or load molecule
+atoms = Atoms('H2O', positions=[[0, 0, 0], [0.96, 0, 0], [-0.24, 0.93, 0]])
+atoms.calc = EMT()
+
+# Optimize structure
+opt = BFGS(atoms)
+opt.run(fmax=0.01)
+
+# Calculate vibrations
+vib = Vibrations(atoms, name='vib')
+vib.run()
+vib.summary()
+
+# Visualize normal modes
+viewer = NormalViewer(atoms, vibrations=vib)
+viewer.show()
+```
+
+#### From ORCA Hessian File
+
+```python
+from ase.io import read
+from aseview import NormalViewer
+
+atoms = read('molecule.xyz')
+viewer = NormalViewer.from_orca(atoms, 'orca.hess')
+viewer.show()
+```
+
+Features:
+- Mode selector dropdown with frequencies
+- Sinusoidal animation of atomic displacements
+- Amplitude slider to control displacement magnitude
+- Show Vectors toggle to display mode displacement arrows
+- Imaginary frequencies (transition states) shown in red
+
+### Using view_molecule Helper
+
+```python
+from aseview.jupyter import view_molecule
+from ase.io import read
+
+atoms = read('molecule.xyz')
+view_molecule(atoms, viewer_type='molecular', height=600)
+```
+
+### Custom Settings
+
+```python
+from aseview import MolecularViewer
+
+viewer = MolecularViewer(
+    atoms,
+    style='neon',           # default, cartoon, neon, glossy, metallic, rowan, grey
+    bondThreshold=1.2,      # bond detection scale factor
+    atomSize=0.5,
+    showCell=False,
+    backgroundColor='#000000'
+)
+viewer.show(width='100%', height=800)
+```
+
+### Save to HTML
+
+```python
+viewer.save_html('output.html')
+```
+
+## Viewer Types
+
+| Viewer | Description |
+|--------|-------------|
+| MolecularViewer | Single structure or trajectory animation |
+| NormalViewer | Normal mode vibration visualization |
+| OverlayViewer | Compare multiple structures overlaid |
+
+## JavaScript Module
+
+Use aseview in any web page without Python:
+
+```html
+<div id="viewer" style="width:100%; height:500px;"></div>
+
+<script src="https://raw.githack.com/kangmg/aseview_v2_dev/main/aseview/static/js/aseview.js"></script>
+<script>
+    const viewer = new ASEView.MolecularViewer('#viewer');
+    viewer.setData({
+        symbols: ['O', 'H', 'H'],
+        positions: [
+            [0.0, 0.0, 0.117],
+            [0.0, 0.757, -0.469],
+            [0.0, -0.757, -0.469]
+        ]
+    });
+</script>
+```
+
+See the [JavaScript Module documentation](https://kangmg.github.io/aseview_v2_dev/js-module/) for full API reference.
+
+## Supported Formats
+
+All formats supported by ASE: xyz, cif, pdb, POSCAR, extxyz, etc.
+
+## License
+
+MIT