### Download and run WulffPack tests

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/get_started/installation.md

After installing via pip, run these commands to download the test suite and execute it, verifying the installation.

```bash
curl -O https://wulffpack.materialsmodeling.org/tests.zip
unzip tests.zip
python3 tests/main.py
```

--------------------------------

### Install WulffPack using pip

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/get_started/installation.md

Use this command for the simplest installation of WulffPack. Ensure pip is available in your environment.

```bash
pip install wulffpack
```

--------------------------------

### Install WulffPack from source

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/get_started/installation.md

After cloning the repository, navigate to the root directory and use this command to install WulffPack for the current user. This method is for obtaining the latest code.

```bash
cd wulffpack
python3 setup.py install --user
```

--------------------------------

### Run WulffPack tests after cloning

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/get_started/installation.md

After installing WulffPack from the cloned repository, execute this command in the root directory to ensure the installation was successful.

```bash
python3 tests/main.py
```

--------------------------------

### Install WulffPack using pip

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/README.rst

Install WulffPack using pip for Python 3. The --user flag installs the package in the user's home directory.

```bash
pip3 install wulffpack --user
```

--------------------------------

### Specify Parameters for Particle Construction

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Define surface energies, primitive structure, and number of atoms. This setup is required before creating any particle instances.

```python
from wulffpack import (
    SingleCrystal,
    Decahedron,
    Icosahedron)
from ase.build import bulk


# Specify parameters
prim = bulk('Au',
            crystalstructure='fcc',
            a=4.08)
surface_energies = {(1, 0, 0): 0.066,
                    (1, 1, 1): 0.06}
twin_energy = 1e-3
natoms = 1000
```

--------------------------------

### WulffPack Shape Comparison Setup

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Sets up SingleCrystal, Decahedron, and Icosahedron objects with specified surface energies, twin energy, and primitive structure. This code block is essential for running subsequent comparisons.

```python
from wulffpack import (
    SingleCrystal,
    Decahedron,
    Icosahedron)
from ase.build import bulk


# Specify parameters
prim = bulk('Au',
            crystalstructure='fcc',
            a=4.08)
surface_energies = {(1, 0, 0): 0.066,
                    (1, 1, 1): 0.06}
twin_energy = 1e-3
natoms = 1000

# Create one particle per type
oh = SingleCrystal(surface_energies,
                   primitive_structure=prim,
                   natoms=natoms)
dh = Decahedron(surface_energies,
                twin_energy=twin_energy,
                primitive_structure=prim,
                natoms=natoms)
ih = Icosahedron(surface_energies,
                 twin_energy=twin_energy,
                 primitive_structure=prim,
                 natoms=natoms)

# Compare volumes
print('Volume (sanity check):')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    volume = particle.volume
    print('{}: {:.2f}'.format(name, volume))
print()

# Compare areas
print('Total surface area (excluding twin boundaries):')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    area = particle.area
    print('{}: {:.2f}'.format(name, area))
print()

# Compare fractions of {100} facets
print('Fraction of {100} facets:')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    fraction = particle.facet_fractions.get((1, 0, 0), 0.)
    print('{}: {:.4f}'.format(name, fraction))
print()

# Compare total surface energies
print('Total surface energy (including twin energy):')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    energy = particle.surface_energy
    print('{}: {:.2f}'.format(name, energy))
print()
```

--------------------------------

### Install WulffPack using python3 -m pip

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/README.rst

Alternatively, install WulffPack using the python3 -m pip command. This method is useful if pip is not directly accessible in your PATH.

```bash
python3 -m pip install wulffpack --user
```

--------------------------------

### Create and Visualize Single Crystal Wulff Shape

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/index.md

This snippet demonstrates how to create a single-crystal Wulff shape using provided surface energies and visualize/save the resulting particle. Ensure 'wulffpack' and 'ase' are installed.

```python
from wulffpack import SingleCrystal
from ase.io import write
surface_energies = {(1, 1, 1): 1.0, (1, 0, 0): 1.2}
particle = SingleCrystal(surface_energies)
particle.view()
write('atoms.xyz', particle)
```

--------------------------------

### Clone WulffPack repository

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/get_started/installation.md

Clone the WulffPack repository to obtain the latest development version. This requires Git to be installed.

```bash
git clone git@gitlab.com:materials-modeling/wulffpack.git
```

--------------------------------

### Plotting Different Particle Types

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/icosahedron.md

Demonstrates how to plot a SingleCrystal, Decahedron, and Icosahedron particle in the same figure using matplotlib. Ensure matplotlib is installed for visualization.

