Update 0.2.0 reader UX and MDHelper docs
This commit is contained in:
+75
-65
@@ -1,84 +1,94 @@
|
||||
# 快速开始
|
||||
# MDHelper 快速开始
|
||||
|
||||
本章说明如何从源码编译 M3Frame,并运行一个 XML 驱动案例。
|
||||
## 1. 启动
|
||||
|
||||
## 1. 编译主程序
|
||||
|
||||
在项目根目录执行:
|
||||
源码运行:
|
||||
|
||||
```powershell
|
||||
cmake -S . -B cmake-build-cuda13 -DCMAKE_BUILD_TYPE=Release
|
||||
cmake --build cmake-build-cuda13 --config Release --target M3Frame
|
||||
.\mdhelper_env\Scripts\python.exe -m mdhelper
|
||||
```
|
||||
|
||||
成功后主程序通常位于:
|
||||
|
||||
```text
|
||||
cmake-build-cuda13/Release/M3Frame.exe
|
||||
```
|
||||
|
||||
## 2. 运行一个 SPH 案例
|
||||
|
||||
以三维溃坝压力案例为例:
|
||||
打开指定文件夹:
|
||||
|
||||
```powershell
|
||||
.\cmake-build-cuda13\Release\M3Frame.exe examples\sph\benchmarks\dam_break_pressure\pipeline.xml
|
||||
.\mdhelper_env\Scripts\python.exe -m mdhelper D:\CODE\SomeProject
|
||||
```
|
||||
|
||||
典型输出包括:
|
||||
|
||||
```text
|
||||
[pipeline] GeometryStage ...
|
||||
[pipeline] ParticleMeshingStage ...
|
||||
[pipeline] SolverStage(sph) ...
|
||||
[sph-monitor] step=...
|
||||
```
|
||||
|
||||
结果一般写入案例目录下的 `outputs/`。
|
||||
|
||||
## 3. 运行一个后处理 benchmark
|
||||
|
||||
部分案例提供 `benchmark_*.cpp`,用于读取求解结果并和解析解对比。此类程序不应再生成几何或直接推进求解器。
|
||||
|
||||
示例:
|
||||
打开指定 Markdown 文件:
|
||||
|
||||
```powershell
|
||||
cmake --build cmake-build-examples-migrated --config Debug --target benchmark_sph_oscillating_droplet
|
||||
.\cmake-build-examples-migrated\Debug\benchmark_sph_oscillating_droplet.exe
|
||||
.\mdhelper_env\Scripts\python.exe -m mdhelper .\docs\user_manual.md
|
||||
```
|
||||
|
||||
## 4. 检查结果
|
||||
打包版同样支持路径参数:
|
||||
|
||||
常用文件:
|
||||
|
||||
- `.pvd`:ParaView 时间序列入口。
|
||||
- `.vtu`:单个时间步的网格或粒子结果。
|
||||
- `.csv`:误差、监测量、反力、能量等时间历程。
|
||||
- `.log`:命令行监测信息和求解诊断。
|
||||
|
||||
建议用 ParaView 打开 `.pvd` 文件查看随时间变化的结果。
|
||||
|
||||
## 5. 最小案例目录
|
||||
|
||||
新建案例时,建议从以下最小结构开始:
|
||||
|
||||
```text
|
||||
my_case/
|
||||
pipeline.xml
|
||||
config/
|
||||
cad.xml
|
||||
particle_meshing.xml 或 meshing.xml
|
||||
sph_solver.xml 或 fem_solver.xml
|
||||
outputs/
|
||||
README.md
|
||||
```powershell
|
||||
.\dist\MDHelper.exe D:\CODE\SomeProject
|
||||
```
|
||||
|
||||
先让 `pipeline.xml` 只执行几何和离散,确认 `outputs/` 中的 `.stl/.obj/.vtu` 正确;再加入求解器阶段。这样可以快速区分问题来自建模、离散还是求解。
|
||||
## 2. 打开文档
|
||||
|
||||
## 6. 推荐调试顺序
|
||||
1. 点击左侧文档栏的打开按钮。
|
||||
2. 选择一个文件夹或 Markdown 文件。
|
||||
3. 左侧文件树会展示当前可阅读的文件。
|
||||
4. 点击文件即可在标签页中打开。
|
||||
|
||||
1. 打开 CAD 导出的 `.stl` 或 `.obj`,确认几何位置和尺寸。
|
||||
2. 打开粒子或网格 `.vtu`,确认材料 id、边界 id、粒子角色。
|
||||
3. 缩短计算步数,例如 `max_steps="10"`,确认日志能正常输出。
|
||||
4. 打开 `.pvd`,检查第一帧和最后一帧是否可读。
|
||||
5. 再逐步增大时间、粒子数或网格数。
|
||||
如果选择单个 Markdown 文件,MDHelper 会自动把该文件所在目录作为当前文件夹。
|
||||
|
||||
## 3. 调整阅读体验
|
||||
|
||||
进入 `工具 - 设置`:
|
||||
|
||||
- `主题颜色`:彩色、白色、黑色、深灰色。
|
||||
- `主题背景`:仅彩色主题下可选。
|
||||
- `正文字号倍率`:调整阅读字号。
|
||||
- `鼠标滚轮速度`:调整滚轮滚动倍率。
|
||||
- `纸张宽度`:默认 A4,可选 `A4 × 1.25` 到 `A4 × 2`。
|
||||
- `阅读导航`:网页内大纲、外部目录栏、网页内进度条。
|
||||
- `展示文件类型`:Markdown / 网页、Python、C / C++。
|
||||
|
||||
纸张宽度越大,同一行能显示的文字越多。
|
||||
|
||||
## 4. 搜索
|
||||
|
||||
左侧搜索框用于搜索当前文件夹:
|
||||
|
||||
1. 输入关键词。
|
||||
2. 点击放大镜按钮搜索。
|
||||
3. 用上/下箭头切换匹配结果。
|
||||
|
||||
当前页查找使用 `Ctrl+F`。
|
||||
|
||||
## 5. 编辑 Markdown
|
||||
|
||||
1. 打开一个 `.md` 或 `.markdown` 文件。
|
||||
2. 按 `Ctrl+E` 进入编辑模式。
|
||||
3. 在顶部选择源码、预览或分屏。
|
||||
4. 按 `Ctrl+S` 保存。
|
||||
|
||||
编辑器支持查找替换、插入 Markdown 模板、草稿恢复和外部修改冲突检测。
|
||||
|
||||
## 6. 导出
|
||||
|
||||
打开 Markdown 后,可从菜单导出:
|
||||
|
||||
- PDF
|
||||
- HTML
|
||||
- DOCX
|
||||
- MHTML
|
||||
|
||||
DOCX 可使用 pandoc 或 python-docx。MHTML 适合把 HTML 和资源打包成单个文件。
|
||||
|
||||
## 7. 文档检查
|
||||
|
||||
检查本地链接和媒体资源是否缺失:
|
||||
|
||||
```powershell
|
||||
.\mdhelper_env\Scripts\python.exe -m mdhelper --check --project-root .
|
||||
```
|
||||
|
||||
打包版:
|
||||
|
||||
```powershell
|
||||
.\dist\MDHelper.exe --check --project-root .
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user