Expose public API and rename hankel_matrix.py (#46)

* Expose public API in `__init__.py` files

* Update modules and scripts to use public API

* Rename `hankel_matrix.py` to `hankel_matrix_utils.py`

- Rename the module to prevent name conflicts with the
  `hankel_matrix()` function within it.
- Update docs to align with the module rename.

This ensures correct docs building with Sphinx and avoids confusion
for users.

Author: pavelacamposp

README.md

@@ -187,7 +187,7 @@ The project is structured as a Python package, encapsulating the core logic of t
 - [`direct_data_driven_mpc/lti_data_driven_mpc_controller.py`](direct_data_driven_mpc/lti_data_driven_mpc_controller.py): Implements a Data-Driven MPC controller for LTI systems in the `LTIDataDrivenMPCController` class. This implementation is based on the **Nominal and Robust Data-Driven MPC schemes** described in [[1]](#1).
 - [`direct_data_driven_mpc/nonlinear_data_driven_mpc_controller.py`](direct_data_driven_mpc/nonlinear_data_driven_mpc_controller.py): Implements a Data-Driven MPC controller for nonlinear systems in the `NonlinearDataDrivenMPCController` class. This implementation is based on the **Nonlinear Data-Driven MPC scheme** described in [[2]](#2).
 
-The utility module [`direct_data_driven_mpc/utilities/hankel_matrix.py`](direct_data_driven_mpc/utilities/hankel_matrix.py) is used for constructing Hankel matrices and evaluating whether data sequences are persistently exciting of a given order.
+The utility module [`direct_data_driven_mpc/utilities/hankel_matrix_utils.py`](direct_data_driven_mpc/utilities/hankel_matrix_utils.py) is used for constructing Hankel matrices and evaluating whether data sequences are persistently exciting of a given order.
 
 ### Model Simulation
 The following utility modules have been implemented to simulate LTI and nonlinear systems:

direct_data_driven_mpc/__init__.py

@@ -0,0 +1,22 @@
+"""
+Implementation of data-driven MPC controllers for Linear Time-Invariant (LTI)
+and nonlinear systems.
+"""
+
+from .lti_data_driven_mpc_controller import (
+    LTIDataDrivenMPCController,
+    LTIDataDrivenMPCType,
+    SlackVarConstraintType,
+)
+from .nonlinear_data_driven_mpc_controller import (
+    AlphaRegType,
+    NonlinearDataDrivenMPCController,
+)
+
+__all__ = [
+    "LTIDataDrivenMPCController",
+    "LTIDataDrivenMPCType",
+    "SlackVarConstraintType",
+    "AlphaRegType",
+    "NonlinearDataDrivenMPCController",
+]

direct_data_driven_mpc/lti_data_driven_mpc_controller.py

@@ -3,7 +3,7 @@
 import cvxpy as cp
 import numpy as np
 
-from direct_data_driven_mpc.utilities.hankel_matrix import (
+from direct_data_driven_mpc.utilities import (
     evaluate_persistent_excitation,
     hankel_matrix,
 )

direct_data_driven_mpc/nonlinear_data_driven_mpc_controller.py

@@ -3,7 +3,7 @@
 import cvxpy as cp
 import numpy as np
 
-from direct_data_driven_mpc.utilities.hankel_matrix import (
+from direct_data_driven_mpc.utilities import (
     evaluate_persistent_excitation,
     hankel_matrix,
 )

direct_data_driven_mpc/utilities/__init__.py

@@ -0,0 +1,23 @@
+from .hankel_matrix_utils import (
+    evaluate_persistent_excitation,
+    hankel_matrix,
+)
+from .initial_state_estimation import (
+    calculate_equilibrium_input_from_output,
+    calculate_equilibrium_output_from_input,
+    estimate_initial_state,
+    observability_matrix,
+    toeplitz_input_output_matrix,
+)
+from .yaml_config_loading import load_yaml_config_params
+
+__all__ = [
+    "evaluate_persistent_excitation",
+    "hankel_matrix",
+    "calculate_equilibrium_input_from_output",
+    "calculate_equilibrium_output_from_input",
+    "estimate_initial_state",
+    "observability_matrix",
+    "toeplitz_input_output_matrix",
+    "load_yaml_config_params",
+]

direct_data_driven_mpc/utilities/controller/__init__.py

@@ -0,0 +1,39 @@
+"""
+Functions and classes for creating data-driven MPC controllers for both Linear
+Time-Invariant (LTI) and nonlinear systems, and for simulating their
+corresponding control loops.
+"""
+
+from .controller_creation import (
+    create_lti_data_driven_mpc_controller,
+    create_nonlinear_data_driven_mpc_controller,
+)
+from .controller_params import (
+    LTIDataDrivenMPCParams,
+    NonlinearDataDrivenMPCParams,
+    get_lti_data_driven_mpc_controller_params,
+    get_nonlinear_data_driven_mpc_controller_params,
+)
+from .data_driven_mpc_sim import (
+    simulate_lti_data_driven_mpc_control_loop,
+    simulate_nonlinear_data_driven_mpc_control_loop,
+)
+from .initial_data_generation import (
+    generate_initial_input_output_data,
+    randomize_initial_system_state,
+    simulate_n_input_output_measurements,
+)
+
+__all__ = [
+    "create_lti_data_driven_mpc_controller",
+    "create_nonlinear_data_driven_mpc_controller",
+    "LTIDataDrivenMPCParams",
+    "NonlinearDataDrivenMPCParams",
+    "get_lti_data_driven_mpc_controller_params",
+    "get_nonlinear_data_driven_mpc_controller_params",
+    "simulate_lti_data_driven_mpc_control_loop",
+    "simulate_nonlinear_data_driven_mpc_control_loop",
+    "generate_initial_input_output_data",
+    "randomize_initial_system_state",
+    "simulate_n_input_output_measurements",
+]

direct_data_driven_mpc/utilities/controller/controller_creation.py

@@ -8,13 +8,12 @@
 
 import numpy as np
 
-from direct_data_driven_mpc.lti_data_driven_mpc_controller import (
+from direct_data_driven_mpc import (
     LTIDataDrivenMPCController,
-)
-from direct_data_driven_mpc.nonlinear_data_driven_mpc_controller import (
     NonlinearDataDrivenMPCController,
 )
-from direct_data_driven_mpc.utilities.controller.controller_params import (
+
+from .controller_params import (
     LTIDataDrivenMPCParams,
     NonlinearDataDrivenMPCParams,
 )

direct_data_driven_mpc/utilities/controller/controller_params.py

@@ -10,14 +10,12 @@
 
 import numpy as np
 
-from direct_data_driven_mpc.lti_data_driven_mpc_controller import (
+from direct_data_driven_mpc import (
+    AlphaRegType,
     LTIDataDrivenMPCType,
     SlackVarConstraintType,
 )
-from direct_data_driven_mpc.nonlinear_data_driven_mpc_controller import (
-    AlphaRegType,
-)
-from direct_data_driven_mpc.utilities.yaml_config_loading import (
+from direct_data_driven_mpc.utilities import (
     load_yaml_config_params,
 )
 

direct_data_driven_mpc/utilities/controller/data_driven_mpc_sim.py

@@ -11,14 +11,12 @@
 from numpy.random import Generator
 from tqdm import tqdm
 
-from direct_data_driven_mpc.lti_data_driven_mpc_controller import (
+from direct_data_driven_mpc import (
     LTIDataDrivenMPCController,
-)
-from direct_data_driven_mpc.nonlinear_data_driven_mpc_controller import (
     NonlinearDataDrivenMPCController,
 )
-from direct_data_driven_mpc.utilities.models.lti_model import LTIModel
-from direct_data_driven_mpc.utilities.models.nonlinear_model import (
+from direct_data_driven_mpc.utilities.models import (
+    LTIModel,
     NonlinearSystem,
 )
 

direct_data_driven_mpc/utilities/controller/initial_data_generation.py

@@ -8,14 +8,15 @@
 import numpy as np
 from numpy.random import Generator
 
-from direct_data_driven_mpc.utilities.controller.controller_params import (
+from direct_data_driven_mpc.utilities.models import (
+    LTIModel,
+    NonlinearSystem,
+)
+
+from .controller_params import (
     DataDrivenMPCParams,
     LTIDataDrivenMPCParams,
 )
-from direct_data_driven_mpc.utilities.models.lti_model import LTIModel
-from direct_data_driven_mpc.utilities.models.nonlinear_model import (
-    NonlinearSystem,
-)
 
 
 def randomize_initial_system_state(