WulffPack

https://wulffpack.materialsmodeling.org/
Admin
WulffPack is a Python package for constructing Wulff shapes of nanoparticles, including single...
Tokens:45,300
Snippets:380
Trust Score:7.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Verify Cloned Installation with Tests

Source: https://wulffpack.materialsmodeling.org/get_started/installation.html

After installing from the cloned repository, run the test suite to ensure the installation was successful. This is a crucial step for verifying the integrity of your setup.

```bash
python3 tests/main.py

```

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

### Install WulffPack from Cloned Repository

Source: https://wulffpack.materialsmodeling.org/get_started/installation.html

Navigate to the cloned repository's root directory and install WulffPack using setup.py. This method installs the package for the current user.

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

```

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

### Verify pip Installation with Tests

Source: https://wulffpack.materialsmodeling.org/get_started/installation.html

After installing via pip, run these commands to download, unzip, and execute the test suite to confirm a successful installation.

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

```

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

### Install WulffPack via pip

Source: https://wulffpack.materialsmodeling.org/get_started/installation.html

Use this command for the simplest installation of WulffPack. It is recommended to test the installation after this step.

```bash
pip install wulffpack

```

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

### Complete Graphics Example Source Code

Source: https://wulffpack.materialsmodeling.org/tutorials/graphics.html

A comprehensive example demonstrating particle creation, visualization with custom colors, saving to file, and using continuous color schemes. Includes imports for `SingleCrystal`, `Decahedron`, and `Icosahedron`.

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

# Define energies and create particle
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)

# Define colors (optional)
colors = {(1, 1, 1): '#7da275',
          (1, 0, 0): '#0053b5',
          (1, 1, 0): '#f6faf5'}
# Show with GUI:
particle.view()
# Save as file:
particle.view(colors=colors, linewidth=0.3, alpha=0.9,
              save_as='single_particle.png')

# Use continuous color scheme
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)
```

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

### Setup forms based on surface energies and symmetries

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/form.html

A function to create a dictionary of surface energies adapted according to specified symmetries, potentially handling restricted and full symmetry sets, and interface conditions.

```python
def setup_forms(surface_energies: Dict, 
                cell: np.ndarray, 
                symmetries_restricted: List[np.ndarray], 
                symmetries_full: List[np.ndarray], 
                twin_boundary: Union[List, tuple] = None, 
                interface: Union[List, tuple] = None, 
                tol: float = 1e-6) -> Dict:
    """
    Create an adapted dictionary of surface energies based on
    the symmetries specified.
    """
```

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

### Initialize Icosahedron Object

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/icosahedron.html

Example of initializing an Icosahedron object with surface energies and twin energy. The primitive structure defaults to an Au FCC structure if not provided. The number of atoms and symmetry precision can also be specified.

```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 View Single Crystal Wulff Shape

Source: https://wulffpack.materialsmodeling.org/index.html

This snippet demonstrates how to initialize a SingleCrystal object with surface energies and then visualize the resulting Wulff shape. Ensure the 'wulffpack' and 'ase' libraries 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)
```

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

### Get Continuous Color Scheme for Forms

Source: https://wulffpack.materialsmodeling.org/moduleref/winterbottom.html

Generate a dictionary of RGB colors for each form, smoothly interpolating between base colors. This is primarily useful for cubic systems.

```python
particle.get_continuous_color_scheme()
```

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

### Plotting Single Crystal Particles

Source: https://wulffpack.materialsmodeling.org/moduleref/single_crystal.html

Generates and saves plots of single crystalline particles using matplotlib. This example demonstrates how to create subplots and customize the plot's appearance.

```python
fig = plt.figure(figsize=(10, 3))

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

