Skip to content

SimulationState

SimulationState

Representation of the state during a single step of the simulation. This is essentially a dictionary that maps the IDs of sites in the simulation structure to dictionaries with arbitrary keys and values that can store whatever state is relevant for the simulation.

Additionally, there is a concept of general simulation state that is separate from the state of any specific site in the simulation.

Source code in pylattica/core/simulation_state.py 
 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
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
class SimulationState:
    """Representation of the state during a single step of the simulation. This is essentially
    a dictionary that maps the IDs of sites in the simulation structure to dictionaries with
    arbitrary keys and values that can store whatever state is relevant for the simulation.

    Additionally, there is a concept of general simulation state that is separate from the state
    of any specific site in the simulation.
    """

    def as_dict(self):
        return {
            "state": self._state,
            "@module": self.__class__.__module__,
            "@class": self.__class__.__name__,
        }

    @classmethod
    def from_dict(cls, state_dict):
        state = state_dict["state"]
        state[SITES] = {int(k): v for k, v in state[SITES].items()}
        return cls(state)

    @classmethod
    def from_struct(cls, struct: PeriodicStructure):
        state = cls()

        for sid in struct.site_ids:
            state.set_site_state(sid, {})

        return state

    def __init__(self, state: Dict = None):
        """Initializes the SimulationState.

        Parameters
        ----------
        state : dict, optional
            A state to store. should be a map with keys "GENERAL" and "SITES", by default None
        """
        if state is None:
            self._state = {
                SITES: {},
                GENERAL: {},
            }
        else:
            self._state = copy.deepcopy(state)

    @property
    def size(self) -> int:
        """Gives the number of sites for which state information is stored.

        Returns
        -------
        int
            The number of sites for which state information is stored.
        """
        return len(self.site_ids())

    def site_ids(self) -> List[int]:
        """A list of site IDs for which some state is stored.

        Returns
        -------
        List[int]
        """
        return list(self._state[SITES].keys())

    def all_site_states(self) -> List[Dict]:
        """Returns a list of dictionaries representing the site
        state values.

        Returns
        -------
        List[Dict]
            The state dictionaries for every site in this state.
        """
        return list(self._state[SITES].values())

    def get_site_state(self, site_id: int) -> Dict:
        """Returns the state stored for the specified site ID, if any.

        Parameters
        ----------
        site_id : int
            The ID of the site for which state information should be retrieved.

        Returns
        -------
        Dict
            The state of that site. Returns None if no state is stored under that site ID.
        """
        return self._state[SITES].get(site_id)

    def get_general_state(self) -> Dict:
        """Returns the general state.

        Returns
        -------
        Dict
            The general state.
        """
        return self._state.get(GENERAL)

    def set_general_state(self, updates: Dict) -> None:
        """Updates the general state with the keys and values provided by the updates parameter.

        Parameters
        ----------
        updates : Dict
            The updates to apply. Note that this overwrites values in the old state, but unspecified
            values are left unchanged.
        """
        old_state = self.get_general_state()
        self._state[GENERAL] = {**old_state, **updates}

    def set_site_state(self, site_id: int, updates: dict) -> None:
        """Updates the state stored for site with ID site_id.

        Parameters
        ----------
        site_id : int
            The ID of the site for which the state should be updated.
        updates : dict
            The updates to the state that should be performed.
        """
        old_state = self._state[SITES].get(site_id)
        if old_state is None:
            old_state = {SITE_ID: site_id}

        self._state[SITES][site_id] = {**old_state, **updates}

    def batch_update(self, update_batch: Dict) -> None:
        """Applies a batch update to many sites and the general state. Takes a dictionary
        formatted like this:

        {
            "GENERAL": {...},
            "SITES": {
                1: {...}
            }
        }

        Parameters
        ----------
        update_batch : Dict
            The updates to apply as a batch.
        """

        if GENERAL in update_batch:
            for site_id, updates in update_batch[SITES].items():
                self.set_site_state(site_id, updates)

            self.set_general_state(update_batch[GENERAL])
        else:
            for site_id, updates in update_batch.items():
                self.set_site_state(site_id, updates)

    def copy(self) -> SimulationState:
        """Creates a new simulation state identical to this one. This is a deepcopy
        operation, so changing the copy will not change the original.

        Returns
        -------
        SimulationState
            The copy of this SimulationState
        """
        return SimulationState(self._state)

    def __eq__(self, other: SimulationState) -> bool:
        return self._state == other._state

__init__(state=None)

Initializes the SimulationState.

Parameters
dict, optional

A state to store. should be a map with keys "GENERAL" and "SITES", by default None

Source code in pylattica/core/simulation_state.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
def __init__(self, state: Dict = None):
    """Initializes the SimulationState.

    Parameters
    ----------
    state : dict, optional
        A state to store. should be a map with keys "GENERAL" and "SITES", by default None
    """
    if state is None:
        self._state = {
            SITES: {},
            GENERAL: {},
        }
    else:
        self._state = copy.deepcopy(state)

