Physics Evaluation Report 문서 작성 가이드

이 디렉터리는 Physics Evaluation Agent가 작성하거나 제안하는 기능별 physics evaluation report를 보관하는 위치다.

Physics Evaluation Agent는 Reference Verification Agent가 pass-for-physics-evaluation으로 넘긴 결과에 대해 물리적 타당성을 검토한다. 이 agent는 reference tolerance를 다시 판정하지 않고, 평형, 반력 부호/합력, 변위 방향, 대칭성, 요소내력/응력 위치, rigid body mode 징후, energy/residual sanity, 테스트 모델 coverage를 검토한다.

기본 문서명은 docs/physics-evaluations/<feature-id>-physics-evaluation.md 형식을 사용한다.

Physics Evaluation Agent 역할

수행한다:

Reference Verification report가 pass-for-physics-evaluation인지 확인한다.
documented physical expectation이 있는 항목만 pass/fail로 판정한다.
global equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress/strain sanity, rigid body mode, energy/residual, model coverage를 검토한다.
물리 검토 실패를 equilibrium-failure, reaction-inconsistency, displacement-direction-failure, symmetry-failure, stress-location-failure, element-force-inconsistency, rigid-body-mode-suspected, nonfinite-result, model-coverage-gap, upstream-contract, environment로 분류한다.
실패 원인에 따라 Correction Agent, Reference Model Agent, Formulation Agent, I/O Definition Agent, Coordinator Agent로 handoff한다.
모든 물리 검토가 문서화된 기대값을 만족하면 Release Agent로 handoff한다.

수행하지 않는다:

source code를 수정하지 않는다.
tests를 수정하지 않는다.
CMake files를 수정하지 않는다.
requirements, formulations, I/O contracts, reference model contracts를 수정하지 않는다.
reference artifacts 또는 tolerance policies를 수정하지 않는다.
Abaqus, Nastran 또는 reference solver를 실행하지 않는다.
reference CSV를 생성하지 않는다.
reference tolerance를 다시 판정하지 않는다.
release readiness를 승인하지 않는다.
release notes 또는 final release checklist를 작성하지 않는다.

실행 순서

Physics Evaluation Agent는 다음 순서를 따른다.

EVIDENCE CHECK -> PHYSICS CHECKS -> CLASSIFY -> REPORT

EVIDENCE CHECK에서 다음 항목을 확인한다.

Reference Verification report status가 pass-for-physics-evaluation인지 여부
checked solver/reference CSVs
compared quantities
model purpose
documented physical expectations
sign convention
units and coordinate system
output location and component naming

Physics Checks

global equilibrium: 적용 하중, 반력, sign convention이 문서화된 경우 전체 힘/모멘트 평형을 검토한다.
reaction consistency: constrained DOF와 reaction component가 경계조건과 일관적인지 검토한다.
displacement direction: 하중 방향, 구속조건, 예상 변형 모드와 변위 부호/방향이 맞는지 검토한다.
symmetry: symmetry, antisymmetry, expected zero component가 모델 목적과 일치하는지 검토한다.
element force balance: element internal force와 외력/반력의 균형 또는 부호 일관성을 검토한다.
stress/strain: stress/strain 부호, component, coordinate system, output location이 모델 expectation과 일치하는지 검토한다.
rigid body mode: 불완전 구속, 비정상적으로 큰 변위, near-zero stiffness 징후를 검토한다.
energy/residual: energy_or_residual.csv 또는 residual output이 있을 때 energy balance, residual trend, convergence sanity를 검토한다.
model coverage: reference model이 claimed feature를 충분히 검증하는지 검토한다.

Failure Classification

equilibrium-failure: 전체 하중-반력 또는 모멘트 평형이 기대와 다르다.
reaction-inconsistency: constrained DOF reaction이 boundary condition 또는 load path와 일관되지 않다.
displacement-direction-failure: 변위 방향 또는 부호가 하중/구속조건과 물리적으로 맞지 않다.
symmetry-failure: expected symmetry, antisymmetry, zero component가 깨졌다.
stress-location-failure: stress/strain output location 또는 component 해석이 물리 expectation과 맞지 않다.
element-force-inconsistency: element internal force balance 또는 sign이 일관되지 않다.
rigid-body-mode-suspected: rigid body mode 또는 under-constrained model 징후가 있다.
nonfinite-result: NaN 또는 infinite value가 있다.
model-coverage-gap: reference model이 기능을 충분히 검증하지 못한다.
upstream-contract: physical expectation, sign convention, unit, coordinate, output location 계약이 누락 또는 충돌한다.
environment: 로컬 실행/읽기 환경 문제로 평가가 불가능하다.

문서 템플릿

# <feature title> Physics Evaluation Report

