ULULA: An ultra-lightweight 2D hydrodynamics code for teaching and experimentation
Benedikt Diemer · 2025
Read ULULA: An ultra-lightweight 2D hydrodynamics code for teaching and experimentation by Benedikt Diemer (2025) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2505-20399.txt.
Introduction
Benedikt Diemer wrote a solo paper in two thousand twenty-five presenting a tiny fluid dynamics code for teaching. Fluid flow is hard to teach because most real problems need numerical solving. Production codes are so large that their complexity hides the physics from first-time users.
His code, ULULA, solves fluid flow and gravity in two dimensions in under eight hundred lines of Python. Parts such as the solvers and boundary rules can be swapped to show their effect. Classic test problems are included and run in minutes on a laptop. The code is open-source, heavily commented, and documented for classroom use.
Catalog record
| CREATOR | Benedikt Diemer |
|---|---|
| YEAR | 2025 |
| COLLECTION | PAPERS |
| FORMAT | TXT |
| FILE SIZE | 53 KB |
| VERSION | 1.0 |
| LICENSE | http://creativecommons.org/licenses/by/4.0/ |
| RIGHTS | CC BY |
| SOURCE | arXiv |
Source: https://arxiv.org/abs/2505-20399
Browse the full library · About the Tower of Babel
Full text
The opening of the work, from the library's hosted text:
ULULA: An ultra-lightweight 2D hydrodynamics code for teaching and experimentation Benedikt Diemer Abstract Hydrodynamics is a difficult subject to teach in the classroom because most relevant problems must be solved numerically rather than analytically. While there are numerous public hydrodynamics codes, the complexity of production-level software obscures the underlying physics and can be overwhelming to first-time users. Here we present Ulula , an ultra-lightweight python code to solve hydrodynamics and gravity in 2D. The main goal is for the code to be easy to understand, extend, and experiment with. The simulation framework consists of fewer than 800 800 active lines of pure python code, but it includes a robust MUSCL-Hancock scheme with exchangeable components such as Riemann solvers, reconstruction schemes, boundary conditions, and equations of state. Numerous well-known hydrodynamics problems are provided and can be run in a few minutes on a laptop. The code is open-source, generously commented, and extensively documented. I. Introduction The dominant physical mechanisms in the Universe are arguably gravity and hydrodynamics (HD). The latter largely controls the evolution of diverse systems such as gas planets, stars, the interstellar and intergalactic medium, galaxy clusters, and the primordial Universe. While Newtonian gravity can be taught in high school, HD is a much more technical subject that is often not even included in undergraduate physics curricula. One reason for this absence may be that solving HD problems in the classroom can be difficult and unsatisfying. While the Euler equations are relatively simple in the sense that they do not contain an overwhelming number of symbols, there are few relevant problems with derivable, analytical solutions (such as sound waves or hydrostatic atmospheres). Most modern research problems need to be solved numerically, meaning that pen-and-paper teaching fails to reflect the day-to-day nature of research related to HD systems. To make matters worse, the learning curve for numerical HD is relatively steep because simple PDE solving techniques fail. For example, finite-differencing schemes can be taught fairly quickly to students with some programming background, but those schemes fail to maintain positivity or conserve mass. The non-linear nature of the Euler equations, as manifested by the ubiquity of discontinuities, has led to a long search for viable solvers that met its first real success with the development of finite-volume schemes [ 10 ] . However, an understanding of how finite-volume solvers work is not easily communicated. The theoretical framework by itself is complex and abstract unless coupled to numerical experimentation, but such practical exploration means either writing a scheme from the ground up (which is too time-consuming for most class environments) or running existing HD codes. Unfortunately, production-level astrophysical HD codes tend to be poor tools for learning and experimentation because the underlying equations are necessarily buried deep in complex code for adaptive grids, parallelization, I/O, and physics other than pure HD. Moreover, compiling C/Fortran code is often challenging enough to make such codes impossible to use in, say, homework sets. In this work, we present Ulula , an extremely lightweight python HD and gravity code designed to be easily understandable and to present a low barrier to entrance. Ulula was written with a strong focus on the brevity and legibility of the code while providing high-performance, real-life HD algorithms. To this end, the entire HD solver framework fits into a single python file with less than 800 active lines of code. The limitation to 2D represents a compromise between simplicity and performance: 1D codes quickly get boring because many HD problems are intrinsically multi-dimensional, but 3D problems are too large to be solved in reasonable time without parallelization. For the sake of simplicity, Ulula is written in pure python with numpy , with no extra libraries that need to be installed or compiled (such as jax or numba ). Given Ulula ’s pedagogical focus, the code comes with extensive online documentation and is heavily commented. In no more than two lines of code, the user can run pre-implemented problem setups, experiment with different HD solvers, and create plots and movies. Ulula is not the first pedagogical HD code written in python. Most notably, Pyro [ 39 , 13 ] was designed with a similar purpose in mind and is paired with an open-source book on numerical HD [ 40 ] . In detail, however, the codes are structured rather differently. While Ulula is built as a single simulation framework with interchangeable solver components, Pyro includes a much larger array of solvers for specific problems, such as advection, multi-grid relaxation, diffusion, and incompressible flows. As a result, the total code volume of Pyro is many times larger than that of Ulula . Moreover, Pyro uses just-in-time calculation to speed up certain routines whereas Ulula is based purely on numpy . An even shorter, more easily comprehensible alternative to Ulula and Pyro are short python scripts that address a specific HD-related problem. For example, the “Create your own” series of scripts by Philip Mocz (see github repository ) excels in solving complex problems such as the Rayleigh-Taylor instability in as few lines of code as possible. On the other end of the complexity spectrum, the general speedup of python via compiled libraries has enabled the creation of production-level python codes such as PySPH [ 24 ] or Dedalus [ 3 ] . Unlike Ulula , those codes are used for research and are incomparable in their size and complexity. The paper is structured as follows. We briefly present the fluid equations in § II . § III gives a detailed description to the algorithms and problem setups that are implemented in Ulula . We test the accuracy and performance of the code in § IV . We discuss avenues for experimentation and development in § V . The code is freely available at bitbucket.org/bdiemer/ulula and documented at bdiemer.bitbucket.io/ulula . II. Theory Ulula solves the Euler equations for compressible, inviscid fluids under gravity, which can be expressed as three conservation laws for mass, momentum, and total energy. The changes in these quantities at a fixed location can be understood as the divergence of a flux plus source terms, \displaystyle\frac{\partial\rho}{\partial t} \displaystyle+\boldsymbol{\nabla}\boldsymbol{\cdot}(\rho{\boldsymbol{v}}) \displaystyle= \displaystyle\ 0 \displaystyle\frac{\partial(\rho{\boldsymbol{v}})}{\partial t} \displaystyle+\boldsymbol{\nabla}\boldsymbol{\cdot}\left(\rho{\boldsymbol{v}}\otimes{\boldsymbol{v}}+{\boldsymbol{I}}P\right) \displaystyle= \displaystyle\ -\rho\boldsymbol{\nabla}\Phi \displaystyle\frac{\partial E}{\partial t} \displaystyle+\boldsymbol{\nabla}\boldsymbol{\cdot}\left([E+P]{\boldsymbol{v}}\right) \displaystyle= \displaystyle\ \rho\frac{\partial\Phi}{\partial t}\,, (1) where \rho is the density, {\boldsymbol{v}}=(v_{\rm x},v_{\rm y}) is the fluid velocity vector in 2D, P is the pressure, E=\rho({\boldsymbol{v}}^{2}/2+\varepsilon+\Phi) is the total energy per unit volume, \varepsilon is the internal energy per unit mass, and \Phi is the gravitational potential. We make the notation more compact by combining the three equations into a single vector equation for a conservation law, \frac{\partial{\boldsymbol{U}}}{\partial t}+\boldsymbol{\nabla}\boldsymbol{\cdot}{\boldsymbol{\mathcal{F}}}({\boldsymbol{U}})={\boldsymbol{S}}\,, (2) where we have defined the vector of conserved fluid quantities, {\boldsymbol{U}} , the vector of flux terms, {\boldsymbol{\mathcal{F}}}({\boldsymbol{U}}) , and the vector of source terms, {\boldsymbol{S}} . In addition, we define a vector of “primitive” variables {\boldsymbol{V}} . For a 2D system, we have {\boldsymbol{V}}\equiv\left(\begin{array}[]{c}\rho\\ \vskip 6.0pt plus 2.0pt minus 2.0pt\cr v_{\rm x}\\ \vskip 6.0pt plus 2.0pt minus 2.0pt\cr v_{\rm y}\\ \vskip 6.0pt plus 2.0pt minus 2.0pt\cr P\end{array}\right)\qquad{\boldsymbol{U}}\equiv\left(\begin{array}[]{c}\rho\\ \vskip 6.0pt plus 2.0pt minus 2.0pt\cr\rho v_{\rm x}\\ \vskip 6.0pt plus 2.0pt minus 2.0pt\cr\rho v_{\rm y}\\ \vskip 6.0pt plus 2.0pt minus 2.0pt\cr E\end{array}\right)\qquad{\boldsymbol{S}}\equiv\left(\begin{array}[]{c}0\\ \vskip 6.0pt plus 2.0pt minus 2.0pt\cr-\rho\ \partial\Phi/\partial x\\ \vskip 6.0pt plus