Getting Started With Minimalist Physics Examples
Most people approaching physics simulation for the first time end up overwhelmed by the amount of boilerplate required. You open a tutorial and suddenly you're configuring gravity, friction, mass matrices, collision layers, and a fixed timestep loop before you've simulated anything recognizable. That's why I started stripping things down to their absolute minimum working state. Minimalist Physics Examples is a collection of stripped-down physics demonstrations that focus on one concept per file. No extra UI, no rendering frameworks, no asset pipelines. Just the code that calculates forces and updates positions. I keep them available on GitHub under the MIT license if you want to pull the repo directly.
Why Minimalist Physics Examples Matter
The main reason I maintain this set is that every beginner tutorial tends to combine too many concerns. You get a bouncing ball, sure, but it also has a menu system, particle effects, and audio. By the time you read through all of it, you have no idea which ten lines actually produced the bounce. Each example here does exactly one thing and nothing else. Take the simple harmonic oscillator example. It's eight lines of Python using nothing but basic arithmetic. That's all a spring needs. The full rigid body dynamics example with multiple contact points is longer, maybe forty lines, but I still consider it minimal because removing any line would break the physics. Nothing decorative survives in these files.
How to Use These Examples
I usually start people off with the 2D point particle example. It demonstrates explicit Euler integration against a constant gravitational field. You'll see the position update formula, the velocity update, and the collision response off a floor boundary. The code assumes you have Python 3.9 or later and numpy installed. That's it. No extra dependencies. The next step is the double pendulum. This is where things get interesting because the equations of motion require a coupled system of differential equations. The example uses scipy.integrate.solve_ivp with a default tolerance that works fine for visualization but isn't precise enough for energy conservation checks over long runs. If you need conservation to within a fraction of a percent over hundreds of seconds, tighten the tolerance to 1e-8 or switch to a symplectic integrator. The example includes a side-by-side comparison file that shows the energy drift clearly after about two hundred seconds at default settings. For collision handling, the stack of boxes example is worth running yourself. It demonstrates how repeated collisions between identical rigid bodies can cause jitter if your restitution coefficient is too close to one. I encountered this firsthand when someone tried to reuse the code for a tower of fifty blocks with a coefficient of restitution set to 0.95. The simulation exploded after about twelve seconds because the solver kept re-entering collision states without settling. The fix was straightforward: reduce the restitution to 0.7, enable the warmstarting flag in the solver, and clamp the maximum velocity per frame to prevent numeric blowup. Once I applied those three changes together, the tower settled in about four seconds and stayed stable. The example repo now includes a corrected version of that scenario.
Get the Full Details
Common Pitfalls
The biggest mistake I see is people treating these examples as production-ready code. They aren't. The timestep is fixed in most of them, which means performance degrades linearly with simulation speed if you're pushing for real-time display. The collision detection is broad-phase only in the simpler examples. Once you need narrow-phase testing with complex shapes, you're past what these files cover. Another issue is the assumption of a purely 2D world. Several examples project everything onto a plane for clarity. When you move to 3D, the coordinate conventions and rotation representations don't translate directly. The angular velocity quaternion integration example exists, but it's brief and doesn't cover gimbal lock or representation switching. If you plan to build on top of these, budget extra time for that translation work.
Edge Case: Nonlinear Damping in the Damped Oscillator
I ran into a problem recently where someone added quadratic damping to the damped oscillator example and the solver failed silently. The velocity would approach zero asymptotically but never actually reach it, so the solver kept iterating past the intended end time. The fix was to add a hard threshold: if the magnitude of velocity drops below 1e-6, set it directly to zero and terminate the integration. It's a small change but it prevents the solver from wasting cycles on an unsolvable tail. I've since added this as a comment in the example file so others don't hit the same wall. There are scenarios where minimalist examples simply don't help. If you're working with continuous collision detection for fast-moving objects, these examples won't cover it. If you need GPU-accelerated particle systems with thousands or millions of bodies, you'll need a different architecture entirely. The examples assume single-CPU execution and CPU memory. They're designed for understanding, not for production workloads that demand parallelism or streaming. For production use, I recommend looking at established libraries like PhysX, Bullet, or Box2D after you understand the fundamentals from these examples. The transition is smoother when you know which ten lines of boilerplate you can skip. The minimalist approach saves you roughly two to three hours of setup time when you're learning, but it doesn't replace the engineering decisions you face when scaling up. Those come from reading actual library source code and documentation, not from simplified demos.
If you want the repository, search for Minimalist Physics Examples on GitHub. The README has installation instructions and links to each standalone example. The files are organized by topic: particles, rigid bodies, constraints, and integrators. Each directory contains a single primary .py file and a short description of the physics involved. Start with the particle folder, move to rigid bodies once you're comfortable, and skip ahead to integrators only if you care about numerical methods specifically.
