Skip to content

Commit 7774d83

Browse files
galjosgaljos
committed
Add 3Dmol viewer and scientific workflow
1 parent 0c9a552 commit 7774d83

62 files changed

Lines changed: 10102 additions & 686 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/pages.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: true
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
- uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.12"
26+
cache: pip
27+
- uses: actions/setup-node@v4
28+
with:
29+
node-version: "22"
30+
cache: npm
31+
cache-dependency-path: frontend/package-lock.json
32+
- name: Install documentation dependencies
33+
run: python -m pip install '.[docs,ase]'
34+
- name: Build documentation
35+
run: python -m sphinx -W -b html docs _site
36+
- name: Install frontend dependencies
37+
working-directory: frontend
38+
run: npm ci
39+
- name: Build read-only viewer
40+
working-directory: frontend
41+
env:
42+
VITE_STATIC_DEMO: "true"
43+
VITE_BASE_PATH: /PQViewer/viewer/
44+
PQVIEWER_OUT_DIR: ../_site/viewer
45+
run: npm run build
46+
- name: Pack the perovskite demo
47+
run: python scripts/build_static_demo.py examples/strontium-titanate.extxyz _site/viewer/demo
48+
- name: Prepare Pages
49+
run: touch _site/.nojekyll
50+
- uses: actions/configure-pages@v5
51+
with:
52+
enablement: true
53+
token: ${{ secrets.GITHUB_TOKEN }}
54+
- uses: actions/upload-pages-artifact@v4
55+
with:
56+
path: _site
57+
58+
deploy:
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
runs-on: ubuntu-latest
63+
needs: build
64+
steps:
65+
- name: Deploy
66+
id: deployment
67+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 51 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
<p align="center">
2-
<img src="frontend/public/pq-logo.png" alt="PQViewer logo" width="72">
3-
</p>
1+
<img src="frontend/public/pq-logo.png" alt="PQViewer logo" width="200">
42

53
# PQViewer
64

@@ -15,7 +13,11 @@ still change before 1.0.
1513
![A 100-frame UMCM-9 trajectory in PQViewer](docs/assets/screenshots/trajectory-workspace.png)
1614

1715
<p align="center">
18-
<a href="docs/index.md"><strong>Explore the documentation</strong></a>
16+
<a href="docs/web-demo.md"><strong>Interactive web demo</strong></a>
17+
·
18+
<a href="https://molarverse.github.io/PQViewer/"><strong>Read the documentation</strong></a>
19+
·
20+
<a href="examples/pqviewer-notebook.ipynb"><strong>Open the Jupyter example</strong></a>
1921
</p>
2022

2123
| Protein | Molecule | Framework |
@@ -38,6 +40,26 @@ pqviewer examples/water.xyz
3840
The interface is bundled with the Python package. Node.js is not required to
3941
install or run the viewer.
4042

