Coordinate Tools

pyharm’s tools for dealing with coordinates are split into two files: pyharm.coordinates, for dealing with general-relativistic quantities (e.g. the metric) and transformations between coordinate systems, and pyharm.grid for holding a Cartesian mesh of native coordinates, coupled with their local metric, connection coefficients, and transformation matrices back to some “base” coordinate system (currently must be Kerr-Schild coordinates)

Coordinate System Classes

Coordinate systems are implemented as classes, each of which subclasses pyharm.coordinates.CoordinateSystem and implements the methods it contains:

class pyharm.coordinates.CoordinateSystem

Interface for representing coordinate systems. Each system implements these functions. Each system is designed to return at least:

• r,th,phi in spherical Kerr-Schild coordinates (or just spherical coordinates in the case of Minkowski)
• A transformation matrix, dxdX, for tensors from one system to the other
• The forms and determinant of the metric, gcov, gcon, & gdet

Everything this class can return is derived from a metric and transformation matrix, so most new coordinate systems just define those two things.

cart_coord(x)

Return Cartesian Kerr-Schild or Minkowski coordinates corresponding to a point X in native coordinates. Individual coordinates below.

conn_func(x, delta=1e-05)

Calculate all connection coefficients \(\Gamma^{i}_{j, k}\). Returns a 3+N dimensional array conn[i,j,k,…]

correct_small_th(theta)

“Corrections” to the theta coordinate to avoid returning exactly 0 or \(\pi\)

gcon(x)

Return contravariant form of the metric. As with all coordinate functions, the matrix/vector indices are first.

gcon_from_gcov(gcov)

Return contravariant form of the metric, given the covariant form. As with all coordinate functions, the matrix/vector indices are first.

gcon_ks(x)

Contravariant metric in Kerr-Schild coordinates at some native location 4-vector X. Inverted numerically, maybe not the most accurate.

gcov(x)

Covariant metric in native coordinates at some native location 4-vector X

gcov_ks(x)

Covariant metric in Kerr-Schild coordinates at some native location 4-vector X

gdet(X)

Return the negative root determinant of the metric \(\sqrt{-g}\).

gdet_from_gcov(gcov)

Return the negative root determinant of the metric \(\sqrt{-g}\), given the covariant form.

get_bl()

Return a Boyer-Lindquist coordinate system with the same black hole spin.

ks_coord(x)

Return Spherical Kerr-Schild or Minkowski coordinates corresponding to a point X in native coordinates. Individual coordinates below.

native_startx(met_params)

Where the native coordinates X (e.g. ‘startx1’) should start, given a set of metric parameters (e.g. grid size & ‘r_out’). Most HARM systems in KS use this to place exactly 5 zones inside the EH.

native_stopx(met_params)

Where the native coordinates X should stop given a set of metric parameters.

The coordinate systems currently supported are Minkowski (pyharm.coordinates.Minkowski), Kerr-Schild (pyharm.coordinates.KS), Modified Kerr-Schild (pyharm.coordinates.MKS), and “Funky” Modified Kerr-Schild (pyharm.coordinates.FMKS). The MKS and FMKS systems are used to concentrate zones toward the midplane, and to make zones near the pole larger, in order to preserve accuracy in simulations while maintaining a reasonable time step (which is driven by the Courant condition at the pole). Details on these coordinate systems can be found here.

The Grid Class

class pyharm.grid.Grid(params, caches=True, cache_conn=False)

The Grid object divides a domain in native coordinates into zones, and caches the local metric (and some other convenient information) at several locations in each zone. The object can be used to consult the grid size/shape for global calculations, and raise and lower the indices of fluid 4-vectors.

__contains__(key)

Whether the given key would return something from this object. Generally for dictionaries the syntax is “if x in dict.keys()” or “if x in dict” but we can’t enumerate possibilities. So instead, check strings on the fly.

__getitem__(key)

This function works something like its companion in FluidDump: It parses a dictionary member “request” and returns various members based on it. This function also allows slicing – slices must be 3D like for fluid dumps, though only the X1 and X2 slices are applied.

__init__(params, caches=True, cache_conn=False)

Initialize a Grid object. Note that “params” is usually filled by reading a file, not manually: for manual Grid creation, see pyharm.grid.make_some_grid().

Parameters:

