A dedicated Python control system library for control system optimization and utilities in KAGRA

Kontrol

Kontrol (also pronounced "control") is a python package for KAGRA control system related work. It is intented for both offline and real-time (via Ezca and maybe diaggui and nds2 later) usage. In principle, it should cover all control related topics ranging from sensor/actuator diagonalization to system identification and control filter design.

Features

• Complementary filter synthesis using \mathcal{H}_\infty methods [1].
  • Synthesize optimal complementary filters in a 2-sensor configuration.
• Curve fitting
  • Fit transfer functions, spectral densities, etc.
• Frequency series modeling (Soon deprecating. See Curve fitting).
  • Model-based empirical fitting.
  • Model frequency series as zero-pole-gain and transfer function models.
• Sensing/Actuation Matrices.
  • Sensing/Actuation Matrices diagonalization with given coupling matrix.
  • General optical lever, horizontal and vertical optical lever sensing matrices, using parameters defined in kagra-optical-lever.
• Spectral analysis
  • Noise spectral density estimation using 2-channel method [2]
  • Noise spectral density estimation using 3-channel method [3]
  • Time series simulation of a given spectral density.
• Foton utilities.
  • Convert Python transfer function objects to Foton expressions
  • Support for translating transfer functions with higher than 20 order (the Foton limit).
• Easy Channel Access (EZCA) utilities (wrapper)
  • Read and write matrices to EPICS record.
• Transfer Function
  • Export transfer functions to foton expressions.
  • Save TransferFunction objects to pickle files.
• Controller design
  • Auto-design of PID controller for oscillatory systems (like pendulum suspensions)
  • Auto-design of post-filters such as notch filters and low-pass filters.
• Dynamic mode decomposition
  • Time series modeling using dynamic mode decomposition

Don't hesitate to check out the tutorials!

• Documentation: https://kontrol.readthedocs.io/
• Repository: https://github.com/terrencetec/kontrol.git

Getting Started

Dependencies

Required

• control>=0.9
• numpy
• matplotlib
• scipy

Optional

• ezca (Needed for accessing EPICs records/real-time model process variables. Use conda to install it.)
• vishack or dttxml (For extracting data from diaggui xml files.)

If you would like to install Kontrol on your local machine with, then pip should install the required dependencies automatically for you. However, if you use Kontrol in a Conda environment, you should install the dependencies before installing Kontrol to avoid using pip. In Conda environment, simply type

conda install -c conda-forge numpy scipy matplotlib control ezca

Install from source

For local usage, type

$ git clone https://github.com/terrencetec/kontrol.git
$ cd kontrol
$ pip install .

For k1ctr workstations, make sure a virtual environment is enabled before installing any packages.

For Developers

Standards and Tools

Please comply with the following standards/guides as much as possible.

Coding style

• PEP 8: https://www.python.org/dev/peps/pep-0008/

CHANGELOG

• Keep a Changelog: https://keepachangelog.com/en/1.0.0/

Versioning

• Semantic Versioning: https://semver.org/spec/v2.0.0.html

Packaging

• PyPA: https://www.pypa.io
• python-packaging: https://python-packaging.readthedocs.io

Documentation

• NumPy docstrings: https://numpydoc.readthedocs.io/en/latest/format.html
• Sphinx: https://www.sphinx-doc.org/
• Read The Docs: https://readthedocs.org/
• Documenting Python Code: A Complete Guide: https://realpython.com/documenting-python-code/

How to Contribute

Just do it.

Pending

• Documentation.
• tests!
• Model reference sensor/actuator diagonalization
• Add support for reading Shoda-san's SUMCON simulations.
• Controller optimization
• Optimal controller synthesis
• python-foton interface.
• Diaggui support.
• Issues: https://github.com/terrencetec/kontrol/issues

[1]	T. T. L. Tsang, T. G. F. Li, T. Dehaeze, C. Collette. Optimal Sensor Fusion Method for Active Vibration Isolation Systems in Ground-Based Gravitational-Wave Detectors. https://arxiv.org/pdf/2111.14355.pdf

[2]	Aaron Barzilai, Tom VanZandt, and Tom Kenny. Technique for measurement of the noise of a sensor in the presence of large background signals. Review of Scientific Instruments, 69:2767–2772, 07 1998.

[3]	R. Sleeman, A. Wettum, and J. Trampert. Three-channel correlation analysis: A new technique to measure instrumental noise of digitizers and seismic sensors. Bulletin of the Seismological Society of America, 96:258–271, 2006.