spectre-core 0.0.8__py3-none-any.whl → 0.0.10__py3-none-any.whl

spectre_core/receivers/gr/_test.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+#
+# SPDX-License-Identifier: GPL-3.0
+#
+# GNU Radio Python Flow Graph
+# Title: Test receiver
+# GNU Radio version: 3.10.1.1
+
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+#
+# Test receiver top blocks
+#
+
+from functools import partial
+from dataclasses import dataclass
+
+from gnuradio import gr
+from gnuradio import blocks
+from gnuradio import spectre
+from gnuradio import analog
+
+from spectre_core.capture_configs import Parameters, PNames
+from spectre_core.config import get_chunks_dir_path
+from ._base import capture
+
+
+class _cosine_signal_1(gr.top_block):
+    def __init__(self, 
+                 tag: str,
+                 parameters: Parameters):
+        gr.top_block.__init__(self, "cosine-signal-1", catch_exceptions=True)
+
+        ##################################################
+        # Unpack capture config
+        ##################################################
+        samp_rate   = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+        batch_size  = parameters.get_parameter_value(PNames.BATCH_SIZE)
+        frequency   = parameters.get_parameter_value(PNames.FREQUENCY)
+        amplitude   = parameters.get_parameter_value(PNames.AMPLITUDE)
+
+        ##################################################
+        # Blocks
+        ##################################################
+        self.spectre_batched_file_sink_0 = spectre.batched_file_sink(get_chunks_dir_path(), 
+                                                                     tag, 
+                                                                     batch_size, 
+                                                                     samp_rate)
+        self.blocks_throttle_0_1 = blocks.throttle(gr.sizeof_float*1, 
+                                                   samp_rate,
+                                                   True)
+        self.blocks_throttle_0 = blocks.throttle(gr.sizeof_float*1, 
+                                                 samp_rate,
+                                                 True)
+        self.blocks_null_source_1 = blocks.null_source(gr.sizeof_float*1)
+        self.blocks_float_to_complex_1 = blocks.float_to_complex(1)
+        self.analog_sig_source_x_0 = analog.sig_source_f(samp_rate, 
+                                                         analog.GR_COS_WAVE, 
+                                                         frequency, 
+                                                         amplitude, 
+                                                         0, 
+                                                         0)
+
+
+        ##################################################
+        # Connections
+        ##################################################
+        self.connect((self.analog_sig_source_x_0, 0), (self.blocks_throttle_0, 0))
+        self.connect((self.blocks_float_to_complex_1, 0), (self.spectre_batched_file_sink_0, 0))
+        self.connect((self.blocks_null_source_1, 0), (self.blocks_throttle_0_1, 0))
+        self.connect((self.blocks_throttle_0, 0), (self.blocks_float_to_complex_1, 0))
+        self.connect((self.blocks_throttle_0_1, 0), (self.blocks_float_to_complex_1, 1))
+
+
+class _tagged_staircase(gr.top_block):
+    def __init__(self, 
+                 tag: str,
+                 parameters: Parameters):
+        gr.top_block.__init__(self, "tagged-staircase", catch_exceptions=True)
+
+        ##################################################
+        # Unpack capture config
+        ##################################################
+        step_increment       = parameters.get_parameter_value(PNames.STEP_INCREMENT)
+        samp_rate            = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+        min_samples_per_step = parameters.get_parameter_value(PNames.MIN_SAMPLES_PER_STEP)
+        max_samples_per_step = parameters.get_parameter_value(PNames.MAX_SAMPLES_PER_STEP)
+        frequency_step       = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
+        batch_size           = parameters.get_parameter_value(PNames.BATCH_SIZE)
+
+        ##################################################
+        # Blocks
+        ##################################################
+        self.spectre_tagged_staircase_0 = spectre.tagged_staircase(min_samples_per_step, 
+                                                                   max_samples_per_step, 
+                                                                   frequency_step,
+                                                                   step_increment, 
+                                                                   samp_rate)
+        self.spectre_batched_file_sink_0 = spectre.batched_file_sink(get_chunks_dir_path(),
+                                                                     tag, 
+                                                                     batch_size, 
+                                                                     samp_rate, 
+                                                                     True,
+                                                                     'rx_freq',
+                                                                     0) # zero means the center frequency is unset
+        self.blocks_throttle_0 = blocks.throttle(gr.sizeof_gr_complex*1, samp_rate, True)
+
+
+        ##################################################
+        # Connections
+        ##################################################
+        self.connect((self.blocks_throttle_0, 0), (self.spectre_batched_file_sink_0, 0))
+        self.connect((self.spectre_tagged_staircase_0, 0), (self.blocks_throttle_0, 0))
+
+
+@dataclass(frozen=True)
+class CaptureMethods:
+    cosine_signal_1  = partial(capture, top_block_cls=_cosine_signal_1)
+    tagged_staircase = partial(capture, top_block_cls=_tagged_staircase)

