"""
A high-level, object-oriented Python library for controlling Spectrum Instrumentation devices.

`spectrumdevice` can connect to individual cards or
[StarHubs](https://spectrum-instrumentation.com/en/m4i-star-hub) (e.g. the
[NetBox](https://spectrum-instrumentation.com/en/digitizernetbox)). `spectrumdevice` provides the following classes
for controlling devices:

### Hardware Classes
| Name                             | Purpose                                                 |
|----------------------------------|---------------------------------------------------------|
| `SpectrumDigitiserCard`          | Controlling individual digitiser cards                  |
| `SpectrumDigitiserStarHub`       | Controlling digitiser cards aggregated with a StarHub   |
| `SpectrumDigitiserAnalogChannel` | Controlling analog channels of a digitiser              |
| `SpectrumDigitiserIOLine`        | Controlling multipurpose IO lines of a digitiser        |
| `SpectrumAWGCard`                | Controlling individual AWG cards                        |
| `SpectrumAWGStarHub`             | (not yet implemented)                                   |
| `SpectrumAWGAnalogChannel`       | Controlling analog channels of an AWG                   |
| `SpectrumAWGIOLine`              | Controlling multipurpose IO lines of an AWG             |
| `PulseGenerator`                 | Controlling pulse generators belonging to IO lines      |

### Mock Classes
`spectrumdevice` also includes mock classes for testing software without drivers installed or hardware connected:

| Name                           | Purpose                                             |
|--------------------------------|-----------------------------------------------------|
| `MockSpectrumDigitiserCard`    | Mocking individual digitiser cards                  |
| `MockSpectrumDigitiserStarHub` | Mocking digitiser cards aggregated with a StarHub   |
| `MockSpectrumAWGCard`          | Mocking individual AWG cards                        |
| `MockSpectrumAWGStarHub`       | Mocking AWG cards aggregated with a StarHub         |

### Abstract Classes
The following abstract classes provide common implementations for methods whose functionality is identical across
different Spectrum devices. They cannot be instantiated themselves, but are included here as they contain
documentation for methods inherited by the concrete (and therefore instantiatable) classes above.

| Name                           | Purpose                                             |
|--------------------------------|-----------------------------------------------------|
| `AbstractSpectrumDevice`       | Implements methods common to all devices            |
| `AbstractSpectrumCard`         | Implements methods common to all card               |
| `AbstractSpectrumStarHub`      | Implements methods common to all hubs               |
| `AbstractSpectrumChannel`      | Implements methods common to all channels           |
| `AbstractSpectrumDigitiser`    | Implements methods common to all digitisers         |
| `AbstractSpectrumAWG`          | Implements methods common to all AWGs               |

### Settings
The submodule `spectrumdevice.settings` provides Enums and Dataclasses wrapping the register values provided by the
Spectrum API, to be used for configuring hardware and interpreting responses received from hardware.

### Resources
* [Source on GitHub](https://github.com/KCL-BMEIS/spectrumdevice)
* [README including quickstart](https://github.com/KCL-BMEIS/spectrumdevice/blob/main/README.md)
* [Examples](https://github.com/KCL-BMEIS/spectrumdevice/tree/main/example_scripts)
* [PyPi](https://pypi.org/project/spectrumdevice/)
* [API reference documentation](https://kcl-bmeis.github.io/spectrumdevice/)

### Reference Documentation
"""

# Christian Baker, King's College London
# Copyright (c) 2021 School of Biomedical Engineering & Imaging Sciences, King's College London
# Licensed under the MIT. You may obtain a copy at https://opensource.org/licenses/MIT.

from .measurement import Measurement
from .devices.digitiser.digitiser_card import SpectrumDigitiserCard
from .devices.digitiser.digitiser_channel import SpectrumDigitiserAnalogChannel, SpectrumDigitiserIOLine
from .devices.digitiser.digitiser_star_hub import SpectrumDigitiserStarHub
from .devices.awg.awg_card import SpectrumAWGCard
from .devices.awg.awg_channel import SpectrumAWGAnalogChannel, SpectrumAWGIOLine
from .devices.mocks import MockSpectrumDigitiserCard, MockSpectrumDigitiserStarHub, MockSpectrumAWGCard
from .devices.abstract_device import (
    AbstractSpectrumDevice,
    AbstractSpectrumCard,
    AbstractSpectrumChannel,
    AbstractSpectrumStarHub,
)
from .devices.digitiser.abstract_spectrum_digitiser import AbstractSpectrumDigitiser
from .features.pulse_generator.pulse_generator import PulseGenerator

__all__ = [
    "SpectrumDigitiserAnalogChannel",
    "SpectrumDigitiserIOLine",
    "SpectrumDigitiserCard",
    "SpectrumDigitiserStarHub",
    "MockSpectrumDigitiserCard",
    "MockSpectrumDigitiserStarHub",
    "AbstractSpectrumDigitiser",
    "AbstractSpectrumStarHub",
    "AbstractSpectrumCard",
    "AbstractSpectrumDevice",
    "AbstractSpectrumChannel",
    "settings",
    "features",
    "Measurement",
    "SpectrumAWGCard",
    "MockSpectrumAWGCard",
    "SpectrumAWGAnalogChannel",
    "SpectrumAWGIOLine",
    "PulseGenerator",
]


from . import _version

__version__ = _version.get_versions()["version"]  # type: ignore

