Implement OOP block structure description

CITATION.cff

@@ -5,6 +5,10 @@ authors:
     given-names: "Steven"
     orcid: "https://orcid.org/0000-0003-4930-9634"
     affiliation: "McGill University"
+  - family-names: "Adams"
+    given-names: "Timothy Everett"
+    orcid: "https://orcid.org/0009-0008-5291-0686"
+    affiliation: "McGill University"
   - family-names: "Forbes"
     given-names: "James Richard"
     orcid: "https://orcid.org/0000-0002-1987-9268"

README.rst

@@ -131,12 +131,12 @@ If you use this software in your research, please cite it as below or see
 
 .. code-block:: bibtex
 
-    @software{dahdah_dkpy_2024,
+    @software{dahdah_dkpy_2025,
         title={{decargroup/dkpy}},
         doi={10.5281/zenodo.14511244},
         url={https://github.com/decargroup/dkpy},
         publisher={Zenodo},
-        author={Steven Dahdah and James Richard Forbes},
+        author={Steven Dahdah and Timothy Everett Adams and James Richard Forbes},
         version = {{v0.1.9}},
-        year={2024},
+        year={2025},
     }

doc/conf.py

@@ -7,8 +7,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "dkpy"
-copyright = "2024, Steven Dahdah and James Richard Forbes"
-author = "Steven Dahdah and James Richard Forbes"
+copyright = "2024, Steven Dahdah, Timothy Everett Adams and James Richard Forbes"
+author = "Steven Dahdah, Timothy Everett Adams and James Richard Forbes"
 version = "0.1.9"
 release = "0.1.9"
 

doc/dkpy.rst

@@ -1,3 +1,38 @@
+``dkpy`` architecture overview
+==============================
+
+``dkpy`` implements each step in the D-K iteration algorithm as an abstract
+class. This ensures that each step satisfies the interface required by the
+algorithm while leaving the numerical implementation up to the user. Sensible
+implementations of each of these steps are provided in ``dkpy``. However, the
+user can create custom implementations via the abstract classes. Therefore,
+anyone aiming to extend or customize ``dkpy`` should familiarize themselves
+with them. The abstract classes are provided below.
+
+.. autosummary::
+   :toctree: _autosummary/
+
+   dkpy.ControllerSynthesis
+   dkpy.StructuredSingularValue
+   dkpy.DScaleFit
+   dkpy.DkIteration
+
+The steps of the D-K iteration algorithm are as follows [SP06]_. 
+1. Controller synthesis (:class:`ControllerSynthesis`): Synthesize an
+   H-infinity controller for the scaled problem with fixed fitted D-scales.
+2. Structured singular value and D-scale computation
+   (:class:`StructuredSingularValue`): Compute the structured singular value
+   and the D-scales over a discrete grid of frequencies with a fixed
+   controller.
+3. D-scale fit (:class:`DScaleFit`): Fit the magnitude of each D-scale to a
+   stable minimum-phase LTI system.
+
+The D-K iteration algorithm, specified by a :class:`DkIteration` object, loops
+through these three steps until the robustness criteria are satisfied.
+Therefore, the algorithm is specified using implementations of each of the
+abstract classes :class:`ControllerSynthesis`,
+:class:`StructuredSingularValue`, and :class:`DScaleFit`.
+
 D-K iteration methods
 =====================
 
@@ -69,17 +104,23 @@ selecting the order in :func:`DScaleFit.fit`.
 
    dkpy.DScaleFitSlicot
 
-Extending ``dkpy``
-==================
+Uncertainty block structure
+===========================
 
-The abstract classes defining the structure of ``dkpy`` are presented below.
-Anyone aiming to extend or customize ``dkpy`` should familiarize themselves
-with them.
+The uncertainty block structure is specified via an
+:class:`UncertaintyBlockStructure` object, which encodes the block diagonal
+uncertainty structure. The :class:`UncertaintyBlockStructure` object is
+composed of individual uncertainty blocks that satisfy the interface in
+:class:`UncertaintyBlock`, which are provided below.
 
 .. autosummary::
    :toctree: _autosummary/
 
-   dkpy.DkIteration
-   dkpy.ControllerSynthesis
-   dkpy.StructuredSingularValue
-   dkpy.DScaleFit
+   dkpy.RealDiagonalBlock
+   dkpy.ComplexDiagonalBlock
+   dkpy.ComplexFullBlock
+
+The :class:`UncertaintyBlockStructure` object can also be specified using the
+MATLAB two-column array format (see `MATLAB documentation
+<https://www.mathworks.com/help/robust/ref/mussv.html>`) for users that are
+more comfortable with this notation.

examples/1_example_dk_iter_fixed_order.py

@@ -19,13 +19,23 @@ def example_dk_iter_fixed_order():
     )
 
     omega = np.logspace(-3, 3, 61)
-    block_structure = np.array([[1, 1], [1, 1], [2, 2]])
+    # Alternative MATLAB descr.
+    # uncertainty_structure = dkpy.UncertaintyBlockStructure(
+    #     [[1, 1], [1, 1], [2, 2]]
+    # )
+    uncertainty_structure = dkpy.UncertaintyBlockStructure(
+        [
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(2, 2),
+        ]
+    )
     K, N, mu, iter_results, info = dk_iter.synthesize(
         eg["P"],
         eg["n_y"],
         eg["n_u"],
         omega,
-        block_structure,
+        uncertainty_structure,
     )
 
     print(f"mu={mu}")

examples/2_example_dk_iter_list_order.py

@@ -23,13 +23,23 @@ def example_dk_iter_list_order():
     )
 
     omega = np.logspace(-3, 3, 61)