ax = fig.add_subplot(132, projection='3d')
particle = Icosahedron(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')
```

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

### setup_forms Function

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/form.html

Creates an adapted dictionary of surface energies based on the specified symmetries, handling potential symmetry breaking.

```APIDOC
## def setup_forms(surface_energies: Dict, cell: np.ndarray, symmetries_restricted: List[np.ndarray], symmetries_full: List[np.ndarray], twin_boundary: Union[List, tuple] = None, interface: Union[List, tuple] = None, tol: float = 1e-6) -> Dict

### Description
Create an adapted dictionary of surface energies based on the symmetries specified.

### Parameters
- **surface_energies** (Dict): A dictionary mapping Miller indices to surface energies.
- **cell** (np.ndarray): The crystallographic cell, with basis vectors as columns.
- **symmetries_restricted** (List[np.ndarray]): A list of symmetry operations that are valid for the current system (e.g., with an interface).
- **symmetries_full** (List[np.ndarray]): A list of all symmetry operations for the bulk system.
- **twin_boundary** (Union[List, tuple], optional): Information about a twin boundary, if present. Defaults to None.
- **interface** (Union[List, tuple], optional): Information about an interface, if present. Defaults to None.
- **tol** (float, optional): Tolerance for floating-point comparisons. Defaults to 1e-6.

### Returns
- Dict: An adapted dictionary of surface energies, potentially grouped into forms.
```

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

### Get particle volume

Source: https://wulffpack.materialsmodeling.org/moduleref/core.html

Returns the volume of the particle.

```APIDOC
## _property _volume

### Description
Returns the volume of the particle.

### Returns
* **volume** (`float`) - The volume of the particle.
```

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

### Get Particle Facets - BaseParticle

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/base_particle.html

Returns a list of all facets belonging to the particle. This is a read-only property.

```python
@property
def facets(self) -> List[Facet]:
    """The facets of the particle (read-only)."""
    return list(self._yield_facets())
```

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

### Get Atoms from SingleCrystal

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/single_crystal.html

Access the atomistic representation of the Wulff construction as an ASE Atoms object.

```python
particle.atoms
```

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

### Wulff Construction for Substrate (Winterbottom)

Source: https://wulffpack.materialsmodeling.org/tutorials/basic_usage.html

Demonstrates the Winterbottom construction for particles on a substrate, specifying interface direction and generalized surface energy.

```python
# Wulff construction for substrate
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)
```

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

### Initialize Winterbottom Construction

Source: https://wulffpack.materialsmodeling.org/moduleref/winterbottom.html

Instantiate a Winterbottom object with surface energies, interface direction, and interface energy. An optional primitive structure can be provided to define the point group and 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)
```

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

### Get Decahedral Scale Factor

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/decahedron.html

Returns a pre-calculated scale factor for decahedra. This value is a constant derived from the geometry of a regular decahedron.

```python
def _get_decahedral_scale_factor() -> float:
    return np.sqrt(10 - 4 * np.sqrt(5))
```

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

### Wulff Construction on Substrate (Winterbottom)

Source: https://wulffpack.materialsmodeling.org/tutorials/basic_usage.html

Constructs a particle on a substrate using the Winterbottom construction. Requires generalized surface energy and interface direction.

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

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

### Plot SingleCrystal Particle

Source: https://wulffpack.materialsmodeling.org/moduleref/single_crystal.html

Plot a SingleCrystal particle using matplotlib. This example demonstrates plotting a single crystal particle in a 3D axis.

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

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

### Form Initialization and Symmetry Handling

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/form.html

This code snippet demonstrates the initialization of Form objects for twin and interface facets, and the subsequent processing of other facets. It includes checks for positive surface energies and identifies inequivalent facet normals using symmetry transformations.

```python
    reciprocal_cell = np.linalg.inv(cell).T
    forms = []
    scaled_normals = []  # To be able to identify over-specified facets
    ordered_facets = []  # --"--
    if min(e for form, e in surface_energies.items() if form != 'interface') < 0:
        raise ValueError('Please use only positive surface/twin energies')

    for form, energy in surface_energies.items():
        inequivalent_normals_scaled = []
        if form == 'twin':
            if twin_boundary:
                forms.append(Form(miller_indices=twin_boundary,
                                  energy=energy / 2,
                                  cell=cell,
                                  symmetries=symmetries_restricted,
                                  parent_miller_indices=form))
        elif form == 'interface':
            if interface:
                forms.append(Form(miller_indices=interface,
                                  energy=energy,
                                  cell=cell,
                                  symmetries=symmetries_restricted,
                                  parent_miller_indices=form))
        else:
            if len(form) == 4:
                miller_indices = convert_bravais_miller_to_miller(form)
            else:
                miller_indices = form
            normal = np.dot(reciprocal_cell, miller_indices)  # Cartesian coords
            normal_scaled = np.linalg.solve(cell, normal)  # scaled coords

            # Check that this facet is not symmetrically equivalent to another
            scaled_normals.append(normal_scaled)
            ordered_facets.append((form, energy))
            for R_r in symmetries_full:
                transformed_normal_scaled = np.dot(R_r, normal_scaled)

                previous_index = where_is_array_in_arrays(transformed_normal_scaled,
                                                          scaled_normals[:-1])
                if previous_index != -1:
                    # Then this facet is redundant.
                    # If it has the same energy, we just skip it,
                    # otherwise we need to throw an exception.
                    if abs(energy - ordered_facets[previous_index][1]) > tol:
                        raise ValueError(
                            f'The Miller indices {form} '
                            f'are equivalent to {ordered_facets[previous_index][0]} '
                            'by symmetry. If your system is such that they should be '
                            'inequivalent, please specify a primitive structure with '
                            'the appropriate point group symmetry or provide a '
                            'custom set of symmetries.')
                    else:
                        break
            else:
                # Then this facet is not symmetrically equivalent to another.
                # Now we need to look at all symmetrically equivalent versions
                # and check whether broken symmetry makes them inequivalent.

```

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