spectre_core/receivers/library/_rsp1a.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Optional
+from dataclasses import dataclass
+from functools import partial
+
+from spectre_core.capture_configs import (
+    CaptureModes
+)
+from ..gr._rsp1a import CaptureMethods
+from .._spec_names import SpecNames
+from .._base import SDRPlayReceiver
+from .._register import register_receiver
+
+@dataclass
+class Modes:
+    FIXED_CENTER_FREQUENCY  = CaptureModes.FIXED_CENTER_FREQUENCY
+    SWEPT_CENTER_FREQUENCY  = CaptureModes.SWEPT_CENTER_FREQUENCY
+
+@register_receiver("rsp1a")
+class _Receiver(SDRPlayReceiver):
+    def __init__(self, 
+                 name: str,
+                 mode: Optional[str]):
+        super().__init__(name,
+                         mode)
+        
+
+    def _add_specs(self) -> None:
+        self.add_spec( SpecNames.SAMPLE_RATE_LOWER_BOUND, 200e3     ) # Hz
+        self.add_spec( SpecNames.SAMPLE_RATE_UPPER_BOUND, 10e6      ) # Hz
+        self.add_spec( SpecNames.FREQUENCY_LOWER_BOUND  , 1e3       ) # Hz
+        self.add_spec( SpecNames.FREQUENCY_UPPER_BOUND  , 2e9       ) # Hz
+        self.add_spec( SpecNames.IF_GAIN_UPPER_BOUND    , -20       ) # dB
+        self.add_spec( SpecNames.RF_GAIN_UPPER_BOUND    , 0         ) # dB
+        self.add_spec( SpecNames.API_RETUNING_LATENCY   , 50 * 1e-3 ) # s
+        self.add_spec( SpecNames.BANDWIDTH_OPTIONS, 
+                      [200000, 300000, 600000, 1536000, 5000000, 6000000, 7000000, 8000000])
+
+
+    def _add_capture_methods(self) -> None:
+        self.add_capture_method(Modes.FIXED_CENTER_FREQUENCY, 
+                                CaptureMethods.fixed_center_frequency)
+        self.add_capture_method(Modes.SWEPT_CENTER_FREQUENCY,
+                                CaptureMethods._swept_center_frequency)
+    
+
+    def _add_capture_templates(self):
+        self.add_capture_template(Modes.FIXED_CENTER_FREQUENCY,
+                                  self._get_capture_template_fixed_center_frequency())
+        self.add_capture_template(Modes.SWEPT_CENTER_FREQUENCY,
+                                  self._get_capture_template_swept_center_frequency())
+        
+    
+    def _add_pvalidators(self):
+        self.add_pvalidator(CaptureModes.FIXED_CENTER_FREQUENCY,
+                            self._get_pvalidator_fixed_center_frequency())
+        self.add_pvalidator(CaptureModes.SWEPT_CENTER_FREQUENCY,
+                            self._get_pvalidator_swept_center_frequency())

spectre_core/receivers/library/_test.py

