RESIDUAL_VIS_DOCS = DocstringTemplate("""
Computes residual visibilities in place
given model visibilities and gains solutions.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
jones : $(array_type)
Gain solutions of shape :code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
vis : $(array_type)
Data values of shape :code:`(row, chan, corr)`.
or :code:`(row, chan, corr, corr)`.
flag : $(array_type)
Flag data of shape :code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`
model : $(array_type)
Model data values of shape :code:`(row, chan, dir, corr)`
or :code:`(row, chan, dir, corr, corr)`.
Returns
-------
residual : $(array_type)
Residual visibilities of shape
:code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
""")
SPI_DOCSTRING = DocstringTemplate(r"""
Computes the spectral indices and the intensity
at the reference frequency of a spectral index model:
.. math::
I(\nu) = A(\nu) I(\nu_0) \left( \frac{\nu}{\nu_0} \right) ^ \alpha
where :math:`I(\nu)` is the apparent source spectrum,
:math:`A(\nu)` is the beam model for each component as a function of
frequency.
Parameters
----------
data : $(array_type)
array of shape :code:`(comps, chan)`
The noisy data as a function of frequency.
weights : $(array_type)
array of shape :code:`(chan,)`
Inverse of variance on each frequency axis.
freqs : $(array_type)
frequencies of shape :code:`(chan,)`
freq0 : float
Reference frequency
alphai : $(array_type), optional
array of shape :code:`(comps,)`
Initial guess for the alphas. Defaults
to -0.7.
I0i : $(array_type), optional
array of shape :code:`(comps,)`
Initial guess for the intensities at the
reference frequency. Defaults to 1.0.
beam_comps : $(array_type), optional
array of shape :code:`(comps, chan)`
Power beam for each component as a function of frequency.
tol : float, optional
Solver absolute tolerance (optional).
Defaults to 1e-6.
maxiter : int, optional
Solver maximum iterations (optional).
Defaults to 100.
dtype : np.dtype, optional
Datatype of result. Should be either np.float32
or np.float64. Defaults to np.float64.
Returns
-------
out : $(array_type)
array of shape :code:`(4, comps)`
The fitted components arranged
as [alphas, alphavars, I0s, I0vars]
""")
AVERAGING_DOCS = DocstringTemplate("""
Averages in time and channel.
Parameters
----------
time : $(array_type)
Time values of shape :code:`(row,)`.
interval : $(array_type)
Interval values of shape :code:`(row,)`.
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
time_centroid : $(array_type), optional
Time centroid values of shape :code:`(row,)`
exposure : $(array_type), optional
Exposure values of shape :code:`(row,)`
flag_row : $(array_type), optional
Flagged rows of shape :code:`(row,)`.
uvw : $(array_type), optional
UVW coordinates of shape :code:`(row, 3)`.
weight : $(array_type), optional
Weight values of shape :code:`(row, corr)`.
sigma : $(array_type), optional
Sigma values of shape :code:`(row, corr)`.
chan_freq : $(array_type), optional
Channel frequencies of shape :code:`(chan,)`.
chan_width : $(array_type), optional
Channel widths of shape :code:`(chan,)`.
vis : $(array_type), optional
Visibility data of shape :code:`(row, chan, corr)`.
flag : $(array_type), optional
Flag data of shape :code:`(row, chan, corr)`.
weight_spectrum : $(array_type), optional
Weight spectrum of shape :code:`(row, chan, corr)`.
sigma_spectrum : $(array_type), optional
Sigma spectrum of shape :code:`(row, chan, corr)`.
time_bin_secs : float, optional
Maximum summed interval in seconds to include within a bin.
Defaults to 1.0.
chan_bin_size : int, optional
Number of bins to average together.
Defaults to 1.
Returns
-------
namedtuple
A namedtuple whose entries correspond to the input arrays.
Output arrays will generally be ``None`` if the inputs were ``None``.
""")
:code:`(dim_1, ..., dim_n, icorr_1, ..., icorr_m)`
input_schema : list of str or int
A schema describing the :code:`icorr_1, ..., icorr_m`
dimension of ``input``. Must have the same shape as
the last dimensions of ``input``.
output_schema : list of str or int
A schema describing the :code:`ocorr_1, ..., ocorr_n`
dimension of the return value.
Returns
-------
result : $(array_type)
Result of shape :code:`(dim_1, ..., dim_n, ocorr_1, ..., ocorr_m)`
The type may be floating point or promoted to complex
depending on the combinations in ``output``.
"""
# Fill in the STOKES TYPES
_map_str = ", ".join(["%s: %d" % (t, i) for i, t in enumerate(STOKES_TYPES)])
_map_str = "{{ " + _map_str + " }}"
# Indent must match docstrings
_map_str = fill(_map_str, initial_indent='', subsequent_indent=' ' * 8)
CONVERT_DOCS = DocstringTemplate(CONVERT_DOCS.format(stokes_type_map=_map_str))
del _map_str
try:
convert.__doc__ = CONVERT_DOCS.substitute(
array_type=":class:`numpy.ndarray`")
except AttributeError:
pass
GAUSS_NEWTON_DOCS = DocstringTemplate("""
Performs phase-only maximum likelihood
calibration using a Gauss-Newton optimisation
algorithm. Currently only DIAG mode is supported.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`.
jones : $(array_type)
Gain solutions of shape :code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
vis : $(array_type)
Data values of shape :code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`.
flag : $(array_type)
Flag data of shape :code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`.
model : $(array_type)
Model data values of shape :code:`(row, chan, dir, corr)`
or :code:`(row, chan, dir, corr, corr)`.
weight : $(array_type)
Weight spectrum of shape :code:`(row, chan, corr)`.
If the channel axis is missing weights are duplicated
for each channel.
tol: float, optional
The tolerance of the solver. Defaults to 1e-4.
maxiter: int, optional
The maximum number of iterations. Defaults to 100.
Returns
-------
gains : $(array_type)
Gain solutions of shape :code:`(time, ant, chan, dir, corr)`
or shape :code:`(time, ant, chan, dir, corr, corr)`
jhj : $(array_type)
The diagonal of the Hessian of shape
:code:`(time, ant, chan, dir, corr)` or shape
:code:`(time, ant, chan, dir, corr, corr)`
jhr : $(array_type)
Residuals projected into gain space
of shape :code:`(time, ant, chan, dir, corr)`
or shape :code:`(time, ant, chan, dir, corr, corr)`.
k: int
Number of iterations (will equal maxiter if
not converged)
""")
COMPUTE_AND_CORRUPT_VIS_DOCS = DocstringTemplate("""
Corrupts time variable component model with arbitrary
Jones terms. Currrently only time variable point source
models are supported.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
jones : $(array_type)
Gains of shape :code:`(utime, ant, chan, dir, corr)`
or :code:`(utime, ant, chan, dir, corr, corr)`.
model : $(array_type)
Model image as a function of time with shape
:code:`(utime, chan, dir, corr)` or
:code:`(utime, chan, dir, corr, corr)`.
uvw : $(array_type)
uvw coordinates of shape :code:`(row, 3)`
lm : $(array_type)
Source lm coordinates as a function of time
:code:`(utime, dir, 2)`
Returns
-------
vis : $(array_type)
visibilities of shape
:code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`.
""")
BEAM_CUBE_DOCS = DocstringTemplate(r"""
Evaluates Direction Dependent Effects along a source's path
by interpolating the values of a complex beam cube
at the source location.
Notes
-----
1. Sources are clamped to the provided `beam_lm_extents`.
2. Frequencies outside the cube (i.e. outside beam_freq_map)
introduce linear scaling to the lm coordinates of a source.
Parameters
----------
beam : $(array_type)
Complex beam cube of
shape :code:`(beam_lw, beam_mh, beam_nud, corr, corr)`.
`beam_lw`, `beam_mh` and `beam_nud` define the size
of the cube in the l, m and frequency dimensions, respectively.
beam_lm_extents : $(array_type)
lm extents of the beam cube of shape :code:`(2, 2)`.
``[[lower_l, upper_l], [lower_m, upper_m]]``.
beam_freq_map : $(array_type)
Beam frequency map of shape :code:`(beam_nud,)`.
This array is used to define interpolation along
the :code:`(chan,)` dimension.
lm : $(array_type)
Source lm coordinates of shape :code:`(source, 2)`.
These coordinates are:
1. Scaled if the associated frequency lies outside the beam cube.
2. Offset by pointing errors: ``point_errors``
3. Rotated by parallactic angles: ``parallactic_angles``.
4. Scaled by antenna scaling factors: ``antenna_scaling``.
parallactic_angles : $(array_type)
Parallactic angles of shape :code:`(time, ant)`.
point_errors : $(array_type)
Pointing errors of shape :code:`(time, ant, chan, 2)`.
antenna_scaling : $(array_type)
Antenna scaling factors of shape :code:`(ant, chan, 2)`
frequencies : $(array_type)
Frequencies of shape :code:`(chan,)`.
Returns
-------
ddes : $(array_type)
Direction Dependent Effects of shape
:code:`(source, time, ant, chan, corr, corr)`
""")
FEED_ROTATION_DOCS = DocstringTemplate(r"""
Computes the 2x2 feed rotation (L) matrix
from the ``parallactic_angles``.
.. math::
\textrm{linear}
\begin{bmatrix}
cos(pa) & sin(pa) \\
-sin(pa) & cos(pa)
\end{bmatrix}
\qquad
\textrm{circular}
\begin{bmatrix}
e^{-i pa} & 0 \\
0 & e^{i pa}
\end{bmatrix}
Parameters
----------
parallactic_angles : $(array_type)
floating point parallactic angles. Of shape
:code:`(pa0, pa1, ..., pan)`.
feed_type : {'linear', 'circular'}
The type of feed
Returns
-------
feed_matrix : $(array_type)
Feed rotation matrix of shape :code:`(pa0, pa1,...,pan,2,2)`
""")
PREDICT_DOCS = DocstringTemplate(r"""
Multiply Jones terms together to form model visibilities according
to the following formula:
.. math::
V_{pq} = G_{p} \left(
B_{pq} + \sum_{s} E_{ps} X_{pqs} E_{qs}^H
\right) G_{q}^H
where for antenna :math:`p` and :math:`q`, and source :math:`s`:
- :math:`B_{{pq}}` represent base coherencies.
- :math:`E_{{ps}}` represents Direction-Dependent Jones terms.
- :math:`X_{{pqs}}` represents a coherency matrix (per-source).
- :math:`G_{{p}}` represents Direction-Independent Jones terms.
Generally, :math:`E_{ps}`, :math:`G_{p}`, :math:`X_{pqs}`
should be formed by using the `RIME API <rime-api-anchor_>`_ functions
and combining them together with :func:`~numpy.einsum`.
**Please read the Notes**
Notes
-----
* Direction-Dependent terms (dde{1,2}_jones) and
Independent (die{1,2}_jones) are optional,
but if one is present, the other must be present.
* The inputs to this function involve ``row``, ``time``
and ``ant`` (antenna) dimensions.
* Each ``row`` is associated with a pair of antenna Jones matrices
at a particular timestep via the
``time_index``, ``antenna1`` and ``antenna2`` inputs.
* The ``row`` dimension must be an increasing partial order in time.
$(extra_notes)
Parameters
----------
time_index : $(array_type)
Time index used to look up the antenna Jones index
for a particular baseline with shape :code:`(row,)`.
Obtainable via $(get_time_index).
antenna1 : $(array_type)
Antenna 1 index used to look up the antenna Jones
for a particular baseline.
with shape :code:`(row,)`.
antenna2 : $(array_type)
Antenna 2 index used to look up the antenna Jones
for a particular baseline.
with shape :code:`(row,)`.
dde1_jones : $(array_type), optional
:math:`E_{ps}` Direction-Dependent Jones terms for the first antenna.
shape :code:`(source,time,ant,chan,corr_1,corr_2)`
source_coh : $(array_type), optional
:math:`X_{pqs}` Direction-Dependent Coherency matrix for the baseline.
with shape :code:`(source,row,chan,corr_1,corr_2)`
dde2_jones : $(array_type), optional
:math:`E_{qs}` Direction-Dependent Jones terms for the second antenna.
This is usually the same array as ``dde1_jones`` as this
preserves the symmetry of the RIME. ``predict_vis`` will
perform the conjugate transpose internally.
shape :code:`(source,time,ant,chan,corr_1,corr_2)`
die1_jones : $(array_type), optional
:math:`G_{ps}` Direction-Independent Jones terms for the
first antenna of the baseline.
with shape :code:`(time,ant,chan,corr_1,corr_2)`
base_vis : $(array_type), optional
:math:`B_{pq}` base coherencies, added to source coherency summation
*before* multiplication with `die1_jones` and `die2_jones`.
shape :code:`(row,chan,corr_1,corr_2)`.
die2_jones : $(array_type), optional
:math:`G_{ps}` Direction-Independent Jones terms for the
second antenna of the baseline.
This is usually the same array as ``die1_jones`` as this
preserves the symmetry of the RIME. ``predict_vis`` will
perform the conjugate transpose internally.
shape :code:`(time,ant,chan,corr_1,corr_2)`
$(extra_args)
Returns
-------
visibilities : $(array_type)
Model visibilities of shape :code:`(row,chan,corr_1,corr_2)`
""")
SPECTRAL_MODEL_DOC = DocstringTemplate(r"""
Compute a spectral model, per polarisation.
.. math::
:nowrap:
\begin{eqnarray}
I(\lambda) & = & \sum_{i=0} \alpha_{i} (\lambda / \lambda_0 - 1)^i
\, \textrm{where} \, \alpha_0 = I(\lambda_0) \\
\ln( I(\lambda) ) & = & \sum_{i=0} \alpha_{i}
\ln (\lambda / \lambda_0)^i
\, \textrm{where} \, \alpha_0 = \ln I_0 \\
\log_{10}( I(\lambda) ) & = & \sum_{i=0} \alpha_{i}
\log_{10} (\lambda / \lambda_0)^i
\, \textrm{where} \, \alpha_0 = \log_{10} I_0 \\
\end{eqnarray}
Parameters
----------
stokes : $(array_type)
Stokes parameters of shape :code:`(source,)` or :code:`(source, pol)`.
If a ``pol`` dimension is present, then it must also be present on ``spi``.
spi : $(array_type)
Spectral index of shape :code:`(source, spi-comps)`
or :code:`(source, spi-comps, pol)`.
ref_freq : $(array_type)
Reference frequencies of shape :code:`(source,)`
frequencies : $(array_type)
Frequencies of shape :code:`(chan,)`
base : {"std", "log", "log10"} or {0, 1, 2} or list.
string or corresponding enumeration specifying the polynomial base.
Defaults to 0.
If a list is provided, a polynomial base can be specified for each
stokes parameter or polarisation in the ``pol`` dimension.
string specification of the base is only supported in python 3.
while the corresponding integer enumerations are supported
on all python versions.
Returns
-------
spectral_model : $(array_type)
Spectral Model of shape :code:`(source, chan)` or
:code:`(source, chan, pol)`.
""")
PHASE_DELAY_DOCS = DocstringTemplate(r"""
Computes the phase delay (K) term:
.. math::
& {\Large e^{-2 \pi i (u l + v m + w (n - 1))} }
& \textrm{where } n = \sqrt{1 - l^2 - m^2}
Notes
-----
Corresponds to the complex exponential of the `Van Cittert-Zernike Theorem
<https://en.wikipedia.org/wiki/Van_Cittert%E2%80%93Zernike_theorem_>`_.
`MeqTrees
<https://github.com/ska-sa/meqtrees-timba/blob/
6a7e873d4d1fe538981dec5851418cbd371b8388/MeqNodes/src/PSVTensor.cc#L314_>`_
uses a positive sign convention and so any UVW coordinates must be inverted
in order for their phase delay terms (and therefore visibilities) to agree.
Parameters
----------
lm : $(array_type)
LM coordinates of shape :code:`(source, 2)` with
L and M components in the last dimension.
uvw : $(array_type)
UVW coordinates of shape :code:`(row, 3)` with
U, V and W components in the last dimension.
frequency : $(array_type)
frequencies of shape :code:`(chan,)`
Returns
-------
complex_phase : $(array_type)
complex of shape :code:`(source, row, chan)`
""")
WSCLEAN_PREDICT_DOCS = DocstringTemplate("""
Predict visibilities from a `WSClean sky model
<https://sourceforge.net/p/wsclean/wiki/ComponentList/>`_.
Parameters
----------
uvw : $(array_type)
UVW coordinates of shape :code:`(row, 3)`
lm : $(array_type)
Source LM coordinates of shape :code:`(source, 2)`, in radians.
Derived from the ``Ra`` and ``Dec`` fields.
source_type : $(array_type)
Strings defining the source type of shape :code:`(source,)`.
Should be either ``"POINT"`` or ``"GAUSSIAN"``.
Contains the ``Type`` field.
flux : $(array_type)
Source flux of shape :code:`(source,)`.
Contains the ``I`` field.
coeffs : $(array_type)
Source Polynomial coefficients of shape :code:`(source, coeffs)`.
Contains the ``SpectralIndex`` field.
log_poly : $(array_type)
Source polynomial type of shape :code:`(source,)`.
If True, logarithmic polynomials are used.
If False, standard polynomials are used.
Contains the ``LogarithmicSI`` field.
ref_freq : $(array_type)
Source Reference frequency of shape :code:`(source,)`.
Contains the ``ReferenceFrequency`` field.
gauss_shape : $(array_type)
Gaussian shape parameters of shape :code:`(source, 3)`
used when the corresponding ``source_type`` is ``"GAUSSIAN"``.
The 3 components should contain the ``MajorAxis``, ``MinorAxis``
and ``Orientation`` fields in radians, respectively.
frequency : $(array_type)
Frequency of shape :code:`(chan,)`.
Returns
-------
visibilities : $(array_type)
Complex visibilities of shape :code:`(row, chan, 1)`
""")
CORRUPT_VIS_DOCS = DocstringTemplate("""
Corrupts model visibilities with arbitrary
Jones terms.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
jones : $(array_type)
Gains of shape :code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
model : $(array_type)
Model data values of shape :code:`(row, chan, dir, corr)`
or :code:`(row, chan, dir, corr, corr)`.
Returns
-------
vis : $(array_type)
visibilities of shape
:code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
""")
AVERAGING_DOCS = DocstringTemplate("""
Averages in time and channel.
Parameters
----------
time : $(array_type)
Time values of shape :code:`(row,)`.
interval : $(array_type)
Interval values of shape :code:`(row,)`.
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
time_centroid : $(array_type), optional
Time centroid values of shape :code:`(row,)`
exposure : $(array_type), optional
Exposure values of shape :code:`(row,)`
flag_row : $(array_type), optional
Flagged rows of shape :code:`(row,)`.
uvw : $(array_type), optional
UVW coordinates of shape :code:`(row, 3)`.
weight : $(array_type), optional
Weight values of shape :code:`(row, corr)`.
sigma : $(array_type), optional
Sigma values of shape :code:`(row, corr)`.
chan_freq : $(array_type), optional
Channel frequencies of shape :code:`(chan,)`.
chan_width : $(array_type), optional
Channel widths of shape :code:`(chan,)`.
effective_bw : $(array_type), optional
Effective channel bandwidth of shape :code:`(chan,)`.
resolution : $(array_type), optional
Effective channel resolution of shape :code:`(chan,)`.
visibilities : $(array_type) or tuple of $(array_type), optional
Visibility data of shape :code:`(row, chan, corr)`.
Tuples of visibilities arrays may be supplied,
in which case tuples will be output.
flag : $(array_type), optional
Flag data of shape :code:`(row, chan, corr)`.
weight_spectrum : $(array_type), optional
Weight spectrum of shape :code:`(row, chan, corr)`.
sigma_spectrum : $(array_type), optional
Sigma spectrum of shape :code:`(row, chan, corr)`.
time_bin_secs : float, optional
Maximum summed interval in seconds to include within a bin.
Defaults to 1.0.
chan_bin_size : int, optional
Number of bins to average together.
Defaults to 1.
Notes
-----
The implementation currently requires unique lexicographical
combinations of (TIME, ANTENNA1, ANTENNA2). This can usually
be achieved by suitably partitioning input data on indexing rows,
DATA_DESC_ID and SCAN_NUMBER in particular.
Returns
-------
namedtuple
A namedtuple whose entries correspond to the input arrays.
Output arrays will be ``None`` if the inputs were ``None``.
""")
GAUSSIAN_DOCS = DocstringTemplate(r"""
Computes the Gaussian Shape Function.
.. math::
& \lambda^\prime = 2 \lambda \pi \\
& r = \frac{e_{min}}{e_{maj}} \\
& u_{1} = (u \, e_{maj} \, cos(\alpha) - v \, e_{maj} \, sin(\alpha))
r \lambda^\prime \\
& v_{1} = (u \, e_{maj} \, sin(\alpha) - v \, e_{maj} \, cos(\alpha))
\lambda^\prime \\
& \textrm{shape} = e^{(-u_{1}^2 - v_{1}^2)}
where:
- :math:`u` and :math:`v` are the UV coordinates and
:math:`\lambda` the frequency.
- :math:`e_{maj}` and :math:`e_{min}` are the major and minor axes
and :math:`\alpha` the position angle.
Parameters
----------
uvw : $(array_type)
UVW coordinates of shape :code:`(row, 3)`
frequency : $(array_type)
frequencies of shape :code:`(chan,)`
shape_param : $(array_type)
Gaussian Shape Parameters of shape :code:`(source, 3)`
where the second dimension contains the
`(emajor, eminor, angle)` parameters describing
the shape of the Gaussian
Returns
-------
gauss_shape : $(array_type)
Shape parameters of shape :code:`(source, row, chan)`
""")
RESIDUAL_DOCS = DocstringTemplate(
r"""
Compute residual image given a model and visibilities using ducc
degridder i.e.
.. math::
I^R = R^\dagger \Sigma^{-1}(V - Rx)
where :math:`R` is an implicit degridding operator, :math:`V`
denotes visibilities of shape :code:`(row, chan)` and
:math:`x` is the image of shape :code:`(band, nx, ny)`.
The number of imaging bands :code:`(band)` must
be less than or equal to the number of channels
:code:`(chan)` at which the data were obtained.
The mapping from :code:`(chan)` to :code:`(band)` is described
by :code:`freq_bin_idx` and :code:`freq_bin_counts` as
described below.
Note that, if the gridding and degridding operators both apply
the square root of the imaging weights then the visibilities
that are passed in should be pre-whitened. In this case the
function computes
.. math::
I^R = R^\dagger \Sigma^{-\frac{1}{2}}(\tilde{V}
- \Sigma^{-\frac{1}{2}}Rx)
which is identical to the above expression if
:math:`\tilde{V} = \Sigma^{-\frac{1}{2}}V`.
Parameters
----------
uvw : $(array_type)
uvw coordinates at which visibilities were
obtained with shape :code:`(row, 3)`.
freq : $(array_type)
Observational frequencies of shape :code:`(chan,)`.
model : $(array_type)
Model image to degrid of shape :code:`(band, nx, ny)`.
vis : $(array_type)
Visibilities of shape :code:`(row,chan)`.
weights : $(array_type)
Imaging weights of shape :code:`(row, chan)`.
freq_bin_idx : $(array_type)
Starting indices of frequency bins for each imaging
band of shape :code:`(band,)`.
freq_bin_counts : $(array_type)
The number of channels in each imaging band of shape :code:`(band,)`.
cell : float
The cell size of a pixel along the :math:`x` direction in radians.
flag: $(array_type), optional
Flags of shape :code:`(row,chan)`. Will only process visibilities
for which flag!=0
celly : float, optional
The cell size of a pixel along the :math:`y` direction in radians.
By default same as cell size along :math:`x` direction.
nu : int, optional
The number of pixels in the padded grid along the :math:`x` direction.
Chosen automatically by default.
nv : int, optional
The number of pixels in the padded grid along the :math:`y` direction.
Chosen automatically by default.
epsilon : float, optional
The precision of the gridder with respect to the direct Fourier
transform. By deafult, this is set to :code:`1e-5` for single
precision and :code:`1e-7` for double precision.
nthreads : int, optional
The number of threads to use. Defaults to one.
do_wstacking : bool, optional
Whether to correct for the w-term or not. Defaults to True
double_accum : bool, optional
If true ducc will accumulate in double precision regardless of
the input type.
Returns
-------
residual : $(array_type)
Residual image corresponding to :code:`model` of shape
:code:`(band, nx, ny)`.
""")
RADEC_TO_LMN_DOCS = DocstringTemplate(r"""
Converts Right-Ascension/Declination coordinates in radians
to a Direction Cosine lm coordinates, relative to the Phase Centre.
.. math::
:nowrap:
\begin{eqnarray}
& l =& \, \cos \, \delta \sin \, \Delta \alpha \\
& m =& \, \sin \, \delta \cos \, \delta 0 -
\cos \delta \sin \delta 0 \cos \Delta \alpha \\
& n =& \, \sqrt{1 - l^2 - m^2} - 1
\end{eqnarray}
where :math:`\Delta \alpha = \alpha - \alpha 0` is the difference between
the Right Ascension of each coordinate and the phase centre and
:math:`\delta 0` is the Declination of the phase centre.
Parameters
----------
radec : $(array_type)
radec coordinates of shape :code:`(coord, 2)`
where Right-Ascension and Declination are in the
last 2 components, respectively.
phase_centre : $(array_type), optional
radec coordinates of the Phase Centre.
Shape :code:`(2,)`
Returns
-------
$(array_type)
lm Direction Cosines of shape :code:`(coord, $(lm_components))`
""")
MODEL_DOCS = DocstringTemplate(r"""
Compute image to visibility mapping using ducc degridder i.e.
.. math::
V = Rx
where :math:`R` is an implicit degridding operator, :math:`V`
denotes visibilities of shape :code:`(row, chan)` and
:math:`x` is the image of shape :code:`(band, nx, ny)`.
The number of imaging bands :code:`(band)` has to
be less than or equal to the number of channels
:code:`(chan)` at which the data were obtained.
The mapping from :code:`(chan)` to :code:`(band)` is described
by :code:`freq_bin_idx` and :code:`freq_bin_counts` as
described below.
There is an option to provide weights during degridding
to cater for self adjoint gridding and degridding operators.
In this case :code:`weights` should actually be the square
root of what is typically referred to as imaging weights.
In this case the degridder computes the whitened model
visibilities i.e.
.. math::
V = \Sigma^{-\frac{1}{2}} R x
where :math:`\Sigma` refers to the inverse of the weights
(i.e. the data covariance matrix when using natural weighting).
Parameters
----------
uvw : $(array_type)
uvw coordinates at which visibilities were
obtained with shape :code:`(row, 3)`.
freq : $(array_type)
Observational frequencies of shape :code:`(chan,)`.
model : $(array_type)
Model image to degrid of shape :code:`(nband, nx, ny)`.
freq_bin_idx : $(array_type)
Starting indices of frequency bins for each imaging
band of shape :code:`(band,)`.
freq_bin_counts : $(array_type)
The number of channels in each imaging band of shape :code:`(band,)`.
cell : float
The cell size of a pixel along the :math:`x` direction in radians.
weights : $(array_type), optional
Imaging weights of shape :code:`(row, chan)`.
flag: $(array_type), optional
Flags of shape :code:`(row,chan)`. Will only process visibilities
for which flag!=0
celly : float, optional
The cell size of a pixel along the :math:`y` direction in radians.
By default same as cell size along :math:`x` direction.
epsilon : float, optional
The precision of the gridder with respect to the direct Fourier
transform. By deafult, this is set to :code:`1e-5` for single
precision and :code:`1e-7` for double precision.
nthreads : int, optional
The number of threads to use. Defaults to one.
If set to zero will use all available cores.
do_wstacking : bool, optional
Whether to correct for the w-term or not. Defaults to True
Returns
-------
vis : $(array_type)
Visibilities corresponding to :code:`model` of shape
:code:`(row,chan)`.
""")
