repast4py.checkpoint module

This module includes classes and functions for checkpointing a repast4py simulation.

class repast4py.checkpoint.Checkpoint

Bases: object

Creates a Checkpoint instance that can be used to save the simulation.

The expectation is that the user can save a Checkpoint instance using the dill module to pickle it. Consequently, all the state to save passed to a Checkpoint instance must be pickleable using dill. If that is not the case, then translate the state into something pickleable (e.g., a string or some bespoke representation).

restore(key, restorer, *args)

Restores a value identified by the specified key using the specified Callable.

Parameters:

  • key – the identifying key of the saved value to restore.

  • restorer (Callable) – a Callable that takes the saved value associated with the key, and returns the restored value.

  • args – additional optional arguments that are passed to the restorer in addition to the saved value.

Returns:

The restored value associated with the key.

Examples

Saving and restoring some arbitrary state from a Model object named model.

>>> ckp = Checkpoint()
>>> model_props = [model.a, model.b, model.c]
>>> ckp.save('mprops', model_props)
>>> def restore_props(prop_data, model):
        model.a = prop_data[0]
        model.b = prop_data[1]
        model.c = prop_data[2]
        return model
>>> ckp.restore('mprops', restore_props, model)
restore_agents(restore_agent)

Restores saved agents one by one, returning a generator over the restored agents.

Each saved agent state (see save_agents) is passed to the restore_agent Callable and the result of that call is returned, until there are no more agents to restore.

Parameters:

restore_agent (Callable) – a Callable that takes agent state and returns an Agent.

Examples

Restore an agent implemented in a MyAgent class with two attributes.

>>> def restore_my_agent(agent_state):
        a = agent_state[0]
        b = agent_state[1]
        return MyAgent(a, b)
>>> for agent in ckp.restore_agents(restore_my_agent):
        # do something with agent
restore_network(context, network, create_agent)

Restores any saved networks from this Checkpoint instance. The networks are added to the context, and all the requisite cross-process edges will be created. Note that the context is expected to curently contain restored agents.

Parameters:

  • context (SharedContext) – the model’s context.

  • comm – the current communicator. This will be used to create ghosts and cross process links where necessary.

  • create_agent (Callable) – Callable that can take the Tuple result of an agent save() and return an agent.

  • network (SharedNetwork)

Raises:

ValueError if expected agents are not found in the context. –

restore_random()

Restores the checkpointed random state, setting repast4py.random.seed and repast4py.random.default_rng to the saved state.

restore_schedule(comm, evt_creator, evt_processor=<function Checkpoint.<lambda>>, tag='__default', initialize=True, restore_stop_at=False)

Restores the state of the schedule, and by default initializes the schedule runner.

The saved metadata dictionaries for each currently scheduled event (see schedule_event and schedule_repeating_event) are passed to the evt_creator argument which is expected to return a Callable that can then be scheduled appropriately. If the evt_creator returns IGNORE_EVT, then the event will not be scheduled as part of restoring the schedule. If an evt_processor is specified, then each metadata dictonary and the ScheduledEvent created when restoring and scheduling saved events is passed to that. This can be useful, if, for example, a model needs to cache ScheduledEvent in order to void them before they are executed. Here an evt_processor can add these ScheduledEvent to the model’s cache.

Parameters:

  • evt_creator (Callable) – a Callable (function, method, etc.) that takes the metadata dictionary associated with an event as an argument and returns the Callable to schedule.

  • evt_processor (Callable) – a Callable that that takes the metadata dictionary associated with an event and the ScheduledEvent created by the evt_creator as arguments.

  • comm (Intracomm) – the communicator in which this is running

  • tag – only saved scheduled events whose metadata dictionary ‘tag’ entry matches this tag will be restored.

  • initialize (bool) – if true, then the schedule runner is initialized with schedule.init_schedule_runner, otherwise the schedule runner is not initialized. When restoring, this needs to be True in one call to restore_schedule.

  • restore_stop_at (bool) – if true, then any stop actions will be restored, otherwise it is the user’s responsibility to schedule a stop after restoring the schedule.

Returns:

The repast4py.schedule.runner.

restore_space(context, space)

Places all the agents in the specified context into the specified space at the location saved for that agent. The saved locations for the specified space are looked up using the space’s name.

Parameters:

  • context (SharedContext) – the model’s context containing the agents we want to place into the specified space as the saved locations.

  • space (SharedGrid | SharedCSpace) – the space to restore the agents into.

save(key, value)

Saves arbitrary key value pairs into this Checkpoint.

Parameters:

  • key – an identifying key for the saved value.

  • value – the value to save.

save_agents(agents)

Saves the specified agents’ state to this Checkpoint.

This iterates over each agent and stores the result of each agents’ save() method. The tuple returned by save() must be pickleable using the dill module.

Parameters:

agents (Iterable[Agent]) – the Iterable of Agents to save.

save_network(network, rank)

Saves the specified network to this Checkpoint instance.

Parameters:

  • network (SharedNetwork) – the network to save.

  • rank (int) – the rank of the executing process.

save_random()

Saves the current random state of the repast4py.random.default_rng generator and the py:mod:repast4py.random.seed.

save_schedule()

Saves the currently scheduled events to this Checkpoint.

The state of the repast4py.schedule.runner is saved together with the currently scheduled events (Python Callables), and their metadata. The intention is that user provides enough metadata to reconstruct the scheduled Callable. For example, if the Callable is a Python class that updates some attribute on some agents, then the metadata would record the agent ids of those agents, and the name of the class. That data can then be used to re-create the class when the scheduled is restored.

save_space(context, space)

Saves the specified space into this Checkpointing by saving the space location of all the agents in the context. The saved locations are identified by the space’s name.

Parameters:
repast4py.checkpoint.DEFAULT_TAG: str = '__default'

The default tag in saved event metadata dictionaries

repast4py.checkpoint.IGNORE_EVT: int = 0

Return value indicating that a saved evt should be ignored when restoring the schedule.