### Get Distance from Origin

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/facet.html

Calculates and returns the distance from the origin to the facet plane. This is determined by the dot product of the first vertex and the facet's normal vector.

```python
@property
def distance_from_origin(self) -> float:
    """Returns the distance from the origin to the facet."""
    return np.dot(self.vertices[0], self.normal)
```

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

### Get Symmetry Operations - Python

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/icosahedron.html

Constructs a subset of symmetry operations that duplicate a single tetrahedron to all 20 tetrahedra. Requires specific fivefold axes to be defined.

```python
def _get_symmetry_operations(self) -> List[np.ndarray]:
        """
        Construct the subset of symmetry operations that duplicates
        a single tetrahedron to all 20 tetrahedra.
        """
        fivefold_1, fivefold_2 = self._get_two_fivefold_axes()
        symmetries = []
        inversion = - np.eye(3)
        symmetries.append(inversion)
        down = get_rotation_matrix(2 * 2 * np.pi / 5, fivefold_1)
        symmetries.append(down)
        symmetries.append(np.dot(inversion, down))
        for i in range(1, 5):
            R = get_rotation_matrix(i * 2 * np.pi / 5, fivefold_2)
            symmetries.append(R)
            symmetries.append(np.dot(inversion, R))
            symmetries.append(np.dot(R, down))
            symmetries.append(np.dot(inversion, np.dot(R, down)))
        assert len(symmetries) == 19
        return symmetries
```

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

### View and Write Winterbottom Particle

Source: https://wulffpack.materialsmodeling.org/moduleref/winterbottom.html

Visualize the Winterbottom particle using the view() method and write its atomic structure to a file using ASE's write function.

```python
particle.view()
write('winterbottom.xyz', particle.atoms)
```

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

### Get All Icosahedral Symmetry Operations

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/icosahedron.html

Retrieves all 60 icosahedral symmetry operations in the current coordinate system. This is essential for applying symmetry transformations to the crystal structure.

```python
    def _get_all_symmetry_operations(self) -> List[np.ndarray]:
        """
        Get the 60 icosahedral symmetry operations in the coordinate

```

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

### Define Crystal Structure and Surface Energies

Source: https://wulffpack.materialsmodeling.org/tutorials/compare_shapes.html

Set up the primitive structure and surface energies for nanoparticle construction. This is a prerequisite for creating any WulffPack particle.

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

```

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

### Initialize BaseParticle

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/base_particle.html

Initializes the BaseParticle with forms, structural information, and atom count. It calculates facets, determines shape based on energies, removes redundant vertices and facets, and scales the particle to match the target volume.

```python
def __init__(self, forms: List[Form],
 standardized_structure: Atoms,
 natoms: int,
 ngrains: int = 1,
 volume_scale: int = 1.0,
 tol: float = 1e-5):
 self._natoms = natoms
 self._standardized_structure = standardized_structure
 self._forms = forms
 self.tol = tol
 self._SMALL = 1e-12

 facets = list(self._yield_facets())
 if min(f.energy for f in facets) < 0:  # interface energy can be negative
 self._closest_vertices(facets)
 else:
 self._dual_wulff_shape(facets)

 # Remove vertices that are on the line between two other vertices
 # (relevant in the Winterbottom case and some corner cases)
 for facet in self._yield_facets():
 facet.remove_redundant_vertices()

 # Delete facets with less than three vertices
 to_pop = []
 for i, form in enumerate(self.forms):
 if len(form.facets[0].vertices) < 3:
 to_pop.append(i)
 for i in reversed(to_pop):
 self.forms.pop(i)

 # Scale everyting such that the volume matches the specified one
 target_volume = self.natoms * standardized_structure.get_volume() /
 len(standardized_structure)
 scale_factor = (target_volume / (ngrains * self.volume * volume_scale)) ** (1 / 3)
 self._scale_size(scale_factor)
