pymultibinit 0.2.0__tar.gz

pymultibinit-0.2.0/.gitignore

@@ -0,0 +1,149 @@
+doc/refs/*.pdf
+
+
+uv.lock
+
+# vim files
+*.swp
+
+# Latex
+*.aux
+
+
+# file for AI IDE
+# kiro
+.kiro/
+# cline
+.cline
+# roo coder
+.roo
+AGENTS.md
+CLAUDE.md
+.opencode
+openspec
+
+
+
+# xyz files
+
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# numpy results
+*.npy
+
+# png files
+
+# C extensions
+*.so
+*.a
+
+# Fortran extensions
+*.fpp
+*.mod
+*.o
+
+# F90wrap files
+*.plist
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg-info/*
+.installed.cfg
+*.egg
+
+# temporary files
+temp/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/

pymultibinit-0.2.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to pymultibinit will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-12-07
+
+### Added
+- **Configuration file support**: New way to initialize potentials from config files
+  - New `config` module with `MultibinitConfig` class for parsing configuration files
+  - New class methods:
+    - `MultibinitPotential.from_config_file()`: Initialize potential from config file
+    - `MultibinitCalculator.from_config_file()`: Initialize ASE calculator from config file
+  - Supports multiple formats:
+    - Simple format: `key: value` pairs
+    - INI format: Sections with `[section]` headers
+    - Both `:` and `=` separators supported
+  - Automatic path resolution: Relative paths resolved relative to config file directory
+  - Comprehensive test suite with 14 tests covering all config scenarios
+  - Example config files in `examples/` directory
+  - Complete documentation in `docs/CONFIG_FILE_USAGE.md`
+
+- **Supercell structure export**: Ability to extract and export the MULTIBINIT internal supercell structure
+  - New methods on `MultibinitPotential`:
+    - `get_supercell_structure()`: Get reference structure as numpy arrays
+    - `export_supercell_to_ase()`: Export as ASE Atoms object
+    - `export_supercell_to_file()`: Export to CIF, VASP, XYZ, etc.
+  - Automatic unit conversion (Angstrom for ASE compatibility)
+  - Test suite with 8 tests covering all export scenarios
+  - Complete documentation in `docs/SUPERCELL_EXPORT.md`
+
+- **Automatic atom matching with PBC handling**: `MultibinitPotential` now automatically matches atom ordering between input structures and MULTIBINIT's internal reference structure
+  - New `atom_matching` module with core matching utilities
+  - Enabled by default with `auto_match_atoms=True` parameter
+  - Persistent mapping: computed once on first evaluation, reused for all subsequent calls
+  - Automatic force remapping: forces always returned in input atom order
+  - **Optimization**: Identity mapping detection to skip unnecessary force remapping when no reordering or PBC shifts needed
+  - Full PBC support using minimum image convention
+  - New utility functions:
+    - `is_identity_mapping_no_pbc_shift()`: Check if mapping is trivial
+  - New methods on `MultibinitPotential`:
+    - `set_reference_structure()`: Explicitly set reference structure for matching
+    - `compute_atom_mapping()`: Compute and store atom mapping
+    - `get_atom_mapping()`: Retrieve stored mapping
+    - `clear_atom_mapping()`: Reset stored mapping
+  - Comprehensive test suite with 12 tests covering all matching scenarios (including PBC shift detection)
+  - Complete documentation in `docs/ATOM_MATCHING_USAGE.md`
+
+### Changed
+- `MultibinitPotential.evaluate()` now automatically handles atom reordering when `auto_match_atoms=True` (default)
+- Forces are now automatically mapped back to input atom order for user convenience
+- **Performance improvement**: Force remapping is skipped when mapping is identity (no reordering) and no PBC shifts are needed
+
+### Documentation
+- Added `docs/SUPERCELL_EXPORT.md`: Complete guide for exporting supercell structures with 6 detailed examples
+- Added `docs/CONFIG_FILE_USAGE.md`: Complete guide for configuration file usage
+- Added `examples/multibinit_simple.conf`: Minimal simple format example
+- Added `examples/multibinit_ini.conf`: Full INI format example
+- Added `docs/ATOM_MATCHING_USAGE.md`: Complete usage guide with examples
+- Added `docs/fortran/ATOM_ORDERING_AND_PBC.md`: Technical details on MULTIBINIT's internal atom handling
+- Added `docs/fortran/DIAGRAMS.md`: Visual diagrams for supercell construction and displacement computation
+- Added `docs/DEVELOPER_GUIDE.md`: Complete developer guide for extending pymultibinit
+- Added `docs/api/API_REFERENCE.md`: Full API reference documentation
+
+## [0.1.0] - Initial Release
+
+### Added
+- Initial Python wrapper for MULTIBINIT C API
+- Basic `MultibinitPotential` class for energy and force evaluation
+- ASE calculator interface
+- Basic tests and examples

pymultibinit-0.2.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: pymultibinit
+Version: 0.2.0
+Summary: Add your description here
+Author-email: Xu He <x.he@uliege.be>
+Requires-Python: >=3.10
+Requires-Dist: ase>=3.26.0
+Requires-Dist: cffi>=2.0.0
+Requires-Dist: numpy>=2.2.6
+Description-Content-Type: text/markdown
+
+# pymultibinit - Python Interface to MULTIBINIT
+
+Python bindings for ABINIT's MULTIBINIT effective potential library.
+
+## Installation
+
+```bash
+# 1. Build ABINIT library
+cd abinit
+rm -rf build && mkdir build && cd build
+CC=mpicc FC=mpif90 cmake -C ~/.abinit/build/shared.cmake ..
+make -j8
+
+# 2. Set library path (choose one):
+
+# Option A: LIBABINIT_PATH (recommended)
+export LIBABINIT_PATH=/path/to/abinit/build/src/98_main/libabinit.dylib  # macOS
+export LIBABINIT_PATH=/path/to/abinit/build/src/98_main/libabinit.so     # Linux
+
+# Option B: Add to LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS)
+export LD_LIBRARY_PATH=/path/to/abinit/build/src/98_main:$LD_LIBRARY_PATH
+
+# Add to ~/.bashrc or ~/.zshrc for persistence
+
+# 3. Install Python package
+pip install pymultibinit
+# or: pip install -e .
+```
+
+## Quick Start
+
+```python
+from pymultibinit import MultibinitCalculator
+from ase import Atoms
+from ase.optimize import BFGS
+
+# Load from config file (recommended)
+calc = MultibinitCalculator.from_config_file("multibinit.conf")
+
+# Or from parameters
+calc = MultibinitCalculator.from_params(
+    ddb_file="system_DDB",
+    sys_file="system.xml",
+    ncell=(2, 2, 2),
+    ngqpt=(4, 4, 4)
+)
+
+# Build supercell (must match ncell!)
+unit_cell = Atoms('BaTiO3', 
+                 scaled_positions=[[0,0,0], [0.5,0.5,0.5], 
+                                   [0.5,0,0.5], [0,0.5,0.5], [0.5,0.5,0]],
+                 cell=[4.0, 4.0, 4.0], pbc=True)
+atoms = unit_cell * (2, 2, 2)  # Match ncell=(2,2,2)
+atoms.calc = calc
+
+# Run calculation
+energy = atoms.get_potential_energy()  # eV
+forces = atoms.get_forces()            # eV/Angstrom
+stress = atoms.get_stress()            # eV/Angstrom^3
+
+# Optimize structure
+opt = BFGS(atoms)
+opt.run(fmax=0.01)
+```
+
+## Configuration File
+
+Create `multibinit.conf`:
+
+```ini
+# Required
+ddb_file: system_DDB
+sys_file: system.xml
+ncell: 2 2 2
+
+# Optional
+ngqpt: 4 4 4
+dipdip: 1
+```
+
+## API Reference
+
+### `MultibinitCalculator` (ASE interface)
+
+```python
+# From config file (recommended)
+calc = MultibinitCalculator.from_config_file("config.conf")
+
+# From parameters
+calc = MultibinitCalculator.from_params(
+    ddb_file="system_DDB",
+    sys_file="system.xml",
+    ncell=(2, 2, 2),
+    ngqpt=(4, 4, 4),
+    dipdip=1
+)
+
+# From .abi file
+calc = MultibinitCalculator.from_abi("input.abi")
+```
+
+### `MultibinitPotential` (Low-level interface)
+
+```python
+from pymultibinit import MultibinitPotential
+import numpy as np
+
+pot = MultibinitPotential.from_params(
+    ddb_file="system_DDB",
+    sys_file="system.xml",
+    ncell=(2, 2, 2)
+)
+
+# Evaluate (Angstrom/eV by default)
+positions = np.array([[0, 0, 0], [2.0, 0, 0]])  # Angstrom
+lattice = np.array([[4, 0, 0], [0, 4, 0], [0, 0, 4]])  # Angstrom
+energy, forces, stress = pot.evaluate(positions, lattice)
+
+# Export structures
+pot.export_supercell_to_file('supercell.cif')  # Export to file
+atoms = pot.export_supercell_to_ase()           # Get ASE Atoms object
+structure = pot.get_supercell_structure()       # Get raw arrays
+
+pot.free()
+```
+
+## Exporting Structures
+
+### Export Reference/Supercell Structure
+
+```python
+
+```
+
+### Command-Line Tools
+
+```bash
+# Export MULTIBINIT reference structure
+mbtools export-ref config.conf output.cif
+
+```
+
+## Important Notes
+
+### Supercell Size
+
+**Your structure must match the `ncell` parameter!**
+
+```python
+# Config: ncell: 2 2 2
+calc = MultibinitCalculator.from_config_file("config.conf")
+
+# ✓ CORRECT
+atoms = unit_cell * (2, 2, 2)  # Match ncell
+
+# ✗ WRONG - will fail with "status 3" error
+atoms = unit_cell  # Size mismatch
+```
+
+### Library Not Found?
+
+If you get "Could not find libabinit":
+
+```bash
+# Option 1: Set LIBABINIT_PATH
+export LIBABINIT_PATH=/full/path/to/libabinit.dylib
+
+# Option 2: Add to library search path
+export LD_LIBRARY_PATH=/path/to/dir/containing/libabinit:$LD_LIBRARY_PATH
+
+# Verify
+python -c "from pymultibinit.utils import find_library; print(find_library())"
+```
+
+### Unit Conventions
+
+| Quantity | Python API | Internal |
+|----------|------------|----------|
+| Length   | Angstrom   | Bohr     |
+| Energy   | eV         | Hartree  |
+| Force    | eV/Å       | Ha/Bohr  |
+
+Conversions are automatic.
+
+## Examples
+
+```bash
+cd pymultibinit/examples
+python simple_example.py
+```
+
+## License
+
+GPL v3 (same as ABINIT)
+
+## Citation
+
+- ABINIT: https://www.abinit.org
+- MULTIBINIT: https://docs.abinit.org/guide/multibinit/

pymultibinit-0.2.0/README.md

@@ -0,0 +1,199 @@
+# pymultibinit - Python Interface to MULTIBINIT
+
+Python bindings for ABINIT's MULTIBINIT effective potential library.
+
+## Installation
+
+```bash
+# 1. Build ABINIT library
+cd abinit
+rm -rf build && mkdir build && cd build
+CC=mpicc FC=mpif90 cmake -C ~/.abinit/build/shared.cmake ..
+make -j8
+
+# 2. Set library path (choose one):
+
+# Option A: LIBABINIT_PATH (recommended)
+export LIBABINIT_PATH=/path/to/abinit/build/src/98_main/libabinit.dylib  # macOS
+export LIBABINIT_PATH=/path/to/abinit/build/src/98_main/libabinit.so     # Linux
+
+# Option B: Add to LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS)
+export LD_LIBRARY_PATH=/path/to/abinit/build/src/98_main:$LD_LIBRARY_PATH
+
+# Add to ~/.bashrc or ~/.zshrc for persistence
+
+# 3. Install Python package
+pip install pymultibinit
+# or: pip install -e .
+```
+
+## Quick Start
+
+```python
+from pymultibinit import MultibinitCalculator
+from ase import Atoms
+from ase.optimize import BFGS
+
+# Load from config file (recommended)
+calc = MultibinitCalculator.from_config_file("multibinit.conf")
+
+# Or from parameters
+calc = MultibinitCalculator.from_params(
+    ddb_file="system_DDB",
+    sys_file="system.xml",
+    ncell=(2, 2, 2),
+    ngqpt=(4, 4, 4)
+)
+
+# Build supercell (must match ncell!)
+unit_cell = Atoms('BaTiO3', 
+                 scaled_positions=[[0,0,0], [0.5,0.5,0.5], 
+                                   [0.5,0,0.5], [0,0.5,0.5], [0.5,0.5,0]],
+                 cell=[4.0, 4.0, 4.0], pbc=True)
+atoms = unit_cell * (2, 2, 2)  # Match ncell=(2,2,2)
+atoms.calc = calc
+
+# Run calculation
+energy = atoms.get_potential_energy()  # eV
+forces = atoms.get_forces()            # eV/Angstrom
+stress = atoms.get_stress()            # eV/Angstrom^3
+
+# Optimize structure
+opt = BFGS(atoms)
+opt.run(fmax=0.01)
+```
+
+## Configuration File
+
+Create `multibinit.conf`:
+
+```ini
+# Required
+ddb_file: system_DDB
+sys_file: system.xml
+ncell: 2 2 2
+
+# Optional
+ngqpt: 4 4 4
+dipdip: 1
+```
+
+## API Reference
+
+### `MultibinitCalculator` (ASE interface)
+
+```python
+# From config file (recommended)
+calc = MultibinitCalculator.from_config_file("config.conf")
+
+# From parameters
+calc = MultibinitCalculator.from_params(
+    ddb_file="system_DDB",
+    sys_file="system.xml",
+    ncell=(2, 2, 2),
+    ngqpt=(4, 4, 4),
+    dipdip=1
+)
+
+# From .abi file
+calc = MultibinitCalculator.from_abi("input.abi")
+```
+
+### `MultibinitPotential` (Low-level interface)
+
+```python
+from pymultibinit import MultibinitPotential
+import numpy as np
+
+pot = MultibinitPotential.from_params(
+    ddb_file="system_DDB",
+    sys_file="system.xml",
+    ncell=(2, 2, 2)
+)
+
+# Evaluate (Angstrom/eV by default)
+positions = np.array([[0, 0, 0], [2.0, 0, 0]])  # Angstrom
+lattice = np.array([[4, 0, 0], [0, 4, 0], [0, 0, 4]])  # Angstrom
+energy, forces, stress = pot.evaluate(positions, lattice)
+
+# Export structures
+pot.export_supercell_to_file('supercell.cif')  # Export to file
+atoms = pot.export_supercell_to_ase()           # Get ASE Atoms object
+structure = pot.get_supercell_structure()       # Get raw arrays
+
+pot.free()
+```
+
+## Exporting Structures
+
+### Export Reference/Supercell Structure
+
+```python
+
+```
+
+### Command-Line Tools
+
+```bash
+# Export MULTIBINIT reference structure
+mbtools export-ref config.conf output.cif
+
+```
+
+## Important Notes
+
+### Supercell Size
+
+**Your structure must match the `ncell` parameter!**
+
+```python
+# Config: ncell: 2 2 2
+calc = MultibinitCalculator.from_config_file("config.conf")
+
+# ✓ CORRECT
+atoms = unit_cell * (2, 2, 2)  # Match ncell
+
+# ✗ WRONG - will fail with "status 3" error
+atoms = unit_cell  # Size mismatch
+```
+
+### Library Not Found?
+
+If you get "Could not find libabinit":
+
+```bash
+# Option 1: Set LIBABINIT_PATH
+export LIBABINIT_PATH=/full/path/to/libabinit.dylib
+
+# Option 2: Add to library search path
+export LD_LIBRARY_PATH=/path/to/dir/containing/libabinit:$LD_LIBRARY_PATH
+
+# Verify
+python -c "from pymultibinit.utils import find_library; print(find_library())"
+```
+
+### Unit Conventions
+
+| Quantity | Python API | Internal |
+|----------|------------|----------|
+| Length   | Angstrom   | Bohr     |
+| Energy   | eV         | Hartree  |
+| Force    | eV/Å       | Ha/Bohr  |
+
+Conversions are automatic.
+
+## Examples
+
+```bash
+cd pymultibinit/examples
+python simple_example.py
+```
+
+## License
+
+GPL v3 (same as ABINIT)
+
+## Citation
+
+- ABINIT: https://www.abinit.org
+- MULTIBINIT: https://docs.abinit.org/guide/multibinit/