State Dictionary¶
The global state
dictionary is used to hold a collection of variables and arrays defining the state of a simulation. It is propagated through the modules during a simulation: modules operate and communicate with each other by reading and writing entries to the state
dictionary.
The state
dictionary thus serves two purposes:
Define the global simulation parameters (e.g. materials parameters) that are common to several simulation modules
Serve as a memory buffer for modules to store / retrieve information (e.g. force calculation modules write nodal forces into the
state
dictionary so that other modules can fetch them)
Global simulation parameters¶
Before initializing modules and running a simulation, the state
dictionary must be initialized with the global simulation parameters, e.g.
state = {
"crystal": 'fcc',
"burgmag": 2.55e-10,
"mu": 54.6e9,
"nu": 0.324,
"a": 6.0,
"maxseg": 2000.0,
"minseg": 300.0,
"rtol": 10.0,
"rann": 10.0,
"nextdt": 1e-10,
"maxdt": 1e-9,
}
The global simulation parameters are generally those parameters that are shared by several modules and defining them in the state
dictionary ensures that there value will consistent across the different modules used in a simulation. Some parameters are required and other are optional, although it is good practice to specify a maximum number of these. A description of the typical parameters is given at Setting up a simulation section.
By specification, the state
dictionary needs to be passed as an argument to modules constructors.
Module state variables¶
Modules can write and read entries in the state
dictionary. By specification, some modules are required to populate or look up for certain items in the state
dictionary. For instance, the NodeForce()
method of a CalForce
module is required to write node forces information into the state
dictionary while the Mobility()
method of a MobilityLaw
module is required to look up for the nodal forces values stored in the state
dictionary, e.g.
calforce = CalForce(state=state, ...)
mobility = MobilityLaw(state=state, ...)
# Compute nodal forces and store them into the state dictionary
state = calforce.NodeForce(N, state)
print('nodal forces', state["nodeforces"])
# Compute nodal velocities from the nodal forces stored into the state dictionary
state = mobility.Mobility(N, state)
print('nodal velocities', state["nodevels"])
In general, each module is free to dump variables into the state
dictionary, e.g. to save information or communicate with other modules. A good rule for determining variables that need to be saved by a module is to consider the state
dictionary as information required to restart a simulation from the current state.