Skip to content

Analyzer

StateAnalyzer

Provides basic functionality for analyzing a SimulationState object.

Source code in pylattica/core/analyzer.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
 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
 91
 92
 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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
class StateAnalyzer:
    """Provides basic functionality for analyzing a SimulationState object."""

    def __init__(self, structure: PeriodicStructure = None):
        """Ininitializes the StateAnalyzer with the structure provided.
        The structure is used to filter sites down by site class, if desired.

        Parameters
        ----------
        structure : PeriodicStructure
            The structure to use as the source for site class information.
        """
        self._structure = structure

    def get_sites(
        self,
        state: SimulationState,
        site_class: str = None,
        state_criteria: List[Callable[[Dict], bool]] = None,
    ) -> List[int]:
        """Retrieves a list of site states matching the specified criteria.
        Criteria are expressed as functions or lambdas that take a site state dictionary
        and return a boolean indicating whether or not the site satisfies the criteria.

        Parameters
        ----------
        state : SimulationState
            The simulation state to analyze
        site_class : str, optional
            If desired, a site class to filter down on, by default None
        state_criteria : List[Callable[[Dict], bool]], optional
            A list of functions which must return true for a site to be included in the returned sites, by default None

        Returns
        -------
        List[Dict]
            A list of site IDs satisfying the specified criteria and belonging to the specified site class.
        """
        if state_criteria is None:
            state_criteria = []

        if self._structure is not None:
            sites = self._structure.sites(site_class)
            sites = [state.get_site_state(site[SITE_ID]) for site in sites]
        else:
            sites = state.all_site_states()

        matching_sites = []
        for site in sites:
            site_state = state.get_site_state(site[SITE_ID])
            meets_criteria = True

            for crit in state_criteria:
                if not crit(site_state):
                    meets_criteria = False
                    break

            if meets_criteria:
                matching_sites.append(site[SITE_ID])

        return matching_sites

    def get_sites_where_equal(
        self, state: SimulationState, search_pairs: Dict, site_class: str = None
    ) -> List[int]:
        """Returns sites whose state dictionaries contain values matching the
        search_pairs parameters passed here. For instance, if you wanted every site
        with had a state value for property "B" equal to 2, search_pairs would be:

        {
            "B": 2
        }

        Also supports filtering sites based on site class.

        Parameters
        ----------
        state : SimulationState
            The state to filter sites from.
        search_pairs : Dict
            The dictionary containing key value pairs that must match the site state.
        site_class : str, optional
            The class of sites to consider, by default None

        Returns
        -------
        List[int]
            A list of site IDs corresponding to the matching sites
        """

        def _criteria(site_state: Dict) -> bool:
            for state_key, state_val in search_pairs.items():
                if site_state.get(state_key) != state_val:
                    return False
            return True

        return self.get_sites(state, site_class=site_class, state_criteria=[_criteria])

    def get_site_count(
        self,
        state: SimulationState,
        site_class: str = None,
        state_criteria: List[Callable[[Dict], bool]] = None,
    ) -> int:
        """Counts the sites in the state matching the specified criteria. See documentation
        for get_sites for more details.

        Parameters
        ----------
        state : SimulationState
            The simulation state to search
        site_class : str, optional
            The class of sites to consider, by default None
        state_criteria : List[Callable[[Dict], bool]], optional
            The criteria by which a site should be assessed for filtering, by default None

        Returns
        -------
        int
            The number of sites matching the specified criteria
        """
        return len(
            self.get_sites(state, site_class=site_class, state_criteria=state_criteria)
        )

    def get_site_count_where_equal(
        self, state: SimulationState, search_pairs: Dict, site_class: str = None
    ) -> int:
        """Counts the sites which have state values equal to those specified by search_pairs.
        See get_sites_equal for a specification of the search_pairs parameter.

        Parameters
        ----------
        state : SimulationState
            The state to search for sites.
        search_pairs : Dict
            The state values that must be matched
        site_class : str, optional
            The class of sites to consider, by default None

        Returns
        -------
        int
            The number of sites matching the criteria
        """
        return len(
            self.get_sites_where_equal(
                state, site_class=site_class, search_pairs=search_pairs
            )
        )

__init__(structure=None)

Ininitializes the StateAnalyzer with the structure provided. The structure is used to filter sites down by site class, if desired.

Parameters
PeriodicStructure

The structure to use as the source for site class information.

Source code in pylattica/core/analyzer.py 
11
12
13
14
15
16
17
18
19
20
def __init__(self, structure: PeriodicStructure = None):
    """Ininitializes the StateAnalyzer with the structure provided.
    The structure is used to filter sites down by site class, if desired.

    Parameters
    ----------
    structure : PeriodicStructure
        The structure to use as the source for site class information.
    """
    self._structure = structure

get_site_count(state, site_class=None, state_criteria=None)

Counts the sites in the state matching the specified criteria. See documentation for get_sites for more details.

Parameters
SimulationState

The simulation state to search

str, optional

The class of sites to consider, by default None

List[Callable[[Dict], bool]], optional

The criteria by which a site should be assessed for filtering, by default None

Returns

int The number of sites matching the specified criteria

