HpxHashTable#

class cygrid.HpxHashTable(uint64_t nside=1, uint32_t scheme=RING, bool dbg_messages=False)#

Bases: Healpix

Helper class for creating cygrid’s lookup tables (HEALPix).

This is used to speed-up cygrid, there is not really any other meaningful application of this class. HpxHashTable derives from the Healpix class and adds-in a few helper functions and lookup-table members.

Usually, only two methods have to be called: prepare_helpers (once) and calculate_output_pixels (for each grid call) See the documentation of the methods for more information.

Parameters:

nsideunsigned 64-bit int: The HEALPix nside parameter.
schemeenum: The HEALPix scheme. Currently, only ‘RING’ is supported.

Notes

The class holds a dictionary (target_dict) that contains for each HEALPix index the list of pixel (centers) of the target (WCS) map that fall into this HEALPix index. For sanity a vector for the pixel centers is used, in case multiple pixels from the WCS map have the same HPX index. Since we need to invert the dictionary later, the coordinate pixel pair is mapped to an integer using the very simple transformation:
```
xy_hash = xpix * MAX_Y + ypix  # with MAX_Y == 2**30
```
All operations make use of the ‘RING’ scheme indexing. Therefore, we store the HEALPix index of the first pixel in each ring, the number of HEALPix pixels per ring and the index of the \(\varphi=180^\circ\) pixel (or rather the closest pixel to the left of \(\varphi=180^\circ\), if ring is shifted).
Furthermore, we store for each ring the HEALPix indices of a disc (with specified radius) as valid for \(\varphi=180^\circ\). These indices can easily be shifted along the \(\varphi\) coordinate to quickly construct discs at any position.
For all of the above, only those indices/rings are stored that are going to be used. Of course, if disc radius (aka kernel support radius) is changed, the caches need to be recomputed.

Attributes Summary

`ncap`	property ncap : unsigned 64-bit int
`npface`	property nface : unsigned 64-bit int
`npix`	property npix : unsigned 64-bit int
`nrings`	property nrings : unsigned 64-bit int
`nside`	property nside : unsigned 64-bit int
`omega`	property omega : double
`order`	property order : unsigned 64-bit int
`resolution`	property resolution : double
`scheme`	property scheme : enum

Methods Summary

