Metadata-Version: 2.4
Name: OgreWulff
Version: 0.2.0
Summary: A Python package for generating and plotting Wulff shapes from surface energy data
Author-email: Zefeng Cai <caizefeng18@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://github.com/caizefeng/OgreWulff
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymatgen<=2025.6.14
Requires-Dist: numpy>=1.20.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: ase>=3.22.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: wulffpack>=1.0.0
Dynamic: license-file

# OgreWulff

A Python package for generating and plotting Wulff shapes from surface energy data, based on WulffPack.

## Installation

### From source

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

### From PyPI

```bash
pip install OgreWulff
```

## Usage

### Wulff shape from surface energies

```python
from OgreWulff import plot_wulff
from ase.build import bulk

# Define surface energies (in mJ/m^2)
surface_energies = {
    (1, 0, 0): 100.0,
    (1, 1, 0): 85.0,
    (1, 1, 1): 75.0
}

conv = bulk('Cu', 'fcc', a=3.6, cubic=True)

# Interactive HTML (Plotly)
plot_wulff(surface_energies=surface_energies, structure=conv, output_file='cu_wulff.html', interactive=True, legend=True)

# Static PNG (matplotlib)
plot_wulff(surface_energies=surface_energies, structure=conv, output_file='cu_wulff.png', interactive=False, legend=True)
```

### BFDH morphology (no surface energies needed)

The Bravais–Friedel–Donnay–Harker (BFDH) model predicts crystal morphology purely from lattice geometry: facets with larger interplanar spacings grow slower and therefore dominate the crystal habit.

```python
from OgreWulff import plot_wulff_BFDH
from ase.build import bulk

conv = bulk('Cu', 'fcc', a=3.6, cubic=True)

particle = plot_wulff_BFDH(structure=conv, output_file='cu_wulff_bfdh.png', interactive=True, legend=True)
```

## Features

- **Wulff shape construction**: Create equilibrium crystal shapes from surface energies
- **Static plotting**: Generate high-quality PNG figures using matplotlib
- **Interactive plotting**: Create rotatable 3D visualizations with Plotly (optional)
- **Facet filtering**: Control which facets to include using `max_index` parameter
- **Customizable appearance**: Control viewing angles, colors, legends, and more

## API Reference

### plot_wulff

Main function for plotting Wulff shapes.

**Parameters:**
- `surface_energies` (dict): Dictionary mapping Miller index tuples to surface energies (in mJ/m^2)
- `structure`: ASE Atoms or pymatgen Structure for the conventional cell
- `output_file` (str): Path to save the plot (optional, defaults to 'wulff_shape.png' or 'wulff_shape.html')
- `legend` (bool): Whether to show legend (default: False)
- `elevation` (int): Viewing elevation angle in degrees (default: 30)
- `azimuth` (int): Viewing azimuth angle in degrees (default: -60)
- `use_common_viewing_angle` (bool): Use elevation=30 and azimuth=30 (default: False)
- `no_title` (bool): Hide the title (default: False)
- `title` (str): Custom plot title (optional)
- `max_index` (int or dict): Filter facets by Miller index magnitude (optional)
- `interactive` (bool): Use Plotly for interactive visualization (default: False)
- `natoms` (int): Number of atoms for Wulff construction (default: 1000)
- `symprec` (float): Symmetry precision for spglib (default: 0.01)
- `tol` (float): Numerical tolerance (default: 1e-5)

**Returns:**
- `OgreSingleCrystal`: The Wulff shape particle object

## Dependencies

- numpy
- matplotlib
- plotly
- ase
- pymatgen
- wulffpack
- tqdm

## License

MIT License