```python
>>> from wulffpack import SingleCrystal, Decahedron, Icosahedron
>>> import matplotlib.pyplot as plt
>>> from mpl_toolkits.mplot3d import Axes3D
>>> 
>>> surface_energies = {(1, 1, 1): 1.0,
...                     (1, 0, 0): 1.1,
...                     (1, 1, 0): 1.15,
...                     (3, 2, 1): 1.15}
>>> twin_energy = 0.05
>>> 
>>> fig = plt.figure(figsize=(3*4.0, 4.0))
>>> ax = fig.add_subplot(131, projection='3d')
>>> particle = SingleCrystal(surface_energies)
>>> particle.make_plot(ax)
>>> 
>>> ax = fig.add_subplot(132, projection='3d')
>>> particle = Decahedron(surface_energies,
...                       twin_energy=0.05)
>>> particle.make_plot(ax)
>>> 
>>> ax = fig.add_subplot(133, projection='3d')
>>> particle = Icosahedron(surface_energies,
...                        twin_energy=0.05)
>>> particle.make_plot(ax)
>>> 
>>> plt.subplots_adjust(top=1, bottom=0, left=0,
...                     right=1, wspace=0, hspace=0)
>>> plt.savefig('particles.png')
```

--------------------------------

### Initialize SingleCrystal Object

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/single_crystal.md

Demonstrates how to initialize a SingleCrystal object with surface energies and a primitive structure. The resulting particle's atomic structure can be viewed and written to a file.

```python
from wulffpack import SingleCrystal
from ase.build import bulk
from ase.io import write
surface_energies = {(1, 1, 0): 1.0, (1, 0, 0): 1.08}
prim = bulk('W', a=3.16, crystalstructure='bcc')
particle = SingleCrystal(surface_energies, prim)
particle.view()
write('single_crystal.xyz', particle.atoms) # Writes atomic structure to file
```

--------------------------------

### Construct Particle on Substrate (Winterbottom)

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/basic_usage.md

Constructs a particle on a substrate using the Winterbottom construction. This requires generalized surface energy, interface direction, and surface energies.

```python
generalized_surface_energy = -0.2
particle = Winterbottom(surface_energies=surface_energies,
                        interface_direction=(1, 1, 1),
                        interface_energy=generalized_surface_energy)
particle.view()
write('winterbottom.xyz', particle.atoms)
```

--------------------------------

### Construct Winterbottom Particle (Strongly Wetting)

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Demonstrates a strongly wetting case for the Winterbottom construction where the interface energy is negative, causing the particle to spread on the substrate.

```python
from wulffpack import Winterbottom
from ase.build import bulk
from ase.io import write

surface_energies = {(1, 1, 0): 1.0,
                    (1, 0, 0): 1.08}

prim = bulk('Fe', a=4.1, crystalstructure='bcc')

# Strongly wetting case (negative interface energy — particle spreads)
particle_wet = Winterbottom(surface_energies=surface_energies,
                             interface_direction=(1, 1, 1),
                             interface_energy=-0.2)
particle_wet.view()
write('winterbottom_wet.xyz', particle_wet.atoms)
```

--------------------------------

### Initialize Winterbottom Object

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/winterbottom.md

Instantiate a Winterbottom object with surface energies, interface direction, and interface energy. Optionally provide a primitive structure and number of atoms to define the particle's atomic composition and volume. The `view()` method can be used to visualize the particle, and `write()` to save its atomic structure.

```python
from wulffpack import Winterbottom
from ase.build import bulk
from ase.io import write
surface_energies = {(1, 1, 0): 1.0, (1, 0, 0): 1.08}
prim = bulk('Fe', a=4.1, crystalstructure='bcc')
particle = Winterbottom(surface_energies=surface_energies,
                        interface_direction=(3, 2, 1),
                        interface_energy=0.4,
                        primitive_structure=prim)
particle.view()
write('winterbottom.xyz', particle.atoms)  # Writes atomic structure to file
```

--------------------------------

### Winterbottom Class Initialization

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/winterbottom.md

Initializes a Winterbottom object with surface energies, interface direction, and interface energy.

```APIDOC
## class wulffpack.Winterbottom(surface_energies: Dict[tuple, float], interface_direction: tuple, interface_energy: float, primitive_structure: Atoms = None, natoms: int = 1000, symprec: float = 1e-05, tol: float = 1e-05)

A `Winterbottom` object is a Winterbottom construction, i.e., the lowest energy shape adopted by a single crystalline particle in contact with an interface.

### Parameters:
* **surface_energies** (Dict[tuple, float]) - A dictionary with surface energies, where keys are Miller indices and values surface energies (per area) in a unit of choice, such as J/m^2.
* **interface_direction** (tuple) - Miller indices for the interface facet.
* **interface_energy** (float) - Energy per area for interfaces. Caution: The interface energy here is equivalent to the generalized surface energy described in the original Winterbottom paper. Thus, this interface energy is the difference between the substrate-particle surface energy and the substrate-vapor surface energy. Note that this parameter can be negative.
* **primitive_structure** (Atoms, optional) - Primitive structure to implicitly define the point group as well as the atomic structure used if an atomic structure is requested. By default, an Au FCC structure is used.
* **natoms** (int, optional) - Together with `primitive_structure`, this parameter defines the volume of the particle. If an atomic structure is requested, the number of atoms will as closely as possible match this value. Defaults to 1000.
* **symprec** (float, optional) - Numerical tolerance for symmetry analysis, forwarded to spglib. Defaults to 1e-05.
* **tol** (float, optional) - Numerical tolerance parameter. Defaults to 1e-05.
```

