Total convolution¶
ducc0.totalconvolve¶
Python interface for total convolution/interpolation library
All arrays containing spherical harmonic coefficients are assumed to have the following format:
values for m=0, l going from 0 to lmax (these values must have an imaginary part of zero)
values for m=1, l going from 1 to lmax (these values can be fully complex)
values for m=2, l going from 2 to lmax
…
values for m=mmax, l going from mmax to lmax
Error conditions are reported by raising exceptions.
- class ducc0.totalconvolve.ConvolverPlan¶
Class encapsulating the low-level interface for convolution/interpolation. Computations are performed on double precision data.
- Nphi(self: ducc0.totalconvolve.ConvolverPlan) int ¶
- Return type:
The full data cube dimension in phi direction (third axis)
- Npsi(self: ducc0.totalconvolve.ConvolverPlan) int ¶
- Return type:
The full data cube dimension in psi direction (first axis)
- Ntheta(self: ducc0.totalconvolve.ConvolverPlan) int ¶
- Return type:
The full data cube dimension in theta direction (second axis)
- deinterpol(self: ducc0.totalconvolve.ConvolverPlan, cube: numpy.ndarray, itheta0: int, iphi0: int, theta: numpy.ndarray, phi: numpy.ndarray, psi: numpy.ndarray, signal: numpy.ndarray) None ¶
Adjoint of interpol. Spreads the values in signal over the appropriate regions of cube
- Parameters:
cube (numpy.ndarray((Npsi(), :, :), dtype=numpy.float64)) – (Partial) data cube to which the deinterpolated values will be added. Must be zeroed before the first call to deinterpol!
itheta0 (int) – starting indices in theta and phi direction of the provided cube relative to the full cube.
iphi0 (int) – starting indices in theta and phi direction of the provided cube relative to the full cube.
theta (numpy.ndarray(nptg, dtype=numpy.float64)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
phi (numpy.ndarray(nptg, dtype=numpy.float64)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
psi (numpy.ndarray(nptg, dtype=numpy.float64)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
signal (numpy.ndarray(nptg, dtype=numpy.float64)) – signal values that will be deinterpolated into cube.
Notes
Repeated calls to this method are fine, but for good performance the number of pointings passed per call should be as large as possible.
- deprepPsi(self: ducc0.totalconvolve.ConvolverPlan, subcube: numpy.ndarray) None ¶
Pepares a data cube for for actual interpolation.
- Parameters:
subcube (numpy.ndarray((Npsi(), :, :), dtype=numpy.float64)) – On entry the part [0:2*kmax+1, :, :] must be filled with results from getPlane() calls. On exit, the entire array will be filled in a form that can be used for subsequent interpol calls.
- getPatchInfo(self: ducc0.totalconvolve.ConvolverPlan, theta_lo: float, theta_hi: float, phi_lo: float, phi_hi: float) list[int] ¶
Returns information necessary to extract a given sub-area from the data cube.
- Parameters:
theta_lo (float, 0 <= theta_lo < theta_hi <= pi) – colatitude borders of the requested patch
theta_hi (float, 0 <= theta_lo < theta_hi <= pi) – colatitude borders of the requested patch
phi_lo (float, 0 <= phi_lo < phi_hi <= 2*pi) – longitude borders of the requested patch
phi_hi (float, 0 <= phi_lo < phi_hi <= 2*pi) – longitude borders of the requested patch
- Returns:
The sub-array [:, itheta_lo:itheta_hi, iphi_lo:iphi_hi] of a full data cube will contain all information necessary to interpolate pointings within the specified patch.
- Return type:
tuple(int) with 4 elements itheta_lo, itheta_hi, iphi_lo, iphi_hi
- getPlane(self: ducc0.totalconvolve.ConvolverPlan, slm: numpy.ndarray, blm: numpy.ndarray, mbeam: int, planes: numpy.ndarray) None ¶
Computes a single (real or complex) sub-plane in (theta, phi) of the data cube
- Parameters:
slm (numpy.ndarray((nalm_sky,), dtype=numpy.complex128), or) – numpy.ndarray((ncomp, nalm_sky), dtype=numpy.complex128) spherical harmonic coefficients of the sky.
blm (numpy.ndarray((nalm_beam,), dtype=numpy.complex128), or) – numpy.ndarray((ncomp, nalm_beam), dtype=numpy.complex128) spherical harmonic coefficients of the beam.
mbeam (int, 0 <= mbeam <= kmax) – requested m moment of the beam
planes (numpy.ndarray((nplanes, Ntheta(), Nphi()), dtype=numpy.float64)) – nplanes must be 1 for mbeam==0, else 2 will be filled with the real part (and the imaginary part for mbeam>0) of the requested sub-planes on exit
Notes
If the slm and blm arrays have a second dimension, the contributions of all components will be added together in re and im.
- interpol(self: ducc0.totalconvolve.ConvolverPlan, cube: numpy.ndarray, itheta0: int, iphi0: int, theta: numpy.ndarray, phi: numpy.ndarray, psi: numpy.ndarray, signal: numpy.ndarray) None ¶
Computes the interpolated values for a given set of angle triplets
- Parameters:
cube (numpy.ndarray((Npsi(), :, :), dtype=numpy.float64)) – (Partial) data cube generated with prepPsi.
itheta0 (int) – starting indices in theta and phi direction of the provided cube relative to the full cube.
iphi0 (int) – starting indices in theta and phi direction of the provided cube relative to the full cube.
theta (numpy.ndarray(nptg, dtype=numpy.float64)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
phi (numpy.ndarray(nptg, dtype=numpy.float64)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
psi (numpy.ndarray(nptg, dtype=numpy.float64)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
signal (numpy.ndarray(nptg, dtype=numpy.float64)) – array into which the results will be written
Notes
Repeated calls to this method are fine, but for good performance the number of pointings passed per call should be as large as possible.
- prepPsi(self: ducc0.totalconvolve.ConvolverPlan, subcube: numpy.ndarray) None ¶
Pepares a data cube for for actual interpolation.
- Parameters:
subcube (numpy.ndarray((Npsi(), :, :), dtype=numpy.float64)) – On entry the part [0:2*kmax+1, :, :] must be filled with results from getPlane() calls. On exit, the entire array will be filled in a form that can be used for subsequent interpol calls.
- updateSlm(self: ducc0.totalconvolve.ConvolverPlan, slm: numpy.ndarray, blm: numpy.ndarray, mbeam: int, planes: numpy.ndarray) None ¶
Updates a set of sky spherical hamonic coefficients resulting from adjoint interpolation.
- Parameters:
slm (numpy.ndarray((nalm_sky,), dtype=numpy.complex128), or) – numpy.ndarray((ncomp, nalm_sky), dtype=numpy.complex128) The deinterpolated spherical harmonic coefficients will be added to this array. Must be zeroed before the first call to updateSlm!
blm (numpy.ndarray((nalm_beam,), dtype=numpy.complex128), or) – numpy.ndarray((ncomp, nalm_beam), dtype=numpy.complex128) spherical harmonic coefficients of the beam.
mbeam (int, 0 <= mbeam <= kmax) – requested m moment of the beam
planes (numpy.ndarray((nplanes, Ntheta(), Nphi()), dtype=numpy.float64)) – nplanes must be 1 for mbeam==0, else 2 real part (and imaginary part for mbeam>0) of the requested plane
Notes
If the slm and blm arrays have a second dimension, the slm will be computed in a fashion that is adjoint to getPlane.
- class ducc0.totalconvolve.ConvolverPlan_f¶
Class encapsulating the low-level interface for convolution/interpolation. Computations are performed on single precision data.
- Nphi(self: ducc0.totalconvolve.ConvolverPlan_f) int ¶
- Return type:
The full data cube dimension in phi direction (third axis)
- Npsi(self: ducc0.totalconvolve.ConvolverPlan_f) int ¶
- Return type:
The full data cube dimension in psi direction (first axis)
- Ntheta(self: ducc0.totalconvolve.ConvolverPlan_f) int ¶
- Return type:
The full data cube dimension in theta direction (second axis)
- deinterpol(self: ducc0.totalconvolve.ConvolverPlan_f, cube: numpy.ndarray, itheta0: int, iphi0: int, theta: numpy.ndarray, phi: numpy.ndarray, psi: numpy.ndarray, signal: numpy.ndarray) None ¶
Adjoint of interpol. Spreads the values in signal over the appropriate regions of cube
- Parameters:
cube (numpy.ndarray((Npsi(), :, :), dtype=numpy.float32)) – (Partial) data cube to which the deinterpolated values will be added. Must be zeroed before the first call to deinterpol!
itheta0 (int) – starting indices in theta and phi direction of the provided cube relative to the full cube.
iphi0 (int) – starting indices in theta and phi direction of the provided cube relative to the full cube.
theta (numpy.ndarray(nptg, dtype=numpy.float32)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
phi (numpy.ndarray(nptg, dtype=numpy.float32)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
psi (numpy.ndarray(nptg, dtype=numpy.float32)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
signal (numpy.ndarray(nptg, dtype=numpy.float32)) – signal values that will be deinterpolated into cube.
Notes
Repeated calls to this method are fine, but for good performance the number of pointings passed per call should be as large as possible.
- deprepPsi(self: ducc0.totalconvolve.ConvolverPlan_f, subcube: numpy.ndarray) None ¶
Adjoint of prepPsi.
- Parameters:
subcube (numpy.ndarray((Npsi(), :, :), dtype=numpy.float32)) – On entry this must be an array filled by one or more deinterpol calls. On exit, only the part [0:2*kmax+1, :, :] is relevant and can be used for updateSlm calls.
- getPatchInfo(self: ducc0.totalconvolve.ConvolverPlan_f, theta_lo: float, theta_hi: float, phi_lo: float, phi_hi: float) list[int] ¶
Returns information necessary to extract a given sub-area from the data cube.
- Parameters:
theta_lo (float, 0 <= theta_lo < theta_hi <= pi) – colatitude borders of the requested patch
theta_hi (float, 0 <= theta_lo < theta_hi <= pi) – colatitude borders of the requested patch
phi_lo (float, 0 <= phi_lo < phi_hi <= 2*pi) – longitude borders of the requested patch
phi_hi (float, 0 <= phi_lo < phi_hi <= 2*pi) – longitude borders of the requested patch
- Returns:
The sub-array [:, itheta_lo:itheta_hi, iphi_lo:iphi_hi] of a full data cube will contain all information necessary to interpolate pointings within the specified patch.
- Return type:
tuple(int) with 4 elements itheta_lo, itheta_hi, iphi_lo, iphi_hi
- getPlane(self: ducc0.totalconvolve.ConvolverPlan_f, slm: numpy.ndarray, blm: numpy.ndarray, mbeam: int, planes: numpy.ndarray) None ¶
Computes a single (real or complex) sub-plane in (theta, phi) of the data cube
- Parameters:
slm (numpy.ndarray((nalm_sky,), dtype=numpy.complex64), or) – numpy.ndarray((ncomp, nalm_sky), dtype=numpy.complex) spherical harmonic coefficients of the sky.
blm (numpy.ndarray((nalm_beam,), dtype=numpy.complex64), or) – numpy.ndarray((ncomp, nalm_beam), dtype=numpy.complex) spherical harmonic coefficients of the beam.
mbeam (int, 0 <= mbeam <= kmax) – requested m moment of the beam
planes (numpy.ndarray((nplanes, Ntheta(), Nphi()), dtype=numpy.float32)) – nplanes must be 1 for mbeam==0, else 2 will be filled with the real part (and the imaginary part for mbeam>0) of the requested sub-planes on exit
Notes
If the slm and blm arrays have a second dimension, the contributions of all components will be added together in re and im.
- interpol(self: ducc0.totalconvolve.ConvolverPlan_f, cube: numpy.ndarray, itheta0: int, iphi0: int, theta: numpy.ndarray, phi: numpy.ndarray, psi: numpy.ndarray, signal: numpy.ndarray) None ¶
Computes the interpolated values for a given set of angle triplets
- Parameters:
cube (numpy.ndarray((Npsi(), :, :), dtype=numpy.float32)) – (Partial) data cube generated with prepPsi.
itheta0 (int) – starting indices in theta and phi direction of the provided cube relative to the full cube.
iphi0 (int) – starting indices in theta and phi direction of the provided cube relative to the full cube.
theta (numpy.ndarray(nptg, dtype=numpy.float32)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
phi (numpy.ndarray(nptg, dtype=numpy.float32)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
psi (numpy.ndarray(nptg, dtype=numpy.float32)) – angle triplets at which the interpolated values will be computed Theta and phi must lie inside the ranges covered by the supplied cube. No constraints on psi.
signal (numpy.ndarray(nptg, dtype=numpy.float32)) – array into which the results will be written
Notes
Repeated calls to this method are fine, but for good performance the number of pointings passed per call should be as large as possible.
- prepPsi(self: ducc0.totalconvolve.ConvolverPlan_f, subcube: numpy.ndarray) None ¶
Pepares a data cube for for actual interpolation.
- Parameters:
subcube (numpy.ndarray((Npsi(), :, :), dtype=numpy.float32)) – On entry the part [0:2*kmax+1, :, :] must be filled with results from getPlane() calls. On exit, the entire array will be filled in a form that can be used for subsequent interpol calls.
- updateSlm(self: ducc0.totalconvolve.ConvolverPlan_f, slm: numpy.ndarray, blm: numpy.ndarray, mbeam: int, planes: numpy.ndarray) None ¶
Updates a set of sky spherical hamonic coefficients resulting from adjoint interpolation.
- Parameters:
slm (numpy.ndarray((nalm_sky,), dtype=numpy.complex64), or) – numpy.ndarray((ncomp, nalm_sky), dtype=numpy.complex64) The deinterpolated spherical harmonic coefficients will be added to this array. Must be zeroed before the first call to updateSlm!
blm (numpy.ndarray((nalm_beam,), dtype=numpy.complex64), or) – numpy.ndarray((ncomp, nalm_beam), dtype=numpy.complex64) spherical harmonic coefficients of the beam.
mbeam (int, 0 <= mbeam <= kmax) – requested m moment of the beam
planes (numpy.ndarray((nplanes, Ntheta(), Nphi()), dtype=numpy.float32)) – nplanes must be 1 for mbeam==0, else 2 real part (and imaginary part for mbeam>0) of the requested plane
Notes
If the slm and blm arrays have a second dimension, the slm will be computed in a fashion that is adjoint to getPlane.
- class ducc0.totalconvolve.Interpolator¶
Class encapsulating the convolution/interpolation functionality
The class can be configured for interpolation or for adjoint interpolation, by means of two different constructors.
Constructor for interpolation mode
- Parameters:
sky (numpy.ndarray((ncomp, nalm_sky), dtype=numpy.complex)) – spherical harmonic coefficients of the sky. ncomp can be 1 or 3.
beam (numpy.ndarray((ncomp, nalm_beam), dtype=numpy.complex)) – spherical harmonic coefficients of the beam. ncomp can be 1 or 3
separate (bool) – whether contributions of individual components should be added together.
lmax (int) – maximum l in the coefficient arays
kmax (int) – maximum azimuthal moment in the beam coefficients
npoints (int) – total number of irregularly spaced points you want to use this object for (only used for performance fine-tuning)
sigma_min (float) – minimum and maximum allowed oversampling factors 1.2 <= sigma_min < sigma_max <= 2.5
sigma_max (float) – minimum and maximum allowed oversampling factors 1.2 <= sigma_min < sigma_max <= 2.5
epsilon (float) – desired accuracy for the interpolation; a typical value is 1e-5
nthreads (the number of threads to use for computation) –
mode (Constructor for adjoint interpolation) –
lmax – maximum l in the coefficient arays
kmax – maximum azimuthal moment in the beam coefficients
ncomp (int) – the number of components which are going to input to deinterpol. Can be 1 or 3.
npoints – total number of irregularly spaced points you want to use this object for (only used for performance fine-tuning)
sigma_min – minimum and maximum allowed oversampling factors 1.2 <= sigma_min < sigma_max <= 2.5
sigma_max – minimum and maximum allowed oversampling factors 1.2 <= sigma_min < sigma_max <= 2.5
epsilon – desired accuracy for the interpolation; a typical value is 1e-5
nthreads –
- deinterpol(self: ducc0.totalconvolve.Interpolator, ptg: numpy.ndarray, data: numpy.ndarray) None ¶
Takes a set of angle triplets and interpolated values and spreads them onto the data cube.
- Parameters:
ptg (numpy.ndarray((N,3), dtype=numpy.float64)) – theta, phi and psi angles (in radian) for N pointings theta must be in the range [0; pi] phi must be in the range [0; 2pi] psi should be in the range [-2pi; 2pi]
data (numpy.ndarray((n2, N), dtype=numpy.float64)) – the interpolated values n2 must match the ncomp value specified in the constructor.
Notes
Can only be called in adjoint mode
repeated calls to this method are fine, but for good performance the number of pointings passed per call should be as large as possible.
- getSlm(self: ducc0.totalconvolve.Interpolator, beam: numpy.ndarray) numpy.ndarray ¶
Returns a set of sky spherical hamonic coefficients resulting from adjoint interpolation
- Parameters:
beam (numpy.array(nalm_beam, nbeam), dtype=numpy.complex)) – spherical harmonic coefficients of the beam with lmax and kmax defined in the constructor call nbeam must match the ncomp specified in the constructor, unless ncomp was 1.
- Returns:
spherical harmonic coefficients of the sky with lmax defined in the constructor call
- Return type:
numpy.array(nalm_sky, nbeam), dtype=numpy.complex)
Notes
Can only be called in adjoint mode
must be the last call to the object
- interpol(self: ducc0.totalconvolve.Interpolator, ptg: numpy.ndarray) numpy.ndarray ¶
Computes the interpolated values for a given set of angle triplets
- Parameters:
ptg (numpy.ndarray((N, 3), dtype=numpy.float64)) – theta, phi and psi angles (in radian) for N pointings theta must be in the range [0; pi] phi must be in the range [0; 2pi] psi should be in the range [-2pi; 2pi]
- Returns:
the interpolated values n2 is either 1 (if separate=True was used in the constructor) or the second dimension of the input slm and blm arrays (otherwise)
- Return type:
numpy.array((n2, N), dtype=numpy.float64)
Notes
Can only be called in “normal” (i.e. not adjoint) mode
repeated calls to this method are fine, but for good performance the number of pointings passed per call should be as large as possible.
- class ducc0.totalconvolve.Interpolator_f¶
Class encapsulating the convolution/interpolation functionality
The class can be configured for interpolation or for adjoint interpolation, by means of two different constructors.
Constructor for interpolation mode
- Parameters:
sky (numpy.ndarray((ncomp, nalm_sky), dtype=numpy.complex)) – spherical harmonic coefficients of the sky. ncomp can be 1 or 3.
beam (numpy.ndarray((ncomp, nalm_beam), dtype=numpy.complex)) – spherical harmonic coefficients of the beam. ncomp can be 1 or 3
separate (bool) – whether contributions of individual components should be added together.
lmax (int) – maximum l in the coefficient arays
kmax (int) – maximum azimuthal moment in the beam coefficients
npoints (int) – total number of irregularly spaced points you want to use this object for (only used for performance fine-tuning)
sigma_min (float) – minimum and maximum allowed oversampling factors 1.2 <= sigma_min < sigma_max <= 2.5
sigma_max (float) – minimum and maximum allowed oversampling factors 1.2 <= sigma_min < sigma_max <= 2.5
epsilon (float) – desired accuracy for the interpolation; a typical value is 1e-5
nthreads (the number of threads to use for computation) –
mode (Constructor for adjoint interpolation) –
lmax – maximum l in the coefficient arays
kmax – maximum azimuthal moment in the beam coefficients
ncomp (int) – the number of components which are going to input to deinterpol. Can be 1 or 3.
npoints – total number of irregularly spaced points you want to use this object for (only used for performance fine-tuning)
sigma_min – minimum and maximum allowed oversampling factors 1.2 <= sigma_min < sigma_max <= 2.5
sigma_max – minimum and maximum allowed oversampling factors 1.2 <= sigma_min < sigma_max <= 2.5
epsilon – desired accuracy for the interpolation; a typical value is 1e-5
nthreads –
- deinterpol(self: ducc0.totalconvolve.Interpolator_f, ptg: numpy.ndarray, data: numpy.ndarray) None ¶
Takes a set of angle triplets and interpolated values and spreads them onto the data cube.
- Parameters:
ptg (numpy.ndarray((N,3), dtype=numpy.float64)) – theta, phi and psi angles (in radian) for N pointings theta must be in the range [0; pi] phi must be in the range [0; 2pi] psi should be in the range [-2pi; 2pi]
data (numpy.ndarray((n2, N), dtype=numpy.float64)) – the interpolated values n2 must match the ncomp value specified in the constructor.
Notes
Can only be called in adjoint mode
repeated calls to this method are fine, but for good performance the number of pointings passed per call should be as large as possible.
- getSlm(self: ducc0.totalconvolve.Interpolator_f, beam: numpy.ndarray) numpy.ndarray ¶
Returns a set of sky spherical hamonic coefficients resulting from adjoint interpolation
- Parameters:
beam (numpy.array(nalm_beam, nbeam), dtype=numpy.complex)) – spherical harmonic coefficients of the beam with lmax and kmax defined in the constructor call nbeam must match the ncomp specified in the constructor, unless ncomp was 1.
- Returns:
spherical harmonic coefficients of the sky with lmax defined in the constructor call
- Return type:
numpy.array(nalm_sky, nbeam), dtype=numpy.complex)
Notes
Can only be called in adjoint mode
must be the last call to the object
- interpol(self: ducc0.totalconvolve.Interpolator_f, ptg: numpy.ndarray) numpy.ndarray ¶
Computes the interpolated values for a given set of angle triplets
- Parameters:
ptg (numpy.ndarray((N, 3), dtype=numpy.float64)) – theta, phi and psi angles (in radian) for N pointings theta must be in the range [0; pi] phi must be in the range [0; 2pi] psi should be in the range [-2pi; 2pi]
- Returns:
the interpolated values n2 is either 1 (if separate=True was used in the constructor) or the second dimension of the input slm and blm arrays (otherwise)
- Return type:
numpy.array((n2, N), dtype=numpy.float64)
Notes
Can only be called in “normal” (i.e. not adjoint) mode
repeated calls to this method are fine, but for good performance the number of pointings passed per call should be as large as possible.