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.