Skip to content

NeighborhoodBuilders

AnnularNeighborhoodBuilder

Bases: NeighborhoodBuilder

This neighborhood builder creates neighbor connections between sites which are within a ring-shaped region around eachother. This region is specified by a minimum (inner radius) and maximum (outer radius) distance.

Source code in pylattica/core/neighborhood_builders.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
class AnnularNeighborhoodBuilder(NeighborhoodBuilder):
    """This neighborhood builder creates neighbor connections between
    sites which are within a ring-shaped region around eachother. This region
    is specified by a minimum (inner radius) and maximum (outer radius) distance.
    """

    def __init__(self, inner_radius: float, outer_radius: float):
        """Instantiates an AnnularNeighborhoodBuilder

        Parameters
        ----------
        inner_radius : float
            The minimum at which two sites are considered neighbors.
        outer_radius : float
            The maximum distance at which two sites are considered neighbors.
        """
        self.inner_radius = inner_radius
        self.outer_radius = outer_radius

    def get_neighbors(self, curr_site: Dict, struct: PeriodicStructure) -> List[Tuple]:
        """Builds a NeighborGraph from the provided structure according
        to the cutoff distance of this Builder.

        Parameters
        ----------
        struct : PeriodicStructure
            The structure from which a NeighborGraph should be constructed.

        Returns
        -------
        NeighborGraph
            The resulting NeighborGraph
        """
        nbs = []
        for other_site in struct.sites():
            if curr_site[SITE_ID] != other_site[SITE_ID]:
                dist = pbc_diff_cart(
                    np.array(other_site[LOCATION]),
                    np.array(curr_site[LOCATION]),
                    struct.lattice,
                )

                if self.inner_radius < dist < self.outer_radius:
                    nbs.append((other_site[SITE_ID], dist))

        return nbs

__init__(inner_radius, outer_radius)

Instantiates an AnnularNeighborhoodBuilder

Parameters
float

The minimum at which two sites are considered neighbors.

float

The maximum distance at which two sites are considered neighbors.

Source code in pylattica/core/neighborhood_builders.py 
145
146
147
148
149
150
151
152
153
154
155
156
def __init__(self, inner_radius: float, outer_radius: float):
    """Instantiates an AnnularNeighborhoodBuilder

    Parameters
    ----------
    inner_radius : float
        The minimum at which two sites are considered neighbors.
    outer_radius : float
        The maximum distance at which two sites are considered neighbors.
    """
    self.inner_radius = inner_radius
    self.outer_radius = outer_radius

get_neighbors(curr_site, struct)

Builds a NeighborGraph from the provided structure according to the cutoff distance of this Builder.

Parameters
PeriodicStructure

The structure from which a NeighborGraph should be constructed.

Returns

NeighborGraph The resulting NeighborGraph

Source code in pylattica/core/neighborhood_builders.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def get_neighbors(self, curr_site: Dict, struct: PeriodicStructure) -> List[Tuple]:
    """Builds a NeighborGraph from the provided structure according
    to the cutoff distance of this Builder.

    Parameters
    ----------
    struct : PeriodicStructure
        The structure from which a NeighborGraph should be constructed.

    Returns
    -------
    NeighborGraph
        The resulting NeighborGraph
    """
    nbs = []
    for other_site in struct.sites():
        if curr_site[SITE_ID] != other_site[SITE_ID]:
            dist = pbc_diff_cart(
                np.array(other_site[LOCATION]),
                np.array(curr_site[LOCATION]),
                struct.lattice,
            )

            if self.inner_radius < dist < self.outer_radius:
                nbs.append((other_site[SITE_ID], dist))

    return nbs

DistanceNeighborhoodBuilder

Bases: NeighborhoodBuilder

This neighborhood builder creates neighbor connections between sites which are within some cutoff distance of eachother.