```

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

### Get Shifted Atoms from SingleCrystal

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/single_crystal.html

Retrieve an ASE Atoms object with its center shifted from the standardized cell. This can help achieve a number of atoms closer to the requested value.

```python
particle.get_shifted_atoms(center_shift=(0.1, 0.2, 0.3))
```

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

### Initialize SingleCrystal Object

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/single_crystal.html

Instantiate a SingleCrystal object with surface energies and an optional primitive structure. The number of atoms and symmetry precision can also be specified.

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

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

### Get Icosahedral Scale Factor - Python

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/icosahedron.html

Calculates a scale factor specific to icosahedral geometry. This is a utility function likely used in geometric constructions or calculations related to icosahedra.

```python
def _get_icosahedral_scale_factor():
    k = (5 + np.sqrt(5)) / 8
    return np.sqrt(2 / (3 * k - 1))
```

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

### Initialize Winterbottom Particle

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/winterbottom.html

Instantiate a Winterbottom object with surface energies, interface direction, and interface energy. Primitive structure and number of atoms can also be specified. Raises ValueError if interface energy is too high.

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

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

### write

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/base_particle.html

Writes the particle data to a file. Currently supports the Wavefront .obj format.

```APIDOC
## write

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

### Request Example
```python
particle.write('my_particle.obj')
```

### Response Example
(Writes the particle data to the specified file)
```

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

### Get Unique Coordinates - Python

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/icosahedron.html

Duplicates atoms based on a list of symmetry operations, ensuring no two atoms occupy the same position. It uses a base element to check for redundant transformations.

```python
def _get_unique_coordinates(atoms: Atoms,
                            symmetries: List[np.ndarray],
                            base_element: np.ndarray) -> List[np.ndarray]:
    """
    Duplicate atoms with a list of symmetries, but avoid putting
    atoms on top of each other.

    atoms
        Atoms object to duplicate
    symmetries
        List of symmetry elements to act on atoms with
    base_element
        An vector in Cartesian coordinates. If two symmetry
        elements carries this vector to the same position,
        one symmetry element will be skipped.

    Returns
    -------
    A list of Cartesian coordinates with new atomic positions,
    including the original ones.
    """
    unique_coordinates = []
    symmetrical_elements = []
    for R in symmetries:
        element = np.dot(R, base_element)
        if is_array_in_arrays(element, symmetrical_elements):
            continue
        else:
            symmetrical_elements.append(element)
        for atom in atoms:
            unique_coordinates.append(np.dot(R, atom.position))
    return unique_coordinates
```

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

### Regular Wulff Construction (SingleCrystal)

Source: https://wulffpack.materialsmodeling.org/tutorials/basic_usage.html

Performs a regular Wulff construction for a cubic crystal using specified surface energies. Imports are required from wulffpack and ase.build.

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

# Show a regular Wulff construction, cubic crystal
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)
```

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

### Create and Plot a Winterbottom Particle

Source: https://wulffpack.materialsmodeling.org/moduleref/winterbottom.html

Instantiates an Icosahedron particle with specified surface energies and twin energy, then generates and saves a plot of the particle. Ensure matplotlib is imported as plt and an axes object 'ax' is available.

```python
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 particle to file

Source: https://wulffpack.materialsmodeling.org/moduleref/core.html

Write the particle to a file. The file format is determined by the filename extension. Currently supports Wavefront .obj files.

```APIDOC
## write

