Skip to content

Commit 4df9541

Browse files
author
shijiashuai
committed
fix: critical bug fixes and documentation improvements
Bug Fixes: - Fix Barnes-Hut tree building losing particles at max depth (>20) Particles at extreme positions were silently dropped when tree depth exceeded 20. Now forces insertion to ensure no particles are lost. - Fix integer overflow in SpatialHashGrid for large grids Use int64_t for cell count calculation to prevent overflow with large bounding boxes. Add sanity check for max 100M cells. - Fix missing input validation in serialization Add checks for truncated/corrupted files when reading headers and particle data arrays. Documentation: - Improve docs navigation with quick links section - Add tutorials section with code examples - Update GitHub Pages config with better SEO settings - Fix broken links in documentation Chore: - Remove unused gitsubmodule dependabot config
1 parent 84bbf43 commit 4df9541

16 files changed

Lines changed: 283 additions & 48 deletions

File tree

‎.github/dependabot.yml‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,3 @@ updates:
1919
- "github-actions"
2020
reviewers:
2121
- "LessUp"
22-
23-
# CMake dependencies (manual tracking)
24-
- package-ecosystem: "gitsubmodule"
25-
directory: "/"
26-
schedule:
27-
interval: "monthly"
28-
open-pull-requests-limit: 3
29-
commit-message:
30-
prefix: "build"
31-
labels:
32-
- "dependencies"
33-
- "submodules"

‎docs/README.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,8 @@ Welcome to the N-Body Particle Simulation documentation.
2222
- [API Reference](./architecture/api.md) — Complete API documentation
2323
- [Performance Guide](./architecture/performance.md) — Optimization strategies and profiling
2424

25-
### Specs (Single Source of Truth)
26-
- [Product Spec](../specs/product/n-body-simulation.md) — Requirements and acceptance criteria
27-
- [Architecture RFC](../specs/rfc/0001-core-architecture.md) — Technical design decisions
25+
### Tutorials
26+
- [Tutorials & Examples](./tutorials/README.md) — Code examples and common use cases
2827

2928
## 🌐 Available Languages
3029

‎docs/zh-CN/README.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,6 @@ N-Body 粒子模拟系统的中文文档。
2020
- [API 参考](./architecture/api.md) — 完整的 API 文档
2121
- [性能指南](./architecture/performance.md) — 优化策略和性能分析
2222

23-
### 规范文档（唯一事实来源）
24-
- [产品规范](../../specs/product/n-body-simulation.md) — 需求和验收标准
25-
- [架构 RFC](../../specs/rfc/0001-core-architecture.md) — 技术设计决策
26-
2723
## 🌐 切换语言
2824

2925
| 语言 | 文档链接 |
@@ -41,6 +37,15 @@ N-Body 粒子模拟系统的中文文档。
4137
| 算法 | 3 种（直接 N²、Barnes-Hut、Spatial Hash） |
4238
| 积分器 | Velocity Verlet（辛积分器） |
4339

40+
## 🔗 快速链接
41+
42+
| 文档 | 说明 |
43+
|------|------|
44+
| [主 README](../../README.zh-CN.md) | 项目概览和快速开始 |
45+
| [更新日志](../../CHANGELOG.md) | 版本历史和变更记录 |
46+
| [示例代码](../../examples/) | 代码示例 |
47+
| [贡献指南](../../CONTRIBUTING.md) | 参与贡献 |
48+
4449
## 🔗 外部资源
4550

4651
- [主 README](../../README.md) | [中文版 README](../../README.zh-CN.md)

‎docs/zh-CN/architecture/architecture.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -357,12 +357,11 @@ case GLFW_KEY_4:
357357
- [ ] 为粒子数选择最佳算法
358358
- [ ] 调整 Barnes-Hut θ 参数
359359
- [ ] 设置合适的 Spatial Hash 单元格大小
360-
361360
---
362361

363362
## 📚 相关文档
364363

365364
- [API 参考](./api.md) - 详细 API 文档
366365
- [算法详解](./algorithms.md) - 算法说明
367366
- [性能指南](./performance.md) - 优化策略
368-
- [快速入门](./getting-started.md) - 安装和使用
367+
- [快速入门](../setup/getting-started.md) - 安装和使用

‎docs/zh-CN/tutorials/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# 教程和示例
2+
3+
本目录包含 N-Body 粒子仿真系统的使用教程和代码示例。
4+
5+
## 📚 教程列表
6+
7+
| 教程 | 说明 |
8+
|------|------|
9+
| 基础用法 | 最小化仿真设置和运行 |
10+
| 算法对比 | 不同力计算算法的性能比较 |
11+
| 自定义分布 | 自定义粒子初始条件 |
12+
| 能量监控 | 监控仿真过程中的能量守恒 |
13+
14+
## 🔗 相关资源
15+
16+
- [快速入门](../setup/getting-started.md) — 安装和首次运行
17+
- [架构概览](../architecture/architecture.md) — 系统设计
18+
- [示例代码](../../../examples/) — 完整代码示例