`ang2pix`(self, double theta, double phi)	Return the pixel index containing the angular coordinates \((\varphi, \vartheta)\).
`ang2pix_many`(self, double[, double[)	Return the pixel indices containing the angular coordinates of \((\varphi, \vartheta)\) arrays.
`clear_hashes`(self)	Clear all internal caches/dictionaries.
`get_ring_info_small`(self, uint64_t ring)	Return start index and number of pixels per healpix ring.
`pix2ang`(self, uint64_t pix)	Convert HEALPix index to angular coordinates \((\varphi, \vartheta)\).
`pix2ang_many`(self, long[)	Convert HEALPix indices to angular coordinates of \((\varphi, \vartheta)\) arrays.
`pix2ring`(self, uint64_t pix)	Return 'ring' number that contains the HEALPix pixel, 'pix'.
`pix2ring_many`(self, long[)	Return 'ring' numbers containing HEALPix pixels given in array, 'pix'.
`query_disc`(self, double theta, double phi, ...)	Return hpx indices of a disc around \((\vartheta, \varphi)\).
`query_disc_phi180`(self, ...)	Return HEALPix indices of a disc around \(\varphi=180^\circ\) for 'disc_ring'.
`set_optimal_nside`(self, double target_res)	Set the HEALPix `nside` such that HEALPix resolution is less than `target_res`.

Attributes Documentation

ncap#

property ncapunsigned 64-bit int: Return the HEALPix ‘ncap’ parameter.

npface#

property nfaceunsigned 64-bit int: Return the HEALPix ‘nface’ parameter.

npix#

property npixunsigned 64-bit int: Return the HEALPix ‘npix’ parameter.

nrings#

property nringsunsigned 64-bit int: Return the HEALPix ‘nrings’ parameter.

nside#

property nsideunsigned 64-bit int: The HEALPix ‘nside’ parameter. (Re-)setting ‘nside’ updates other properties.

omega#

property omegadouble: Return the solid angle, ‘omega’ of the HEALPix pixels for current nside.

order#

property orderunsigned 64-bit int: Return the HEALPix ‘order’ parameter.

resolution#

property resolutiondouble: Return the angular size of the HEALPix pixels for current nside.

scheme#

property schemeenum: The HEALPix ‘scheme’. Currently only ‘RING’ is supported.

Methods Documentation

ang2pix(self, double theta, double phi)#

Return the pixel index containing the angular coordinates \((\varphi, \vartheta)\).

Wrapper around the Cython-only (private) method _ang2pix.

Parameters:

thetadouble: \(\vartheta\) coordinate (\(\vartheta = \pi/2 - \mathrm{latitude}\)).
phidouble: \(\varphi\) coordinate (longitude).

Returns:

pixunsigned 64-bit int: The HEALPix pixel index.

Raises:

ValueError: Invalid theta value.

ang2pix_many(self, double[::1] theta, double[::1] phi)#

Return the pixel indices containing the angular coordinates of \((\varphi, \vartheta)\) arrays.

Wrapper around the Cython-only (private) method _ang2pix.

Parameters:

thetaarray of doubles: \(\vartheta\) coordinate (\(\vartheta = \pi/2 - \mathrm{latitude}\)).
phiarray of doubles: \(\varphi\) coordinate (longitude).

Returns:

pixarray of unsigned 64-bit int: The HEALPix pixel index.

clear_hashes(self)#: Clear all internal caches/dictionaries.

get_ring_info_small(self, uint64_t ring)#

Return start index and number of pixels per healpix ring.

Wrapper around the Cython-only (private) method _get_ring_info_small.

Parameters:

ringunsigned 64-bit int: The HEALPix ring parameter to get information on.

Returns:

startpixunsigned 64-bit int: The HEALPix index of the first pixel in ring.
num_pix_in_ringunsigned 64-bit int: The number of HEALPix pixels in ring.
shiftedbool: Whether the central HEALPix pixel in that ring is shifted from \(\varphi=180^\circ\).

Raises:

ValueError: Ring index not in valid range.

pix2ang(self, uint64_t pix)#

Convert HEALPix index to angular coordinates \((\varphi, \vartheta)\).

Wrapper around the Cython-only (private) method _pix2ang.

Parameters:

pixunsigned 64-bit int: The HEALPix pixel index.

Returns:

thetadouble: \(\vartheta\) coordinate (\(\vartheta = \pi/2 - \mathrm{latitude}\)).
phidouble: \(\varphi\) coordinate (longitude).

Raises:

ValueError: pix not in valid range.

pix2ang_many(self, long[::1] pix)#

Convert HEALPix indices to angular coordinates of \((\varphi, \vartheta)\) arrays.

Wrapper around the Cython-only (private) method _pix2ang.

Parameters:

pixarray of unsigned 64-bit int: The HEALPix pixel index.

Returns:

thetaarray of doubles: \(\vartheta\) coordinate (\(\vartheta = \pi/2 - \mathrm{latitude}\)).
phiarray of doubles: \(\varphi\) coordinate (longitude).

pix2ring(self, uint64_t pix)#

Return ‘ring’ number that contains the HEALPix pixel, ‘pix’.

Wrapper around the Cython-only (private) method _pix2ring.

Parameters:

pixunsigned 64-bit int: The HEALPix index.

Returns:

ringunsigned 64-bit int: The HEALPix ring.

Raises:

ValueError: Pixel index not in valid range.

pix2ring_many(self, long[::1] pix)#

Return ‘ring’ numbers containing HEALPix pixels given in array, ‘pix’.

Wrapper around the Cython-only (private) method _pix2ring.

Parameters:

pixarray of unsigned 64-bit int: The HEALPix indices.

Returns:

ringarray of unsigned 64-bit int: The HEALPix rings.

query_disc(self, double theta, double phi, double disc_size_rad)#

Return hpx indices of a disc around \((\vartheta, \varphi)\).

This uses query_disc_phi180 and shifts the pixels along ring.

Wrapper around the cython-only (private) method _query_disc.

Parameters:

theta/phidouble: Coordinates \((\vartheta, \varphi)\) in radians.
disc_size_raddouble: Size of the disc in radians.

Returns:

disc_indicesarray of unsigned 64-bit int: The HEALPix indices of the disc.

query_disc_phi180(self, double disc_size_rad, uint64_t disc_ring)#

Return HEALPix indices of a disc around \(\varphi=180^\circ\) for ‘disc_ring’.

This is a modified version of the HEALPix library query_disc routine that returns the HEALPix indices of a disc around arbitrary coordinates. Here, it was modified to only work for coordinates having \(\varphi=180^\circ\) and a \(\vartheta\) that coincides with the latitude of a HEALPix ring. These discs can be shifted along \(\varphi\) - which is faster than calling query_disc if one cashes the \(\varphi=180^\circ\) discs.

Wrapper around the Cython-only (private) method _query_disc_phi180.

Parameters:

disc_size_raddouble: Size of the disc in radians.
disc_ringunsigned 64-bit int: HEALPix ring index of the requested disc center.

Returns:

disc_indicesarray of unsigned 64-bit int: The HEALPix indices of the disc.

set_optimal_nside(self, double target_res)#

Set the HEALPix nside such that HEALPix resolution is less than target_res.

Parameters:

target_resdouble: Requested target resolution of the HEALPix representation. nside will be set such that the HEALPix resolution is better than target_res.