Metadata-Version: 2.4
Name: hybrid-automaton
Version: 1.0.0
Summary: Python framework for real-time and simulation hybrid automata, easily integrable with ROS2 and other environments.
Project-URL: Documentation, https://github.com/rymc-dev/hybrid-automaton#readme
Project-URL: Issues, https://github.com/rymc-dev/hybrid-automaton/issues
Project-URL: Source, https://github.com/rymc-dev/hybrid-automaton
Author-email: Ryan McKee <ryanmckee47@icloud.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: autonomy,hybrid_automaton,navigation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Requires-Dist: lark
Requires-Dist: matplotlib
Requires-Dist: numpy<3,>=1.24
Requires-Dist: pyyaml
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-mock; extra == 'test'
Description-Content-Type: text/markdown

# hybrid-automaton

[![PyPI - Version](https://img.shields.io/pypi/v/hybrid-automaton.svg)](https://pypi.org/project/hybrid-automaton)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hybrid-automaton.svg)](https://pypi.org/project/hybrid-automaton)

-----

| Field         | Value        |
|---------------|--------------|
| Last Updated  | 2026-08-10   |
| Version       | 1.0.0        |

## Overview
Hybrid Automaton is a Python-based framework for simulating and running hybrid automata in both real-time and offline settings. It provides a lightweight, flexible foundation for defining & evaluating custom automata, while remaining easily integrable into real-world technology stacks such as ROS2 or other systems. The design emphasizes simplicity, extensibility, and practical applicability for a wide range of use cases.

This project was created out of necessity for a USV Hybrid Automaton project and is the first implementation of its kind. As of v1.0.0, **it is production-capable for many real-world applications** including robotics, industrial control, building automation, and more. See [Practical Use Cases](#practical-use-cases) below for detailed information.

**Framework Status**: v1.0.0 - Stable API, ready for production use in non-safety-critical applications with proper testing.

If you have ideas for improvement or want to contribute, please reach out and become a collaborator!

## Table of Contents

- [hybrid-automaton](#hybrid-automaton)
  - [Overview](#overview)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
  - [Usage](#usage)
  - [Practical Use Cases](#practical-use-cases)
  - [Collaborators](#collaborators)
  - [License](#license)

## Installation

```console
pip install hybrid-automaton
```

## Usage

Below is a sample of how one of the demonstration hybrid automaton (`bouncing ball`) definitions are ran in simulation mode. The definition of the Automaton
using the framework can be found here: [bouncing ball automaton definition](./src/hybrid_automatons/bouncing_ball.py)

```python
import os
import numpy as np

from hybrid_automatons import bouncing_ball
from hybrid_automaton import Automaton, RunResult, RuntimeContext

ContinuousState = RuntimeContext.ContinuousState

ha: Automaton = bouncing_ball(gravity=-9.81, restitution=0.8)
results: RunResult = await ha.activate(
    initial_continuous_state=ContinuousState(
        "bouncing_ball_state",
        x0=np.array([5.0, 0.0]),
        x_labels=['height', 'velocity'],
    ),
    enable_real_time_mode=False,
    continuous_state_sampler_enabled=True,
    continuous_state_sampler_rate=100,
    enable_self_integration=True,
    delta_time=0.001,
    timeout_sec=30.0,
    output_dir=os.path.join(os.getcwd(), 'logs', 'bouncing_ball_run')
)
print(results)
```

## Practical Use Cases

**Is this framework ready for real-world use?** Yes! As of v1.0.0, hybrid-automaton is production-capable for many applications.

### Key Applications

This framework excels in domains requiring both continuous dynamics and discrete state management:

- **🚗 Autonomous Vehicles & Robotics**: Cruise control, USV navigation, drone flight controllers
- **🏭 Industrial Control**: HVAC systems, batch processing, conveyor control
- **🏢 Building Automation**: Smart thermostats, traffic lights, elevator systems  
- **⚡ Energy Management**: Battery management, microgrid control, EV charging
- **🎓 Education & Research**: Hybrid systems theory, control algorithm prototyping
- **🏥 Medical Devices**: Infusion pumps, ventilators (with proper validation)

### Framework Strengths

- ✅ **ROS2 Integration Ready** - Designed for robotics stacks
- ✅ **Real-Time & Simulation Modes** - Test offline, deploy online
- ✅ **Async-Native** - Built with Python asyncio for modern concurrent systems
- ✅ **Well-Tested** - Comprehensive test suite included
- ✅ **Rich Examples** - Bouncing ball, cruise control, thermostat, traffic lights

### Maturity Assessment

| Use Case | Status | Recommendation |
|----------|--------|----------------|
| Academic/Research | ✅ Ready | Excellent for prototyping and learning |
| Robotics Prototyping | ✅ Ready | Great for ROS2 projects, test thoroughly |
| Industrial Automation | ⚠️ Pilot Projects | Start with non-critical systems |
| Production Systems | ⚠️ With Caution | Pin versions, extensive validation |

**📚 For detailed use cases, integration patterns, and best practices, see [PRACTICAL_USES.md](./PRACTICAL_USES.md)**

## Collaborators

This project was created by:
- **[Ryan McKee](https://github.com/rymc-dev)**

### Contributing

We welcome contributions! This is an active project and the first open-source framework of its kind for hybrid automata in Python. Whether you're interested in:

- 🐛 Reporting bugs or suggesting features
- 📝 Improving documentation or examples  
- 🔧 Contributing code improvements
- 🧪 Adding test coverage
- 🎓 Using it in research or teaching

Please open an issue or pull request on [GitHub](https://github.com/rymc-dev/hybrid-automaton).

### Citation

Please cite this package as described below if used in research:

```bibtex
@misc{hybrid_automaton_2026,
  author       = {Ryan McKee},
  title        = {hybrid-automaton v1.0.0},
  howpublished = {GitHub repository},
  year         = {2026},
  note         = {Accessed: Aug. 10, 2026},
  url          = {https://github.com/rymc-dev/hybrid-automaton}
}
```

## License

`hybrid-automaton` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
