ResearchProject/FESurrogateModelTutorial/docs/ARCHITECTURE.md

아키텍처

개요

이 프로젝트는 문서와 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

디렉토리 구조

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.

주요 인터페이스

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:
    ...

데이터 흐름

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다.

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 해석에는 사용하지 않는다.

기준 변위 파일은 다음 형식을 가진다.

# 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 단위 컬럼을 사용한다.

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에는 다음을 포함한다.

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 이름이 실제 구조와 일치하는지 검토.