YouTube-simulations turns C physics code into rendered video frames

A video production pipeline, not a reusable simulation library

The repository description is blunt: code for simulations on YouTube. The project describes itself as a tool to create videos of particles or waves in different 2D domains, and it names the author, Nils Berglund, and the optimizer, Marco Mancini. The code produced the videos published on the YouTube channel the project links to, and that context matters for adoption. What you get is a working pipeline of C source files, a set of hand-tuned constants and a documented path from a source file to an mp4 file. What you do not get is a library with a stable public API, semantic versioning for your own fork, or an installer. Every simulation is a standalone program with its own main routine. The audience is a person who understands classical mechanics and partial differential equations, wants an animation that looks like a published science channel, and is prepared to read the top of a C file to change a constant. If you are looking for a package to call from another program, this is the wrong shape.

Four families of simulations share one set of conventions

The code is organised into four groups, described as eight files, nineteen files, six files and four files. The billiard group covers classical particles: particle_billiard.c for a collection of non-interacting particles, drop_billiard.c for an expanding front of particles, particle_pinball.c for a variant with extra statistics plots, and billiard_phasespace.c for phase portraits, which work only for certain shapes. The wave group is the largest and covers wave_billiard.c, a 3d rendering in wave_3d.c, wave_sphere.c for a wave on a sphere, wave_comparison.c for the same equation in two domains, wave_energy.c for an energy profile, mangrove.c, heat.c for the heat equation with optional gradient field lines, and rde.c for reaction-diffusion with Schrödinger, Euler, shallow water, Kuramoto and Keller-Segel models. The molecular dynamics group holds lennardjones.c with a hashgrid and a separate movie renderer, and the percolation group holds percolation.c with cluster finding. In each family a global_ file holds variables and parameters, and sub_ files hold the drawing and computation routines that the top level programs share.

Frames go to disk as TIFF, then ffmpeg makes the video

The data flow is the same in every simulation and it is worth understanding before you change anything. A program computes the state, renders it, and writes numbered TIFF frames into a subfolder that you create yourself. The frame folders are listed as tif_part and tif_drop for the billiard programs, tif_wave, tif_heat, tif_bz and tif_schrod for the wave family, tif_ljones for molecular dynamics and tif_perc for percolation. Encoding is then a separate step. For the billiard group the documented command is:

ffmpeg -i part.%05d.tif -vcodec libx264 part.mp4

The pattern assumes five digit frame numbering, which matches how the renderers write filenames. The wave, molecular dynamics and percolation variants follow the same shape with their own prefixes, for example a wave sequence becomes wave.mp4 and a percolation sequence becomes percolation.mp4. Nothing in the repository automates that step, so producing a video is at least three manual actions: compile, run the program long enough to fill the frame folder, then run ffmpeg. That is deliberate for a one-off animation and annoying for a batch.

Compiling means linking against an X11 and OpenGL stack

Build instructions are given in two forms. The short form is a make target per simulation, for example:

make particle_billiard

and the same pattern applies to wave_billiard, lennardjones and percolation. The long form is a direct gcc invocation, and the wave one looks like this:

gcc -o wave_billiard wave_billiard.c -L/usr/X11R6/lib -ltiff -lm -lGL -lGLU -lX11 -lglut -O3 -fopenmp

Read that line as a requirements list. It links libtiff for the frame writer, the math library, OpenGL and GLU for the 3d drawing, X11 and GLUT for the window and event loop, and it enables OpenMP with -fopenmp. The library search path is the old X11R6 convention, and the heat example adds -lXmu on top. You need those development packages present, and you need to create the frame subfolder before running, otherwise the writes have nowhere to go. The project also warns that laptops claiming four cores often have two virtual ones, and suggests setting the thread count before running:

export OMP_NUM_THREADS=2

That advice is about OpenMP overhead on the compute step, not about the renderer.

Constants live at the top of each C file and in dated markdown logs