--------------------------------

### ASE integration for atomistic representation

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Access the particle's `atoms` property to get an ASE Atoms object. This enables integration with the ASE ecosystem for visualization, file I/O, and use with MD/DFT codes.

```python
from wulffpack import SingleCrystal, Decahedron
from ase.build import bulk
from ase.io import write
from ase.visualize import view

surface_energies = {(1, 1, 1): 1.0, (1, 0, 0): 1.1}
prim = bulk('Au')

# Single crystal
sc = SingleCrystal(surface_energies, primitive_structure=prim, natoms=500)
atoms = sc.atoms                   # ASE Atoms object, ~500 atoms, PBC=False
view(atoms)                        # Open ASE GUI
write('particle.xyz',  atoms)      # XYZ format
write('particle.extxyz', atoms)    # Extended XYZ
write('particle.cif',  atoms)      # CIF
write('POSCAR',        atoms)      # VASP POSCAR

# Decahedron — full 5-grain atomistic structure
dh = Decahedron(surface_energies, twin_energy=0.03,
                primitive_structure=prim, natoms=1000)
write('decahedron.xyz', dh.atoms)

# Shift atomic center relative to lattice for best atom-count match
atoms_shifted = sc.get_shifted_atoms(center_shift=(1.0, 0.5, 0.5))
write('shifted.xyz', atoms_shifted)

print(f'Number of atoms: {len(sc.atoms)}')
# Number of atoms: 489  (closest achievable to the requested 500)
```

--------------------------------

### Create and Visualize an Icosahedron Particle

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/icosahedron.md

Illustrates how to instantiate an Icosahedron object with specified surface and twin energies, and then visualize its atomic structure. Requires ASE for atomic structure manipulation.

```python
from wulffpack import Icosahedron
from ase.build import bulk
from ase.io import write
surface_energies = {(1, 1, 1): 1.0, (1, 0, 0): 1.14}
particle = Icosahedron(surface_energies,
                       twin_energy=0.03,
                       primitive_structure=bulk('Au'))
particle.view()
write('icosahedron.xyz', particle.atoms) # Writes atomic structure
```

--------------------------------

### Create and Visualize a Single Crystal Wulff Construction

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/README.rst

Use this snippet to create a single crystal particle with specified surface energies and visualize its Wulff construction. The resulting atomistic structure can be saved to a file.

```python
from wulffpack import SingleCrystal
from ase.io import write
surface_energies = {(1, 1, 1): 1.0, (1, 0, 0): 1.2}
particle = SingleCrystal(surface_energies)
particle.view()
write('atoms.xyz', particle.atoms)
```

--------------------------------

### Visualize Particle with Continuous Color Scheme

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/graphics.md

Create a SingleCrystal particle with vicinal surface energies and obtain a continuous color scheme for visualization.

```python
surface_energies_vicinal = {
                            (1, 1, 1): 1.0,
                            (1, 1, 0): 1.1,
                            (1, 0, 0): 1.1,
                            (3, 3, 2): 1.05,
                            (2, 1, 0): 1.15}
particle_vicinal = SingleCrystal(surface_energies_vicinal)
continuous_colors = particle_vicinal.get_continuous_color_scheme()
particle_vicinal.view(colors=continuous_colors)
```

--------------------------------

### Construct Winterbottom Particle (Moderately Adhesive)

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Models a single-crystalline particle on a substrate using the Winterbottom construction. Requires surface energies, interface direction, and interface energy. The interface energy can be negative.

```python
from wulffpack import Winterbottom
from ase.build import bulk
from ase.io import write

surface_energies = {(1, 1, 0): 1.0,
                    (1, 0, 0): 1.08}

prim = bulk('Fe', a=4.1, crystalstructure='bcc')

# Particle wetting a (3,2,1) surface with a moderately adhesive interface
particle = Winterbottom(surface_energies=surface_energies,
                        interface_direction=(3, 2, 1),
                        interface_energy=0.4,
                        primitive_structure=prim,
                        natoms=1000)
particle.view()
write('winterbottom_partial.xyz', particle.atoms)
```

--------------------------------

### Import WulffPack and ASE Modules

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/basic_usage.md

Imports the required classes from WulffPack and functions from ASE for building and writing atomic structures.

```python
from wulffpack import (
                       SingleCrystal,
                       Decahedron,
                       Icosahedron,
                       Winterbottom)
from ase.build import bulk
from ase.io import write
```

--------------------------------

### Import WulffPack Crystal Structures

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/graphics.md

Import necessary crystal structure classes from the WulffPack library for use in creating and manipulating particles.

```python
from wulffpack import (
                       SingleCrystal,
                       Decahedron,
                       Icosahedron
                      )
```

--------------------------------

### Create Different Nanoparticle Shapes

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Instantiate SingleCrystal, Decahedron, and Icosahedron objects with the specified surface energies and parameters. These objects represent different nanoparticle structures.

