:orphan:

Tutorials
=========

Seven guided scripts, each a complete program that runs as is (the figures of these
pages are produced when the documentation is built). They go from the first call to
a campaign run from the command line, then to the tools that look inside a chain:

1. **A first link** — bits, constellation, noise, decisions, the closed form, and the
   same link as a chain on the parallel runner.
2. **A classical single-carrier chain** — pulse shaping, matched filter, decimation;
   the eye diagram and the spectrum; phase noise and carrier recovery as variants.
3. **Writing a block in Python** — a transmitter IQ imbalance and its blind
   compensation as Python blocks, checked against the native blocks trial for trial.
4. **Specifications and the command line** — the chain as a YAML file, expected
   results, the operating point of a metric, and the ``comnum`` command.
5. **Where the time goes** — the profile of a chain, block by block, on both
   runners; two settings compared; the price of a Python block.
6. **Looking at the signals** — the trace of one trial, probes during a campaign,
   ``dump`` recordings at a point of the link, and a Python block as a tap.
7. **A measured signal** — a capture of a software radio through the front end, the
   LTE cell search and the MIB, the FM stereo multiplex and its RDS; the same code on
   a simulated capture and on a HackRF recording.

The :doc:`user guide <../user_guide/index>` is the reference for what the tutorials
touch; the :doc:`gallery <../auto_examples/index>` has the classical curves.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The smallest complete simulation: draw bits, map them on a constellation, add noise, decide, count the errors and compare with the closed form. Every step is one call on NumPy arrays. The same link is then written as a chain of named blocks and run as a Monte Carlo campaign on every core, with a stopping rule and confidence intervals.">

.. only:: html

  .. image:: /auto_tutorials/images/thumb/sphx_glr_plot_01_first_link_thumb.png
    :alt:

  :doc:`/auto_tutorials/plot_01_first_link`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A first link: 16-QAM over AWGN</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="QPSK at several samples per symbol: root-raised-cosine pulse shaping, additive noise, the matched filter and decimation to one sample per symbol — the textbook chain, as a comnum.Chain of native blocks. The chain runs once to look at the signals after every block (the eye diagram, the spectrum, the constellation), then as a campaign against the closed form; variants with laser phase noise and blind phase search are one line apart.">

.. only:: html

  .. image:: /auto_tutorials/images/thumb/sphx_glr_plot_02_classic_chain_thumb.png
    :alt:

  :doc:`/auto_tutorials/plot_02_classic_chain`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A classical single-carrier chain</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A block of a chain is any callable f(frame, rng) that reads and writes the samples of a comnum.Frame, or any subclass of comnum.Block. Python blocks prototype an impairment or an algorithm with NumPy, run inside the same chains as the native blocks, and are checked against them trial for trial. This tutorial writes a transmitter IQ imbalance and its blind compensation, the Gram–Schmidt orthogonalisation procedure (GSOP) of Fatadin, Savory &amp; Ives, IEEE Photon. Technol. Lett. 20(20), 2008, and compares both with the native blocks.">

.. only:: html

  .. image:: /auto_tutorials/images/thumb/sphx_glr_plot_03_python_block_thumb.png
    :alt:

  :doc:`/auto_tutorials/plot_03_python_block`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Writing a block in Python</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A campaign is a document: the grid, the link as a list of blocks, the metrics, the stopping rule and the expected results, in a YAML file. The file runs from Python (comnum.run_spec) and from the command line (``comnum run``), on the parallel Rust runner, and its report records the version, the seed and the specification, so that every number can be traced back to what produced it. This tutorial writes the chain of the first tutorial as a file, states what its results must be, searches the operating point of a metric, and shows the command line.">

.. only:: html

  .. image:: /auto_tutorials/images/thumb/sphx_glr_plot_04_specifications_thumb.png
    :alt:

  :doc:`/auto_tutorials/plot_04_specifications`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Specifications and the command line</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A campaign run with profile=True times every block of every trial and reports the mean time per trial of each as a metric, &lt;block&gt;.time_ms, next to the error rates. comnum.Results.profile turns these metrics into a table, in the order of the link, with the share of every block; comnum.Chain.profile runs a short campaign and returns it. The same table comes from the command line with comnum run --profile. This tutorial profiles the coherent receiver of specs/coherent_link.yaml, compares two settings of its carrier recovery, and measures the price of a block written in Python.">

.. only:: html

  .. image:: /auto_tutorials/images/thumb/sphx_glr_plot_05_profiling_thumb.png
    :alt:

  :doc:`/auto_tutorials/plot_05_profiling`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Where the time goes: profiling a chain</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Three ways to see what a block does to the signal. comnum.Chain.trace runs one trial and keeps the frame after every block, for plots and NumPy; probe blocks measure metrics at a point of the link during a whole campaign; the dump block saves the samples at a point of the link for the first trials of every condition, as SigMF recordings that any tool reads. A Python block can also keep whatever it wants. The chain is the coherent receiver of specs/coherent_link.yaml.">

.. only:: html

  .. image:: /auto_tutorials/images/thumb/sphx_glr_plot_06_signals_thumb.png
    :alt:

  :doc:`/auto_tutorials/plot_06_signals`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Looking at the signals along a chain</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A capture of a software radio goes through the same blocks as a simulation. This tutorial takes two: the LTE downlink of a cell (its identity and the master information block of every frame), and an FM station with its stereo multiplex and its radio data system. Both are simulated here, so that the page builds anywhere; the same calls read the recordings of a HackRF One at the end of the page.">

.. only:: html

  .. image:: /auto_tutorials/images/thumb/sphx_glr_plot_07_measured_signal_thumb.png
    :alt:

  :doc:`/auto_tutorials/plot_07_measured_signal`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A measured signal</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /auto_tutorials/plot_01_first_link
   /auto_tutorials/plot_02_classic_chain
   /auto_tutorials/plot_03_python_block
   /auto_tutorials/plot_04_specifications
   /auto_tutorials/plot_05_profiling
   /auto_tutorials/plot_06_signals
   /auto_tutorials/plot_07_measured_signal



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_