class SpectrumDigitiserAnalogChannel(AbstractSpectrumAnalogChannel, SpectrumDigitiserAnalogChannelInterface):
    """Class for controlling an individual channel of a spectrum digitiser. Channels are constructed automatically when
    a `SpectrumDigitiserCard` or `SpectrumDigitiserStarHub` is instantiated, and can then be accessed via the
    `.channels` property."""

    def __init__(self, channel_number: int, parent_device: SpectrumDigitiserInterface) -> None:

        if parent_device.type != CardType.SPCM_TYPE_AI:
            raise SpectrumCardIsNotADigitiser(parent_device.type)

        # pass unused args up the inheritance hierarchy
        super().__init__(channel_number=channel_number, parent_device=parent_device)

        self._full_scale_value = self._parent_device.read_spectrum_device_register(SPC_MIINST_MAXADCVALUE)
        # used frequently so store locally instead of reading from device each time:
        self._vertical_range_mv = self.vertical_range_in_mv
        self._vertical_offset_in_percent = self.vertical_offset_in_percent

    def _get_settings_as_dict(self) -> dict:
        return {
            SpectrumDigitiserAnalogChannel.input_path.__name__: self.input_path,
            SpectrumDigitiserAnalogChannel.input_coupling.__name__: self.input_coupling,
            SpectrumDigitiserAnalogChannel.input_impedance.__name__: self.input_impedance,
            SpectrumDigitiserAnalogChannel.vertical_range_in_mv.__name__: self.vertical_range_in_mv,
            SpectrumDigitiserAnalogChannel.vertical_offset_in_percent.__name__: self.vertical_offset_in_percent,
        }

    def _set_settings_from_dict(self, settings: dict) -> None:
        self.set_input_path(settings[SpectrumDigitiserAnalogChannel.input_path.__name__])
        self.set_input_coupling(settings[SpectrumDigitiserAnalogChannel.input_coupling.__name__])
        self.set_input_impedance(settings[SpectrumDigitiserAnalogChannel.input_impedance.__name__])
        self.set_vertical_range_in_mv(settings[SpectrumDigitiserAnalogChannel.vertical_range_in_mv.__name__])
        self.set_vertical_offset_in_percent(
            settings[SpectrumDigitiserAnalogChannel.vertical_offset_in_percent.__name__]
        )

    def convert_raw_waveform_to_voltage_waveform(self, raw_waveform: ndarray) -> ndarray:
        vertical_offset_mv = 0.01 * float(self._vertical_range_mv * self._vertical_offset_in_percent)
        return 1e-3 * (
            float(self._vertical_range_mv) * raw_waveform / float(self._full_scale_value) + vertical_offset_mv
        )

    @property
    def vertical_range_in_mv(self) -> int:
        """The currently set input range of the channel in mV.

        Returns:
            vertical_range (int): The currently set vertical range in mV.
        """
        self._vertical_range_mv = self._parent_device.read_spectrum_device_register(
            VERTICAL_RANGE_COMMANDS[self._number]
        )
        return self._vertical_range_mv

    def set_vertical_range_in_mv(self, vertical_range: int) -> None:
        """Set the input range of the channel in mV. See Spectrum documentation for valid values.

        Args:
            vertical_range (int): The desired vertical range in mV.
        """
        self._parent_device.write_to_spectrum_device_register(VERTICAL_RANGE_COMMANDS[self._number], vertical_range)
        self._vertical_range_mv = vertical_range

    @property
    def vertical_offset_in_percent(self) -> int:
        """The currently set input offset of the channel in percent of the vertical range.

        Returns:
            offset (int): The currently set vertical offset in percent.
        """
        self._vertical_offset_in_percent = self._parent_device.read_spectrum_device_register(
            VERTICAL_OFFSET_COMMANDS[self._number]
        )
        return self._vertical_offset_in_percent

    def set_vertical_offset_in_percent(self, offset: int) -> None:
        """Set the input offset of the channel in percent of the vertical range. See spectrum documentation for valid
        values.

        Args:
            offset (int): The desired vertical offset in percent.
        """
        self._parent_device.write_to_spectrum_device_register(VERTICAL_OFFSET_COMMANDS[self._number], offset)
        self._vertical_offset_in_percent = offset

    @property
    def input_impedance(self) -> InputImpedance:
        """The current input impedance setting of the channel (50 Ohm or 1 MOhm)"""
        impedance_binary_value = self._parent_device.read_spectrum_device_register(
            INPUT_IMPEDANCE_COMMANDS[self._number]
        )
        return InputImpedance(impedance_binary_value)

    def set_input_impedance(self, input_impedance: InputImpedance) -> None:
        self._parent_device.write_to_spectrum_device_register(
            INPUT_IMPEDANCE_COMMANDS[self._number], input_impedance.value
        )

    @property
    def input_coupling(self) -> InputCoupling:
        """The coupling (AC or DC) setting of the channel. Only available on some hardware."""
        coupling_binary_value = self._parent_device.read_spectrum_device_register(INPUT_COUPLING_COMMANDS[self._number])
        return InputCoupling(coupling_binary_value)

    def set_input_coupling(self, input_coupling: InputCoupling) -> None:
        self._parent_device.write_to_spectrum_device_register(
            INPUT_COUPLING_COMMANDS[self._number], input_coupling.value
        )

    @property
    def input_path(self) -> InputPath:
        """The input path setting of the channel. Only available on some hardware."""
        path_binary_value = self._parent_device.read_spectrum_device_register(INPUT_PATH_COMMANDS[self._number])
        return InputPath(path_binary_value)

    def set_input_path(self, input_path: InputPath) -> None:
        self._parent_device.write_to_spectrum_device_register(INPUT_PATH_COMMANDS[self._number], input_path.value)

class SpectrumDigitiserIOLine(AbstractSpectrumIOLine, SpectrumDigitiserIOLineInterface):
    """Class for controlling multipurpose IO lines of a digitiser, e.g. X0, X1, X2 and X3."""

    def __init__(self, parent_device: AbstractSpectrumCard, **kwargs: Any) -> None:
        if parent_device.type != CardType.SPCM_TYPE_AI:
            raise SpectrumCardIsNotADigitiser(parent_device.type)
        super().__init__(parent_device=parent_device, **kwargs)  # pass unused args up the inheritance hierarchy

    def _get_io_line_mode_settings_mask(self, mode: IOLineMode) -> int:
        return 0  # no settings required for DigOut

