Skip to content

StructureBuilder

StructureBuilder

Bases: ABC

An abstract class for building structures out of motifs and lattices. In general. this class works by tiling space to an extent specified, and then filling that space according to the motif (mapping of site types to locations within the unit cell) provided.

Source code in pylattica/core/structure_builder.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
class StructureBuilder(ABC):
    """An abstract class for building structures out of motifs and lattices. In general.
    this class works by tiling space to an extent specified, and then filling that
    space according to the motif (mapping of site types to locations within the unit cell)
    provided.
    """

    frac_coords = False

    def __init__(self, lattice: Lattice, motif: Dict[str, List[Tuple]]):
        """Instantiates a StructureBuilder using a Lattice and a motif.

        Parameters
        ----------
        lattice : Lattice
            The Lattice with which space will be tiled.
        motif : Dict[str, List[Tuple]]
            The motif with which sites will be placed inside the structure. These motifs
            are given by a mapping of site type (str) to list of locations inside
            the unit cell that that site type exists.
        """
        self.lattice = lattice
        self.motif = motif

    def build(self, size: Union[Tuple[int], int]) -> PeriodicStructure:
        """Builds a structure with the provided size.

        Parameters
        ----------
        size : Union[Tuple[int], int]
            Either an integer or a tuple of integers specifying the extent
            of the desired structure in each dimension.

        Returns
        -------
        PeriodicStructure
            The resulting structure.

        Raises
        ------
        ValueError
            If the size is a tuple that is not of length equal to the lattice
            dimension, a value error is thrown. In other words, you must specify
            size along each dimension of the lattice.
        """
        if isinstance(size, tuple):
            if not len(size) == self.lattice.dim:
                raise ValueError(
                    f"Desired structure dimensions, {size}, does not match "
                    "dimensionality of lattice: {self.lattice.dim}"
                )
        else:
            size = [size for _ in range(self.lattice.dim)]

        return PeriodicStructure.build_from(
            self.lattice, size, self.motif, frac_coords=self.frac_coords
        )

__init__(lattice, motif)

Instantiates a StructureBuilder using a Lattice and a motif.

Parameters
Lattice

The Lattice with which space will be tiled.

Dict[str, List[Tuple]]

The motif with which sites will be placed inside the structure. These motifs are given by a mapping of site type (str) to list of locations inside the unit cell that that site type exists.

Source code in pylattica/core/structure_builder.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def __init__(self, lattice: Lattice, motif: Dict[str, List[Tuple]]):
    """Instantiates a StructureBuilder using a Lattice and a motif.

    Parameters
    ----------
    lattice : Lattice
        The Lattice with which space will be tiled.
    motif : Dict[str, List[Tuple]]
        The motif with which sites will be placed inside the structure. These motifs
        are given by a mapping of site type (str) to list of locations inside
        the unit cell that that site type exists.
    """
    self.lattice = lattice
    self.motif = motif

build(size)

Builds a structure with the provided size.

Parameters
Union[Tuple[int], int]

Either an integer or a tuple of integers specifying the extent of the desired structure in each dimension.

Returns

PeriodicStructure The resulting structure.

Raises

ValueError If the size is a tuple that is not of length equal to the lattice dimension, a value error is thrown. In other words, you must specify size along each dimension of the lattice.

Source code in pylattica/core/structure_builder.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def build(self, size: Union[Tuple[int], int]) -> PeriodicStructure:
    """Builds a structure with the provided size.

    Parameters
    ----------
    size : Union[Tuple[int], int]
        Either an integer or a tuple of integers specifying the extent
        of the desired structure in each dimension.

    Returns
    -------
    PeriodicStructure
        The resulting structure.

    Raises
    ------
    ValueError
        If the size is a tuple that is not of length equal to the lattice
        dimension, a value error is thrown. In other words, you must specify
        size along each dimension of the lattice.
    """
    if isinstance(size, tuple):
        if not len(size) == self.lattice.dim:
            raise ValueError(
                f"Desired structure dimensions, {size}, does not match "
                "dimensionality of lattice: {self.lattice.dim}"
            )
    else:
        size = [size for _ in range(self.lattice.dim)]

    return PeriodicStructure.build_from(
        self.lattice, size, self.motif, frac_coords=self.frac_coords
    )