Metadata-Version: 2.4
Name: meown
Version: 1.0.7
Summary: Muon Site Prediction Engine — P-UEP framework with physics-informed inference
Author: QM Labs
Author-email: Sayan Ghosh <sayangeophysics@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/your-org/meown
Project-URL: Bug Tracker, https://github.com/your-org/meown/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
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
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: torch>=2.0
Requires-Dist: pymatgen>=2023.1
Requires-Dist: spglib>=2.0
Provides-Extra: gui
Requires-Dist: PyQt6>=6.4; extra == "gui"
Requires-Dist: pyqtgraph>=0.13; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file
Dynamic: requires-python

<p align="center">
  <img src="meown_logo.ico" alt="Meown Logo" width="128">
</p>

# Meown — Muon Site Prediction Engine

[![Python](https://img.shields.io/badge/python-3.9%2B-blue?logo=python)](https://www.python.org/)
[![PyTorch](https://img.shields.io/badge/pytorch-2.0%2B-orange?logo=pytorch)](https://pytorch.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-windows%20%7C%20linux-lightgrey)]()

A research-grade **Muon Site Prediction Engine** using a Polarizable Unperturbed Electrostatic Potential (P-UEP) framework with physics-informed inference to identify high-probability muon stopping sites in crystal structures.

---

## Features

- **Physics Inference Engine** — high-speed potential energy surface (PES) exploration using P-UEP
- **Advanced Potentials** — Hartree, exchange-correlation, polarization, Morse corrections
- **Ultra-Precision Relaxation** — symmetry-aware optimization with basin-hopping + L-BFGS
- **Interactive GUI** — PyQt6 workspace with 3D crystal visualization and energy landscapes
- **Universal Confidence Metric** — physics-grounded scoring integrating energy, geometry, and dynamical stability
- **Batch Processing** — process multiple CIF files from the API
- **Export Formats** — CSV, JSON, PDF reports of predicted muon sites

---

## Installation

### Prerequisites

- **Python 3.9–3.12** (Python 3.13+ is not yet supported by PyTorch)
- **pip** (latest — `python -m pip install --upgrade pip`)
- **Git** (optional — for cloning the repository)
- **CUDA-capable GPU** (optional — enables GPU-accelerated inference)

> **Windows users**: If you get build errors during installation, install [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) and ensure the "Desktop development with C++" workload is selected.

### Step 1 — Create a virtual environment (recommended)

Isolate dependencies to avoid conflicts:

```bash
# Windows (Command Prompt)
python -m venv venv
venv\Scripts\activate

# Windows (PowerShell)
python -m venv venv
.\venv\Scripts\Activate.ps1

# Linux / macOS
python3 -m venv venv
source venv/bin/activate
```

Your shell prompt should now show `(venv)`.

### Step 2 — Clone the repository

```bash
git clone https://github.com/your-org/meown.git
cd meown
```

Or download and unzip the source manually, then `cd` into the `meown/` directory.

### Step 3 — Install PyTorch (choose your platform)

PyTorch is the core deep-learning backend. Install the correct version for your system:

**CPU-only (works on any system):**
```bash
pip install torch --index-url https://download.pytorch.org/whl/cpu
```

**CUDA 11.8 (NVIDIA GPU):**
```bash
pip install torch --index-url https://download.pytorch.org/whl/cu118
```

**CUDA 12.1 (NVIDIA GPU, newer):**
```bash
pip install torch --index-url https://download.pytorch.org/whl/cu121
```

> If unsure, start with CPU. You can reinstall with CUDA later — no changes to Meown needed.

### Step 4 — Install Meown

#### Basic install (engine only, no GUI)

```bash
pip install -e .
```

This installs the core dependencies: NumPy, SciPy, PyTorch, pymatgen, spglib.

#### With GUI support (recommended for desktop use)

```bash
pip install -e ".[gui]"
```

Adds PyQt6 and pyqtgraph for the interactive 3D workspace.

#### With development tools

```bash
pip install -e ".[dev]"
```

Adds pytest, black, mypy, and ruff for testing and linting.

#### Full install (everything)

```bash
pip install -e ".[gui,dev]"
```

### Step 5 — Verify installation

```bash
python -c "from src.api import MuonSiteEngine; print('Meown ready')"
```

Expected output:
```
Meown ready
```

### Step 6 — Run a quick test

```bash
python -c "
from src.api import MuonSiteEngine
e = MuonSiteEngine()
e.load_structure('data/cifs/SrTiO3.cif')
sites = e.find_sites(n_sites=2, inference_steps=50)
for s in sites:
    print(f'  Site at {s.frac_coords}, energy={s.total_energy:.3f} eV')
print('OK')
"
```

This loads `SrTiO3.cif`, runs 50 inference steps, and prints the top 2 predicted muon sites.

### Troubleshooting

| Problem | Solution |
|---|---|
| `pip install` fails with MSVC error | Install [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) |
| `ImportError: No module named torch` | You skipped Step 3 — install PyTorch first, then Meown |
| `ImportError: No module named PyQt6` | Install the GUI extras: `pip install -e ".[gui]"` |
| `OSError: [WinError 126]` or DLL errors | Ensure no conflicting torch versions; try `pip install torch --force-reinstall` |
| Model loss shows `nan` | This is expected with very few steps. Increase `inference_steps` (≥200) for real usage. |
| GUI fails to open | Run from a desktop environment (not SSH). If it still fails, try `python gui/main_window.py --debug` |
| GPU not detected | Run `python -c "import torch; print(torch.cuda.is_available())"`. If `False`, reinstall PyTorch with the correct CUDA index URL. |

---

## Quick Start

### GUI

```bash
python gui/main_window.py
```

Load a CIF file from `data/cifs/`, run the engine, and explore predicted muon sites in 3D.

### Python API

```python
from src.api import MuonSiteEngine

engine = MuonSiteEngine()

# Load a crystal structure
crystal = engine.load_structure("data/cifs/SrTiO3.cif")
print(f"Loaded {crystal.formula} ({crystal.space_group})")

# Find muon sites
sites = engine.find_sites(n_sites=5, inference_steps=300)

print(f"Found {len(sites)} candidate sites")
for site in sites:
    print(f"  Site at {site.frac_coords}: {site.total_energy:.3f} eV, "
          f"confidence={site.confidence:.1f}")
```

### Batch processing

```python
from src.api import MuonSiteEngine
from pathlib import Path

engine = MuonSiteEngine()

cif_dir = Path("data/cifs")
for cif_file in cif_dir.glob("*.cif"):
    crystal = engine.load_structure(str(cif_file))
    sites = engine.find_sites(n_sites=2, inference_steps=300)
    print(f"{cif_file.name} ({crystal.formula}): {len(sites)} sites")
    for site in sites:
        print(f"  {site.frac_coords}  {site.total_energy:.3f} eV")
```

---

## GUI

Launch the interactive workspace:

```bash
python gui/main_window.py
```

Features:
- **3D Crystal Viewer** — rotate, zoom, inspect atomic positions
- **Energy Landscape** — 2D slices and 3D surfaces of the P-UEP potential
- **Site Table** — ranked list of predicted muon sites with scores
- **Export Panel** — save results to CSV, JSON, or PDF

---

## Configuration

All physics parameters are in [`src/config.py`](src/config.py) as composable dataclasses:

```python
from src.config import MuonSiteConfig, OptimizationConfig

config = MuonSiteConfig(
    optimization=OptimizationConfig(
        n_random_starts=100,
        n_basin_hops=50,
    )
)
```

| Config Class | Purpose |
|---|---|
| `MuonSiteConfig` | Master config combining all sub-configs |
| `CorrelationConfig` | Correlation barrier strength and decay |
| `ElectrostaticsConfig` | Electrostatic field smoothing and screening |
| `OptimizationConfig` | Random starts, basin-hopping, L-BFGS tolerance |
| `ValidationConfig` | Minimum distance, energy thresholds |
| `QuantumConfig` | Zero-point energy (ZPE) and Hessian settings |

---

## Project Structure

```
meown/
├── src/                    # Core physics engine
│   ├── api.py              # Public API — MuonSiteEngine
│   ├── config.py           # Physics parameters & configuration
│   ├── physics.py          # P-UEP engine
│   ├── optimization.py     # Symmetry-aware site optimization
│   ├── implantation.py     # Muon implantation physics
│   ├── symmetry.py         # Crystal symmetry utilities
│   ├── loader.py           # CIF file loading
│   ├── exporter.py         # CSV/JSON/PDF export
│   ├── validation.py       # Result validation
│   ├── validator.py        # Site validator
│   └── qe_potential.py     # Quantum Espresso integration
│
├── gui/                    # Graphical user interface (PyQt6)
│   ├── main_window.py      # Main application window
│   └── visualizer.py       # 3D crystal & energy landscape visualization
│
├── meown_logo.ico          # Application icon (used by GUI)
├── data/                   # Sample crystal structures (CIF)
│   └── cifs/               # CIF collection (SrTiO3, MnSi, Cu, etc.)
│
├── tests/                  # Test suite
│
├── pyproject.toml           # Modern Python packaging (PEP 621)
├── setup.py                 # Legacy setup script
├── requirements.txt         # Python dependencies
├── meown_logo.ico           # Application icon
├── README.md
├── LICENSE                  # MIT
└── CONTRIBUTING.md
```

---

## Input Data Format

Crystal structures should be provided in **CIF** format. Sample CIFs are in `data/cifs/`.

---

## Output

| Format | Description |
|---|---|
| CSV | Ranked list of muon sites with coordinates and energies |
| JSONL | Per-site physics breakdown |
| PDF | Full report with visualizations (GUI only) |

---



## License

MIT License — see [LICENSE](LICENSE).
