Introduction

Welcome to The Violet User Guide, the place-to-be for everything about the Violet simulator. In this guide, we will have a more detailed look on how to use Violet for your own simulations.

If you're simply looking for which functions and classes Violet has in store for you, then you can also check out Violet's API Reference. While the API documentation goes in-depth on specific functions and attributes, this User Guide tries to explain where to start, and which hidden superpowers are available to you.

What is Violet anyway?

Many simulator frameworks exist, and for this course you're free to experiment with others as well, but Violet is tailor-made for the course Project Collective Intelligence.

Violet is a small framework which builds on top of PyGame, an easy-to-use Python package for game development. Now, you don't really need to understand how PyGame works, as Violet hides all the complexity behind some easy to use functions and classes. However, if you have some cool ideas which Violet doesn't support out-of-the-box, such as creating a player-controllable agent, then Violet doesn't get in your way either. You can always drop down a level and call any PyGame function that you want, such as polling the event queue or checking which keys are currently pressed.

In fact, you'll notice that Violet's Agent class, which will be the foundation of your simulations, is simply a wrapper around PyGame's Sprite class, but with some helpful additions which we'll get to later.

Technicalities aside, you probably won't be using Violet beyond the scope of this course. And that's a good thing! This course is all about you learning how to conduct empirical research in the field of collective intelligence, no matter which simulator you chose to use! Therefore, Violet tries to get out of your way as often as it can. Want to change the image of the agent? That's just one line of code away! How about querying agents that are in proximity of the agent? Well, perhaps that's two lines of code. 😉

With that out of the way, let's build some simulations!

Getting started

Installation

Installing Violet is just a simple pip install away.

pip install -U violet-simulator

Please do note that Violet requires Python 3.9 or later.

Quick start

Below we show a simple snippet that creates a new simulation, adds 500 agents and then runs the simulation.

from vi import Agent, Simulation

(
    Simulation()
    .batch_spawn_agents(500, Agent, images=["examples/images/white.png"])
    .run()
)

The snippet above will add 500 instances of the Agent class to the simulation, with each agent defaulting to the first image, which is white.png. All agents are positioned randomly and automatically wander through the environment.

Agent quick start

To add custom logic to your agents, you can inherit the Agent class and override the update method with your own.

from vi import Agent, Config, Simulation


class MyAgent(Agent):
    def update(self):
        if self.in_proximity_accuracy().count() > 0:
            self.change_image(1)  # red
        else:
            self.change_image(0)  # white


(
    Simulation(Config(radius=15))
    .batch_spawn_agents(
        500,
        MyAgent,  # 👈 use our own MyAgent class
        images=[
            "examples/images/white.png",
            "examples/images/red.png",
        ],
    )
    .run()
)

Here we create a new class called MyAgent in which we inherit Agent. We inherit the Agent class so that our agent is drawn to the screen automatically.

In our update function we check whether there are any agents close to our current agent. If there is at least one agent nearby, we change our image to index 1 of the images list, in this case resulting in us selecting red.png. However, if no one is around, we revert the image back to white.png.

Last but not least we make sure to spawn our newly created MyAgent class inside the batch_spawn_agents function. In addition, we change the radius (the agent's visibility) from the default of 50 pixels to 15 pixels by modifying the radius configuration value.

Reference guide

Want to have a look at all the functions and classes that Violet has to offer? The API reference is the place-to-be:

Python API

Violet - User Guide