Metadata-Version: 2.4
Name: eagle-rock
Version: 5.0.0rc5
Summary: Hybrid rocket conceptual-design and simulation platform: propulsion, aerodynamics, trajectory, structures, validation, CAD export, and a PyQt6 GUI.
License: Apache-2.0
Project-URL: Homepage, https://github.com/zylvex-tech/eagle-rock
Project-URL: Documentation, https://github.com/zylvex-tech/eagle-rock/blob/main/docs/SOFTWARE_MANUAL.md
Project-URL: Source, https://github.com/zylvex-tech/eagle-rock
Project-URL: BugTracker, https://github.com/zylvex-tech/eagle-rock/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: PyQt6>=6.5
Provides-Extra: cantera
Requires-Dist: cantera>=3.0; extra == "cantera"
Provides-Extra: cad
Requires-Dist: pythonocc-core>=7.7; extra == "cad"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

﻿
![Eagle Rock](assets/banner.png)

# Eagle Rock — Professional Aerospace Engineering Platform

**Hybrid rocket design • Simulation • CAD • Manufacturing • Validation • AI Copilot**

[![Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python)](https://python.org)
[![CI: Test](https://github.com/zylvex-tech/eagle-rock/actions/workflows/test.yml/badge.svg)](https://github.com/zylvex-tech/eagle-rock/actions/workflows/test.yml)
[![CI: Lint](https://github.com/zylvex-tech/eagle-rock/actions/workflows/lint.yml/badge.svg)](https://github.com/zylvex-tech/eagle-rock/actions/workflows/lint.yml)
[![Tests](https://img.shields.io/badge/Tests-39%20passing-brightgreen)](#testing)
[![Release](https://img.shields.io/badge/Release-v5.0.0--rc1-orange)](https://github.com/zylvex-tech/eagle-rock/releases)
[![Documentation](https://img.shields.io/badge/docs-latest-blue)](docs/)
[![DOI](https://img.shields.io/badge/DOI-pending-lightgrey)](CITATION.cff)

---

Eagle Rock is a modular, open-source, **deterministic** aerospace engineering platform for conceptual and preliminary design of hybrid sounding rockets. It covers the full engineering lifecycle: **mission definition → vehicle design → propulsion → aerodynamics → stability → structures → mass budget → trajectory performance → recovery → avionics → ground systems → test stand → Monte Carlo → optimization → validation → reports**.

Built as a modern successor to UKZN ASRI's **HYROPS** (Chowdhury 2012) and **PyROPS** (Slabber et al. 2024), Eagle Rock adds a full GUI, manufacturing support, CAD export, and AI-assisted design review — all while keeping engineering calculations fully deterministic and transparent.

---

## Features

| Domain | Capabilities |
|--------|-------------|
| **Propulsion** | Hybrid motor design (N₂O/paraffin, N₂O/HTPB, LOX). Regression rate models (Marxman, Karabeyoglu). Equilibrium & frozen-flow thermochemistry. Blowdown & pressure-fed feed systems. |
| **Aerodynamics** | Barrowman CP/CNα. ISA atmosphere (0–86 km). Drag buildup (body, fins, interference). Compressibility corrections. |
| **Trajectory** | 3-DOF (point mass) & 6-DOF (rigid body) simulators. Variable-mass. Spherical Earth. Wind profiles. Thrust misalignment. |
| **Structures** | Mass budget with CG tracking. Cylindrical, spherical, and composite tank mass. Structural safety factors. |
| **CAD** | Parametric SVG, DXF, STEP export of airframe, fins, bulkheads, motor case, tank. |
| **Manufacturing** | BOM generation, part numbering, fastener schedules, engineering spec sheets. |
| **Validation** | Workspace comparing simulation against published Phoenix flight data. Cases with known motor parameters are simulated like-for-like; others are flagged NO_DATA. Error metrics and PASS/REVIEW status. |
| **Design Reviews** | SRR → PDR → CDR → FRR with auto-populated findings from current design state. |
| **RVM** | Requirements Verification Matrix — auto-check design against mission requirements. |
| **Monte Carlo** | Statistical dispersion analysis with configurable input distributions. |
| **Optimization** | Single- and multi-objective (NSGA-II) with configurable constraints. |
| **AI Copilot** | Optional LLM interface (OpenAI / Anthropic / Gemini) for design guidance — never modifies project data without confirmation. |
| **Plugin System** | Hook-based plugin framework with discovery, validation, and dependency resolution. |
| **Learning Center** | Curated beginner → intermediate → advanced learning paths with interactive tutorials. |
| **Collaboration** | Review comments, change requests, approvals, design history. |
| **Engineering Database** | 9+ structural materials, component properties, design limits. |

---

## Architecture

```
eagle-rock/                 # git repository (GitHub: zylvex-tech/eagle-rock)
├── pyproject.toml          # packaging / build config
├── eagle_rock/             # importable Python package
│   ├── core/               # Engineering engine (deterministic, no-GUI dependencies)
│   │   ├── propulsion/     #   Hybrid motor, thermochemistry, feed systems
│   │   ├── aerodynamics/   #   Barrowman, drag, atmosphere
│   │   ├── trajectory/     #   3-DOF & 6-DOF integrators
│   │   ├── structures/     #   Mass budget, tank mass, composites
│   │   ├── vehicle.py      #   Vehicle assembly
│   │   ├── project.py      #   Central data model with dependency tracking
│   │   ├── validation/     #   Flight data, comparison, dashboard
│   │   ├── database/       #   Material and component database
│   │   ├── simulation/     #   Background job runner
│   │   ├── monte_carlo/    #   Statistical dispersion
│   │   ├── optimization/   #   Single & multi-objective
│   │   ├── collaboration/  #   Review, comments, approvals
│   │   ├── plugins/        #   Plugin framework
│   │   ├── reports/        #   Design reviews, spec sheets, RVM
│   │   ├── cad/            #   Parametric export (SVG/DXF/STEP)
│   │   ├── manufacturing/  #   BOM, part numbers, fastener schedule
│   │   ├── learning/       #   Learning center content
│   │   └── ai/             #   AI Copilot abstraction
│   ├── gui/                # PyQt6 application
│   │   ├── main_window.py  #   7 workspaces, 28 tabs
│   │   ├── tabs/           #   Individual tab panels
│   │   └── widgets/        #   Reusable widgets
│   ├── examples/           # Example scripts
│   └── tests/              # Unit & integration tests
├── docs/                   # Documentation
├── tutorials/              # Interactive tutorials (in progress)
├── benchmarks/             # Performance benchmarks (planned)
├── scripts/                # Utility scripts (planned)
├── assets/                # Images, icons, screenshots
└── .github/                # CI workflows, templates
```

### Workspaces (7)

| Workspace | Tabs |
|-----------|------|
| **Design** | Mission → Propulsion → Aerodynamics → Stability → Structures → Mass Budget |
| **Analysis** | Trajectory → Recovery → Avionics → Ground Systems → Test Stand |
| **Engineering** | Performance → Monte Carlo → Optimization → Reports |
| **Operations** | Validation → RVM → Design Reviews → Spec Sheets |
| **Learning** | Learning Center → Tutorials → Engineering Database |
| **Project** | Collaboration → Export → Manufacturing → CAD |
| **Admin** | Settings → Plugin Manager → AI Copilot |

---

## Quick Start

### Prerequisites

- Python 3.10+
- pip

### Install (editable, recommended for development)

```bash
pip install -e .
```

Or install from a built wheel:

```bash
pip install eagle_rock-5.0.0rc1-py3-none-any.whl
```

Optional high-fidelity chemistry:

```bash
pip install cantera
```

### Run the GUI

After installation, launch from the command line:

```bash
eagle-rock
```

Or run the module directly:

```bash
python -m eagle_rock.gui.main_window
```

### Run the example script

```bash
python -m eagle_rock.examples.eagle_rock_demo
```

Output shows motor performance, 3-DOF/6-DOF trajectory results, and validation comparison against published Phoenix-1B flight data.

### Run tests

```bash
pip install -e ".[dev]"
python -m pytest
# 23+ tests, all passing
```

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Software Manual](docs/SOFTWARE_MANUAL.md) | Installation, configuration, and workflow guide |
| [Design Handbook](docs/DESIGN_HANDBOOK.md) | Hybrid rocket design theory and practice |
| [User Guide](docs/user/) | Workspace-by-workspace walkthrough |
| [Developer Guide](docs/developer/) | Architecture, plugins, SDK, contribution |
| [API Reference](docs/api/) | Full module API documentation |
| [Theory Manual](docs/theory/) | Governing equations, numerical methods |
| [Validation Handbook](docs/validation/) | Validation cases, assumptions, limitations |
| [Architecture Overview](docs/architecture/) | System design, data flow, dependency graph |
| [Manufacturing Guide](docs/manufacturing/) | BOM, part numbering, assembly instructions |
| [Tutorials](tutorials/) | Step-by-step design examples |

---

## Example Workflow

```python
from eagle_rock.core.propulsion.hybrid_motor import HybridMotor, FeedSystem
from eagle_rock.core.structures.structures import MassBudget
from eagle_rock.core.vehicle import Vehicle
from eagle_rock.core.trajectory.integrators import simulate_3dof

# 1. Design motor
feed = FeedSystem("fixed_flow", mdot_ox=2.0)
motor = HybridMotor(oxidizer="N2O", fuel="PARAFFIN",
                    grain_length=0.6, port_radius=0.030,
                    throat_diameter=0.045, expansion_ratio=6.0, feed=feed,
                    initial_ox_mass=31.0)

# 2. Build mass budget
mb = MassBudget()
mb.add("Motor", 12.0, 2.4).add("Payload", 1.0, 0.9).add("Fins", 2.0, 4.0)

# 3. Assemble vehicle
geo = dict(length=4.2, diameter=0.164, Xn=0.9, Xb=4.0,
           Lf=0.45, Lr=0.30, Lt=0.18, Nf=4, Sf=0.045)
veh = Vehicle(motor, mb, geo)

# 4. Simulate
res = simulate_3dof(veh, rail_length=5.0, launch_lat=-34.0)
print(f"Apogee: {res['apogee']/1000:.2f} km")
```

See the full example at [`examples/eagle_rock_demo.py`](examples/eagle_rock_demo.py).

---

## Screenshots

*(Screenshots to be added — the GUI is fully functional. See the [User Guide](docs/user/) for detailed walkthroughs with screen captures.)*

| Workspace | Preview |
|-----------|---------|
| **Design Workspace** | Mission → Propulsion → Aerodynamics → Stability → Structures → Mass Budget |
| **Engineering Workspace** | Performance plots, Monte Carlo histograms, optimization Pareto fronts |
| **Operations Workspace** | Validation comparison, RVM status, design review findings |
| **CAD Workspace** | SVG/DXF/STEP parametric export preview |
| **Learning Center** | Curated learning paths with progress tracking |

---

## Validation Philosophy

Eagle Rock separates **deterministic engineering calculations** from **AI-assisted guidance**.

- **Engineering modules** are purely deterministic — same inputs always produce the same outputs. No ML models are embedded in the physics pipeline.
- **Validation** compares simulation output against published flight data with explicit error metrics. Results are marked PASS / REVIEW / FAIL based on configurable thresholds.
- **AI Copilot** is advisory only. It reads the current Project state and offers suggestions, but never modifies project data without explicit user confirmation.
- **Limitations** are documented alongside each validation case. Users must understand the domain of applicability before relying on results for flight hardware.

---

## Roadmap

| Release | Focus |
|---------|-------|
| **v5.0.0-rc1** (current) | Core physics, 28-tab GUI, validation dashboard, AI Copilot, plugin framework, CAD export, manufacturing BOM |
| **v5.0.0-rc2** | Expanded validation (multiple reference cases), full documentation, performance benchmarks, CI/CD, packaging |
| **v5.0.0 stable** | Production-ready for education, research, and conceptual design |
| **v5.1** | CFD improvements, additional propulsion models, more AI workflows, expanded CAD |
| **v6.0** | Multi-user collaboration, plugin marketplace, certification paths |

See [ROADMAP.md](ROADMAP.md) and [CHANGELOG.md](CHANGELOG.md) for details.

---

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

### Areas we need help with

- Adding validation cases from published flight data
- Writing documentation and tutorials
- Performance optimization of simulation kernels
- Testing on non-Windows platforms
- GUI usability improvements
- Plugin development

---

## Security

See [SECURITY.md](SECURITY.md) for our security policy.

Eagle Rock is an engineering analysis tool. It does not:
- Collect personal data
- Make network requests without explicit user action
- Execute untrusted code

---

## License

Copyright 2026 Eagle Rock Project

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

---

## Citation

If you use Eagle Rock in your research, please cite:

```bibtex
@software{eagle_rock_2026,
  title = {Eagle Rock: Professional Aerospace Engineering Platform},
  version = {5.0.0-rc1},
  url = {https://github.com/zylvex-tech/eagle-rock}
}
```

See [CITATION.cff](CITATION.cff) for machine-readable citation metadata.

---

## Acknowledgements

Eagle Rock builds on decades of hybrid rocket research. In particular:

- **HYROPS** (Chowdhury, 2012) — UKZN ASRI's original hybrid rocket optimization and simulation tool
- **PyROPS** (Slabber, 2024) — Python port of HYROPS
- **Phoenix Program** (UKZN ASRI) — Flight data used for validation
- **Marxman & Gilbert** (1963) — Turbulent boundary-layer regression model
- **Karabeyoglu et al.** (2001) — Liquefying fuel regression model
- **Barrowman** (1967) — Aerodynamic stability method

---

*Made for the hybrid rocket community.*

