In this paper
AbstractIntroductionRelation to earlier workConstraints of WebGPU and the data layoutHydrodynamicsSchemeReconstructionRobustness in single precisionWell-balanced reconstructionEquations of state and coolingViscosity and conductionSpeciesNuclear burningConservation without stored fluxesAdaptive mesh refinementGhost cells computed on loadMatching fluxes across refinement boundariesLocal timestepsGravity, point masses and sinksPoisson solverCoupling to the gasInitial states in discrete balancePoint masses and sinksMagnetic fieldsConstrained transportMagnetic fields on the adaptive meshInterface, input and outputProblemsEducational useValidationPerformanceDiscussionConclusionsAcknowledgmentsAppendixValidation testsReferencesWorksPhysics and Astronomy
Shaderous: A Browser-based Hydrodynamics Code for Physics Research and Teaching
Abstract
Shaderous is a three-dimensional code for compressible gas dynamics and ideal magnetohydrodynamics that runs in WebGPU compute shaders in a web browser on any vendor’s GPU. It combines an unsplit MUSCL-Hancock scheme and HLLC fluxes with a multigrid Poisson solver, block-structured adaptive mesh refinement with per-block timesteps, constrained transport with HLLD fluxes, point masses with sinks, cooling, viscosity, conduction, mixtures of gases, and nuclear burning by a neural network trained on a 13-isotope reaction network. A setup is shared as a link and runs on a student’s own laptop or phone, so the code suits teaching, from school pupils to graduate students. A run is limited to one GPU: the largest adaptive mesh so far held about 175 million cells, using 117 GB on an NVIDIA H200. The code therefore suits parameter studies, run as sweeps from the command line, rather than single simulations at the largest scales. Three aspects of the design are, as far as we can find, new. First, the hydrodynamic solver stores no face flux. The two cells that share a face compute bit-identical fluxes, so cells at boundaries between levels and between timesteps recompute their neighbors’ fluxes instead of keeping a flux register. Mass, momentum and energy are conserved to round-off on the adaptive mesh. Second, the whole step runs on the GPU: the timestep and the assignment of blocks to time bins are reduced there, and ghost cells are computed as they are loaded rather than exchanged. Third, the code works in single precision and still holds hydrostatic stars and atmospheres in balance, using a well-balanced reconstruction after Käppeli & Mishra (2014) and initial states settled against the grid’s own potential. A column whose density falls by a factor of nine million stays below Mach , against 0.35 without. Compensated sums keep the divergence of the magnetic field at round-off.
Introduction
Grid codes for astrophysical gas dynamics, such as FLASH (B. Fryxell et al. 2000), RAMSES (R. Teyssier 2002) and Athena++ (J. M. Stone et al. 2020), are large native programs. A user compiles them against a compiler, an MPI library and, on graphics processors, a vendor toolchain, then runs them on a workstation or a cluster and inspects the output afterward. That workflow suits production science. It is a poor fit for teaching, for exploring a problem before committing to a production run, and for handing a colleague a result that they can reproduce and modify in a minute.
Graphics processors entered numerical gas dynamics through their graphics interfaces. Before CUDA, solvers were written as fragment programs that read and wrote textures: linear algebra and multigrid (J. Bolz et al. 2003; N. Goodnight et al. 2003; J. Krüger & R. Westermann, 2003), incompressible cloud dynamics (M. J. Harris et al. 2003), and the compressible Euler equations with high-resolution finite-volume schemes in two and three dimensions (T. R. Hagen et al. 2006). J. D. Owens et al. (2007) surveyed that period. General-purpose toolchains then replaced the graphics route, and astrophysics gained a generation of GPU codes, among them GAMER (H.-Y. Schive et al. 2010, 2018), the adaptive solver of P. Wang et al. (2010), the Euler solver of P. Kestener et al. (2010), Cholla (E. E. Schneider & B. E. Robertson 2015), FARGO3D [7], Astaraoth (J. Pekkila et al. 2017), K-Athena (P. Grete et al. 2021), Quokka (B. D. Wibking & M. R. Krumholz 2022), Idefix (G. R. J. Lesur et al. 2023), Kratos (L. Wang 2025), AthenaK (J. M. Stone et al. 2026), AGILE (O. Porth et al. 2026) and RAMSES-GPU (R. Teyssier et al. 2026). These codes are fast and scale to many devices, but each is a native application built with CUDA, HIP or a portability layer.
WebGPU, a graphics and compute interface that browsers now ship, brings compute shaders to every desktop and many phones without an installation step. Its shading language, WGSL, compiles to whatever the local driver accepts. Simulators that use the GPU from a browser exist for reaction-diffusion and cardiac models (A. Kaboudian et al. 2019), for the Gross-Pitaevskii equation [3], and for plasma turbulence: A. Mallet & E. Abraham (2026) wrote a WebGPU solver for reduced MHD that runs in the browser, a port of their pseudospectral code taranis.1 We found none that solves the compressible Euler or MHD equations with shocks, self-gravity or adaptive refinement (§ 1.1).
This paper describes Shaderous, a code that does. All fluid and gravity computation runs in WGSL compute shaders, and the code runs at a web address. Nothing in the scheme is specific to astrophysics. It solves the compressible Euler equations, or the equations of ideal magnetohydrodynamics (MHD), with optional gravity, diffusion, heating, cooling and nuclear burning, and serves the same purpose in a course on fluid dynamics or for a problem in another field. We demonstrate it on astrophysical problems because they exercise every part of the code at once: strong shocks, self-gravity, stars that must stay in hydrostatic balance, point masses that accrete, magnetized disks, detonations, and equations of state as far from an ideal gas as degenerate electrons. The physics is conventional and we credit its sources throughout. What is new is how the scheme is mapped onto an interface designed for graphics. WebGPU forbids a pass from reading and writing the same four-channel floating-point texture, has no double precision, limits the number of storage bindings, and returns data to the CPU only asynchronously. We turned each restriction into a design choice. The result is a code that conserves to round-off on an adaptive mesh without storing a single hydrodynamic face flux, that never exchanges ghost cells, that keeps every step on the GPU, and that keeps hydrostatic objects in balance and magnetic fields free of divergence in single precision.
§ 1.1 compares Shaderous with earlier work. § 2 describes the constraints of WebGPU and the data layout that follows from them. § 3 gives the hydrodynamic scheme, including mixtures and nuclear burning, § 4 the flux evaluation that conserves without stored fluxes, § 5 the adaptive mesh and its local timesteps, § 6 gravity, point masses and sinks, and § 7 magnetic fields. § 8 describes the interface, the problems, the file format and the interfaces for scripts, § 9 the uses of the code in teaching, § 10 the validation suite, and § 11 performance. § 12 discusses limitations.
Relation to earlier work
We searched for earlier codes in three literatures: general-purpose computation in graphics shaders, GPU codes for astrophysical fluids, and scientific simulators that run in a browser.
The shader-era solvers are the closest in spirit. T. R. Hagen et al. (2006) solved the compressible Euler equations on uniform grids in fragment programs, and N. Goodnight et al. (2003) and J. Bolz et al. (2003) ran multigrid in the same way. Adaptive data structures in textures also came from computer graphics: A. E. Lefohn et al. (2006) built page tables and octrees in textures for random access on the GPU. Shaderous uses compute shaders rather than fragment programs, but it inherits the same model of state held in textures and updated by one invocation per cell. It adds what those solvers did not have: self-gravity, adaptive refinement with conservative coupling between levels, local timesteps, and the physics of astrophysical problems.
Among GPU codes for astrophysics, GAMER (H.-Y. Schive et al. 2010, 2018) and the code of P. Wang et al. (2010) are the closest in structure: both refine in fixed-size patches or blocks, as Shaderous does. They follow M. J. Berger & P. Colella [8] in correcting the coarse side of a refinement boundary with fluxes stored from the fine side. The hydrodynamic solver of Shaderous stores no fluxes at all (§ 4).
Several of these codes also solve ideal MHD with the constrained transport of C. R. Evans & J. F. Hawley (1988), among them K-Athena, Idefix and AthenaK, which follow the unsplit integrators of Athena (T. A. Gardiner & J. M. Stone 2005; J. M. Stone et al. 2008; J. M. Stone & T. Gardiner 2009). The MHD solver of Shaderous uses the same integrator (§ 7), and like those codes it stores its face fluxes and keeps a flux register at refinement boundaries.
The browser simulators of A. Kaboudian et al. (2019) and A. W. Baggaley [3] show that interactive computing on the GPU through WebGL and WebGPU is practical. They solve reaction-diffusion and Schrödinger-type equations on uniform grids, where no conservation law has to hold across a shock or a refinement boundary.
The closest earlier code is the WebGPU solver for reduced MHD of A. Mallet & E. Abraham (2026), which ports the pseudospectral algorithms of their JAX code taranis to the browser. Like Shaderous, it runs in WebGPU compute shaders in single precision, and it solves a magnetized fluid in two and three dimensions. Reduced MHD assumes a strong guide field and a nearly incompressible plasma, so shocks cannot form, and the pseudospectral method needs a uniform periodic grid. Within those limits, it follows Alfvénic turbulence with little numerical dissipation and offers tools that Shaderous lacks: random forcing in a band of wavenumbers, energy spectra, and Elsässer variables. Shaderous solves the full compressible equations with shocks, gravity and adaptive refinement, but its Godunov scheme dissipates more at a given resolution.
Constraints of WebGPU and the data layout
Four properties of WebGPU shaped the code. Each is a property of the interface, not of the hardware.
No read-write access to four-channel floating-point textures. A compute pass can write an rgba32float texture only as a write-only storage texture. Every update therefore reads one copy of the state and writes another. Single-channel r32float textures can be read and written in one pass, which the red-black smoother of the Poisson solver uses.
Limited storage buffers. The default limits allow few storage buffers per shader stage and cap a single binding at 128 MB. We hold the state in 3D textures instead: density and momentum in one rgba32float texture, and total energy, internal energy and a passive scalar in a second. We measured the same flux stencil on storage buffers and found it about 1.4 times slower than on textures.
No double precision. WGSL has no 64-bit floating-point type. Every quantity is a 32-bit float, and the scheme has to hold hydrostatic balance, track internal energy in fast flows, and keep the magnetic field free of divergence at that precision (§ 3.3, § 3.4 and § 7.1).
Asynchronous readback. Data return to the CPU only through a mapped buffer, some frames later. A code that reads the timestep back before every step would stall. Shaderous computes the timestep on the GPU, writes it to a small buffer, and lets the following passes read it there. The CPU reads diagnostics and refinement indicators without waiting for them.
WGSL also has no dynamic dispatch. A small preprocessor assembles each shader from modules: the equation of state, the Riemann solver, the slope limiter, the cooling function and the diffusive fluxes in use are chosen when the shaders are built, and changing one rebuilds the affected pipelines. A module that is switched off maps to a stub, so a run without species, cooling or diffusion pays nothing for them.
Reductions run in stages. The timestep, the diagnostics and the refinement indicators all use them. Each stage folds blocks of records from the stage before, so sums are formed hierarchically, which limits the round-off of single precision. Maxima of non-negative values are accumulated with an atomic maximum on their bit patterns, which order the same way as the floating-point values.
No browser reports how much memory its GPU has, and a phone that runs out kills the page before WebGPU reports an error. Shaderous therefore guesses a memory budget from what the browser does report: 2.5 GB for a discrete desktop GPU, 2 GB where the GPU shares the system’s memory, and 1 GB on a phone. The user can change it. Before each large allocation the page leaves a note in the browser’s local storage. A note that is still there when the page next loads means that the page crashed holding that much memory, and the budget is then lowered below it for good. A run without a person at the page, on a server, takes its budget from the command line (§ 8).
Hydrodynamics
Shaderous solves the Euler equations with gravity,
where is the density, the velocity, the pressure, the total energy density, the gravitational potential, the identity, and and the heating and cooling rates per unit volume. A passive scalar is advected with the gas, and the internal energy density is evolved alongside (§ 3.3).
Scheme
The scheme is an unsplit MUSCL-Hancock method ((B. van Leer 1979), in the form given by E. F. Toro (2009). A predictor pass advances each cell half a step from its own reconstructed slopes. An update pass then reconstructs face states from the half-step values, solves a Riemann problem at each of the cell’s six faces, and applies the flux differences and the gravitational source. With the passes that compute the signal speed and reduce the timestep, a step is four passes. On the uniform grid no primitive variables are stored: the predictor and the update convert the conserved state as they load it, because the flux update is limited by texture fetches (with all of its arithmetic removed, it still takes 85 percent as long) and a pass that only rewrites the state costs more than repeating the conversion. Figure 1 shows the accuracy of the scheme on a shock tube, a blast and a smooth flow.
Figure 1. Accuracy of the hydrodynamics. (a) Density, velocity and pressure of the Sod shock tube at along the middle row of a grid (points), and the exact solution (lines). (b) Density against distance from the center for the leaf cells of a three-dimensional Sedov blast on the adaptive mesh (finest resolution 256 cells, three levels) at , every 33rd of the 6.5 million cells (points), and the similarity solution (line). (c) Mean density error against the number of cells per side for a Gaussian advected once around the periodic box along a diagonal, with the default limiter of B. Koren (1993) and the monotonized central limiter, and for the Sod tube; gray lines show first-, second- and third-order convergence.
The timestep is the smallest of three limits: , , and the limit of each pair of point masses (§ 6.4). Here is the CFL number, the cell size, a component of the velocity, the sound speed, and the gravitational acceleration. The maxima run over all cells. The step is also shortened so that it ends exactly on the next output time. Viscosity and conduction add a signal speed (§ 3.6); cooling does not limit the step (§ 3.5).
The fluxes come from the HLLC solver of E. F. Toro et al. (1994), the HLL solver of A. Harten et al. (1983), or a low-Mach variant of HLLC. Wave speeds are the estimates of S. F. Davis (1988), and . Here is the velocity normal to the face, the sound speed, and L and R denote the two sides of the face. These estimates need only the pressure and the sound speed on each side, so the solvers do not depend on the equation of state. Barotropic gas uses HLL, since it has no contact wave for HLLC to resolve.
The low-Mach variant follows B. Thornber et al. (2008): the velocity jump handed to HLLC is scaled by the local Mach number, so that slow flow is not damped at a rate set by the sound speed:
We set the floor to 0.3. With one predictor and one update and the unlimited third-order reconstruction below, the scheme relies on some of the solver’s damping, and a Gresho vortex (P. M. Gresho & S. T. Chan 1990) at Mach 0.01 gains kinetic energy without bound for a floor of 0.1 or less. With the floor at 0.3, that vortex on cells loses 6 percent of its kinetic energy in two time units, against 15 percent with plain HLLC. Scaling the acoustic wave speeds instead, as N. Fleischmann et al. (2020) do, also removes the damping of pressure jumps and was unstable in this scheme at Mach 0.03.
Reconstruction
The default reconstruction gives each face the value of the parabola through the cell and its two neighbors, which is third-order accurate on the three-cell stencil that a slope limiter already uses. The face value is , where is the value in the cell, the difference to the neighbor on the side of the face, and the difference to the neighbor on the other side. A three-cell limiter cannot tell a smooth extremum from a jump and flattens both. Following the idea of M. Čada & M. Torrilhon (2009), we apply a limiter only where a quantity changes by more than 1 percent of its natural scale across a cell: the density, the pressure, or the sound speed for the velocities. Calling that scale , the face value blends from the unlimited value to the limited one as rises from 0.5 to 1.5. The limiter is that of B. Koren (1993) with the bounds of the monotonized central limiter (B. van Leer 1977). A smooth peak then keeps its height: the largest error in the advection test is 2.5 to 5 times smaller than with the monotonized central limiter (Figure 1c). Kinks and jumps smaller than 1 percent go unlimited, and shock-tube errors are a few percent higher on axis-aligned tubes. The monotonized central, B. van Leer (1974) and minmod (P. L. Roe 1986) limiters remain available.
Robustness in single precision
Single precision loses the pressure of gas whose kinetic energy dominates its total energy. We evolve the internal energy alongside the total energy and use it where the kinetic energy dominates, after the dual-energy formalism of G. L. Bryan et al. (1995). The internal energy that we evolve replaces the difference of the total and kinetic energies wherever that difference is below of the total energy, or below the least internal energy that the equation of state allows. Where we use it, we rebuild the total energy from it, except in degenerate gas. There we keep the total energy as the conservative update left it and take only the pressure from the internal energy, because a degenerate gas has a pressure, at least that of its cold electrons, even where the total energy minus the kinetic energy is negative. In a collision of two white dwarfs that difference turns negative in the cell ahead of each strong shock. Rebuilding the total energy there added 2.3 percent to it at the moment of greatest compression. Keeping it leaves a change of 0.6 percent through the collision. A face state with a non-positive density or pressure drops its cell to first order for that step. Next to a cell flagged by a pressure-jump shock detector, the flux blends from HLLC toward HLL, which suppresses the carbuncle instability (J. J. Quirk 1994). The detector flags a cell where the flow converges and the pressures of its two neighbors along some axis differ by more than half of the smaller one. It measures that difference against hydrostatic balance (§ 3.4). Density and pressure floors, by default and in code units, catch what remains, and the number of floored cells is reported as a diagnostic.
Well-balanced reconstruction
In hydrostatic balance the pressure is not smooth across a stratified cell; its balance with gravity is. Following R. Käppeli & S. Mishra (2014), what is limited and reconstructed is each neighbor’s deviation from that balance,
where the subscripts c and n denote the cell and its neighbor. The balanced part of the step to the face, , is added back unlimited. Where the cells obey the trapezoid rule of Equation (2) with , the two cells that share a face agree on its pressure, and a cell’s two face pressures differ by exactly the momentum that the gravity kick adds. The state then holds to round-off however steep it is. The shock detector measures pressure jumps against the same balance, so that a steep atmosphere at rest is not flagged as a shock. An isothermal column whose density falls by a factor of every four cells keeps its largest Mach number at after a sound crossing, against 0.35 without the balanced reconstruction (Figure 2a). The background of the Rayleigh-Taylor problem is 240 times quieter, and the error in the growth rate of the Jeans instability is 12 times smaller.
Figure 2. Hydrostatic balance in single precision. (a) Largest Mach number in an isothermal column whose density falls by a factor of every four cells, over one sound crossing, with the well-balanced reconstruction (solid) and without it (dashed). (b) Central density of a white dwarf of on the adaptive mesh (finest resolution 256 cells, two levels), settled against the grid’s own potential (solid) and mapped from its analytic profile (dashed), relative to its starting value.
Equations of state and cooling
Every equation of state implements the same four functions (pressure, sound speed, internal energy from pressure, temperature), so the hydrodynamic passes are independent of it. Shaderous provides an ideal gas, a barotropic gas (isothermal or polytropic), and an ideal gas plus radiation pressure in local thermodynamic equilibrium, whose temperature comes from a Newton iteration with a fixed number of steps. Each WGSL module has a double-precision mirror in TypeScript for testing.
Three further equations of state use the composition of the gas, which a problem with physical units gives as a list of species and their mass fractions. The first adds the pressure of fully degenerate electrons at any degree of relativity (S. Chandrasekhar 1935) to an ideal gas and radiation, for white dwarfs. Its density scale follows from the number of electrons per nucleon. Each part is thermodynamically consistent on its own, so the square of the sound speed is the derivative of the degenerate pressure plus of the thermal part. Where the Fermi momentum is below half of , the pressure and energy of the degenerate gas are summed as series, because their closed forms cancel to nothing in single precision. The second equation of state lets hydrogen ionize in Saha equilibrium (M. N. Saha 1920), so that the mean molecular weight and the internal energy, which includes 13.6 eV per ionization, follow the temperature. Its adiabatic index is computed exactly and dips below 1.3 in the ionization zone. Its temperature comes from Newton’s method kept inside a bracket.
The third equation of state is for white dwarf matter that burns. It treats the electrons and positrons at any degeneracy and temperature, in the manner of F. X. Timmes & F. D. Swesty (2000). The first equation of state gives every electron a thermal energy of on top of the degenerate gas, which is far more heat than degenerate electrons take up. It therefore reads shocked degenerate fuel two to five times too cold: at , gas at reads as . Burning rates rise as or faster, so the error decides whether a detonation ignites. We evaluated the Fermi-Dirac integrals of the electron-positron gas in double precision and tabulated its thermal free energy, less that of the pairs at zero net charge, with its first derivatives. The table runs in and at intervals of 0.02 dex. Pressure and energy are first derivatives of the free energy, so a bicubic Hermite interpolation keeps them thermodynamically consistent. The pairs at zero charge depend on the temperature alone and are a Chebyshev series in it. The ions are an ideal gas, and radiation is added. Against the exact gas, the double-precision mirror gives the energy and the pressure to and the square of the sound speed to (99th percentile). The GPU matches the mirror to in energy and pressure, which is what single precision allows for a temperature found by iteration.
The hydrodynamic state gives the energy or the pressure, so the temperature comes from Newton’s method in . Each step of the iteration reads four neighboring texels. It starts from a coarse table of the inverse at three mean nucleon numbers, and it converges in 2.6 iterations on average, against 9.3 from a guess that treats the gas as classical. The table, its inverse and the pair series fill one texture of 4.3 MB. With the burning network running, a carbon-oxygen detonation took 15 percent longer per step than with the first equation of state. We also fitted small neural networks to the free energy and to its inverse. On the GPU, the table with Newton’s method was three times faster than the best inverse network and about a thousand times more accurate.
Optically thin cooling is either a power law in temperature with uniform heating, or the interstellar cooling function of H. Koyama & S.-i. Inutsuka (2002) with the correction of E. Vázquez-Semadeni et al. (2007). In the second, the internal energy per unit volume changes at the rate , where is the number density of hydrogen atoms in , the heating rate per atom, the temperature in kelvin, and
Cooling is applied to the internal energy at fixed density at the end of the update, in up to 12 second-order substeps that each change the energy by at most a tenth. A substep that would cross thermal balance stops at the balance point, so cooling times far shorter than the timestep are stable and do not overshoot. The timestep is not shortened for cooling.
Viscosity and conduction
Shaderous can add a viscous stress and a conductive heat flux to Equation (1). The momentum flux gains and the energy flux gains , with
where is the temperature, and the kinematic viscosity and the coefficient are constants. The temperature of an ideal gas with adiabatic index then diffuses at .
Both fluxes are evaluated explicitly from the state at the start of the step and added to the Riemann flux of each face. Derivatives along the normal of a face are differences of its two cells. Derivatives across it are the mean of the centered differences in the two cells. Because the diffusive terms are part of the face flux, the properties of that flux carry over to them. The two cells that share a face compute the same bits, and the matching of § 5.2 and § 5.3 conserves momentum and energy across refinement boundaries and between blocks on different timesteps. On the adaptive mesh the transverse differences on the rim of a block’s face would need edge ghost cells, which Shaderous never computes. Both blocks that share the face use one-sided differences along the rim instead. A face of an obstacle is a wall at rest to which the gas sticks and through which no heat passes. The heat that the stress dissipates is added to the separately evolved internal energy (§ 3.3).
The timestep counts diffusion as an additional signal speed of , where is the number of dimensions, the cell size, and the larger of and the thermal diffusivity. The step therefore falls as where diffusion dominates. There is no implicit solve, so strong diffusion on a fine mesh is slow. Viscosity lengthens the flux update by a factor of 1.6 in two dimensions and 1.8 in three, because the transverse derivatives need the cells diagonally across from the one being updated. Conduction alone adds no measurable time.
Species
A problem can carry any number of species, as mass fractions that sum to one. They are stored apart from the hydrodynamic state, as in four-channel textures, and the hydrodynamic passes never read them. The update records the mass flux through every face, and a separate pass then moves every species with it. The flux of a species through a face is the mass flux times the fraction of that species in the upwind cell at the half step, extrapolated to the face with its limited slope, as for the passive scalar.
Each species has its own monotonized central slope, so a sharp front in one species does not flatten the others. The slopes then need not sum to zero, while the fractions on a face must sum to one. We therefore take the excess back from the slopes of the sign that has too much, each in proportion to its size. This only shrinks slopes, so no face value leaves the range of the neighboring cells, and a species that is uniform stays uniform. Scaling the face fractions so that they sum to one, as in the consistent multi-fluid advection of T. Plewa & E. Müller (1999), would change such a species. Because the face fractions sum to one, moves exactly as does, and every fraction stays between zero and one. What rounding leaves is removed by scaling the new values to the new density. On the adaptive mesh a coarse cell takes the average of the fine cells’ species fluxes, as it does for the mass (§ 5.2). Local timesteps are not yet available with species.
When every species is a nuclide, or dry air taken as one species for laboratory flows, the equation of state follows the composition of each cell, and each species may have its own adiabatic index. Each equation of state needs at most four numbers from the composition, and each is a sum over the species weighted by mass fraction, so they mix linearly. A texture beside the state holds them. For an ideal gas they are the inverse of the mean molecular weight and the heat capacity, so that the adiabatic index of a mixture follows from the heat capacities of its gases summed by mass, the mixing rule of ideal gases at one temperature.
A conservative scheme that carries mass fractions makes the pressure oscillate where two gases with different adiabatic indices meet ([1] (S. Karni 1996)). In Shaderous the cause is that the density and the mass fractions are reconstructed in different passes, so that at a face they disagree on how much of each gas crossed it. A contact between helium and air at one temperature, carried across the box, erred by 3.7 percent in pressure. Where differs between neighbors by more than 1 percent, the predictor and the species passes therefore blend their face values toward first order, fully so at a difference of 5 percent. The same contact then errs by 0.2 percent. The blend is continuous because an on-off switch turned round-off into differences of 5 percent between mirror-image cells of the shock-bubble problem (§ 8.1). On the adaptive mesh a jump of 0.1 in any mass fraction between neighbors also refines a block, because an interface smeared over a few coarse cells looks smooth to the indicator of § 5. Without this criterion, the helium bubble of J. J. Quirk & S. Karni (1996) drifted onto coarse blocks, and 24 percent of its helium ended at the finest level, against 99 percent with it.
Nuclear burning
A problem can burn its species in one of two ways, in a pass of its own after the species pass, on the uniform grid and on the adaptive mesh alike. The first is the single-step Arrhenius reaction that is the standard model in the theory of detonations (W. Fickett & C. K. Davis 1979). The fraction of fuel falls as , where is a rate constant, the activation temperature and the temperature, and each unit of mass that burns releases an energy into the gas at fixed density. The pass splits the time step into up to eight substeps, none of which releases more than a fifth of the cell’s internal energy, and solves each exactly at its starting temperature, so the burn never overshoots however stiff it is. The timestep is not shortened for burning. On the adaptive mesh, blocks are refined where the burning length, the distance that sound travels while the burn releases the cell’s internal energy, is shorter than 80 cells.
A problem also chooses whether cells that the shock detector flags may burn. Where the front is far thinner than a cell they should not, because a captured shock is a few cells of numerical smearing through states that no real gas passes through, and burning there lets the scheme rather than the reaction set the speed of the front (P. Colella et al. 1986). Where the reaction zone is resolved they should. A stable detonation started from its exact steady solution, with 12.8 cells per half-reaction length, then runs within 1 percent of the Chapman-Jouguet speed, on the uniform grid and on the adaptive mesh. With burning suppressed in shocks it falls 5 percent short, an error that halves with each doubling of the resolution.
The second is the 13-isotope -chain of F. X. Timmes et al. (2000), for white dwarf matter, stepped by a small neural network rather than by an implicit integrator. We built the reference network with pynucastro (A. Smith Clark et al. 2023), from the rates of REA-CLIB (R. H. Cyburt et al. 2010) with the screening that pynucastro applies, and integrated it at constant density with the heat that the burning releases. The neural network takes the logarithms of the density, temperature and timestep, the mass fractions, and the logarithm of every screened rate term of the reference, and returns the change in composition through four hidden layers of 128 units. The rate terms are inputs because they rise with temperature far more steeply than a network of this size could resolve from the temperature alone. The output is built so that mass is conserved exactly and no fraction falls below zero, whatever the weights: each species loses a share of itself, and a softmax distributes what is lost among the species. The energy released is the change in nuclear binding energy and is not predicted, so energy and composition always agree. The states that the network reaches when it is applied step after step were labeled with the reference network and added to its training set, in 30 rounds of the DAgger method of S. Ross et al. (2011). On the GPU, in single precision and half-precision weights, one step on 48 states from held-out burns matches a float64 copy of the network to 2 percent in the change of composition. Only gas hotter than K and denser than g cm burns, the range of the training set, and a hydrodynamic step longer than 10 ms is split into network steps. Following D. Kushnir et al. (2013), a run can limit the rate at which a cell takes in energy from burning to , where is the internal energy density, the time that sound takes to cross the cell, and a chosen factor. Each network step is then scaled down as a whole, which keeps mass conserved and every fraction positive. The limiter is off by default. In detonations in a tube with cells of 0.5 to 4 km, below about 0.2 stopped even resolved detonations, while matched the unlimited front and removed the early ignition that 4 km cells otherwise give. With the first equation of state of § 3.5, the head-on collision of two white dwarfs of detonated on contact on cells of 940 km and made of , as collisions of such dwarfs do in simulations that resolve them (C. Raskin et al. 2010; D. Kushnir et al. 2013). With the limiter at and 0.4 it made only 0.008 and . That equation of state gives shocked degenerate fuel a temperature two to five times too low, and the runs with burning now use the third one. With it, the same collision made of . The network was still trained on burns that heat the gas as the first equation of state does.
Conservation without stored fluxes
Most finite-volume codes on GPUs evaluate each face flux once, store it, and difference the stored fluxes. The hydrodynamic solver of Shaderous gathers instead: each cell needs the fluxes on its own six faces, and a face that two cells share is evaluated wherever either of them needs it. Conservation then requires that the evaluations agree bit for bit. They do if they read identical inputs and perform identical arithmetic in the same order. Every quantity that enters a face flux, including the potential differences of the well-balanced reconstruction, is formed from the same values whichever cell asks. Figure 3 shows the three places where a face is shared: within a level, across a refinement boundary (§ 5.2), and between blocks on different timesteps (§ 5.3).
Figure 3. How the hydrodynamic solver conserves without storing a face flux. The shared face is orange, and each arrow across it is one evaluation of its flux, colored by the side that makes it. (a) Two cells of one level each evaluate the flux of the face between them, from the same inputs with the same arithmetic, and get the same bits. (b) At a refinement boundary, shown in two dimensions, each fine cell evaluates the flux of its own face against a ghost cell that is computed as it is loaded. The coarse cell evaluates the same fine fluxes again and takes their mean. (c) Between time bins, with time running to the right, the slower block takes the fluxes of the faster block’s two substeps, the first when its own step starts and the second at its midpoint. The faster block reads the slower one from its half-step prediction (dashed).
Identical source code is not enough. WGSL lets a compiler fuse and reassociate floating-point operations, and the Metal backend of Chrome compiles shaders in a relaxed mode that does so. On an Apple M4 Pro, a cell’s lower face and its neighbor’s upper face, computed by two calls of the same function, differed in the last bit on thousands of faces. Every face that two cells share is therefore computed at one place in the code and in one compiled pipeline. For the same reason, compensated sums pass their intermediate values through an exclusive-or with a zero that the compiler cannot see, which keeps it from simplifying the compensation away.
Within a workgroup, the update computes each face of the workgroup’s box of cells once, into workgroup memory, and each cell reads its six faces from there. The neighboring workgroup computes the faces on the edge of the box again, so no flux leaves the pass. This made the largest uniform grids 1.3 to 1.5 times faster on an Apple M4 Pro ( and cells). Gathering still evaluates the faces on the edges of the boxes twice. In exchange there is no flux storage, no second pass to difference fluxes, and no race between invocations that write the same face. The validation suite checks the property directly: for three flows, the two cells that share each face compute bit-identical mass fluxes on every face. A uniform state advected ten times across the box conserves mass and every momentum component to the round-off of single precision.
The other stencil passes are compiled twice from one source. Cells at least two cells from every boundary use a version with the boundary mapping compiled out; the shell uses the general version, dispatched in slabs two cells thick so that it launches no more invocations than it has cells. The update is not split this way, so that every face comes from one pipeline, at a cost of about 10 percent. Boundaries (periodic, outflow, outflow without inflow, and reflecting, chosen per face) are applied in the function that maps a cell index to a texel, so the uniform grid has no ghost cells.
Adaptive mesh refinement
The adaptive mesh is a tree of blocks of cells ( in two dimensions). A block splits into eight children of half the cell size, and face neighbors differ by at most one level. Each field lives in one 3D texture atlas that holds every block, with two ghost layers around each. The tree itself is small and lives on the CPU, which uploads it to the GPU as flat tables whenever the mesh changes. Every few steps a pass reduces a refinement indicator per block, the CPU reads it back without blocking, adapts the tree, and one pass fills the new leaves by copying, prolonging or restricting from the old state. Blocks are refined where the normalized second derivative of the density or the pressure exceeds 0.8. Sibling blocks are merged when it falls below 0.2 in all of them. This is the error indicator of R. Löhner (1987) in the form that FLASH uses (B. Fryxell et al. 2000), including a filter that ignores ripples of about one percent of the local value. For a quantity in cell , it is
where , , the neighbors are taken along each axis in turn, the sums run over the axes, and is the filter. The indicator is close to 1 at a discontinuity and falls in proportion to the cell size across a smooth profile. An indicator that is based on first differences refines smooth gradients as readily as shocks, and in our tests it kept most of the disk of the binary problem at the finest level. With self-gravity, blocks are also refined where the Jeans length falls below 16 cells. A problem can also ask that every block near its point masses be kept at the finest level (§ 6.4), or every block with gas above a given density. The white dwarf problems use the second, because the smooth interior of a star does not raise the indicator. Figure 4 shows meshes that the indicator builds in two and three dimensions.

Figure 4. The adaptive mesh, drawn by the code’s own renderer. (a) Density of a two-dimensional Kelvin-Helmholtz instability at , at an effective resolution of with three levels of refinement; the faint lines outline the blocks of cells. (b) Refinement level of the same state. (c) Slice through a three-dimensional Sedov blast (finest resolution 256 cells, three levels) with local timesteps, each block colored by its time bin; a block in bin steps times the smallest step. The hot gas behind the shock takes the smallest steps, and the cold gas outside it the largest.
Ghost cells computed on load
Because a pass cannot read and write one rgba32float texture, ghost cells cannot be filled in place by copying from neighbors. Shaderous does not fill them. The pass that converts the conserved state to primitive variables computes every texel of a block, ghost or interior, directly from wherever its value lives: the same block, a neighboring block, the image of a cell across a physical boundary, the average of the finer cells that cover it, or an interpolation from a coarser block. There is no separate exchange step, and no ghost cell is ever stale.
Matching fluxes across refinement boundaries
The adaptive solvers of M. J. Berger & J. Oliger (1984) and M. J. Berger & P. Colella [8], and the GPU codes that follow them (H.-Y. Schive et al. 2010; P. Wang et al. 2010), store the fluxes that the fine side computes on a coarse face and correct the coarse cell afterward. Shaderous extends the gathering of § 4 across levels instead. At a refinement boundary the coarse cell recomputes the fluxes of the fine faces that cover its face, from the same fine states, with the same arithmetic as the fine cells (Figure 3b). Mass, momentum and energy are therefore conserved to round-off without storing any flux. The validation suite checks that the fluxes agree bit for bit between blocks on the same level and to across refinement boundaries.
Local timesteps
The subcycling of M. J. Berger & J. Oliger (1984) lets fine levels take more steps than coarse ones. Shaderous assigns timesteps per block rather than per level, using power-of-two time bins in the manner of particle codes such as GADGET-2 (V. Springel 2005). Time advances in cycles of up to eight substeps of the smallest step. At the start of a cycle each block is put in a bin from its own signal speed, on the GPU: a block in bin advances substeps at a time. Relaxation sweeps then enforce three rules: face neighbors are at most one bin apart, a block next to a faster one steps as fast as it, and a block is never slower than a coarser neighbor.
Across a face whose other side steps twice as often, a block takes the other side’s fluxes, recomputed from stored states: half when its own step starts and half at its midpoint (Figure 3c). A faster block reads a slower neighbor that is part way through a step from that neighbor’s half-step prediction. As at refinement boundaries, nothing is stored and conservation holds to round-off. With self-gravity the potential is solved on every block at the end of a cycle. In between, it is solved only on the blocks that finish a step and carried forward elsewhere at the rate at which it last changed.
The extra passes are not free. In three dimensions each block update costs about 10 percent more without gravity and 50 to 70 percent more with it, where every substep also relaxes the potential. Shaderous therefore reads back, every few cycles, the share of block updates that a cycle actually makes, and falls back to a single timestep while that share is above 80 percent (65 percent with gravity). A three-dimensional Sedov blast at a finest resolution of 256 cells with three levels makes 2.2 times fewer block updates with local timesteps and runs 1.9 times faster. An isothermal collapse at the same resolution makes 2.3 times fewer and runs 1.6 times faster. Figure 4c shows how the bins follow a blast.
Gravity, point masses and sinks
Poisson solver
The potential is solved every step by geometric multigrid ((A. Brandt 1977)), with red-black Gauss-Seidel smoothing, restriction by the average of eight cells, and trilinear prolongation, warm-started from the previous potential. A V-cycle makes two smoothing sweeps before each restriction, two after each prolongation, and eight on the coarsest level of cells. A step runs two V-cycles on the uniform grid. On the adaptive mesh it runs up to three, and the later ones only while they still reduce the residual. Periodic boundaries subtract the mean density from the source. For isolated boundaries a reduction computes the mass and its first and second moments about the box center, and the boundary values of the potential come from the monopole and quadrupole terms,
where is the mass, the position relative to the center of mass, , the second moments of the mass about its center, and repeated indices are summed. The dipole term vanishes about the center of mass.
On the adaptive mesh the potential lives on every block, parents included. The density is averaged into the parents, a level’s ghost cells come from its neighbors or are interpolated from the level above, and a multigrid cycle runs inside the blocks, at 16, 8, 4, 2 and 1 cells across. The coupling between levels is one-way: a fine level never corrects the coarse potential beneath it. On a uniform sphere the error stays below 0.3 percent with three levels. A new mesh is solved level by level from the coarsest down. During a run all levels relax in the same dispatches, each against the boundary values that its coarser level had at the start of the cycle, so the cost does not grow with the depth of the tree.
Coupling to the gas
Gravity enters the update as kick-drift-kick: half a kick with the old potential inside the update pass, and the other half after the new potential is solved. Applying the whole kick after the flux update leaks internal energy from gas in hydrostatic balance and slowly cools a star. The gravitational energy source defaults to a flux form, in which the work on a cell is the mass flux through each face times the difference of the potential across it, as in V. Springel (2010). Along one axis, the energy of cell changes by
where is the mass flux through a face and is extrapolated to the half step; the axes add. The work that leaves one cell enters its neighbor, so this conserves total energy. The alternative adds exactly the kinetic energy of each kick, so gravity never touches the internal energy, at the cost of total-energy conservation where the flow is under-resolved. Figure 5a compares the two forms in the collapse of A. E. Evrard (1988). The pull of the point masses (§ 6.4) and of an accelerating frame always takes the kick form. Debris torn from a star is cold and fast, and each step the tidal field changes its kinetic energy by hundreds of times its internal energy. In flux form, the mismatch between that work and the kick, which is of the order of the truncation error, went into the internal energy. It cut the entropy of the leading half of a disrupted polytrope of index 3 a hundredfold. In kick form the entropy of the star holds to about 0.1 dex. Optionally, a pressure floor keeps the Jeans length resolved by a chosen number of cells, at least the four of J. K. Truelove et al. (1997).
Figure 5. Gravity. (a) Kinetic, thermal, gravitational and total energy during the collapse of A. E. Evrard (1988), with the gravitational energy source in flux form (solid) and kick form (dashed), on a uniform grid of cells (thick lines) and on the adaptive mesh with a finest resolution of 128 cells and two levels (thin lines). After the outgoing shock reaches the edge of the box and gas leaves it. (b) Relative error of the potential of a uniform sphere with isolated boundaries, along the axis through its center, on a uniform grid and with two and three levels of refinement; the sphere fills the shaded interval.
Initial states in discrete balance
A star set up from its analytic profile is in balance with the analytic potential, not with the one that the Poisson solver finds on the grid, and it rings in response to the mismatch. As M. Zingale et al. (2002) do for stellar models mapped onto a grid, Shaderous settles every star of a problem before the first step. The density is set to satisfy with the grid’s potential and the star’s mass, where is the specific enthalpy of the star’s cold gas and a constant, the potential is solved again, and the two are repeated until the density changes by less than , which takes six to eight rounds for a polytrope. Several stars settle together, in the same rounds. Each is balanced in its own potential: the grid’s potential less the pull of the other stars, which outside a spherical star is that of a point of its mass. A star that moves keeps its velocity. A round changes only the density, and is found by regula falsi from its value in the previous round. For white dwarfs each round’s change is over-relaxed by a factor of 1.6, and the rounds stop at a change of . They settle in 7 to 12 rounds, which take 1.6 to 5.5 s at finest resolutions of 256 and 512 cells. Mapped without settling, a white dwarf of one solar mass rang in its fundamental mode, and its central density swung by 30 percent at a finest resolution of 256 cells (Figure 2b). Its core is close to relativistic, with not far above 4/3, so the small mismatch meets little restoring force. Settled, the central density stays within 0.5 percent over six dynamical times. For a polytrope of index 1 this relation is exactly the trapezoid rule of Equation (2). On the adaptive mesh, at finest resolution of 128 cells with two levels, the central density of the settled polytrope strays by 0.14 percent over three dynamical times, against 0.26 percent for the plain scheme, and its energy by 0.33 percent against 0.77 percent.
Point masses and sinks
Up to four point masses act on the gas through Plummer-softened gravity (H. C. Plummer (1911)). The gravity field texture holds self-gravity alone. Every pass that needs the pull of the masses (the kicks, the predictor, the timestep, the well-balanced reconstruction) adds it from their positions as the pass runs. The potential difference of a mass between neighboring cells is formed as , with , where and are the softened distances of the two cells from the mass and its softening length, rather than as the difference of two potentials thousands of times larger. Each step the masses drift; then one reduction over the updated gas gives every mass its pull on the gas, whose reaction moves the mass, and what its sink takes. The second half-kick pass removes exactly that amount from the cells. Inside a sink radius gas is removed at a rate that falls from at the center to zero at the radius, and the gas that is removed takes its momentum to the mass. Mass and momentum are conserved between gas and masses to in the validation test. Sinks in grid codes go back to M. R. Bate et al. [6], M. R. Krumholz et al. (2004) and C. Federrath et al. (2010); our removal at a local orbital rate is closer to the sinks of circumbinary-disk studies, such as B. D. Farris et al. (2014), who remove gas on a local viscous timescale. The pull between two masses is softened by the larger of their two lengths. By default the softening length and the sink radius of a mass are two cells. On the adaptive mesh these are cells of the finest level when the problem keeps the blocks near its masses at that level, as the binary problem does. Otherwise they are cells of the coarsest level, the only size that the mass is sure to find.
The timestep of the gas does not follow two masses that pass close to one another. Each pair of masses therefore limits the step to one sixteenth of the CFL number times the lesser of and , where is the softened separation of the pair, its relative speed and its total mass. At the default CFL number of 0.8 a circular orbit takes about 125 steps. Two masses on an orbit of eccentricity 0.9 in near-empty gas keep the energy of the orbit to 0.7 percent over two periods with this limit. Without it they lose 94 percent.
The frame is inertial unless a problem asks for another. The tidal disruption problem uses the rest frame of the gas: as in the simulations of J. Guillochon et al. (2009) and J. Guillochon & E. Ramirez-Ruiz (2013), the frame accelerates with the center of mass of the gas, so the star stays at the box center while the perturber’s orbit is integrated alongside the gas. The binary problem uses the rest frame of the masses instead. That frame accelerates with the mean pull of the gas on the masses, and the gas feels the opposite acceleration. After each step we also set the velocity of the masses’ center of mass back to zero, which removes the slow drift that rounding in their mutual pull and the momentum of accreted gas would cause. The box, its boundaries and the damping zone of the disk (§ 8) then move with the binary.
Magnetic fields
With a magnetic field, Shaderous solves the equations of ideal MHD in units in which the magnetic pressure is , so that the plasma , and the total energy includes . Gravity, point masses, sinks, cooling, viscosity, conduction, species and burning act on magnetized gas as they do without a field. A sink removes mass, momentum and the kinetic and internal energy of the gas that it takes, but leaves the field, which it could not remove without breaking constrained transport. Viscosity and conduction stay isotropic: the code has no transport that follows the direction of the field. Figure 6 shows the field lines of two of the magnetized problems of § 8.1, as the code draws them (§ 8).

Figure 6. Magnetic field lines, drawn by the code’s own renderer and colored by the magnetic pressure on a logarithmic scale. (a) The vortex of S. A. Orszag & C.-M. Tang (1979) on cells at . The background is the density, and the lines are 28 contours of the flux function, so the same magnetic flux passes between any two neighbors and the lines crowd where the field is strong. (b) A star threaded by a dipole field at , about two dynamical times after it passed a black hole of at ( at the finest level, three levels of refinement). The lines are traced in three dimensions from 256 seeds and drawn as tubes. The stripped streams stretch their field straight, and the surviving core winds its field up. The arrows give the orientation of the axes.
Constrained transport
The field lives on the faces of the cells, as in the constrained transport of C. R. Evans & J. F. Hawley (1988). Each face is updated from the electric fields on its four edges, and every edge enters the faces around it with opposite signs, so the divergence of no cell changes. An initial field is the discrete curl of a vector potential sampled on the edges, so it starts free of divergence to rounding. The integrator is the van Leer predictor-corrector of J. M. Stone & T. Gardiner (2009), as in Athena++ (J. M. Stone et al. (2020)). A first stage takes half a step with first-order fluxes. A second stage takes the whole step with fluxes from a limited linear reconstruction of the half-step state. Each stage computes every face flux once into a storage buffer, from which both cells read it, then the electric field on each edge, then the update of cells and faces. These passes run in slabs along one axis, so the buffers hold a few layers of the grid at a time.
The electric fields on the edges follow the construction of T. A. Gardiner & J. M. Stone (2005). It upwinds their gradients by the direction of the mass flux, which keeps intact a loop of field that a uniform flow carries. We also implemented the edge estimates of D. Lee & A. E. Deane (2009) and the upwind selection of D. Lee (2013). In the field-loop test these kept about 1 percent more of the magnetic energy, but they raised the overshoot of the peak field from 8 percent to 17 to 21 percent at 128 cells and left more stray field outside the loop, so the default remains that of T. A. Gardiner & J. M. Stone (2005). The fluxes come from the HLLD solver of T. Miyoshi & K. Kusano (2005), which resolves contacts and Alfvén waves, or from HLL with the fast magnetosonic speeds in the estimates of S. F. Davis (1988). As HLLC does, HLLD falls back to HLL next to cells where the flow converges and the total pressure jumps by more than the threshold of the shock detector. The signal speed of the timestep is , where is the number of dimensions and the fastest magnetosonic speed.
Constrained transport keeps the divergence unchanged only in exact arithmetic. In single precision each face rounds its own sum of the impulses from its edges, and the rounding walks the divergence away from zero: in the vortex of S. A. Orszag & C.-M. Tang (1979) the largest reached after 750 steps. Each face therefore holds a pair of numbers, the field and a compensation in a second texture that keeps what the rounding of the field dropped, and the impulses are added with an error-free summation. The pair carries the exact sum of the face’s impulses, and the divergence stays at a few roundings: after 751 steps and after 3483. The face field and its compensation, at both parities and at the half step, add 80 bytes per cell to the 112 that the uniform grid holds for the gas.
Next to the edge of a star in near-vacuum, the first stage can fill a nearly empty cell to hundreds of times its density. The second stage then pushes more gas out of the half-step cell through its other faces than the cell held at the start, and the update empties it. A cell whose density the first stage changed by more than a factor of four either way, more than a strong shock compresses gas, therefore takes the first-order HLL flux of the starting state on all of its faces, a step that keeps the density positive. The face makes this decision from its own two cells, so the cells, slabs or blocks that share a face compute the same flux, and the edge fields made from these fluxes keep the divergence. Where a magnetized problem asks for it, a ceiling on the Alfvén speed adds mass at rest to cells whose would exceed it. This is not conservative, and only the magnetized disk uses it (§ 8.1).
Magnetic fields on the adaptive mesh
On the adaptive mesh every face of every leaf block is stored. With a field, the tree keeps neighbors across edges, and not only across faces, within one level of each other. At a refinement boundary a coarse cell takes the mean of the fine fluxes, which the fine blocks write to a flux register, and every edge takes the electric field of the finest blocks around it. Each coarse face then stays the mean of the fine faces on it, and the field stays free of divergence across levels. On a refined mesh, energy is conserved to , and the magnetic energy of a rotor and of a blast is within 0.3 and 0.1 percent of a uniform grid at the finest resolution.
When the mesh changes, a copied block keeps its faces and their compensations, and a merged block’s face is the mean of the old children’s faces on it. A new child takes each fine face on the boundary of a coarse cell from an old leaf at its level where one exists, and otherwise from the coarse face, with limited slopes that keep its mean. The faces inside the coarse cell start from the mean of the outer faces in line with them. They are then corrected by the smallest change that makes every fine cell free of divergence, , where is the divergence of the fine cells, the incidence matrix of the interior faces on the cells, and the graph Laplacian of the fine cells. The Walsh functions diagonalize , so applying its pseudo-inverse costs a transform and a division. This prolongation has the aims of G. Tóth & P. L. Roe (2002), being exactly free of divergence, conservative, and keeping the fine faces that exist, but it does not use their formulas. Carried once around the box with 144 rebuilds of the mesh, a dense field loop keeps at and 96 percent of its magnetic energy, the same share as on a uniform grid at the finest resolution.
Per-block timesteps also work with a field. Neighbors across faces, edges and, in two dimensions, vertices are kept within one bin of each other. A slower block takes the fluxes and edge impulses of a faster neighbor’s first substep during its own step, and those of the second substep at its midpoint, so both copies of a shared face receive the same impulses. The saving depends on the contrast in signal speed. A two-dimensional MHD blast at makes 85 percent of the block updates of a single timestep, while problems whose signal speed varies by less than the factor of two between bins make 98 to 100 percent.
Interface, input and output
Shaderous runs at a web address. A user picks a problem, a grid and the physics, and watches the gas through a ray-marched volume rendering or an axis-aligned slice, both drawn on the same device from the simulation textures (Figure 7). The view can show the density, temperature, pressure, a passive scalar, the speed and each velocity component, the Mach number, the entropy function , the net heating rate, the vorticity, the divergence of the velocity, the normalized density gradient , the gravitational potential, the kinetic energy density, the Jeans length in cells and, on the adaptive mesh, the refinement level. The color range follows the field as it evolves, and for the derived fields it ignores the most extreme 0.5 percent of cells. Brushes add mass, velocity or heat; obstacles and sources can be drawn; and the sink tool places point masses. A query tool shows the state of the cell under the pointer and, on the adaptive mesh, the block that holds it, its level and its refinement indicator. The refinement thresholds can be changed during a run. The address bar records the problem, the grid and every setting that differs from the problem’s defaults, so a link reproduces a setup.

Figure 7. The whole interface of Shaderous in the browser during a three-dimensional run of the binary problem, with the binary’s orbit tilted 90° to the disk. The volume view shows isosurfaces of the density. Around it are the problem and physics controls and the diagnostics.
With a magnetic field the view can also show the field strength, the plasma and the divergence of the field, and it draws field lines. In two dimensions the lines are contours of the flux function , integrated from the face field itself. Because the face field is free of divergence to round-off, the integral to a corner does not depend on its path, and the same magnetic flux passes between any two neighboring lines. In three dimensions, lines are traced both ways from seeds that move with the gas, so that the picture does not flicker. A seed that leaves the box or the field is placed again at random, with a probability proportional to the magnetic energy density. The lines are drawn as lit tubes inside the volume rendering, colored by the magnetic pressure on a logarithmic scale as J. Guillochon & M. McCourt (2017) colored theirs. A run can also be recorded as an MP4 movie, encoded frame by frame in the browser with a color bar, axes and the simulated time drawn on each frame. A frame is taken at the end of the step nearest to its time, and no step is shortened, so a recorded run is bit for bit the same as one that is not recorded.
The state can be exported as an HDF5 file in the layout of Athena++ (J. M. Stone et al. 2020), which yt reads directly (M. J. Turk et al. 2011), in two and three dimensions and on uniform and adaptive grids. Files written by Shaderous also carry the run’s settings, time and point masses, so importing one continues the run on the same mesh. Each species is written as a variable named after it. Checkpoints write the same file each time the simulated time passes a multiple of a set interval.
The same page can also run without a person at it. A programming interface in the page loads a setup described by the keys of a link, advances the run by a number of steps or to a given time, and returns diagnostics, samples of the gas, images of the view and exported files as plain data. When the run advances to a given time, its last step is shortened so that it ends at that time exactly. With one parameter in the address, the page neither draws nor plays by itself, so the GPU takes only the steps that a script asks for. Two tools in the repository build on this interface, and both open the page in a browser without a window. A command-line program runs a setup, or a sweep over the values of its parameters. It writes the diagnostics, images, slices, movies and HDF5 files at fixed intervals of simulated time, together with the setup, the version of the code and the GPU that produced them. It also runs on rented Linux servers with data-center GPUs, where the browser reaches the GPU through Vulkan, with a memory budget set on the command line. A server for the Model Context Protocol2 offers the same operations to an AI agent as tools. Within one conversation the agent can load a problem, advance it, read the numbers back and inspect images of the flow.
Problems
The problems that ship with the code are the shock tubes of G. A. Sod (1978) along each axis and the diagonal and a strong shock tube from E. F. Toro (2009), the blast of G. Taylor (1950) and L. I. Sedov (1959), Kelvin-Helmholtz and Rayleigh-Taylor instabilities, the Mach 3 wind tunnel with a step of A. F. Emery (1968) and P. Woodward & P. Colella (1984), smooth advection, the Jeans instability (J. H. Jeans 1902), a polytrope of index 1 in equilibrium, a cold white dwarf in equilibrium, two white dwarfs that collide on a parabolic orbit (S. Rosswog et al. 2009; C. Raskin et al. 2009), the collapse of A. E. Evrard (1988), a uniform sphere, an isothermal turbulent collapse, the thermal instability (G. B. Field 1965) with the cooling function of H. Koyama & S.-i. Inutsuka (2002), a tidal disruption of a polytropic star by a point mass, and a binary accreting from a viscous circumbinary disk ([2] (A. I. MacFadyen & M. Milosavljević 2008)). A shock in air hits a bubble of helium (J.-F. Haas & B. Sturtevant 1987; J. J. Quirk & S. Karni 1996). Detonations of a single-step Arrhenius reaction start from the exact steady solution. At a higher activation energy the front pulses (W. Fickett & W. W. Wood 1966), and a pocket of unburned gas behind it breaks the front into cells. The network of § 3.8 burns a detonation of carbon and oxygen at , lit at the closed end of a tube 1000 km long, and the collision of two white dwarfs. With magnetic fields there are the shock tube of M. Brio & C. C. Wu (1988), the vortex of S. A. Orszag & C.-M. Tang (1979), the rotor of D. S. Balsara & D. S. Spicer [5], the field loop of T. A. Gardiner & J. M. Stone (2005), a circularly polarized Alfvén wave (G. Tóth 2000), a blast in a magnetized medium (J. M. Stone et al. 2008), polytropes threaded by a dipole or a random field, magnetized tidal disruptions, and a magnetized accretion disk. Figure 8 shows four of these problems.

Figure 8. Problems that ship with Shaderous, drawn by the code’s own renderer. (a) Isosurfaces of the density of two white dwarfs of 1.0 and 0.8 after an off-center collision (pericenter 0.6 times the sum of their radii): the lighter one is torn into a tail of debris. (b) Isosurfaces of the density of a detonation of the single-step Arrhenius reaction in three dimensions ( cells, ). A pocket of unburned gas behind the front breaks it into cells, and the burned gas behind it is turbulent. (c) Density of gas around an accreting binary of equal masses after 20 orbits, with the cavity and the streams that cross it. (d) Temperature in the thermal instability at , with cold clouds and filaments (dark) in a warm medium. The arrows in (a) and (b) give the orientation of the axes. The script that made the figure records each setup as the link that reproduces it.
Two of these problems use the diffusive fluxes of § 3.6 by default. The disk of the binary has in units of the square of the binary’s separation times its orbital frequency. At the binary’s separation this equals an viscosity with , the value that B. D. Farris et al. (2014) chose. The thermal instability has in units of the box size and the problem’s unit of time, so that conduction rather than the cell size sets the size of the clouds. H. Koyama & S.-i. Inutsuka (2004) showed that simulations of this instability converge with resolution only if they include conduction and resolve the Field length with at least three cells. With conduction the scale of the structure at changes by 8 percent between and cells. Without it the scale falls by 20 percent.
The disk of the binary also has a damping zone at its outer edge, of the kind that M. de Val-Borro et al. (2006) used to compare codes for disk-planet interaction. Beyond 4.5 binary separations from the center, the density, velocity and specific internal energy of the gas relax toward the initial disk. The rate of relaxation rises from zero there to three times per local orbital period at the edge of the box, 6 separations from the center, and both values can be changed during a run. Without the zone, gas flowed in through the outflow boundaries at the corners of the box, and the disk grew until its uneven pull pushed the binary out of the box. A zone that is fixed to the box brings a second problem. The outer disk then takes up none of the binary’s recoil, and a fixed disk pulls an off-center binary further toward its near side. Following the masses’ center of mass (§ 6.4) removes this instability.
The magnetized accretion disk is a globally isothermal disk around one softened point mass with a sink, in exact vertical and radial balance with the softened potential. Four poloidal loops of field with no net flux thread it, as in J. F. Hawley (2000) but laid along the radius, with in the midplane where two loops meet.
Its damping zone acts on the gas alone and leaves the field to the induction equation, and a ceiling of 3 on the Alfvén speed keeps the nearly empty corona from setting the timestep. The shear winds the loops, and the magnetorotational instability grows [4]. The code reports the Maxwell and Reynolds stresses over the body of the disk as parameters, and the quality factors and of J. F. Hawley et al. (2011), the number of cells across the fastest-growing wavelength of the instability. On the default mesh ( at the finest level, two levels of refinement), after three orbits at unit radius, , , and , below the values of about 8 and 20 above which J. F. Hawley et al. (2011) found that the turbulence saturates as it does at higher resolution. The largest run so far is this disk at with three levels on an NVIDIA RTX 4090. With room for 5832 blocks, about 24 million cells, it held 16.8 GB of GPU memory, and one orbit at unit radius (6359 steps) took 14 minutes. Over that orbit the magnetic energy grew 5.4 times, and the Maxwell stress reached .
For the tidal disruption the code also sorts the debris by its specific orbital energy about the black hole, from which follows the rate at which bound debris returns to pericenter. Gas that has left the box moves almost ballistically in the potential of the black hole, so its energy no longer changes. The update therefore adds the mass that crosses each open face of the box to a histogram of energy as it crosses. A census adds the gas that is still in the box. It sets apart a surviving core, which we find by iteration: gas belongs to the core if it is bound to the core’s mean velocity by the gas’s own potential, and the core’s mean velocity is then recomputed from that gas. The histograms are sums of 64-bit integers, so they are exact and do not depend on the order in which the GPU adds them. In the validation runs, the mass in the box, the mass that has left and the mass that the sink has taken add up to the starting mass to within the rounding of the total. Kepler’s third law turns the histogram of the bound debris into a rate of return (Figure 9). When a star of index passes a black hole of at , the rate peaks at 61 d after pericenter and then falls close to . At this resolution a clump stays bound, and it still sheds mass 40 dynamical times into the run, when it holds . The late part of the rate fills in only as that gas leaves the clump. At the star keeps , and the rate falls faster than , as J. Guillochon & E. Ramirez-Ruiz (2013) found for encounters that leave a core.
Figure 9. Tidal disruptions of a polytrope of index with the mass and radius of the Sun by a black hole of , run with the command-line runner on the adaptive mesh in a box across ( at the finest level, three levels of refinement). (a, b) Isosurfaces of the density drawn by the code’s renderer at , about two dynamical times after pericenter, five levels evenly spaced in from 0.01 to , for impact parameters (the star keeps most of its mass) and (it is torn apart). (c) Mass per unit specific orbital energy about the black hole, in units of the spread , 40 dynamical times into the run: the gas that has left the box and the gas in it, without the surviving core. (d) The rate at which the bound debris returns to pericenter, against time since pericenter; the dashed line falls as . The partial disruption returns its debris in a narrow peak and then falls more steeply.
A polytrope of index 3 is evolved with gas of , as in J. Guillochon & E. Ramirez-Ruiz (2013). In our runs it is destroyed for between 1.8, where its peak density collapses again, and 2, where the peak density keeps falling, against the 1.85 that they found. The magnetized disruptions set the field inside the star as J. Guillochon & M. McCourt (2017) did: a dipole, or a random field with a Kolmogorov spectrum, whose strength follows the pressure of the star so that is about the same throughout it.
Educational use
Several properties make the code practical in a classroom. It needs no installation, no account and no allocation of computing time. It runs on the laptops that students already own, and the two-dimensional problems run on phones. A link records a whole setup, so an instructor can hand a class a prepared run by posting its address. The brushes, the query tool and the choice of displayed field let students change a flow while it runs and read the state of any cell. An exported file opens in yt, so students who know Python can analyze runs with their own scripts, and a recorded movie can be shown in a lecture. A guide in the repository (https://github.com/guillochon/shaderous/blob/main/docs/teaching.md) gives each activity below with links that open its setup. The code is too new to have been used in a course. The activities are proposals, and we invite instructors who try them to tell us what worked.
For primary and secondary school, the guide gives seven demonstrations that a teacher shows on a projector, each a few minutes long, in a routine of predicting, watching and explaining. Children see that air and water flow and swirl, that hot gas rises and spreads, and that a star is a ball of hot gas held together by gravity. Each demonstration is paired with something that students can see or do themselves, such as food coloring that curls in a glass of water. Older pupils work in pairs, read numbers with the query tool, and discuss how far a simulation can be trusted.
For undergraduates who are not majoring in physics or astronomy, the code works as a set of demonstrations that need no equations. A Kelvin-Helmholtz instability rolls up into the billows seen in clouds and in the bands of Jupiter. A Rayleigh-Taylor instability grows fingers like the filaments of the Crab Nebula. A Sedov-Taylor blast shows a thin, dense shell around a hot, thin interior, as in a supernova remnant, and opens a discussion of how G. Taylor (1950) estimated the energy of an explosion from photographs of its fireball. A polytrope at rest shows the balance between pressure and gravity in a star. A tidal disruption, in which students change the depth of the orbit, shows a star torn apart by a black hole. In each, students predict what will happen before they run it.
For physics and astronomy majors the same problems become quantitative. In a shock tube, students identify the rarefaction, the contact discontinuity and the shock, check the jump conditions with the query tool, and compare limiters by editing the link. From dimensional analysis they derive the growth of the Sedov-Taylor radius as and fit it to a run. They measure the growth rates of the Rayleigh-Taylor and Jeans instabilities and compare them with linear theory. They compare the density profile of the polytrope with the Lane-Emden solution, and turn off the well-balanced reconstruction to see what it does. The thermal instability shows how the cooling curve sets the phases of the interstellar medium, and how conduction sets the size of the smallest clouds. A longer laboratory exercise asks students to run a problem with a known answer at four resolutions, compute the error with yt, and measure the order of convergence, including why shocks converge at first order.
For graduate students the code is a readable example of a modern Godunov method. It has about 12,000 lines of WGSL and 26,500 of TypeScript, and each physical module is a small file. Exercises compare the Riemann solvers on a contact discontinuity and a Gresho vortex, find the carbuncle by turning off the HLL blend at a grid-aligned shock, compare the flux and kick forms of the gravitational energy source in the Evrard collapse, measure when local timesteps pay for themselves, and compare the edge electric fields of § 7.1 on the field loop. Term projects include adding a Riemann solver or a test problem with its own validation test, an implicit solver for diffusion, a study of single against double precision using the CPU reference of § 10, and a performance study from the per-pipeline timing. We pair these with the introduction of H. Trac & U.-L. Pen (2003) and the texts of R. J. LeVeque (2002) and E. F. Toro (2009).
Validation
Validation runs in the browser on the reader’s own GPU, from a page next to the simulator, and from the command line through a browser driven by Playwright. A double-precision CPU implementation of the same scheme, and an exact Riemann solver (E. F. Toro 2009), serve as references. Appendix § 16 lists the 64 tests, their pass criteria and the values measured in one run. A float64 copy of the MHD scheme serves as the reference for the magnetic tests. Figure 1 compares the hydrodynamics with exact solutions and shows how the error falls with resolution. Figure 5 shows the energy budget of a gravitational collapse and the accuracy of the potential on the adaptive mesh.
Performance
The flux update is limited by texture fetches rather than arithmetic, which is why the uniform grid stores no primitive variables. In two dimensions a run uses workgroups, which more than halves the cost of the flux update against workgroups with three idle layers. The number of steps per frame adapts to the GPU, and results agree across browsers to round-off. On the adaptive mesh the passes that cover a block and its ghost layers, 18 or 20 cells across, run as rows of 64 threads per block, because tiles left about half of their threads idle. In two dimensions the four layers of a workgroup take four blocks. These two changes made a step of a two-dimensional Kelvin-Helmholtz problem 2.8 times faster, and a step of a three-dimensional Sedov blast 19 percent faster. The interface can also report the GPU time that each pipeline takes, from timestamp queries. Figure 10 shows the throughput on a discrete GPU (an NVIDIA RTX 3080 with 12 GB) in Chrome 156 and Firefox 160, and in Chrome on an integrated one (that of an Apple M4 Pro, which shares 273 GB s of memory bandwidth with the CPU). It was measured with the scripting interface at normal priority, with the GPU otherwise idle, and each point is the median of three runs. In Chrome on the RTX 3080, a uniform grid of cells takes cell updates per second, and one of cells . On the adaptive mesh a leaf cell costs more than a cell of a uniform grid, because its ghost cells are computed as they are loaded and the refinement boundaries recompute fine fluxes. In two dimensions the mesh still takes to updates per second, and in three, to with two to four levels. The M4 Pro takes updates per second on cells and on , and to on the adaptive meshes. Firefox on the RTX 3080 is within 12 percent of Chrome on the largest uniform grids, with updates per second on cells and on . On the adaptive mesh it takes 1.5 to 7 times fewer: to in two dimensions and to in three. A step there takes about 2 ms in two dimensions and 4 ms in three, almost whatever the size of the mesh, against 0.3 to 0.8 ms and 1.9 to 3.7 ms in Chrome. That points to a fixed cost per step in Firefox, which we have not traced.
Figure 10. Throughput on a discrete GPU (NVIDIA RTX 3080, 12 GB) in Chrome and in Firefox, and on an integrated one (Apple M4 Pro) in Chrome. (a) Cell updates per second against the number of cells, for a two-dimensional Kelvin–Helmholtz instability and a three-dimensional Sedov blast, each on uniform grids and on adaptive meshes (two to four levels, local timesteps off). On the adaptive mesh every leaf cell counts as one update per step. Each point is the median of three runs, and the bars span all three. The gray points are the hydrodynamic throughput of AthenaK on one V100 and one A100 ((J. M. Stone et al. 2026)), on a uniform grid of cells (drawn apart for legibility). (b) The same throughputs divided by each device’s peak memory bandwidth. The A100’s bar spans its 40 and 80 GB versions, since the device used is not stated. Shaderous runs in single precision with one stage per step. AthenaK’s precision and integrator for this benchmark are not stated; the hollow gray markers are its values times four, its throughput per byte moved if it ran in double precision with two stages per step.
For comparison, AthenaK (J. M. Stone et al. 2026), the GPU version of Athena++ written with Kokkos, reports hydrodynamic cell updates per second on one NVIDIA V100 and on one A100. Both were measured on a uniform grid. Both codes are limited by memory traffic, so Figure 10(b) divides each throughput by the device’s peak memory bandwidth from its datasheet: GB s for the V100, or GB s for the 40 and 80 GB A100, and GB s for the RTX 3080. Per unit of bandwidth, Shaderous on a grid takes 4 to 5 times as many updates as AthenaK, on either GPU. Two differences account for much of this. Shaderous computes in single precision, which halves the bytes per cell, and it takes one MUSCL-Hancock step per update where a two-stage Runge-Kutta integrator does twice the work. J. M. Stone et al. (2026) do not state the precision or the integrator of their benchmark. AthenaK builds in double precision by default, and the linear-wave input in its repository takes two stages per step.3 If the benchmark ran so, AthenaK moved four times the bytes per update, and its throughput per byte moved is the hollow markers of Figure 10(b). On that measure the two codes are level: Shaderous takes 1.0 to 1.3 times as many updates. The comparison therefore shows that a browser costs Shaderous little or no throughput against a native GPU code. It does not show that its scheme is faster, and a native code in single precision with one stage per step would likely match or exceed it.
The memory of the GPU, rather than the code, limits the size of a run. On a server, where the memory budget is set on the command line, the three-dimensional adaptive mesh holds up to blocks of cells with a magnetic field and with species. These limits come from the largest storage buffer that one binding may hold, 2 GiB, which bounds the flux register of the field and the face mass fluxes of the species. Without a field or
species, only the memory of the card bounds the mesh, because every pass over the blocks is dispatched in slabs that keep within the number of workgroups that one dispatch may launch. The magnetized disk at with four levels ran on an NVIDIA H200 at blocks, about 175 million cells, using 117 GB, and took 10 steps in 10 s.
Discussion
Shaderous is not a replacement for production codes. It runs on one GPU, within the memory that the browser will allocate, and it has no radiation transport. Its MHD is ideal, and its viscosity and conduction are explicit, isotropic and have constant coefficients. Single precision is adequate for the problems that ship with the code, but round-off is biased when a uniform background sits exactly on a power of two, and long integrations accumulate errors that double precision would not.
The design choices of § 4 to § 5 came from constraints of WebGPU, but they do not depend on it. Gathering fluxes and recomputing them across refinement and time-bin boundaries trades extra arithmetic for less storage and less memory traffic, which suits any processor whose throughput is limited by memory rather than by arithmetic. Computing ghost cells on load removes a synchronization step from every AMR cycle. The MHD solver does not gather: it stores its face fluxes and edge electric fields, and it keeps a flux register at refinement boundaries.
The burning network is a fit to a reference network. It covers the 13 isotopes of the -chain and the densities and temperatures of its training set, and on held-out burns it matches its float64 copy to 2 percent per step. Its accuracy against the reference network over a whole detonation remains to be measured, and it has yet to be retrained on burns that heat the gas as the tabulated equation of state does (§ 3.8).
Conclusions
Shaderous is a code for compressible hydrodynamics and ideal MHD with self-gravity, adaptive mesh refinement, local timesteps, point masses, sinks, cooling, viscosity, conduction, mixtures of gases and nuclear burning, written entirely in WebGPU compute shaders and run from a web page. Its hydrodynamic solver conserves mass, momentum and energy to round-off on the adaptive mesh without storing any face flux, by having every cell recompute the fluxes it needs, bit for bit, across refinement and time-bin boundaries. It keeps every step on the GPU and computes ghost cells as it loads them. It works in single precision and holds hydrostatic stars and atmospheres in balance through a well-balanced reconstruction and a settled initial state, and it keeps magnetic fields free of divergence to round-off through compensated sums. The code and its validation suite run on the reader’s own GPU, and a link reproduces any setup. Scripts and AI agents can drive the same page without a person at it, on a desktop or on a GPU server. The same properties make it a tool for teaching, from demonstrations for school pupils to term projects for graduate students.
Acknowledgments
We thank J. Xavier Prochaska for providing access to the Claude team through which all of the Claude models named below were used.
The code, its validation suite, the manuscript source, the bibliography and the notes behind every number in the text are available online.4 The author takes full responsibility for the contents of this paper and of the code. Large language models (Claude Opus 5.5 and Claude Fable 5.2) were used, under author supervision, to write and test the code, to search the literature, to draft and edit the text and the online documentation, and to measure the numbers that the text quotes. Every number in the text is traced to the code, to a measurement recorded in the repository, or to a cited paper. Every bibliography entry was checked against the NASA Astrophysics Data System, Crossref or arXiv, and all references and AI edits were hand-checked by the author. We aimed to be compliant with the AAS guidelines on generative AI in manuscript preparation.5 Those guidelines do not treat such tools as authors; responsibility for accuracy remains with the listed author.
Software: Shaderous (https://github.com/guillochon/shaderous), TypeScript, Vite, Vitest, Playwright, h5wasm, Mediabunny, yt ((M. J. Turk et al. 2011)), pynucastro ((A. Smith Clark et al. 2023)), PyTorch
Appendix
Table 1. The validation suite: hydrodynamics, species and burning on the uniform grid. Criteria are those coded in the suite; L1 errors are means over cells, relative to the mean density. The measured values are in the order of the criteria.
| Test | Pass criterion | Measured |
| Sod tube along , , | L1 density error ; runs agree under axis permutation to | 0.0079; 0 |
| Sod tube along the diagonal | L1 density error | 0.011 |
| Strong shock tube (pressure ratio ) | No floored cells; relative L1 density error at 128 cells | None; 0.075 |
| Sedov-Taylor blast | Mean shock radius within 2% of the similarity solution | 1.6% |
| Kelvin-Helmholtz | Transverse kinetic energy grows more than fivefold by | 11-fold |
| Low-Mach HLLC | Gresho vortex loses less than half the energy lost with plain HLLC, and gains none | Loses 6% against 15% |
| Well-balanced column | Largest Mach number after a sound crossing, uniform and block grids; at least 100 times below the plain scheme | and ; plain scheme 0.35 |
| Uniform advection, 10 crossings | Mass and momentum drift | Mass , momentum |
| Species | Fractions in [0, 1] summing to 1 within ; each species’ mass to ; a smooth species as accurate as the passive scalar | Sum ; mass ; error against |
| Species in the equation of state | Helium in hydrogen at rest stays at rest to under four equations of state; carried across, pressure balanced to (ideal gas) or 0.05; helium in air, of 5/3 and 1.4, to 0.01 | At rest ; carried or 0.013; helium in air 0.002 |
| Shock and helium bubble | Helium mass to ; bit-identical faces; on the adaptive mesh, over 95% of the helium at the finest level | ; no face differs; 99.3% |
| Arrhenius detonation | Front within 1% of the Chapman-Jouguet speed; fuel left behind | 0.12% slow; |
| Smooth advection | Mean error at ; second order or better | ; order 2.0 |
| Flux determinism | Bit-identical mass fluxes on every face, three flows | 0 of 291,840 faces differ |
| Blast in a reflecting box | Mass to , total energy to | Mass , energy |
| Two-dimensional grids | Sod L1 error at ; bit-identical fluxes | 0.0021; no face differs |
| Rayleigh-Taylor | At rest, Mach at ; perturbed, energy to | Mach ; energy |
Table 1.
Validation tests
Tables 1, 2 and 3 list every test of the validation suite (§ 10) with its pass criterion and the value measured in one run of the suite in Chrome 156 on an NVIDIA RTX 3080. The report of that run is in the repository.
| Test | Pass criterion | Measured |
| Block grid without refinement | Density within of the uniform grid in every cell; same number of steps | 0; same |
| Adaptive Sod tube | L1 error on under 60% of the cells; mass and energy to | 0.0022 on 34%; mass , energy |
| Adaptive species | As for species, with the mesh rebuilt; a smooth species within of the passive scalar | Sum ; mass ; |
| Adaptive species in the equation of state | At rest to ; carried across, pressure within 0.05; faces match across levels | 0; 0.007; faces to |
| Adaptive detonation | As the detonation, with the whole reaction zone at the finest level | 0.12% slow; no coarse cell in the zone |
| Adaptive Sedov blast | Radius within 2%; mass and energy to | 1.6%; mass 0, energy |
| Adaptive instabilities | Mass to , energy to while the mesh follows the flow | Mass , energy |
| Adaptive Poisson solve | Sphere potential within 1% with 0, 2 and 3 levels; Jeans rate within 5% | 0.15, 0.17 and 0.26%; 0.02% |
| Adaptive Evrard and polytrope | Energy to 2% through bounce; central density within 10% | 0.19%; 0.8% |
| Adaptive tidal disruption | Pericenter within 2%; frame centered to 0.005 stellar radii | 0.4%; 0.0007 |
| Local timesteps | Sod and Sedov as with one timestep; mass and energy to | Sod 0.0023, Sedov 1.6%; mass , energy |
| HDF5 export and import | Restarted state equal to ; continued runs agree to | 0; |
| Cooling | Power-law decay to 0.1%; thermal balance to 1% without overshoot | 0.001%; balance without overshoot |
| Viscosity | Energy of a shear wave decays as to 1%, and to 3% between no-slip walls; energy to on the adaptive mesh | 0.3%; 0.05%; |
| Conduction | Temperature wave decays at the linear rate to 1%; cloud scale of the thermal instability changes by when the resolution doubles | 0.27%; 7.5% |
| Point mass and sink | Gas plus accreted mass constant to | |
| Binary orbit | Separation within 0.5% over one period; both masses accrete | 0.016%; both accrete |
| Close encounter of two masses | Orbit of eccentricity 0.9 keeps its energy to 1% over two periods | 0.67% |
| GPU against CPU reference | Density and energy differ by of the mean after 20 steps | Density , energy |
| Burning network | One step on 48 held-out states within 2% (L1) of the float64 network | 0.11% |
| Equations of state | Round trip to ; WGSL matches float64 mirrors to , degenerate electrons and hydrogen ionization included; tabulated electrons to , and to in sound speed | Round trip ; mirrors ; tabulated and |
| Uniform sphere potential | Largest error (isolated boundaries) | 0.15% |
| Jeans instability | Growth rate within 5% of linear theory | 0.013% |
| Polytrope | Central density within 10% over 10 dynamical times | 2.5% |
| Cold white dwarf | Settled dwarf: central density within 5% over three dynamical times; energy to | 3.3%; |
| Evrard collapse | Total energy to 2%; thermal energy peaks at | 0.82%; peak at |
| Tidal disruption | Pericenter within 2%; star disrupted | 0.14%; peak density falls to 4% |
Table 2. The validation suite, continued: the adaptive mesh, diffusion, point masses, equations of state and gravity.
| Test | Pass criterion | Measured |
| Brio-Wu shock tube | Compound wave, slow shock and least in the ranges of M. Brio & C. C. Wu (1988); mass and energy to ; HLLD and HLLE agree to 0.01 | Compound wave at , slow shock at 0.146, ; energy ; 0.0017 |
| Orszag-Tang vortex | Mass and energy to ; magnetic energy and peak pressure within regression ranges | Mass , energy ; 0.0617 and 0.511 |
| Field loop | After one crossing, at least 90% of the magnetic energy kept and the peak within 10% | 93.3%; peak 8% high |
| Alfvén wave | Mean error of at ; second order or better | ; order 2.0 |
| Blast in a field, 3D | Mass to , energy to ; elongated along the field by at least 1.3 | Mass , energy ; 2.0 |
| Stepping in slabs | State and faces bit-identical to one slab | No value differs |
| GPU against CPU reference | Density, energy and face field within of the mean after 20 steps | |
| HDF5 restart | Face field restored bit for bit; continued runs agree to | No face differs; |
| Blocks without refinement | Energies equal to the uniform grid’s to after 40 steps | 0 |
| Refined mesh | Mass to , energy to ; coarse face the mean of the fine to ; magnetic energy within 1% of the uniform grid | Mass , energy ; ; 0.02% |
| Leaves in chunks | Bit-identical to one chunk | No value differs |
| Moving mesh | Over at least 20 rebuilds, mass to ; field loop keeps 94% of its energy | 144 rebuilds, mass ; 96.2% |
| Per-block timesteps | Magnetic energy within 0.5% of one timestep; never more block updates | 0.013%; 85 to 100% of the updates |
| Gravity, point masses and cooling | Magnetized polytrope and column as still as without a field; cooling decay to ; sink budget to | Central density of the star 0.1%; cooling ; sink |
| The same on blocks | As above, also with per-block timesteps | 0.11%; ; |
| Fields inside stars | Dipole star: central density and magnetic energy within 5% over two dynamical times | 0.5% and 2.3% |
| Species in a field | As for species, in a field at | Sum ; mass |
| Viscosity and conduction in a field | Shear waves to 1%; viscously damped Alfvén wave to 2%; temperature wave across the field to 1% | 0.31%; 0.03%; 0.10% |
| Magnetized tidal disruption | Field energy within 3% of its integral; disruption follows the hydrodynamic run to 5% | 0.26%; 0.56% |
| Magnetized disk | Mass within 3%, kinetic energy within 5%; Alfvén ceiling held; Maxwell stress grows from zero | Mass 0.6%, kinetic energy 1%; from to |
Table 3. The validation tests of MHD. Except where the field is the subject of the test, each also requires and that faces shared by two blocks agree; the largest value measured was .
References
- [1]Abgrall, R. 1996, Journal of Computational Physics, 125, 150, doi: 10.1006/jcph.1996.0085DOI
- [2]Artymowicz, P., & Lubow, S. H. 1994, ApJ, 421, 651, doi: 10.1086/173679DOI
- [3]Baggaley, A. W. 2026, arXiv e-prints, arXiv:2611.04060, doi: 10.48550/arXiv.2611.04060DOI
- [4]Balbus, S. A., & Hawley, J. F. 1991, ApJ, 376, 214, doi: 10.1086/170270DOI
- [5]Balsara, D. S., & Spicer, D. S. 1999, Journal of Computational Physics, 149, 270, doi: 10.1006/jcph.1998.6153DOI
- [6]Bate, M. R., Bonnell, I. A., & Price, N. M. 1995, MNRAS, 277, 362, doi: 10.1093/mnras/277.2.362DOI
- [7]Benítez-Llambay, P., & Masset, F. S. 2016, ApJS, 223, 11, doi: 10.3847/0067-0049/223/1/11
- [8]Berger, M. J., & Colella, P. 1989, Journal of Computational Physics, 82, 64, doi: 10.1016/0021-9991(89)90035-1DOI