-    block_structure = np.array([[1, 1], [1, 1], [2, 2]])
+    # Alternative MATLAB descr.
+    # uncertainty_structure = dkpy.UncertaintyBlockStructure(
+    #     [[1, 1], [1, 1], [2, 2]]
+    # )
+    uncertainty_structure = dkpy.UncertaintyBlockStructure(
+        [
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(2, 2),
+        ]
+    )
     K, N, mu, iter_results, info = dk_iter.synthesize(
         eg["P"],
         eg["n_y"],
         eg["n_u"],
         omega,
-        block_structure,
+        uncertainty_structure,
     )
 
     print(f"mu={mu}")

examples/3_example_dk_iter_auto_order.py

@@ -44,13 +44,23 @@ def example_dk_iter_auto_order():
     )
 
     omega = np.logspace(-3, 3, 61)
-    block_structure = np.array([[1, 1], [1, 1], [2, 2]])
+    # Alternative MATLAB descr.
+    # uncertainty_structure = dkpy.UncertaintyBlockStructure(
+    #     [[1, 1], [1, 1], [2, 2]]
+    # )
+    uncertainty_structure = dkpy.UncertaintyBlockStructure(
+        [
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(2, 2),
+        ]
+    )
     K, N, mu, iter_results, info = dk_iter.synthesize(
         eg["P"],
         eg["n_y"],
         eg["n_u"],
         omega,
-        block_structure,
+        uncertainty_structure,
     )
 
     print(f"mu={mu}")

examples/4_example_dk_iter_interactive.py

@@ -37,13 +37,23 @@ def example_dk_iter_interactive():
     )
 
     omega = np.logspace(-3, 3, 61)
-    block_structure = np.array([[1, 1], [1, 1], [2, 2]])
+    # Alternative MATLAB descr.
+    # uncertainty_structure = dkpy.UncertaintyBlockStructure(
+    #     [[1, 1], [1, 1], [2, 2]]
+    # )
+    uncertainty_structure = dkpy.UncertaintyBlockStructure(
+        [
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(2, 2),
+        ]
+    )
     K, N, mu, iter_results, info = dk_iter.synthesize(
         eg["P"],
         eg["n_y"],
         eg["n_u"],
         omega,
-        block_structure,
+        uncertainty_structure,
     )
 
     print(f"mu={mu}")

examples/5_example_dk_iteration_custom.py

@@ -34,7 +34,7 @@ def _get_fit_order(
         D_omega,
         P,
         K,
-        block_structure,
+        uncertainty_structure,
     ):
         print(f"Iteration {self.my_iter_count} with mu of {np.max(mu_omega)}")
         if self.my_iter_count < 3:
@@ -70,13 +70,23 @@ def example_dk_iter_custom():
     )
 
     omega = np.logspace(-3, 3, 61)
-    block_structure = np.array([[1, 1], [1, 1], [2, 2]])
+    # Alternative MATLAB descr.
+    # uncertainty_structure = dkpy.UncertaintyBlockStructure(
+    #     [[1, 1], [1, 1], [2, 2]]
+    # )
+    uncertainty_structure = dkpy.UncertaintyBlockStructure(
+        [
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(1, 1),
+            dkpy.ComplexFullBlock(2, 2),
+        ]
+    )
     K, N, mu, iter_results, info = dk_iter.synthesize(
         eg["P"],
         eg["n_y"],
         eg["n_u"],
         omega,
-        block_structure,
+        uncertainty_structure,
     )
 
     print(f"mu={mu}")

src/dkpy/__init__.py

@@ -4,4 +4,5 @@
 from .dk_iteration import *
 from .d_scale_fit import *
 from .structured_singular_value import *
+from .uncertainty_structure import *
 from .utilities import *

src/dkpy/controller_synthesis.py

@@ -71,7 +71,7 @@ class HinfSynSlicot(ControllerSynthesis):
     >>> P, n_y, n_u = example_scherer1997_p907
     >>> K, N, gamma, info = dkpy.HinfSynSlicot().synthesize(P, n_y, n_u)
     >>> gamma
-    9.5080
+    9.51
     """
 
     def __init__(self):
@@ -107,7 +107,7 @@ class HinfSynLmi(ControllerSynthesis):
     >>> P, n_y, n_u = example_scherer1997_p907
     >>> K, N, gamma, info = dkpy.HinfSynLmi().synthesize(P, n_y, n_u)
     >>> gamma
-    9.5081
+    9.51
 
     H-infinity controller synthesis with CLARABEL
 
@@ -407,7 +407,7 @@ class HinfSynLmiBisection(ControllerSynthesis):
     ...     },
     ... ).synthesize(P, n_y, n_u)
     >>> gamma
-    9.5093
+    9.51
     """
 
     def __init__(