update readme; add example usage

Author: rssalessio

README.md

@@ -1,4 +1,4 @@
-# PythonVRFT Library - Version 0.0.5
+# PythonVRFT Library - Version 0.0.6
 VRFT Adaptive Control Library written in Python. Aim of this library is to provide an implementation of the VRFT (Virtual Reference Feedback Tuning) algorithm.
 
 You can find the package also at the following [link](https://pypi.org/project/pythonvrft/)
@@ -22,10 +22,44 @@ Other dependencies:
 - Install from source: git clone this repo and from the root folder execute the command ```pip install .```
 
 ## Usage/Examples
-You can import the library by typing ```import vrft``` in your code.
+You can import the library by typing ```python import vrft``` in your code.
+
 To learn how to use the library, check the examples located in the examples/ folder. At the moment there are examples available. 
 Check example3 to see usage of instrumental variables.
 
+In general the code has the following structure
+```python
+from vrft import ExtendedTF    # Discrete transfer function (inherits from the scipy.signal.dlti class)
+from vrft import iddata        # object used to store input/output data
+from vrft import compute_vrft  # VRFT algorithm
+
+# Parameters
+dt = 0.1  # sampling time
+
+# Define a reference model
+ref_model = ExtendedTF([0.6], [1, -0.4], dt=t_step)   # 0.6/ (z-0.4)
+
+# Define pre-filter
+pre_filter = (1 - ref_model) * ref_model
+
+# Define control base (PI control)
+control = [ExtendedTF([1], [1, -1], dt=t_step),  # 1/(z-1)
+        ExtendedTF([1, 0], [1, -1], dt=t_step)]  # z/(z-1)
+
+# Generate input/output data from a system
+u = ....  # Generate input
+y = ....  # measured output
+
+# Create an iddata object
+y0 = ... # initial conditions of the system (the length depends on the order of the reference model)
+data = iddata(y, u, dt, y0)
+
+# Compute VRFT
+# theta is the vector of parameters that parametrizes the control base
+# C is the final controller (computed as control.dot(theta))
+theta, _, _, C = compute_vrft(data, ref_model, control, pre_filter)
+```
+
 ## Tests
 To execute tests run the following command
 ```sh

examples/example1.py

@@ -11,7 +11,7 @@
 # along with PythonVRFT.  If not, see <http://www.gnu.org/licenses/>.
 #
 # Code author: [Alessio Russo - alessior@kth.se]
-# Last update: 06th January 2020, by alessior@kth.se
+# Last update: 08th January 2020, by alessior@kth.se
 #
 
 import numpy as np
@@ -75,7 +75,7 @@
 ys = np.array(ys).flatten()
 yc = np.array(yc).flatten()
 fig, ax = plt.subplots(4, sharex=True, figsize=(12,8), dpi= 100, facecolor='w', edgecolor='k')
-ax[0].plot(t, yr,label='Ref System')
+ax[0].plot(t, yr,label='Reference System')
 ax[0].plot(t, yc, label='CL System')
 ax[0].set_title('Systems response')
 ax[0].grid(True)

examples/example2.py

@@ -84,7 +84,7 @@ def generateNoise(t):
 ys = np.array(ys).flatten()
 yc = np.array(yc).flatten()
 fig, ax = plt.subplots(4, sharex=True, figsize=(12,8), dpi= 100, facecolor='w', edgecolor='k')
-ax[0].plot(t, yr,label='Ref System')
+ax[0].plot(t, yr,label='Reference System')
 ax[0].plot(t, yc, label='CL System')
 ax[0].set_title('Systems response')
 ax[0].grid(True)

examples/example3.py

@@ -30,7 +30,7 @@
 t_start = 0
 t_end = 10
 dt = 1e-2
-t = np.array([i * dt for i in range(int(t_end/dt    ))])
+t = np.array([i * dt for i in range(int(t_end/dt))])
 
 #Experiment
 num = [0.5]
@@ -88,7 +88,7 @@ def generate_data(sys, u, t):
 yc_iv = yc_iv.flatten()
 
 fig, ax = plt.subplots(4, sharex=True, figsize=(12,8), dpi= 100, facecolor='w', edgecolor='k')
-ax[0].plot(t, yr,label='Ref System')
+ax[0].plot(t, yr,label='Reference System')
 ax[0].plot(t, yc_iv, label='CL System - IV')
 ax[0].plot(t, yc_noiv, label='CL System - No IV')
 ax[0].set_title('CL Systems response')

examples/notebook_example_1.ipynb

@@ -188,7 +188,7 @@
     "ys = np.array(ys).flatten()\n",
     "yc = np.array(yc).flatten()\n",
     "fig, ax = plt.subplots(4, sharex=True, figsize=(12,8), dpi= 100, facecolor='w', edgecolor='k')\n",
-    "ax[0].plot(t, yr,label='Ref System')\n",
+    "ax[0].plot(t, yr,label='Reference System')\n",
     "ax[0].plot(t, yc, label='CL System')\n",
     "ax[0].set_title('Systems response')\n",
     "ax[0].grid(True)\n",

examples/notebook_example_2.ipynb

@@ -197,7 +197,7 @@
     "ys = np.array(ys).flatten()\n",
     "yc = np.array(yc).flatten()\n",
     "fig, ax = plt.subplots(4, sharex=True, figsize=(12,8), dpi= 100, facecolor='w', edgecolor='k')\n",
-    "ax[0].plot(t, yr,label='Ref System')\n",
+    "ax[0].plot(t, yr,label='Reference System')\n",
     "ax[0].plot(t, yc, label='CL System')\n",
     "ax[0].set_title('Systems response')\n",
     "ax[0].grid(True)\n",

examples/notebook_example_3.ipynb

@@ -212,7 +212,7 @@
     "yc_iv = yc_iv.flatten()\n",
     "\n",
     "fig, ax = plt.subplots(4, sharex=True, figsize=(12,8), dpi= 100, facecolor='w', edgecolor='k')\n",
-    "ax[0].plot(t, yr,label='Ref System')\n",
+    "ax[0].plot(t, yr,label='Reference System')\n",
     "ax[0].plot(t, yc_iv, label='CL System - IV')\n",
     "ax[0].plot(t, yc_noiv, label='CL System - No IV')\n",
     "ax[0].set_title('CL Systems response')\n",

setup.py

@@ -6,7 +6,7 @@
 
 
 setup(name = 'pythonvrft',
-    version = '0.0.5',
+    version = '0.0.6',
     description = 'VRFT Python Library',
     long_description = long_description,
     long_description_content_type = 'text/markdown',