@@ -0,0 +1,221 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from dataclasses import dataclass
+from typing import Optional, Callable
+
+from spectre_core.capture_configs import (
+    CaptureTemplate, CaptureModes, Parameters, Bound, PValidators, PNames,
+    get_base_capture_template, make_base_capture_template, get_base_ptemplate
+)
+from ..gr._test import CaptureMethods
+from .._spec_names import SpecNames
+from .._base import BaseReceiver
+from .._register import register_receiver
+
+
+@dataclass
+class Modes:
+    COSINE_SIGNAL_1  = "cosine-signal-1"
+    TAGGED_STAIRCASE = "tagged-staircase"
+
+
+@register_receiver("test")
+class _Receiver(BaseReceiver):
+    def __init__(self, 
+                 name: str,
+                 mode: Optional[str]):
+        super().__init__(name,
+                         mode)
+        
+
+    def _add_specs(self) -> None:
+        self.add_spec( SpecNames.SAMPLE_RATE_LOWER_BOUND, 64000  )
+        self.add_spec( SpecNames.SAMPLE_RATE_UPPER_BOUND, 640000 )
+        self.add_spec( SpecNames.FREQUENCY_LOWER_BOUND  , 16000  )
+        self.add_spec( SpecNames.FREQUENCY_UPPER_BOUND  , 160000 )
+
+
+    def _add_capture_methods(self) -> None:
+        self.add_capture_method( Modes.COSINE_SIGNAL_1 , CaptureMethods.cosine_signal_1 )
+        self.add_capture_method( Modes.TAGGED_STAIRCASE, CaptureMethods.tagged_staircase)
+    
+
+    def _add_pvalidators(self) -> None:
+        self.add_pvalidator( Modes.COSINE_SIGNAL_1 , self.__get_pvalidator_cosine_signal_1()  )
+        self.add_pvalidator( Modes.TAGGED_STAIRCASE, self.__get_pvalidator_tagged_staircase() )
+
+
+    def _add_capture_templates(self) -> None:
+        self.add_capture_template( Modes.COSINE_SIGNAL_1 , self.__get_capture_template_cosine_signal_1()  )
+        self.add_capture_template( Modes.TAGGED_STAIRCASE, self.__get_capture_template_tagged_staircase() )
+        
+
+    def __get_capture_template_cosine_signal_1(self) -> CaptureTemplate:
+        #
+        # Create the base template
+        #
+        capture_template = get_base_capture_template( CaptureModes.FIXED_CENTER_FREQUENCY )
+        capture_template.add_ptemplate( get_base_ptemplate(PNames.AMPLITUDE) )
+        capture_template.add_ptemplate( get_base_ptemplate(PNames.FREQUENCY) )
+
+        #
+        # Update the defaults
+        #
+        capture_template.set_defaults(
+            (PNames.BATCH_SIZE,            3.0),
+            (PNames.CENTER_FREQUENCY,      16000),
+            (PNames.AMPLITUDE,             2.0),
+            (PNames.FREQUENCY,             32000),
+            (PNames.SAMPLE_RATE,           128000),
+            (PNames.WINDOW_HOP,            512),
+            (PNames.WINDOW_SIZE,           512),
+            (PNames.WINDOW_TYPE,           "boxcar")
+        )
+
+        #
+        # Enforce defaults
+        #
+        capture_template.enforce_defaults(
+            PNames.TIME_RESOLUTION,
+            PNames.TIME_RANGE,
+            PNames.FREQUENCY_RESOLUTION,
+            PNames.WINDOW_TYPE
+        )
+
+
+        #
+        # Adding pconstraints
+        #
+        capture_template.add_pconstraint(
+            PNames.SAMPLE_RATE,
+            [
+                Bound(
+                    lower_bound=self.get_spec(SpecNames.SAMPLE_RATE_LOWER_BOUND),
+                    upper_bound=self.get_spec(SpecNames.SAMPLE_RATE_UPPER_BOUND)
+                )
+            ]
+        )
+        capture_template.add_pconstraint(
+            PNames.FREQUENCY,
+            [
+                Bound(
+                    lower_bound=self.get_spec(SpecNames.FREQUENCY_LOWER_BOUND),
+                    upper_bound=self.get_spec(SpecNames.FREQUENCY_UPPER_BOUND)
+                )
+            ]
+        )
+        return capture_template
+
+
+    def __get_capture_template_tagged_staircase(self) -> CaptureTemplate:
+        #
+        # Make the base template
+        #
+        capture_template = make_base_capture_template(
+                PNames.TIME_RESOLUTION,
+                PNames.FREQUENCY_RESOLUTION,
+                PNames.TIME_RANGE,
+                PNames.SAMPLE_RATE,
+                PNames.BATCH_SIZE,
+                PNames.WINDOW_TYPE,
+                PNames.WINDOW_HOP,
+                PNames.WINDOW_SIZE,
+                PNames.EVENT_HANDLER_KEY,
+                PNames.CHUNK_KEY,
+                PNames.WATCH_EXTENSION,
+                PNames.MIN_SAMPLES_PER_STEP,
+                PNames.MAX_SAMPLES_PER_STEP,
+                PNames.FREQUENCY_STEP,
+                PNames.STEP_INCREMENT,
+                PNames.OBS_ALT,
+                PNames.OBS_LAT,
+                PNames.OBS_LON,
+                PNames.OBJECT,
+                PNames.ORIGIN,
+                PNames.TELESCOPE,
+                PNames.INSTRUMENT
+        )
+
+        #
+        # Update the defaults
+        #
+        capture_template.set_defaults(
+            (PNames.BATCH_SIZE,            3.0),
+            (PNames.FREQUENCY_STEP,        128000),
+            (PNames.MAX_SAMPLES_PER_STEP,  5000),
+            (PNames.MIN_SAMPLES_PER_STEP,  4000),
+            (PNames.SAMPLE_RATE,           128000),
+            (PNames.STEP_INCREMENT,        200),
+            (PNames.WINDOW_HOP,            512),
+            (PNames.WINDOW_SIZE,           512),
+            (PNames.WINDOW_TYPE,           "boxcar"),
+            (PNames.EVENT_HANDLER_KEY,     CaptureModes.SWEPT_CENTER_FREQUENCY),
+            (PNames.CHUNK_KEY,             CaptureModes.SWEPT_CENTER_FREQUENCY),
+            (PNames.WATCH_EXTENSION,       "bin")
+        )
+
+
+        #
+        # Enforce defaults
+        #
+        capture_template.enforce_defaults(
+            PNames.TIME_RESOLUTION,
+            PNames.TIME_RANGE,
+            PNames.FREQUENCY_RESOLUTION,
+            PNames.WINDOW_TYPE,
+            PNames.EVENT_HANDLER_KEY,
+            PNames.CHUNK_KEY,
+            PNames.WATCH_EXTENSION
+        )
+
+        return capture_template
+    
+    
+    def __get_pvalidator_cosine_signal_1(self) -> Callable:
+        def pvalidator(parameters: Parameters):
+            PValidators.window(parameters)
+
+            sample_rate          = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+            frequency            = parameters.get_parameter_value(PNames.FREQUENCY)
+            window_size          = parameters.get_parameter_value(PNames.WINDOW_SIZE)
+
+            # check that the sample rate is an integer multiple of the underlying signal frequency
+            if sample_rate % frequency != 0:
+                raise ValueError("The sampling rate must be some integer multiple of frequency")
+
+            a = sample_rate/frequency
+            if a < 2:
+                raise ValueError((f"The ratio of sampling rate over frequency must be greater than two. "
+                                f"Got {a}"))
+            
+            # analytical requirement
+            # if p is the number of sampled cycles, we can find that p = window_size / a
+            # the number of sampled cycles must be a positive natural number.
+            p = window_size / a
+            if window_size % a != 0:
+                raise ValueError((f"The number of sampled cycles must be a positive natural number. "
+                                  f"Computed that p={p}"))
+        return pvalidator
+
+
+    def __get_pvalidator_tagged_staircase(self) -> None:
+        def pvalidator(parameters: Parameters):
+            PValidators.window(parameters)
+
+            freq_step            = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
+            sample_rate          = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+            min_samples_per_step = parameters.get_parameter_value(PNames.MIN_SAMPLES_PER_STEP)
+            max_samples_per_step = parameters.get_parameter_value(PNames.MAX_SAMPLES_PER_STEP)
+
+            if freq_step != sample_rate:
+                raise ValueError(f"The frequency step must be equal to the sampling rate")
+            
+            
+            if min_samples_per_step > max_samples_per_step:
+                raise ValueError((f"Minimum samples per step cannot be greater than the maximum samples per step. "
+                                f"Got {min_samples_per_step}, which is greater than {max_samples_per_step}"))
+            
+        return pvalidator
+        

