Creating threads to update visualization asynchronously

[HMNS19]

Summary

This PR introduces a thread-based mechanism to handle model updates and visualization rendering concurrently. It ensures smooth execution of simulations by separating model step execution and visualization updates into independent threads, improving performance and responsiveness during simulations.
Fixes #2604

Motive

Previously, the visualization process could become a bottleneck during rapid simulations, as rendering was tightly coupled with model updates. This caused delays and UI responsiveness issues. By separating these operations into threads, the model execution is no longer hindered by the visualization process.

Implementation

1. Introduced separate thread for visualisation:
   Handles visualization updates triggered by threading.Event (visualization_pause_event) to synchronize rendering with model steps.
2. Thread Synchronization:
   Implemented visualization_pause_event to signal the visualization thread after each model step is completed, ensuring rendering happens efficiently without blocking the simulation.

Usage Examples

• Play Button Behavior: The play button now ensures the simulation continues smoothly.

• Concurrent Rendering: Visualization and simulation run in parallel, reducing delays.

• Before
  

• After
  

Additional Notes

• Dependencies: Utilizes solara.use_thread and Python's threading mechanisms for concurrency.
• Potential Side Effects: Proper adjustment of play_interval is recommended to balance simulation speed and rendering performance.

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 +0.8% [+0.2%, +1.3%]	🔵 +0.1% [-0.0%, +0.2%]
BoltzmannWealth	large	🔵 +0.3% [-0.3%, +0.9%]	🔵 +0.5% [+0.2%, +0.9%]
Schelling	small	🔵 +0.3% [+0.0%, +0.6%]	🔵 -0.3% [-0.4%, -0.2%]
Schelling	large	🔵 +0.5% [+0.2%, +0.8%]	🔵 -0.3% [-0.7%, -0.0%]
WolfSheep	small	🔵 -0.2% [-0.4%, +0.0%]	🔵 +0.0% [-0.1%, +0.2%]
WolfSheep	large	🔵 +0.3% [-0.2%, +0.7%]	🔵 +0.4% [-0.1%, +0.8%]
BoidFlockers	small	🔵 +0.8% [+0.3%, +1.4%]	🔵 +1.0% [+0.8%, +1.2%]
BoidFlockers	large	🔵 +0.6% [+0.2%, +1.0%]	🔵 +0.1% [-0.1%, +0.3%]

[EwoutH]

Thanks for the PR and the detailed PR message!

I’m on vacation the whole of February, so I will leave the review to other maintainers.

Have you also tried using a separate thread for every figure?

[HMNS19]

Thanks! Hope you have a great vacation!
I actually had a few questions about using separate threads for each figure. Right now, this PR allows the model to run in the background while plotting, without worrying about sync issues. But if we spawn a thread for each figure, wouldn’t we need to constantly keep the figures in sync with each other to avoid confusion? And wouldn’t that also require locks to manage shared data properly?

[EwoutH]

But if we spawn a thread for each figure, wouldn’t we need to constantly keep the figures in sync with each other to avoid confusion?

That's an excellent point. You're right.

Another option could be that a new thread is used to draw all figures for a single step. Then the figures for a certain step will be ready at the same time.

You would have to guarantee that each frame is displayed for about the same time (or for a minimum duration).

It's up to you how complicated you make it in this PR. We could also keep this PR to a minimal, simple implementation and implement further ideas in future PRs.

[HMNS19]

Yes, this PR ensures a single thread handles drawing all figures together for a specific step, ensuring synchronization.

You would have to guarantee that each frame is displayed for about the same time (or for a minimum duration).

Noted, currently even if the play interval is set, the model doesn’t always visualize it correctly, and the user has to manually adjust it leading to poor responsiveness.I'll start working on this and create a new PR to handle this issue.

[HMNS19]

Hi @quaquel , Is this PR good to go, or does it need any changes? Since @EwoutH is on vacation, I wanted to check if anyone else could review it. I’d like to get some input regarding this PR before starting a follow-up to keep the next PR aligned.

[EwoutH]

You're in luck, my knee hurts a little so I need to take some more breaks between skiing and I quickly looked through the code.

I appreciate the detailed approach to decoupling model steps from visualization updates. Separating these concerns should help improve responsiveness during simulations. However, I have some concerns regarding the mix of threading and asyncio constructs, which might complicate maintenance and lead to subtle concurrency issues.

My main worries are about the unnecessary use of asyncio event loops within threads and potential race conditions when updating shared model state. The duplicated logic between ModelController and SimulatorController also adds complexity, and I’m not entirely convinced that the current implementation guarantees thread safety—especially when forcing UI updates from background threads.

To move forward, please consider the following specific points:

1. Remove asyncio event loop creation in threads if you’re not using async/await, and stick to pure threading.
2. Ensure event objects persist across component re-renders to avoid unintended resets.
3. Verify that methods like model.value.step() and simulator.run_for() are thread-safe.
4. Refactor the duplicated concurrency logic between ModelController and SimulatorController.

Hope it helps. I think the goal of this PR should be to implement is both simple and scalable, so we have foundation to build on this.

Let me know if you have any questions. I'm Sunday in an long distance train for 7 hours, so I can look at it again then.

Thanks for your work on it so far!

[HMNS19]

Hey, sorry for the late reply! Just to clarify regarding thread safety—are you more concerned about multiple threads accessing model value at the same time (which could cause inconsistent state in model.value.step() and simulator.run_for()), or is the main issue updating the UI from a background thread?

For the first one, I haven’t come across any issues where step value gets into an unsafe state with the current code, but if there's a potential risk, I can add a lock, queue, etc. or make it bidirectional (whichever works best) to ensure safety. If it’s about UI updates, I was thinking of using a reactive variable and then triggering updates in use_effect on the main thread instead of updating directly from a background thread. Let me know what you think!

[EwoutH]

Thanks for getting back! My comment wasn't primarily about thread safety of model state or UI updates. The main concern is that you're creating asyncio event loops inside threads without using any async/await functionality there. For example, in your step function:

def step():
    try:
        loop = asyncio.new_event_loop()
        asyncio.set_event_loop(loop)
        while running.value and playing.value:
            time.sleep(play_interval.value / 1000)
            do_step()
            if use_threads.value:
                visualization_pause_event.set()
    except Exception as e:
        print(f"Error in step: {e}")
        return
    finally:
        loop.close()

You create and set an asyncio event loop, but then only use regular blocking calls like time.sleep(). The same happens in visualization_task(). This unnecessarily complicates the code by combining two different concurrency paradigms (threading and asyncio) without actually using asyncio's features.

I'd suggest simplifying by sticking to pure threading. The loop creation, error handling and cleanup could be much simpler that way.

cc @quaquel - let us know if you have a take on this.

[HMNS19]

Understood, will change it right away.

[EwoutH]

Thanks! I will let another maintainer with broader knowledge of the visualisation stack do the final review.

[tpike3]

@HMNS19 Thanks for the PR!

I will leave the more focused review to @quaquel and @Corvince, however if possible I like to avoid lambda functions in Mesa as they are generally viewed as less readable, harder to read in the traceback and create issues with serialization. As this is part of the visual I appreciate the last 2 are less of a concern

However a simple function is also fairly easy to add

def set_reactive_use_threads(value):
   reactive_use_threads.set(value)

solara.Checkbox(
   label="Use Threads",
   value=reactive_use_threads,
   on_value=set_reactive_use_threads,
)

See PEP 8

[HMNS19]

Thanks for the feedback! I’ve replaced the lambda with a named function as you suggested. Let me know if there’s anything else to improve. Also curious—would lambda functions in the play_interval and render_interval sliders have similar concerns?