meown 1.1.4

Muon Site Prediction Engine — P-UEP framework with physics-informed inference

Meown — Muon Site Prediction Engine

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 and ensure the "Desktop development with C++" workload is selected.

Step 1 — Create a virtual environment (recommended)

Isolate dependencies to avoid conflicts:

# 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

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):

pip install torch --index-url https://download.pytorch.org/whl/cpu

CUDA 11.8 (NVIDIA GPU):

pip install torch --index-url https://download.pytorch.org/whl/cu118

CUDA 12.1 (NVIDIA GPU, newer):

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)

pip install -e .

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

With GUI support (recommended for desktop use)

pip install -e ".[gui]"

Adds PyQt6 and pyqtgraph for the interactive 3D workspace.

With development tools

pip install -e ".[dev]"

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

Full install (everything)

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

Step 5 — Verify installation

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

Expected output:

Meown ready

Step 6 — Run a quick test

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
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

python gui/main_window.py

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

Python API

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

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:

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 as composable dataclasses:

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.