# tjdx

**Repository Path**: 9open/tjdx

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-31
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🧠 NetPyNE UI - 独立后端版本

[![Phase 1](https://img.shields.io/badge/Phase%201-Complete-brightgreen)](./项目完成总结.md)
[![Tests](https://img.shields.io/badge/Tests-6%2F6%20Passing-brightgreen)](./test_fixes.py)
[![Docs](https://img.shields.io/badge/Docs-8%20Files-blue)](./文档索引.md)

这是 NetPyNE UI 的独立后端实现，使用 FastAPI 替代原有的 Jupyter/Geppetto 架构。

**最新更新**: Phase 1 (P0) 核心功能修复完成 ✅ (2026-01-24)

---

## 🎯 快速导航

- 🚀 [快速开始](#快速开始)
- 📖 [文档索引](./文档索引.md)
- 🧪 [运行测试](#运行测试)
- 📊 [项目状态](#项目状态)
- 🔧 [最新修复](#最新修复-phase-1)

---

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 启动后端

```bash
python api_server.py
```

或使用批处理文件：

```bash
run_api.bat
```

### 3. 启动前端

```bash
cd frontend
npm install
npm run dev
```

或使用批处理文件：

```bash
run_frontend.bat
```

### 4. 访问应用

- 🌐 后端 API: http://localhost:5000
- 📚 API 文档: http://localhost:5000/api/docs
- 🎨 前端界面: http://localhost:5173

---

## 🧪 运行测试

```bash
python test_fixes.py
```

**预期结果**: 6/6 测试通过 ✅

---

## 📊 项目状态

### Phase 1 (P0) - 核心功能 ✅
- ✅ 状态检测 - `do_i_have_inst_or_sim_data()`
- ✅ 数据清理 - `clear_all()`
- ✅ 类型转换 - `ensure_types()`
- ✅ 参数验证 - `validate_netParams()`
- ✅ 深拷贝过滤 - `deepcopy_wout_empty()`
- ✅ 异常类 - `NetpyneValidationError`
- ✅ 完整导入流程 - `import_model_from_python()`
- ✅ pt3d 判断和绘制

**完成度**: 8/8 (100%)

### Phase 2 (P1) - 完整流程 ⏳
- ❌ loadModel() 完整流程
- ❌ _create3D_shapes()
- ⚠️ simulate() 完善
- ❌ 环境检测
- ❌ 子进程管理

**完成度**: 0/5 (0%)

---

## 🔧 最新修复 (Phase 1)

### 核心改进

1. **完整的清理逻辑**
   - 实现 `clear_all()` 方法
   - 清理 NetPyNE、NEURON 和内部数据
   - 避免旧数据干扰新模型

2. **自动类型转换**
   - 实现 `ensure_types()` 方法
   - 自动转换 dict → specs.NetParams/SimConfig
   - 减少类型错误

3. **参数验证**
   - 实现 `validate_netParams()` 方法
   - 提前发现错误
   - 提供清晰的错误消息

4. **完整的导入流程**
   - 完善 `import_model_from_python()` 方法
   - 7步完整流程（清理→初始化→导入→转换→修正→保存→实例化）
   - 一键完成所有操作

### 增强功能

- ✅ 自动修正空间参数（sizeY, yRange）
- ✅ 自动保存到项目
- ✅ 自动实例化网络

**详细信息**: 查看 [修复完成报告](./NetPyNE-UI修复完成报告.md)

---

## 📖 文档

### 快速参考
- 📋 [快速参考](./快速参考.md) - 快速查阅的参考卡片
- 📚 [文档索引](./文档索引.md) - 所有文档的索引和导航

### 分析文档
- 🔍 [完整分析综合文档](./NetPyNE-UI完整分析综合文档.md) - 13 个核心判断点
- 🔍 [补充判断逻辑分析](./NetPyNE-UI补充判断逻辑分析.md) - 10 个补充判断点

### 实施文档
- 📝 [完整移植实施计划](./NetPyNE-UI完整移植实施计划.md) - 详细实施步骤
- 📝 [修复完成报告](./NetPyNE-UI修复完成报告.md) - 已完成功能清单

### 使用文档
- 📖 [修复使用指南](./NetPyNE-UI修复使用指南.md) - 详细使用说明
- 📖 [修复总结](./NetPyNE-UI修复总结.md) - 项目总体概览
- 📖 [项目完成总结](./项目完成总结.md) - 完整的项目总结

---

## 🏗️ 项目结构

```
newproject/
├── api/                    # API 路由和服务
│   ├── __init__.py
│   ├── core.py            # 核心服务层 ⭐ (已修复)
│   ├── model.py           # 模型管理
│   ├── network.py         # 网络结构
│   ├── simulations.py     # 仿真管理
│   └── plots.py           # 绘图功能
├── data/                  # 数据目录
│   ├── projects/          # 项目数据
│   └── workpath/          # 工作路径（包含 gui_tut*.py）
├── frontend/              # 前端（Vite + React）
├── 📚 文档/               # 修复文档（8 个）
│   ├── NetPyNE-UI完整分析综合文档.md
│   ├── NetPyNE-UI补充判断逻辑分析.md
│   ├── NetPyNE-UI完整移植实施计划.md
│   ├── NetPyNE-UI修复完成报告.md
│   ├── NetPyNE-UI修复使用指南.md
│   ├── NetPyNE-UI修复总结.md
│   ├── 快速参考.md
│   └── 文档索引.md
├── test_fixes.py          # 测试脚本 ⭐ (新增)
├── api_server.py          # FastAPI 入口
├── config.py              # 配置文件
└── README.md              # 本文件
```

---

## 🎓 主要功能

### 模型管理
- ✅ 导入模型（Python 文件）
- ✅ 导出模型（HLS）
- ✅ 保存/加载模型
- ✅ 项目管理

### 网络管理
- ✅ 网络实例化
- ✅ 3D 网络拓扑可视化
- ✅ 细胞形态渲染（pt3d）
- ✅ 连接可视化

### 仿真管理
- ✅ 运行仿真
- ✅ 状态检测
- ✅ 数据收集

### 数据可视化
- ✅ Raster 图
- ✅ Traces 图
- ✅ Spike Histogram
- ✅ LFP 图
- ✅ 2D 网络图
- ✅ 连接图

---

## 🔌 API 端点

### 模型管理
- `GET /api/v1/model` - 获取当前模型
- `POST /api/v1/model/import` - 导入模型 ⭐ (已修复)
- `POST /api/v1/model/save` - 保存模型
- `POST /api/v1/model/load` - 加载模型

### 网络管理
- `GET /api/v1/network` - 获取网络结构
- `POST /api/v1/network/instantiate` - 实例化网络 ⭐ (已修复)
- `GET /api/v1/network/topology` - 获取网络拓扑
- `GET /api/v1/network/status` - 获取网络状态 ⭐ (已修复)

### 仿真管理
- `POST /api/v1/simulations/run` - 运行仿真
- `GET /api/v1/simulations/status` - 获取仿真状态

### 绘图
- `POST /api/v1/plots/{plot_name}` - 生成指定类型的图表

---

## 💻 技术栈

### 后端
- **FastAPI** - Web 框架
- **TJDX (NetPyNE)** - 神经网络仿真
- **NEURON** - 神经元模拟器
- **Plotly** - 交互式绘图

### 前端
- **Vite** - 构建工具
- **React** - UI 框架
- **TypeScript** - 类型安全
- **Three.js** - 3D 可视化

---

## 🔄 与原版的对比

### 架构变化
- ❌ 移除 Jupyter Notebook 依赖
- ❌ 移除 Geppetto 框架
- ✅ 使用 FastAPI 提供 RESTful API
- ✅ 使用 Vite 构建现代前端

### 功能兼容性
- ✅ 保持与原版 NetPyNE-UI 的功能兼容
- ✅ 完全匹配原版的判断逻辑
- ✅ 增加 3 项增强功能

### 代码质量
- ✅ 更清晰的代码结构
- ✅ 完善的文档体系
- ✅ 自动化测试

---

## 🛠️ 开发说明

### 代码修复流程

1. **分析原版代码**
   - 阅读 NetPyNE-UI 源代码
   - 识别判断逻辑和关键流程
   - 整理成分析文档

2. **实施修复**
   - 按优先级实施（P0 → P1 → P2）
   - 编写代码和注释
   - 创建实施文档

3. **测试验证**
   - 编写测试用例
   - 运行自动化测试
   - 验证与原版行为一致

4. **文档编写**
   - 创建使用文档
   - 编写总结报告
   - 整理文档索引

### 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📞 获取帮助

### 常见问题
查看 [修复使用指南](./NetPyNE-UI修复使用指南.md) 的"常见问题"部分

### 技术支持
- **使用问题**: 查看使用文档
- **实施问题**: 查看实施文档
- **原理问题**: 查看分析文档

---

## 📜 许可证

MIT License

---

## 🙏 致谢

感谢原版 NetPyNE-UI 团队的优秀工作，为我们提供了完整的参考实现。

---

## 📅 更新日志

### v1.0 (2026-01-24) - Phase 1 完成
- ✅ 实现 8 个核心功能
- ✅ 创建 8 个完整文档
- ✅ 编写 6 个测试用例
- ✅ 100% 测试通过率

### 下一步
- ⏳ Phase 2 (P1) - 完整流程功能
- ⏳ Phase 3 (P2) - 优化增强功能

---

## 新增：统一UI系统 (2024)

### 前端功能模块

本项目新增了5个统一设计的功能模块，采用模板驱动架构：

#### 1. 机器人臂控制
- 路由: `/robot-arm`
- 功能: 多自由度关节控制与运动学习
- 参数: 关节数、学习率、迭代次数、目标位置

#### 2. 神经网络模拟
- 路由: `/neural-simulation`
- 功能: 生物神经网络动态行为仿真
- 参数: 神经元数、模拟时间、连接概率、放电阈值

#### 3. 手写数字识别
- 路由: `/mnist`
- 功能: MNIST深度学习任务
- 参数: 训练轮数、批次大小、学习率、隐层单元数

#### 4. 运动学习
- 路由: `/motor-learning`
- 功能: 自适应运动控制学习
- 参数: 训练时长、学习率、试验次数、噪声水平

#### 5. 乒乓球游戏
- 路由: `/pingpong-game`
- 功能: 强化学习智能体训练
- 参数: 训练轮数、学习率、折扣因子、批次大小

### 核心架构

```
UnifiedFunctionalPage (模板组件)
├── 动态参数配置
├── 实时进度显示
├── 任务结果展示
└── API交互管理

配置驱动的页面开发
├── RobotArmPage
├── NeuralSimulationPage
├── MNISTPage
├── MotorLearningPage
└── PingPongPage
```

### 相关文档

- [UI完成总结](./frontend/UI_UNIFIED_COMPLETION_REPORT.md)
- [快速启动指南](./frontend/QUICK_START_GUIDE.md)
- [架构设计](./frontend/ARCHITECTURE.md)
- [组件文档](./frontend/src/components/UNIFIED_PAGE_DOCUMENTATION.md)
- [API实现指南](./backend/API_IMPLEMENTATION_GUIDE.md)
- [项目完成总结](./PROJECT_COMPLETION_SUMMARY.md)
- [完成检查清单](./PROJECT_COMPLETION_CHECKLIST.md)

### 前端访问方式

1. **通过首页导航** - 点击功能卡片
2. **通过菜单栏** - 点击"功能"菜单项
3. **直接URL** - `/robot-arm` 等

### 后端实现需求

后端需要实现以下API端点：

```
POST /api/v1/cerebellum/robot-arm/start
POST /api/v1/cerebellum/neural-simulation/start
POST /api/v1/cerebellum/mnist/start
POST /api/v1/cerebellum/motor-learning/start
POST /api/v1/cerebellum/pingpong/start
GET  /api/v1/cerebellum/task/status/{task_id}
POST /api/v1/cerebellum/task/stop/{task_id}
```

详见 `backend/API_IMPLEMENTATION_GUIDE.md`

---

**README v2.0** | 最后更新: 2024年 | [查看完整文档](./文档索引.md)