Merge branch 'main' into add_benchmarks

.github/workflows/build_docs.yaml

@@ -2,6 +2,7 @@ name: Build and deploy docs
 on:
   pull_request:
     branches:
+      - main
       - 'doc/**'
       - 'docs/**'
     tags:

.gitignore

@@ -29,3 +29,5 @@ docs/source/examples/_notebooks
 # emacs work in progress files (lock and autosave)
 .#*
 \#*#
+# Exclude files starting with exclude (local test and development)
+exclude*

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "lib/pybind11"]
 	path = lib/pybind11
 	url = https://github.com/pybind/pybind11.git
+[submodule "include/eigen"]
+	path = include/eigen
+	url = https://gitlab.com/libeigen/eigen.git

CMakeLists.txt

@@ -29,10 +29,11 @@ find_library(CFITSIO_LIBRARY
 
 add_subdirectory(lib/pybind11)
 
-set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
 
 include_directories(
     include/
+    include/eigen
 )
 
 

benchmarks/bench_masking.py

@@ -0,0 +1,150 @@
+import timeit
+import numpy as np
+
+from kbmod.masking import (
+    BitVectorMasker,
+    DictionaryMasker,
+    GlobalDictionaryMasker,
+    GrowMask,
+    ThresholdMask,
+    apply_mask_operations,
+)
+from kbmod.result_list import ResultRow
+from kbmod.search import ImageStack, PSF, RawImage, LayeredImage
+
+
+def set_up_image_stack():
+    """Create a fake image stack to use with the masking tests.
+
+    Returns
+    -------
+    stack : `ImageStack`
+        The generated images.
+    """
+    imgs = []
+    for i in range(10):
+        img = LayeredImage(
+            "test_image",
+            1024,  # Width
+            1024,  # Height
+            0.1,  # Noise level
+            0.01,  # Variance
+            i,  # Time
+            PSF(1.0),
+        )
+
+        # Mask some pixels.
+        msk = img.get_mask()
+        for y in range(1024):
+            for x in range(1024):
+                if x % 10 == 0 and y % 10 == 0:
+                    msk.set_pixel(x, y, 1)
+
+        imgs.append(img)
+    return ImageStack(imgs)
+
+
+def bench_image_masker(masker, stack):
+    """Benchmark a single ImageMasker object.
+
+    Parameters
+    ----------
+    masker : `ImageMasker`
+        The object to benchmark.
+    stack : `ImageStack`
+        The data to use.
+
+    Returns
+    -------
+    res_time : `float`
+        The average run time.
+    """
+    tmr = timeit.Timer(stmt="masker.apply_mask(stack)", globals=locals())
+    res_time = np.mean(tmr.repeat(repeat=50, number=1))
+    return res_time
+
+
+def bench_dictionary_masker():
+    mask_bits_dict = {
+        "BAD": 0,
+        "SAT": 1,
+        "INTRP": 2,
+        "CR": 3,
+        "EDGE": 4,
+    }
+    masker = DictionaryMasker(mask_bits_dict, ["BAD", "EDGE"])
+    return bench_image_masker(masker, set_up_image_stack())
+
+
+def bench_threshold_masker():
+    masker = ThresholdMask(100.0)
+    return bench_image_masker(masker, set_up_image_stack())
+
+
+def bench_bit_vector_masker():
+    masker = BitVectorMasker(1, [])
+    return bench_image_masker(masker, set_up_image_stack())
+
+
+def bench_cpp_bit_vector():
+    stack = set_up_image_stack()
+    tmr = timeit.Timer(stmt="stack.apply_mask_flags(1, [])", globals=locals())
+    res_time = np.mean(tmr.repeat(repeat=50, number=1))
+    return res_time
+
+
+def bench_cpp_threshold():
+    stack = set_up_image_stack()
+    tmr = timeit.Timer(stmt="stack.apply_mask_threshold(100.0)", globals=locals())
+    res_time = np.mean(tmr.repeat(repeat=50, number=1))
+    return res_time
+
+
+def bench_grow_mask(r):
+    res_times = []
+
+    # We run the loop outside because we need to reset the stack each time
+    # and we do not want that to be included in the cost.
+    for i in range(10):
+        stack = set_up_image_stack()
+        premasker = BitVectorMasker(1, [])
+        premasker.apply_mask(stack)
+
+        grow_masker = GrowMask(r)
+        res_times.append(timeit.timeit("grow_masker.apply_mask(stack)", number=1, globals=locals()))
+    return np.mean(np.array(res_times))
+
+
+def bench_grow_mask_cpp(r):
+    res_times = []
+
+    # We run the loop outside because we need to reset the stack each time
+    # and we do not want that to be included in the cost.
+    for i in range(10):
+        stack = set_up_image_stack()
+        premasker = BitVectorMasker(1, [])
+        premasker.apply_mask(stack)
+
+        res_times.append(timeit.timeit("stack.grow_mask(r)", number=1, globals=locals()))
+    return np.mean(np.array(res_times))
+
+
+def run_all_benchmarks():
+    print("Apply Mask Timings (ave of 50 repetitions):")
+    print("    Method       | Time (sec)")
+    print("-" * 30)
+    print(f" Python Dict     | {bench_dictionary_masker():10.7f}")
+    print(f" Python Bit Vect | {bench_bit_vector_masker():10.7f}")
+    print(f" C++ Bit Vect    | {bench_cpp_bit_vector():10.7f}")
+    print(f" Python Thresh   | {bench_threshold_masker():10.7f}")
+    print(f" C++ Thresh      | {bench_cpp_threshold():10.7f}")
+
+    print("\n\nGrow Mask Timings (ave of 10 repetitions):")
+    print("r |  Python (sec) |  C++ (sec)")
+    print("-" * 30)
+    for r in range(1, 5):
+        print(f"{r} | {bench_grow_mask(r):10.7f}    | {bench_grow_mask_cpp(r):10.7f}")
+
+
+if __name__ == "__main__":
+    run_all_benchmarks()

docs/source/api_reference/index.rst

@@ -9,7 +9,6 @@ Object Search
 
    run_search_referenceapi
    search_referenceapi
-   image_info
 
 
 Filtering Results

docs/source/api_reference/search_referenceapi.rst

@@ -3,5 +3,4 @@ Module: search
 
 .. automodule:: kbmod.search
    :members:
-   :undoc-members:
    :show-inheritance:

docs/source/index.rst

@@ -18,11 +18,9 @@ KBMOD (Kernel Based Moving Object Detection) is a GPU-accelerated framework for
         :img-top: _static/getting_started.svg
 
         Getting Started
-	^^^^^^^^^^^^^^^
-
-        Just found out about KBMOD? Crash course to what KBMOD can do,
-	guided through Jupyter Notebooks. Recommended to anyone looking
-	to see KBMOD in action.
+        ^^^^^^^^^^^^^^^
+
+        Just found out about KBMOD? Crash course to what KBMOD can do, guided through Jupyter Notebooks. Recommended to anyone looking to see KBMOD in action.
 
         +++
 
@@ -39,8 +37,7 @@ KBMOD (Kernel Based Moving Object Detection) is a GPU-accelerated framework for
         User Manual
         ^^^^^^^^^^^
 
-	An in-depth guide through the basic concepts used by KBMOD. Recommended
-	to anyone looking to use KBMOD in their work. 
+        An in-depth guide through the basic concepts used by KBMOD. Recommended to anyone looking to use KBMOD in their work.
 
         +++
 
@@ -57,10 +54,7 @@ KBMOD (Kernel Based Moving Object Detection) is a GPU-accelerated framework for
         API Reference
         ^^^^^^^^^^^^^
 
-        The API reference guide contains a detailed description of the functions,
-        modules, and objects included in KBMOD, which parameters to use and what
-	to expect as a returned value. For those interested in contributing, or
-	using KBMOD in their own work.
+        The API reference guide contains a detailed description of the functions, modules, and objects included in KBMOD, which parameters to use and what to expect as a returned value. For those interested in contributing, or using KBMOD in their own work.
 
         +++
 
@@ -74,11 +68,10 @@ KBMOD (Kernel Based Moving Object Detection) is a GPU-accelerated framework for
     .. grid-item-card::
         :img-top: _static/contributor.svg
 
-        Contributors 
+        Contributors
         ^^^^^^^^^^^^
 
-        Want to cite KBMOD? See changelog or release history? Nuts and bolts
-	of KBMOD mainly intended for developers and contributors to KBMOD. 
+        Want to cite KBMOD? See changelog or release history? Nuts and bolts of KBMOD mainly intended for developers and contributors to KBMOD.
 
         +++
 
@@ -89,7 +82,7 @@ KBMOD (Kernel Based Moving Object Detection) is a GPU-accelerated framework for
 
             To the developers pages
 
-	
+
 Indices and tables
 ------------------
 
@@ -103,23 +96,23 @@ Indices and tables
 
     .. toctree::
        :maxdepth: 1
-	
+
        user_manual/index
 
     .. toctree::
        :maxdepth: 1
-	      
+
        examples/index
-	
-	
+
+
     .. toctree::
        :maxdepth: 1
-		      
+
        api_reference/index
-	
-	
+
+
     .. toctree::
        :maxdepth: 1
-	
+
        project_details/index
 

notebooks/KBMOD_Demo.ipynb

@@ -1,7 +1,6 @@
 {
  "cells": [
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -185,8 +184,8 @@
     "    \"average_angle\": 0.0,\n",
     "}\n",
     "\n",
-    "rs = run_search(input_parameters)\n",
-    "rs.run_search()"
+    "rs = SearchRunner()\n",
+    "rs.run_search(input_parameters)"
    ]
   },
   {