MUCUR GRMHD 2D Equatorial Plane
A general-relativistic magnetohydrodynamics code for accretion onto rotating (Kerr) black holes in the equatorial plane (r, φ), all the way around the hole. Built for flows that are not axisymmetric: winds passing the hole, shock cones and their oscillations, spirals and rotating discs.
- Release v24
- Fortran 90 · MPI · PARAMESH
- Kerr space-time, Boyer–Lindquist and Kerr–Schild
- 70 modified-gravity and alternative space-times
- 5 test problems, 18 test models
What the code does
The code solves the equations of ideal GRMHD for a perfect fluid with an ideal-gas equation of state on a fixed black-hole background. It evolves the equatorial plane θ = π/2 of the black hole: all quantities depend on (t, r, φ), with φ running all the way around the hole. The gas can rotate, and the magnetic field lies in the plane and can be wound up by the flow and by frame dragging.
This is the natural geometry for flows that are not axisymmetric: a wind passing the hole in its orbital plane, its shock cone and the cone's oscillations (flip-flop, quasi-periodic oscillations), spiral structures and rotating discs.
The release comes with three ready-to-run set-ups and 18 test models, and a suite of five test problems with exact or published solutions.
Typical applications
- Bondi–Hoyle–Lyttleton accretion of a wind moving in the plane onto a Kerr black hole: the shock cone, flip-flop oscillations, QPOs and the magnetic structures the flow forms
- Spherical (Bondi, Michel) accretion, with or without a radial field
- Rotating flows in the plane: rings, discs and equilibrium tori, and the transport of magnetic flux by them
- Accretion in alternative black-hole space-times
- Any initial state on the plane: inflows, rings and discs, perturbations, custom magnetic fields
What “2D in the equatorial plane” means
- The model is a thin, mirror-symmetric layer of a 3D flow, so the volume element keeps the factor r² of the spherical geometry. It is not a flat 2D slab.
- Integrated rates (Ṁ, Ė, L̇) are given per unit polar angle. Multiply by an assumed opening angle for a total.
- There is no vertical structure, so jets and the vertical-field MRI are absent. For those, use the 2D Meridional code.
Physics and numerical method
| Component | Implementation |
|---|---|
| Equations | Ideal GRMHD in the Valencia 3+1 conservative formulation. Conserved variables D, Sj, τ, B̃k; geometric sources from the metric derivatives; the Sφ source is exactly zero for axisymmetric space-times, so angular momentum changes only through fluxes. |
| Evolved plane | θ = π/2, coordinates (r, φ), periodic in φ. All θ derivatives vanish by reflection symmetry; an optional Bθ component is carried passively. |
| Space-time | Kerr black hole in Boyer–Lindquist coordinates, or in horizon-penetrating ingoing Kerr–Schild coordinates with the inner boundary inside the horizon. Any spin. In addition, 70 alternative black-hole space-times and a tilted Kerr metric, each written with the black-hole mass and its full θ dependence and evaluated on the plane. |
| Equation of state | Ideal gas, p = (Γ − 1)ρε, with adjustable adiabatic index Γ |
| Reconstruction and fluxes | Minmod reconstruction of ρ, p, vi, Bi; HLLE Riemann solver with the fast-magnetosonic characteristic speeds. Legacy hydrodynamic solvers (Marquina, HLLC) are available for pure GRHD runs. |
| Divergence of B | Flux-constrained transport keeps ∇·B = 0 to round-off |
| Time integration | Second-order Runge–Kutta with Strang-type splitting of the source terms; Courant time step |
| Primitive recovery | One-dimensional Newton–Raphson iteration safeguarded by bisection (Noble et al. type), with an optional entropy-based (dual-energy) recovery for strongly magnetised cells |
| Robustness | Density, pressure and magnetisation floors; a temperature floor set automatically from the injected gas, and an entropy floor; Lorentz-factor and temperature ceilings; a safety stop and full bookkeeping of what the floors add |
| Boundaries | Periodic in φ. Inner boundary: zero-gradient outflow with no inflow from the hole. Outer boundary: zero-gradient outflow, with injection of a Bondi–Hoyle–Lyttleton wind on the upstream half or of spherical inflow at all angles. In Kerr–Schild coordinates the boundary conditions act on the true radial velocity ur, so the injected mass flux is exact. The stationary test problems keep their exact solution in the radial guard cells. |
| Initial states | A static atmosphere, the wind everywhere, the exact solutions of the test problems (Michel, Gammie, tori, field loop), or your own state. Field: straight in-plane lines at any angle to the wind, with an optional Bθ part. |
| Grid and parallelism | PARAMESH blocks of 32 × 32 cells, uniform resolution, MPI parallel. Nφ = 256 and Nr = 256 × n (e.g. 512 × 256: Δr = 0.19 M, Δφ = 1.4°) |
| Run control | Checkpoint and restart; all problem parameters, including the choice of test problem, in a single user header file |
Beyond Kerr: 70 modified-gravity and alternative space-times
Besides Kerr, the code evolves the flow in 70 further black-hole space-times from the literature: modified theories of gravity, quantum-corrected and regular black holes, nonlinear electrodynamics, and black holes surrounded by dark matter. A tilted Kerr metric, which depends on φ, is also available. The metrics come from the same file as in the 2D Meridional code, so both codes use identical space-times.
- Schwarzschild
- Einstein–Gauss–Bonnet
- Proca–Gauss–Bonnet
- Hartle–Thorne
- Horndeski
- DHOST
- Hořava
- f(R, T)
- Bumblebee
- Kalb–Ramond
- Barrow
- Weyl
- Lee–Wick
- Disformal Kerr
- Konoplya–Zhidenko
- Johannsen–Psaltis
- Hairy Kerr
- Kerr–Sen
- Kerr–EMDA
- Kerr–Bertotti–Robinson
- Euler–Heisenberg
- ModMax
- Magnetic (confining NLED)
- Yang–Mills
- SU(N) sigma model
- Dyonic
- Freund–Nambu
- Yukawa
- Global monopole
- Hayward
- Dymnikova
- Ghosh–Kumar
- Generalised Ghosh
- Quantum-corrected
- Covariant quantum-corrected
- Quantum-improved Kerr in PFDM
- qOS
- Non-commutative
- Dunkl
- CBH
- Perfect-fluid dark matter (PFDM)
- Dark-matter halos
- Tilted Kerr
- … and more
How the metrics are implemented
- Every metric is written with the black-hole mass and its full θ dependence, and evaluated on the plane θ = π/2.
- Kerr matches its closed form to 10−16, the metric derivatives match finite differences to 10−10, and every metric was checked against its literature formula and its general-relativity limit.
Good to know
- The parameters of each theory (couplings, charges, hair, dark-matter density and so on) are set in the user header file.
- The full test suite is run in the Kerr space-time; the alternative space-times are checked at the level of the metric.
- If the metric you need is not in the list, we can add it.
The computational domain
All set-ups share one grid: the equatorial plane rmin ≤ r ≤ rmax, 0 ≤ φ < 2π, seen from above the spin axis, with uniform cells in r and φ. The φ direction is periodic. For a > 0 the hole rotates towards +φ.
In Boyer–Lindquist coordinates the inner boundary lies outside the horizon and the ergosphere. In Kerr–Schild coordinates it lies inside the horizon, so the horizon and the ergosphere are on the grid.
At rmax gas is injected where the set-up feeds it: on the upstream half for a wind, or at all angles for spherical inflow. Elsewhere it leaves freely, with no inflow allowed.
The evolved plane is the mirror-symmetric layer θ = π/2 of the three-dimensional flow, so all integrated fluxes are per unit polar angle.
Ready-to-run set-ups
The distributed header sets up magnetised Bondi–Hoyle–Lyttleton accretion onto a Kerr black hole in the plane. Two variants differ from it in a few lines only, and the test suite adds 18 test-model headers. Every set-up is one user header file: pick the closest one and change what you need.
| Set-up | Coordinates and grid | Magnetic field | Purpose |
|---|---|---|---|
| GRMHD BL (distributed header) | Boyer–Lindquist, 2.3 ≤ r ≤ 100 M, 512 × 256 | Enters with the wind, β0 = 10, perpendicular to the wind | Magnetised BHL accretion in the plane; the reference set-up |
| GRMHD KS | Kerr–Schild, 1 ≤ r ≤ 100 M, 512 × 256 | As above | The same problem in horizon-penetrating coordinates |
| GRHD | Boyer–Lindquist, as the reference | None | Hydrodynamic reference |
| 18 test models | Mostly Kerr–Schild; test-specific domains | Test-specific | The five test problems below |
Reference wind: a = 0.9, v∞ = 0.2, cs,∞ = 0.1, ρ∞ = 1, Γ = 4/3 (Mach 2.03, accretion radius 40 M), injected on the upstream half π/2 ≤ φ ≤ 3π/2; run to t = 60 000 M.
Validation: five test problems
The code is tested on five problems, each with an exact solution or published results to compare with. Together they exercise every part of the code that matters on the plane: the metric and geometric sources in both coordinate systems, flow through the horizon, primitive recovery at high magnetisation and in cold gas, the induction equation and constrained transport, shocks and the outer injection. Each of the 18 models is selected by the user header alone, and an analysis script compares every snapshot with the exact solution.
| Test | Runs | What it tests | Status |
|---|---|---|---|
| Magnetised Michel accretion | M1, M2a–c, M4, M5 | Gravity and sources against an exact solution; flow through the horizon; force-free radial field; primitive recovery up to σ ≈ 103; order of convergence; Boyer–Lindquist against Kerr–Schild | To be run |
| Gammie inflow inside the ISCO | G1a–c, G2 | Magnetised inflow onto a Kerr hole (a = 0.5): frame dragging, coupled Br–Bφ, cold gas; order of convergence | To be run |
| Equilibrium tori | T2, T3a, T3b | Long-term balance of pressure, centrifugal, gravitational and magnetic forces around a Kerr hole (a = 0.9); toroidal field | To be run |
| Bondi–Hoyle–Lyttleton accretion | B2, B3, B4 | Shocks in curved space; the shock cone and its stability; spin; the outer injection | To be run |
| Field-loop advection by a rotating torus | L1a, L1b | Constrained transport in a sheared flow: numerical resistivity, ∇·B, loss of magnetic energy | To be run |
Checks already done
- The exact solutions agree with independent references: Michel to 10−13, Gammie to 10−12, the tori against published values. The stationary GRMHD equations of the code are satisfied by the initial data to 10−12–5 × 10−7 in both coordinate systems.
- Every cell of the 15 test models with exact initial data, including the guard cells, was checked for a physical, consistent state before any run.
- The analysis chain was checked on the exact solution written in the code's output format: errors at the level of single-precision rounding.
- These checks found and fixed two errors before release.
The results of the test runs will be added here when they are complete.
What a run produces
- Accretion rates of mass, energy and angular momentum (Ṁ, Ė, L̇) at four radii, as functions of time
- Binary VTK snapshots with 43 quantities on the plane, ready for VisIt and ParaView: densities, velocities, Lorentz factor, Mach numbers, Bernoulli parameter, fluxes, magnetic field, magnetisation, plasma β and more
- A time series of the magnetic flux on the hole and the MAD parameter
- Floor statistics, so the effect of numerical floors can be checked
- Python tools for maps, field and stream lines, radial and azimuthal profiles, time averages and power spectra
Physics extracted from the output
- Accretion rate, efficiency and angular-momentum transport, including the Maxwell stress
- Shock-cone structure, flip-flop motion and spiral shocks
- Variability and quasi-periodic oscillations from power spectra
- Magnetic flux on the hole and the magnetically arrested state
All quantities are in geometrised units, G = c = M = 1, with lengths and times in M. The manual gives the conversion to physical units; for M = 10 M⊙, 100 M is 4.9 ms.
Working with the code: collaboration
The source code is not publicly distributed. If you have an astrophysical problem in the equatorial plane of a black hole, we are happy to solve it together as a collaboration.
- You
Describe the problem
The physical system, spin or space-time, initial state, magnetic field, how gas is fed, and the quantities you want to measure. - We
Check feasibility
We check that the problem fits the equatorial-plane code, and agree on a plan. - We
Prepare the set-up
We write the user header file and the initial and boundary data for your problem. - You
Run the simulations
You run the code with the prepared set-up, following the user manual. - Together
Analyse and publish
We interpret the results together, and they go into a joint publication.
Contact
To discuss a collaboration, write to us with a short description of your problem.
E-mail: orhan.donmez71@gmail.com
Coming soon
Results and movies will be added to this page.
Methods and tests the code builds on
- L. Antón et al., Numerical 3+1 general relativistic magnetohydrodynamics: a local characteristic approach, ApJ 637, 296 (2006)
- A. Cruz-Osorio, F. D. Lora-Clavijo, F. S. Guzmán, Is the flip-flop behaviour of accretion shock cones on to black holes an effect of coordinates?, MNRAS (2012), arXiv:1210.6588
- O. Dönmez, O. Zanotti, L. Rezzolla, On the development of quasi-periodic oscillations in Bondi–Hoyle accretion flows, MNRAS 412, 1659 (2011)
- J. A. Font, F. Daigne, The runaway instability of thick discs around black holes. I. The constant angular momentum case, MNRAS 334, 383 (2002)
- J. A. Font, J. M. Ibáñez, Non-axisymmetric relativistic Bondi–Hoyle accretion on to a Schwarzschild black hole, MNRAS 298, 835 (1998)
- J. A. Font, J. M. Ibáñez, P. Papadopoulos, Non-axisymmetric relativistic Bondi–Hoyle accretion on to a Kerr black hole, MNRAS 305, 920 (1999)
- C. F. Gammie, Efficiency of magnetized thin accretion disks in the Kerr metric, ApJ 522, L57 (1999)
- C. F. Gammie, J. C. McKinney, G. Tóth, HARM: a numerical scheme for general relativistic magnetohydrodynamics, ApJ 589, 444 (2003)
- T. A. Gardiner, J. M. Stone, An unsplit Godunov method for ideal MHD via constrained transport, J. Comput. Phys. 205, 509 (2005)
- S. S. Komissarov, Magnetized tori around Kerr black holes: analytic solutions with a toroidal magnetic field, MNRAS 368, 993 (2006)
- F. C. Michel, Accretion of matter by condensed objects, Ap&SS 15, 153 (1972)
- P. Mösta et al., GRHydro: a new open-source general-relativistic magnetohydrodynamics code for the Einstein toolkit, Class. Quantum Grav. 31, 015005 (2014)
- S. C. Noble, C. F. Gammie, J. C. McKinney, L. Del Zanna, Primitive variable solvers for conservative general relativistic magnetohydrodynamics, ApJ 641, 626 (2006)
- G. Tóth, The ∇·B = 0 constraint in shock-capturing magnetohydrodynamics codes, J. Comput. Phys. 161, 605 (2000)