tunecontrol 0.1.0__tar.gz

tunecontrol-0.1.0/CITATION.cff

@@ -0,0 +1,34 @@
+cff-version: 1.2.0
+message: "If you use TuneControl in your research, please cite the paper below."
+title: TuneControl
+type: software
+version: 0.1.0
+license: MIT
+repository-code: "https://github.com/Data-Science-in-Mechanical-Engineering/tunecontrol"
+authors:
+  - family-names: von Rohr
+    given-names: Alexander
+  - family-names: Menn
+    given-names: Johanna
+  - family-names: Brunzema
+    given-names: Paul
+preferred-citation:
+  type: article
+  title: "A Decade of Bayesian Optimization for Controller Tuning and Robot Learning: Tutorial, Review, and Future Prospects"
+  authors:
+    - family-names: Stenger
+      given-names: David
+    - family-names: Brunzema
+      given-names: Paul
+    - family-names: Menn
+      given-names: Johanna
+    - family-names: von Rohr
+      given-names: Alexander
+    - family-names: Schoellig
+      given-names: Angela P.
+    - family-names: Trimpe
+      given-names: Sebastian
+  year: 2026
+  journal: arXiv
+  doi: "10.48550/arXiv.2609.09403"
+  url: "https://arxiv.org/abs/2609.09403"

tunecontrol-0.1.0/LICENCE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alexander von Rohr, Johanna Menn, Paul Brunzema
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tunecontrol-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CITATION.cff
+recursive-include tests *.py
+include examples/standard_bo_for_controller_tuning.ipynb