Source code in pylattica/core/neighborhood_builders.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
class DistanceNeighborhoodBuilder(NeighborhoodBuilder):
    """This neighborhood builder creates neighbor connections between
    sites which are within some cutoff distance of eachother.
    """

    def __init__(self, cutoff: float):
        """Instantiates a DistanceNeighborhoodBuilder

        Parameters
        ----------
        cutoff : float
            The maximum distance at which two sites are considered neighbors.
        """
        self.cutoff = cutoff

    def get_neighbors(self, curr_site: Dict, struct: PeriodicStructure) -> List[Tuple]:
        """Builds a NeighborGraph from the provided structure according
        to the cutoff distance of this Builder.

        Parameters
        ----------
        struct : PeriodicStructure
            The structure from which a NeighborGraph should be constructed.

        Returns
        -------
        NeighborGraph
            The resulting NeighborGraph
        """
        nbs = []
        curr_loc = curr_site[LOCATION]
        curr_id = curr_site[SITE_ID]
        for other_site in struct.sites():
            other_id = other_site[SITE_ID]
            if curr_id != other_id:
                dist = struct.lattice.cartesian_periodic_distance(
                    other_site[LOCATION],
                    curr_loc,
                )

                if dist < self.cutoff:
                    nbs.append((other_id, dist))

        return nbs

__init__(cutoff)

Instantiates a DistanceNeighborhoodBuilder

Parameters
float

The maximum distance at which two sites are considered neighbors.

Source code in pylattica/core/neighborhood_builders.py 
 98
 99
100
101
102
103
104
105
106
def __init__(self, cutoff: float):
    """Instantiates a DistanceNeighborhoodBuilder

    Parameters
    ----------
    cutoff : float
        The maximum distance at which two sites are considered neighbors.
    """
    self.cutoff = cutoff

get_neighbors(curr_site, struct)

Builds a NeighborGraph from the provided structure according to the cutoff distance of this Builder.

Parameters
PeriodicStructure

The structure from which a NeighborGraph should be constructed.

Returns

NeighborGraph The resulting NeighborGraph

Source code in pylattica/core/neighborhood_builders.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def get_neighbors(self, curr_site: Dict, struct: PeriodicStructure) -> List[Tuple]:
    """Builds a NeighborGraph from the provided structure according
    to the cutoff distance of this Builder.

    Parameters
    ----------
    struct : PeriodicStructure
        The structure from which a NeighborGraph should be constructed.

    Returns
    -------
    NeighborGraph
        The resulting NeighborGraph
    """
    nbs = []
    curr_loc = curr_site[LOCATION]
    curr_id = curr_site[SITE_ID]
    for other_site in struct.sites():
        other_id = other_site[SITE_ID]
        if curr_id != other_id:
            dist = struct.lattice.cartesian_periodic_distance(
                other_site[LOCATION],
                curr_loc,
            )

            if dist < self.cutoff:
                nbs.append((other_id, dist))

    return nbs

MotifNeighborhoodBuilder

Bases: NeighborhoodBuilder

This NeighborhoodBuilder constructs NeighborGraphs with connections between points that are separated by one of a set of specific offset vectors.

For example, consider a 2D structure with two types of sites, A and B. Each A site is connected to two other A sites, one offset by 1 unit in each of the positive and negative x directions. Each A site is also connected to two B sites, one offset by one unit in each of the positive and negative y directions, then the spec parameter for this arrangement would look as follows.

{
    "A": [
        [0, 1],
        [1, 0],
        [0, -1],
        [-1, 0],
    ],
    "B": [
        [0, 1],
        [0, -1],
    ]
}

Note that there is reciprocity here between the A and B sites. The A sites list B sites as their neighbors, and the B sites list A sites as their neighbors.