43+
The application stays on one page: **View** controls the scene, **Edit** owns
44+
atom and cell changes, **Analyze** explains selections and measurements, and
45+
**Export** opens the publication figure path. The central finder searches
46+
atoms, settings, and commands using `Cmd/Ctrl+K` or `/`; on small screens,
47+
**Tools** opens the same inspector as an expandable sheet.
48+
49+
## Playable web demo
50+
51+
The Pages-ready demo runs the same bundled 3Dmol.js interface against a
52+
read-only SrTiO3 perovskite dataset. It supports rotation, selection,
53+
structure and cell edits, representation controls, command search, and
54+
client-side structure and figure export without a Python server. Opening local
55+
files, streaming growing trajectories, and PQAnalysis calculations remain in
56+
the installed local application.
57+
58+
Its target URL is
59+
[`molarverse.github.io/PQViewer/viewer/`](https://molarverse.github.io/PQViewer/viewer/).
60+
Publishing from the current private repository requires a GitHub plan that
61+
supports Pages for private repositories, or making the repository public.
62+
4163
Open a trajectory, PQ input, run directory, or frame slice:
4264

4365
```bash
@@ -55,13 +77,35 @@ pqviewer structure.cif
5577
pqviewer optimization.traj
5678
```
5779

80+
## Jupyter
81+
82+
Install the notebook helper, then return `view(...)` from a cell:
83+
84+
```bash
85+
python -m pip install '.[jupyter,ase]'
86+
```
87+
88+
```python
89+
from pqviewer import view
90+
91+
viewer = view("trajectory.xyz", height=620)
92+
viewer
93+
```
94+
95+
The iframe is the real local application, not a static screenshot. Close its
96+
server with `viewer.close()` when it is no longer needed. See the
97+
[executable notebook](examples/pqviewer-notebook.ipynb) and
98+
[Jupyter guide](docs/jupyter.md).
99+
58100
## What it does
59101

60102
- Opens structures, trajectories, PQ inputs, and joined restart runs.
61103
- Uses indexed access for PQ sources, ASE `.traj`, and indexed ASE sequences
62104
without retaining every coordinate frame in memory.
63105
- Displays forces, velocities, charges, periodic images, water, protein
64106
cartoons, and crystal coordination polygons or polyhedra when supported.
107+
- Edits atom identity, Cartesian coordinates, lattice parameters, vectors, and
108+
periodic axes locally, then downloads the current frame as EXTXYZ.
65109
- Uses PQ's centered fractional cell convention, `[-0.5, 0.5)`, including
66110
triclinic cells.
67111
- Selects atoms by pointer, box, element, molecule, residue, connectivity, or
@@ -80,12 +124,15 @@ Try the included periodic fixtures:
80124
pqviewer examples/periodic-boundary.extxyz
81125
pqviewer examples/periodic-crossing.extxyz
82126
pqviewer examples/acof-triclinic.xyz
127+
pqviewer examples/strontium-titanate.extxyz
83128
```
84129

85130
## Documentation
86131

87132
- [Documentation overview](docs/index.md)
88133
- [Getting started](docs/getting-started.md)
134+
- [Interactive web demo](docs/web-demo.md)
135+
- [Jupyter](docs/jupyter.md)
89136
- [Viewer guide](docs/viewer-guide.md)
90137
- [Data sources and periodic conventions](docs/data-and-conventions.md)
91138
- [Trajectory analysis](docs/trajectory-analysis.md)

‎THIRD_PARTY_NOTICES.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,82 @@
11
# Third-party notices
22

3+
## Lucide
4+
5+
PQViewer bundles icons from Lucide React 1.27.0.
6+
7+
ISC License
8+
9+
Copyright (c) 2026 Lucide Icons and Contributors
10+
11+
Permission to use, copy, modify, and/or distribute this software for any
12+
purpose with or without fee is hereby granted, provided that the above
13+
copyright notice and this permission notice appear in all copies.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
16+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
17+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
18+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
19+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
20+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
21+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
22+
23+
Some Lucide icons are derived from the Feather project:
24+
25+
MIT License
26+
27+
Copyright (c) 2013-present Cole Bemis
28+
29+
Permission is hereby granted, free of charge, to any person obtaining a copy
30+
of this software and associated documentation files (the "Software"), to deal
31+
in the Software without restriction, including without limitation the rights
32+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
33+
copies of the Software, and to permit persons to whom the Software is
34+
furnished to do so, subject to the following conditions:
35+
36+
The above copyright notice and this permission notice shall be included in all
37+
copies or substantial portions of the Software.
38+
39+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
40+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
41+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
42+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
43+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
44+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
45+
SOFTWARE.
46+
47+
## 3Dmol.js
48+
49+
PQViewer bundles 3Dmol.js 2.5.5 for interactive molecular rendering.
50+
51+
BSD 3-Clause License
52+
53+
Copyright (c) 2014, University of Pittsburgh and contributors
54+
All rights reserved.
55+
56+
Redistribution and use in source and binary forms, with or without
57+
modification, are permitted provided that the following conditions are met:
58+
59+
1. Redistributions of source code must retain the above copyright notice,
60+
this list of conditions and the following disclaimer.
61+
2. Redistributions in binary form must reproduce the above copyright notice,
62+
this list of conditions and the following disclaimer in the documentation
63+
and/or other materials provided with the distribution.
64+
3. Neither the name of the copyright holder nor the names of its contributors
65+
may be used to endorse or promote products derived from this software
66+
without specific prior written permission.
67+
68+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
69+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
70+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
71+
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
72+
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
73+
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
74+
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
75+
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
76+
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
77+
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
78+
POSSIBILITY OF SUCH DAMAGE.
79+
380
## PQAnalysis example data
481

582
`examples/acof-triclinic.xyz` contains the first four frames of the PQAnalysis

‎docs/_static/custom.css‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,47 @@ html[data-theme="dark"] {
4949
border-radius: 0.35rem;
5050
}
5151

52+
.pq-demo-shell {
53+
margin: 1.5rem 0 2rem;
54+
overflow: hidden;
55+
border: 1px solid var(--pst-color-border);
56+
border-radius: 0.55rem;
57+
background: var(--pst-color-surface);
58+
}
59+
60+
.pq-demo-heading {
61+
display: flex;
62+
gap: 1rem;
63+
align-items: center;
64+
justify-content: space-between;
65+
padding: 0.75rem 0.9rem;
66+
border-bottom: 1px solid var(--pst-color-border);
67+
}
68+
69+
.pq-demo-heading div {
70+
display: grid;
71+
gap: 0.1rem;
72+
}
73+
74+
.pq-demo-heading span {
75+
color: var(--pst-color-text-muted);
76+
font-size: 0.86rem;
77+
}
78+
79+
.pq-demo-heading a {
80+
white-space: nowrap;
81+
font-weight: 650;
82+
}
83+
84+
.pq-demo-shell iframe {
85+
display: block;
86+
width: 100%;
87+
height: min(72vh, 690px);
88+
min-height: 420px;
89+
border: 0;
90+
background: #f6f8f8;
91+
}
92+
5293
.sd-card {
5394
box-shadow: none;
5495
}
@@ -69,3 +110,14 @@ html[data-theme="dark"] {
69110
max-width: 100%;
70111
}
71112
}
113+
114+
@media screen and (max-width: 40em) {
115+
.pq-demo-heading {
116+
align-items: flex-start;
117+
flex-direction: column;
118+
}
119+
120+
.pq-demo-shell iframe {
121+
min-height: 520px;
122+
}
123+
}

0 commit comments

Comments
 (0)