Reference on jhuki.grid

The grid module provides infrastructure to work with the grid structure of a simulation.

The module provides a class RefinementCenter which contains all information for the refinement structure around a given refinement center. One or more RefinementCenter objects form a Grid, which has the entire information on a computational grid. The object can produce parfile code or can be printed to give an overview of the grid structure.

One of the most important functions provided in this module is set_dt_max_grid(). The function takes two arguments: a Grid and the maximum timestep that you want the grid to have. The return value is a new Grid which is identical to the input one, with the exception that the timestep of the outermost refinement levels is synced so that the maximum timestep on the grid is the one you provided. This function is important because it can be used to produce grids that satisfy CFL conditions (like the ones due to damp_lorenz or eta_beta).

Another useful function is create_twopunctures_grid(), which takes a TwoPunctures and returns a grid built on top of it.

Warning: at the moment we only support grids in which the three dimensions are the same in resolution and extent.

class jhuki.grid.Grid(refinement_centers, outer_boundary, num_ghost=3, symmetry=None, tiny_shift=False)[source]

A grid is a collection of RefinementCenter objects. For example, a binary black hole simulation will likely have two RefinementCenter, centered each black hole.

This class immutable.

Variables
  • outer_boundary (float or None) – Radius of the outer boundary of the overall grid. We assume that it is the same for the three directions.

  • num_levels_with_dt_coarse (int) – How many refinement levels should have the same dt as the coarsest refinement level. This will translate to Carpet::time_refinement_factors. The minimum is 1 (the coarsest level itself). This is extracted from the refinement center with the most number of levels.

  • max_num_refinement_levels (int) – Maximum number of refinement levels on the grid.

  • refinement_centers (list or tuple of RefinementCenter) – Input list, sorted by center_num.

  • dx_coarse (float) – Resolution on the coarsest level.

  • dt_coarse (float) – Timestep on the coarsest level.

  • cfl_coarse (float) – Courant factor on the coarsest level.

  • center_with_most_levels (RefinementCenter) – Refinement center that has the largest number of levels.

  • symmetry (str, or None) – If None, no symmetry is not enabled. If ‘x’, ‘y’, or ‘z’, enable reflection symmetry along that axis. If ‘xy’, ‘yz’, or ‘xz’, enable reflection symmetry along two axis. If ‘xyz’, enable octant symmetry. If 90 or 180, enable rotational symmetry (about the z axis). Rotational symmetry is the kind of symmetry that exists for a single black hole (90), or for identical binary (180). Activate both rotational and reflection symmetries with 90z or 180z.

  • num_ghost (int) – Number of ghost zones.

Constructor.

The different refinement centers that form a grid must be compatible. They must have different center_num (as they identify different refinement centers) and compatible resolutions and timesteps in the outer levels. They can have different number of levels.

Parameters
  • refinement_centers (list or tuple of RefinementCenter) – List of mesh refinements corresponding to the various different centers.

  • symmetry – If None, no symmetry is not enabled. If ‘x’, ‘y’, or ‘z’, enable reflection symmetry along that axis. If ‘xy’, ‘yz’, or ‘xz’, enable reflection symmetry along two axis. If ‘xyz’, enable octant symmetry. If 90 or 180, enable rotational symmetry (about the z axis). Rotational symmetry is the kind of symmetry that exists for a single black hole (90), or for identical binary (180). Activate both rotational and reflection symmetries with 90z or 180z.

  • tiny_shift (bool) – Apply a tiny (subpixel) shift to the outer boundary so that the point (0,0,0) is not on the grid. This is hard-coded to be 1/7 of a pixel.

  • num_ghost (int) – Number of ghost zones.

Variables

outer_boundary (float or None) – Radius of the outer boundary of the overall grid. We assume that it is the same for the three directions.

property parfile_code

Return the code you would put in your parfile.

property rl_synced_every

Number of iterations at which all the refinement levels are at the same time.

Return type

int

property time_refinement_factors

Return parameters for Carpet to set up time_refinement_factors.

class jhuki.grid.RefinementCenter(refinement_radii, dx_fine, cfl_fine, center_num=1, position=(0, 0, 0), num_levels_with_dt_coarse=1)[source]

The RefinementCenter class contains all the information related to the grid structure around one single refinement center. This is not the entire grid structure for a simulation (unless you have only one refinement center).

This class is immutable.

To understand this class always keep in mind the following example, where we draw a simple grid with three refinement levels (two refinement radii). The numbers 500, 250, 125, 0 are hypothetical refinement radii that you would put in CarpetRegrid.

..code-block:

 |------------------|------------------|------------------|
500                250                125                 0
O.B.             R.R. 1             R.R. 2
       R.L. 0              R.L. 1             R.L. 2
