Introduction#
This tutorial will guide users through the important features of tdcpy with illustrations on how to use them.
For detailed information and syntax on the individual functions and classes, please refer to the ../reference/api_reference section of the
tdcpy manual and in the references listed at the end of this document.
The related theory on the topic, can be found in [Michiels and Niculescu, 2007] and the TDS-Control manual [Appeltans and Michiels, 2023].
Getting Started#
The most basic data structure utilized within tdcpy is the NumPy array. At the beginning of every script,
it is required to import the NumPy and tdcpy packages as follows:
import numpy as np
import tdcpy as tds
The secondary package SciPy is used for scientific computations and optimization, and can be imported as follows:
import scipy as sp
Similarly, the plotting package Matplotlib is used for visualization of results, and can be imported as follows:
import matplotlib.pyplot as plt
Once the packages have been imported, the user can create tdcpy objects, perform spectral analysis and design appropriate controllers.
In the remaining part of this tutorial, we assume that the above main packages have been imported already.
Kindly follow the below links for the next steps of this guide.
Section |
Description |
|---|---|
Defining a time-delay system |
|
Spectral analysis of time-delay systems |
|
Stabilization and controller design |
|
../reference/api_reference |
Detailed description of all functions and classes |
Examples of usage of tdcpy |
High-level API vs Low-level API#
tdcpy functions can be called using the low-level API or the high-level API.
The high-level API is most often sufficient for users wanting to work directly with high-level functions, for example, root computation or controller design.
Internally, the high-level API wraps the low-level API around high-level functions to provide a simplified interface to users.
Nevertheless, for users intending to gain a deeper insight in the workings of the software, or for those wanting to include the basic functions
into their own code, for example in optimization routines, users can directly access the low-level API, which provides the necessary building blocks.
For example, for computing the characteristic roots of a time-delay system, the below code snippet uses the high-level function tdcpy.roots, to provide a similar
functionality as the TDS-Control MATLAB function tds_roots.
A0 = np.array([ [-1, 0, 0, 0],
[0, 1, 0, 0],
[0, 0, -10, -4],
[0, 0, 4, -10]])
A1 = np.array([ [3, 3, 3, 3],
[0, -1.5, 0, 0],
[0, 0, 3, -5],
[0, 5, 5, 5]])
hA = np.array([0,1])
rdde = tds.RDDE(A = [A0, A1], hA=hA)
roots, info = tds.roots(rdde, r=-1.0)
Computing the roots can alternately be performed using the low-level function roots_ddae from the submodule tdcpy.stability.characteristic_roots as follows:
import numpy as np
from tdcpy.stability.characteristic_roots import roots_ddae
E = np.array(np.eye(4))
A = np.zeros(shape=(4,4,2))
A[:,:,0] = np.array([[-1, 0, 0, 0],
[0, 1, 0, 0],
[0, 0, -10, -4],
[0, 0, 4, -10]])
A[:,:,1] = np.array([[3, 3, 3, 3],
[0, -1.5, 0, 0],
[0, 0, 3, -5],
[0, 5, 5, 5]])
hA = np.array([0,1])
cr, info = roots_ddae(E,A,hA,r=-1)
Both code snippets will yield the same results. However, the first snippet is practical if one is only interested in the characteristic roots of the time-delay system.
If however, the task of root computation is part of a larger framework, for example in an optimization routine,
the second code snippet provides more flexibility to the user in incorporating the root computation into their own code.
Secondly, notice that the low-level API requires the user to explicitly provide the system matrices in a 3D NumPy array, whereas the high-level API handles this internally when creating the time-delay system object.
More details on the structure of the tdcpy object can be found in the next sections of this tutorial.