Source code in pylattica/core/neighborhood_builders.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
class MotifNeighborhoodBuilder(NeighborhoodBuilder):
    """This NeighborhoodBuilder constructs NeighborGraphs with connections between
    points that are separated by one of a set of specific offset vectors.

    For example, consider a 2D structure with two types of sites, A and B. Each A
    site is connected to two other A sites, one offset by 1 unit in each of the positive
    and negative x directions. Each A site is also connected to two B sites, one offset
    by one unit in each of the positive and negative y directions, then the spec
    parameter for this arrangement would look as follows.

    ```
    {
        "A": [
            [0, 1],
            [1, 0],
            [0, -1],
            [-1, 0],
        ],
        "B": [
            [0, 1],
            [0, -1],
        ]
    }
    ```

    Note that there is reciprocity here between the A and B sites. The A sites
    list B sites as their neighbors, and the B sites list A sites as their neighbors.
    """

    def __init__(self, motif: List[List[float]]):
        """Instantiates the MotifNeighborhoodBuilder by a motif as described in
        the docstring for the class.

        Parameters
        ----------
        motif : Dict[str, List[List[float]]]
            See class docstring.
        """
        self._motif = motif

        self.distances = EuclideanDistanceMap(motif)

    def get_neighbors(self, curr_site: Dict, struct: PeriodicStructure) -> List[Tuple]:
        """Given a structure, constructs a NeighborGraph with site connections
        according to the motif.

        Parameters
        ----------
        struct : PeriodicStructure
            The structure for which a NeighborGraph should be constructed.

        Returns
        -------
        NeighborGraph
            The resulting NeighborGraph.
        """

        location = curr_site[LOCATION]
        nbs = []
        for neighbor_vec in self._motif:
            loc = tuple(s + n for s, n in zip(location, neighbor_vec))
            nb_id = struct.id_at(loc)
            if nb_id != curr_site[SITE_ID]:
                nbs.append((nb_id, self.distances.get_dist(neighbor_vec)))
        return nbs

__init__(motif)

Instantiates the MotifNeighborhoodBuilder by a motif as described in the docstring for the class.

Parameters
Dict[str, List[List[float]]]

See class docstring.

Source code in pylattica/core/neighborhood_builders.py 
216
217
218
219
220
221
222
223
224
225
226
227
def __init__(self, motif: List[List[float]]):
    """Instantiates the MotifNeighborhoodBuilder by a motif as described in
    the docstring for the class.

    Parameters
    ----------
    motif : Dict[str, List[List[float]]]
        See class docstring.
    """
    self._motif = motif

    self.distances = EuclideanDistanceMap(motif)

get_neighbors(curr_site, struct)

Given a structure, constructs a NeighborGraph with site connections according to the motif.

Parameters
PeriodicStructure

The structure for which a NeighborGraph should be constructed.

Returns

NeighborGraph The resulting NeighborGraph.

Source code in pylattica/core/neighborhood_builders.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
def get_neighbors(self, curr_site: Dict, struct: PeriodicStructure) -> List[Tuple]:
    """Given a structure, constructs a NeighborGraph with site connections
    according to the motif.

    Parameters
    ----------
    struct : PeriodicStructure
        The structure for which a NeighborGraph should be constructed.

    Returns
    -------
    NeighborGraph
        The resulting NeighborGraph.
    """

    location = curr_site[LOCATION]
    nbs = []
    for neighbor_vec in self._motif:
        loc = tuple(s + n for s, n in zip(location, neighbor_vec))
        nb_id = struct.id_at(loc)
        if nb_id != curr_site[SITE_ID]:
            nbs.append((nb_id, self.distances.get_dist(neighbor_vec)))
    return nbs

NeighborhoodBuilder

An abstract class to extend in order to implement a new type of NeighborhoodBuilder

