정식화 문서 작성 가이드

이 디렉터리는 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 HDF5 파일이나 deterministic CSV view를 생성하지 않는다.
release readiness를 승인하지 않는다.
Numerical Review Agent 검토 전 정식화를 최종 승인하지 않는다.

문서 템플릿

# <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:
symmetry:
positive_definiteness:
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 문제를 명시한다.