Source code in pylattica/core/analyzer.py 
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
def get_site_count(
    self,
    state: SimulationState,
    site_class: str = None,
    state_criteria: List[Callable[[Dict], bool]] = None,
) -> int:
    """Counts the sites in the state matching the specified criteria. See documentation
    for get_sites for more details.

    Parameters
    ----------
    state : SimulationState
        The simulation state to search
    site_class : str, optional
        The class of sites to consider, by default None
    state_criteria : List[Callable[[Dict], bool]], optional
        The criteria by which a site should be assessed for filtering, by default None

    Returns
    -------
    int
        The number of sites matching the specified criteria
    """
    return len(
        self.get_sites(state, site_class=site_class, state_criteria=state_criteria)
    )

get_site_count_where_equal(state, search_pairs, site_class=None)

Counts the sites which have state values equal to those specified by search_pairs. See get_sites_equal for a specification of the search_pairs parameter.

Parameters
SimulationState

The state to search for sites.

Dict

The state values that must be matched

str, optional

The class of sites to consider, by default None

Returns

int The number of sites matching the criteria

Source code in pylattica/core/analyzer.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def get_site_count_where_equal(
    self, state: SimulationState, search_pairs: Dict, site_class: str = None
) -> int:
    """Counts the sites which have state values equal to those specified by search_pairs.
    See get_sites_equal for a specification of the search_pairs parameter.

    Parameters
    ----------
    state : SimulationState
        The state to search for sites.
    search_pairs : Dict
        The state values that must be matched
    site_class : str, optional
        The class of sites to consider, by default None

    Returns
    -------
    int
        The number of sites matching the criteria
    """
    return len(
        self.get_sites_where_equal(
            state, site_class=site_class, search_pairs=search_pairs
        )
    )

get_sites(state, site_class=None, state_criteria=None)

Retrieves a list of site states matching the specified criteria. Criteria are expressed as functions or lambdas that take a site state dictionary and return a boolean indicating whether or not the site satisfies the criteria.

Parameters
SimulationState

The simulation state to analyze

str, optional

If desired, a site class to filter down on, by default None

List[Callable[[Dict], bool]], optional

A list of functions which must return true for a site to be included in the returned sites, by default None

Returns

List[Dict] A list of site IDs satisfying the specified criteria and belonging to the specified site class.

Source code in pylattica/core/analyzer.py 
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
65
66
67
68
def get_sites(
    self,
    state: SimulationState,
    site_class: str = None,
    state_criteria: List[Callable[[Dict], bool]] = None,
) -> List[int]:
    """Retrieves a list of site states matching the specified criteria.
    Criteria are expressed as functions or lambdas that take a site state dictionary
    and return a boolean indicating whether or not the site satisfies the criteria.

    Parameters
    ----------
    state : SimulationState
        The simulation state to analyze
    site_class : str, optional
        If desired, a site class to filter down on, by default None
    state_criteria : List[Callable[[Dict], bool]], optional
        A list of functions which must return true for a site to be included in the returned sites, by default None

    Returns
    -------
    List[Dict]
        A list of site IDs satisfying the specified criteria and belonging to the specified site class.
    """
    if state_criteria is None:
        state_criteria = []

    if self._structure is not None:
        sites = self._structure.sites(site_class)
        sites = [state.get_site_state(site[SITE_ID]) for site in sites]
    else:
        sites = state.all_site_states()

    matching_sites = []
    for site in sites:
        site_state = state.get_site_state(site[SITE_ID])
        meets_criteria = True

        for crit in state_criteria:
            if not crit(site_state):
                meets_criteria = False
                break

        if meets_criteria:
            matching_sites.append(site[SITE_ID])

    return matching_sites

get_sites_where_equal(state, search_pairs, site_class=None)

Returns sites whose state dictionaries contain values matching the search_pairs parameters passed here. For instance, if you wanted every site with had a state value for property "B" equal to 2, search_pairs would be:

{ "B": 2 }

Also supports filtering sites based on site class.

Parameters
SimulationState

The state to filter sites from.

Dict

The dictionary containing key value pairs that must match the site state.

str, optional

The class of sites to consider, by default None

Returns

List[int] A list of site IDs corresponding to the matching sites

Source code in pylattica/core/analyzer.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def get_sites_where_equal(
    self, state: SimulationState, search_pairs: Dict, site_class: str = None
) -> List[int]:
    """Returns sites whose state dictionaries contain values matching the
    search_pairs parameters passed here. For instance, if you wanted every site
    with had a state value for property "B" equal to 2, search_pairs would be:

    {
        "B": 2
    }

    Also supports filtering sites based on site class.

    Parameters
    ----------
    state : SimulationState
        The state to filter sites from.
    search_pairs : Dict
        The dictionary containing key value pairs that must match the site state.
    site_class : str, optional
        The class of sites to consider, by default None

    Returns
    -------
    List[int]
        A list of site IDs corresponding to the matching sites
    """

    def _criteria(site_state: Dict) -> bool:
        for state_key, state_val in search_pairs.items():
            if site_state.get(state_key) != state_val:
                return False
        return True

    return self.get_sites(state, site_class=site_class, state_criteria=[_criteria])