spectre_core/spectrograms/__init__.py

@@ -1,3 +1,21 @@
 # SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
+
+from ._analytical import (
+    get_analytical_spectrogram, validate_analytically, TestResults
+)
+from ._spectrogram import (
+    Spectrogram, FrequencyCut, TimeCut, SpectrumTypes, TimeTypes
+)
+from ._transform import (
+    frequency_chop, time_chop, frequency_average, time_average, 
+    join_spectrograms
+)
+
+__all__ = [
+    "get_analytical_spectrogram", "validate_analytically", "TestResults",
+    "Spectrogram", "FrequencyCut", "TimeCut", "SpectrumTypes", "frequency_chop",
+    "time_chop", "frequency_average","time_average", "join_spectrograms",
+    "TimeTypes"
+]

spectre_core/spectrograms/{analytical.py → _analytical.py}

@@ -2,17 +2,21 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from typing import Callable, Any
+from typing import Callable
 from dataclasses import dataclass
 
 import numpy as np
 
-from spectre_core.file_handlers.configs import CaptureConfig
-from spectre_core.spectrograms.spectrogram import Spectrogram
-from spectre_core.spectrograms.array_operations import is_close
+from spectre_core.capture_configs import CaptureConfig, PNames
 from spectre_core.exceptions import ModeNotFoundError
