HpxHashTable

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

Bases: cygrid.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

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

  3. 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.

  4. 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 ints

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 ints

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 ints

The HEALPix indices.

Returns
ringarray of unsigned 64-bit ints

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 ints

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 ints

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.