### Description
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.
```

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

### Get Atoms Object with Icosahedral Symmetry

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/icosahedron.html

Retrieves an ASE Atoms object representing the icosahedral structure. It handles special cases for fivefold axes and twin faces to avoid duplication and adjusts atom positions to fill space.

```python
    @property
    def atoms(self) -> Atoms:
        """
        Returns an ASE Atoms object
        """
        atoms = self._get_atoms()

        # Handle fivefold axes and twin faces separately
        # (they will be duplicated otherwise)
        max_projections_twin = [-1e9, -1e9, -1e9]
        twin_normals = [self._twin_form.facets[i].original_normal for i in range(3)]

        # Find max projections onto twin directions
        for atom in atoms:
            for i, normal in enumerate(twin_normals):
                projection = np.dot(normal, atom.position)
                if projection > max_projections_twin[i]:
                    max_projections_twin[i] = projection

        # Now identify all atoms that are
        # close to the maximum projection
        fivefold_atoms = Atoms()
        twin_indices = [set(), set(), set()]
        for atom in atoms:
            for i, normal in enumerate(twin_normals):
                projection = np.dot(normal, atom.position)
                if abs(projection - max_projections_twin[i]) < 1e-5:
                    twin_indices[i].add(atom.index)

        # Since they should not be duplicated we will remove them from
        # the atoms object eventually
        to_remove = list(twin_indices[0].union(*twin_indices[1:]))

        # Identify the central atom
        central_atom = list(twin_indices[0].intersection(*twin_indices[1:]))
        if central_atom:
            assert len(central_atom) == 1
            for twin in twin_indices:
                twin.remove(central_atom[0])
            central_atom = atoms[central_atom[0]]

        # Identify the fivefold axes
        fivefold_axes = []
        fivefold_atoms = []
        for i in range(3):
            fivefold_axes.append(twin_indices[i].intersection(twin_indices[(i + 1) % 3]))
        for fivefold_axis in fivefold_axes:
            fivefold_atoms.append(atoms[list(fivefold_axis)])
            for ind in fivefold_axis:
                for i in range(3):
                    twin_indices[i].discard(ind)
        twin_atoms = []
        for twin in twin_indices:
            twin_atoms.append(atoms[list(twin)])
        del atoms[to_remove]
        tetrahedron_atoms = atoms.copy()

        # Increase the distance from 111 for each vertex to fill space
        middle = np.array([1., 1., 1.])
        middle /= np.linalg.norm(middle)
        for atoms in [tetrahedron_atoms, *twin_atoms, *fivefold_atoms]:
            for atom in atoms:
                if np.allclose(atom.position, [0, 0, 0]):
                    continue
                dist = atom.position - np.dot(atom.position, middle) * middle
                atom.position = atom.position + (_get_icosahedral_scale_factor() - 1) * dist

        # Make 20 grains
        symmetries = self._get_all_symmetry_operations()
        new_positions = []

        # Add the "bulk" of each tetrahedron
        base_tetrahedron = np.array([1., 1., 1])
        new_positions += _get_unique_coordinates(tetrahedron_atoms, symmetries, base_tetrahedron)

        # Add the atoms on the 30 twin boundaries
        base_twin = np.array(sum(atom.position for atom in twin_atoms[0]))
        new_positions += _get_unique_coordinates(twin_atoms[0], symmetries, base_twin)

        # Add the atoms along the fivefold axes
        base_fivefold = np.array(sum(atom.position for atom in fivefold_atoms[0]))
        new_positions += _get_unique_coordinates(fivefold_atoms[0], symmetries, base_fivefold)

        atoms = Atoms('{}{}'.format(self.standardized_structure[0].symbol,
                                    len(new_positions)),
                      positions=new_positions)
        atoms.append(central_atom)
        return atoms
```

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

### Facet Class Initialization

Source: https://wulffpack.materialsmodeling.org/moduleref/core.html

Initializes a Facet object with its normal vector, surface energy, symmetry information, and optional parameters for original grain status and numerical tolerance.

```APIDOC
## Facet(normal, energy, rotation, original_grain=True, tol=1e-05)

A `Facet` carries information about a particular facet, i.e., only one facet out of potentially several that are equivalent by symmetry.

Parameters:
    
  * **normal** (`Union`[`List`[`float`], `Tuple`[`float`]]) – The normal to the surface in Cartesian coordintes
  * **energy** (`float`) – Surface energy (in units of energy per surface area)
  * **rotation** – Symmetry operation (acting on scaled coordinates) that carried an arbtriraily defined “parent facet” to this facet
  * **original_grain** (`bool`) – If True, this facet is part of an “original grain”, i.e., in the case of decahedron/icosahedron, it is part of the first created tetrahedron
  * **tol** (`float`) – Numerical tolerance
