MU-MIMO System
==============

Overview
--------

The :class:`~mu_mimo.core.system.MuMimoSystem` class represents the complete MU-MIMO downlink digital communication system. It acts as the central coordinator between the three core components:

- A :class:`~mu_mimo.core.system.BaseStation` (BS) — responsible for bit allocation, mapping and precoding.
- A :class:`~mu_mimo.core.system.Channel` — responsible for propagating signals and control messages between the BS and the UTs.
- A set of :class:`~mu_mimo.core.system.UserTerminal` (UT) instances — each responsible for combining, equalizing, detecting and demapping the received signal.

The system is driven by the :class:`~mu_mimo.core.system.SimulationRunner`, which calls the three methods of this class in the following order for each channel realization:

.. code-block:: text

   reset()  →  configure()  →  communicate()


System Phases
-------------

Reset
^^^^^

.. code-block:: python

   mu_mimo_system.reset(csi)

Clears the state of all components and prepares the system for a new channel realization. Concretely:

1. The BS state (:attr:`~mu_mimo.core.system.BaseStation.state`) is cleared.
2. Each UT state (:attr:`~mu_mimo.core.system.UserTerminal.state`) is cleared.
3. The channel state is reset: the SNR is set (or defaults to :math:`\infty`) and a new channel matrix :math:`\mathbf{H}` is generated by the channel model if not provided.

Configuration
^^^^^^^^^^^^^

.. code-block:: python

   mu_mimo_system.configure()

Exchanges control messages between the BS and the UTs to determine bit allocation, precoding matrix and combining matrix for the current channel realization. It proceeds in three phases:

| **1. Pilot phase**
| The BS transmits pilot signals. Each UT estimates its channel matrix :math:`\mathbf{H}_k` from the received pilot signals. Because channel estimation is not the focus of this work, we assume perfect channel state information (CSI) at the UTs, so the channel estimation step is skipped and each UT directly receives its true channel matrix from the pilot messages.

| In case of non-coordinated beamforming, the UTs compute their own (suboptimal) combining matrices :math:`\mathbf{G}_k` based on their channel matrices.
| In case of coordinated beamforming, the combining matrices are computed at the BS alongside the precoding matrix.

| **2. Feedback phase**
| Each UT sends its effective channel matrix :math:`\mathbf{H}_{\text{eff},k}` back to the BS. The effective channel matrix is the channel matrix as seen by the BS.
| In case of non-coordinated beamforming, the effective channel matrix is the channel matrix followed by the UT's combining matrix: :math:`\mathbf{H}_{\text{eff},k} = \mathbf{G}_k \mathbf{H}_k`.
| In case of coordinated beamforming, the effective channel matrix is the same as the true channel matrix: :math:`\mathbf{H}_{\text{eff},k} = \mathbf{H}_k`.

| At the BS, this feedback message is processed to compute the precoding matrix :math:`\mathbf{P}` and, in case of coordinated beamforming, the combining matrices :math:`\mathbf{G}_k` as well. The bit allocation and the equalization factors are also computed at the BS.

| **3. Feedforward phase**
| The BS broadcasts the computed parameters back to each UT, so that each UT can correctly combine, equalize and decode its received signal during the data transmission phase.



Data Transmission
^^^^^^^^^^^^^^^^^

.. code-block:: python

   tx_bits_list, rx_bits_list = mu_mimo_system.communicate(M)

A simulation of the complete data transmission for :math:`M` symbol vectors. It consists of three steps:

| **1. BS transmit chain**
| Bits are allocated, mapped to constellation symbols and precoded into the transmitted signal :math:`\mathbf{x}`.

| **2. Channel propagation** 
| Noise is generated and added to the channel-distorted signal, yielding the per-UT received signals :math:`\mathbf{y}_k`.

| **3. UT receive chain** 
| Each UT applies combining, equalization, detection and demapping to recover the transmitted bitstreams.

The method returns the transmitted and reconstructed bitstreams for all UTs, which are used by the :class:`~mu_mimo.core.system.SimulationRunner` to compute the performance metrics (BER, IBR, ...).


Documentation
-------------

.. autoclass:: mu_mimo.core.system.MuMimoSystem
   :members:


See Also
--------

- :doc:`simulation_runner`
- :doc:`base_station`
- :doc:`channel`
- :doc:`user_terminal`