initial commit FESurrogateModelTutorial

2026-05-21 17:03:51 +09:00
parent 93665d9ee6
commit 43b86669fa
122 changed files with 7929 additions and 0 deletions
@@ -0,0 +1,30 @@
+{
+  "project": "FEMSurrogateTutorial",
+  "phase": "3-notebooks-and-final-verification",
+  "steps": [
+    {
+      "step": 0,
+      "name": "dataset-notebook",
+      "status": "completed",
+      "summary": "Added and executed dataset notebook that validates BeamExamples, generates LHS samples, builds FEM dataset, and writes reference CSV/metadata."
+    },
+    {
+      "step": 1,
+      "name": "model-notebooks",
+      "status": "completed",
+      "summary": "Added and executed five model notebooks sharing the same dataset, target, and split seed while saving metrics, predictions, and diagnostic figures."
+    },
+    {
+      "step": 2,
+      "name": "comparison-notebook",
+      "status": "completed",
+      "summary": "Added and executed comparison notebook that reads saved metrics and writes model comparison CSV and figures without retraining."
+    },
+    {
+      "step": 3,
+      "name": "final-verification",
+      "status": "completed",
+      "summary": "Ran full pytest, ruff, all seven nbconvert executions, and verified comparison outputs exist."
+    }
+  ]
+}
@@ -0,0 +1,23 @@
+# Step 0: dataset-notebook
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/src/femsurrogate/`
+
+## 작업
+
+`notebooks/00_beam2d_fea_dataset.ipynb`를 만든다. Notebook은 BeamExamples regression 검증, LHS sampling, FEM batch run, dataset 저장을 설명하고 실행한다.
+
+## Acceptance Criteria
+
+```powershell
+uv run jupyter nbconvert --to notebook --execute notebooks/00_beam2d_fea_dataset.ipynb
+uv run ruff check .
+```
+
+## 금지사항
+
+- 핵심 solver 구현을 notebook cell에 넣지 마라.
@@ -0,0 +1,39 @@
+# Step 1: model-notebooks
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/theory/02_response_surface_methodology.md`
+- `/docs/theory/03_gaussian_process_kriging.md`
+- `/docs/theory/04_random_forest.md`
+- `/docs/theory/05_gradient_boosting.md`
+- `/docs/theory/06_mlp_neural_network.md`
+- `/src/femsurrogate/surrogates/`
+- `/src/femsurrogate/plotting/`
+
+## 작업
+
+모델별 notebook 5개를 만든다.
+
+- `notebooks/01_response_surface_surrogate.ipynb`
+- `notebooks/02_gaussian_process_kriging_surrogate.ipynb`
+- `notebooks/03_random_forest_surrogate.ipynb`
+- `notebooks/04_gradient_boosting_surrogate.ipynb`
+- `notebooks/05_mlp_surrogate.ipynb`
+
+각 notebook은 같은 dataset, target, split seed를 쓰고 metric JSON과 prediction CSV를 저장한다.
+
+## Acceptance Criteria
+
+```powershell
+uv run jupyter nbconvert --to notebook --execute notebooks/01_response_surface_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/02_gaussian_process_kriging_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/03_random_forest_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/04_gradient_boosting_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/05_mlp_surrogate.ipynb
+uv run ruff check .
+```
+
+## 금지사항
+
+- 모델별로 다른 split을 쓰지 마라.
@@ -0,0 +1,24 @@
+# Step 2: comparison-notebook
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/reports/results/`
+- `/reports/predictions/`
+- `/src/femsurrogate/plotting/comparison.py`
+
+## 작업
+
+`notebooks/06_compare_surrogate_models.ipynb`를 만든다. 이전 notebook 결과물을 읽어 RMSE, MAE, R2, 학습 시간, 예측 시간을 비교하고 모델 선택 가이드를 정리한다.
+
+## Acceptance Criteria
+
+```powershell
+uv run jupyter nbconvert --to notebook --execute notebooks/06_compare_surrogate_models.ipynb
+uv run ruff check .
+```
+
+## 금지사항
+
+- 비교 notebook에서 모델을 다시 학습하지 마라.
@@ -0,0 +1,37 @@
+# Step 3: final-verification
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/PROGRESS.md`
+- `/WORKNOTES.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+
+## 작업
+
+전체 검증과 handoff 문서 정리를 수행한다.
+
+- `uv run pytest`
+- `uv run ruff check .`
+- 모든 notebook 순차 `nbconvert --execute`
+- `/PROGRESS.md` 최종 업데이트
+- `/WORKNOTES.md`에 남은 주의점 기록
+
+## Acceptance Criteria
+
+```powershell
+uv run pytest
+uv run ruff check .
+uv run jupyter nbconvert --to notebook --execute notebooks/00_beam2d_fea_dataset.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/01_response_surface_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/02_gaussian_process_kriging_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/03_random_forest_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/04_gradient_boosting_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/05_mlp_surrogate.ipynb
+uv run jupyter nbconvert --to notebook --execute notebooks/06_compare_surrogate_models.ipynb
+```
+
+## 금지사항
+
+- 실패한 검증을 성공으로 기록하지 마라.