ResearchProject/FESurrogateModelTutorial/AGENTS.md

# 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?