initial commit

2026-06-09 12:27:22 +09:00
commit f186160e44
79 changed files with 6915 additions and 0 deletions
@@ -0,0 +1,148 @@
+# 정식화 문서 작성 가이드
+
+이 디렉터리는 Formulation Agent가 작성하거나 제안한 기능별 유한요소 정식화 문서를 보관하는 위치다.
+
+기본 파일명은 `docs/formulations/<feature-id>-formulation.md` 형식을 사용한다. 각 문서는 Requirement Agent의 요구조건과 Research Agent의 연구 브리프를 입력으로 받아 Implementation Planning Agent와 Implementation Agent가 사용할 수 있는 수학/알고리즘 계약을 제공해야 한다.
+
+## Formulation Agent 역할
+
+Formulation Agent는 구현 가능한 FEM 정식화 문서를 작성한다.
+
+수행한다:
+- strong form, weak form, discretization을 정리한다.
+- shape functions, `B` matrix 또는 kinematic operator를 정의한다.
+- constitutive contract, element residual/internal force, stiffness/tangent matrix를 정리한다.
+- numerical integration, mapping, Jacobian 규칙을 명시한다.
+- output recovery, algorithm pseudocode, edge case, numerical risk를 정리한다.
+- Numerical Review Agent가 검토할 handoff 항목을 남긴다.
+
+수행하지 않는다:
+- C++ 코드를 구현하지 않는다.
+- C++ API나 파일 구조를 설계하지 않는다.
+- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
+- reference CSV 결과를 생성하지 않는다.
+- release readiness를 승인하지 않는다.
+- Numerical Review Agent 검토 전 정식화를 최종 승인하지 않는다.
+
+## 문서 템플릿
+
+```markdown
+# <feature title> Formulation
+
+## Metadata
+- feature_id: <feature-id>
+- source_requirement: docs/requirements/<feature-id>.md
+- source_research: docs/research/<feature-id>-research.md
+- status: draft | needs-research | ready-for-numerical-review
+- owner_agent: formulation-agent
+- date: <YYYY-MM-DD>
+
+## Scope and Assumptions
+- analysis_type: linear static | nonlinear static | modal | dynamic | other
+- element_type: <target element>
+- deformation: small | large | TBD
+- linearity: linear | nonlinear | TBD
+- material_model_boundary: <scope>
+- coordinate_system: <global/local coordinates>
+- units: <unit system>
+
+## Primary Variables and DOFs
+- nodal_variables: <variables>
+- dof_ordering: <ordering>
+- sign_convention: <convention>
+- constrained_free_dof_assumptions: <assumptions>
+
+## Strong Form and Boundary Conditions
+- governing_equation: <equation>
+- dirichlet_boundary: <essential BC>
+- neumann_boundary: <natural BC>
+- natural_boundary_terms: <terms>
+
+## Weak or Variational Form
+- test_functions: <definition>
+- integration_by_parts: <steps>
+- internal_virtual_work: <expression>
+- external_virtual_work: <expression>
+
+## Discretization
+- interpolation: <field interpolation>
+- shape_functions: <shape functions>
+- partition_of_unity_check: <expected check>
+- kronecker_delta_check: <expected check>
+- nodal_layout: <layout>
+
+## Kinematics
+- strain_displacement_relation: <relation>
+- B_matrix_or_kinematic_operator: <definition>
+- deformation_gradient: <definition or N/A>
+- strain_measure: <definition or N/A>
+
+## Constitutive Contract
+- elasticity_matrix_or_stress_update: <contract>
+- material_state_variables: <variables or N/A>
+- assumptions_and_constraints: <assumptions>
+
+## Element Equations
+- internal_force_or_residual: <expression>
+- external_force: <expression>
+- stiffness_or_tangent_matrix: <expression>
+- mass_or_damping: <required expression or N/A>
+- vector_matrix_dimensions: <dimensions>
+
+## Mapping and Numerical Integration
+- reference_coordinates: <coordinates>
+- isoparametric_mapping: <mapping>
+- jacobian: <definition>
+- determinant_checks: <validity checks>
+- gauss_points_and_weights: <rule>
+- integration_policy: full | reduced | selective | analytical | TBD
+
+## Output Recovery
+- displacement: <location and convention>
+- reaction: <calculation>
+- element_force: <calculation>
+- strain: <location and recovery>
+- stress: <location and recovery>
+- nodal_extrapolation: <policy or N/A>
+
+## Algorithm Pseudocode
+```text
+math-level element routine and assembly flow only
+no C++ signatures, class names, or file paths
+```
+
+## Numerical Risks
+- rigid_body_modes: <risk/check>
+- patch_test: <expected test>
+- symmetry: <expected property>
+- positive_definiteness: <expected property>
+- hourglass: <risk or N/A>
+- shear_locking: <risk or N/A>
+- volumetric_locking: <risk or N/A>
+- distortion: <risk/check>
+- singular_jacobian: <risk/check>
+
+## Open Issues and Downstream Handoff
+
+### Numerical Review Agent
+- <derivations, assumptions, numerical risks, open issues>
+
+### I/O Definition Agent
+- <required inputs, outputs, units, coordinate conventions, output locations>
+
+### Reference Model Agent
+- <benchmarkable quantities, patch test needs, expected invariants, edge cases>
+
+### Implementation Planning Agent
+- <math-level pseudocode, acceptance-relevant quantities, tests to write first>
+```
+
+## 품질 기준
+
+- 요구조건과 연구 브리프에 없는 값을 임의로 확정하지 않는다.
+- strong form, weak form, discretization, kinematics, constitutive contract, element equations를 구분한다.
+- shape functions는 가능한 경우 partition of unity와 Kronecker delta 검사를 포함한다.
+- numerical integration은 integration point, weight, 적분 대상, full/reduced/selective 정책을 포함한다.
+- mapping은 reference coordinates, Jacobian, determinant validity check를 포함한다.
+- output recovery는 nodal, element-level, integration-point 위치를 구분한다.
+- numerical risk는 rigid body modes, patch test, hourglass, locking, Jacobian 문제를 명시한다.