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

**URL:** <https://discourse.julialang.org/t/ann-mavi-jl-a-flexible-package-for-particle-dynamics-simulations/132976>\
**Category:** Community\
**Tags:** package, announcement\
**Created:** [October 8, 2025, 12:33pm UTC](https://discourse.julialang.org/t/ann-mavi-jl-a-flexible-package-for-particle-dynamics-simulations/132976 "2025-10-08T12:33:46Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![marcos1561](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/marcos1561/32/218892_2.png) [@marcos1561](https://discourse.julialang.org/u/marcos1561)\
**Post date:** [October 8, 2025, 12:33pm UTC](https://discourse.julialang.org/t/ann-mavi-jl-a-flexible-package-for-particle-dynamics-simulations/132976/1 "2025-10-08T12:33:46Z")

</div>

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.](https://github.com/marcos1561/Mavi.jl)

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.

```julia
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

```

---

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [October 8, 2025, 2:34pm UTC](https://discourse.julialang.org/t/ann-mavi-jl-a-flexible-package-for-particle-dynamics-simulations/132976/2 "2025-10-08T14:34:27Z")

</div>

Incredible logo!

---

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [October 8, 2025, 2:35pm UTC](https://discourse.julialang.org/t/ann-mavi-jl-a-flexible-package-for-particle-dynamics-simulations/132976/3 "2025-10-08T14:35:32Z")

</div>

And welcome to the community!

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

---

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [October 8, 2025, 3:42pm UTC](https://discourse.julialang.org/t/ann-mavi-jl-a-flexible-package-for-particle-dynamics-simulations/132976/4 "2025-10-08T15:42:04Z")

</div>

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](https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-rules), or if it takes multiple pings to get a reaction.

---

<div class="post-metadata">

**Author:** ![marcos1561](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/marcos1561/32/218892_2.png) [@marcos1561](https://discourse.julialang.org/u/marcos1561)\
**Post date:** [October 9, 2025, 1:17am UTC](https://discourse.julialang.org/t/ann-mavi-jl-a-flexible-package-for-particle-dynamics-simulations/132976/5 "2025-10-09T01:17:43Z")

</div>

Thank you! I looked for a “project announcements” category but somehow missed it 😅

---

<div class="post-metadata">

**Author:** ![marcos1561](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/marcos1561/32/218892_2.png) [@marcos1561](https://discourse.julialang.org/u/marcos1561)\
**Post date:** [October 9, 2025, 1:27am UTC](https://discourse.julialang.org/t/ann-mavi-jl-a-flexible-package-for-particle-dynamics-simulations/132976/6 "2025-10-09T01:27:55Z")

</div>

Thanks! I didn’t know about the length restriction, I’m already emotionally attached to the name Mavi at this point, but I think I could change it to Marvin.