documentation update

gridder_cxx.h

@@ -1308,6 +1308,7 @@ template<typename T, typename Serv> void x2dirty(
 
       size_t cnt=0;
       subidx.resize(nvis_plane[iw]);
+      // FIXME: this loop becomes a bottleneck when using many threads
       for (size_t ipart=0; ipart<nvis; ++ipart)
         if ((int(iw)>=minplane[ipart]) && (iw<minplane[ipart]+supp))
           subidx[cnt++] = ipart;
@@ -1399,6 +1400,7 @@ template<typename T, typename Serv> void dirty2x(
 
       subidx.resize(nvis_plane[iw]);
       size_t cnt=0;
+      // FIXME: this loop becomes a bottleneck when using many threads
       for (size_t ipart=0; ipart<nvis; ++ipart)
         if ((int(iw)>=minplane[ipart]) && (iw<minplane[ipart]+supp))
           subidx[cnt++] = ipart;

nifty_gridder.cc

@@ -305,6 +305,8 @@ pixsize_x: float
     Pixel size in x direction (radians)
 pixsize_y: float
     Pixel size in y direction (radians)
+nthreads: int
+    the number of threads to use for all calculations involving this object.
 )""";
 class PyGridderConfig: public GridderConfig
   {
@@ -714,6 +716,35 @@ template<typename T> pyarr<T> vis2dirty2(const PyBaselines &baselines,
   }
   return dirty;
   }
+
+constexpr auto vis2dirty_DS = R"""(
+Converts an array of visibilities to a dirty image.
+
+Parameters
+==========
+baselines: Baselines
+    the Baselines object
+gconf: GridderConf
+    the GridderConf object to be used
+    (used to optimize the ordering of the indices)
+idx: np.array((nvis,), dtype=np.uint32)
+    the indices for the provided visibilities
+vis: np.array(nvis,), dtype=np.complex64 or np.complex128)
+    The input visibilities
+    Its data type determines the precision in which the calculation is carried
+    out.
+wgt: np.array((nvis,), dtype=float with same precision as `vis`, optional
+    If present, visibilities are multiplied by the corresponding entries.
+do_wstacking: bool
+    if True, the full improved w-stacking algorithm is carried out, otherwise
+    the w values are assumed to be zero.
+
+Returns
+=======
+np.array((nxdirty, nydirty), dtype=float of same precision as `vis`.)
+    The dirty image
+)""";
+
 py::array Pyvis2dirty(const PyBaselines &baselines,
   const PyGridderConfig &gconf, const py::array &idx,
   const py::array &vis, const py::object &wgt, bool do_wstacking)
@@ -745,6 +776,34 @@ template<typename T> pyarr<complex<T>> dirty2vis2(const PyBaselines &baselines,
   }
   return vis;
   }
+
+constexpr auto dirty2vis_DS = R"""(
+Converts a dirty image into a 1D array of visibilities.
+
+Parameters
+==========
+baselines: Baselines
+    the Baselines object
+gconf: GridderConf
+    the GridderConf object to be used
+    (used to optimize the ordering of the indices)
+idx: np.array((nvis,), dtype=np.uint32)
+    the indices for the visibilities to be computed
+dirty: np.array((nxdirty, nydirty), dtype=np.float32 or np.float64)
+    dirty image
+    Its data type determines the precision in which the calculation is carried
+    out.
+wgt: np.array((nvis,), same dtype as `dirty`, optional
+    If present, visibilities are multiplied by the corresponding entries.
+do_wstacking: bool
+    if True, the full improved w-stacking algorithm is carried out, otherwise
+    the w values are assumed to be zero.
+
+Returns
+=======
+np.array((nvis,), dtype=complex of same precision as `dirty`.)
+    The visibility data
+)""";
 py::array Pydirty2vis(const PyBaselines &baselines,
   const PyGridderConfig &gconf, const py::array &idx, const py::array &dirty,
   const py::object &wgt, bool do_wstacking)
@@ -779,6 +838,43 @@ template<typename T> py::array ms2dirty2(const py::array &uvw_,
   return dirty;
   }
 
+constexpr auto ms2dirty_DS = R"""(
+Converts an MS object to dirty image.
+
+Parameters
+==========
+uvw: np.array((nrows, 3), dtype=np.float64)
+    UVW coordinates from the measurement set
+freq: np.array((nchan,), dtype=np.float64)
+    channel frequencies
+ms: np.array((nrows, nchan,), dtype=np.complex64 or np.complex128)
+    the input measurement set data.
+    Its data type determines the precision in which the calculation is carried
+    out.
+wgt: np.array((nrows, nchan), float with same precision as `ms`), optional
+    If present, its values are multiplied to the output
+npix_x, npix_y: int
+    dimensions of the dirty image
+pixsize_x, pixsize_y: float
+    angular pixel size (in radians) of the dirty image
+epsilon: float
+    accuracy at which the computation should be done. Must be larger than 2e-13.
+    If `ms` has type np.complex64, it must be larger than 1e-5.
+do_wstacking: bool
+    if True, the full improved w-stacking algorithm is carried out, otherwise
+    the w values are assumed to be zero.
+nthreads: int
+    number of threads to use for the calculation
+verbosity: int
+    0: no output
+    1: some output
+    2: detailed output
+
+Returns
+=======
+np.array((nxdirty, nydirty), dtype=float of same precision as `ms`)
+    the dirty image
+)""";
 py::array Pyms2dirty(const py::array &uvw,
   const py::array &freq, const py::array &ms, const py::object &wgt,
   size_t npix_x, size_t npix_y, double pixsize_x, double pixsize_y, double epsilon,
@@ -816,6 +912,41 @@ template<typename T> py::array dirty2ms2(const py::array &uvw_,
   return ms;
   }
 
+constexpr auto dirty2ms_DS = R"""(
+Converts a dirty image to an MS object.
+
+Parameters
+==========
+uvw: np.array((nrows, 3), dtype=np.float64)
+    UVW coordinates from the measurement set
+freq: np.array((nchan,), dtype=np.float64)
+    channel frequencies
+dirty: np.array((nxdirty, nydirty), dtype=np.float32 or np.float64)
+    dirty image
+    Its data type determines the precision in which the calculation is carried
+    out.
+wgt: np.array((nrows, nchan), same dtype as `dirty`), optional
+    If present, its values are multiplied to the output
+pixsize_x, pixsize_y: float
+    angular pixel size (in radians) of the dirty image
+epsilon: float
+    accuracy at which the computation should be done. Must be larger than 2e-13.
+    If `dirty` has type np.float32, it must be larger than 1e-5.
+do_wstacking: bool
+    if True, the full improved w-stacking algorithm is carried out, otherwise
+    the w values are assumed to be zero.
+nthreads: int
+    number of threads to use for the calculation
+verbosity: int
+    0: no output
+    1: some output
+    2: detailed output
+
+Returns
+=======
+np.array((nrows, nchan,), dtype=complex of same precision as `dirty`)
+    the measurement set data.
+)""";
 py::array Pydirty2ms(const py::array &uvw,
   const py::array &freq, const py::array &dirty, const py::object &wgt,
   double pixsize_x, double pixsize_y, double epsilon,
@@ -909,15 +1040,15 @@ PYBIND11_MODULE(nifty_gridder, m)
     "grid"_a, "wgt"_a=None);
   m.def("get_correlations", &Pyget_correlations<double>, "baselines"_a, "gconf"_a,
     "idx"_a, "du"_a, "dv"_a, "wgt"_a=None);
-  m.def("vis2dirty",&Pyvis2dirty, "baselines"_a, "gconf"_a,
+  m.def("vis2dirty",&Pyvis2dirty, vis2dirty_DS, "baselines"_a, "gconf"_a,
     "idx"_a, "vis"_a, "wgt"_a=None, "do_wstacking"_a=false);
-  m.def("dirty2vis",&Pydirty2vis, "baselines"_a, "gconf"_a,
+  m.def("dirty2vis",&Pydirty2vis, "baselines"_a, dirty2vis_DS, "gconf"_a,
     "idx"_a, "dirty"_a, "wgt"_a=None, "do_wstacking"_a=false);
 
-  m.def("ms2dirty",&Pyms2dirty,"uvw"_a,"freq"_a,"ms"_a,
-    "wgt"_a=None,"npix_x"_a,"npix_y"_a,"pixsize_x"_a,"pixsize_y"_a,"epsilon"_a,
+  m.def("ms2dirty", &Pyms2dirty, ms2dirty_DS, "uvw"_a, "freq"_a, "ms"_a,
+    "wgt"_a=None, "npix_x"_a, "npix_y"_a, "pixsize_x"_a, "pixsize_y"_a,
+    "epsilon"_a, "do_wstacking"_a=false, "nthreads"_a=1, "verbosity"_a=0);
+  m.def("dirty2ms", &Pydirty2ms, dirty2ms_DS, "uvw"_a, "freq"_a, "dirty"_a,
+    "wgt"_a=None, "pixsize_x"_a, "pixsize_y"_a, "epsilon"_a,
     "do_wstacking"_a=false, "nthreads"_a=1, "verbosity"_a=0);
-  m.def("dirty2ms",&Pydirty2ms,"uvw"_a,"freq"_a,"dirty"_a,
-    "wgt"_a=None,"pixsize_x"_a,"pixsize_y"_a, "epsilon"_a, "do_wstacking"_a=false, "nthreads"_a=1,
-    "verbosity"_a=0);
   }