cf.Domain.create_healpix

classmethod Domain.create_healpix(refinement_level, indexing_scheme='nested', radius=None)[source]

Create a new global HEALPix grid.

The HEALPix axis of the new Domain is ordered so that the HEALPix indices are monotonically increasing.

See CF Appendix F: Grid Mappings. https://doi.org/10.5281/zenodo.14274886

Performance

High refinement levels may require the setting of a very large Dask chunksize, to prevent a possible run-time failure resulting from an attempt to create an excessive amount of chunks for the healpix_index coordinates. For instance, with the default Dask chunksize of 128 MiB, healpix_index coordinates at refinement level 29 would need ~206 billion Dask chunks, which is almost certainly more than enough to cause a crash. In this case, a Dask chunksize of 1 pebibyte results in only 24576 Dask chunks, a much more manageable amount:

>>> cf.chunksize()
<CF Constant: 134217728>
>>> d = cf.Domain.create_healpix(10)
>>> assert d.coord('healpix_index').data.npartitions == 1
>>> d = cf.Domain.create_healpix(15)
>>> assert d.coord('healpix_index').data.npartitions == 768
>>> with cf.chunksize('1 PiB'):
...     d = cf.Domain.create_healpix(29)
...     assert d.coord('healpix_index').data.npartitions == 24576

Added in version 3.20.0.

See also

cf.Domain.create_regular, cf.Domain.create_latlon_coordinates

Parameters:
refinement_level: int

The refinement level of the grid within the HEALPix hierarchy, starting at 0 for the base tessellation with 12 cells. The number of cells in the global HEALPix grid for refinement level n is \(12\times 4^n\).

indexing_scheme: str

The HEALPix indexing scheme. One of 'nested' (the default), 'ring', 'nuniq', or 'zuniq'.

The nested scheme indexes with consecutive indices the pixels inside a single coarser refinement level cell. When the indices are sorted monotonically, the scheme is optimised for data retrievals within a geographical range.

The ring scheme indexes with consecutive indices the pixels moving down from the north to the south pole along each isolatitude ring. When the indices are sorted monotonically, the scheme is optimised for data retrievals along latitude bands, such as required for spherical harmonics.

When the HEALPix axis is ordered with monotonically increasing indices, each type of indexing scheme is optimised for different types of operation. For instance, the ring scheme is optimised for Fourier transforms with spherical harmonics; and the nested scheme is optimised for geographical nearest-neighbour operations such as decreasing the refinement level.

A Multi-Order Coverage (MOC) has pixels with different refinement levels stored in the same array. An indexing scheme for an MOC has a unique index for each cell at each refinement level.

The nuniq scheme defines MOC indices such that all cells within a particular refinement level form a set of consecutive integers. E.g. for refinement level 0 the indices are 4, …, 15, for refinement level 1 the indices are 16, …, 63, for refinement level 2 the indices are 64, …, 255, etc. When the indices are sorted monotonically, the scheme is optimised for data retrievals within a refinement level and within a geographical range.

The zuniq scheme defines MOC indices such that, for adjacent refinement levels, cells in the proximity of a particular geographical location have similar index values. This means that the indices for a particular refinement level do not form a set of consecutive integers. In fact the difference between the smallest and largest indices within any given refinement level is \(O(10^19)\). When the indices are sorted monotonically, the scheme is optimised for data retrievals across refinement levels.

radius: optional

Specify the radius of the latitude-longitude plane defined in spherical polar coordinates. May be set to any numeric scalar object, including numpy and Data objects. The units of the radius are assumed to be metres, unless specified by a Data object. If the special value 'earth' is given then the radius taken as 6371229 metres. If None (the default) then no radius is set.

Example:

Equivalent ways to set a radius of 6371229 metres: 6371229, numpy.array(6371229), cf.Data(6371229), cf.Data(6371229, 'm'), cf.Data(6371.229, 'km'), 'earth'.

Returns:
Domain

The newly created HEALPix domain.

Examples

>>> d = cf.Domain.create_healpix(4)
>>> d.dump()
--------
Domain:
--------
Domain Axis: healpix_index(3072)

Dimension coordinate: healpix_index
    standard_name = 'healpix_index'
    Data(healpix_index(3072)) = [0, ..., 3071]

Coordinate reference: grid_mapping_name:healpix
    Coordinate conversion:grid_mapping_name = healpix
    Coordinate conversion:indexing_scheme = nested
    Coordinate conversion:refinement_level = 4
    Dimension Coordinate: healpix_index

>>> d = cf.Domain.create_healpix(4, "nuniq", radius=6371000)
>>> d.dump()
--------
Domain:
--------
Domain Axis: healpix_index(3072)

Dimension coordinate: healpix_index
    standard_name = 'healpix_index'
    Data(healpix_index(3072)) = [1024, ..., 4095]

Coordinate reference: grid_mapping_name:healpix
    Coordinate conversion:grid_mapping_name = healpix
    Coordinate conversion:indexing_scheme = nuniq
    Datum:earth_radius = 6371000.0
    Dimension Coordinate: healpix_index

>>> d.create_latlon_coordinates(inplace=True)
>>> print(d)
Dimension coords: healpix_index(3072) = [1024, ..., 4095]
Auxiliary coords: latitude(healpix_index(3072)) = [2.388015463268772, ..., -2.388015463268786] degrees_north
                : longitude(healpix_index(3072)) = [45.0, ..., 315.0] degrees_east
Coord references: grid_mapping_name:healpix