# 정식화 문서 작성 가이드

이 디렉터리는 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 항목을 남긴다.

수행하지 않는다:
- Fortran 코드를 구현하지 않는다.
- Fortran source layout이나 파일 구조를 설계하지 않는다.
- Abaqus 해석을 직접 실행하지 않는다.
- 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 Fortran signatures, source layout, 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 문제를 명시한다.