all_site_states()

Returns a list of dictionaries representing the site state values.

Returns

List[Dict] The state dictionaries for every site in this state.

Source code in pylattica/core/simulation_state.py 
77
78
79
80
81
82
83
84
85
86
def all_site_states(self) -> List[Dict]:
    """Returns a list of dictionaries representing the site
    state values.

    Returns
    -------
    List[Dict]
        The state dictionaries for every site in this state.
    """
    return list(self._state[SITES].values())

batch_update(update_batch)

Applies a batch update to many sites and the general state. Takes a dictionary formatted like this:

{ "GENERAL": {...}, "SITES": { 1: {...} } }

Parameters
Dict

The updates to apply as a batch.

Source code in pylattica/core/simulation_state.py 
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
def batch_update(self, update_batch: Dict) -> None:
    """Applies a batch update to many sites and the general state. Takes a dictionary
    formatted like this:

    {
        "GENERAL": {...},
        "SITES": {
            1: {...}
        }
    }

    Parameters
    ----------
    update_batch : Dict
        The updates to apply as a batch.
    """

    if GENERAL in update_batch:
        for site_id, updates in update_batch[SITES].items():
            self.set_site_state(site_id, updates)

        self.set_general_state(update_batch[GENERAL])
    else:
        for site_id, updates in update_batch.items():
            self.set_site_state(site_id, updates)

copy()

Creates a new simulation state identical to this one. This is a deepcopy operation, so changing the copy will not change the original.

Returns

SimulationState The copy of this SimulationState

Source code in pylattica/core/simulation_state.py 
167
168
169
170
171
172
173
174
175
176
def copy(self) -> SimulationState:
    """Creates a new simulation state identical to this one. This is a deepcopy
    operation, so changing the copy will not change the original.

    Returns
    -------
    SimulationState
        The copy of this SimulationState
    """
    return SimulationState(self._state)

get_general_state()

Returns the general state.

Returns

Dict The general state.

Source code in pylattica/core/simulation_state.py 
103
104
105
106
107
108
109
110
111
def get_general_state(self) -> Dict:
    """Returns the general state.

    Returns
    -------
    Dict
        The general state.
    """
    return self._state.get(GENERAL)

get_site_state(site_id)

Returns the state stored for the specified site ID, if any.

Parameters
int

The ID of the site for which state information should be retrieved.

Returns

Dict The state of that site. Returns None if no state is stored under that site ID.

Source code in pylattica/core/simulation_state.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def get_site_state(self, site_id: int) -> Dict:
    """Returns the state stored for the specified site ID, if any.

    Parameters
    ----------
    site_id : int
        The ID of the site for which state information should be retrieved.

    Returns
    -------
    Dict
        The state of that site. Returns None if no state is stored under that site ID.
    """
    return self._state[SITES].get(site_id)

set_general_state(updates)

Updates the general state with the keys and values provided by the updates parameter.

Parameters
Dict

The updates to apply. Note that this overwrites values in the old state, but unspecified values are left unchanged.

Source code in pylattica/core/simulation_state.py 
113
114
115
116
117
118
119
120
121
122
123
def set_general_state(self, updates: Dict) -> None:
    """Updates the general state with the keys and values provided by the updates parameter.

    Parameters
    ----------
    updates : Dict
        The updates to apply. Note that this overwrites values in the old state, but unspecified
        values are left unchanged.
    """
    old_state = self.get_general_state()
    self._state[GENERAL] = {**old_state, **updates}

set_site_state(site_id, updates)

Updates the state stored for site with ID site_id.

Parameters
int

The ID of the site for which the state should be updated.

dict

The updates to the state that should be performed.

Source code in pylattica/core/simulation_state.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def set_site_state(self, site_id: int, updates: dict) -> None:
    """Updates the state stored for site with ID site_id.

    Parameters
    ----------
    site_id : int
        The ID of the site for which the state should be updated.
    updates : dict
        The updates to the state that should be performed.
    """
    old_state = self._state[SITES].get(site_id)
    if old_state is None:
        old_state = {SITE_ID: site_id}

    self._state[SITES][site_id] = {**old_state, **updates}

site_ids()

A list of site IDs for which some state is stored.

Returns

List[int]

Source code in pylattica/core/simulation_state.py 
68
69
70
71
72
73
74
75
def site_ids(self) -> List[int]:
    """A list of site IDs for which some state is stored.

    Returns
    -------
    List[int]
    """
    return list(self._state[SITES].keys())

size() property

Gives the number of sites for which state information is stored.

Returns

int The number of sites for which state information is stored.

Source code in pylattica/core/simulation_state.py 
57
58
59
60
61
62
63
64
65
66
@property
def size(self) -> int:
    """Gives the number of sites for which state information is stored.

    Returns
    -------
    int
        The number of sites for which state information is stored.
    """
    return len(self.site_ids())