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

ComponentImplementation
EquationsIdeal 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-timeKerr 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 stateIdeal gas, p = (Γ − 1)ρε, with adjustable adiabatic index Γ
Reconstruction and fluxesMinmod 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 BFlux-constrained transport keeps ∇·B = 0 to round-off
Time integrationSecond-order Runge–Kutta with Strang-type splitting of the source terms; Courant time step
Primitive recoveryOne-dimensional Newton–Raphson iteration safeguarded by bisection (Noble et al. type), with an optional entropy-based (dual-energy) recovery for strongly magnetised cells
RobustnessDensity, 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
BoundariesPeriodic 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 statesA 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 parallelismPARAMESH 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 controlCheckpoint 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.

Computational domain: the equatorial plane seen from above the spin axis, with injection on the upstream half, outflow elsewhere, periodic phi direction and the inner boundary
The computational domain shared by all set-ups (not to scale). Blue: injection at rmax; green: outflow. Inset: the evolved plane is the layer θ = π/2 of the 3D flow.

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-upCoordinates and gridMagnetic fieldPurpose
GRMHD BL (distributed header)Boyer–Lindquist, 2.3 ≤ r ≤ 100 M, 512 × 256Enters with the wind, β0 = 10, perpendicular to the windMagnetised BHL accretion in the plane; the reference set-up
GRMHD KSKerr–Schild, 1 ≤ r ≤ 100 M, 512 × 256As aboveThe same problem in horizon-penetrating coordinates
GRHDBoyer–Lindquist, as the referenceNoneHydrodynamic reference
18 test modelsMostly Kerr–Schild; test-specific domainsTest-specificThe 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.

Six cartoons of the initial set-ups: BHL wind, spherical inflow, Michel accretion, Gammie inflow, equilibrium torus, field loop in the torus
The initial set-ups of the code and of the test problems (cartoons; blue: injection at rmax, purple: exact solution kept in the radial guard cells): (a) BHL wind in the plane, (b) spherical inflow, (c) Michel accretion with a radial field, (d) Gammie inflow inside the ISCO of a hole with a = 0.5, (e) equilibrium torus around a hole with a = 0.9, (f) field loop carried by the torus.

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.

TestRunsWhat it testsStatus
Magnetised Michel accretionM1, M2a–c, M4, M5Gravity 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–SchildTo be run
Gammie inflow inside the ISCOG1a–c, G2Magnetised inflow onto a Kerr hole (a = 0.5): frame dragging, coupled Br–Bφ, cold gas; order of convergenceTo be run
Equilibrium toriT2, T3a, T3bLong-term balance of pressure, centrifugal, gravitational and magnetic forces around a Kerr hole (a = 0.9); toroidal fieldTo be run
Bondi–Hoyle–Lyttleton accretionB2, B3, B4Shocks in curved space; the shock cone and its stability; spin; the outer injectionTo be run
Field-loop advection by a rotating torusL1a, L1bConstrained transport in a sheared flow: numerical resistivity, ∇·B, loss of magnetic energyTo 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.

  1. 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.
  2. We

    Check feasibility

    We check that the problem fits the equatorial-plane code, and agree on a plan.
  3. We

    Prepare the set-up

    We write the user header file and the initial and boundary data for your problem.
  4. You

    Run the simulations

    You run the code with the prepared set-up, following the user manual.
  5. 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.

Simulations of the test modelsMichel, Gammie, tori, BHL and field-loop tests
Shock-cone moviesTime evolution of wind accretion in the plane
Astrophysical simulationsAccretion in Kerr and alternative space-times

Methods and tests the code builds on

  1. L. Antón et al., Numerical 3+1 general relativistic magnetohydrodynamics: a local characteristic approach, ApJ 637, 296 (2006)
  2. 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
  3. O. Dönmez, O. Zanotti, L. Rezzolla, On the development of quasi-periodic oscillations in Bondi–Hoyle accretion flows, MNRAS 412, 1659 (2011)
  4. J. A. Font, F. Daigne, The runaway instability of thick discs around black holes. I. The constant angular momentum case, MNRAS 334, 383 (2002)
  5. J. A. Font, J. M. Ibáñez, Non-axisymmetric relativistic Bondi–Hoyle accretion on to a Schwarzschild black hole, MNRAS 298, 835 (1998)
  6. 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)
  7. C. F. Gammie, Efficiency of magnetized thin accretion disks in the Kerr metric, ApJ 522, L57 (1999)
  8. C. F. Gammie, J. C. McKinney, G. Tóth, HARM: a numerical scheme for general relativistic magnetohydrodynamics, ApJ 589, 444 (2003)
  9. T. A. Gardiner, J. M. Stone, An unsplit Godunov method for ideal MHD via constrained transport, J. Comput. Phys. 205, 509 (2005)
  10. S. S. Komissarov, Magnetized tori around Kerr black holes: analytic solutions with a toroidal magnetic field, MNRAS 368, 993 (2006)
  11. F. C. Michel, Accretion of matter by condensed objects, Ap&SS 15, 153 (1972)
  12. P. Mösta et al., GRHydro: a new open-source general-relativistic magnetohydrodynamics code for the Einstein toolkit, Class. Quantum Grav. 31, 015005 (2014)
  13. S. C. Noble, C. F. Gammie, J. C. McKinney, L. Del Zanna, Primitive variable solvers for conservative general relativistic magnetohydrodynamics, ApJ 641, 626 (2006)
  14. G. Tóth, The ∇·B = 0 constraint in shock-capturing magnetohydrodynamics codes, J. Comput. Phys. 161, 605 (2000)