initial commit FESurrogateModelTutorial
This commit is contained in:
김경종
@@ -0,0 +1,226 @@
|
||||
# 아키텍처
|
||||
|
||||
## 개요
|
||||
이 프로젝트는 문서와 Jupyter notebook이 중심인 교육용 Python 프로젝트다. 재사용 가능한 계산 로직은 `src/femsurrogate/`에 모듈화하고, notebook은 설명, 시각화, 실행 순서, 결과 해석을 담당한다.
|
||||
|
||||
## 기술 스택
|
||||
- Python `>=3.12,<3.15`
|
||||
- `uv` + `pyproject.toml` + `uv.lock`
|
||||
- NumPy, SciPy
|
||||
- pandas, matplotlib
|
||||
- scikit-learn
|
||||
- JupyterLab, ipykernel, nbconvert
|
||||
- pytest, ruff
|
||||
- joblib, CSV, JSON
|
||||
|
||||
## 디렉토리 구조
|
||||
```text
|
||||
docs/
|
||||
PRD.md
|
||||
ARCHITECTURE.md
|
||||
ADR.md
|
||||
theory/
|
||||
00_surrogate_modeling_for_fem.md
|
||||
01_doe_sampling_validation.md
|
||||
02_response_surface_methodology.md
|
||||
03_gaussian_process_kriging.md
|
||||
04_random_forest.md
|
||||
05_gradient_boosting.md
|
||||
06_mlp_neural_network.md
|
||||
|
||||
BeamExamples/
|
||||
CantileverBeam.txt
|
||||
CantileverBeam_Displacements.txt
|
||||
|
||||
notebooks/
|
||||
00_beam2d_fea_dataset.ipynb
|
||||
01_response_surface_surrogate.ipynb
|
||||
02_gaussian_process_kriging_surrogate.ipynb
|
||||
03_random_forest_surrogate.ipynb
|
||||
04_gradient_boosting_surrogate.ipynb
|
||||
05_mlp_surrogate.ipynb
|
||||
06_compare_surrogate_models.ipynb
|
||||
|
||||
src/femsurrogate/
|
||||
fea/
|
||||
element.py
|
||||
model.py
|
||||
io.py
|
||||
assembly.py
|
||||
solver.py
|
||||
responses.py
|
||||
benchmark.py
|
||||
data/
|
||||
bounds.py
|
||||
sampling.py
|
||||
dataset.py
|
||||
schema.py
|
||||
surrogates/
|
||||
common.py
|
||||
rsm.py
|
||||
gpr.py
|
||||
random_forest.py
|
||||
boosting.py
|
||||
mlp.py
|
||||
registry.py
|
||||
plotting/
|
||||
diagnostics.py
|
||||
comparison.py
|
||||
|
||||
tests/
|
||||
data/
|
||||
reference/
|
||||
processed/
|
||||
reports/
|
||||
results/
|
||||
predictions/
|
||||
figures/
|
||||
```
|
||||
|
||||
## 핵심 모듈 책임
|
||||
### `femsurrogate.fea`
|
||||
2D Euler-Bernoulli beam/frame 요소 기반 선형 정적 해석을 담당한다.
|
||||
|
||||
- `element.py`: local 6x6 stiffness matrix와 좌표 변환 행렬.
|
||||
- `model.py`: node, element, support, load, material, section, parameter dataclass.
|
||||
- `io.py`: `BeamExamples/*.txt`의 간단한 텍스트 fixture parser.
|
||||
- `assembly.py`: global sparse stiffness matrix 조립.
|
||||
- `solver.py`: 경계조건 적용과 `K u = f` 풀이.
|
||||
- `responses.py`: tip displacement, bending stress, mass, compliance 계산.
|
||||
- `benchmark.py`: cantilever analytical solution 등 검증 helper.
|
||||
|
||||
### `femsurrogate.data`
|
||||
입력 공간 정의, 샘플링, batch 해석, dataset schema를 담당한다.
|
||||
|
||||
- `bounds.py`: 설계변수 범위와 단위.
|
||||
- `sampling.py`: Latin Hypercube Sampling.
|
||||
- `dataset.py`: 샘플별 FEM 실행과 CSV/metadata 저장.
|
||||
- `schema.py`: 컬럼명, target명, 단위, split seed.
|
||||
|
||||
### `femsurrogate.surrogates`
|
||||
scikit-learn 기반 모델 생성, 학습, 평가를 담당한다.
|
||||
|
||||
- `common.py`: train/test split, scaling, metric, timing, JSON 저장.
|
||||
- `rsm.py`: `PolynomialFeatures` + `Ridge`.
|
||||
- `gpr.py`: `GaussianProcessRegressor`.
|
||||
- `random_forest.py`: `RandomForestRegressor`.
|
||||
- `boosting.py`: `GradientBoostingRegressor`.
|
||||
- `mlp.py`: `MLPRegressor`.
|
||||
- `registry.py`: notebook에서 모델명을 통해 builder를 가져오는 작은 registry.
|
||||
|
||||
### `femsurrogate.plotting`
|
||||
모델 진단과 최종 비교 그림을 담당한다.
|
||||
|
||||
- `diagnostics.py`: parity plot, residual plot, error histogram.
|
||||
- `comparison.py`: 모델별 metric table, bar plot, prediction-time comparison.
|
||||
|
||||
## 주요 인터페이스
|
||||
```python
|
||||
def run_beam2d_case(params: BeamParameters) -> AnalysisResult:
|
||||
...
|
||||
|
||||
def generate_lhs_samples(bounds: ParameterBounds, n: int, seed: int) -> pd.DataFrame:
|
||||
...
|
||||
|
||||
def build_dataset(samples: pd.DataFrame) -> pd.DataFrame:
|
||||
...
|
||||
|
||||
def make_model(model_name: str, random_state: int):
|
||||
...
|
||||
|
||||
def evaluate_model(model, X_train, X_test, y_train, y_test) -> MetricsReport:
|
||||
...
|
||||
```
|
||||
|
||||
## 데이터 흐름
|
||||
```text
|
||||
Parameter bounds
|
||||
-> Latin Hypercube samples
|
||||
-> Beam2D FEM batch analysis
|
||||
-> data/reference/beam2d_lhs_300.csv
|
||||
-> model-specific notebooks
|
||||
-> reports/results/<model>_metrics.json
|
||||
-> reports/predictions/<model>_predictions.csv
|
||||
-> notebooks/06_compare_surrogate_models.ipynb
|
||||
```
|
||||
|
||||
## FEM 해석 설계
|
||||
- 요소: 2-node 2D Euler-Bernoulli frame element.
|
||||
- 노드 DOF: `[ux, uy, rz]`.
|
||||
- Local stiffness matrix: axial `EA/L` 항과 bending `EI` 항을 포함한 6x6 matrix.
|
||||
- Global assembly: sparse matrix 기반.
|
||||
- Solver: constrained DOF 제거 후 `scipy.sparse.linalg.spsolve`.
|
||||
- 기준 검증: cantilever tip displacement `P L^3 / (3 E I)`.
|
||||
|
||||
## Solver Verification Fixture
|
||||
`BeamExamples/`의 cantilever 예제는 solver 구현의 canonical regression fixture다.
|
||||
|
||||
```text
|
||||
BeamExamples/CantileverBeam.txt
|
||||
BeamExamples/CantileverBeam_Displacements.txt
|
||||
```
|
||||
|
||||
입력 파일은 다음 항목을 포함한다.
|
||||
|
||||
- Section/material metadata: `Area`, `J`, `Iyy`, `Izz`, `ElasticModulus`, `Poisson'sRatio`.
|
||||
- Geometry: `Node, NodeID, X, Y`.
|
||||
- Connectivity: `Beam, BeamID, NodeID1, NodeID2`.
|
||||
- Boundary condition: `Fix, NodeID`.
|
||||
- Load: `NodeLoad, NodeID, Fx, Fy, Mz`.
|
||||
|
||||
2D in-plane Euler-Bernoulli frame solver는 `Area`, `Izz`, `ElasticModulus`, node coordinates, beam connectivity, fixed nodes, nodal loads를 사용한다. `J`, `Iyy`, `Poisson'sRatio`는 fixture metadata로 보존하되 v1 해석에는 사용하지 않는다.
|
||||
|
||||
기준 변위 파일은 다음 형식을 가진다.
|
||||
|
||||
```text
|
||||
# NodeID, Ux, Uy, Rz
|
||||
1 0.000000, 0.000000, 0.000000
|
||||
...
|
||||
```
|
||||
|
||||
검증 test는 solver 결과의 모든 node별 `[Ux, Uy, Rz]`를 기준 파일과 비교한다. 기준 파일 값은 소수점 6자리로 반올림되어 있으므로 기본 허용오차는 `atol=5e-7`, `rtol=1e-6`로 둔다. Tip displacement는 별도로 해석해 `P L^3 / (3 E I)`와 비교해 부호와 크기를 확인한다.
|
||||
|
||||
## Dataset Schema
|
||||
기본 dataset은 SI 단위 컬럼을 사용한다.
|
||||
|
||||
```text
|
||||
L_m
|
||||
b_m
|
||||
h_m
|
||||
E_pa
|
||||
P_n
|
||||
A_m2
|
||||
I_m4
|
||||
tip_uy_m
|
||||
max_abs_bending_stress_pa
|
||||
mass_kg
|
||||
compliance_j
|
||||
```
|
||||
|
||||
Metadata JSON에는 다음을 포함한다.
|
||||
|
||||
```text
|
||||
dataset_name
|
||||
created_by
|
||||
sample_count
|
||||
random_seed
|
||||
parameter_bounds
|
||||
target_columns
|
||||
unit_system
|
||||
fea_model
|
||||
notes
|
||||
```
|
||||
|
||||
## Notebook 책임
|
||||
- Notebook은 한 번에 위에서 아래로 실행 가능해야 한다.
|
||||
- Notebook 셀에 핵심 FEM 또는 ML helper 구현을 길게 두지 않는다.
|
||||
- 각 모델별 notebook은 같은 dataset, target, split seed를 사용한다.
|
||||
- 각 모델별 notebook은 metric JSON과 prediction CSV를 저장한다.
|
||||
- 최종 비교 notebook은 이전 notebook 결과물을 읽어 비교만 수행한다.
|
||||
|
||||
## 검증 전략
|
||||
- Unit tests: FEM element, solver, dataset generation, model factory.
|
||||
- Regression tests: `BeamExamples/CantileverBeam.txt`를 해석하고 `BeamExamples/CantileverBeam_Displacements.txt`와 비교.
|
||||
- Integration tests: 작은 sample count로 dataset 생성과 모든 surrogate smoke test.
|
||||
- Notebook tests: `nbconvert --execute`로 순차 실행.
|
||||
- Documentation checks: 문서의 경로와 notebook/file 이름이 실제 구조와 일치하는지 검토.
|
||||
Reference in New Issue
Block a user