Tutorials
=========

These tutorials are meant to be read in order. Each one introduces the tools
the next one uses, so that nothing is ever used before it has been explained,
and nothing is explained twice.

.. list-table::
   :header-rows: 1
   :widths: 8 30 62

   * - #
     - Tutorial
     - What it introduces
   * - 0
     - :doc:`../getting_started/first_simulation`
     - The ``Sequential`` chain, the blocks it is made of, an observation to look
       inside it, and one error rate.
   * - 1
     - :doc:`awgn`
     - A Monte Carlo study: first as an ordinary ``for`` loop, then the same
       thing with ``monte_carlo``, read against a closed form written out in
       NumPy, and ending on four QAM orders at equal energy per bit. Also
       ``seed``, ``set_params`` and ``plot_error_rate``.
   * - 2
     - :doc:`ofdm`
     - A frequency-selective channel, and the two ways to equalize it:
       one matrix inversion, or one division per subcarrier.
   * - 3
     - :doc:`ofdm_papr`
     - What an OFDM waveform costs the amplifier, and the CCDF that measures
       it.
   * - 4
     - :doc:`mimo`
     - Several antennas, and the five detectors that separate the streams --
       from the pseudo-inverse to the sphere decoder.
   * - 5
     - :doc:`alamouti`
     - Diversity without channel knowledge at the transmitter: space-time
       coding, measured against its closed form.
   * - 6
     - :doc:`coding`
     - Redundancy: convolutional codes and the Viterbi trellis, the union
       bound, and an LDPC waterfall.
   * - 7
     - :doc:`shaping`
     - Sending some constellation points more often than others, and the
       1.53 dB it recovers.
   * - 8
     - :doc:`gn_model`
     - A nonlinear channel: how much noise the fibre's nonlinearity makes,
       in closed form, and the launch power that minimizes it -- checked
       against a split-step simulation.
   * - 9
     - :doc:`optical_pdm`
     - The blind coherent receiver: a fibre that mixes the two
       polarizations (``PMDEmulator``), the CMA butterfly that
       unmixes them, and blind phase search against the laser.
   * - 9
     - :doc:`optical_fiber_nonlinearity`
     - The performance the previous tutorial predicted, improved: digital
       back-propagation undoes the nonlinearity instead of budgeting for it.

If you are looking for one specific thing rather than a course, every page is
self-contained enough to be read alone -- it will simply point back at the
tutorial where a tool was introduced instead of explaining it again.

The scripts behind these pages are also available on GitHub: `https://github.com/vincentchoqueuse/comnumpy/tree/main/examples <https://github.com/vincentchoqueuse/comnumpy/tree/main/examples>`_.

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   awgn
   ofdm
   ofdm_papr
   mimo
   alamouti
   coding
   shaping
   gn_model
   optical_pdm
   optical_fiber_nonlinearity