class SpectrumDigitiserCard(
    AbstractSpectrumCard[SpectrumDigitiserAnalogChannelInterface, SpectrumDigitiserIOLineInterface],
    AbstractSpectrumDigitiser,
):
    """Class for controlling individual Spectrum digitiser cards."""

    def __init__(self, device_number: int, ip_address: Optional[str] = None) -> None:
        """
        Args:
            device_number (int): Index of the card to control. If only one card is present, set to 0.
            ip_address (Optional[str]): If connecting to a networked card, provide the IP address here as a string.

        """
        # pass unused args up the inheritance hierarchy
        super().__init__(device_number=device_number, ip_address=ip_address)

        if self.type != CardType.SPCM_TYPE_AI:
            raise SpectrumCardIsNotADigitiser(self.type)
        self._acquisition_mode = self.acquisition_mode
        self._timestamper: Optional[Timestamper] = None
        self._batch_size = 1

    def _init_analog_channels(self) -> Sequence[SpectrumDigitiserAnalogChannelInterface]:
        num_modules = self.read_spectrum_device_register(SPC_MIINST_MODULES)
        num_channels_per_module = self.read_spectrum_device_register(SPC_MIINST_CHPERMODULE)
        total_channels = num_modules * num_channels_per_module
        return tuple(
            [SpectrumDigitiserAnalogChannel(channel_number=n, parent_device=self) for n in range(total_channels)]
        )

    def _init_io_lines(self) -> Sequence[SpectrumDigitiserIOLineInterface]:
        if (self.model_number.value & TYP_SERIESMASK) == TYP_M2PEXPSERIES:
            return tuple([SpectrumDigitiserIOLine(channel_number=n, parent_device=self) for n in range(4)])
        else:
            raise NotImplementedError("Don't know how many IO lines other types of card have. Only M2P series.")

    def enable_timestamping(self) -> None:
        self._timestamper = Timestamper(self, self._handle)

    def wait_for_acquisition_to_complete(self) -> None:
        """Blocks until the current acquisition has finished, or the timeout is reached.

        In Standard Single mode (SPC_REC_STD_SINGLE), this should be called after `start()`. Once the call
            to `wait_for_acquisition_to_complete()` returns, the newly acquired samples are in the on_device buffer and
            ready for transfer to the `TransferBuffer` using `start_transfer()`.

        In FIFO mode (SPC_REC_FIFO_MULTI), the card will continue to acquire samples until
            `stop()` is called, so `wait_for_acquisition_to_complete()` should not be used.

        """
        self.write_to_spectrum_device_register(SPC_M2CMD, M2CMD_CARD_WAITREADY)

    def get_waveforms(self) -> List[List[NDArray[float_]]]:
        """Get a list of the most recently transferred waveforms, in channel order.

        This method copies and reshapes the samples in the `TransferBuffer` into a list of lists of 1D NumPy arrays
        (waveforms) and returns the list.

        In Standard Single mode (SPC_REC_STD_SINGLE), `get_waveforms()` should be called after
        `wait_for_transfer_to_complete()` has returned.

        In FIFO mode (SPC_REC_FIFO_MULTI), while the card is continuously acquiring samples and transferring them to the
        `TransferBuffer`, this method should be called in a loop . The method will block until each new transfer is
        received, so the loop will run at the same rate as the acquisition (in SPC_REC_FIFO_MULTI mode, for example,
        this would the rate at which your trigger source was running).

        Returns:
             waveforms (List[List[NDArray[float_]]]): A list of lists of 1D numpy arrays, one inner list per acquisition
             and one array per enabled channel, in channel order. To average the acquisitions:
                `np.array(waveforms).mean(axis=0)`

        """
        if self._transfer_buffer is None:
            raise SpectrumNoTransferBufferDefined("Cannot find a samples transfer buffer")

        num_read_bytes = 0
        num_samples_per_frame = self.acquisition_length_in_samples * len(self.enabled_analog_channel_nums)
        num_expected_bytes_per_frame = num_samples_per_frame * self._transfer_buffer.data_array.itemsize
        raw_samples = zeros(num_samples_per_frame * self._batch_size, dtype=self._transfer_buffer.data_array.dtype)

        if self.acquisition_mode in (AcquisitionMode.SPC_REC_STD_SINGLE, AcquisitionMode.SPC_REC_STD_AVERAGE):
            raw_samples = self._transfer_buffer.copy_contents()

        elif self.acquisition_mode in (AcquisitionMode.SPC_REC_FIFO_MULTI, AcquisitionMode.SPC_REC_FIFO_AVERAGE):
            self.wait_for_transfer_chunk_to_complete()

            while num_read_bytes < (num_expected_bytes_per_frame * self._batch_size):
                num_available_bytes = self.read_spectrum_device_register(SPC_DATA_AVAIL_USER_LEN)
                position_of_available_bytes = self.read_spectrum_device_register(SPC_DATA_AVAIL_USER_POS)

                # Don't allow reading over the end of the transfer buffer
                if (
                    position_of_available_bytes + num_available_bytes
                ) > self._transfer_buffer.data_array_length_in_bytes:
                    num_available_bytes = self._transfer_buffer.data_array_length_in_bytes - position_of_available_bytes

                # Don't allow reading over the end of the current acquisition:
                if (num_read_bytes + num_available_bytes) > (num_expected_bytes_per_frame * self._batch_size):
                    num_available_bytes = (num_expected_bytes_per_frame * self._batch_size) - num_read_bytes

                num_available_samples = num_available_bytes // self._transfer_buffer.data_array.itemsize
                num_read_samples = num_read_bytes // self._transfer_buffer.data_array.itemsize

                raw_samples[
                    num_read_samples : num_read_samples + num_available_samples
                ] = self._transfer_buffer.read_chunk(position_of_available_bytes, num_available_bytes)
                self.write_to_spectrum_device_register(SPC_DATA_AVAIL_CARD_LEN, num_available_bytes)

                num_read_bytes += num_available_bytes

        waveforms_in_columns = raw_samples.reshape(
            (self._batch_size, self.acquisition_length_in_samples, len(self.enabled_analog_channel_nums))
        )

        repeat_acquisitions = []
        for n in range(self._batch_size):
            repeat_acquisitions.append(
                [
                    cast(
                        SpectrumDigitiserAnalogChannel, self.analog_channels[ch_num]
                    ).convert_raw_waveform_to_voltage_waveform(squeeze(waveform))
                    for ch_num, waveform in zip(self.enabled_analog_channel_nums, waveforms_in_columns[n, :, :].T)
                ]
            )

        return repeat_acquisitions

    def get_timestamp(self) -> Optional[datetime.datetime]:
        """Get timestamp for the last acquisition"""
        if self._timestamper is not None:
            return self._timestamper.get_timestamp()
        else:
            return None

    @property
    def acquisition_length_in_samples(self) -> int:
        """The current recording length (per channel) in samples.

        Returns:
            length_in_samples (int): The current recording length ('acquisition length') in samples."""
        return self.read_spectrum_device_register(SPC_MEMSIZE)

    def set_acquisition_length_in_samples(self, length_in_samples: int) -> None:
        """Change the recording length (per channel). In FIFO mode, it will be quantised according to the step size
          allowed by the connected card type.

        Args:
            length_in_samples (int): The desired recording length ('acquisition length'), in samples.
        """
        length_in_samples = self._coerce_num_samples_if_fifo(length_in_samples)
        self.write_to_spectrum_device_register(SPC_SEGMENTSIZE, length_in_samples)
        self.write_to_spectrum_device_register(SPC_MEMSIZE, length_in_samples)

    @property
    def post_trigger_length_in_samples(self) -> int:
        """The number of samples of the recording that will contain data received after the trigger event.

        Returns:
            length_in_samples (int): The currently set post trigger length in samples.
        """
        return self.read_spectrum_device_register(SPC_POSTTRIGGER)

    def set_post_trigger_length_in_samples(self, length_in_samples: int) -> None:
        """Change the number of samples of the recording that will contain data received after the trigger event.
        In FIFO mode, this will be quantised according to the minimum step size allowed by the connected card.

        Args:
            length_in_samples (int): The desired post trigger length in samples."""
        length_in_samples = self._coerce_num_samples_if_fifo(length_in_samples)
        if self.acquisition_mode == AcquisitionMode.SPC_REC_FIFO_MULTI:
            if (self.acquisition_length_in_samples - length_in_samples) < get_memsize_step_size(self._model_number):
                logger.warning(
                    "FIFO mode: coercing post trigger length to maximum allowed value (step-size samples less than "
                    "the acquisition length)."
                )
                length_in_samples = self.acquisition_length_in_samples - get_memsize_step_size(self._model_number)
        self.write_to_spectrum_device_register(SPC_POSTTRIGGER, length_in_samples)

    def _coerce_num_samples_if_fifo(self, value: int) -> int:
        if self.acquisition_mode == AcquisitionMode.SPC_REC_FIFO_MULTI:
            if value != mod(value, get_memsize_step_size(self._model_number)):
                logger.warning(
                    f"FIFO mode: coercing length to nearest {get_memsize_step_size(self._model_number)}" f" samples"
                )
                value = int(value - mod(value, get_memsize_step_size(self._model_number)))
        return value

    @property
    def number_of_averages(self) -> int:
        return self.read_spectrum_device_register(SPC_AVERAGES)

    def set_number_of_averages(self, num_averages: int) -> None:
        if num_averages > 0:
            self.write_to_spectrum_device_register(SPC_AVERAGES, num_averages)
        else:
            raise ValueError("Number of averages must be greater than 0.")

    @property
    def acquisition_mode(self) -> AcquisitionMode:
        """The currently enabled card mode. Will raise an exception if the current mode is not supported by
        `spectrumdevice`.

        Returns:
            mode (`AcquisitionMode`): The currently enabled card acquisition mode."""
        return AcquisitionMode(self.read_spectrum_device_register(SPC_CARDMODE))

    def set_acquisition_mode(self, mode: AcquisitionMode) -> None:
        """Change the currently enabled card mode. See `AcquisitionMode` and the Spectrum documentation
        for the available modes.

        Args:
            mode (`AcquisitionMode`): The desired acquisition mode."""
        self.write_to_spectrum_device_register(SPC_CARDMODE, mode.value)

    @property
    def batch_size(self) -> int:
        return self._batch_size

    def set_batch_size(self, batch_size: int) -> None:
        self._batch_size = batch_size

    def define_transfer_buffer(self, buffer: Optional[Sequence[TransferBuffer]] = None) -> None:
        """Create or provide a `TransferBuffer` object for receiving acquired samples from the device.

        If no buffer is provided, and no buffer has previously been defined, then one will be created: in FIFO mode,
         with a notify size of 10 pages or the size of the acquisition, whichever is smaller; in Standard Single mode,
         one with the correct length and no notify size. A separate buffer for transferring Timestamps will also be
         created using the Timestamper class.

        Args:
            buffer (Optional[List[`TransferBuffer`]]): A length-1 list containing a pre-constructed
                `TransferBuffer` set up for card-to-PC transfer of samples ("data"). The size of the buffer should be
                chosen according to the current number of active channels, the acquisition length and the number
                of acquisitions which you intend to download at a time using get_waveforms().
        """
        self._set_or_update_transfer_buffer_attribute(buffer)
        if self._transfer_buffer is not None:
            set_transfer_buffer(self._handle, self._transfer_buffer)

    def _set_or_update_transfer_buffer_attribute(self, buffer: Optional[Sequence[TransferBuffer]]) -> None:
        if buffer:
            self._transfer_buffer = buffer[0]
            if self._transfer_buffer.direction != BufferDirection.SPCM_DIR_CARDTOPC:
                raise ValueError("Digitisers need a transfer buffer with direction BufferDirection.SPCM_DIR_CARDTOPC")
            if self._transfer_buffer.type != BufferType.SPCM_BUF_DATA:
                raise ValueError("Digitisers need a transfer buffer with type BufferDirection.SPCM_BUF_DATA")
        elif self._transfer_buffer is None:
            if self.acquisition_mode in (AcquisitionMode.SPC_REC_FIFO_MULTI, AcquisitionMode.SPC_REC_FIFO_AVERAGE):
                samples_per_batch = (
                    self.acquisition_length_in_samples * len(self.enabled_analog_channel_nums) * self._batch_size
                )
                pages_per_batch = samples_per_batch * self.bytes_per_sample / PAGE_SIZE_IN_BYTES

                if pages_per_batch < DEFAULT_NOTIFY_SIZE_IN_PAGES:
                    notify_size = pages_per_batch
                else:
                    notify_size = DEFAULT_NOTIFY_SIZE_IN_PAGES

                # Make transfer buffer big enough to hold all samples in the batch
                self._transfer_buffer = create_samples_acquisition_transfer_buffer(
                    size_in_samples=samples_per_batch,
                    notify_size_in_pages=notify_size,
                    bytes_per_sample=self.bytes_per_sample,
                )
            elif self.acquisition_mode in (AcquisitionMode.SPC_REC_STD_SINGLE, AcquisitionMode.SPC_REC_STD_AVERAGE):
                self._transfer_buffer = create_samples_acquisition_transfer_buffer(
                    size_in_samples=self.acquisition_length_in_samples * len(self.enabled_analog_channel_nums),
                    notify_size_in_pages=0,
                    bytes_per_sample=self.bytes_per_sample,
                )
            else:
                raise ValueError("AcquisitionMode not recognised")

    def __str__(self) -> str:
        return f"Card {self._visa_string}"

