Improve inspection notebooks, Minor update of docs

python-control · KybernetikJo · Jul 26, 2023 · Jul 26, 2023 · Jul 26, 2023 · Jul 26, 2023
commit 07271278629c6dfd58c422d1f90b6183296e2c0c
diff --git a/doc/index.rst b/doc/index.rst
@@ -6,22 +6,24 @@
 Slycot
 ======
 
-Python wrapper for selected SLICOT routines, 
+Python wrapper for selected `SLICOT <https://github.com/SLICOT/SLICOT-Reference>`_ routines, 
 notably including solvers for Riccati, Lyapunov, and Sylvester equations.
 
-.. rubric:: Features
-
-- Analysis Routines
-- Benchmark
-- Adaptive Control
-- Data Analysis
-- Filtering
-- Identification
-- Mathematical Routines
-- Nonlinear Systems
-- Synthesis Routines
-- Transformation Routines
-- Utility Routines
+.. rubric:: Chapters
+
+The Slycot library is organised by chapters. Each chapter can be identified by a single letter. The following chapters are included:
+
+- ``A`` : Analysis Routines
+- ``B`` : Benchmark
+- ``C`` : Adaptive Control
+- ``D`` : Data Analysis
+- ``F`` : Filtering
+- ``I`` : Identification
+- ``M`` : Mathematical Routines
+- ``N`` : Nonlinear Systems
+- ``S`` : Synthesis Routines
+- ``T`` : Transformation Routines
+- ``U`` : Utility Routines
 
 .. rubric:: Documentation
 

diff --git a/doc/intro.rst b/doc/intro.rst
@@ -53,7 +53,14 @@ To install in your home directory, use::
 Getting started
 ===============
 
-There are two different ways to use the package.  For the default interface
-described in :ref:`function-ref`, simply import the control package as follows::
+There are two different ways to use the package. For the default interface
+described in :ref:`function-ref`, simply import the slycot package as follows::
 
-    >>> import slycot
+    >>> import slycot
+
+.. warning::
+  In general, the second way is not recommended.
+
+  To access the f2py interface described in :ref:`inner_function-ref`, simply import the slycot package as follows::
+
+    >>> import slycot._wrapper
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -1,6 +1,7 @@
 sphinx>=3.4
 numpy
 scipy
+pandas
 matplotlib
 matplotlib_venn
 sphinx_rtd_theme

diff --git a/doc/source/dev/inspect_slycot.ipynb b/doc/source/dev/inspect_slycot.ipynb
@@ -15,7 +15,7 @@
    "source": [
     "This notebook shows how to inspect the slycot module.\n",
     "The result gives us a first insight which slicot procedures are implemented.\n",
-    "In addition we get some insight about the orginisation of the module."
+    "In addition we get some insight about the organization of the slycot module."
    ]
   },
   {
@@ -27,7 +27,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "0.1.dev606+g8b31df8\n"
+      "0.1.dev607+g25317fd.d20230808\n"
      ]
     }
    ],
@@ -42,7 +42,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Inspect Wrapper function"
+    "##  Helper functions"
    ]
   },
   {
@@ -51,27 +51,35 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "def get_slycot_method(sly):\n",
+    "def print_list_chunks(routines_list, n=6):\n",
+    "    \"\"\"Print list in chunks of lists.\"\"\"\n",
+    "    start = 0\n",
+    "    end = len(routines_list)\n",
+    "    step = n\n",
+    "    for i in range(start, end, step):\n",
+    "        x = i\n",
+    "        print(routines_list[x:x+step])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def get_slycot_routines(sly):\n",
     "    all_attributes = dir(sly)\n",
     "    r = re.compile(\"[a-z][a-z][0-9][0-9a-z][a-z][a-z]\")\n",
     "    matched_attributes = list(filter(r.match, all_attributes)) # Read Note below\n",
     "    return matched_attributes"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": 3,
+   "attachments": {},
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "def print_list_chunks(l, n=6):\n",
-    "      \n",
-    "    start = 0\n",
-    "    end = len(l)\n",
-    "    step = n\n",
-    "    for i in range(start, end, step):\n",
-    "        x = i\n",
-    "        print(l[x:x+step])\n"
+    "## Inspect Wrapper function"
    ]
   },
   {
@@ -91,7 +99,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Currently there are 49 methods implemented.\n",
+      "Currently there are 49 routines implemented.\n",
       "------\n",
       "['ab01nd', 'ab05md', 'ab05nd', 'ab07nd', 'ab08nd', 'ab08nz']\n",
       "['ab09ad', 'ab09ax', 'ab09bd', 'ab09md', 'ab09nd', 'ab13bd']\n",
@@ -107,9 +115,9 @@
     }
    ],
    "source": [
-    "slycot_wrapper = get_slycot_method(slycot)\n",
+    "slycot_wrapper = get_slycot_routines(slycot)\n",
     "\n",
-    "print(f\"Currently there are {len(slycot_wrapper)} methods implemented.\")\n",
+    "print(f\"Currently there are {len(slycot_wrapper)} routines implemented.\")\n",
     "print(\"------\")\n",
     "print(print_list_chunks(slycot_wrapper))"
    ]
