Examples Gallery
Explore what’s possible with vidigi through these hands-on examples.
SimPy Examples
A collection of models built using the SimPy framework.
A very simple example with one server
The simplest possible starting point - a single-step SimPy model with just one server. This example walks through using vidigi's EventLogger helper class to capture arrivals, queueing and resource use with the minimum of code changes to an existing model.
A slightly more complex example with multiple servers
Building on the single-server example, this model introduces multiple servers, so we need a way to track which specific resource each entity is using. Here we bring in vidigi's VidigiStore class, a drop-in replacement for SimPy's Resource that keeps this tracking automatic.
A very simple example with one server - avoiding the vidigi logger class
Not everyone wants to use vidigi's EventLogger helper class. This example strips things back to show the minimal set of columns and events vidigi actually needs, so you can build and populate your own event log by hand if that fits your model better.
A Simple Animation of a One-step SimPy Model
The simplest possible vidigi animation - a single-step SimPy model with one queue and one resource. It's a good first stop for seeing the full logging-to-animation pipeline, and also shows what happens - and how to display it more clearly - when a queue grows larger than the space available to show it. This animation also makes use of a custom background.
Animation of a SimPy Model with Branching and Multiple Steps
A more realistic pathway, where entities can branch down different routes and pass through multiple queueing and resource-use steps. Also demonstrates 'setup_mode', which overlays a coordinate grid on your background image to help you place resources and queues accurately.
Using the VidigiPriorityStore to Simplify Model Code Changes with Priority Resources
Extends the VidigiStore approach to priority-based resource requests, using VidigiPriorityStore. Entities with a higher priority can jump the queue for a resource while keeping the same familiar 'with ... request()' syntax.
Examples from Outside of Healthcare: Carwash
A vidigi-animated version of the classic carwash example from the SimPy documentation. It's a good demonstration of how little needs to change to bring logging and animation to a model built entirely outside a healthcare context.
Ciw Examples
Models built using the Ciw library.
A More Complex Ciw Example with Backgrounds
A more involved Ciw model, taken from the official Ciw tutorial, animated with a custom background image. Shows how vidigi's Ciw helpers scale up to handle more complex network-of-queues models.
A ciw 2.x example
A simple queueing model built with Ciw rather than SimPy, showing how to convert Ciw's own simulation records into a vidigi-compatible event log. Based on a published reproducible Ciw model example from Monks, Harper & Heather (2023).
Salabim Examples
Models built using the Salabim package.
A Simple Salabim Model
vidigi isn't tied to SimPy - here it's paired with Salabim instead. Using the classic 'bank with three clerks' example from the Salabim documentation, we show that the same logging and animation approach carries across to a different simulation engine with only minor changes.
Agent Based Simulation (ABS) Examples
These examples look at how vidigi could be used for agent based simulation instead.
Using Vidigi to Visualise an Agent-Based Simulation (ABS)
vidigi isn't built for agent-based simulation, but with a little creativity it can still animate one - here using the Mesa package. Shows how to capture agent positions at each step of an ABS model so vidigi can render them like any other simulation.
Advanced Examples
Advanced examples with more complex elements introduced. These are primarily written in SimPy, but a lot of the principles could be applied to ciw or other examples too.
Visualising Entities with Different Priorities
Shows how to visualise entities with different priorities competing for the same resource, using VidigiPriorityStore. Higher-priority entities are served first, and the animation makes that queue-jumping visible at a glance.
Managing Higher Numbers of Resources with Resource Wrapping
Looks at what goes wrong when you have a larger number of identical resources that haven't been wrapped for vidigi tracking, then shows how wrapping them fixes it. Useful when scaling a model up from a handful of servers to many.
Creative Layouts - Single Hospital Ward Example
A single hospital ward laid out on a custom background image, with resource icons spaced out to match the real positions of bays and beds. Demonstrates how much creative control you have over entity and resource placement beyond the default grid layout.
Creative Layouts - Multiple Ward Example
Extends the single-ward layout example to multiple wards on the same background image, each with its own set of spaced-out resources. Shows how a wider, more elaborate custom layout can represent a whole department rather than a single area.
Mental Health - Appointment Booking Model
Not every model needs a literal 'resource' to track - here, a mental health appointment-booking pathway is animated using queue steps alone. It's a good example of using vidigi to visualise the buildup and clearing of a queue for something more abstract, like appointment slots.
More Resourceless Queues - Community Service Repeat Appointment Booking Model with Variable Follow-ups
A resourceless community appointment-booking model where clients have an initial appointment followed by a variable number of follow-ups with the same clinician. Demonstrates how to animate continuity-of-care patterns that are awkward to represent with standard SimPy resources.
Additional Synchronised Traces - Orthopaedic Ward - Hospital Efficiency Project
An orthopaedic ward model from the Hospital Efficiency Project, paired with a synchronised subplot that tracks an additional metric - such as bed occupancy - alongside the main entity animation. Shows how to keep a secondary chart moving in step with the animation timeline.
Visualising a more complex status alongside entity icons - gas station with individual fuel tank level
A gas station model where each fuel pump/resource has its own continuously changing status - the tank's fuel level - shown alongside the entity icons. Demonstrates visualising a more complex, numeric resource state rather than just 'busy' or 'free'.
Precalculated pathing
A packing robot model comparing two ways of moving entities between steps: vidigi's default interpolated pathing, versus precalculated paths for when the interpolated route would cut across a background image awkwardly. Useful once your layout gets complex enough that a straight line between steps stops looking right.
Deep Dive: Ways of visualising larger queues
Compares several ways of visualising queues that grow too large to show as individual icons, going beyond the default '+ x more' text. A deep dive for anyone whose model produces queues large enough to make the standard display hard to read at a glance.
Visualising Moving Resources
Not all resources are static - sometimes, a resource may need to move to where our entities are, not the other way around, or move to where another static resource is. In this example we look at a case where we have more treatment rooms than nurses, so the nurses move between rooms as they are needed.
Legacy Examples
Old examples aimed at those using earlier versions of vidigi.
Adding Vidigi to a Simple simpy Model (HSMA Structure) - vidigi 0.0.4 and below
The original version of the HSMA-structure walkthrough, kept for anyone still running vidigi 0.0.4 or earlier. If you're on a current release, see the updated version of this example instead.
Adding Vidigi to a Simple simpy Model (HSMA Structure) - vidigi 1.0.0 to 1.3.1
A step-by-step walkthrough of retrofitting vidigi onto an existing SimPy model written in the style taught on the Health Service Modelling Associates (HSMA) programme. The core steps - adding logging, swapping in vidigi's resource classes, and building the animation - apply just as well if your model is structured differently.
Populating Event Logs - vidigi 0.0.4 and below
A reference guide to the event log format vidigi 0.0.4 and below expects - the required event types, columns and structure for arrivals, queueing and resource use. Kept for anyone still on an older release; current versions of vidigi are better served by the EventLogger-based examples.
Using the VidigiStore to Simplify Model Code Changes
Revisits the simplest one-resource model to show off VidigiStore, a class that lets you request and release resources using the same 'with ... request()' pattern as a standard SimPy Resource. It cuts down the amount of rewriting needed to bring vidigi's resource tracking into an existing model.