```python
oh = SingleCrystal(surface_energies,
                   primitive_structure=prim,
                   natoms=natoms)
dh = Decahedron(surface_energies,
                twin_energy=twin_energy,
                primitive_structure=prim,
                natoms=natoms)
ih = Icosahedron(surface_energies,
                 twin_energy=twin_energy,
                 primitive_structure=prim,
                 natoms=natoms)
```

--------------------------------

### Construct Icosahedron Particle

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Constructs an icosahedral particle using specified surface energies and twin energy. Requires ASE's bulk for primitive structure. Strain energy can be estimated.

```python
from wulffpack import Icosahedron
from ase.build import bulk
from ase.io import write

surface_energies = {(1, 1, 1): 1.0,
                    (1, 0, 0): 1.14}

prim = bulk('Au', crystalstructure='fcc', a=4.08)

particle = Icosahedron(surface_energies,
                       twin_energy=1e-3,
                       primitive_structure=prim,
                       natoms=1000)

particle.view()
write('icosahedron.xyz', particle.atoms)

# Strain energy estimate (Howie & Marks 1984, Eq. 23)
shear_modulus  = 0.17
poissons_ratio = 0.42
strain_energy = particle.get_strain_energy(shear_modulus, poissons_ratio)
print(f'Strain energy: {strain_energy:.2f} eV')
```

--------------------------------

### Regular Wulff Construction with SingleCrystal

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/basic_usage.md

Performs a Wulff construction using arbitrary surface energies for an FCC crystal. Surface energy ratios determine the shape, and units are flexible but eV/Å^2 is recommended with ASE.

```python
surface_energies = {(1, 0, 0): 1.1,
                    (1, 1, 1): 1.,
                    (1, 1, 0): 1.15,
                    (2, 1, 1): 1.14}
particle = SingleCrystal(surface_energies)
particle.view()
write('single_crystal.xyz', particle.atoms)
```

--------------------------------

### Smooth facet coloring for vicinal surfaces

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Generates a color dictionary where colors interpolate smoothly between base colors assigned to specific facets. Useful for cubic systems and visually similar surfaces. Requires wulffpack.

```python
from wulffpack import SingleCrystal

surface_energies = {(1, 1, 1): 1.0,
                    (1, 1, 0): 1.1,
                    (1, 0, 0): 1.1,
                    (3, 3, 2): 1.05,
                    (2, 1, 0): 1.15}

particle = SingleCrystal(surface_energies)

# Auto-generated smooth color scheme
colors = particle.get_continuous_color_scheme()
particle.view(colors=colors)
```

```python
# Override base color for (1,1,1) to green, keep others default
colors_custom = particle.get_continuous_color_scheme(
    base_colors={(1, 1, 1): 'g'})
particle.view(colors=colors_custom)
```

```python
# Normalized RGB vectors (unit norm)
colors_norm = particle.get_continuous_color_scheme(normalize=True)
```

--------------------------------

### SingleCrystal Class Initialization

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/single_crystal.md

Initializes a SingleCrystal object for Wulff construction. Requires surface energies and can optionally take a primitive structure, number of atoms, symmetry precision, tolerance, and explicit symmetry operations.

```APIDOC
## class wulffpack.SingleCrystal(surface_energies: dict, primitive_structure: Atoms = None, natoms: int = 1000, symprec: float = 1e-05, tol: float = 1e-05, symmetry_operations: List[ndarray] = None)

### Parameters
* **surface_energies** – A dictionary with surface energies, where keys are Miller indices and values surface energies (per area) in a unit of choice, such as J/m^2.
* **primitive_structure** – primitive cell to implicitly define the point group as well as the atomic structure used if an atomic structure is requested. By default, an Au FCC structure is used.
* **natoms** – Together with `primitive_structure`, this parameter defines the volume of the particle. If an atomic structure is requested, the number of atoms will as closely as possible match this value.
* **symprec** – Numerical tolerance for symmetry analysis, forwarded to spglib.
* **tol** – Numerical tolerance parameter.
* **symmetry_operations** – This parameter allows one to pass an explicit list of allowed symmetry operations. By default (`None`) the allowed symmetry operations are obtained from `primitive_structure`.
```

--------------------------------

### Export to Wavefront .obj for 3D software

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Writes the particle's continuum surface geometry to a Wavefront .obj file, readable by 3D tools like Blender. Each crystallographic form becomes a named group for per-form coloring.

```python
from wulffpack import Winterbottom
from ase.build import bulk

surface_energies = {(1, 1, 1): 1.0, (1, 0, 0): 1.1}
particle = Winterbottom(surface_energies=surface_energies,
                        interface_direction=(1, 1, 1),
                        interface_energy=-0.3)

particle.write('winterbottom.obj')
```

--------------------------------

### Standard Wulff Construction (SingleCrystal)

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Compute the equilibrium shape of a single-crystalline nanoparticle using surface energies. Supports FCC and HCP lattices, and allows customization of the primitive structure and atom count. The resulting particle can be visualized and exported.

