OgreWulff

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

Installation

From source

pip install -e .

From PyPI

pip install OgreWulff

Usage

Wulff shape from surface energies

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.

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