+from ._spectrogram import Spectrogram
+from ._array_operations import is_close
 
-
+__all__ = [
+    "get_analytical_spectrogram",
+    "validate_analytically",
+    "TestResults"
+]
 
 @dataclass
 class TestResults:
@@ -36,7 +40,7 @@ class TestResults:
         return len(self.spectrum_validated) - self.num_validated_spectrums
     
 
-    def jsonify(self) -> dict[str, Any]:
+    def to_dict(self) -> dict[str, bool | dict[float, bool]]:
         return {
             "times_validated": self.times_validated,
             "frequencies_validated": self.frequencies_validated,
@@ -72,14 +76,13 @@ class _AnalyticalFactory:
         by parameters in the corresponding capture config and the number of spectrums
         in the output spectrogram.
         """
-        receiver_name, test_mode = capture_config['receiver'], capture_config['mode']
 
-        if receiver_name != "test":
+        if capture_config.receiver_name != "test":
             raise ValueError(f"Input capture config must correspond to the test receiver")
         
-        builder_method = self.builders.get(test_mode)
+        builder_method = self.builders.get(capture_config.receiver_mode)
         if builder_method is None:
-            raise ModeNotFoundError(f"Test mode not found. Expected one of {self.test_modes}, but received {test_mode}")
+            raise ModeNotFoundError(f"Test mode not found. Expected one of {self.test_modes}, but received {capture_config.receiver_mode}")
         return builder_method(num_spectrums, 
                               capture_config)
     
@@ -88,14 +91,14 @@ class _AnalyticalFactory:
                         num_spectrums: int,
                         capture_config: CaptureConfig) -> Spectrogram:
         # Extract necessary parameters from the capture configuration.
-        window_size = capture_config['window_size']
-        samp_rate = capture_config['samp_rate']
-        amplitude = capture_config['amplitude']
-        frequency = capture_config['frequency']
-        hop = capture_config['hop']
-
+        window_size      = capture_config.get_parameter_value(PNames.WINDOW_SIZE)
+        sample_rate      = capture_config.get_parameter_value(PNames.SAMPLE_RATE)
+        amplitude        = capture_config.get_parameter_value(PNames.AMPLITUDE)
+        frequency        = capture_config.get_parameter_value(PNames.FREQUENCY)
+        window_hop       = capture_config.get_parameter_value(PNames.WINDOW_HOP)
+        center_frequency = capture_config.get_parameter_value(PNames.CENTER_FREQUENCY)
         # Calculate derived parameters a (sampling rate ratio) and p (sampled periods).
-        a = int(samp_rate / frequency)
+        a = int(sample_rate / frequency)
         p = int(window_size / a)
 
         # Create the analytical spectrum, which is constant in time.
@@ -111,11 +114,11 @@ class _AnalyticalFactory:
         analytical_dynamic_spectra = np.ones((window_size, num_spectrums)) * spectrum[:, np.newaxis]
 
         # Compute time array.
-        sampling_interval = 1 / samp_rate
-        times = np.arange(num_spectrums) * hop * sampling_interval
+        sampling_interval = 1 / sample_rate
+        times = np.arange(num_spectrums) * window_hop * sampling_interval
 
         # compute the frequency array.
-        frequencies = np.fft.fftshift(np.fft.fftfreq(window_size, sampling_interval))
+        frequencies = np.fft.fftshift(np.fft.fftfreq(window_size, sampling_interval)) + center_frequency
 
         # Return the spectrogram.
         return Spectrogram(analytical_dynamic_spectra,
@@ -129,11 +132,11 @@ class _AnalyticalFactory:
                         num_spectrums: int,
                         capture_config: CaptureConfig) -> Spectrogram:
         # Extract necessary parameters from the capture configuration.
-        window_size = capture_config['window_size']
-        min_samples_per_step = capture_config['min_samples_per_step']
-        max_samples_per_step = capture_config['max_samples_per_step']
-        step_increment = capture_config['step_increment']
-        samp_rate = capture_config['samp_rate']
+        window_size          = capture_config.get_parameter_value(PNames.WINDOW_SIZE)
+        min_samples_per_step = capture_config.get_parameter_value(PNames.MIN_SAMPLES_PER_STEP)
+        max_samples_per_step = capture_config.get_parameter_value(PNames.MAX_SAMPLES_PER_STEP)
+        step_increment       = capture_config.get_parameter_value(PNames.STEP_INCREMENT)
+        samp_rate            = capture_config.get_parameter_value(PNames.SAMPLE_RATE)
 
         # Calculate step sizes and derived parameters.
         num_samples_per_step = np.arange(min_samples_per_step, max_samples_per_step + 1, step_increment)
@@ -152,11 +155,10 @@ class _AnalyticalFactory:
 
         # Compute time array
         num_samples_per_sweep = sum(num_samples_per_step)
-        midpoint_sample = sum(num_samples_per_step) // 2
         sampling_interval = 1 / samp_rate
         # compute the sample index we are "assigning" to each spectrum
         # and multiply by the sampling interval to get the equivalent physical time
-        times = np.array([ midpoint_sample + (i * num_samples_per_sweep) for i in range(num_spectrums) ]) * sampling_interval
+        times = np.array([(i * num_samples_per_sweep) for i in range(num_spectrums) ]) * sampling_interval
 
         # Compute the frequency array
         baseband_frequencies = np.fft.fftshift(np.fft.fftfreq(window_size, sampling_interval))

spectre_core/spectrograms/{array_operations.py → _array_operations.py}

@@ -6,6 +6,53 @@ from datetime import datetime
 
 import numpy as np
 
+def average_array(array: np.ndarray, average_over: int, axis=0) -> np.ndarray:
+
+    # Check if average_over is an integer
+    if type(average_over) != int:
+        raise TypeError(f"average_over must be an integer. Got {type(average_over)}")
+
+    # Get the size of the specified axis which we will average over
+    axis_size = array.shape[axis]
+    # Check if average_over is within the valid range
+    if not 1 <= average_over <= axis_size:
+        raise ValueError(f"average_over must be between 1 and the length of the axis ({axis_size})")
+    
+    max_axis_index = len(np.shape(array)) - 1
+    if axis > max_axis_index: # zero indexing on specifying axis, so minus one
+        raise ValueError(f"Requested axis is out of range of array dimensions. Axis: {axis}, max axis index: {max_axis_index}")
+
+    # find the number of elements in the requested axis
+    num_elements = array.shape[axis]
+
+    # find the number of "full blocks" to average over
+    num_full_blocks = num_elements // average_over
+    # if num_elements is not exactly divisible by average_over, we will have some elements left over
+    # these remaining elements will be padded with nans to become another full block
+    remainder = num_elements % average_over
+    
+    # if there exists a remainder, pad the last block
+    if remainder != 0:
+        # initialise an array to hold the padding shape
+        padding_shape = [(0, 0)] * array.ndim
+        # pad after the last column in the requested axis
+        padding_shape[axis] = (0, average_over - remainder)
+        # pad with nan values (so to not contribute towards the mean computation)
+        array = np.pad(array, padding_shape, mode='constant', constant_values=np.nan)
+    
+    # initalise a list to hold the new shape
+    new_shape = list(array.shape)
+    # update the shape on the requested access (to the number of blocks we will average over)
+    new_shape[axis] = num_full_blocks + (1 if remainder else 0)
+    # insert a new dimension, with the size of each block
+    new_shape.insert(axis + 1, average_over)
+    # and reshape the array to sort the array into the relevant blocks.
+    reshaped_array = array.reshape(new_shape)
+    # average over the newly created axis, essentially averaging over the blocks.
+    averaged_array = np.nanmean(reshaped_array, axis=axis + 1)
+    # return the averaged array
+    return averaged_array
+
 
 def is_close(ar: np.ndarray, 
              ar_comparison: np.ndarray,
@@ -15,7 +62,6 @@ def is_close(ar: np.ndarray,
                              ar_comparison, 
                              atol=absolute_tolerance))
 
-
 def find_closest_index(
     target_value: float | datetime, 
     array: np.ndarray,