MSC Virtual Workflows
=====================

The MSC measurement scripts can be run with virtual device configurations for
development and regression testing without laboratory hardware.

Available scripts and configurations
------------------------------------

The modern text-based MSC scripts live in the ``script`` directory:

.. list-table::
   :header-rows: 1

   * - Script
     - Purpose
     - Typical virtual configuration
   * - ``msc-maincal.py``
     - Chamber calibration for ``empty`` and ``loaded`` states
     - ``conf/msc-immunity-virtual/conf.py``
   * - ``msc-eutcal.py``
     - EUT loading calibration
     - ``conf/msc-immunity-virtual/conf-eutcal.py``
   * - ``msc-immunity.py``
     - Immunity measurement using the calibration history
     - ``conf/msc-immunity-virtual/conf-immunity.py``
   * - ``msc-emission.py``
     - Emission measurement using the calibration history
     - ``conf/msc-emission-virtual/conf.py`` or
       ``conf/msc-emission-virtual/conf-after-immunity.py``

Each of these scripts also has a Qt starter with the same configuration
interface: ``msc-maincal-qt.py``, ``msc-eutcal-qt.py``, ``msc-immunity-qt.py``
and ``msc-emission-qt.py``. These starters use the simple Qt UI with
``Stop / RF Off`` and run the measurement logic in a worker thread.

The ``msc-immunity-virtual`` and ``msc-emission-virtual`` configurations use
virtual instruments and synthetic path corrections. The matching
``*-realpaths`` configurations still use virtual instruments, but load real
path correction data from ``MpyConfig/LargeRC/ini``.

History pickles
---------------

The MSC pickle files are history containers. A script loads an existing
``MSC`` instance from ``pickle_input_filename``, adds the next measurement and
evaluation results, and writes the complete updated instance to
``pickle_output_filename``.

This means that every new output pickle should contain the full previous
measurement history plus the newly added data. For traceability, do not treat
these files as isolated intermediate calibration files.

Typical sequences are:

.. code-block:: text

   maincal -> eutcal -> immunity
   maincal -> eutcal -> emission
   maincal -> eutcal -> immunity -> emission

Virtual MSC immunity chain
--------------------------

From the ``script`` directory, the virtual immunity chain can be run as:

.. code-block:: console

   python msc-maincal.py conf/msc-immunity-virtual/conf.py
   python msc-eutcal.py conf/msc-immunity-virtual/conf-eutcal.py
   python msc-immunity.py conf/msc-immunity-virtual/conf-immunity.py

The same chain can be run through the Qt starters:

.. code-block:: console

   python msc-maincal-qt.py conf/msc-immunity-virtual/conf.py
   python msc-eutcal-qt.py conf/msc-immunity-virtual/conf-eutcal.py
   python msc-immunity-qt.py conf/msc-immunity-virtual/conf-immunity.py

The corresponding output pickles are written below
``conf/msc-immunity-virtual/output``.

The real-path variant uses the same script sequence with
``conf/msc-immunity-virtual-realpaths``:

.. code-block:: console

   python msc-maincal.py conf/msc-immunity-virtual-realpaths/conf.py
   python msc-eutcal.py conf/msc-immunity-virtual-realpaths/conf-eutcal.py
   python msc-immunity.py conf/msc-immunity-virtual-realpaths/conf-immunity.py

Virtual MSC emission
--------------------

For an emission run directly after EUT calibration:

.. code-block:: console

   python msc-emission.py conf/msc-emission-virtual/conf.py

Or with the Qt UI:

.. code-block:: console

   python msc-emission-qt.py conf/msc-emission-virtual/conf.py

For an emission run that should preserve a preceding immunity measurement in
the same history:

.. code-block:: console

   python msc-emission.py conf/msc-emission-virtual/conf-after-immunity.py

The corresponding real-path variants are:

.. code-block:: console

   python msc-emission.py conf/msc-emission-virtual-realpaths/conf.py
   python msc-emission.py conf/msc-emission-virtual-realpaths/conf-after-immunity.py

Real path data
--------------

The ``*-realpaths`` variants expect the ``MpyConfig`` checkout next to the
``mpylab`` repository:

.. code-block:: text

   workspace/
   ├── mpylab/
   └── MpyConfig/
       └── LargeRC/
           └── ini/

If ``MpyConfig/LargeRC/ini`` is missing, tests that need real path correction
data are skipped. The pure virtual configurations remain fully hardware
independent.

Tests
-----

The hardware-independent MSC workflows are covered by the pytest suite:

.. list-table::
   :header-rows: 1

   * - Test
     - Coverage
   * - ``test_msc_immunity_virtual_config.py``
     - Loads the virtual and real-path DOT configurations and initializes the
       MGraph without hardware access.
   * - ``test_msc_virtual_history_workflow.py``
     - Runs the script sequence with temporary output files and verifies that
       each output pickle preserves the previous ``MSC`` history.

Run the tests from the repository root with:

.. code-block:: console

   PYTHONPATH=src:../scuq/src python -m pytest test