Source code in pylattica/core/neighborhood_builders.py 
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
class NeighborhoodBuilder:
    """An abstract class to extend in order to implement a new type of
    NeighborhoodBuilder"""

    def get(self, struct: PeriodicStructure, site_class: str = None) -> Neighborhood:
        """Given a structure and a site class to build a neighborhood for,
        build the neighborhood.

        Parameters
        ----------
        struct : PeriodicStructure
            The structure for which the Neighborhood of every site should be
            calculated
        site_class : str, optional
            Specify a single class of sites to calculate the neighborhood for,
            by default None

        Returns
        -------
        Neighborhood
            _description_
        """
        graph = rx.PyDiGraph()

        if site_class is None:
            sites = struct.sites()
        else:
            sites = struct.sites(site_class=site_class)

        for site in struct.sites():
            graph.add_node(site[SITE_ID])

        for curr_site in tqdm(sites):
            nbs = self.get_neighbors(curr_site, struct)
            for nb_id, weight in nbs:
                graph.add_edge(curr_site[SITE_ID], nb_id, weight)

        return Neighborhood(graph)

    @abstractmethod
    def get_neighbors(self, curr_site: Dict, struct: PeriodicStructure) -> List[Tuple]:
        pass  # pragma: no cover

get(struct, site_class=None)

Given a structure and a site class to build a neighborhood for, build the neighborhood.

Parameters
PeriodicStructure

The structure for which the Neighborhood of every site should be calculated

str, optional

Specify a single class of sites to calculate the neighborhood for, by default None

Returns

Neighborhood description

Source code in pylattica/core/neighborhood_builders.py 
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
def get(self, struct: PeriodicStructure, site_class: str = None) -> Neighborhood:
    """Given a structure and a site class to build a neighborhood for,
    build the neighborhood.

    Parameters
    ----------
    struct : PeriodicStructure
        The structure for which the Neighborhood of every site should be
        calculated
    site_class : str, optional
        Specify a single class of sites to calculate the neighborhood for,
        by default None

    Returns
    -------
    Neighborhood
        _description_
    """
    graph = rx.PyDiGraph()

    if site_class is None:
        sites = struct.sites()
    else:
        sites = struct.sites(site_class=site_class)

    for site in struct.sites():
        graph.add_node(site[SITE_ID])

    for curr_site in tqdm(sites):
        nbs = self.get_neighbors(curr_site, struct)
        for nb_id, weight in nbs:
            graph.add_edge(curr_site[SITE_ID], nb_id, weight)

    return Neighborhood(graph)

SiteClassNeighborhoodBuilder

Bases: NeighborhoodBuilder

A class which constructs the neighborhood of each site as a function of the class of that site.

Source code in pylattica/core/neighborhood_builders.py 
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
class SiteClassNeighborhoodBuilder(NeighborhoodBuilder):
    """A class which constructs the neighborhood of each site as a function
    of the class of that site."""

    def __init__(self, nb_builders: Dict[str, NeighborhoodBuilder]):
        """Instantiates the SiteClassNeighborhoodBuilder.

        Parameters
        ----------
        nb_builders : Dict[str, NeighborhoodBuilder]
            A mapping of site classes to the NeighborhoodBuilders which
            specify what neighborhood that class of sites should have.
        """
        self._builders = nb_builders

    def get(self, struct: PeriodicStructure) -> Neighborhood:
        """Constructs the neighborhood of every site in the provided
        structure, conditional on the class of each site.

        Parameters
        ----------
        struct : PeriodicStructure
            The structure for which the neigborhood should be calculated.

        Returns
        -------
        Neighborhood
            The resulting Neighborhood object.
        """
        nbhood_map = {}
        for sclass, builder in self._builders.items():
            nbhood = builder.get(struct, site_class=sclass)
            nbhood_map[sclass] = nbhood

        return SiteClassNeighborhood(struct, nbhood_map)

__init__(nb_builders)

Instantiates the SiteClassNeighborhoodBuilder.

Parameters
Dict[str, NeighborhoodBuilder]

A mapping of site classes to the NeighborhoodBuilders which specify what neighborhood that class of sites should have.