```

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

### Get Atoms within Facets - Wulffpack Core

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/base_particle.html

Extracts an ASE Atoms object containing only the atoms that lie within the particle's facets. It calculates bounds based on facet vertices and filters atoms based on their position relative to facet normals. Handles optional center shifts.

```python
mins = [1e9, 1e9, 1e9]
        maxs = [-1e9, -1e9, -1e9]
        for facet in self._yield_facets(only_original_grains=True):
            if facet.original_vertices:
                vertices = facet.original_vertices
            else:
                vertices = facet.vertices
            for vertex in vertices:
                scaled_vertex = np.linalg.solve(self.standardized_structure.cell.T, vertex)
                for i, v in enumerate(scaled_vertex):
                    if v < mins[i]:
                        mins[i] = v
                    if v > maxs[i]:
                        maxs[i] = v

        mins = [int(i) - 1 for i in mins]
        maxs = [int(np.ceil(i)) + 1 for i in maxs]
        repeat = [int(np.ceil(i)) - int(j) for i, j in zip(maxs, mins)]
        atoms = self.standardized_structure.repeat(repeat)
        atoms.translate(np.dot(self.standardized_structure.cell.T, mins))

        if center_shift:
            atoms.translate(center_shift)

        to_delete = []
        for atom in atoms:
            for facet in self._yield_facets(only_original_grains=True):
                if np.dot(atom.position, facet.original_normal) > \
                        facet.distance_from_origin + 1e-5:
                    to_delete.append(atom.index)
                    break
        del atoms[to_delete]
        atoms.set_pbc(False)
        atoms.set_cell([0., 0., 0.])
        return atoms
```

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

### Winterbottom Class Initialization

Source: https://wulffpack.materialsmodeling.org/moduleref/winterbottom.html

Initializes a Winterbottom object, representing the lowest energy shape of a crystalline particle at an interface.

```APIDOC
## Winterbottom Class

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

#### Required 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.

#### Optional Parameters
- **primitive_structure** - 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) - 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) - Numerical tolerance for symmetry analysis, forwarded to spglib. Defaults to 1e-05.
- **tol** (float) - Numerical tolerance parameter. Defaults to 1e-05.

### Example
```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
```
```

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

### Write Particle to File

Source: https://wulffpack.materialsmodeling.org/moduleref/winterbottom.html

Saves the particle data to a file. The file format is determined by the filename extension; currently, Wavefront .obj is supported.

```python
particle.write(filename)
```

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

### Winterbottom Class Initialization

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/winterbottom.html

Initializes a Winterbottom object, representing the lowest energy shape of a crystalline particle at an interface. It requires surface energies, interface direction, and interface energy, and can optionally take a primitive structure and number of atoms.

```APIDOC
## Winterbottom(surface_energies, interface_direction, interface_energy, primitive_structure=None, natoms=1000, symprec=1e-05, tol=1e-05)

### Description
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]) - Required
A dictionary with surface energies, where keys are Miller indices and values are surface energies (per area) in a unit of choice, such as J/m^2.
#### `interface_direction` (tuple) - Required
Miller indices for the interface facet.
#### `interface_energy` (float) - Required
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) - Default: None
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) - Default: 1000
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` (float, optional) - Default: 1e-05
Numerical tolerance for symmetry analysis, forwarded to spglib.
#### `tol` (float, optional) - Default: 1e-05
Numerical tolerance parameter.

### Example
```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
```
```

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

### Import necessary WulffPack and ASE modules

Source: https://wulffpack.materialsmodeling.org/tutorials/basic_usage.html

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

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



```

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

### Write Particle to Wavefront OBJ File

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/base_particle.html

Exports the particle geometry to a Wavefront OBJ file. Supports custom colors for different forms by writing group information.

```python
supported_file_formats = ['obj']
fileformat = filename.split('.')[-1]
if fileformat not in supported_file_formats:
    raise ValueError('File format {} not supported, '.format(fileformat) +
                     'supported formats are: ' + ' '.join(supported_file_formats))
