mapa17 / breakfastclub

A multi-agent system based classroom simulation

Breakfastclub

Breakfastclub is a multi-agent based social simulation platform of a virtual classroom that was developed to study the effect of different personality types on attention and happiness. It was developed as part of a Master Thesis by Manuel Pasieka at the university UNIR, under supervision of Prof. Dr. Michael Kickmeier-Rust.

From the master thesis abstract:

Agent-based models have proven to be a useful tool to study complex social phenomena. In this work we have developed a simulation using an agent-based model of a virtual classroom, simulating the behavior of students and adolescents in an autonomous study group. The agent cognition is based on the widely used Big-Five personality trait model, and agent behavior has been aligned with empirical studies showing how specific person- ality traits correlate with academic success. The simulation software was used to compare how different classroom compositions with an increasing ratio of students with Attention- deficit hyperactivity disorder (ADHD) prototypical personality traits affect the classroom dynamics. We found a very strong effect of ADHD students on the mean classroom hap- piness and attention. Even a very small number of ADHD students can cause a shift in the behavior of None-ADHD students, decreasing their mean happiness and attention, in addition to more frequent classroom wide quarrels.

Latest Development

The latest version is v2.0 and can be found here

Downloads

Binaries are provided for the Windows and macOS platforms compressed with 7zip

• Windows
• macOS

Documentation

The master thesis itself is the most complete documentation of the project and can be found here

A short summary is available in form of a presentation here

A few special topics and a presentation of the project can be found here ...

Examples on how to run the simulation can be found in the working directory ...

breakfastclub's Issues

Make the RETRY_THRESHOLD be based on the agents consciousness

Currently the RETRY_THRESHOLD is a constant value for each action. Make it a function of the agents consciousness. Where higher level of consciousness cause more retries.

Make agents traverse each other like ghosts

Maybe path finding would be much easier if agents could just traverse each other like ghosts. How to achieve that? Its not by simple removing the collider ...

Only StudyAlone if next to to table?

Should Agents only be executing the Action StudyAlone if they are next/ontop of the individual table? Because at the moment the Study alone Action is executed and can even finish before the agent reaches the table.

Random Walk during Break

Visualize Agent Status in UI

Implement some basic MouseOver Display that shows what an Agent is up to, once the mouse hovers over the agent.

Make # retries depend on personality

Calculate the 'RETRY_THRESHOLD' as a function of personality (consciousness)

Change the AgentBehavior, reflecting that they are personal to an agent

Change the definition of AgentBehavior passing a Agent reference to the constructor instead of passing ti to each call.

The Action is not static anymore, but holds Agents specific information, and this should be reflected in the definition.

Agent don't get angry

Problem

Agent don't loose happiness.

Behavior

Agents never quarrel

Description

The cognitive model produces a loss of happiness only in the case the agents have to wait.

This happens only if they cannot perform the action that suits them best.
Relevant actions at the moment are

• Study Alone
• Study in a Group
• Take a break
• Chat

Only Study in a Group has a dependency on others that is relevant (needs others to study with)
but at the moment the agent will start studying by itself, and the Action scored will diminish.

So the agent never enters a waiting state, and therefore cannot become unhappy.

Solutions

• Sit on the table and go into action waiting with the desire to study in a group. The desire must be evaluated before all actions. But this goes completely against the current implementation.
  The same should happen with Chatting. The Agent should not simply start to chat, but go into waiting and have the desire to chat (in addition to interact with the target agent)
  So while the target agent does not chat, the source agent gets angry.

