diff --git a/.gitlab-ci.common.yml b/.gitlab-ci.common.yml index 8213d63adecd868e1dd7ae41a0ab6f82719babc8..96253054d07c97a5a47f1ef05b66c9963615929f 100644 --- a/.gitlab-ci.common.yml +++ b/.gitlab-ci.common.yml @@ -32,7 +32,7 @@ versioning: # Unshallowing ensures that 'git log' works - git fetch --unshallow - echo BASE_IMAGE_2004=${CI_REGISTRY_IMAGE}/base_2004:$(git log -n 1 --pretty=format:%H -- docker/ubuntu_20_04_base) > versions.env - - echo BASE_IMAGE_2204=${CI_REGISTRY_IMAGE}/base_2204:$(git log -n 1 --pretty=format:%H -- docker/ubuntu_22_04_base) >> versions.env + - echo BASE_IMAGE_2404=${CI_REGISTRY_IMAGE}/base_2404:$(git log -n 1 --pretty=format:%H -- docker/ubuntu_24_04_base) >> versions.env - cat versions.env artifacts: reports: @@ -70,11 +70,11 @@ prepare-base-2004: DOCKER_IMAGE: $BASE_IMAGE_2004 DOCKER_FILE: docker/ubuntu_20_04_base -prepare-base-2204: +prepare-base-2404: extends: .prepare variables: - DOCKER_IMAGE: $BASE_IMAGE_2204 - DOCKER_FILE: docker/ubuntu_22_04_base + DOCKER_IMAGE: $BASE_IMAGE_2404 + DOCKER_FILE: docker/ubuntu_24_04_base .needs-2004: needs: @@ -83,21 +83,21 @@ prepare-base-2204: optional: true image: $BASE_IMAGE_2004 -.needs-2204: +.needs-2404: needs: - job: versioning - - job: prepare-base-2204 + - job: prepare-base-2404 optional: true - image: $BASE_IMAGE_2204 + image: $BASE_IMAGE_2404 format: - extends: .needs-2204 + extends: .needs-2404 stage: linting script: - ./scripts/run-format.sh clang-tidy: - extends: .needs-2204 + extends: .needs-2404 stage: linting script: - mkdir -p build/reports @@ -105,7 +105,7 @@ clang-tidy: # Generate compile_commands.json for clang-tidy. - cmake -DBUILD_TESTING=ON -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE .. - cd .. - - clang-tidy-12 -p build/ `find cpp/ -name *.cc` | scripts/clang-tidy-to-junit.py . > build/reports/linting.xml + - clang-tidy -p build/ `find cpp/ -name *.cc` | scripts/clang-tidy-to-junit.py . > build/reports/linting.xml artifacts: when: always paths: @@ -127,8 +127,8 @@ clang-tidy: build-2004: extends: [".needs-2004",".build"] -build-2204: - extends: [".needs-2204",".build"] +build-2404: + extends: [".needs-2404",".build"] .test: stage: test @@ -152,10 +152,10 @@ test-2004: after_script: - gcovr -j`nproc` -e 'external/.*' -e '.*/CompilerIdCXX/.*' -e '.*/test/.*' build/ -test-2204: +test-2404: extends: .test - needs: ["versioning","build-2204"] - image: $BASE_IMAGE_2204 + needs: ["versioning","build-2404"] + image: $BASE_IMAGE_2404 after_script: - mkdir -p build/reports - scripts/junit-merge.py build/reports/unit-tests.xml $(find build -name unittests_*.xml) @@ -170,10 +170,10 @@ test-2204: coverage_format: cobertura path: build/reports/code-coverage.xml -build-doc-2204: - extends: .needs-2204 +build-doc-2404: + extends: .needs-2404 stage: build - image: $BASE_IMAGE_2204 + image: $BASE_IMAGE_2404 script: - mkdir build && cd build - cmake -DBUILD_PYTHON_BINDINGS=ON -DBUILD_DOCUMENTATION=ON .. -G Ninja @@ -183,10 +183,10 @@ build-doc-2204: paths: - build/doc/html -build-docstrings-2204: - extends: .needs-2204 +build-docstrings-2404: + extends: .needs-2404 stage: build - image: $BASE_IMAGE_2204 + image: $BASE_IMAGE_2404 script: - mkdir build && cd build - cmake -DBUILD_DOCSTRINGS=ON -G Ninja .. diff --git a/README.md b/README.md index 209778aca1554fa3899b59810dc56bf4b688e922..5c11e33d3affe72d168d3fb7a8334a62a3d0e8a7 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,15 @@ -# Radio Astronomical Deconvolution Library +# Radler: Radio Astronomical Deconvolution Library -Radler is a library providing functionality for deconvolving astronomical images. Radler evolved as a stand-alone library from the w-stacking clean (WSClean) imager, `https://gitlab.com/aroffringa/wsclean`_. +Radler is a library providing functionality for deconvolving astronomical images. The library was split off from WSClean, `https://gitlab.com/aroffringa/wsclean`_ in order to enhance modularity and comparisons. + +## Documentation + +The Radler-specific documentation can be found here: `https://radler.readthedocs.io/`_, which includes how to interface with Radler from Python or C++. Information about the different methods and when to +use which method (aimed at astronomers) can be found in the WSClean manual, `https://wsclean.readthedocs.io/`_. The WSClean documentation also contains references to scientific papers that describe the methods that are implemented +in Radler. ## Testing -Radler will be more extensively tested in the near-future. Tests for the core functionality - in particular the different `DeconvolutionAlgorithms` can be found in the `cpp/test` directory. Smaller scale unit tests can be found at namespace level (see, e.g., `cpp/math/test`) +Tests for the core functionality - in particular the different deconvolution algorithms can be found in the `cpp/test` directory. Smaller scale unit tests can be found at namespace level (see, e.g., `cpp/math/test`). Some example scripts of how the C++ interface can be used, are found in the `cpp/demo` directory. diff --git a/doc/build-instructions.rst b/doc/build-instructions.rst index 3163bc54f76a2aff7ebc4813ee87b9f3908eb02f..d3fde4f7baa6a347e29d0d0c05fdee486ebc0823 100644 --- a/doc/build-instructions.rst +++ b/doc/build-instructions.rst @@ -14,41 +14,35 @@ Radler can be installed from pypi: pip install radler +This is the easiest way to install radler, but might not always contain the latest features. To be sure to have the latest features, build it from source. Building from source ~~~~~~~~~~~~~~~~~~~~ -Radler needs a number of dependencies in order to successfully compile. On a clean (ubuntu 22.04) system, +Radler needs a number of dependencies in order to successfully compile. On a clean (Ubuntu 24.04) system, the dependencies can be installed with (see also the ``docker`` directory): General packages: :: - apt update && apt -y install git make cmake libpython3-dev g++ \ - libboost-date-time-dev libhdf5-dev libfftw3-dev libgsl-dev python3-pip + apt install git make cmake libpython3-dev g++ casacore-dev \ + libboost-date-time-dev libcfitsio-dev libfftw3-dev libgsl-dev \ + libhdf5-dev -Astronomy-specific packages: +In order to be able to build the documentation with ``make doc`` and ``sphinx``, a few documentation tools need to be installed: :: - apt -y install casacore-dev libcfitsio-dev + apt -y install doxygen python3-pip + pip3 install sphinx sphinx_rtd_theme breathe -In order to be able to build the documentation with ``make doc``, ``sphinx`` and some other documentation tools need to be installed: -:: - - apt -y install doxygen - pip3 install sphinx sphinx_rtd_theme breathe myst-parser - - - - -Quick installation guide -~~~~~~~~~~~~~~~~~~~~~~~~ +Quick compilation guide +~~~~~~~~~~~~~~~~~~~~~~~ :: - git clone --recursive https://git.astron.nl/RD/Radler.git + git clone https://git.astron.nl/RD/Radler.git cd Radler mkdir build && cd build cmake -DBUILD_PYTHON_BINDINGS=On .. @@ -64,9 +58,9 @@ Installation options * :code:`BUILD_PYTHON_BINDINGS`: build Python module 'radler' to use Radler from Python * :code:`BUILD_TESTING`: compile tests -All other build options serve development purposes only, and can/should be left at the default values by a regular user. +All other build options serve development purposes only, and can be left at the default values by a regular user. All libraries are installed in :code:`<installpath>/lib`. The header files in :code:`<installpath>/include`. The Python module in -:code:`<installpath>/lib/python{VERSION_MAJOR}.{VERSION_MINOR}/site-packages`. Make sure that your -:code:`LD_LIBRARY_PATH` and :code:`PYTHONPATH` are set as appropiate. +:code:`<installpath>/lib/python{VERSION_MAJOR}.{VERSION_MINOR}/site-packages`. Depending on your configuration, it might be necessary to set +:code:`LD_LIBRARY_PATH` and :code:`PYTHONPATH` appropiately. diff --git a/doc/conf.py b/doc/conf.py index a4fceb2b5968d4c3202595495e761928f769bd5b..c6ed51d1ac545e0c3c3d923fdfe8ebd6c04b0f1e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -45,7 +45,6 @@ extensions = [ "sphinx.ext.autodoc", "sphinx.ext.napoleon", "breathe", - "myst_parser", ] # Disable typehints in signatures - doens't seem to take any effect diff --git a/doc/index.rst b/doc/index.rst index 8836ed7033c911c1edafdf6f774e41ce88f9366f..aa0af2de8cc580510550426ab3c50864d5212191 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,5 +1,22 @@ -.. include:: ../README.md - :parser: myst_parser.sphinx_ +Radler: Radio Astronomical Deconvolution Library +================================================ + +Radler is a library providing functionality for deconvolving astronomical images. The library was split off from WSClean, `https://gitlab.com/aroffringa/wsclean`_ in order to enhance modularity and comparisons. + +Documentation +------------- + +This manual describes Radler-specific documentation, which includes how to interface with Radler from Python or C++. +Information about the different methods and when to +use which method (aimed at astronomers) can be found in `the WSClean manual <https://wsclean.readthedocs.io/>`_. The WSClean documentation also contains references to scientific papers that describe the methods that are implemented +in Radler. + +For more information, contact André Offringa (offringa@gmail.com). + +License +------- + +Radler is released under the LGPL version 3. .. toctree:: :maxdepth: 2 diff --git a/doc/requirements.txt b/doc/requirements.txt index 442c966a3697803a0d080ce614a1bd8c56ac8e09..9f5d6aae6d1c19ad42e2299c71c05e94c58f6c08 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -3,6 +3,5 @@ # Required python packages for building on ReadTheDocs. # See .readthedocs.yaml in the root of this repository. breathe -myst-parser numpy sphinx_rtd_theme diff --git a/doc/tree/cpp-interface.rst b/doc/tree/cpp-interface.rst index d81999fecd4eddbbcddcacbb90d1ca40611ed80a..d1930ca302e618aa406051f0f6f5de8ba95e8c01 100644 --- a/doc/tree/cpp-interface.rst +++ b/doc/tree/cpp-interface.rst @@ -1,7 +1,7 @@ C++ interface ============= -Below the most important parts of the Radler C++ API are documented. +The following sections describe the most important parts of the Radler C++ API. .. toctree:: :maxdepth: 1 diff --git a/doc/tree/interfaces-overview.rst b/doc/tree/interfaces-overview.rst index a020e0fa90a97184b33f7aba60c48b89ba3f2a53..84fa13372852673a66cb40faebbbf71959003e1c 100644 --- a/doc/tree/interfaces-overview.rst +++ b/doc/tree/interfaces-overview.rst @@ -1,6 +1,6 @@ Interface overview ====================== -Radler is primarily written in :code:`C++`. If Radler was compiled with :code:`BUILD_PYTHON_BINDINGS=ON` -Python bindings are generated to interface the Radler API from within Python. See below for the documentation of the -:code:`C++` and the :code:`Python` interface. +Radler is primarily written in ``C++``. If Radler was compiled with ``BUILD_PYTHON_BINDINGS=ON`` +Python bindings are generated to interface the Radler API from within Python. The next sections describe the +``C++`` and the ``Python`` interface. diff --git a/doc/tree/python-interface.rst b/doc/tree/python-interface.rst index b413326471900341afbdd676b2aad23df522c144..1cfb93ef9a60e0571d8ca27681cae5c10b2b4e40 100644 --- a/doc/tree/python-interface.rst +++ b/doc/tree/python-interface.rst @@ -4,7 +4,7 @@ Python interface Radler provides an interface via the :code:`radler` module. In order to build this module, make sure the cmake configuration option :code:`BUILD_PYTHON_BINDINGS` is turned :code:`ON`. -After successfully compiling and installing the python bindings, you should update your :code:`LD_LIBRARY_PATH` +After successfully compiling and installing the python bindings, you may have to update your :code:`LD_LIBRARY_PATH` and your :code:`PYTHONPATH` as follows: :: diff --git a/docker/ubuntu_22_04_base b/docker/ubuntu_24_04_base similarity index 57% rename from docker/ubuntu_22_04_base rename to docker/ubuntu_24_04_base index 31ee846d3606091256c6717103c511c334b5d7d3..ea5328bbf13392be19f2fbc45065c5ca461a58da 100644 --- a/docker/ubuntu_22_04_base +++ b/docker/ubuntu_24_04_base @@ -1,19 +1,19 @@ # SPDX-License-Identifier: LGPL-3.0-only # base -FROM ubuntu:22.04 +FROM ubuntu:24.04 # libclang, llvm just needed for docstrings (for development only) RUN export DEBIAN_FRONTEND="noninteractive" && \ apt-get update && \ apt-get upgrade -y && \ apt-get -y install \ + black \ casacore-dev \ casacore-tools \ - libclang1 \ - clang-format-12 \ - clang-tidy-12 \ + clang-format-14 \ + clang-tidy \ cmake \ - doxygen \ + doxygen \ g++ \ gcovr \ git \ @@ -27,29 +27,20 @@ RUN export DEBIAN_FRONTEND="noninteractive" && \ locales \ make \ ninja-build \ + python3-breathe \ + python3-numpy \ python3-pip \ + python3-pytest \ + python3-pytest-lazy-fixture \ + python3-sphinx \ + python3-sphinx-rtd-theme \ wcslib-dev \ wget \ && \ - rm -rf /var/lib/apt/lists/* \ - # The formatter needs a binary named 'clang-format', not 'clang-format-12'. - # Same for clang-tidy-12 - && \ - ln -sf clang-format-12 /usr/bin/clang-format \ - && \ - ln -sf clang-tidy-12 /usr/bin/clang-tidy -RUN python3 -m pip install \ - black \ - breathe \ + rm -rf /var/lib/apt/lists/* +RUN python3 -m pip install --break-system-packages \ cmake-format \ - myst-parser \ - numpy \ - pybind11-mkdoc \ - pytest \ - pytest-lazy-fixture \ - sphinx \ - sphinx_rtd_theme \ - ; + pybind11-mkdoc RUN locale-gen en_US.UTF-8 # Necessary for creating docstrings (Högbom) ENV LANG en_US.UTF-8 ENV LANGUAGE en_US:UTF-8 diff --git a/scripts/run-format.sh b/scripts/run-format.sh index 37964f6d95e892de2f1407fd3110c6d15382c7e5..6839fa7624b0ed05c391c9331a9bb9eb3e60f8da 100755 --- a/scripts/run-format.sh +++ b/scripts/run-format.sh @@ -8,6 +8,8 @@ SOURCE_DIR=$(dirname "$0")/.. #relative to SOURCE_DIR. EXCLUDE_DIRS=(external build CMake python/docstrings) +CLANG_FORMAT_BINARY=clang-format-14 + #End script configuration. #The common formatting script has further documentation.