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

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:

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:

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?