‎site/_config.yml‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ description: >-
66
Real-time CUDA-OpenGL interop rendering for up to 1 million particles.
77
url: "https://lessup.github.io"
88
baseurl: "/n-body"
9+
author: LessUp
910

1011
# Theme & Plugins
1112
remote_theme: pmarsceill/just-the-docs
@@ -14,6 +15,19 @@ plugins:
1415
- jekyll-seo-tag
1516
- jekyll-sitemap
1617

18+
# SEO & Social
19+
twitter:
20+
card: summary_large_image
21+
username: lessup_dev
22+
github_username: LessUp
23+
social:
24+
name: LessUp
25+
links:
26+
- https://github.com/LessUp
27+
28+
# Logo
29+
logo: "/assets/logo.png"
30+
1731
# Repository
1832
repository: LessUp/n-body
1933
gh_repo: https://github.com/LessUp/n-body
@@ -59,6 +73,10 @@ footer_content: "Copyright © 2024-2026 LessUp. Released under MIT License."
5973
back_to_top: true
6074
back_to_top_text: "Back to Top"
6175

76+
# Google Analytics (optional - uncomment to enable)
77+
# ga_tracking: UA-XXXXXXXX-X
78+
# ga_tracking_anonymize_ip: true
79+
6280
# Last Modified Timestamp
6381
last_edit_timestamp: true
6482
last_edit_time_format: "%b %e %Y at %I:%M %p"
@@ -69,6 +87,18 @@ collections:
6987
permalink: "/:collection/:path"
7088
output: true
7189

90+
# Callouts
91+
callouts:
92+
warning:
93+
title: Warning
94+
color: red
95+
note:
96+
title: Note
97+
color: blue
98+
tip:
99+
title: Tip
100+
color: green
101+
72102
# Defaults
73103
defaults:
74104
- scope:
@@ -77,15 +107,16 @@ defaults:
77107
layout: "default"
78108
nav_order: 1
79109
- scope:
80-
path: "docs"
110+
path: "docs-content"
81111
values:
82112
layout: "default"
83113
has_children: true
84114
nav_order: 2
85115
- scope:
86-
path: "changelog"
116+
path: "changelog-content"
87117
values:
88118
layout: "default"
119+
has_children: true
89120
nav_order: 3
90121

91122
# Exclude from Build
@@ -96,3 +127,4 @@ exclude:
96127
- "*.gem"
97128
- Gemfile
98129
- Gemfile.lock
130+
- DIRECTORY_RESTRUCTURE_SUMMARY.md

‎site/docs-content/README.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,8 @@ Welcome to the N-Body Particle Simulation documentation.
2222
- [API Reference](./architecture/api.md) — Complete API documentation
2323
- [Performance Guide](./architecture/performance.md) — Optimization strategies and profiling
2424

25-
### Specs (Single Source of Truth)
26-
- [Product Spec](../specs/product/n-body-simulation.md) — Requirements and acceptance criteria
27-
- [Architecture RFC](../specs/rfc/0001-core-architecture.md) — Technical design decisions
25+
### Tutorials
26+
- [Tutorials & Examples](./tutorials/README.md) — Code examples and common use cases
2827

2928
## 🌐 Available Languages
3029

@@ -49,7 +48,7 @@ N-Body simulation is a computational method that models the motion of particles
4948

5049
## 🔗 External Resources
5150