```python
from wulffpack import SingleCrystal
from ase.build import bulk
from ase.io import write

# --- FCC cubic particle (default Au lattice) ---
surface_energies = {(1, 0, 0): 1.1,
                    (1, 1, 1): 1.0,
                    (1, 1, 0): 1.15,
                    (2, 1, 1): 1.14}

particle = SingleCrystal(surface_energies)
particle.view()                              # interactive matplotlib window
write('single_crystal.xyz', particle.atoms) # write ~1000-atom XYZ file

# --- HCP crystal (Bravais-Miller indices) ---
prim = bulk('Co', crystalstructure='hcp')
surface_energies_hcp = {(1, 0, -1, 0): 1.1,
                        (0, 0, 0,  1): 1.0,
                        (1, 1, -2, 0): 1.0}

particle_hcp = SingleCrystal(surface_energies_hcp,
                              primitive_structure=prim,
                              natoms=5000)
particle_hcp.view()
write('hcp_particle.xyz', particle_hcp.atoms)

# Resize without rerunning the construction
particle_hcp.natoms = 10000
write('hcp_particle_10k.xyz', particle_hcp.atoms)

# Inspect the standardized cell (Miller indices always refer to this)
from ase.visualize import view as ase_view
ose_view(particle_hcp.standardized_structure)

# Shifted-center atomistic representation (moves center off-atom for better fit)
 atoms_shifted = particle.get_shifted_atoms(center_shift=(0.5, 0.5, 0.5))
write('single_crystal_shifted.xyz', atoms_shifted)
```

--------------------------------

### Define and View a Single Particle

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/graphics.md

Define surface energies and create a Decahedron particle. Visualize it with default settings or save it as a PNG with custom colors and line styles.

```python
surface_energies = {
                    (1, 1, 1): 1.0,
                    (1, 0, 0): 1.1,
                    (1, 1, 0): 1.12}
particle = Decahedron(surface_energies=surface_energies,
                      twin_energy=0.02)

colors = {
          (1, 1, 1): '#7da275',
          (1, 0, 0): '#0053b5',
          (1, 1, 0): '#f6faf5'}
particle.view()
particle.view(colors=colors, linewidth=0.3, alpha=0.9,
              save_as='single_particle.png')
```

--------------------------------

### Compare Nanoparticle Volumes

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Check if the created particles have the same volume. The volume is determined by the number of atoms and the primitive structure.

```python
print('Volume (sanity check):')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    volume = particle.volume
    print('{}: {:.2f}'.format(name, volume))
```

--------------------------------

### Plotting Different Wulffpack Particles

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/core.md

Demonstrates how to create and plot SingleCrystal, Decahedron, and Icosahedron particles using specified surface energies and twin energies. This is useful for visualizing the shapes of Wulff constructions.

```python
from wulffpack import SingleCrystal, Decahedron, Icosahedron
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D

surface_energies = {(1, 1, 1): 1.0,
                    (1, 0, 0): 1.1,
                    (1, 1, 0): 1.15,
                    (3, 2, 1): 1.15}
twin_energy = 0.05

fig = plt.figure(figsize=(3*4.0, 4.0))
ax = fig.add_subplot(131, projection='3d')
particle = SingleCrystal(surface_energies)
particle.make_plot(ax)

ax = fig.add_subplot(132, projection='3d')
particle = Decahedron(surface_energies,
                      twin_energy=0.05)
particle.make_plot(ax)

ax = fig.add_subplot(133, projection='3d')
particle = Icosahedron(surface_energies,
                       twin_energy=0.05)
particle.make_plot(ax)

plt.subplots_adjust(top=1, bottom=0, left=0,
                    right=1, wspace=0, hspace=0)
plt.savefig('particles.png')
```

--------------------------------

### Write Atoms Object to XYZ File

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/graphics.md

Export the ASE Atoms object to an XYZ file, enabling visualization with external atomistic structure software.

```python
from ase.io import write
write('atoms.xyz', particle.atoms)
```

--------------------------------

### Write Particle to Wavefront OBJ File

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/graphics.md

Save the particle geometry to a Wavefront .obj file, which can be imported into 3D modeling software like Blender.

```python
particle.write('particle.obj')
```

--------------------------------

### Particle Visualization and Writing

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/winterbottom.md

Methods for visualizing the particle using matplotlib and writing it to a file.

```APIDOC
## Particle Visualization and Writing

### Description
Methods for visualizing the particle using matplotlib and writing it to a file.

#### view(alpha: float = 0.85, linewidth: float = 0.3, colors: dict = None, legend: bool = True, save_as: str = None)
Use matplotlib to view a rendition of the particle.

* **Parameters:**
  * **alpha** – Opacity of the faces
  * **linewidth** – Thickness of lines between faces
  * **colors** – Allows custom colors for facets of all or a subset of forms,
    example `{(1, 1, 1): '#FF0000'}`
  * **legend** – Whether or not to show a legend with facet-color definitions
  * **save_as** – Filename to save figure as. If None, show the particle
    with the GUI instead.

#### write(filename: str)
Write particle to file. The file format is derived from the
filename. Currently supported fileformats are:

> * Wavefront .obj
* **Parameters:**
  **filename** – Filename of file to write to
```

