initial commit FESurrogateModelTutorial

FESurrogateModelTutorial/docs/ADR.md

@@ -0,0 +1,76 @@
+# Architecture Decision Records
+
+## 철학
+이 프로젝트는 연구용 개념 전달과 재현성을 우선한다. 구현은 작고 명시적이어야 하며, notebook 교육 흐름과 테스트 가능한 Python 모듈 사이의 경계를 분명히 둔다.
+
+---
+
+## ADR-001: Python tutorial project로 구성
+**결정**: Python `>=3.12,<3.15` 기반의 문서 + notebook + src package 구조를 사용한다.
+
+**이유**: 대상 사용자는 FEM/CAE 연구자이며 Python scientific stack에 익숙하다. NumPy, SciPy, scikit-learn, pandas, matplotlib로 FEM 데이터 생성과 surrogate 모델링을 모두 재현할 수 있다.
+
+**트레이드오프**: 브라우저 대시보드 기반 상호작용은 제공하지 않는다. 시각적 결과는 notebook과 저장된 figure로 제한한다.
+
+---
+
+## ADR-002: `uv`와 `pyproject.toml` 사용
+**결정**: 의존성 관리는 `uv`, 프로젝트 설정은 `pyproject.toml`, lock은 `uv.lock`으로 관리한다.
+
+**이유**: 튜토리얼 재현성을 높이고, pytest/ruff/jupyter 실행 명령을 하나의 환경에서 고정하기 쉽다.
+
+**트레이드오프**: conda 기반 연구실 환경보다 초기 학습 비용이 있을 수 있다. 대신 repository-local workflow가 단순해진다.
+
+---
+
+## ADR-003: 자체 2D Euler-Bernoulli beam/frame solver 사용
+**결정**: FEM 데이터는 NumPy/SciPy로 구현한 2-node 2D Euler-Bernoulli beam/frame element에서 생성한다.
+
+**이유**: 외부 CAE solver 없이 해석 데이터 생성 과정을 완전히 설명할 수 있다. 요소 강성, 조립, 경계조건, 응답 계산이 surrogate 학습 데이터와 직접 연결된다.
+
+**트레이드오프**: 산업용 고충실도 해석과 차이가 있다. v1은 선형 정적, slender beam 가정에 제한된다.
+
+---
+
+## ADR-004: Notebook은 orchestration layer로 제한
+**결정**: 핵심 계산과 학습 helper는 `src/femsurrogate/`에 두고 notebook은 설명, 호출, 시각화, 해석을 담당한다.
+
+**이유**: notebook hidden state 문제를 줄이고, pytest로 핵심 로직을 검증할 수 있다. 모델별 notebook도 같은 helper를 사용하므로 비교 조건이 일관된다.
+
+**트레이드오프**: 독자가 처음 볼 파일 수는 늘어난다. 대신 코드 재사용성과 검증 가능성이 높아진다.
+
+---
+
+## ADR-005: scikit-learn 중심 surrogate 모델
+**결정**: Response Surface, Gaussian Process/Kriging, Random Forest, Gradient Boosting, MLP를 모두 scikit-learn API로 구현한다.
+
+**이유**: 공통 `fit/predict` 인터페이스를 사용하면 모델별 비교가 단순하다. 연구자에게 익숙하고 설치 부담이 낮다.
+
+**트레이드오프**: PyTorch 기반 deep learning, GPU 학습, 복잡한 Bayesian optimization framework는 제외한다.
+
+---
+
+## ADR-006: 기준 데이터셋은 CSV + metadata JSON
+**결정**: 기준 FEM 데이터는 CSV로 저장하고, 생성 조건은 JSON metadata로 별도 저장한다.
+
+**이유**: CSV는 notebook, pandas, spreadsheet, 다른 ML 도구에서 쉽게 읽을 수 있다. Metadata JSON은 seed, bounds, 단위, target 정보를 명확히 남긴다.
+
+**트레이드오프**: 대용량/버전관리형 데이터셋에는 Parquet, DVC, database가 더 적합할 수 있다. v1에서는 단순성과 가독성을 우선한다.
+
+---
+
+## ADR-007: 모델별 이론 문서와 모델별 notebook 분리
+**결정**: 각 surrogate 모델은 별도 이론 문서와 별도 실습 notebook으로 구성한다. 최종 비교는 별도 notebook에서 수행한다.
+
+**이유**: 모델별 가정, 장점, 실패 모드, hyperparameter가 다르므로 독립적으로 학습하는 편이 좋다. 최종 비교 notebook은 같은 입력 데이터와 metric을 기준으로 모델 선택을 돕는다.
+
+**트레이드오프**: notebook 수가 늘어난다. 대신 각 notebook의 목표가 분명하고 실행 실패 범위가 작아진다.
+
+---
+
+## ADR-008: Notebook 중심 범위 고정
+**결정**: 브라우저 앱과 디자인 시스템 계획을 프로젝트 범위에서 제외한다.
+
+**이유**: 튜토리얼은 notebook 기반이다. 브라우저 앱 설계 지침은 현재 목표에 직접 기여하지 않으며 미래 agent에게 잘못된 구현 방향을 줄 수 있다.
+
+**트레이드오프**: 웹 기반 인터랙티브 학습 환경은 제공하지 않는다.