Simulation

Description

sim = Simulation(name, T_sim, [addTimestamp = false], [resultsDirectory = [pwd filesep 'Results']]);

The simulation object represents the actual set simulation. It handles the simulation execution and shared information between the agents.

A simulation is defined by the simulation time T_sim, the agents that should be simulated and the plots that should be produced.

The actual simulation is run as a discrete for loop over the simulation time, with the time step between global steps being the time step of the slowest agent. Inside this loop, the actual local simulation steps take place in a secondary loop where the agents are called in order and frequency proportional to the relation of their time step size to each other. I.e., the slowest agents executes first, the second slowest second, the third slowest third. The slowest agent $i = 1$ is executed once, the second agent $i = 2$ is executed a total of $T_{s,1}/T_{s,2}$ times, but after each execution of $i = 2$, agent $i = 3$ will execute $T_{s,2}/T_{s,3}$ many times, etc.

Since the fractions $T_{s,i-1}/T_{s,i}$ must be integers, the time steps of the agents must be even multiples of each other. This also ensures that all agents have a small lowest common multiple at which the agents meet.

Note that the first time step in the horizon time steps (agent.config.T_s) defines the agent's local simulation time step.

Partitioning the simulation loop into an outer global loop and a inner local loop makes it easy to track and highlight the moment all agents are aligned. For distributed or hierarchical control algorithms, this moment can be used to update information across agents (e.g. adjusting diverted states) or to negotiate a consensus trajectory for the next iterations.

Properties

Public

Property	Type	Description
T_sim	scalar	simulation time
simulationName	string	simulation name for storing result
agents	struct	struct of agents added to the simulation
initialSeed	integer	initial seed for seeding random number generator
timestepSeeds	[]	seed generated for each timestep for better reproduceability
negotiationOrder	function_handle	fixed negotation order
negotiationCallback	function_handle	callback for user defined negotiation
resultDirectory	string	directory in which to store simulation results, default is name + timestamp (if enabled) + "/Results/", if resultDirectory not set in constructor
shared	struct	data shared between agents
progress	struct	simulation progress data
plots	cell	list of figures to be plotted
config	struct	simulation configuration

Protected

Property	Type	Description
T_s_max	scalar	largest time step between all agents
logFileHandle	integer	File handle of the log file of the simulation

Read-only

Property	Type	Description
loopOrder	[]	agent call order within a timestep
k_sim	integer	current global timestep

Configuration

Field	Default	Description
enablePlots	true	Enable/disable plotting
livePlot	true	Enable/disable live plotting (so at each agent timestep) globally
storeResults	true	Enable/disable storing of simulation results
storePlots	true	Enable/disable storing of plots
autoSave	false	If false auto save is disabled. To enable, set autoSave to number of steps between auto saving. E.g. autoSave = 100 will cause PARODIS to auto save results every 100 steps
doCopyCSVSources	false	Enable/disable copying csv-sources once (at the beginning) to 'Results/simulationName/sources'
doCopyCallingScript	true	Enable/disable copying script from which runSimulation() is called to 'Results/simulationName/'

Negotiation

At the beginning of each global time step, before local iteration begins, a negotiation between the agents can take place. The agents each can define a negotiation callback, with which the user can define how each agent engages in the negotiation. See the Agent documentation for more detailed information about the callback.

The negotiation can happen in one of two ways:

• A fixed call order, defined in negotiationOrder, where each entry in the cell array is the name of an agent. The agents' doNegotiation method will be called in the exact order defined in the array.
• A user defined negotiationCallback can be set. If it is set, it overrides the fixed negotiation order (if it was set). The callback is passed the simulation object as an argument, which enables the user to access and manipulate the entire simulation state, if necessary. That way, any arbitrary consensus algorithm can be implemented.

Exchanging information between agents

To exchange information between agents, especially during negotiation, the simulation object offers the shared struct as a public property. Agents can freely store and read information in and from this struct. Note that the struct will be cleared after each global simulation step has been performed.

Progressing (update of status in Matlab command window)

To have a direct look at the simulation's progress, the current state of the simulation loop as well as of the agents is printed in the Matlab command window. To this end, a structure progress is stored as a class property and updated within the simulation loop. progress has ... fields:

Fieldname	Description
currentProgress	Char array with current progress message.
previousProgress	Char array with former/previous progress message
loopAgentStep	Vector with as many entries as there are agents. Integer value for each agent with its current loop step.
loopAgentStepMax	Vector with as many entries as there are agents. Integer value for each agent with maximum number of steps in simulation loop.
PARETO	TODO
negotiationStep	TODO: not implemented yet
overallInPercent	Overall simulation progress in percent
previousDebug	TODO: Do we need this? not used so far
previousDebug	TODO: Do we need this? not used so far

Printing the progress inside the command window without constantly adding new lines is done by deleting the previous message before printing the new one. This is achieved by.... TODO