--------------------------------

### write

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/core.md

Writes the particle data to a file. The file format is determined by the filename extension.

```APIDOC
#### write(filename: str)

Write particle to file. The file format is derived from the
filename. Currently supported fileformats are:

> * Wavefront .obj
* **Parameters:**
  **filename** – Filename of file to write to
```

--------------------------------

### Compare Fraction of Specified Facets

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Determine the fraction of a specific facet, such as {100}, for each nanoparticle shape. This is useful for understanding facet distribution and its relation to surface energy.

```python
print('Fraction of {100} facets:')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    fraction = particle.facet_fractions.get((1, 0, 0), 0.)
    print('{}: {:.4f}'.format(name, fraction))
```

--------------------------------

### Visualize Atoms Object with ASE GUI

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/graphics.md

Extract an ASE Atoms object from a WulffPack particle and visualize it using ASE's built-in GUI.

```python
from ase.visualize import view
view(particle.atoms)
```

--------------------------------

### Show Particle with Continuous Color Scheme

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/graphics.md

Generate and apply a continuous color scheme for particles with vicinal surfaces using `get_continuous_color_scheme`. This is primarily useful for crystals with cubic symmetry.

```python
surface_energies_vicinal = {(1, 1, 1): 1.0,
                            (1, 1, 0): 1.1,
                            (1, 0, 0): 1.1,
                            (3, 3, 2): 1.05,
                            (2, 1, 0): 1.15}
particle_vicinal = SingleCrystal(surface_energies_vicinal)
continuous_colors = particle_vicinal.get_continuous_color_scheme()
particle_vicinal.view(colors=continuous_colors)
```

--------------------------------

### Compare Average Surface Energies

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Compares the average surface energy of different particle shapes. Ensure the particle objects (oh, dh, ih) are initialized before use.

```python
print('Average surface energy (excluding twin energy):')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    energy = particle.average_surface_energy
    print('{}: {:.4f}'.format(name, energy))
print()
```

--------------------------------

### Construct Icosahedral Particle

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/basic_usage.md

Constructs an icosahedral particle with identical interface to constructing a decahedral particle. It requires surface energies, twin energy, and a primitive structure.

```python
particle = Icosahedron(surface_energies,
                       twin_energy=0.04,
                       primitive_structure=prim)
```

--------------------------------

### Icosahedron Methods

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/icosahedron.md

Methods available for interacting with and manipulating the Icosahedron particle.

```APIDOC
## Icosahedron Methods

### rotate_particle(rotation: ndarray)

Rotate the particle.

* **Parameters:**
  **rotation** – Rotation matrix

### translate_particle(translation: ndarray)

Translate the particle.

* **Parameters:**
  **translation** (*list* *of* *3 floats*) – Translation vector

### view(alpha: float = 0.85, linewidth: float = 0.3, colors: dict = None, legend: bool = True, save_as: str = None)

Use matplotlib to view a rendition of the particle.

* **Parameters:**
  * **alpha** – Opacity of the faces
  * **linewidth** – Thickness of lines between faces
  * **colors** – Allows custom colors for facets of all or a subset of forms,
    example `{(1, 1, 1): '#FF0000'}`
  * **legend** – Whether or not to show a legend with facet-color definitions
  * **save_as** – Filename to save figure as. If None, show the particle
    with the GUI instead.

### write(filename: str)

Write particle to file. The file format is derived from the
filename. Currently supported fileformats are:

> * Wavefront .obj
* **Parameters:**
  **filename** – Filename of file to write to
```

--------------------------------

### Compare Number of Corners and Total Edge Length

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Prints the number of corners and total edge length for single crystal, decahedral, and icosahedral particles. This comparison focuses on surface features and excludes internal defects.

```python
print('Number of corners and total edge length:')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    ncorners = particle.number_of_corners
    edge_length = particle.edge_length
    print('{}: {} corners, edge length: {:.2f}'.format(name,
                                                       ncorners,
                                                       edge_length))
```

```text
Number of corners and total edge length:
Oh: 24 corners, edge length: 409.48
Dh: 42 corners, edge length: 610.03
Ih: 72 corners, edge length: 614.70
```

--------------------------------

### Initialize Decahedron Particle

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/decahedron.md

Instantiate a Decahedron object with specified surface energies, twin energy, and primitive structure. The atomic structure can be defined by a primitive cell and the desired number of atoms.

```python
from wulffpack import Decahedron
from ase.build import bulk
from ase.io import write
surface_energies = {(1, 1, 1): 1.0, (1, 0, 0): 1.14}
prim = bulk('Au')
particle = Decahedron(surface_energies,
                      twin_energy=0.03,
                      primitive_structure=bulk('Au'))
particle.view()
write('decahedron.xyz', particle.atoms) # Writes atomic structure
```