Variables
  • refinement_radii (list of float) – Radii over which a change in refinement happens. This is what you would write in CarpetRegrid. Refinement levels are always stored from the largest to the smallest (as in Carpet).

  • center_num (int) – Identifier of the current mesh refinement hierarchy in the context of the entire grid. In CarpetRegrid, you specify num_centers, then each hierarchy is identified with numbers from 1 to num_centers. This is that number.

  • position (list or tuple of float) – (x, y, z) position of the refinement center in the overall grid.

  • dx_fine (float) – Resolution at the finest level (near the center). We assume that the three directions have the same resolution.

  • cfl_fine (float) – CFL number at the finest level (near the center). This is dt_finest/dx_finest.

  • dt_fine (float) – Timestep at the finest level (near the center).

  • num_levels_with_dt_coarse (int) – How many refinement levels should have the same dt as the coarsest refinement level. This will translate to Carpet::time_refinement_factors. The minimum is 1 (the coarsest level itself).

  • num_refinement_radii (int) – Number of radii over which a change in refinement happens. This is not the number of refinement levels (while the two are off by one). This is the number of radii in CarpetRegrid.

  • num_refinement_levels (int) – Number of distinct refinement levels. This is the same as the number of different resolutions over a grid and it is equal to the number of refinement radii + 1.

Constructor.

Parameters
  • refinement_radii (list of float) – Radii over which a change in refinement happens. This is what you would write in CarpetRegrid.

  • center_num (int) – Identifier of the current mesh refinement hierarchy in the context of the entire grid. In CarpetRegrid, you specify num_centers, then each hierarchy is identified with numbers from 1 to num_centers. This is that number.

  • position (list or tuple of float) – (x, y, z) position of the refinement center in the overall grid.

  • dx_fine (float) – Resolution at the finest level (near the center). We assume that the three directions have the same resolution.

  • cfl_fine (float) – CFL number at the finest level (near the center). This is dt_finest/dx_finest.

  • num_levels_with_dt_coarse (int) – How many refinement levels should have the same dt as the coarsest refinement level. This will translate to Carpet::time_refinement_factors. The minimum is 1 (the coarsest level itself).

property cfl

Return dt/dx at every level.

Returns

Courant factor on every refinement level.

Return type

tuple

property dt

Timesteps at each refinement level.

Return type

tuple of float

property dx

Grid spacing at each refinement level.

Return type

tuple of float

dx_at(radius: float) float[source]

Return dx at the given radius.

Parameters

radius (float) – Distance from the center.

Returns

Resolution at given point.

Return type

float

get_summary(outer_boundary=9999.999)[source]

Return a summary of all the refinement levels.

Parameters

outer_boundary (float or None) – Outer boundary of the grid. Used only for the aesthetics of having a table full of data. If None, a large number full of nines will be used.

property parfile_code

Return the code you would put in your parfile.

property rl_synced_every

Number of iterations at which all the refinement levels are at the same time.

Return type

int

jhuki.grid.create_twopunctures_grid(two_punctures: Union[jhuki.twopunctures.TwoPunctures, jhuki.twochargedpunctures.TwoChargedPunctures], points_on_horizon_radius: int, minimum_outer_boundary: float, cfl_num: float = 0.45, horizon_padding_points: int = 5, skip_radii: Optional[Iterable[int]] = None, **kwargs)[source]

Create a grid centered around a given two punctures.

The grid has three identical refinement centers: two on the punctures and one in the center.

The construction of the grid starts by estimating the horizon radius. Then, the horizon is covered with points_on_horizon_radius. From there, refinement levels are added until the minimum_outer_boundary is reached. Radii are placed at powers of 2 from the central one, unless the index is in the skip_radii list. For example, if skip_radii = [2, 3], and the refinement boundaries are supposed to be [1, 2, 4, 8, 16], the actual one will be [1, 2, 16]. This is useful to encompass regions of space with the same resolution. Indices are counted from the innermost.

This function does nothing fancy about the mass ratio: it simply considers the smaller horizon and creates the grid starting from there.

Unknown arguments are passed to the constructor of Grid.

Parameters
  • two_punctures (TwoPunctures or TwoChargedPunctures) – Two punctures for which the grid has to be created.

  • points_on_horizon_radius (int) – Desired number of grid points on the radius of the smaller horizon.

  • minimum_outer_boundary (float) – Minimum outer boundary that the grid has to have

  • cfl_num (float) – CFL factor for the finest refinement level

  • horizon_padding_points (int) – Add this number of points to the innermost refinement level.

  • skip_radii (list of int) – Do not add to the grid refinement boundaries with these indices.

Returns

Grid built on top of the given two punctures.

Return type

Grid

jhuki.grid.set_dt_max(ref_center, dt_max)[source]

Return a new RefinementCenter with maximum timestep smaller than the given one. This is achieved by changing the parameter ~.num_levels_with_dt_coarse.

This function is smart enough to preserve existing synced levels, so you can apply it as many times as you want (for diverse conditions).

This function is very important! Several equations have a maximum timestep allowed for numerical stability (e.g., the shift gauge evolution equation and its parameter eta_beta).

Parameters
  • ref_center (RefinementCenter) – Grid that has to be adjusted.

  • dt_max (float) – Maximum allowed timestep.

Returns

New grid with maximum timestep smaller than dt_max.

Return type

RefinementCenter

jhuki.grid.set_dt_max_grid(grid, dt_max)[source]

Return a new Grid with maximum timestep smaller than the given one.

This is achieved by applying set_dt_max() to each refinement center.

This function is very important! Several equations have a maximum timestep allowed for numerical stability (e.g., the shift gauge evolution equation and its parameter eta_beta).

Parameters
  • grid (Grid) – Grid that has to be adjusted.

  • dt_max (float) – Maximum timestep allowed.

Returns

Grid with maximum timestep smaller than the given one.

Return type

Grid