• Add the cognitive model to cause unhappiness with other things than waiting (for example working in groups although the agent would prefer to study alone.

Chosen Solution

Keep the cognitive model, but don't just perform an action that is not satisfied, but go to wait. In addition one can get rid of the reduced score by studying alone and not chatting.

Add agent interactions for StudyGroup

Study Group needs a set of agent interactions similar to chat.

• Entering into a study group
• Leaving a study group

Add classroom logging

Classroom should log values like

• Turn
• Noise level
• Mean Energy + Standard deviation
• Mean Happiness + Standard deviation

Make Quarrel a Agent interaction

Quarrel is up till now a solo action. Make it an Agent interaction!

Show game paused in UI

Make a simple text appear when the game is paused!

Agents never gets up from table

Once an agent tries to engage in a group study and takes a seat, it never gets up again.

Implement GroupStudy agent interaction

Agents can only learn in groups if

• They have a seat on a shared table
• There are other agents in executing group studies

One agent has to start a study group; this could be implemented by putting the agent on a shared table and start a group learning, but reducing the score because of the missing study partners. If others join this bias will be removed.

How to make actions more persistent

Problem

In the current version, agents normally switch actions at each iteration.

• This is in part because the thresholds and meta parameters of the different actions are untuned
• And because it can happen that two actions produce very similar thresholds and than the agent just toggles between the two.

Solutions

Explicit Bias

The agent could be more persistent by adding a bias to the current task. That bias could be exponentially decreasing over time ...

This has the benefit that one could include consciousness into the model ...

Tune action score

One could try to tune the action scoring, although i can imagen that this type of race condition and flip-flop behavior would re-appear.

Minimum number of turns

One could set a minimum number of tourns an action has to be performed. One could even include consciousness into this by making that number be based on consciousness.
It would be less dynamic/flexible than the score bias, but more explicit.

Chosen Solution

I will go for the Explicit Bias for now, because it builds on the scoring system, I like the idea of exponential decay of interest, and dependency on consciousness.

What happens if a agent gets convinced to chat/quarrel

If an agent gets convinced to chat, should this only change its action or desire as well.?

Put Name Label on top of agent

Jep do that

StudyAlone happens without approaching table

Agents Perform StudyAllone without being at the table, and not going there either.

This should not happen. They should approach the table when starting to execute the action.

Use studentname in status messages

Instead of using the Unity game object name, use the studentname in status messages

Handle leaving chat

The agent should react to the other agent leaving a chat.

If the agent really wants to continue chatting it should start to search for someone else.
If not, the chat simple ends ...

Add openness to Attention?

The personality trait Openness is unused at the moment. It would make sense to have it influence attention. As high levels of openness are correlated with engagement.

Add agreeableness and Neuroticism to Quarrel

Make the score for quarrel depend Agreeableness and Neuroticism

Implement Noise distraction

Make Studying impossible as soon as the noise level in the classroom gets higher than some personality (consciousness) defined threshold.

Resolve deadlock

Problem

We have the situation that an Agent is so unhappy that it wants to quarrel, but does not have the energy to do so.

Behavior

The agent has the Desire to Quarrel, but can only perform Wait. Its Stuck.

Implement Chat

Problem

How to implement chatting function? Who should chat with who and where?
In order to chat is it enough to want it, or must the other agent chat too?
Is chatting contagious? Effecting the other agent? To what extend? Which personality trait influences this?

Possible solutions

Who

• Random other agent
• The last agent one interacted with

Where?

• The new chatter goes to the other agent
• They meet somewhere on a chatting spot

Conditioned on other agent

• No, one can chat without the other having to do so too
• The other agent has to execute or desire action Chat
• The other agent will change its action to chat

If contagious how?

• This needs a complete agent interaction system

Solution

So I think it should be the following

• A chatter selects another agent by random
• Approaches the other agent
• Will start chatting (similar to GroupStudy)
• The other agent might be convinced to chat too

Handle accept to chat

Accepting a chat with someone has to be handled, if one just calls the chat action, the agent searches for someone to chat, although it already has someone.

Make Agents attention depend on noise level

Currently the agents attention is defined by its Energy and Happiness. In addition make it dependent on the noise level in the classroom.

Refactor BehaviorActions to include a wait state

Problem

There are several issues with Actions that depend on other Agents and that have a kind of waiting to be executed state.

Behavior

It happens that some Action.end() is not called correctly, because the current Action is Wait() with a Desire being Action(). This is particularly problematic for the Action StudyGroup that reserves a seat at a group table See issue #22.

Solutions

There are múltiple options

• Refactor everything making are more simplified Agent state machine. Which has the downside of being less modular and the agent has to keep track of all internal info of an action (otherAgent, reserved seat, ...)
• Implement new actions like WaitforChat(), WaitforQuarrel(), WaitforGroupStudy(), but the question is how do those actions enforce that Chat(), Quarrel() GroupStudy() will be called?? At the moment the Action scores are calculated independently. And it should stay like that.
• Make the Wait State part of each Action. So each Action can explicitly be in a state of Waiting or execution. In general it would be: Inactive, Waiting, Executing

Chosen Solution

I will try the last option of explicit States in each Action. This keeps things modular, makes them more explicit and removes Wait as a separate Action.
So the downside is that Wait() has to be implemented everywhere, but there can be a base implementation in AgentBehavior().

Iteration time

Iteration time in the Update() callback of MonoBehaviour is not fixed. see

Better move the AI and logic related things to the FixedUpdate() callback, and set the iteration time to something like 0.1 sec as mentioned here

Issues switching Actions

There is some issue when switching actions (for example if the agent gets convinced to chat with another).

Make the starting a new action a separate function, call it from evaluate_action() and handle_interaction().

Make Wait be effected by Neuroticism

Make agents with higher level of Neuroticism suffer a strong happiness decrease.

Restructure Project

Restructure the project folder

• Removing the different old unity test projects
• Create a single Unity Project folder
• Create a folder for documentation and images
• A folder for tools (analysis and visualization)
• A folder for builds and releases (in binary for different platforms)

Adding action prohibiting factors

Add several factors that prohibit the execution of an action

• Too high noise for Studying (needs agent personality dependency, only consciousness?)
• For GroupStudy add dependency on other agents

Random Walk during Wait

Agents should perform a random walk during wait.

Build analysis tools

Create python scripts that will plot summary graphs based on log files.

The summaries should contain

• Classroom Noise
• Medium Energy + Std deviation
• Medium Happiness + Std

Tool to extract Stats

Build a tool that read the complete log file and extract the stats only lines, splitting AgentX and Classroom data into separate CSV files, parsing the corresponding fields.

Set Attention to zero in case of no study

During any action that is not studying, set the value of attention to 0.0, so the aggregated mean can be used to evaluate the class as a whole over time.

Include an end action to all behaviors

Create one additional callback for agent behavior called

endAktion(Agent, agent)

that is called when ever the agent switches or ends an action.

Extend the log format

Make the default log format one that has fields for the state of agents

Accepting quarrel fails

Something strange is happening when an agent accepts a quarrel.

It seems like its dropping to quarrel with other agents at that time. They can definitely quarrel as a group ...

Implement a more useful action description

Each BehaviorAction should have a

public string description() function that includes the name of the action + some useful meta info (like who the action is performed with, or where)

Maybe don't try to chat with a angry agent?

Maybe an agent should not try to chat with a agent that is either quarreling or has the desire to do so?

Because unhappy agents won't get to the low state in order to recover?

Visualize user effect on Simulation

The idea

This is an idea concerning a way to provide feedback to an user interacting with the simulation, about the effect its her actions on the outcome of the simulation.

In the best of worlds, the user would be able to track the effect of her actions during the simulation or after wards by how they change some aggregated properties (e.g. average happiness and average attention).

One could imagine a two dimensional plot showing the outcome of the simulation without user interaction as a single point. Each interaction causes the appearance of another point that is generated by running the simulation until its 'end' (defined # of iterations) without any further user interaction. So we have something like a spanning tree of iteration instances that, where a new branch forks every time the user performs an action. Each path is run to its end, and is than evaluated and visualized.

The user would be able to see the effect of each of her actions on the aggregated result.

Implementation

In order for this to work, there are two requirements

Determinism

The simulation must be deterministic, apart from an initial seed, and the user interactions.

A headless mode

The simulation must be executable in a headless mode which will be injected with recorded user interactions.

Scale Action durations

Problem

Actions don't last long enough. They are often terminated after only 3-4 turns.

Behavior

Agents start an action and move about in the class, but switch so rapidly between tasks that its a continuous stop and go.

It would be nice if they would last at least 10 turns.

Solutions

• One could change the Energy and Happiness increments (scaling them?)
• One could give a higher score bonus to the current task

Implementation

I think it would be best to first scale the Energy/Happiness increments, and if they problem persists, adapt the score bonus.

Analysis tools to compare simulation

Create some tools and visualization to compare two consecutive simulation runs.

Change target for chat after X retries

Similar to Quarrel, change the target agent for chatting after X retries.

Agent interaction system

There should be some Agent interaction possible.

After evaluating_current_action() the agent should take care of possible interactions of other agents with it.

This could be implemented either using the Unity Events, or some manned list.

• So first learn about Events in Unity.

Add markers for user intaction

Once we have user interactions, add some visual markers to the analysis plots.

Flexible Agent

Agents either perform the highest scored action (what they want mostly) or none (wait).

One could imagen maybe a more flexible agent that based on some personality is willing to try the second or third highest ranked action ...

Choose tables randomly

At the moment the agents iterate the table lists in order. Make them select tables by random, or select the last table they choose.