MolarVerse-PQSetup 0.1.0__tar.gz

molarverse_pqsetup-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.DS_Store
+.release-venv/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+build/
+dist/
+output/
+docs/_build/
+.playwright-cli/
+frontend/node_modules/
+frontend/.vite/
+frontend/vite.config.js
+frontend/vite.config.d.ts
+*.tsbuildinfo
+playwright-report/
+test-results/

molarverse_pqsetup-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+PQSetup follows [Semantic Versioning](https://semver.org/). This file records
+user-visible changes.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-13
+
+Initial public alpha.
+
+### Added
+
+- Local browser interface for preparing PQ simulation inputs
+- CIF, XYZ, PDB, MOL, SDF, ASE trajectory, and PQ restart imports
+- Molecular mechanics and supported external QM calculator setup
+- NVE, NVT, and NPT run planning with optional equilibration
+- Local validation with optional validation by a compatible PQ executable
+- Portable run packages with ordered inputs, launcher, provenance, and hashes
+- Reproducible coordinate wrapping and optional seeded perturbation

molarverse_pqsetup-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MolarVerse
+
+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.

molarverse_pqsetup-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: MolarVerse-PQSetup
+Version: 0.1.0
+Summary: Prepare and validate PQ simulation inputs.
+Project-URL: Documentation, https://molarverse.github.io/PQSetup/
+Project-URL: Repository, https://github.com/MolarVerse/PQSetup
+Project-URL: Changelog, https://github.com/MolarVerse/PQSetup/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/MolarVerse/PQSetup/issues
+Project-URL: PQ, https://github.com/MolarVerse/PQ
+Author: MolarVerse
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: computational chemistry,molecular dynamics,simulation input
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Requires-Dist: ase>=3.23
+Requires-Dist: fastapi>=0.115
+Requires-Dist: numpy>=2.0
+Requires-Dist: pydantic>=2.10
+Requires-Dist: python-multipart>=0.0.18
+Requires-Dist: scipy>=1.13
+Requires-Dist: uvicorn>=0.34
+Provides-Extra: docs
+Requires-Dist: furo<2027,>=2024.8.6; extra == 'docs'
+Requires-Dist: sphinx-copybutton<1,>=0.5; extra == 'docs'
+Requires-Dist: sphinx-design<1,>=0.6; extra == 'docs'
+Requires-Dist: sphinx<9,>=8; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/MolarVerse/PQSetup/main/frontend/public/pq-logo.png" alt="PQSetup logo" width="200">
+
+[![CI](https://github.com/MolarVerse/PQSetup/actions/workflows/ci.yml/badge.svg)](https://github.com/MolarVerse/PQSetup/actions/workflows/ci.yml)
+[![Docs](https://github.com/MolarVerse/PQSetup/actions/workflows/docs.yml/badge.svg)](https://molarverse.github.io/PQSetup/)
+[![PyPI](https://img.shields.io/pypi/v/molarverse-pqsetup.svg)](https://pypi.org/project/molarverse-pqsetup/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+# PQSetup
+
+Prepare and validate PQ simulation inputs in a local browser interface.
+
+PQSetup builds the input package. [PQ](https://github.com/MolarVerse/PQ) runs it.
+
+[Documentation](https://molarverse.github.io/PQSetup/) ·
+[Getting started](https://molarverse.github.io/PQSetup/getting-started.html) ·
+[Command line](https://molarverse.github.io/PQSetup/reference/cli.html)
+
+## Install
+
+Python 3.11 or newer. The UI ships inside the package; Node.js is not required.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install MolarVerse-PQSetup
+```
+
+From a local clone (contributors):
+
+```bash
+python -m pip install .
+```
+
+## Quick Start
+
+```bash
+pqsetup
+```
+
+Keep the water example, choose a method, review the inputs, download the
+package, then run it where PQ is installed:
+
+```bash
+unzip water-nvt.zip -d water-nvt
+cd water-nvt
+./run.sh /path/to/PQ
+```
+
+Check what this machine can see:
+
+```bash
+pqsetup doctor
+pqsetup --pq-executable /path/to/PQ doctor
+```
+
+Validate an existing input:
+
+```bash
+pqsetup validate run.in
+```
+
+See the [documentation](https://molarverse.github.io/PQSetup/) for server
+options, validation scopes, and complete setup examples.
+
+## Input
+
+| Structure | Extension | Handling |
+| --- | --- | --- |
+| PQ restart | `.rst` | Preserves atom names, molecule types, and available velocities or forces |
+| CIF | `.cif` | Read through ASE |
+| XYZ | `.xyz`, `.extxyz` | Reads standard and extended XYZ data |
+| Protein Data Bank | `.pdb` | Read through ASE |
+| MOL / SDF | `.mol`, `.sdf` | Read through ASE |
+| ASE trajectory | `.traj` | Read through ASE |
+
+Multi-frame ASE sources import the final frame. Structures without a cell
+receive a centered vacuum cell. Periodic coordinates follow PQ's
+origin-centered cell convention.
+
+## Workflow
+
+| Step | Result |
+| --- | --- |
+| System | Inspect coordinates, elements, periodic cells, and close contacts |
+| Method | Configure molecular mechanics or one supported QM calculator |
+| Conditions | Build NVE, NVT, or NPT sampling with optional NVT equilibration |
+| Prepare | Wrap periodic atoms and optionally perturb perfect crystal symmetry |
+| Review | Inspect every generated input before creating the package |
+
+PQSetup does not submit jobs or run the simulation.
+
+## Validation
+
+PQSetup checks the structure, plan, required files, and generated inputs
+locally. When the selected PQ executable advertises machine-readable
+validation, PQSetup also checks the inputs with PQ.
+
+Environment detection reports what is available. It does not establish that a
+method, force field, or protocol is scientifically suitable.
+
+PQSetup writes inputs for the stable PQ v0.7.0 release.
+
+## Run Packages
+
+| File | Purpose |
+| --- | --- |
+| `run-eq.in` | Optional NVT equilibration |
+| `run-01.in` … `run-999.in` | Sampling inputs and restart chain |
+| Structure restart | Prepared coordinates under the selected start filename |
+| `run.sh` | Fail-fast execution in the recorded order |
+| `pqproject.json` | Plan, environment, provenance, warnings, and file hashes |
+
+Uploaded force-field files and calculator templates are included in the
+package.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+npm --prefix frontend ci
+python -m pytest
+npm --prefix frontend test
+npm --prefix frontend run build
+```

molarverse_pqsetup-0.1.0/README.md

@@ -0,0 +1,124 @@
+<img src="https://raw.githubusercontent.com/MolarVerse/PQSetup/main/frontend/public/pq-logo.png" alt="PQSetup logo" width="200">
+
+[![CI](https://github.com/MolarVerse/PQSetup/actions/workflows/ci.yml/badge.svg)](https://github.com/MolarVerse/PQSetup/actions/workflows/ci.yml)
+[![Docs](https://github.com/MolarVerse/PQSetup/actions/workflows/docs.yml/badge.svg)](https://molarverse.github.io/PQSetup/)
+[![PyPI](https://img.shields.io/pypi/v/molarverse-pqsetup.svg)](https://pypi.org/project/molarverse-pqsetup/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+# PQSetup
+
+Prepare and validate PQ simulation inputs in a local browser interface.
+
+PQSetup builds the input package. [PQ](https://github.com/MolarVerse/PQ) runs it.
+
+[Documentation](https://molarverse.github.io/PQSetup/) ·
+[Getting started](https://molarverse.github.io/PQSetup/getting-started.html) ·
+[Command line](https://molarverse.github.io/PQSetup/reference/cli.html)
+
+## Install
+
+Python 3.11 or newer. The UI ships inside the package; Node.js is not required.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install MolarVerse-PQSetup
+```
+
+From a local clone (contributors):
+
+```bash
+python -m pip install .
+```
+
+## Quick Start
+
+```bash
+pqsetup
+```
+
+Keep the water example, choose a method, review the inputs, download the
+package, then run it where PQ is installed:
+
+```bash
+unzip water-nvt.zip -d water-nvt
+cd water-nvt
+./run.sh /path/to/PQ
+```
+
+Check what this machine can see:
+
+```bash
+pqsetup doctor
+pqsetup --pq-executable /path/to/PQ doctor
+```
+
+Validate an existing input:
+
+```bash
+pqsetup validate run.in
+```
+
+See the [documentation](https://molarverse.github.io/PQSetup/) for server
+options, validation scopes, and complete setup examples.
+
+## Input
+
+| Structure | Extension | Handling |
+| --- | --- | --- |
+| PQ restart | `.rst` | Preserves atom names, molecule types, and available velocities or forces |
+| CIF | `.cif` | Read through ASE |
+| XYZ | `.xyz`, `.extxyz` | Reads standard and extended XYZ data |
+| Protein Data Bank | `.pdb` | Read through ASE |
+| MOL / SDF | `.mol`, `.sdf` | Read through ASE |
+| ASE trajectory | `.traj` | Read through ASE |
+
+Multi-frame ASE sources import the final frame. Structures without a cell
+receive a centered vacuum cell. Periodic coordinates follow PQ's
+origin-centered cell convention.
+
+## Workflow
+
+| Step | Result |
+| --- | --- |
+| System | Inspect coordinates, elements, periodic cells, and close contacts |
+| Method | Configure molecular mechanics or one supported QM calculator |
+| Conditions | Build NVE, NVT, or NPT sampling with optional NVT equilibration |
+| Prepare | Wrap periodic atoms and optionally perturb perfect crystal symmetry |
+| Review | Inspect every generated input before creating the package |
+
+PQSetup does not submit jobs or run the simulation.
+
+## Validation
+
+PQSetup checks the structure, plan, required files, and generated inputs
+locally. When the selected PQ executable advertises machine-readable
+validation, PQSetup also checks the inputs with PQ.
+
+Environment detection reports what is available. It does not establish that a
+method, force field, or protocol is scientifically suitable.
+
+PQSetup writes inputs for the stable PQ v0.7.0 release.
+
+## Run Packages
+
+| File | Purpose |
+| --- | --- |
+| `run-eq.in` | Optional NVT equilibration |
+| `run-01.in` … `run-999.in` | Sampling inputs and restart chain |
+| Structure restart | Prepared coordinates under the selected start filename |
+| `run.sh` | Fail-fast execution in the recorded order |
+| `pqproject.json` | Plan, environment, provenance, warnings, and file hashes |
+
+Uploaded force-field files and calculator templates are included in the
+package.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+npm --prefix frontend ci
+python -m pytest
+npm --prefix frontend test
+npm --prefix frontend run build
+```

molarverse_pqsetup-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,50 @@
+# Third-party notices
+
+## Lucide
+
+PQSetup bundles icons from `lucide-react` 0.468.0.
+
+ISC License
+
+Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2022 as part
+of Feather (MIT). All other copyright (c) for Lucide are held by Lucide
+Contributors 2022.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+## React
+
+The browser bundle includes `react` 19.2.8, `react-dom` 19.2.8, and
+`scheduler` 0.27.0.
+
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+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.

molarverse_pqsetup-0.1.0/docs/_static/custom.css

@@ -0,0 +1,59 @@
+/* PQSetup-specific additions to Furo. */
+
+.sidebar-brand {
+  flex-direction: row;
+  align-items: center;
+  gap: 0.75rem;
+  padding-block: 0.75rem;
+}
+
+.sidebar-logo-container {
+  display: flex;
+  flex: 0 0 4.5rem;
+  align-items: center;
+  margin: 0;
+}
+
+.sidebar-logo {
+  width: 4.5rem;
+  margin: 0;
+}
+
+.sidebar-brand-text {
+  margin: 0;
+  font-size: 1.35rem;
+  font-weight: 700;
+  line-height: 1.1;
+  letter-spacing: -0.02em;
+}
+
+.sd-card {
+  box-shadow: none;
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+.sd-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.08);
+}
+
+.content p code.literal,
+.content li code.literal {
+  background: var(--color-code-background);
+  border-radius: 0.2em;
+}
+
+.pq-workspace {
+  margin: 1.5rem 0 0;
+}
+
+.pq-workspace img,
+.pq-shot img {
+  width: 100%;
+  border: 1px solid var(--color-foreground-border);
+  border-radius: 0.35rem;
+}
+
+.pq-shot {
+  margin: 1.5rem 0 2rem;
+}

molarverse_pqsetup-0.1.0/docs/conf.py

@@ -0,0 +1,84 @@
+"""Sphinx configuration for the PQSetup documentation."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+project = "PQSetup"
+author = "MolarVerse"
+copyright = "2026, the PQSetup authors"
+
+try:
+    from pqsetup import __version__ as release
+except Exception:  # pragma: no cover - package may be absent in a bare checkout
+    release = ""
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "sphinx_design",
+]
+
+autodoc_typehints = "description"
+napoleon_numpy_docstring = True
+napoleon_google_docstring = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "furo"
+html_title = "PQSetup"
+html_logo = "assets/pq-logo.png"
+html_favicon = "assets/pq-logo.png"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
+html_theme_options = {
+    "sidebar_hide_name": False,
+    "light_css_variables": {
+        "color-brand-primary": "#1f718f",
+        "color-brand-content": "#176c8c",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#65bddb",
+        "color-brand-content": "#65bddb",
+    },
+    "source_repository": "https://github.com/MolarVerse/PQSetup/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/MolarVerse/PQSetup",
+            "html": (
+                '<svg stroke="currentColor" fill="currentColor" stroke-width="0" '
+                'viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 '
+                '3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01'
+                '-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13'
+                '-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 '
+                '2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31'
+                '-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 '
+                '1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 '
+                '1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 '
+                '3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55'
+                '.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>'
+            ),
+            "class": "",
+        },
+    ],
+}
+
+html_baseurl = "https://molarverse.github.io/PQSetup/"

molarverse_pqsetup-0.1.0/docs/getting-started.rst

@@ -0,0 +1,99 @@
+Getting started
+===============
+
+PQSetup prepares PQ input packages in a local browser. It does not install or
+run PQ. Install `PQ <https://github.com/MolarVerse/PQ>`_ separately to validate
+deeply and to execute ``run.sh``.
+
+You can design and export packages without a detected calculator or PQ
+executable. Missing checks are reported instead of silently passed.
+
+Requirements
+------------
+
+* Python 3.11 or newer
+* A PQ executable to validate and run the generated inputs
+* The calculator and supporting files required by the chosen method
+
+Install
+-------
+
+.. code-block:: bash
+
+   python3 -m venv .venv
+   source .venv/bin/activate
+   python -m pip install MolarVerse-PQSetup
+
+From a local clone:
+
+.. code-block:: bash
+
+   python -m pip install .
+
+Node.js is only needed when changing the interface.
+
+Open the interface
+------------------
+
+.. code-block:: bash
+
+   pqsetup
+
+PQSetup opens a local page at ``127.0.0.1:8888``. To choose another port or
+avoid opening a browser:
+
+.. code-block:: bash
+
+   pqsetup serve --port 8890 --no-browser
+
+Create the first package
+------------------------
+
+#. Keep the water example, or import a structure.
+#. Choose molecular mechanics or one QM calculator.
+#. Set the sampling ensemble and duration. Add NVT equilibration if needed.
+#. Review optional coordinate preparation.
+#. Inspect every generated input, then create the package.
+
+Presets are editable starting points, not validated production protocols.
+
+Check the environment
+---------------------
+
+.. code-block:: bash
+
+   pqsetup doctor
+
+``doctor`` reports the selected PQ executable and the external calculators
+that PQSetup can detect. To use a different executable:
+
+.. code-block:: bash
+
+   pqsetup --pq-executable /opt/pq/bin/PQ doctor
+
+The same path can be supplied through ``PQ_EXECUTABLE``.
+
+Run the package
+---------------
+
+Unpack the download on the machine where PQ and the calculator are available:
+
+.. code-block:: bash
+
+   mkdir water-nvt
+   unzip water-nvt.zip -d water-nvt
+   cd water-nvt
+   ./run.sh /opt/pq/bin/PQ
+
+The launcher follows the recorded input order, writes output to ``run-logs/``,
+and stops after the first failed or incomplete PQ run.
+
+PQSetup does not submit a scheduler job. Transfer and submission remain under
+the user's control.
+
+Next
+----
+
+* :doc:`Build a run <workflow>`
+* :doc:`Understand validation <validation>`
+* :doc:`Inspect the package format <run-packages>`