--------------------------------

### Custom colors, saved to PNG

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Customize particle colors using a dictionary and save the visualization to a PNG file. The legend can also be disabled.

```python
colors = {(1, 1, 1): '#7da275', (1, 0, 0): '#0053b5', (1, 1, 0): '#f6faf5'}
particle.view(colors=colors, alpha=0.9, linewidth=0.3,
              save_as='decahedron.png')
```

```python
particle.view(legend=False, save_as='no_legend.png')
```

--------------------------------

### Decahedron Methods

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/decahedron.md

Available methods for interacting with Decahedron particles.

```APIDOC
## Decahedron Methods

### rotate_particle

Rotate the particle.

#### Parameters:
* **rotation** (ndarray) – Rotation matrix

### translate_particle

Translate the particle.

#### Parameters:
* **translation** (list of 3 floats) – Translation vector

### view

Use matplotlib to view a rendition of the particle.

#### Parameters:
* **alpha** (float, optional) – Opacity of the faces. Defaults to 0.85.
* **linewidth** (float, optional) – Thickness of lines between faces. Defaults to 0.3.
* **colors** (dict, optional) – Allows custom colors for facets of all or a subset of forms, example `{(1, 1, 1): '#FF0000'}`.
* **legend** (bool, optional) – Whether or not to show a legend with facet-color definitions. Defaults to True.
* **save_as** (str, optional) – Filename to save figure as. If None, show the particle with the GUI instead.

### write

Write particle to file. The file format is derived from the filename. Currently supported fileformats are:

> * Wavefront .obj

#### Parameters:
* **filename** (str) – Filename of file to write to
```

--------------------------------

### Compare Nanoparticle Surface Areas

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Calculate and compare the total surface area of the nanoparticles, excluding twin boundaries. This helps in understanding the surface exposure of different shapes.

```python
print('Total surface area (excluding twin boundaries):')
for name, particle in zip(['Oh', 'Dh', 'Ih'], [oh, dh, ih]):
    area = particle.area
    print('{}: {:.2f}'.format(name, area))
```

--------------------------------

### Icosahedron Class

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/icosahedron.md

Initializes an Icosahedron object, representing a generalized Wulff construction of an icosahedral particle.

```APIDOC
## class wulffpack.Icosahedron

### Description
An `Icosahedron` object is a generalized Wulff construction of an icosahedral particle.

### Parameters
* **surface_energies** (Dict[tuple, float]) - A dictionary with surface energies, where keys are Miller indices and values surface energies (per area) in a unit of choice, such as J/m^2.
* **twin_energy** (float) - Energy per area for twin boundaries.
* **primitive_structure** (Atoms, optional) - Primitive cell to define the atomic structure used if an atomic structure is requested. By default, an Au FCC structure is used. The crystal has to have cubic symmetry.
* **natoms** (int, optional) - Together with `lattice_parameter`, this parameter defines the volume of the particle. If an atomic structure is requested, the number of atoms will as closely as possible match this value.
* **symprec** (float, optional) - Numerical tolerance for symmetry analysis, forwarded to spglib.
* **tol** (float, optional) - Numerical tolerance parameter.

### Example
```python
>>> from wulffpack import Icosahedron
>>> from ase.build import bulk
>>> from ase.io import write
>>> surface_energies = {(1, 1, 1): 1.0, (1, 0, 0): 1.14}
>>> particle = Icosahedron(surface_energies,
...                        twin_energy=0.03,
...                        primitive_structure=bulk('Au'))
>>> particle.view()
>>> write('icosahedron.xyz', particle.atoms) # Writes atomic structure
```
```

--------------------------------

### Construct Decahedral Particle

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/basic_usage.md

Constructs a decahedral particle using specified surface energies, twin boundary energy, and a primitive crystal structure. The resulting particle can be visualized and saved.

```python
surface_energies = {(1, 0, 0): 1.1,
                    (1, 1, 1): 1.,
                    (1, 1, 0): 1.15}
prim = bulk('Pd', a=3.9)
particle = Decahedron(surface_energies,
                      twin_energy=0.04,
                      primitive_structure=prim)
particle.view()
write('decahedron.xyz', particle.atoms)
```

--------------------------------

### SingleCrystal Methods

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/single_crystal.md

Methods available for interacting with and manipulating SingleCrystal objects.

```APIDOC
## Method: rotate_particle
### Description
Rotate the particle.
### Parameters
#### rotation
- **rotation** (ndarray) - Rotation matrix
```

```APIDOC
## Method: translate_particle
### Description
Translate the particle.
### Parameters
#### translation
- **translation** (list of 3 floats) - Translation vector
```

