PoreMS App

Web interface for PoreMS — a Python library for generating atomistic silica pore models for molecular dynamics simulations.

The app provides a three-step wizard:

1. Structure & Shape — crystal polymorph (α/β-Cristobalite or amorphous), pore geometry (cylinder, slit, bottleneck, cone, constriction, parallel), block dimensions, and hydroxylation density.
2. Molecules — attach surface-grafted molecules loaded from a local topology library or built from scratch in an atom-by-atom editor with a live 3-D preview.
3. Generate — review the full configuration, then build and download the pore as a GROMACS-ready .zip (coordinates, topology, force-field parameters, a property table, and a reproducible Python script).

---

Running locally

Requirements: Python 3.12+, Git (needed to install PoreMS from source).

# 1. Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate        # macOS / Linux
venv\Scripts\activate           # Windows

# 2. Install dependencies
pip install -r requirements.txt

# 3. Start the development server
uvicorn main:app --reload

Open http://localhost:8000.

--reload restarts automatically on file changes — no manual restart needed while editing main.py.

---

Topology library (optional)

The molecule picker in step 2 can load from a local topology folder. The folder must contain one or more of the following sub-directories:

topologies/
├── Surface/          # one sub-folder per molecule, each containing a .gro file
├── Cyclodextrin/     # alpha|beta|gamma → grid_<n>/ variants
└── Catalyst/         # cata/ and catabm/ sub-folders

Set the path at startup with the TOPOLOGIES_PATH environment variable:

TOPOLOGIES_PATH=/path/to/topologies uvicorn main:app --reload

If the folder does not exist the library picker shows only the two built-in molecules (TMS and Silanol).

---

Running with Docker

docker compose up --build

Generated pore files are written to ./temp/ on the host via a volume mount.

Mounting a topology library

Uncomment and adjust the optional lines in docker-compose.yml:

volumes:
  - ./temp:/app/temp
  - /path/to/your/topologies:/topologies
environment:
  - TOPOLOGIES_PATH=/topologies

---

Project layout

main.py               FastAPI application — all API endpoints and generation logic
requirements.txt      Python dependencies
requirements-dev.txt  Additional dependencies for running tests
Dockerfile
docker-compose.yml
.dockerignore
templates/
  index.html          Single-page wizard UI (HTML + inline CSS)
static/
  app.js              Frontend state, molecule editor, 3-D viewer (3Dmol.js)
  logo.svg
tests/
  test_api.py         Integration tests (pytest + FastAPI TestClient)
temp/                 Generated pore files — gitignored, persisted via Docker volume

---

Running tests

pip install -r requirements-dev.txt
pytest tests/ -v

Tests cover the health endpoint, molecule template and preview endpoints, GRO round-trips, the topology library endpoints, and path-traversal safety. The full generation pipeline is not tested automatically because it is long-running; use the UI for end-to-end verification.

---

API reference

Method	Path	Description
GET	/	Serve the wizard UI
GET	/health	Health check — returns {"status":"ok"}
POST	/api/generate	Start an async pore generation job
GET	/api/jobs/{id}	Poll job status and progress
GET	/api/download/{id}	Download generated pore.zip
GET	/api/download/{id}/excel	Download property table as .xlsx
GET	/api/jobs/{id}/script	Download reproducible Python script
GET	/api/molecule/template	Fetch atom positions for a built-in molecule
POST	/api/molecule/preview	Reconstruct 3-D positions from internal coordinates
POST	/api/molecule/from-gro	Parse a .gro file into internal coordinates
POST	/api/molecule/gro	Export a molecule definition as a .gro file
GET	/api/library	List available molecules from the topology library
GET	/api/library/load	Load a molecule from the library by ID

---

Notes

• Single worker only. Job state is held in memory (JOBS dict). Do not run with multiple uvicorn workers or the job-polling endpoint will fail across processes.
• Temp cleanup. Old job directories under temp/ are never automatically removed. Prune them periodically on long-running deployments.