add uncommitted files

2026-07-29 23:32:26 +09:00
parent fb0f8f39a0
commit f5379472ce
80 changed files with 7461 additions and 1 deletions
@@ -0,0 +1,26 @@
+{
+  "project": "FESA",
+  "phase": "fem-and-beam-kernel",
+  "steps": [
+    {
+      "step": 0,
+      "name": "quadrature-and-shape-functions",
+      "status": "pending"
+    },
+    {
+      "step": 1,
+      "name": "dof-manager",
+      "status": "pending"
+    },
+    {
+      "step": 2,
+      "name": "beam-local-frame",
+      "status": "pending"
+    },
+    {
+      "step": 3,
+      "name": "timoshenko-stiffness-kernel",
+      "status": "pending"
+    }
+  ]
+}
@@ -0,0 +1,47 @@
+# Step 0: Quadrature and Shape Functions
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/superpowers/plans/2026-07-29-fesa-phase-1.md`
+- `/include/fesa/core/vec3.hpp`
+
+## 작업
+
+특정 analysis에 종속되지 않는 1D Gauss quadrature와 2절점 선형 shape function을
+`fem` 모듈에 구현한다.
+
+```cpp
+struct GaussPoint1D final { double xi; double weight; };
+[[nodiscard]] std::span<const GaussPoint1D> gauss_rule_1d(int order);
+[[nodiscard]] std::array<double, 2> line2_shape(double xi);
+[[nodiscard]] std::array<double, 2> line2_shape_derivative(double xi);
+[[nodiscard]] double line2_jacobian(double length);
+```
+
+- partition of unity, endpoint interpolation, derivative sum zero, 1점/2점 적분의
+  정확도, length/2 Jacobian, invalid order/length를 실패 테스트로 먼저 작성한다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "Quadrature|ShapeFunction|Jacobian" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. 수학 invariant 테스트의 실패를 확인한다.
+2. 고정 크기 값 타입과 최소 함수만 구현한다.
+3. tolerance 근거를 테스트 이름 또는 주석에 명시한다.
+4. 전체 CTest와 index 갱신을 수행한다.
+
+## 금지사항
+
+- Beam stiffness를 이 step에 구현하지 마라. 이유: 수학 primitive 경계를 유지한다.
+- runtime quadrature registry를 만들지 마라. 이유: 1점과 2점만 필요하다.
+- 잘못된 길이에 임의 epsilon을 더하지 마라. 이유: model 오류를 숨긴다.
@@ -0,0 +1,57 @@
+# Step 1: DOF Manager
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/include/fesa/model/domain.hpp`
+- `/include/fesa/model/step_definition.hpp`
+- `/include/fesa/fem/`
+
+## 작업
+
+절점당 6자유도와 constrained/free equation numbering을 전담하는 `DofManager`를
+구현한다.
+
+```cpp
+enum class NodeDof : std::uint8_t { ux, uy, uz, rx, ry, rz };
+struct DofAddress final { NodeId node; NodeDof dof; };
+class DofManager final {
+public:
+    [[nodiscard]] static DofManager build(const Domain&);
+    [[nodiscard]] std::size_t full_dof_count() const noexcept;
+    [[nodiscard]] std::size_t free_equation_count() const noexcept;
+    [[nodiscard]] std::optional<std::size_t> equation(DofAddress) const;
+    [[nodiscard]] std::array<std::size_t, 12> element_full_dofs(
+        const BeamElement&) const;
+    [[nodiscard]] std::vector<double> reconstruct_full(
+        std::span<const double> reduced) const;
+};
+```
+
+- external label 순서와 무관한 deterministic numbering, 비영 지정값, full/reduced
+  reconstruction, invalid DOF를 실패 테스트로 먼저 고정한다.
+- equation ID를 Node/Element에 쓰지 않는다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "DofManager|EquationNumbering" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. 실패 테스트를 먼저 실행한다.
+2. Domain 읽기 전용 view만 사용해 numbering을 구현한다.
+3. constrained/free mapping과 reconstruction을 직접 assertion한다.
+4. 전체 테스트와 index 갱신을 수행한다.
+
+## 금지사항
+
+- sparse matrix pattern을 소유하지 마라. 이유: assembly 책임이다.
+- Node/Element에 equation ID를 저장하지 마라. 이유: 아키텍처 규칙 위반이다.
+- MPC나 penalty 자유도를 추가하지 마라. 이유: Phase 1 범위 밖이다.
@@ -0,0 +1,53 @@
+# Step 2: Beam Local Frame
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/include/fesa/core/vec3.hpp`
+- `/include/fesa/model/beam_section.hpp`
+- `/include/fesa/model/beam_element.hpp`
+
+## 작업
+
+두 절점과 mandatory orientation vector로 오른손 직교 Beam 국부 기저와 12x12
+좌표변환을 계산한다.
+
+```cpp
+struct BeamFrame final { Vec3 ex; Vec3 ey; Vec3 ez; };
+struct BeamFrameResult final {
+    std::optional<BeamFrame> frame;
+    std::vector<Diagnostic> diagnostics;
+};
+[[nodiscard]] BeamFrameResult make_beam_frame(
+    const Vec3& first,
+    const Vec3& second,
+    const Vec3& orientation);
+[[nodiscard]] Matrix12 beam_transformation(const BeamFrame&);
+```
+
+- 축 방향 정규화, Gram-Schmidt, 오른손성, 직교성, 회전 불변성을 테스트한다.
+- zero length, zero orientation, orientation parallel to element axis를 실패시킨다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "BeamFrame|BeamTransformation" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. 축 정렬 및 임의 회전 테스트의 실패를 확인한다.
+2. tolerance를 scale-aware하게 적용한다.
+3. \(R R^T=I\), determinant \(+1\), 변환 energy invariant를 확인한다.
+4. 전체 테스트와 index를 갱신한다.
+
+## 금지사항
+
+- orientation을 자동 추측하지 마라. 이유: 입력 계약에서 필수다.
+- degenerate vector를 임의 축으로 대체하지 마라. 이유: 모델 오류를 숨긴다.
+- element stiffness를 추가하지 마라. 이유: 다음 kernel step의 책임이다.
@@ -0,0 +1,59 @@
+# Step 3: Timoshenko Stiffness Kernel
+
+## 읽어야 할 파일
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/superpowers/plans/2026-07-29-fesa-phase-1.md`
+- `/include/fesa/fem/`
+- `/include/fesa/model/material.hpp`
+- `/include/fesa/model/beam_section.hpp`
+- `/docs/formulation/timoshenko-beam-3d.md`가 있으면 전체
+
+## 작업
+
+먼저 `docs/formulation/timoshenko-beam-3d.md`에 자유도 순서, 변형률, 부호,
+constitutive matrix, Jacobian과 선택적 감차적분 식을 작성한다. 그 식으로 실제
+2절점 3D isoparametric Timoshenko Beam stiffness를 구현한다.
+
+```cpp
+struct Beam3D2Input final {
+    std::array<Vec3, 2> coordinates;
+    IsotropicElastic material;
+    BeamSection section;
+};
+struct Beam3D2Contribution final {
+    Matrix12 local_stiffness;
+    Matrix12 global_stiffness;
+    BeamFrame frame;
+};
+[[nodiscard]] BeamKernelResult compute_beam3d2(const Beam3D2Input&);
+```
+
+- 축·굽힘·비틀림은 2점, 전단은 1점 Gauss 적분한다.
+- \(G=E/[2(1+\nu)]\)를 사용한다.
+- 먼저 대칭성, 강체운동 zero energy, 축/비틀림/굽힘 해석해, shear-dominant,
+  세장비 sweep과 좌표회전 invariant 테스트를 실패시킨다.
+
+## Acceptance Criteria
+
+```powershell
+cmake --build --preset windows-debug
+ctest --preset windows-debug -R "Beam3D2|Timoshenko|RigidBody" --output-on-failure
+ctest --preset windows-debug --output-on-failure
+```
+
+## 검증 절차
+
+1. 정식화 문서를 production code보다 먼저 확정한다.
+2. 실패 테스트를 실행해 가짜 matrix로 통과하지 않음을 확인한다.
+3. 최소 kernel을 구현하고 focused/full test를 실행한다.
+4. 식과 코드의 DOF/component 순서를 대조하고 index를 갱신한다.
+
+## 금지사항
+
+- 닫힌형 가짜 stiffness를 임시로 넣지 마라. 이유: 파이프라인 수치 신뢰성을 훼손한다.
+- shear term을 2점 적분하지 마라. 이유: 승인된 selective integration과 다르다.
+- 비선형, 워핑, offset 또는 \(I_{yz}\)를 추가하지 마라. 이유: Phase 1 밖이다.