with open(filename, 'w') as f:
    if fileformat == 'obj':
        f.write('# Vertices
')
        for form in self.forms:
            for facet in form.facets:
                for vertex in facet.ordered_vertices[:-1]:
                    f.write('v {:15.8f} {:15.8f} {:15.8f}\n'.format(*vertex))

        f.write('# Faces
')
        vertex_counter = 1
        for form in self.forms:
            # Define a group to be able to color each form separately
            f.write('g {}
'.format(form.parent_miller_indices))
            for facet in form.facets:
                # Tie the face to the right vertices. Count starts from 1.

```

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

### Facet Class Initialization

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/facet.html

Initializes a Facet object with its normal vector, energy, symmetry operation, and optional original grain and tolerance parameters.

```APIDOC
## Facet(normal, energy, symmetry, original_grain=True, tol=1e-5)

### Description
Initializes a Facet object.

### Parameters
- **normal** (Union[List[float], Tuple[float]]) - The normal to the surface in Cartesian coordinates.
- **energy** (float) - Surface energy (in units of energy per surface area).
- **symmetry** (np.ndarray) - Symmetry operation (acting on scaled coordinates) that carried an arbitrarily defined "parent facet" to this facet.
- **original_grain** (bool) - Optional. If True, this facet is part of an "original grain". Defaults to True.
- **tol** (float) - Optional. Numerical tolerance. Defaults to 1e-5.
```

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

### Winterbottom Particle Visualization and Output

Source: https://wulffpack.materialsmodeling.org/moduleref/winterbottom.html

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

```APIDOC
### `view(alpha=0.85, linewidth=0.3, colors=None, legend=True, save_as=None)`

Use matplotlib to view a rendition of the particle.

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

### `write(filename)`

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

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

### Writing Particle to File

Source: https://wulffpack.materialsmodeling.org/moduleref/single_crystal.html

Saves the particle's atomic structure to a file. The file format is determined by the filename extension. Currently, Wavefront .obj is supported.

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

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

### Icosahedron Constructor

Source: https://wulffpack.materialsmodeling.org/moduleref/icosahedron.html

Initializes an Icosahedron object with specified surface energies, twin energy, and optional parameters for primitive structure, number of atoms, and numerical tolerances.

```APIDOC
## Icosahedron(surface_energies, twin_energy, primitive_structure=None, natoms=1000, symprec=1e-05, tol=1e-05)

### 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) – 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) – 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) – Numerical tolerance for symmetry analysis, forwarded to spglib.
* **tol** (float) – 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
```
```

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

### Create Different Nanoparticle Shapes

Source: https://wulffpack.materialsmodeling.org/tutorials/compare_shapes.html

Instantiate SingleCrystal, Decahedron, and Icosahedron particles with the defined surface energies and parameters. These objects represent different crystallographic shapes.

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



```

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

### SingleCrystal Class Initialization

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/single_crystal.html

Initializes a SingleCrystal object for Wulff construction. It takes surface energies, a primitive crystal structure, and optionally the number of atoms, symmetry precision, and tolerance as input.

```APIDOC
## SingleCrystal(surface_energies, primitive_structure=None, natoms=1000, symprec=1e-05, tol=1e-05, symmetry_operations=None)

### Description
A `SingleCrystal` object is a Wulff construction of a single crystalline particle, i.e., a standard Wulff construction.

### Parameters
#### Parameters
- **surface_energies** (dict) - 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** (ase.Atoms, optional) - 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** (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.
- **symmetry_operations** (List[np.ndarray], optional) - This parameter allows one to pass an explicit list of allowed symmetry operations. By default (``None``) the allowed symmetry operations are obtained from :attr:`primitive_structure`.

### Example
```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
```
```

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

### Write Particle to Wavefront .obj File

Source: https://wulffpack.materialsmodeling.org/tutorials/graphics.html

Export a WulffPack particle to a Wavefront .obj file, compatible with 3D modeling software like Blender. Uses the `write` method of the particle object.

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

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

### BaseParticle Methods

Source: https://wulffpack.materialsmodeling.org/_modules/wulffpack/core/base_particle.html

Methods for manipulating and querying the particle.

```APIDOC
## Methods

### `_yield_facets(only_original_grains: bool = False)`

Generate all facets that are included in the facets dictionary.

### `_duplicate_particle(symmetries)`

Duplicate the particle by applying symmetry operations.

Useful for making an icosahedron from a single tetrahedron for example.

#### Parameters

*   **symmetries**: list of NumPy arrays
    Each array a symmetry operation(operating on Cartesian coordinates)
    that should create a duplicate.

### `translate_particle(translation: np.ndarray)`

Translate the particle.

#### Parameters

*   **translation**: np.ndarray
    The translation vector.
```

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

### Initialize Decahedron Particle

Source: https://wulffpack.materialsmodeling.org/moduleref/decahedron.html

Initializes a Decahedron object with specified surface energies and twin energy. Requires importing Decahedron, bulk from ase.build, and write from ase.io. The primitive_structure parameter uses ase.build.bulk to define the atomic structure.

```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
```
Tokens:
Raw