Updating Documentation

doc/src/development.md

@@ -73,7 +73,7 @@ If you run mypy several times for the same file(s) and it takes a while, you can
 
 ### pydocstyle
 
-[pydocstyle](http://www.pydocstyle.org/en/stable/) supports docstring checking out of the box. The check can be used via CLI `pydocstyle {source_file_or_directory}. Further options can be found in the [documentation](http://www.pydocstyle.org/en/stable/usage.html) or via `pydocstyle --help`.
+[pydocstyle](http://www.pydocstyle.org/en/stable/) supports docstring checking out of the box. The check can be used via CLI `pydocstyle {source_file_or_directory}`. Further options can be found in the [documentation](http://www.pydocstyle.org/en/stable/usage.html) or via `pydocstyle --help`.
 
 In our project we use the [google convention](http://www.pydocstyle.org/en/stable/error_codes.html?highlight=google#default-conventions). Python files, classes as well as functions need corresponding docstrings. There are autocompletion tools for IDE's that create docstrings in the correct format (e.g. VSCode [autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring)). Below is an example of a dummy function with the corresponding docstring template:
 

doc/src/index.rst

@@ -41,6 +41,12 @@ Modules
 
    main_features/sourcedetection.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Utilities
+
+   utilities/utils.rst
+
 
 Development
 ===========

doc/src/installation_user.md

@@ -28,7 +28,7 @@ conda env config vars set LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/wsl/lib
 ```
 
 ## Dealing with the error 'OSKAR library not found'
-If you use Karabo and get the error `RuntimeError: OSKAR library not found.` then this because the correct CUDA drivers are not installed. Karabo relies on CUDA drivers 11.7. It has been reported that often versions > 12 get installed automatically. In this case the above mentioned error is shown at runtime. More information about this issue can be found [here (issue #568)](https://github.com/i4Ds/Karabo-Pipeline/issues/568). Refer to this issue for a workaround.
+If you use Karabo and get the error `RuntimeError: OSKAR library not found.` then this is because the correct CUDA drivers were not installed. Karabo relies on CUDA drivers 11.7. It has been reported that often versions > 12 get installed automatically. In this case the above mentioned error is shown at runtime. More information about this issue can be found [here (issue #568)](https://github.com/i4Ds/Karabo-Pipeline/issues/568). Refer to this issue for a workaround.
 
 Please refer to the troubleshooting section at the bottom of this page if you feel something else does not work.
 

doc/src/main_features/simulation.rst

@@ -37,3 +37,19 @@ Classes
    :members:
    :special-members: __init__
    :exclude-members: __strfdelta, __run_simulation_oskar, __run_simulation_long, __get_OSKAR_settings_tree
+
+.. autoclass:: karabo.simulation.east_north_coordinate.EastNorthCoordinate
+   :members:
+   :special-members: __init__
+   :exclude-members:
+
+Line emission package
+------------------------
+.. automodule:: karabo.simulation.line_emission
+   :members:
+   :show-inheritance:
+
+.. automodule:: karabo.simulation.line_emission_helpers
+   :members:
+   :show-inheritance:
+

doc/src/utilities/utils.rst

@@ -0,0 +1,62 @@
+karabo.util package
+===================
+
+This package provides auxiliary function used in different parts of
+the code. 
+
+Submodules
+----------
+
+karabo.util.dask
+----------------
+.. automodule:: karabo.util.dask
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+karabo.util.gpu_util
+--------------------
+.. automodule:: karabo.util.gpu_util
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+karabo.util.hdf5_util
+---------------------
+.. automodule:: karabo.util.hdf5_util
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+karabo.util.file_handler
+------------------------
+.. automodule:: karabo.util.file_handler
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+karabo.util.math_util
+------------------------
+.. automodule:: karabo.util.math_util
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+karabo.util.rascil_util
+------------------------
+.. automodule:: karabo.util.rascil_util
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+karabo.util.data_util
+------------------------
+.. automodule:: karabo.util.data_util
+   :members:
+   :show-inheritance:
+
+karabo.util.survey
+------------------------
+.. automodule:: karabo.util.survey
+   :members:
+   :show-inheritance:

karabo/imaging/imager_wsclean.py

@@ -261,7 +261,6 @@ def create_image_custom_command(
             Example 2: ['wsclean-image.fits', 'wsclean-residual.fits']
 
     Returns:
-
         - If output_filenames is a **string**, returns an Image object of the file \
             output_filenames.
         - If output_filenames is a **list of strings**, returns a list of \

karabo/simulation/east_north_coordinate.py

@@ -2,12 +2,13 @@ class EastNorthCoordinate:
     """
     Class defining an east-north-(up) coordinate.
 
-    :ivar x: east coordinate in meters
-    :ivar y: north coordinate in meters
-    :ivar z: up coordinate in meters
-    :ivar x_error: east coordinate error in meters
-    :ivar y_error: north coordinate error in meters
-    :ivar z_error: up coordinate error in meters
+    Args:
+        x: east coordinate in meters
+        y: north coordinate in meters
+        z: up coordinate in meters
+        x_error: east coordinate error in meters
+        y_error: north coordinate error in meters
+        z_error: up coordinate error in meters
 
     """
 

karabo/simulation/interferometer.py

@@ -88,93 +88,101 @@ class InterferometerSimulation:
     """
     Class containing all configuration for the Interferometer Simulation.
 
-    :ivar channel_bandwidth_hz: The channel width, in Hz, used to simulate bandwidth
-        smearing. (Note that this can be different to the
-        frequency increment if channels do not cover a
-        contiguous frequency range).
-    :ivar time_average_sec: The correlator time-average duration, in seconds, used
-    to simulate time averaging smearing.
-    :ivar max_time_per_samples: The maximum number of time samples held in memory
-    before being written to disk.
-    :ivar correlation_type: The type of correlations to produce. Any value of Enum
-    CorrelationType
-    :ivar uv_filter_min: The minimum value of the baseline UV length allowed by the
-    filter. Values outside this range are not evaluated
-    :ivar uv_filter_max: The maximum value of the baseline UV length allowed by the
-        filter. Values outside this range are not evaluated.
-    :ivar uv_filter_units: The units of the baseline UV length filter values.
-        Any value of Enum FilterUnits
-    :ivar force_polarised_ms: If True, always write the Measurement Set in polarised
-        format even if the simulation was run in the single
-        polarisation 'Scalar' (or Stokes-I) mode. If False,
-        the size of the polarisation dimension in the
-        Measurement Set will be determined by the simulation mode.
-    :ivar ignore_w_components: If enabled, baseline W-coordinate component values will
-        be set to 0. This will disable W-smearing. Use only if
-        you know what you're doing!
-    :ivar noise_enable: If true, noise is added.
-    :ivar noise_seed: Random number generator seed.
-    :ivar noise_start_freq: The start frequency in Hz for which noise is included, if
-        noise is set to true.
-    :ivar noise_inc_freq: The frequency increment in Hz, if noise is set to true.
-    :ivar noise_number_freq: The number of frequency taken into account, if noise is set
-         to true.
-    :ivar noise_rms_start: Station RMS (noise) flux density range start value, in Jy.
-        The range is expanded linearly over the number of frequencies
-        for which noise is defined.
-    :ivar noise_rms_end: Station RMS (noise) flux density range end value, in Jy. The
-        range is expanded linearly over the number of frequencies for
-        which noise is defined.
-    :ivar noise_rms: The specifications for the RMS noise value:
-        Telescope model: values are loaded from files in the telescope
+    Args:
+        channel_bandwidth_hz: The channel width, in Hz, used to simulate bandwidth
+            smearing. (Note that this can be different to the
+            frequency increment if channels do not cover a
+            contiguous frequency range).
+        time_average_sec: The correlator time-average duration, in seconds, used
+            to simulate time averaging smearing.
+        max_time_per_samples: The maximum number of time samples held in memory
+            before being written to disk.
+        correlation_type: The type of correlations to produce. Any value of Enum
+            CorrelationType
+        uv_filter_min: The minimum value of the baseline UV length allowed by the
+            filter. Values outside this range are not evaluated
+        uv_filter_max: The maximum value of the baseline UV length allowed by the
+            filter. Values outside this range are not evaluated.
+        uv_filter_units: The units of the baseline UV length filter values.
+            Any value of Enum FilterUnits
+        force_polarised_ms: If True, always write the Measurement Set in polarised
+            format even if the simulation was run in the single
+            polarisation 'Scalar' (or Stokes-I) mode. If False,
+            the size of the polarisation dimension in the
+            Measurement Set will be determined by the simulation mode.
+        ignore_w_components: If enabled, baseline W-coordinate component values will
+            be set to 0. This will disable W-smearing. Use only if
+            you know what you're doing!
+        noise_enable: If true, noise is added.
+        noise_seed: Random number generator seed.
+        noise_start_freq: The start frequency in Hz for which noise is included, if
+            noise is set to true.
+        noise_inc_freq: The frequency increment in Hz, if noise is set to true.
+        noise_number_freq: The number of frequency taken into account, if noise is set
+             to true.
+        noise_rms_start: Station RMS (noise) flux density range start value, in Jy.
+            The range is expanded linearly over the number of frequencies
+            for which noise is defined.
+        noise_rms_end: Station RMS (noise) flux density range end value, in Jy. The
+            range is expanded linearly over the number of frequencies for
+            which noise is defined.
+        noise_rms: The specifications for the RMS noise value:
+
+            - Telescope model: values are loaded from files in the telescope
             model directory.
-        Data file: values are loaded from the specified file.
-        Range: values are evaluated according to the specified range
-            parameters (Default).
-        The noise values are specified in Jy and represent the RMS noise of
-        an unpolarised source in terms of flux measured in a single
-        polarisation of the detector.
-    :ivar noise_freq: The list of frequencies for which noise values are defined:
-        Telescope model: frequencies are loaded from a data file in
-             the telescope model directory.
-        Observation settings: frequencies are defined by the observation
-         settings.
-        Data file: frequencies are loaded from the specified data file.
-        Range: frequencies are specified by the range parameters (Default).
-    :ivar enable_array_beam: If true, then the contribution to the station beam from
-     the array pattern (given by beam-forming the antennas in
-     the station) is evaluated.
-    :ivar enable_numerical_beam: If true, make use of any available numerical element
-        pattern files. If numerical pattern data are missing,
-         the functional type will be used instead.
-    :ivar beam_polX: currently only considered for 'ObservationLong'
-    :ivar beam_polX: currently only considered for 'ObservationLong'
-    :ivar use_gpus: Set to true if you want to use gpus for the simulation
-    :ivar client: The dask client to use for the simulation
-    :ivar split_idxs_per_group: The indices of the sky model to split for each group
-         of workers. If None, the sky model will not be split.
-        Useful if the sky model is too large to fit into the
-        memory of a single worker. Group index should be
-        strictly monotonic increasing.
-    :ivar precision: For the arithmetic use you can choose between "single" or
-        "double" precision
-    :ivar station_type: Here you can choose the type of each station in the
-        interferometer. You can either disable all station beam
-        effects by choosing "Isotropic beam". Or select one of the
-        following beam types:
-        "Gaussian beam", "Aperture array" or "VLA (PBCOR)"
-    :ivar enable_power_pattern: If true, gauss_beam_fwhm_deg will be taken in as
-        power pattern.
-    :ivar gauss_beam_fwhm_deg: If you choose "Gaussian beam" as station type you need
-        specify the full-width half maximum value at the
-        reference frequency of the Gaussian beam here.
-        Units = degrees. If enable_power_pattern is True,
-        gauss_beam_fwhm_deg is in power pattern, otherwise
-        it is in field pattern.
-    :ivar gauss_ref_freq_hz: The reference frequency of the specified FWHM, in Hz.
-    :ivar ionosphere_fits_path: The path to a fits file containing an ionospheric screen
-        generated with ARatmospy. The file parameters
-        (times/frequencies) should coincide with the planned observation.
+
+            - Data file: values are loaded from the specified file.
+
+            - Range: values are evaluated according to the specified range
+            parameters (Default). The noise values are specified in Jy and
+            represent the RMS noise of
+            an unpolarised source in terms of flux measured in a single
+            polarisation of the detector.
+        noise_freq: The list of frequencies for which noise values are defined:
+
+            - Telescope model: frequencies are loaded from a data file in
+            the telescope model directory.
+
+            - Observation settings: frequencies are defined by the observation
+            settings.
+
+            - Data file: frequencies are loaded from the specified data file.
+
+            - Range: frequencies are specified by the range parameters (Default).
+        enable_array_beam: If true, then the contribution to the station beam from
+            the array pattern (given by beam-forming the antennas in
+            the station) is evaluated.
+        enable_numerical_beam: If true, make use of any available numerical element
+            pattern files. If numerical pattern data are missing,
+            the functional type will be used instead.
+        beam_polX: currently only considered for 'ObservationLong'
+        beam_polX: currently only considered for 'ObservationLong'
+        use_gpus: Set to true if you want to use gpus for the simulation
+        client: The dask client to use for the simulation
+        split_idxs_per_group: The indices of the sky model to split for each group
+            of workers. If None, the sky model will not be split.
+            Useful if the sky model is too large to fit into the
+            memory of a single worker. Group index should be
+            strictly monotonic increasing.
+        precision: For the arithmetic use you can choose between "single" or
+            "double" precision
+        station_type: Here you can choose the type of each station in the
+            interferometer. You can either disable all station beam
+            effects by choosing "Isotropic beam". Or select one of the
+            following beam types:
+            "Gaussian beam", "Aperture array" or "VLA (PBCOR)"
+        enable_power_pattern: If true, gauss_beam_fwhm_deg will be taken in as
+            power pattern.
+        gauss_beam_fwhm_deg: If you choose "Gaussian beam" as station type you need
+            specify the full-width half maximum value at the
+            reference frequency of the Gaussian beam here.
+            Units = degrees. If enable_power_pattern is True,
+            gauss_beam_fwhm_deg is in power pattern, otherwise
+            it is in field pattern.
+        gauss_ref_freq_hz: The reference frequency of the specified FWHM, in Hz.
+        ionosphere_fits_path: The path to a fits file containing an ionospheric screen
+            generated with ARatmospy. The file parameters
+            (times/frequencies) should coincide with the planned observation.
 
     """
 
@@ -414,7 +422,7 @@ def run_simulation(
 
         Returns:
             Visibility object of the generated data or list of Visibility objects
-                for ObservationParallelized observations.
+            for ObservationParallelized observations.
         """
 
         if backend is SimulatorBackend.OSKAR:

karabo/simulation/line_emission.py

@@ -131,10 +131,11 @@ def line_emission_pipeline(
     And again, if desired, perform a primary beam correction on the final dirty images.
 
     For OSKAR, the provided primary beams will only be used for correction.
-        For the actual primary beam effect in OSKAR,
-        set the relevant parameter in the InterferometerSimulation constructor.
+    For the actual primary beam effect in OSKAR,
+    set the relevant parameter in the InterferometerSimulation constructor.
+
     For RASCIL, the provided primary beams are used
-        for both the primary beam effect and its correction.
+    for both the primary beam effect and its correction.
     """
     print(f"Selected backend: {simulator_backend}")