@@ -131,7 +139,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Currently there are 71 methods implemented.\n",
+      "Currently there are 71 routines implemented.\n",
       "------\n",
       "['ab01nd', 'ab05md', 'ab05nd', 'ab07nd', 'ab08nd', 'ab08nz']\n",
       "['ab09ad', 'ab09ax', 'ab09bd', 'ab09md', 'ab09nd', 'ab13bd']\n",
@@ -150,9 +158,9 @@
     }
    ],
    "source": [
-    "slycot_f2py_wrapper = get_slycot_method(slycot._wrapper)\n",
+    "slycot_f2py_wrapper = get_slycot_routines(slycot._wrapper)\n",
     "\n",
-    "print(f\"Currently there are {len(slycot_f2py_wrapper)} methods implemented.\")\n",
+    "print(f\"Currently there are {len(slycot_f2py_wrapper)} routines implemented.\")\n",
     "print(\"------\")\n",
     "print(print_list_chunks(slycot_f2py_wrapper))"
    ]
@@ -186,31 +194,31 @@
      "text": [
       "Currently there are 10 routines implemented in slycot_wrapper which are not in slycot_f2py_wrapper.\n",
       "------\n",
-      "['tb05ad', 'sb02od', 'td04ad', 'tc04ad', 'tc01od', 'sb02mt']\n",
-      "['sb03md57', 'tb04ad', 'sg02ad', 'tb03ad']\n",
+      "['tb04ad', 'tb05ad', 'sb02mt', 'td04ad', 'tc04ad', 'tc01od']\n",
+      "['sg02ad', 'tb03ad', 'sb02od', 'sb03md57']\n",
       "None\n",
       "\n",
       "\n",
       "Currently there are 32 routines implemented in slycot_f2py_wrapper which are not in slycot_wrapper.\n",
       "------\n",
-      "['sg02ad_bd', 'tc01od_r', 'sg02ad_bc', 'sb02od_n', 'sg02ad_g', 'tg01ad']\n",
-      "['tb05ad_nh', 'sb10jd', 'td04ad_r', 'sb02mt_nl', 'tb05ad_ng', 'tb04ad_r']\n",
-      "['tb03ad_r', 'td04ad_c', 'tg01fd_uu', 'ag08bd', 'tb03ad_l', 'sb02od_b']\n",
-      "['sb02mt_n', 'tg01fd_nn', 'sb02mt_c', 'tb05ad_ag', 'tc04ad_r', 'sb02od_d']\n",
-      "['tg01fd_ii', 'sg02ad_bb', 'tc04ad_l', 'sb02mt_cl', 'tb04ad_c', 'tc01od_l']\n",
-      "['sb02od_c', 'sg02ad_bn']\n",
+      "['td04ad_c', 'sb02mt_cl', 'sg02ad_bb', 'sb02mt_c', 'tc04ad_l', 'tg01fd_nn']\n",
+      "['tc01od_r', 'sb02od_c', 'tb04ad_r', 'ag08bd', 'sb02mt_n', 'sg02ad_bn']\n",
+      "['td04ad_r', 'tb03ad_l', 'sg02ad_bc', 'sb02od_d', 'tc04ad_r', 'tg01fd_ii']\n",
+      "['tc01od_l', 'tb05ad_ng', 'sb02od_n', 'sb02mt_nl', 'sb10jd', 'sb02od_b']\n",
+      "['tb05ad_ag', 'tb05ad_nh', 'tg01fd_uu', 'tb04ad_c', 'tg01ad', 'tb03ad_r']\n",
+      "['sg02ad_bd', 'sg02ad_g']\n",
       "None\n",
       "\n",
       "\n",
       "Currently there are 42 routines implemented in slycot_wrapper or slycot_f2py_wrapper.\n",
       "------\n",
-      "['sg02ad_bd', 'tc04ad', 'tc01od_r', 'sb02mt', 'sb02od_n', 'sg02ad_bc']\n",
-      "['sg02ad_g', 'tg01ad', 'tb05ad_nh', 'sb10jd', 'td04ad_r', 'sb02mt_nl']\n",
-      "['tb05ad_ng', 'td04ad', 'tb04ad_r', 'tb03ad_r', 'td04ad_c', 'tg01fd_uu']\n",
-      "['ag08bd', 'tb04ad', 'sg02ad', 'sb02od_b', 'tb03ad_l', 'sb02od']\n",
-      "['sb02mt_n', 'tg01fd_nn', 'tb05ad_ag', 'sb02mt_c', 'tc04ad_r', 'sb03md57']\n",
-      "['tg01fd_ii', 'sb02od_d', 'sg02ad_bb', 'tc04ad_l', 'tb05ad', 'sb02mt_cl']\n",
-      "['tb04ad_c', 'tc01od_l', 'sb02od_c', 'tc01od', 'sg02ad_bn', 'tb03ad']\n",
+      "['td04ad_c', 'tb05ad', 'sb02mt_cl', 'sg02ad_bb', 'sb02mt', 'sb02mt_c']\n",
+      "['tc04ad_l', 'tg01fd_nn', 'tc01od_r', 'tb03ad', 'ag08bd', 'sb02od_c']\n",
+      "['tb04ad_r', 'sb03md57', 'sb02mt_n', 'tb04ad', 'td04ad', 'sg02ad_bn']\n",
+      "['td04ad_r', 'tb03ad_l', 'sg02ad_bc', 'sb02od_d', 'tc04ad_r', 'tg01fd_ii']\n",
+      "['tc01od_l', 'tb05ad_ng', 'sb02od_n', 'sg02ad', 'sb02od', 'sb02mt_nl']\n",
+      "['sb10jd', 'sb02od_b', 'tb05ad_ag', 'tb05ad_nh', 'tg01fd_uu', 'tc04ad']\n",
+      "['tb04ad_c', 'tg01ad', 'tb03ad_r', 'sg02ad_bd', 'tc01od', 'sg02ad_g']\n",
       "None\n",
       "\n",
       "\n"
@@ -254,32 +262,32 @@
      "text": [
       "Currently there are 39 routines implemented in slycot_wrapper and in slycot_f2py_wrapper.\n",
       "------\n",
-      "['tf01md', 'ab13ed', 'mb05md', 'ab13fd', 'mb03vd', 'ab07nd']\n",
-      "['mb03rd', 'ab09bd', 'ab05md', 'sg03bd', 'ab08nz', 'sb10hd']\n",
-      "['mb05nd', 'ab09md', 'mc01td', 'tb01id', 'ab08nd', 'ab13dd']\n",
-      "['sb02md', 'ab09ax', 'sb10ad', 'sb10dd', 'ab09ad', 'ab13md']\n",
-      "['sb01bd', 'tf01rd', 'ab13bd', 'sg03ad', 'sb03md', 'tb01pd']\n",
-      "['ab01nd', 'ab05nd', 'sb03od', 'sb04qd', 'ab09nd', 'mb03vy']\n",
-      "['sb10fd', 'mb03wd', 'sb04md']\n",
+      "['mc01td', 'sb04qd', 'ab13dd', 'ab13md', 'ab13fd', 'sb03od']\n",
+      "['sg03bd', 'ab08nz', 'tb01id', 'mb03rd', 'tb01pd', 'mb05nd']\n",
+      "['sb04md', 'tf01rd', 'sb01bd', 'mb03vd', 'mb05md', 'ab05nd']\n",
+      "['mb03vy', 'ab08nd', 'ab05md', 'ab09ax', 'sb02md', 'sg03ad']\n",
+      "['ab09md', 'sb10dd', 'sb03md', 'ab09bd', 'tf01md', 'ab09ad']\n",
+      "['sb10hd', 'sb10ad', 'ab07nd', 'ab01nd', 'mb03wd', 'ab09nd']\n",
+      "['ab13ed', 'ab13bd', 'sb10fd']\n",
       "None\n",
       "\n",
       "\n",
       "Currently there are 81 routines implemented in slycot_wrapper or in slycot_f2py_wrapper.\n",
       "------\n",
-      "['sg02ad_bd', 'ab13ed', 'tc04ad', 'ab13fd', 'mb03vd', 'tc01od_r']\n",
-      "['sb02mt', 'mb03rd', 'sb02od_n', 'sg02ad_g', 'tg01ad', 'tb05ad_nh']\n",
-      "['ab08nz', 'sb10hd', 'td04ad', 'tb04ad_r', 'tb03ad_r', 'tb04ad']\n",
-      "['ab09md', 'ab08nd', 'ab13dd', 'mc01td', 'sb02od_b', 'tb01id']\n",
-      "['tb03ad_l', 'sb02md', 'sb10dd', 'ab09ad', 'sb02mt_c', 'tb05ad_ag']\n",
-      "['tb01pd', 'sg02ad_bb', 'ab05nd', 'tb05ad', 'sb03od', 'sb04qd']\n",
-      "['sb02od_c', 'ab09nd', 'mb03vy', 'sg02ad_bn', 'mb03wd', 'sb04md']\n",
-      "['tf01md', 'mb05md', 'ab07nd', 'sg02ad_bc', 'ab09bd', 'ab05md']\n",
-      "['sb10jd', 'td04ad_r', 'sb02mt_nl', 'sg03bd', 'tb05ad_ng', 'td04ad_c']\n",
-      "['tg01fd_uu', 'mb05nd', 'ag08bd', 'sg02ad', 'ab09ax', 'sb02od']\n",
-      "['sb10ad', 'sb02mt_n', 'tg01fd_nn', 'ab13md', 'sb01bd', 'tc04ad_r']\n",
-      "['sb02od_d', 'ab13bd', 'sg03ad', 'sb03md', 'tf01rd', 'tg01fd_ii']\n",
-      "['sb03md57', 'ab01nd', 'tc04ad_l', 'sb02mt_cl', 'tb04ad_c', 'tc01od_l']\n",
-      "['sb10fd', 'tc01od', 'tb03ad']\n",
+      "['mc01td', 'td04ad_c', 'sg02ad_bb', 'sb02mt', 'sb02mt_c', 'tc01od_r']\n",
+      "['ab13md', 'ag08bd', 'ab08nz', 'tb01id', 'mb03rd', 'tb04ad']\n",
+      "['td04ad', 'sb04md', 'tf01rd', 'mb03vd', 'ab05nd', 'tc04ad_r']\n",
+      "['sb02md', 'sg03ad', 'tg01fd_ii', 'tc01od_l', 'tb05ad_ng', 'sb02od_n']\n",
+      "['sb03md', 'sb02mt_nl', 'sb10jd', 'tf01md', 'sb02od_b', 'ab09ad']\n",
+      "['tb05ad_ag', 'sb10hd', 'tb04ad_c', 'sb10ad', 'ab01nd', 'tg01ad']\n",
+      "['ab13ed', 'tb03ad', 'sg02ad_bd', 'tb05ad', 'sb02mt_cl', 'sb04qd']\n",
+      "['tc04ad_l', 'tg01fd_nn', 'ab13dd', 'ab13fd', 'sb03od', 'sb02od_c']\n",
+      "['tb04ad_r', 'sg03bd', 'sb02mt_n', 'sb03md57', 'tb01pd', 'mb05nd']\n",
+      "['sg02ad_bn', 'td04ad_r', 'sb01bd', 'tb03ad_l', 'mb05md', 'sg02ad_bc']\n",
+      "['sb02od_d', 'mb03vy', 'ab08nd', 'ab05md', 'ab09ax', 'ab09md']\n",
+      "['sb10dd', 'sg02ad', 'ab09bd', 'sb02od', 'tb05ad_nh', 'tg01fd_uu']\n",
+      "['tc04ad', 'ab07nd', 'mb03wd', 'ab09nd', 'tb03ad_r', 'ab13bd']\n",
+      "['sb10fd', 'tc01od', 'sg02ad_g']\n",
       "None\n",
       "\n",
       "\n"