hybrid-automaton

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 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
  • Overview
  • Table of Contents
  • Installation
  • Usage
  • Practical Use Cases
  • Collaborators
  • License

Installation

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

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

📚 For detailed use cases, integration patterns, and best practices, see PRACTICAL_USES.md

Collaborators

This project was created by:

• Ryan McKee

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.

Citation

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

@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 license.