tunecontrol-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: tunecontrol
+Version: 0.1.0
+Summary: A benchmark suite for controller tuning.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Data-Science-in-Mechanical-Engineering/tunecontrol
+Project-URL: Issues, https://github.com/Data-Science-in-Mechanical-Engineering/tunecontrol/issues
+Project-URL: Documentation, https://github.com/Data-Science-in-Mechanical-Engineering/tunecontrol/blob/main/README.md
+Project-URL: Paper, https://arxiv.org/abs/2609.09403
+Keywords: controller tuning,bayesian optimization,benchmark,robotics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENCE.txt
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: matplotlib
+Requires-Dist: torch>=2.2
+Provides-Extra: botorch
+Requires-Dist: botorch==0.15.1; extra == "botorch"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# TuneControl
+
+A collection of **black-box controller-tuning problems** with a common
+Python interface. Choose a problem and objective, supply controller gains, and
+receive a scalar cost plus the simulated trajectory.
+
+The collection currently includes CartPole and cascaded tanks, each with several
+objectives and deterministic or noisy configurations. You can use the problems
+with your own optimizer or add a new problem family.
+
+![Controller tuning workflow: gains → controller → simulator → cost](docs/bo_example.png)
+
+## Install
+
+TuneControl currently supports **Python 3.12**. Install from GitHub:
+
+```bash
+python -m pip install "tunecontrol @ git+https://github.com/Data-Science-in-Mechanical-Engineering/tunecontrol.git"
+```
+
+For the Bayesian optimization notebook, include BoTorch:
+
+```bash
+python -m pip install "tunecontrol[botorch] @ git+https://github.com/Data-Science-in-Mechanical-Engineering/tunecontrol.git"
+```
+
+For development from a local checkout, run `python -m pip install -e '.[dev,botorch]'`.
+
+## Evaluate a controller
+
+```python
+from tunecontrol import CartPole, CartPoleConfig
+
+problem = CartPole(CartPoleConfig(dim=2, objective="mae"))
+theta = problem.bounds.mean(dim=0)
+value, info = problem.evaluate(theta)
+
+print(f"Cost: {value.item():.4f}")
+print("Controller:", theta.tolist())
+print("State columns:", info["trajectory"]["state_names"])
+```
+
+Expected output:
+
+```text
+Cost: 8.2734
+Controller: [-40.0, -6.25]
+State columns: ('cart_position', 'cart_velocity', 'pole_angle', 'pole_angular_velocity')
+```
+
+The bounds describe the controller search space; their midpoint is an example
+controller. `info["trajectory"]` contains timestamps, state and input arrays,
+and column names and units. See [evaluate and plot](examples/quickstart.py) to
+visualize both built-in problems.
+
+## Problems
+
+| Family | Controller parameters | Objectives | Standard configurations |
+|---|---|---|---|
+| [CartPole](docs/cartpole_task_doc.md) | 1–4 state-feedback gains | MAE, LQR, ITAE | 24 |
+| [Cascaded tanks](docs/cascaded_tank_task_doc.md) | 2 PI gains | SSE, LogSSE, quadratic, rise time, overshoot | 10 |
+
+Both families provide deterministic and noisy configurations. Standard
+configurations enumerate combinations of dimensions, objectives, and noise;
+custom settings are also supported. The linked problem descriptions define the
+models, objectives, bounds, and sampling conventions.
+
+```python
+import tunecontrol as tc
+
+print(tc.list_problems())  # ['cartpole', 'cascaded_tank']
+configs = tc.available_configs("cartpole")
+problem = tc.make("cartpole", config={"dim": 2, "objective": "mae"})
+```
+
+Direct Python construction and registry construction use the same configurations.
+See [discover and configure](examples/discover_problems.py) for configuration
+serialization and reconstruction.
+
+![Objective landscapes for deterministic two-parameter problems](docs/figures/deterministic_2d_gallery.png)
+
+Darker colors indicate lower cost. White regions mark undefined evaluations.
+
+## Noise and evaluation behavior
+
+Configurations are deterministic by default (`noise=None`). To add process noise
+and CartPole initial-state perturbations, supply a noise configuration:
+
+```python
+from tunecontrol import CartPole, CartPoleConfig, CartPoleNoise
+
+problem = CartPole(CartPoleConfig(dim=2, noise=CartPoleNoise()))
+problem.setup(run_seed=42)
+value, info = problem.evaluate(problem.bounds.mean(dim=0))
+```
+
+Each problem owns its random stream. Successive noisy evaluations advance that
+stream; calling `setup(run_seed=42)` again replays the sequence. Record the family,
+full configuration, package version, and seed when saving an experiment. Seeded
+replay assumes the same software and runtime environment.
+
+`evaluate` accepts a finite floating-point tensor of shape `(problem.dim,)`.
+Gains must lie within the declared bounds, including the endpoints. Out-of-bounds
+gains raise `ValueError` before simulation. Other invalid inputs also raise errors.
+Undefined or nonfinite objectives return `(NaN, info)` with diagnostics preserved.
+Check `torch.isnan(value)` before using a cost in an optimizer. Penalty handling
+belongs to the optimizer or example, rather than the problem itself.
+
+## Examples
+
+Start with [the example guide](examples/README.md). Notebooks include saved outputs
+and plots so you can read them directly on GitHub.
+
+| Example | Purpose |
+|---|---|
+| [Evaluate and plot](examples/quickstart.py) | Run both built-in problems and inspect trajectories |
+| [Discover and configure](examples/discover_problems.py) | List families and save a configuration |
+| [Bayesian optimization](examples/standard_bo_for_controller_tuning.ipynb) | Tune one controller gain with BoTorch |
+| [Add a problem](examples/creating_custom_task.ipynb) | Implement a mass-spring-damper family |
+
+## Contributing
+
+New controller-tuning problems are welcome. Start with the
+[custom-task notebook](examples/creating_custom_task.ipynb) and the
+[family API and contribution guide](docs/task_module_architecture.md).
+Document the model, controller parameters, objective definitions, noise, and
+sampling, and include tests and an example trajectory with your contribution.
+
+## Citation
+TuneControl was introduced in [*A Decade of Bayesian Optimization for Controller Tuning and Robot Learning: Tutorial, Review, and Future Prospects*](https://arxiv.org/abs/2609.09403). Please cite it if TuneControl supports your research.
+
+```bibtex
+@misc{stenger2026decade,
+    title = {A Decade of {Bayesian} Optimization for Controller Tuning and Robot Learning: Tutorial, Review, and Future Prospects},
+    author = {Stenger, David and Brunzema, Paul and Menn, Johanna and von Rohr, Alexander and Schoellig, Angela P. and Trimpe, Sebastian},
+    year = {2026},
+    eprint = {2609.09403},
+    archivePrefix = {arXiv},
+    primaryClass = {cs.RO},
+    doi = {10.48550/arXiv.2609.09403},
+    url = {https://arxiv.org/abs/2609.09403}
+}
+```
+
+## License
+Released under the [MIT License](LICENCE.txt).

tunecontrol-0.1.0/README.md

@@ -0,0 +1,146 @@
+# TuneControl
+
+A collection of **black-box controller-tuning problems** with a common
+Python interface. Choose a problem and objective, supply controller gains, and
+receive a scalar cost plus the simulated trajectory.
+
+The collection currently includes CartPole and cascaded tanks, each with several
+objectives and deterministic or noisy configurations. You can use the problems
+with your own optimizer or add a new problem family.
+
+![Controller tuning workflow: gains → controller → simulator → cost](docs/bo_example.png)
+
+## Install
+
+TuneControl currently supports **Python 3.12**. Install from GitHub:
+
+```bash
+python -m pip install "tunecontrol @ git+https://github.com/Data-Science-in-Mechanical-Engineering/tunecontrol.git"
+```
+
+For the Bayesian optimization notebook, include BoTorch:
+
+```bash
+python -m pip install "tunecontrol[botorch] @ git+https://github.com/Data-Science-in-Mechanical-Engineering/tunecontrol.git"
+```
+
+For development from a local checkout, run `python -m pip install -e '.[dev,botorch]'`.
+
+## Evaluate a controller
+
+```python
+from tunecontrol import CartPole, CartPoleConfig
+
+problem = CartPole(CartPoleConfig(dim=2, objective="mae"))
+theta = problem.bounds.mean(dim=0)
+value, info = problem.evaluate(theta)
+
+print(f"Cost: {value.item():.4f}")
+print("Controller:", theta.tolist())
+print("State columns:", info["trajectory"]["state_names"])
+```
+
+Expected output:
+
+```text
+Cost: 8.2734
+Controller: [-40.0, -6.25]
+State columns: ('cart_position', 'cart_velocity', 'pole_angle', 'pole_angular_velocity')
+```
+
+The bounds describe the controller search space; their midpoint is an example
+controller. `info["trajectory"]` contains timestamps, state and input arrays,
+and column names and units. See [evaluate and plot](examples/quickstart.py) to
+visualize both built-in problems.
+
+## Problems
+
+| Family | Controller parameters | Objectives | Standard configurations |
+|---|---|---|---|
+| [CartPole](docs/cartpole_task_doc.md) | 1–4 state-feedback gains | MAE, LQR, ITAE | 24 |
+| [Cascaded tanks](docs/cascaded_tank_task_doc.md) | 2 PI gains | SSE, LogSSE, quadratic, rise time, overshoot | 10 |
+
+Both families provide deterministic and noisy configurations. Standard
+configurations enumerate combinations of dimensions, objectives, and noise;
+custom settings are also supported. The linked problem descriptions define the
+models, objectives, bounds, and sampling conventions.
+
+```python
+import tunecontrol as tc
+
+print(tc.list_problems())  # ['cartpole', 'cascaded_tank']
+configs = tc.available_configs("cartpole")
+problem = tc.make("cartpole", config={"dim": 2, "objective": "mae"})
+```
+
+Direct Python construction and registry construction use the same configurations.
+See [discover and configure](examples/discover_problems.py) for configuration
+serialization and reconstruction.
+
+![Objective landscapes for deterministic two-parameter problems](docs/figures/deterministic_2d_gallery.png)
+
+Darker colors indicate lower cost. White regions mark undefined evaluations.
+
+## Noise and evaluation behavior
+
+Configurations are deterministic by default (`noise=None`). To add process noise
+and CartPole initial-state perturbations, supply a noise configuration:
+
+```python
+from tunecontrol import CartPole, CartPoleConfig, CartPoleNoise
+
+problem = CartPole(CartPoleConfig(dim=2, noise=CartPoleNoise()))
+problem.setup(run_seed=42)
+value, info = problem.evaluate(problem.bounds.mean(dim=0))
+```
+
+Each problem owns its random stream. Successive noisy evaluations advance that
+stream; calling `setup(run_seed=42)` again replays the sequence. Record the family,
+full configuration, package version, and seed when saving an experiment. Seeded
+replay assumes the same software and runtime environment.
+
+`evaluate` accepts a finite floating-point tensor of shape `(problem.dim,)`.
+Gains must lie within the declared bounds, including the endpoints. Out-of-bounds
+gains raise `ValueError` before simulation. Other invalid inputs also raise errors.
+Undefined or nonfinite objectives return `(NaN, info)` with diagnostics preserved.
+Check `torch.isnan(value)` before using a cost in an optimizer. Penalty handling
+belongs to the optimizer or example, rather than the problem itself.
+
+## Examples
+
+Start with [the example guide](examples/README.md). Notebooks include saved outputs
+and plots so you can read them directly on GitHub.
+
+| Example | Purpose |
+|---|---|
+| [Evaluate and plot](examples/quickstart.py) | Run both built-in problems and inspect trajectories |
+| [Discover and configure](examples/discover_problems.py) | List families and save a configuration |
+| [Bayesian optimization](examples/standard_bo_for_controller_tuning.ipynb) | Tune one controller gain with BoTorch |
+| [Add a problem](examples/creating_custom_task.ipynb) | Implement a mass-spring-damper family |
+
+## Contributing
+
+New controller-tuning problems are welcome. Start with the
+[custom-task notebook](examples/creating_custom_task.ipynb) and the
+[family API and contribution guide](docs/task_module_architecture.md).
+Document the model, controller parameters, objective definitions, noise, and
+sampling, and include tests and an example trajectory with your contribution.
+
+## Citation
+TuneControl was introduced in [*A Decade of Bayesian Optimization for Controller Tuning and Robot Learning: Tutorial, Review, and Future Prospects*](https://arxiv.org/abs/2609.09403). Please cite it if TuneControl supports your research.
+
+```bibtex
+@misc{stenger2026decade,
+    title = {A Decade of {Bayesian} Optimization for Controller Tuning and Robot Learning: Tutorial, Review, and Future Prospects},
+    author = {Stenger, David and Brunzema, Paul and Menn, Johanna and von Rohr, Alexander and Schoellig, Angela P. and Trimpe, Sebastian},
+    year = {2026},
+    eprint = {2609.09403},
+    archivePrefix = {arXiv},
+    primaryClass = {cs.RO},
+    doi = {10.48550/arXiv.2609.09403},
+    url = {https://arxiv.org/abs/2609.09403}
+}
+```
+
+## License
+Released under the [MIT License](LICENCE.txt).