[Doc]: Add new example to matplotlib.animation

[shubham-93]

Documentation Link

https://matplotlib.org/devdocs/gallery/animation/index.html

Problem

There is currently no example showing how to use classes and matplotlib.animation to perform typical physics simulations.

Classes are the natural choice when it comes to describing many different physics phenomena of various complexities, and I think this should be emphasized. Combining this with matplotlib.animation, one can create very interesting animated visualizations of real-time physics phenomena. This can definitely help in better education (physics and/or Python programming), and potentially also in academic research. Coming from a physics background myself (PhD), I found it rare to come across good examples on how to do physics simulations (especially when they are complicated), so I made an example myself (see link below).

A universal problem in physics is about describing the motion of particles interacting with each other and the environment. These particles can have different properties, like velocity, which change upon interactions. This allows many physics problems to be naturally modelled in an object-oriented framework: the properties become the attributes, and the interactions become the methods.

The seemingly long problem of calculating the trajectories of an arbitrary large number of particles experiencing different interactions then neatly breaks down into defining an appropriate class for a particle. To create multiple particles, we just create multiple instances of that class. Each instance holds the data that defines the state of the particle it corresponds to. And its methods automatically keep track of when and how the state should be modified during interactions.

This object-oriented approach makes it very easy to modify or add new properties and interactions to a particle: one can then just start with a simple problem and sequentially add more attributes and methods to describe more complex behaviors. Debugging becomes easy, since the core working principles of the problem reside in the class definition, and not additionally in the rest of the program.

After this, one can use matplotlib.animation, quite straightforwardly, to get the plotting data from the instances of these classes and then make real-time simulations to show how the world works. Powerful and intuitive!

Suggested improvement

I propose to add a new example to the documentation for matplotlib.animation (link above). Particularly, I made a simulation of an arbitrary number of particles colliding elastically with each other inside a box in 2 dimensions (a standard physics problem). The particles have random masses, positions and velocities. I used a class with attributes to label particle data, and methods to check for collisions and update the data. I also use numpy to do some vector calculations, emphasizing how to leverage linear algebra to simplify simulation codes for complicated problems. The code is just one file, and can be found here: https://github.com/shubham-93/n-body-collision-sim.git

[story645]

Hi, I think your example is really nice, but the code is very attuned to the physics and we're trying to streamline our examples to be much more focused on the specific matplotib functionality. What matplotib features does your example show that's not handled by the gallery examples or tutorial ? Or which feature does it explain better and how does it do so?

Precisely because it's so physics oriented, I think this might be a better fit for the scientific Python blog

[shubham-93]

Hi, thanks for your comment.

I think the main general idea that my example shows better is

1) how to animate many objects with different characteristics and 2) how to make each object affect and change the other's position on the plot

There is currently no example that shows the above. There are several animations one might want to make that are based on multiple objects interacting with each other, not independent of each other, and my example show how to do that.

I would say that I'm not using a specific, new matplotlib functionality not given in the current examples to do this. But, I show a specific, new technique with classes that enable intuitive and easy use of matplotlib.animation to animate problems that require 1. and 2. above. Another advantage of the method is that it is straightforward to generalize to more complex animations (e.g. more objects, more characteristics, more interactions). (There are 1-2 physics examples in the gallery, but they do not show this).

What do you think? Also, thanks for the recommendation of the scientific Python blog - I will check that as well.

[jklymak]

Our docs are not a general programming resource. From Matplotlib point of view this example just accessed the x and y properties of the class and plots them. I don't think that is unique enough to merit adding as an extra example.

[tacaswell]

I agree this is a cool example, but from Matplotlib's point of view does not add much over the existing examples. If we compare this example with https://matplotlib.org/devdocs/gallery/animation/animate_decay.html#sphx-glr-gallery-animation-animate-decay-py

The pseudo-code of both evolution and run is roughly

def one_step(frame):
    # COMPUTE DATA AT NEXT STEP
    # SET DATA ON Line2D
    # RETURN ARTIST

but with different versions of COMPUTE DATA FOR NEXT STEP.

As a technical detail, I think that using a generator here to wrap up all of the simulation and then yield out the new x, y is a much nicer pattern than a class that relies on the name of the list of the instances in the global namespace to work.

Thank you for the suggestion (and that is a nice example), but this would be much better as a contribution to the scientific Python blog (which would also give you a chance to discuss more general simulation / OO design etc than you could have in the Matplotlib docs).