class SpectrumDigitiserStarHub(
    AbstractSpectrumStarHub[
        SpectrumDigitiserCard, SpectrumDigitiserAnalogChannelInterface, SpectrumDigitiserIOLineInterface
    ],
    AbstractSpectrumDigitiser,
):
    """Composite class of `SpectrumDigitiserCard` for controlling a StarHub digitiser device, for example the Spectrum
    NetBox. StarHub digitiser devices are composites of more than one Spectrum digitiser card. Acquisition from the
    child cards of a StarHub is synchronised, aggregating the channels of all child cards. This class enables the
    control of a StarHub device as if it were a single Spectrum card."""

    def __init__(self, device_number: int, child_cards: tuple[SpectrumDigitiserCard, ...], master_card_index: int):
        """
        Args:
            device_number (int): The index of the StarHub to connect to. If only one StarHub is present, set to 0.
            child_cards (Sequence[`SpectrumDigitiserCard`]): A list of `SpectrumCard` objects defining the child cards
                located within the StarHub, correctly constructed with their IP addresses and/or device numbers.
            master_card_index (int): The position within child_cards where the master card (the card which controls the
                clock) is located.
        """
        super().__init__(device_number=device_number, child_cards=child_cards, master_card_index=master_card_index)
        self._acquisition_mode = self.acquisition_mode

    def define_transfer_buffer(self, buffer: Optional[Sequence[TransferBuffer]] = None) -> None:
        """Create or provide `CardToPCDataTransferBuffer` objects for receiving acquired samples from the child cards.
        If no buffers are provided, they will be created with the correct size and a board_memory_offset_bytes of 0. See
        `SpectrumDigitiserCard.define_transfer_buffer()` for more information

        Args:
            buffer (Optional[`CardToPCDataTransferBuffer`]): A list containing pre-constructed
            `CardToPCDataTransferBuffer` objects, one for each child card. The size of the buffers should be chosen
            according to the current number of active channels in each card and the acquisition length.
        """
        if buffer:
            for card, buff in zip(self._child_cards, buffer):
                card.define_transfer_buffer([buff])
        else:
            for card in self._child_cards:
                card.define_transfer_buffer()

    def wait_for_acquisition_to_complete(self) -> None:
        """Wait for each card to finish its acquisition. See `SpectrumDigitiserCard.wait_for_acquisition_to_complete()`
        for more information."""
        for card in self._child_cards:
            card.wait_for_acquisition_to_complete()

    def get_waveforms(self) -> List[List[NDArray[float_]]]:
        """Get a list of the most recently transferred waveforms.

        This method gets the waveforms from each child card and joins them into a new list, ordered by channel number.
        See `SpectrumDigitiserCard.get_waveforms()` for more information.

        Args:
            num_acquisitions (int): For FIFO mode:  the number of acquisitions (i.e. trigger events) to wait for and
            copy. Acquiring in batches (num_acquisitions > 1) can improve performance.

        Returns:
            waveforms (List[List[NDArray[float_]]]): A list lists of 1D numpy arrays, one inner list per acquisition,
              and one array per enabled channel, in channel order.
        """
        card_ids_and_waveform_sets: Dict[str, list[list[NDArray[float_]]]] = {}

        def _get_waveforms(digitiser_card: SpectrumDigitiserCard) -> None:
            this_cards_waveforms = digitiser_card.get_waveforms()
            card_ids_and_waveform_sets[str(digitiser_card)] = this_cards_waveforms

        threads = [Thread(target=_get_waveforms, args=(card,)) for card in self._child_cards]

        for thread in threads:
            thread.start()
        for thread in threads:
            thread.join()

        waveform_sets_all_cards_ordered = []
        for n in range(self.batch_size):
            waveforms_in_this_batch = []
            for card in self._child_cards:
                waveforms_in_this_batch += card_ids_and_waveform_sets[str(card)][n]
            waveform_sets_all_cards_ordered.append(waveforms_in_this_batch)

        return waveform_sets_all_cards_ordered

    def get_timestamp(self) -> Optional[datetime.datetime]:
        """Get timestamp for the last acquisition"""
        return self._triggering_card.get_timestamp()

    def enable_timestamping(self) -> None:
        self._triggering_card.enable_timestamping()

    @property
    def acquisition_length_in_samples(self) -> int:
        """The currently set recording length, which should be the same for all child cards. If different recording
        lengths are set, an exception is raised. See `SpectrumDigitiserCard.acquisition_length_in_samples` for more
        information.

        Returns:
            length_in_samples: The currently set acquisition length in samples."""
        lengths = []
        for d in self._child_cards:
            lengths.append(d.acquisition_length_in_samples)
        return check_settings_constant_across_devices(lengths, __name__)

    def set_acquisition_length_in_samples(self, length_in_samples: int) -> None:
        """Set a new recording length for all child cards. See `SpectrumDigitiserCard.set_acquisition_length_in_samples()`
        for more information.

        Args:
            length_in_samples (int): The desired acquisition length in samples."""
        for d in self._child_cards:
            d.set_acquisition_length_in_samples(length_in_samples)

    @property
    def post_trigger_length_in_samples(self) -> int:
        """The number of samples recorded after a trigger is received. This should be consistent across all child
        cards. If different values are found across the child cards, an exception is raised. See
        `SpectrumDigitiserCard.post_trigger_length_in_samples` for more information.

        Returns:
            length_in_samples (int): The current post trigger length in samples.
        """
        lengths = []
        for d in self._child_cards:
            lengths.append(d.post_trigger_length_in_samples)
        return check_settings_constant_across_devices(lengths, __name__)

    def set_post_trigger_length_in_samples(self, length_in_samples: int) -> None:
        """Set a new post trigger length for all child cards. See `SpectrumDigitiserCard.set_post_trigger_length_in_samples()`
        for more information.

        Args:
            length_in_samples (int): The desired post trigger length in samples.
        """
        for d in self._child_cards:
            d.set_post_trigger_length_in_samples(length_in_samples)

    @property
    def acquisition_mode(self) -> AcquisitionMode:
        """The acquisition mode, which should be the same for all child cards. If it's not, an exception is raised.
        See `SpectrumDigitiserCard.acquisition_mode` for more information.

        Returns:
            mode (`AcquisitionMode`): The currently enabled acquisition mode.
        """
        modes = []
        for d in self._child_cards:
            modes.append(d.acquisition_mode)
        return AcquisitionMode(check_settings_constant_across_devices([m.value for m in modes], __name__))

    def set_acquisition_mode(self, mode: AcquisitionMode) -> None:
        """Change the acquisition mode for all child cards. See `SpectrumDigitiserCard.set_acquisition_mode()` for more
        information.

        Args:
            mode (`AcquisitionMode`): The desired acquisition mode."""
        for d in self._child_cards:
            d.set_acquisition_mode(mode)

    @property
    def batch_size(self) -> int:
        batch_sizes = []
        for d in self._child_cards:
            batch_sizes.append(d.batch_size)
        return check_settings_constant_across_devices(batch_sizes, __name__)

    def set_batch_size(self, batch_size: int) -> None:
        for d in self._child_cards:
            d.set_batch_size(batch_size)

    def force_trigger(self) -> None:
        for d in self._child_cards:
            d.force_trigger()

    @property
    def type(self) -> CardType:
        return self._child_cards[0].type

    @property
    def model_number(self) -> ModelNumber:
        return self._child_cards[0].model_number

    @property
    def analog_channels(self) -> Sequence[SpectrumDigitiserAnalogChannelInterface]:
        """A tuple containing of all the channels of the child cards of the hub. See `AbstractSpectrumCard.channels` for
        more information.

        Returns:
            channels (Sequence[`SpectrumDigitiserAnalogChannelInterface`]):
            A tuple of `SpectrumDigitiserAnalogChannelInterface` objects.
        """
        return super().analog_channels