• caches – Whether to cache gcon/gcov/gdet at zone centers/faces. Usually desired.
• cache_conn – Whether to cache connection coefficients (all 64/zone) at zone centers. Usually not desired.
• params –
  Dictionary containing the following parameters, depending on coordinate system:

  n{1,2,3}tot: total number of physical grid zones in each direction

  ng: number of “ghost” zones in each direction to add for boundary conditions/domain decomposition

  coordinates: name of the coordinate system (value in parens below)

  
  

  === For Minkowski coordinates (“minkowski”): ===

  x{1,2,3}min: location of nearest corner of first grid zone [0,0,0]

  x{1,2,3}max: location of farthest corner of last grid zone [n1tot, n2tot, n3tot]

  
  

  === For Spherical Kerr-Schild coordinates (“ks”): ===

  a: black hole spin

  r_out: desired location of the outer edge of the farthest radial zone on the grid

  
  

  === For Modified Kerr-Schild coordinates (“mks”): ===

  hslope: narrowing parameter for X2, defined in Gammie et. al. (2003)

  
  

  === For Modified Modified Kerr-Schild coordinates (“mmks”): ===

  All of the MKS parameters, plus

  poly_xt, poly_alpha: See the AFD docs wiki

  
  

  === For “Funky” Modified Kerr-Schild coordinates (“fmks”): ===

  All of the MMKS parameters, plus

  mks_smooth: See HARM docs wiki

__weakref__

list of weak references to the object (if defined)

coord(i, j, k, loc=<Loci.CENT: 3>, squeeze=False)

Get the position x of zone(s) i,j,k, in _native_ coordinates

If given lists of i,j,k, this returns x[NDIM,len(i),len(j),len(k)] via np.meshgrid(). Any index given as a single value is suppressed on output, down to x[NDIM]

All functions in coordinates.py which take coordinates “x” also accept a grid of the form this returns.

coord_all(loc=<Loci.CENT: 3>, mesh=False)

Like coord_bulk, but including ghost zones

coord_bulk(loc=<Loci.CENT: 3>, mesh=False)

Return a 3D array of all position vectors X within the physical zones. See coord() for use.

coord_ij(at=0)

Get just a 2D meshgrid of locations, usually for plotting

coord_ij_mesh(at=0)

Get just a 2D meshgrid of locations, usually for plotting

coord_ik(at=0)

Get just a 2D meshgrid of locations, usually for plotting

coord_ik_mesh(at=0)

Get just a 2D meshgrid of locations, usually for plotting

coord_jk(at=0)

Get just a 2D meshgrid of locations, usually for plotting

coord_jk_mesh(at=0)

Get just a 2D meshgrid of locations, usually for plotting

dot(ucon, ucov)

Inner product along first index.

dt_light()

Returns the light crossing time of the smallest zone in the grid

get_thphi_locations(at, mesh=False, native=False, bottom=False, projection='mercator')

Get the mesh locations x_ij and y_ij needed for plotting a th-phi slice. This can be done in a bunch of ways controlled with options

Parameters:

• mesh – get mesh corners rather than centers, for flat shading
• native – get native X1/X3 coordinates rather than Cartesian x,z locations
• bottom – take the view from -z axis instead of +z axis
• projection –
  “mercator”: default, project theta on Y-axis and phi on X-axis. Differs from ‘native’ due to midplane compression.

  ”polar”: view down from +z. Or with ‘bottom’, view up from -Z.

  ”flattened_polar”: reinterpret as polar coordinates, theta -> r, phi -> phi

get_xy_locations(mesh=False, native=False, log_r=False)

Get the mesh locations x_ij and y_ij needed for plotting a midplane slice. Note there is no need for an ‘at’ parameter, at least for plotting: 2D plots should be face-on.

Parameters:

• mesh – get mesh corners rather than centers, for flat shading
• native – get native X1/X3 coordinates rather than Cartesian x,z locations
• log_r – logarithmically compress the radial coordinate

get_xz_areas(**kwargs)

Get cell areas in the plotting plane using the trapezoid area function from cell corners

get_xz_locations(mesh=False, native=False, half_cut=False, log_r=False)

Get the mesh locations x_ij and z_ij needed for plotting a poloidal slice. By default, gets locations at zone centers in slices phi=0,180. Note there is no need for an ‘at’ parameter, at least for plotting: 2D plots should be face-on.

Parameters:

• mesh – get mesh corners rather than centers, for flat shading
• native – get native X1/X2 coordinates rather than Cartesian x,z locations
• half_cut – get only the slice at phi=0

lower_grid(vcon, loc=<Loci.CENT: 3>)

Lower a grid of contravariant rank-1 tensors to covariant ones.

raise_grid(vcov, loc=<Loci.CENT: 3>)

Raise a grid of covariant rank-1 tensors to contravariant ones.

pyharm.grid.make_some_grid(system, n1=128, n2=128, n3=128, a=0, hslope=0.3, r_in=None, r_out=1000, caches=True, cache_conn=False)

Convenience function for generating grids with particular known parameters.

Parameters:system – coordinate system, denoted ‘eks’, ‘mks’, ‘fmks’, ‘minkowski’, or anything exotic defined in :mode`pyharm.coordinates`

All other parameters are as described in Grid.__init__, and are optional with Illinois-centric defaults. If not given, ‘r_in’ will be chosen to put 5 zones inside the event horizon as done in iharm3d/KHARMA.