[ANN] Mavi.jl: a flexible package for particle dynamics simulations

Community
,
1

Hi everyone!

I’d like to share an open source project called Mavi for particle dynamics simulations I’ve been working on.

Github Repository: GitHub - marcos1561/Mavi.jl: Mavi is a Particle Dynamics Engine.

The project is still in early development, so suggestions and new contributors are very welcome!

About the project

The goal of the project is to provide a flexible implementation for studying systems of interacting particles that can be customized to the user’s needs.

Main features

  • Support for different equations of motion (Newton’s seconds law, Langevin equations, custom-defined)
  • Common interaction potentials (Lennard-Jones, custom-defined)
  • Support for simulations with varying particle numbers.
  • Obstacles with general geometries constructed from line segments or with specialized shapes, such as circles. Obstacles can also have different behaviors upon collisions with particles – exerting forces or solving collisions in special ways, such as reflecting the velocity.
  • A system to run virtual experiments and collect data. Users can run experiments with custom collectors to gather only relevant data. Long experiments can periodically create checkpoints that can be used to load and continue an experiment.
  • Tools for visualization (using Makie):
    • Real-time interactive animation, with the possibility of adding custom visual elements.
    • Image generation.
    • Video generation.

To demonstrate the extensibility of the Mavi core module, there is a Mavi.Rings submodule that implements a model for biological cells using active rings, as presented in this article: Teixeira, Emanuel F., Carine P. Beatrici, Heitor C. M. Fernandes, and Leonardo G. Brunnet. “Segregation in Binary Mixture with Differential Contraction among Active Rings.” Physical Review Letters 134, no. 13 (2025): 138401

Example

Example of creating particles at the vertices of a rectangular grid, interacting via a harmonic truncated potential (with Newtonian dynamics), embedded in a rectangle space with rigid walls. We also animate the system in real time, drawing the particles with physically meaningful radii and coloring them with the magma colormap.

using Mavi
using Mavi.States
using Mavi.InitStates
using Mavi.Configs
using Mavi.Visualization

function main()
    num_p_x = 10
    num_p_y = 10
    offset = 0.4
    
    num_p = num_p_x * num_p_y
    
    dynamic_cfg = HarmTruncCfg(ko=10, ro=1, ra=1)
    radius = particle_radius(dynamic_cfg)

    pos, geometry_cfg = rectangular_grid(num_p_x, num_p_y, offset, radius)
    state = SecondLawState(
        pos=pos,
        vel=random_vel(num_p),
    )

    space_cfg = SpaceCfg(
        wall_type=RigidWalls(),
        geometry_cfg=geometry_cfg,
    )

    system = System(
        state=state, 
        space_cfg=space_cfg,
        dynamic_cfg=dynamic_cfg,
        int_cfg=IntCfg(dt=0.01),
    )

    anim_cfg = AnimationCfg(
        graph_cfg=CircleGraphCfg(colors_map=:magma),
    )

    animate(system, anim_cfg)
end
4 Likes
2

Incredible logo!

2 Likes
3

And welcome to the community!

p.s.: The discourse has a dedicated category for package announcements: Package Announcements - Julia Programming Language I think more people may subscribe there (not sure!) there is also a slack channel you can announce this to!

1 Like
4

Thank you for sharing! This looks very nice. And like @Datseris, I really like to logo as well.

Just as a heads-up: When you’re going to register this, you’ll run into the automatic “Name is not at least 5 characters long” check. Personally, I think the name Mavi is totally fine, in the category of “less systematic names”. But there does seem to be an increasing reluctance among the registry maintainers to accept very short package names, and this will need manual merging from a registry maintainer. Don’t get discouraged if you have to advocate for the package name after feedback along the lines of “we’re not that thrilled about short names” and a reminder of the guidelines, or if it takes multiple pings to get a reaction.

4 Likes