class MockSpectrumDigitiserCard(MockAbstractSpectrumDigitiser, MockAbstractSpectrumCard, SpectrumDigitiserCard):
    """A mock spectrum card, for testing software written to use the `SpectrumDigitiserCard` class.

    This class overrides methods of `SpectrumDigitiserCard` that communicate with hardware with mocked implementations,
    allowing software to be tested without Spectrum hardware connected or drivers installed, e.g. during CI. It overrides
    methods to use to set up a mock 'on-device buffer' attribute into which a mock waveform source will write
    samples. It also uses a MockTimestamper to generated timestamps for mock waveforms.
    """

    def __init__(
        self,
        device_number: int,
        model: ModelNumber,
        mock_source_frame_rate_hz: float,
        num_modules: int,
        num_channels_per_module: int,
        card_features: Optional[list[CardFeature]] = None,
        advanced_card_features: Optional[list[AdvancedCardFeature]] = None,
    ):
        """
        Args:
            device_number (int): The index of the mock device to create. Used to create a name for the device which is
                used internally.
            model (ModelNumber): The model of card to mock. Affects the allowed acquisition and post-trigger lengths.
            mock_source_frame_rate_hz (float): Rate at which waveforms will be generated by the mock source providing
                data to the mock spectrum card.
            num_modules (int): The number of internal modules to assign the mock card. Default 2. On real hardware, this
                is read from the device so does not need to be set. See the Spectrum documentation to work out how many
                modules your hardware has.
            num_channels_per_module (int): The number of channels per module. Default 4 (so 8 channels in total). On
                real hardware, this is read from the device so does not need to be set.
            card_features (list[CardFeature]): List of available features of the mock device
            advanced_card_features (list[AdvancedCardFeature]): List of available advanced features of the mock device

        """

        super().__init__(
            device_number=device_number,
            model=model,
            mock_source_frame_rate_hz=mock_source_frame_rate_hz,
            num_modules=num_modules,
            num_channels_per_module=num_channels_per_module,
            card_type=CardType.SPCM_TYPE_AI,
            card_features=card_features if card_features is not None else [],
            advanced_card_features=advanced_card_features if advanced_card_features is not None else [],
        )
        self._connect(self._visa_string)
        self._acquisition_mode = self.acquisition_mode
        self._previous_transfer_chunk_count = 0
        self._param_dict[TRANSFER_CHUNK_COUNTER] = 0

    def enable_timestamping(self) -> None:
        self._timestamper: MockTimestamper = MockTimestamper(self, self._handle)

    def set_acquisition_mode(self, mode: AcquisitionMode) -> None:
        """Mock timestamper needs to be recreated if the acquisition mode is changed."""
        super().set_acquisition_mode(mode)
        self._timestamper = MockTimestamper(self, self._handle)

    def set_sample_rate_in_hz(self, rate: int) -> None:
        """Mock timestamper needs to be recreated if the sample rate is changed."""
        super().set_sample_rate_in_hz(rate)
        self._timestamper = MockTimestamper(self, self._handle)

    def set_acquisition_length_in_samples(self, length_in_samples: int) -> None:
        """Set length of mock recording (per channel). In FIFO mode, this will be quantised to the nearest 8 samples.
        See `SpectrumDigitiserCard` for more information. This method is overridden here only so that the internal
        attributes related to the mock on-device buffer can be set.

        Args:
            length_in_samples (int): Number of samples in each generated mock waveform
        """
        super().set_acquisition_length_in_samples(length_in_samples)

    def set_enabled_analog_channels(self, channels_nums: List[int]) -> None:
        """Set the channels to enable for the mock acquisition. See `SpectrumDigitiserCard` for more information. This
        method is overridden here only so that the internal attributes related to the mock on-device buffer
        can be set.

        Args:
            channels_nums (List[int]): List of mock channel indices to enable, e.g. [0, 1, 2].

        """
        if len(list(filter(lambda x: 0 <= x < len(self.analog_channels), channels_nums))) == len(channels_nums):
            super().set_enabled_analog_channels(channels_nums)
        else:
            raise SpectrumSettingsMismatchError("Not enough channels in mock device configuration.")

    def define_transfer_buffer(self, buffer: Optional[Sequence[TransferBuffer]] = None) -> None:
        """Create or provide a `TransferBuffer` object for receiving acquired samples from the device.

        See SpectrumDigitiserCard.define_transfer_buffer(). This mock implementation is identical apart from that it
        does not write to any hardware device."""
        self._set_or_update_transfer_buffer_attribute(buffer)

    def start_transfer(self) -> None:
        """See `SpectrumDigitiserCard.start_transfer()`."""
        pass

    def stop_transfer(self) -> None:
        """See `SpectrumDigitiserCard.stop_transfer()`."""
        pass

    def wait_for_transfer_chunk_to_complete(self) -> None:
        """See `SpectrumDigitiserCard.wait_for_transfer_chunk_to_complete()`. This mock implementation blocks until a
        new mock transfer has been completed by waiting for a change to TRANSFER_CHUNK_COUNTER."""
        if self._transfer_buffer:
            t0 = perf_counter()
            t_elapsed = 0.0
            while (
                self._previous_transfer_chunk_count == self._param_dict[TRANSFER_CHUNK_COUNTER]
            ) and t_elapsed < MOCK_TRANSFER_TIMEOUT_IN_S:
                sleep(0.1)
                t_elapsed = perf_counter() - t0
            self._previous_transfer_chunk_count = self._param_dict[TRANSFER_CHUNK_COUNTER]
        else:
            raise SpectrumNoTransferBufferDefined("No transfer in progress.")

    def wait_for_acquisition_to_complete(self) -> None:
        """See `SpectrumDigitiserCard.wait_for_acquisition_to_complete()`. This mock implementation blocks until a mock
        acquisition has been completed (i.e. the acquisition thread has shut down) or the request has timed out
        according to the `self.timeout_ms attribute`."""
        if self._acquisition_thread is not None:
            self._acquisition_thread.join(timeout=1e-3 * self.timeout_in_ms)
            if self._acquisition_thread.is_alive():
                logger.warning("A timeout occurred while waiting for mock acquisition to complete.")
        else:
            logger.warning("No acquisition in progress. Wait for acquisition to complete has no effect")

