# Concept¶

Kontrol is a Python package that is programmed to help setting KAGRA control systems, particularly vibration isolation systems. Kontrol can be used designed to be used side-by-side with KAGRA software for data acquisition and control systems implementation, such as diaggui and Foton. Kontrol provides the neccessary tools for completing a control system setup jobs, including

1. Sensor and actuator calibration and diagonalization (kontrol.sensact module),
2. Transfer function and frequency spectrum modeling (kontrol.curvefit module), and
3. Controller and filter design (kontrol.regulator and kontrol.complementary_filter modules).

And, other utilities interfacing Python and KAGRA digital systems, such as kontrol.ezca, are provided.

## Basic control systems setup¶

A typical complete control systems setup workflow would be the following:

1. Calibration:
1. Obtain sensor calibration data.
• For linear sensors, obtain a 2-array consisting of physical quantity (e.g. displacement) and readout (e.g. voltage or digital counts).
• For sensors requiring calibration filters, it is necessary to do an inter-calibration between the sensor and another calibrated sensor. In this case, obtain atransfer function between the readouts of the calibrated sensor and the sensor of interest.
1. Obtain calibration factor/filter
• For linear sensors, use kontrol.sensact.calibrate().
• For sensors requiring calibration filters, fit the transfer function using kontrol.curvefit.TransferFunctionFit class. This requires the user to define a model of the calibration filter.
1. Implement the calibration factor/filter
• For calibration factors, simply copy it into the MEDM interface.
• For calibration filters, convert the calibrated transfer function into a kontrol.TransferFunction object and then use the kontrol.TransferFunction.foton() method to extract a Foton string, which can be directly copied to the Foton interface.
1. Diagonalization (We assume geometric matrices are implemented):
1. Sensors:
1. Somehow obtain obtain a coupling matrix that maps the control space to the sensor space.
2. Define a kontrol.sensact.SensingMatrix class and use kontrol.sensact.SensingMatrix.diagonalize() method to obtain a diagonalizing sensing matrix. If the geometric matrix and diagonalization matrix can be implemented separately, the object can be defined with an identity matrix. Otherwise, the method returns a diagonalized geometric matrix.
1. Actuators:
• Terrence doesn’t believe there’s a true way to diagonalize actuators so the method is not implemented. Hint: diagonalizing actuation matrices are different from diagonalizing sensing matrices.
1. Transfer function modeling
1. Obtain the frequency response data and load it using something like vishack.data.diaggui.Diaggui.tf() from VISHack.
2. (Optional) Initial guess: Fit the frequency response manually by tweaking a kontrol.curvefit.model.ComplexZPK class (or other models).
3. Fit the frequency response with a kontrol.curvefit.TransferFunctionFit class. If the an initial guess is not provided, then a global optimization method, such as scipy.optimize.differential_evolution, is needed to be specified as the optimizer attribute.
4. (Optional) Obtain a transfer function from kontrol.curvefit.model.ComplexZPK.tf (or otherwise), define it as a kontrol.TransferFunction object and export a Foton expression using kontrol.TransferFunction.foton() method.
5. (Optional) Alternatively, export the transfer function object using kontrol.TransferFunction.save() method.
2. Obtain the optimal PID controller (For systems that have 2 more complex poles than complex zeros).
1. Obtain a transfer function (from above or otherwise).
2. Use kontrol.regulator.oscillator.pid() to optimize a derivative, PD, or PID controller. * Derivative gain is optimized by converting two complex poles to simple double poles.
3. Use kontrol.regulator.post_filter.post_notch() and kontrol.regulator.post_filter.post_low_pass() to obtain necessary notch filter and low-pass filter (with a specified phase margin) for stabilization and practical implementation.
4. Again, use kontrol.TransferFunction to extract their Foton expressions for implementation.

• kontrol.complementary_filter.ComplementaryFilter class provides an option use H-infinity synthesis to optimize complementary filters according to modeled sensor noises.