Source code in pylattica/core/neighborhood_builders.py 
258
259
260
261
262
263
264
265
266
267
def __init__(self, nb_builders: Dict[str, NeighborhoodBuilder]):
    """Instantiates the SiteClassNeighborhoodBuilder.

    Parameters
    ----------
    nb_builders : Dict[str, NeighborhoodBuilder]
        A mapping of site classes to the NeighborhoodBuilders which
        specify what neighborhood that class of sites should have.
    """
    self._builders = nb_builders

get(struct)

Constructs the neighborhood of every site in the provided structure, conditional on the class of each site.

Parameters
PeriodicStructure

The structure for which the neigborhood should be calculated.

Returns

Neighborhood The resulting Neighborhood object.

Source code in pylattica/core/neighborhood_builders.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
def get(self, struct: PeriodicStructure) -> Neighborhood:
    """Constructs the neighborhood of every site in the provided
    structure, conditional on the class of each site.

    Parameters
    ----------
    struct : PeriodicStructure
        The structure for which the neigborhood should be calculated.

    Returns
    -------
    Neighborhood
        The resulting Neighborhood object.
    """
    nbhood_map = {}
    for sclass, builder in self._builders.items():
        nbhood = builder.get(struct, site_class=sclass)
        nbhood_map[sclass] = nbhood

    return SiteClassNeighborhood(struct, nbhood_map)

StochasticNeighborhoodBuilder

Bases: NeighborhoodBuilder

A helper class for building StochasticNeighborhoods - that is, neighborhoods for which one of several random neighbor sets is chosen each time a site's neighbors are requested.

Source code in pylattica/core/neighborhood_builders.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class StochasticNeighborhoodBuilder(NeighborhoodBuilder):
    """A helper class for building StochasticNeighborhoods - that is,
    neighborhoods for which one of several random neighbor sets is chosen
    each time a site's neighbors are requested."""

    def __init__(self, builders: List[NeighborhoodBuilder]):
        """Instantiates the StochasticNeighborhoodBuilder class.

        Parameters
        ----------
        builders : List[NeighborhoodBuilder]
            A list of builders which will give the neighborhoods that
            might be returned by the StochasticNeighborhood
        """
        self.builders = builders

    def get(self, struct: PeriodicStructure) -> Neighborhood:
        """For the provided structure, calculate the StochasticNeighborhood
        specified by the list of builders originally provided to this class.

        Parameters
        ----------
        struct : PeriodicStructure
            The structure for which the neighborhood should be calculated.

        Returns
        -------
        Neighborhood
            The resulting StochasticNeighborhood
        """
        return StochasticNeighborhood([b.get(struct) for b in self.builders])

__init__(builders)

Instantiates the StochasticNeighborhoodBuilder class.

Parameters
List[NeighborhoodBuilder]

A list of builders which will give the neighborhoods that might be returned by the StochasticNeighborhood

Source code in pylattica/core/neighborhood_builders.py 
65
66
67
68
69
70
71
72
73
74
def __init__(self, builders: List[NeighborhoodBuilder]):
    """Instantiates the StochasticNeighborhoodBuilder class.

    Parameters
    ----------
    builders : List[NeighborhoodBuilder]
        A list of builders which will give the neighborhoods that
        might be returned by the StochasticNeighborhood
    """
    self.builders = builders

get(struct)

For the provided structure, calculate the StochasticNeighborhood specified by the list of builders originally provided to this class.

Parameters
PeriodicStructure

The structure for which the neighborhood should be calculated.

Returns

Neighborhood The resulting StochasticNeighborhood

Source code in pylattica/core/neighborhood_builders.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def get(self, struct: PeriodicStructure) -> Neighborhood:
    """For the provided structure, calculate the StochasticNeighborhood
    specified by the list of builders originally provided to this class.

    Parameters
    ----------
    struct : PeriodicStructure
        The structure for which the neighborhood should be calculated.

    Returns
    -------
    Neighborhood
        The resulting StochasticNeighborhood
    """
    return StochasticNeighborhood([b.get(struct) for b in self.builders])