```APIDOC
## Method: view
### Description
Use matplotlib to view a rendition of the particle.
### Parameters
#### alpha
- **alpha** (float) - Opacity of the faces
#### linewidth
- **linewidth** (float) - Thickness of lines between faces
#### colors
- **colors** (dict) - Allows custom colors for facets of all or a subset of forms, example `{(1, 1, 1): '#FF0000'}`
#### legend
- **legend** (bool) - Whether or not to show a legend with facet-color definitions
#### save_as
- **save_as** (str) - Filename to save figure as. If None, show the particle with the GUI instead.
```

```APIDOC
## Method: write
### Description
Write particle to file. The file format is derived from the filename. Currently supported fileformats are: Wavefront .obj
### Parameters
#### filename
- **filename** (str) - Filename of file to write to
```

--------------------------------

### Compare Estimated Strain Energies

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/tutorials/compare_shapes.md

Compares the estimated strain energies for different particle shapes using provided shear modulus and Poisson's ratio. Requires particle objects (dh, ih) and material properties.

```python
shear_modulus = 0.17  # eV / Angstrom^3
poissons_ratio = 0.42  # unitless
print('Estimated strain energies:')
for name, particle in zip(['Dh', 'Ih'], [dh, ih]):
    energy = particle.get_strain_energy(shear_modulus=shear_modulus,
                                        poissons_ratio=poissons_ratio)
    print('{}: {:.2f}'.format(name, energy))
print()
```

--------------------------------

### Twinned Decahedral Wulff Construction (Decahedron)

Source: https://context7.com/materials-modeling/wulffpack/llms.txt

Implement a Wulff construction for five-grain decahedral particles, including twin-boundary energy. Requires cubic symmetry and specific conditions for twin energy. Provides geometric properties and a strain-energy estimator.

```python
from wulffpack import Decahedron
from ase.build import bulk
from ase.io import write

surface_energies = {(1, 1, 1): 1.0,
                    (1, 0, 0): 1.14,
                    (1, 1, 0): 1.15}

prim = bulk('Pd', a=3.9)   # cubic FCC — required for decahedra

particle = Decahedron(surface_energies,
                      twin_energy=0.04,
                      primitive_structure=prim,
                      natoms=2000)

particle.view()
write('decahedron.xyz', particle.atoms)

# Geometric properties
print('Fivefold axis:', particle.fivefold_axis_vector)  # e.g. [0. 0. 1.]
print('Aspect ratio: ', particle.aspect_ratio)           # height / width

# Strain energy estimate (Howie & Marks 1984, Eq. 10)
shear_modulus  = 0.17   # eV/ų
poissons_ratio = 0.42   # unitless
strain_energy = particle.get_strain_energy(shear_modulus, poissons_ratio)
print(f'Strain energy: {strain_energy:.2f} eV')
# Example output: Strain energy: 0.52 eV
```

--------------------------------

### view

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/core.md

Renders a matplotlib visualization of the particle. Allows customization of opacity, line width, colors, legend, and saving the figure.

```APIDOC
## view(alpha: float = 0.85, linewidth: float = 0.3, colors: dict = None, legend: bool = True, save_as: str = None)

Use matplotlib to view a rendition of the particle.

* **Parameters:**
  * **alpha** – Opacity of the faces
  * **linewidth** – Thickness of lines between faces
  * **colors** – Allows custom colors for facets of all or a subset of forms,
    example `{(1, 1, 1): '#FF0000'}`
  * **legend** – Whether or not to show a legend with facet-color definitions
  * **save_as** – Filename to save figure as. If None, show the particle
    with the GUI instead.
```

--------------------------------

### Decahedron Class Initialization

Source: https://gitlab.com/materials-modeling/wulffpack/-/blob/master/doc/moduleref/decahedron.md

Initializes a Decahedron object. This object represents a decahedral particle constructed using a generalized Wulff construction.

```APIDOC
## class wulffpack.Decahedron

### Description
A `Decahedron` object is a generalized Wulff construction of a decahedral particle.

### Parameters
* **surface_energies** (Dict[tuple, float]) - A dictionary with surface energies, where keys are Miller indices and values surface energies (per area) in a unit of choice, such as J/m^2.
* **twin_energy** (float) - Energy per area for twin boundaries.
* **primitive_structure** (Atoms, optional) - Primitive cell to define the atomic structure used if an atomic structure is requested. By default, an Au FCC structure is used. The crystal has to have cubic symmetry.
* **natoms** (int, optional) - Together with `lattice_parameter`, this parameter defines the volume of the particle. If an atomic structure is requested, the number of atoms will as closely as possible match this value. Defaults to 1000.
* **symprec** (float, optional) - Numerical tolerance for symmetry analysis, forwarded to spglib. Defaults to 1e-05.
* **tol** (float, optional) - Numerical tolerance parameter. Defaults to 1e-05.

### Example
```python
from wulffpack import Decahedron
from ase.build import bulk
from ase.io import write
surface_energies = {(1, 1, 1): 1.0, (1, 0, 0): 1.14}
prim = bulk('Au')
particle = Decahedron(surface_energies,
                      twin_energy=0.03,
                      primitive_structure=bulk('Au'))
particle.view()
write('decahedron.xyz', particle.atoms) # Writes atomic structure
```
```