class MockSpectrumDigitiserStarHub(MockAbstractSpectrumStarHub, SpectrumDigitiserStarHub):
    """A mock spectrum StarHub, for testing software written to use the `SpectrumStarHub` class.

    Overrides methods of `SpectrumStarHub` and `AbstractSpectrumDigitiser` that communicate with hardware with mocked
    implementations allowing software to be tested without Spectrum hardware connected or drivers installed, e.g. during
    CI."""

    def __init__(self, **kwargs: Any):
        """
        Args:
            child_cards (Sequence[`MockSpectrumDigitiserCard`]): A list of `MockSpectrumDigitiserCard` objects defining the
                properties of the child cards located within the mock hub.
            master_card_index (int): The position within child_cards where the master card (the card which controls the
                clock) is located.
        """
        super().__init__(param_dict=None, **kwargs)
        self._visa_string = "/mock" + self._visa_string
        self._connect(self._visa_string)
        self._acquisition_mode = self.acquisition_mode

    def start(self) -> None:
        """Start a mock acquisition

        See `AbstractSpectrumDevice.start()`. With a hardware device, StarHub's only need to be sent a single
        instruction to start acquisition, which they automatically relay to their child cards - hence why
        `start` is implemented in `AbstractSpectrumDevice` (base class to both `SpectrumDigitiserCard` and
        `SpectrumStarHub`) rather than in `SpectrumStarHub`. In this mock `implementation`, each card's acquisition is
        started individually.

        """
        for card in self._child_cards:
            card.start()

    def stop(self) -> None:
        """Stop a mock acquisition

        See `AbstractSpectrumDevice.stop_acquisition`. With a hardware device, StarHub's only need to be sent a single
        instruction to stop acquisition, which they automatically relay to their child cards - hence why
        `stop_acquisition()` is implemented in `AbstractSpectrumDevice` (base class to both `SpectrumDigitiserCard` and
        `SpectrumStarHub`) rather than in `SpectrumStarHub`. In this mock implementation, each card's acquisition is
        stopped individually.

        """
        for card in self._child_cards:
            card.stop()

