SCDDS-core documentation
===================

.. include:: license_msg.rst 
 
Introduction
-----------------------------
This repository contains a set of tools (a library) to develop real-time control systems in Matlab/Simulink, specifically for pulsed devices like tokamaks.

This code was developed at the `Swiss Plasma Center`_ at EPFL Lausanne, originally for use on the `TCV tokamak`_ , over the period 2008-2022.

In 2022 the library was refactored to be independent of TCV and suitable for use for any tokamak control system.
These tools are now distributed in open-source (see license below) in the hope of contributing to a standardization of the way we define, test and deploy control algorithms across fusion devices.

If this library finds its use outside tokamaks or fusion devices, that would also be welcome.

Key features
------------------------

The code consists of a set of functions and classes to define components of the control system. 
Usually, a matlab object (instantiation of a class) is associated with one (or more) Simulink models. 
The matlab object allows the user to perform common tasks for the Simulink model such as retrieving its parameters and signals (from a file or external parameter database), building it into an executable, or running (unit or integration) tests.

Various control system components are defined:

- Architectural elements: 

	.. figure:: /_static/imgs/architecture_illustration.png
		:alt: Architecture illustration
		:width: 240 px
		:align: right


	- ``algos``: represenging functional blocks with algorithms.
	- ``wrappers``: (running collections of algorithms), this is the unit that is normally compiled into an executable.
	- ``nodes``: (collections of threads running on one computational node).
	- ``expcode``: a representation of the entire control system, being a collection of nodes.\
	
	.. note:: It is not necessary to use all the components in this hierarcy, depending on the use-case, already using algos may be very useful.

- Classes for testing all these components.
- Interfaces to parameter and signal databases (like ``MDSplus``) to load parameters and signals for a given experiment (shot).
- Methods to programmatically define and trigger the compilation of components to C code and deployment to a real-time framework.


Use of the library
--------------------
The normal use of this library consists of deriving classes for a specific instantiation of a control system.

For example the TCV control code is built using classes that derive from the superclasses from this library.

This library comes with a demo file (repository `SCDDS-demo`_ that contains a demo implementation of a simple control system, that is interfaced with an MDSplus database and deployed to the MARTe2 real-time control system.
New users can first check out this demo.


.. referenced links:
.. _SCDDS-demo: https://gitlab.epfl.ch/spc/scdds/scdds-demo
.. _Swiss Plasma Center: https://www.epfl.ch/research/domains/swiss-plasma-center/
.. _TCV tokamak: https://en.wikipedia.org/wiki/Tokamak_%C3%A0_configuration_variable