## Metadata
- feature_id: <feature-id>
- source_reference_verification_report: docs/reference-verifications/<feature-id>-reference-verification.md
- source_reference_model: docs/reference-models/<feature-id>-reference-models.md
- source_requirement: docs/requirements/<feature-id>.md
- source_formulation: docs/formulations/<feature-id>-formulation.md
- status: pass-for-release-agent | needs-correction | needs-reference-model | needs-formulation-review | needs-io-decision | needs-upstream-decision | blocked
- owner_agent: physics-evaluation-agent
- date: <YYYY-MM-DD>

## Input Evidence

| evidence | path_or_source | status | notes |
| --- | --- | --- | --- |
| reference_verification | docs/reference-verifications/<feature-id>-reference-verification.md | pass-for-physics-evaluation | <summary> |
| solver_results | <solver CSV path> | present | missing | <summary> |
| reference_results | references/<feature-id>/<model-id>/ | present | missing | <summary> |
| model_purpose | docs/reference-models/<feature-id>-reference-models.md | documented | missing | <summary> |
| physical_expectations | <source docs> | documented | missing | <summary> |

## Physics Checks

| check | documented_expectation | observed_evidence | verdict | classification |
| --- | --- | --- | --- | --- |
| global equilibrium | <expected force/moment balance> | <observed> | pass | fail | skipped | equilibrium-failure |
| reaction consistency | <expected reaction behavior> | <observed> | pass | fail | skipped | reaction-inconsistency |
| displacement direction | <expected direction/sign> | <observed> | pass | fail | skipped | displacement-direction-failure |
| symmetry | <expected symmetry/zero components> | <observed> | pass | fail | skipped | symmetry-failure |
| element force balance | <expected element force relation> | <observed> | pass | fail | skipped | element-force-inconsistency |
| stress/strain sanity | <expected sign/location/component> | <observed> | pass | fail | skipped | stress-location-failure |
| rigid body mode | <expected constrained behavior> | <observed> | pass | fail | skipped | rigid-body-mode-suspected |
| energy/residual | <expected energy/residual sanity> | <observed> | pass | fail | skipped | upstream-contract |
| model coverage | <claimed feature coverage> | <observed> | pass | fail | skipped | model-coverage-gap |

## Failure Classification
- classification: equilibrium-failure | reaction-inconsistency | displacement-direction-failure | symmetry-failure | stress-location-failure | element-force-inconsistency | rigid-body-mode-suspected | nonfinite-result | model-coverage-gap | upstream-contract | environment | N/A
- primary_failure: <short summary>
- evidence: <short relevant evidence>

## Evaluation Verdict
- verdict: pass-for-release-agent | needs-correction | needs-reference-model | needs-formulation-review | needs-io-decision | needs-upstream-decision | blocked
- reason: <short reason>

## Handoff Recommendation

| target_agent | reason | required_input |
| --- | --- | --- |
| Correction Agent | <implementation-owned physical failure> | <failed check and evidence> |
| Reference Model Agent | <model coverage or missing physical expectation issue> | <coverage gap> |
| Formulation Agent | <formulation or sign convention issue> | <failed physics check> |
| I/O Definition Agent | <output location/component/unit/coordinate ambiguity> | <contract gap> |
| Coordinator Agent | <blocked or repeated ambiguity> | <classification and open issue> |
| Release Agent | <all documented physics checks passed> | <evaluation report> |

## No-Change Assertion
- source_files_modified: false
- test_files_modified: false
- cmake_files_modified: false
- reference_artifacts_modified: false
- tolerance_policies_modified: false
- notes: <observed no-change evidence or exception>

## Open Issues
- <missing physical expectation, incomplete model coverage, contradictory sign convention, or unavailable energy/residual evidence>

상태 값

pass-for-release-agent: documented physics checks가 통과했고 Release Agent가 release readiness를 평가할 수 있다.
needs-correction: implementation-owned physical failure가 있어 Correction Agent가 필요하다.
needs-reference-model: reference model coverage가 부족하거나 추가 physical expectation이 필요하다.
needs-formulation-review: formulation 또는 numerical review 재검토가 필요하다.
needs-io-decision: output location, component naming, sign convention, unit, coordinate mapping이 evaluation을 막는다.
needs-upstream-decision: physical expectation, sign convention, model purpose, acceptance criterion이 누락 또는 충돌한다.
blocked: 사용자 또는 Coordinator Agent 결정 없이는 안전하게 진행할 수 없다.

품질 기준

Reference Verification report가 pass-for-physics-evaluation이 아니면 physics pass를 판정하지 않는다.
documented expectation이 없는 항목은 pass/fail로 판정하지 않고 skipped, needs-upstream-decision, 또는 needs-reference-model로 둔다.
평형 검토는 적용 하중, 반력, element/internal force sign convention이 문서화된 경우에만 수행한다.
stress/strain 검토는 output location, component naming, coordinate system, units가 정의된 경우에만 수행한다.
pass는 Release Agent로 넘길 수 있다는 뜻이며 release readiness 승인이 아니다.
reference artifacts와 tolerance policies는 수정하지 않는다.

10 KiB Raw Blame History