class AbstractSpectrumDigitiser(
    AbstractSpectrumDevice[SpectrumDigitiserAnalogChannelInterface, SpectrumDigitiserIOLineInterface],
    SpectrumDigitiserInterface,
    ABC,
):
    """Abstract superclass which implements methods common to all Spectrum digitiser devices. Instances of this class
    cannot be constructed directly. Instead, construct instances of the concrete classes (`SpectrumDigitiserCard`,
    `SpectrumDigitiserStarHub` or their mock equivalents) which inherit the methods defined here. Note that
    the mock devices override several of the methods defined here."""

    def configure_acquisition(self, settings: AcquisitionSettings) -> None:
        """Apply all the settings contained in an `AcquisitionSettings` dataclass to the device.

        Args:
            settings (`AcquisitionSettings`): An `AcquisitionSettings` dataclass containing the setting values to apply.
        """
        if settings.batch_size > 1 and settings.acquisition_mode == AcquisitionMode.SPC_REC_STD_SINGLE:
            raise ValueError("In standard single mode, only 1 acquisition can be downloaded at a time.")
        self._acquisition_mode = settings.acquisition_mode
        self.set_batch_size(settings.batch_size)
        self.set_acquisition_mode(settings.acquisition_mode)
        self.set_sample_rate_in_hz(settings.sample_rate_in_hz)
        self.set_acquisition_length_in_samples(settings.acquisition_length_in_samples)
        self.set_post_trigger_length_in_samples(
            settings.acquisition_length_in_samples - settings.pre_trigger_length_in_samples
        )
        self.set_timeout_in_ms(settings.timeout_in_ms)
        self.set_enabled_analog_channels(settings.enabled_channels)

        # Apply channel dependent settings
        for channel_num, v_range, v_offset, impedance in zip(
            self.enabled_analog_channel_nums,
            settings.vertical_ranges_in_mv,
            settings.vertical_offsets_in_percent,
            settings.input_impedances,
        ):
            channel = self.analog_channels[channel_num]
            channel.set_vertical_range_in_mv(v_range)
            channel.set_vertical_offset_in_percent(v_offset)
            channel.set_input_impedance(impedance)

        # Only some hardware has software programmable input coupling, so coupling can be None
        if settings.input_couplings is not None:
            for channel, coupling in zip(self.analog_channels, settings.input_couplings):
                channel.set_input_coupling(coupling)

        # Only some hardware has software programmable input paths, so it can be None
        if settings.input_paths is not None:
            for channel, path in zip(self.analog_channels, settings.input_paths):
                channel.set_input_path(path)

        # Write the configuration to the card
        self.write_to_spectrum_device_register(SPC_M2CMD, M2CMD_CARD_WRITESETUP)

        if settings.timestamping_enabled:
            self.enable_timestamping()

    def execute_standard_single_acquisition(self) -> Measurement:
        """Carry out a single measurement in standard single mode and return the acquired waveforms.

        This method automatically carries out a standard single mode acquisition, including handling the creation
        of a `TransferBuffer` and the retrieval of the acquired waveforms. After being called, it will wait until a
        trigger event is received before carrying out the acquisition and then transferring and returning the acquired
        waveforms. The device must be configured in SPC_REC_STD_SINGLE acquisition mode.

        Returns:
            measurement (Measurement): A Measurement object. The `.waveforms` attribute of `measurement` will be a list
                of 1D NumPy arrays, each array containing the waveform data received on one channel, in channel order.
                The Waveform object also has a timestamp attribute, which (if timestamping was enabled in acquisition
                settings) contains the time at which the acquisition was triggered.
        """
        if self._acquisition_mode != AcquisitionMode.SPC_REC_STD_SINGLE:
            raise SpectrumWrongAcquisitionMode(
                "Set the acquisition mode to SPC_REC_STD_SINGLE using "
                "configure_acquisition() or set_acquisition_mode() before executing "
                "a standard single mode acquisition."
            )
        self.start()
        self.wait_for_acquisition_to_complete()
        self.define_transfer_buffer()
        self.start_transfer()
        self.wait_for_transfer_chunk_to_complete()
        waveforms = self.get_waveforms()[0]
        self.stop()  # Only strictly required for Mock devices. Should not affect hardware.
        return Measurement(waveforms=waveforms, timestamp=self.get_timestamp())

    def execute_finite_fifo_acquisition(self, num_measurements: int) -> List[Measurement]:
        """Carry out a finite number of FIFO mode measurements and then stop the acquisitions.

        This method automatically carries out a defined number of measurement in Multi FIFO mode, including handling the
        creation of a `TransferBuffer`, streaming the acquired waveforms to the PC, terminating the acquisition and
        returning the acquired waveforms. After being called, it will wait for the requested number of triggers to be
        received, generating the correct number of measurements. It retrieves each measurement's waveforms from the
        `TransferBuffer` as they arrive. Once the requested number of measurements have been received, the acquisition
        is terminated and the waveforms are returned. The device must be configured in SPC_REC_FIFO_MULTI or
        SPC_REC_FIFO_AVERAGE acquisition mode.

        Args:
            num_measurements (int): The number of measurements to carry out.
        Returns:
            measurements (List[Measurement]): A list of Measurement objects with length `num_measurements`. Each
                Measurement object has a `waveforms` attribute containing a list of 1D NumPy arrays. Each array is a
                waveform acquired from one channel. The arrays are in channel order. The Waveform objects also have a
                timestamp attribute, which (if timestamping was enabled in acquisition settings) contains the time at
                which the acquisition was triggered.
        """
        if (num_measurements % self.batch_size) != 0:
            raise ValueError(
                "Number of measurements in a finite FIFO acquisition must be a multiple of the "
                " batch size configured using AbstractSpectrumDigitiser.configure_acquisition()."
            )
        self.execute_continuous_fifo_acquisition()
        measurements = []
        for _ in range(num_measurements // self.batch_size):
            measurements += [
                Measurement(waveforms=frame, timestamp=self.get_timestamp()) for frame in self.get_waveforms()
            ]
        self.stop()
        return measurements

    def execute_continuous_fifo_acquisition(self) -> None:
        """Start a continuous FIFO mode acquisition.

        This method automatically starts acquiring and streaming samples in FIFO mode, including handling the
        creation of a `TransferBuffer` and streaming the acquired waveforms to the PC. It will return almost
        instantaneously. The acquired waveforms must then be read out of the transfer buffer in a loop using the
        `get_waveforms()` method. Waveforms must be read at least as fast as they are being acquired.
        The FIFO acquisition and streaming will continue until `stop_acquisition()` is called. The device
        must be configured in SPC_REC_FIFO_MULTI or SPC_REC_FIFO_AVERAGE acquisition mode."""
        if self._acquisition_mode not in (AcquisitionMode.SPC_REC_FIFO_MULTI, AcquisitionMode.SPC_REC_FIFO_AVERAGE):
            raise SpectrumWrongAcquisitionMode(
                "Set the acquisition mode to SPC_REC_FIFO_MULTI or SPC_REC_FIFO_AVERAGE using "
                "configure_acquisition() or set_acquisition_mode() before executing "
                "a fifo mode acquisition."
            )
        self.define_transfer_buffer()
        self.start()
        self.start_transfer()