Every simulation is configured by editing constants at the beginning of its .c file, a pattern the project repeats for each family. On top of that, the repository keeps a long history of parameter values as markdown files: Parameters.md plus dated files such as Parameters_April21.md, Parameters_March26.md and Parameters_June26.md. Parameter values used in specific simulations are added to these files gradually, so the markdown is a lab notebook of what produced which video. For anyone changing the code, that history is more useful than it first looks, because it lets you reconstruct the state of a known published animation instead of guessing a parameter set from scratch. The top level also holds a large set of gzipped PPM maps, for example Earth_Map_Blue_Marble_2002_large.ppm.gz, Mars_Viking_ClrMosaic_global_925m_scaled.ppm.gz and Moon_LRO_LOLA_global_LDEM_1024.ppm.gz. wave_sphere.c and rde.c require them, and they must be unzipped before compiling.

Colour handling and maze generation come from separate sources

The rendering look is assembled from code that originated elsewhere, and the provenance is explicit. Four colour related files are included: hsluv.c and hsluv.h from the hsluv-color-gradient project, turbo_colormap.c from a gist by mikhailov-work, and colormaps.c containing look-up tables from the tinycolormap project. The repository also carries sub_maze.c, which is labelled a beta version providing support for creating mazes. This matters for a legal and technical reader. The repository is published under CC0-1.0, a public domain dedication that makes reuse of your own edits straightforward, but the vendored colour files arrived from other authors under their own terms, and those licenses are not reproduced there. If you reuse this code commercially, the safe move is to read the license headers in hsluv.c, turbo_colormap.c and colormaps.c yourself. The colormaps are look-up tables indexed by value, which is why heat.c and the wave renderers can map a scalar field onto colour without computing a gradient per pixel.

Where this approach stops working

Several limits are visible in the instructions themselves. First, the build assumes a Unix toolchain with X11 and OpenGL development headers and a GLUT based window system, and no alternative for headless servers is documented, macOS or Windows, so anyone on those platforms must solve the porting problem themselves. Second, there is no dependency manifest of any kind, so the make targets assume a machine that already has the libraries. Third, the workflow is manual at every step: create folder, compile, run, encode. Fourth, the maze support is described as beta, and billiard_phasespace.c is said to work only for certain shapes, which means a family of videos cannot be reproduced in a general way from the shipped code. Finally, the parameter history lives in dozens of separate markdown files rather than in one structured record, so programmatic comparison of runs is not supported. Nothing here is a criticism of the results, but if your goal is reproducible research output rather than finished videos, the tooling stops at the mp4. The real alternative is to write the simulation yourself in a scripting stack you already maintain, for example a short script that computes the same wave equation and writes PNG frames, with a plotting library doing the drawing. The difference in approach is concrete: that route needs no X11 headers, no GLUT window and no OpenMP tuning, but it gives up the hand-tuned parameter sets, the 3d renderers and the frame pipeline that this repository already contains. Choose the C route when the visuals are the product and you want to inherit them; choose the scripting route when you need to run the simulation inside an existing analysis pipeline and can accept simpler output.

Release tags show a steady but slow update cadence

The repository is not archived, and the last push was on 2026-08-10. Three tags are visible in the release history: v2.6 on 2026-08-10, v2.5 on 2026-04-11 and v2.4 on 2025-12-30. The gaps between those tags are months rather than weeks, which fits a project that evolves one published video at a time rather than on a release cadence for its users. There is no compatibility promise attached to those numbers, so treat v2.x as a label on a point in the simulation history, not as a semver contract you can depend on. If you fork this code and merge it forward, expect to resolve conflicts in the global_ parameter files by hand, because the constants that matter most are exactly the lines most likely to be touched between tags. The dated Parameters markdown files make that reconciliation easier, since they record what each published configuration looked like.

Editorial conclusion

Adopt YouTube-simulations when you are willing to edit C constants at the top of each file, create the frame subfolder by hand and compile against an X11 and OpenGL stack, and you want a physics animation you can change in minutes. Do not adopt it if you need a packaged library with a stable API, continuous integration friendly builds, or Windows support that the README never mentions. Check first that your machine has the X11, GLUT and libtiff development packages the compile commands expect, and unzipped map files in place if you plan to run wave_sphere.c or rde.c.

Frequently asked questions

Official sources

1. Issues
2. License: CC0-1.0
3. nilsberglund-orleans/YouTube-simulations on GitHub
4. README
5. Releases