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,168 @@
+# FEMSurrogateTutorial Agent Instructions
+
+## Project Purpose
+This repository is a Korean tutorial project for studying surrogate models in finite element method (FEM) structural analysis. The tutorial combines:
+- Theory documents on surrogate modeling methods.
+- NumPy/SciPy implementation of a 2D Euler-Bernoulli beam/frame element.
+- Jupyter notebooks that build, validate, and compare surrogate models from generated FEM data.
+
+The primary audience is graduate students and researchers who already know basic FEM and Python.
+
+## Tech Stack
+- Python `>=3.12,<3.15`
+- Environment and dependency management: `uv`, `pyproject.toml`, `uv.lock`
+- Numerical computing: NumPy, SciPy
+- Machine learning: scikit-learn
+- Data and plotting: pandas, matplotlib
+- Notebook workflow: JupyterLab, ipykernel, nbconvert
+- Testing and quality: pytest, ruff
+- Model/result persistence: joblib, CSV, JSON
+
+## Architecture Rules
+- CRITICAL: At the start of every new task or session, read `AGENTS.md`, `PROGRESS.md`, and `WORKNOTES.md` before planning or editing. Use them to understand current scope, completed work, open tasks, and known pitfalls.
+- CRITICAL: Keep `PROGRESS.md` current while working. Update it whenever the task state materially changes, including completed milestones, in-progress work, blockers, verification status, and next actions.
+- CRITICAL: Record meaningful trial-and-error, mistakes, false starts, debugging discoveries, and corrective decisions in `WORKNOTES.md`. Do not log routine command output; log lessons future agents need.
+- CRITICAL: Core calculation logic must live under `src/femsurrogate/`; notebooks should explain and orchestrate, not hide reusable implementation in cells.
+- CRITICAL: FEM data for the tutorial must be generated with the in-repository 2D beam/frame implementation using NumPy/SciPy. Do not introduce Abaqus, ANSYS, OpenSeesPy, CalculiX, or other external solvers for v1.
+- CRITICAL: Keep the structural model linear static and Euler-Bernoulli based for v1. Do not add Timoshenko shear deformation, geometric nonlinearity, material nonlinearity, dynamics, contact, or shell/solid elements unless explicitly requested.
+- CRITICAL: Use `BeamExamples/CantileverBeam.txt` and `BeamExamples/CantileverBeam_Displacements.txt` as the canonical solver verification fixture. The solver must reproduce the listed `Ux`, `Uy`, and `Rz` values within documented floating-point tolerance before it is used to generate surrogate training data.
+- CRITICAL: All random sampling, train/test splits, and model training examples must use fixed seeds for reproducibility.
+- CRITICAL: Keep the project document and Python notebook based. Do not add browser app or design-system work.
+- Keep public helper interfaces small and stable:
+  - `run_beam2d_case(params)`
+  - `generate_lhs_samples(bounds, n, seed)`
+  - `build_dataset(samples)`
+  - `make_model(model_name, random_state)`
+  - `evaluate_model(...)`
+
+## Expected Repository Shape
+```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
+
+PROGRESS.md
+WORKNOTES.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/
+    io.py
+  data/
+  surrogates/
+  plotting/
+
+tests/
+```
+
+## Development Process
+- Start each session by reading `PROGRESS.md` and `WORKNOTES.md` after `AGENTS.md`.
+- Before making changes, update `PROGRESS.md` with the current task, intended scope, and success criteria when they are not already recorded.
+- During longer tasks, update `PROGRESS.md` after each meaningful milestone instead of waiting until the end.
+- When you encounter an implementation mistake, incorrect assumption, failed approach, non-obvious parser/detail issue, or verification problem, add a concise note to `WORKNOTES.md` with the date and lesson learned.
+- At the end of a task, update `PROGRESS.md` with completed work, verification commands/results, remaining risks, and recommended next step.
+- Use TDD for code changes: write a failing pytest first, implement the smallest passing change, then refactor only if needed.
+- For documentation changes, verify that links, filenames, and referenced commands match the repository.
+- Prefer simple educational implementations over production abstractions.
+- Keep every change traceable to the tutorial goal. Do not add speculative tooling, dashboards, APIs, or deployment layers.
+- Commit messages should follow Conventional Commits, for example `docs: define tutorial architecture` or `feat: add beam2d solver`.
+
+## Commands
+Use these commands once the Python project files exist:
+
+```powershell
+uv sync
+uv run pytest
+uv run ruff check .
+uv run jupyter nbconvert --to notebook --execute notebooks/00_beam2d_fea_dataset.ipynb
+```
+
+For full notebook verification:
+
+```powershell
+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
+```
+
+## Documentation Standards
+- Write tutorial content in Korean.
+- Keep technical terms such as surrogate model, response surface, Gaussian process, Kriging, Random Forest, Gradient Boosting, MLP, DOE, LHS, RMSE, MAE, and R2 in English when that is clearer.
+- Theory documents must include citations and links to primary or official sources where possible.
+- Avoid long quotations. Summarize sources in your own words.
+- When adding equations, define symbols and units near the equation.
+- Each model-specific theory document should explain:
+  - Core idea and assumptions.
+  - Mathematical form.
+  - FEM structural-analysis use case.
+  - Strengths, weaknesses, and failure modes.
+  - Hyperparameters used in the matching notebook.
+  - References.
+
+## Progress And Work Notes
+`PROGRESS.md` and `WORKNOTES.md` are mandatory handoff files for future agents.
+
+`PROGRESS.md` should answer:
+- What is the current project/task state?
+- What has been completed?
+- What is in progress?
+- What is blocked or intentionally deferred?
+- What verification has been run, with command names and results?
+- What should the next agent do first?
+
+`WORKNOTES.md` should answer:
+- What assumptions turned out to be wrong?
+- What approaches were tried and rejected?
+- What parsing, numerical, notebook, or tooling pitfalls were discovered?
+- What should future agents avoid repeating?
+
+Keep both files concise and factual. Do not use them as a full chat transcript.
+
+## Data And Result Conventions
+- Treat files under `BeamExamples/` as checked-in verification fixtures, not generated data.
+- `BeamExamples/CantileverBeam.txt` defines a six-node, five-element cantilever beam with fixed node 1 and a downward nodal load at node 6.
+- `BeamExamples/CantileverBeam_Displacements.txt` defines expected nodal `Ux`, `Uy`, and `Rz` values for that example.
+- The BeamExamples fixture uses clockwise-positive `Rz`; keep element stiffness, solver output, and regression comparisons in that convention.
+- For the 2D in-plane beam/frame solver, use `Area`, `ElasticModulus`, and `Izz` from the example input. Preserve `J`, `Iyy`, and `Poisson'sRatio` when parsing metadata, but do not use them in the v1 Euler-Bernoulli in-plane solve.
+- Store generated reference data under `data/reference/`.
+- Store derived or regenerated data under `data/processed/`.
+- Store metrics under `reports/results/`.
+- Store predictions under `reports/predictions/`.
+- Store generated figures under `reports/figures/`.
+- Use SI units in data columns and encode units in column names where practical, for example `tip_uy_m`, `max_abs_bending_stress_pa`, `mass_kg`, `compliance_j`.
+- Include metadata JSON for generated datasets with seed, sample count, bounds, and code version notes.
+
+## Review Checklist
+- Does the change keep notebooks thin and reusable code in `src/femsurrogate/`?
+- Does the FEM implementation remain a linear static 2D Euler-Bernoulli beam/frame model?
+- Does the solver pass the `BeamExamples/CantileverBeam.txt` displacement regression check?
+- Are random seeds fixed?
+- Are tests added or updated for new code behavior?
+- Do docs and notebooks refer to the same paths and artifact names?
+- Are citations present for theory claims?
+- Has browser-app and design-system work been avoided?