Molecular Modeling Toolkit

日本語版 README はこちら (README_ja.md)

A molecular modeling toolkit built on ASE (Atomic Simulation Environment) with Voronoi cell optimization. Reads TOML-based molecular definitions, builds supercells, optimizes molecular orientations via Voronoi IoU maximization, and exports structure files in QE / VASP / CIF formats.

Features

• Supercell Construction: Build ASE Atoms objects from TOML configuration with replication and substitution support
• Voronoi Optimization: Determine molecular orientations by maximizing Voronoi cell IoU via Euler angle grid search
• Structure File Export: Quantum ESPRESSO (qe.in), VASP (POSCAR, INCAR, KPOINTS), and CIF formats
• 3D Visualization: Generate Voronoi cell overlay images with matplotlib
• GUI: Interactive molecular modeling interface based on tkinter (ASE-GUI extension)

Setup

Requires Python 3.11 or later.

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

For development (testing and documentation):

pip install -e ".[dev]"

Usage

Run all commands from the repository root.

CLI — Pipeline Execution

python run.py

Pipeline flow:

1. Read input/input.toml + data/*.toml and build ASE Atoms
2. Optimize molecular orientations by maximizing Voronoi cell IoU
3. Save Voronoi cell overlay images to voronoi_pngs/
4. Export structure files to structure_out/

GUI — Interactive Interface

python molecular_modeling_gui.py

Documentation

• English Documentation (PDF)
• 日本語ドキュメント (PDF)

Tests

pytest                             # all tests
pytest -m "not slow"               # skip slow tests
pytest tests/test_voronoi_geom.py  # single file

Repository Structure

molecular_modeling/              <- repository root
├── README.md                    <- this file (English)
├── README_ja.md                 <- Japanese README
├── LICENSE                      <- LGPL-2.1-or-later
├── .github/workflows/           <- CI (GitHub Actions)
├── pyproject.toml               <- dependencies and build config
├── run.py                       <- CLI entry point
├── molecular_modeling_gui.py    <- GUI entry point
├── source/                      <- main package (= molecular_modeling)
│   ├── main.py                  <- main pipeline
│   ├── voronoi_geom.py          <- Voronoi geometry
│   ├── build_system_from_toml.py
│   ├── optimize_voronoi_overlap.py
│   ├── render_voronoi_overlays.py
│   ├── write_structure.py
│   └── gui/                     <- GUI modules
├── input/                       <- runtime config (input.toml)
├── data/                        <- molecule definitions (*.toml)
├── tests/                       <- test suite
├── docs/                        <- documentation (Sphinx / PDF)
├── structure_out/               <- output: structure files
└── voronoi_pngs/                <- output: visualization images

License

This project is licensed under the GNU Lesser General Public License v2.1 or later (LGPL-2.1-or-later).

See LICENSE for details.