52-
- [Main README](../README.md)
53-
- [Changelog](../CHANGELOG.md)
54-
- [Examples](../examples/)
55-
- [Contributing Guide](../CONTRIBUTING.md)
51+
- [Main README](https://github.com/LessUp/n-body#readme)
52+
- [Changelog](../changelog-content/en/index.md)
53+
- [Examples](https://github.com/LessUp/n-body/tree/main/examples)
54+
- [Contributing Guide](https://github.com/LessUp/n-body/blob/main/CONTRIBUTING.md)

‎site/docs-content/tutorials/README.md‎

Lines changed: 68 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,71 @@
1-
# Tutorials
1+
---
2+
layout: default
3+
title: Tutorials
4+
parent: Documentation
5+
nav_order: 3
6+
has_children: true
7+
---
28

3-
Step-by-step guides and tutorials for using the N-Body simulation.
9+
# Tutorials & Examples
410

5-
## Available Tutorials
11+
This directory contains tutorials and code examples for the N-Body Particle Simulation System.
612

7-
- Getting Started (Coming Soon)
8-
- Creating Custom Particle Distributions (Coming Soon)
9-
- Performance Tuning Guide (Coming Soon)
13+
## 📚 Tutorial List
14+
15+
| Tutorial | Description |
16+
|----------|-------------|
17+
| Basic Usage | Minimal simulation setup and execution |
18+
| Algorithm Comparison | Performance comparison of different force calculation algorithms |
19+
| Custom Distribution | Custom particle initial conditions |
20+
| Energy Monitoring | Monitor energy conservation during simulation |
21+
22+
## 🔗 Related Resources
23+
24+
- [Getting Started](../setup/getting-started.md) — Installation and first run
25+
- [Architecture Overview](../architecture/architecture.md) — System design
26+
- [Example Code](https://github.com/LessUp/n-body/tree/main/examples) — Complete code examples
27+
28+
## 📖 Code Examples
29+
30+
### Basic Simulation
31+
32+
```cpp
33+
#include "nbody/particle_system.hpp"
34+
35+
using namespace nbody;
36+
37+
int main() {
38+
SimulationConfig config;
39+
config.particle_count = 100000;
40+
config.force_method = ForceMethod::BARNES_HUT;
41+
config.dt = 0.001f;
42+
43+
ParticleSystem system;
44+
system.initialize(config);
45+
46+
for (int i = 0; i < 1000; ++i) {
47+
system.update(system.getTimeStep());
48+
}
49+
50+
return 0;
51+
}
52+
```
53+
54+
### Energy Monitoring
55+
56+
```cpp
57+
float ke = system.computeKineticEnergy();
58+
float pe = system.computePotentialEnergy();
59+
float total = system.computeTotalEnergy();
60+
std::cout << "Energy: KE=" << ke << " PE=" << pe << " Total=" << total << std::endl;
61+
```
62+
63+
### Save and Load State
64+
65+
```cpp
66+
// Save
67+
system.saveState("checkpoint.nbody");
68+
69+
// Load
70+
system.loadState("checkpoint.nbody");
71+
```

‎site/docs-content/zh-CN/README.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ N-Body 粒子模拟系统的中文文档。
77
| 目录 | 用途 |
88
|------|------|
99
| [`setup/`](./setup/) | 环境搭建、构建说明、故障排除 |
10+
| [`tutorials/`](./tutorials/) | 教程、使用指南和代码示例 |
1011
| [`architecture/`](./architecture/) | 系统设计、算法、API 参考、性能 |
1112

1213
## 🚀 快速导航
@@ -20,9 +21,8 @@ N-Body 粒子模拟系统的中文文档。
2021
- [API 参考](./architecture/api.md) — 完整的 API 文档
2122
- [性能指南](./architecture/performance.md) — 优化策略和性能分析
2223

23-
### 规范文档（唯一事实来源）
24-
- [产品规范](../../specs/product/n-body-simulation.md) — 需求和验收标准
25-
- [架构 RFC](../../specs/rfc/0001-core-architecture.md) — 技术设计决策
24+
### 教程
25+
- [教程和示例](./tutorials/README.md) — 代码示例和常见场景
2626

2727
## 🌐 切换语言
2828

@@ -43,7 +43,7 @@ N-Body 粒子模拟系统的中文文档。
4343

4444
## 🔗 外部资源
4545

46-
- [主 README](../../README.md) | [中文版 README](../../README.zh-CN.md)
47-
- [更新日志](../../CHANGELOG.md)
48-
- [示例代码](../../examples/)
49-
- [贡献指南](../../CONTRIBUTING.md)
46+
- [主 README](https://github.com/LessUp/n-body#readme) | [中文版 README](https://github.com/LessUp/n-body#n-body-粒子仿真系统)
47+
- [更新日志](../changelog-content/zh-CN/index.md)
48+
- [示例代码](https://github.com/LessUp/n-body/tree/main/examples)
49+
- [贡献指南](https://github.com/LessUp/n-body/blob/main/CONTRIBUTING.md)

‎site/docs-content/zh-CN/architecture/architecture.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -365,4 +365,5 @@ case GLFW_KEY_4:
365365
- [API 参考](./api.md) - 详细 API 文档
366366
- [算法详解](./algorithms.md) - 算法说明
367367
- [性能指南](./performance.md) - 优化策略
368-
- [快速入门](./getting-started.md) - 安装和使用
368+
- [快速入门](../setup/getting-started.md) - 安装和使用
369+
- [教程和示例](../tutorials/README.md) - 代码示例

0 commit comments

Comments
 (0)