# upright

**Repository Path**: uloong6/upright

## Basic Information

- **Project Name**: upright
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Balance Car Sim

两轮平衡车仿真 + 强化学习训练框架。

## 架构

```
upright/
├── core/          仿真核心（C 共享库）    → upright.dll
│   ├── upright.c/h           物理 / 传感器 / 执行器调度
│   └── control_law.c/h       仿真与真机共享的控制律
├── gui/           Qt GUI（C++ 可执行）    → Upright.exe
│   ├── car_simulator.cpp/h
│   └── qml/main.qml
├── tools/         CLI 工具 + 验证脚本
│   ├── check_layout.c        ABI 布局检查
│   ├── upright_headless.c    无 GUI 单跑
│   ├── verify_ctypes.py      ctypes/headless 一致性
│   └── diag/                 诊断脚本
├── train/         Python 训练栈
│   ├── upright_ctypes.py     ctypes 绑定
│   ├── evaluate.py           评估（从 Frame 流算指标）
│   └── train.py              Optuna 训练
├── docs/          架构与增益来源
├── legacy/        归档脚本
├── tests/         单元测试（预留）
└── gains.json     运行时增益配置（源码位置）
```

## 分层原则

1. **Core 只做仿真**——物理、传感器、控制律，输出 `UprightFrame`
2. **评估在 Python**——`train/evaluate.py` 从 Frame 流算所有指标
3. **加新指标不改 core**——只改 `evaluate.py` + reward
4. **DR 由 `dr_mask` 统一控制**——10 位掩码（v58: 删未实现的 PWM_QUANT/MASS_FREEZE），`DR_NONE` 完全干净

## 快速开始

**构建**：
```bash
cmake -B build -G "MinGW Makefiles"
cmake --build build
```

产物：

```
build/core/upright.dll
build/gui/Upright.exe
build/tools/check_layout.exe
build/tools/upright_headless.exe
build/gains.json
```

GUI：

```bash
build/gui/Upright.exe
```

增益从 gains.json 读取（exe 同目录优先，上级回退）。

训练：

```bash
cd train
python train.py
```

ABI 自检：

```bash
cd tools
python verify_ctypes.py     # 期望 [layout] OK + [compare] MATCH
```

## 相关文档

- `docs/GAINS_PROVENANCE.md`——增益来源、混合方案、v55 系列失败分析
- `core/control_law.h`——控制律语义
- `core/upright.h`——ABI 定义

## 提交历史约定

- **Core 变更**（core/upright.c/h、core/control_law.c/h）——需重编 dll，破坏历史 trial
- **Python 变更**（train/train.py、train/evaluate.py）——不重编，保持 ABI 兼容
- **UprightResult 字段**——已删除（v56），新指标走 evaluate.py