김경종
305 lines
13 KiB
Markdown
305 lines
13 KiB
Markdown
# Reference Model 문서 작성 가이드
|
|
|
|
이 디렉터리는 Reference Model Agent가 작성하거나 제안한 기능별 reference model 설계 문서를 보관하는 위치다.
|
|
|
|
Reference Model Agent는 Abaqus User Subroutine 검증에 필요한 Abaqus `.inp` 기반 테스트 모델 포트폴리오와 `references/<feature-id>/<model-id>/` artifact bundle 계약을 정의한다. Agent는 Abaqus 해석을 직접 실행하지 않고, reference CSV 값을 생성하지 않으며, solver 결과 비교나 release readiness 승인도 하지 않는다.
|
|
|
|
기본 파일명은 `docs/reference-models/<feature-id>-reference-models.md` 형식을 사용한다. 각 문서는 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의를 입력으로 받아 구현 전에 준비해야 할 테스트 모델과 reference artifact 요구사항을 정의해야 한다.
|
|
|
|
## Reference Model Agent 역할
|
|
|
|
수행한다:
|
|
- 기능별 reference model portfolio를 smoke, analytical, patch test, benchmark, regression, negative/invalid-input model로 구분한다.
|
|
- `model.inp`가 I/O Definition Agent의 supported Abaqus keyword subset 안에 있는지 확인한다.
|
|
- `references/<feature-id>/<model-id>/` artifact bundle 구조와 필수 파일을 정의한다.
|
|
- `metadata.json` provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 정의한다.
|
|
- `displacements.csv`, `reactions.csv`, `element_forces.csv`, `stresses.csv` 요구사항을 정의한다.
|
|
- requirement와 model, compared quantity, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.
|
|
|
|
수행하지 않는다:
|
|
- Fortran 코드를 구현하지 않는다.
|
|
- parser를 구현하지 않는다.
|
|
- Fortran source layout이나 파일 구조를 설계하지 않는다.
|
|
- Abaqus 해석을 직접 실행하지 않는다.
|
|
- reference CSV를 생성하지 않는다.
|
|
- solver 결과를 비교하지 않는다.
|
|
- release readiness를 승인하지 않는다.
|
|
- reference 값, tolerance, Abaqus compatibility를 임의로 만들지 않는다.
|
|
|
|
## 문서 템플릿
|
|
|
|
```markdown
|
|
# <feature title> Reference Models
|
|
|
|
## Metadata
|
|
- feature_id: <feature-id>
|
|
- source_requirement: docs/requirements/<feature-id>.md
|
|
- source_research: docs/research/<feature-id>-research.md
|
|
- source_formulation: docs/formulations/<feature-id>-formulation.md
|
|
- source_numerical_review: docs/numerical-reviews/<feature-id>-review.md
|
|
- source_io_definition: docs/io-definitions/<feature-id>-io.md
|
|
- status: draft | needs-user-decision | needs-reference-artifacts | ready-for-implementation-planning | blocked
|
|
- owner_agent: reference-model-agent
|
|
- date: <YYYY-MM-DD>
|
|
|
|
## Reference Strategy
|
|
- verification_scope: <feature verification purpose>
|
|
- code_verification: <unit/math-level checks supported by this portfolio>
|
|
- solution_verification: <mesh, convergence, patch, or analytical checks>
|
|
- benchmark_reference_comparison: <Abaqus/NAFEMS/NASA/paper-derived comparison plan>
|
|
- excluded_validation_scope: <physical experiment validation excluded unless explicitly available>
|
|
|
|
## Model Inventory
|
|
|
|
| model_id | category | purpose | status | required_artifacts |
|
|
| --- | --- | --- | --- | --- |
|
|
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, metadata.json, required CSVs |
|
|
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, required CSVs |
|
|
| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, required CSVs |
|
|
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, required CSVs |
|
|
| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, required CSVs |
|
|
| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp, metadata.json |
|
|
|
|
## Model Record
|
|
|
|
### <model-id>
|
|
- category: smoke | analytical | patch test | benchmark | regression | negative/invalid-input
|
|
- purpose: <what this model proves>
|
|
- verified_requirements: [<requirement-id>]
|
|
- analysis_type: <linear static | nonlinear static | modal | other>
|
|
- element_type: <Abaqus element type and subroutine feature scope>
|
|
- material: <material model and values>
|
|
- boundary_conditions: <BC summary>
|
|
- loads: <load summary>
|
|
- expected_physical_quantities: displacement | reaction | element force | stress | strain | energy | residual
|
|
- tolerance: <absolute/relative/norm policy or needs-user-decision>
|
|
- source: <user | analytical | Abaqus Verification Guide | Abaqus Benchmarks Guide | NAFEMS | NASA/FEMCI | paper>
|
|
- artifact_status: draft | needs-reference-artifacts | ready-for-implementation-planning | blocked
|
|
|
|
## Abaqus Input Requirements
|
|
- input_file: references/<feature-id>/<model-id>/model.inp
|
|
- supported_keyword_subset: <keywords from docs/io-definitions/<feature-id>-io.md>
|
|
- model_data: <nodes, elements, sets, material, section, coordinates, units>
|
|
- history_data: <step, procedure, boundary conditions, loads, output requests>
|
|
- output_requests: <requests needed to populate reference CSV files>
|
|
- unsupported_keyword_policy: unsupported | ignored-with-warning | requires-user-decision
|
|
|
|
## Artifact Bundle Contract
|
|
|
|
```text
|
|
references/
|
|
<feature-id>/
|
|
<model-id>/
|
|
model.inp
|
|
metadata.json
|
|
job.msg.tail.txt
|
|
job.dat.tail.txt
|
|
job.log.tail.txt
|
|
job.sta.tail.txt
|
|
result.odb.sha256
|
|
extraction/
|
|
extract_odb_to_csv.py
|
|
extracted/
|
|
displacements.csv
|
|
reactions.csv
|
|
element_forces.csv
|
|
stresses.csv
|
|
README.md
|
|
```
|
|
|
|
Required files:
|
|
- `model.inp`: Abaqus input file for the reference model.
|
|
- `metadata.json`: provenance and model contract metadata.
|
|
- `.msg/.dat/.log/.sta` tail files: externally generated Abaqus job evidence.
|
|
- `extracted/*.csv`: ODB-extracted CSV reference results declared in `metadata.json`.
|
|
- `README.md`: short description, generation notes, and limitations.
|
|
|
|
Optional files:
|
|
- `result.odb.sha256`: ODB hash evidence when the ODB itself is not stored.
|
|
- `extraction/extract_odb_to_csv.py`: copy of the user-run extraction script when available.
|
|
- `extracted/strains.csv`: strain reference results when required.
|
|
- `extracted/energy_or_residual.csv`: energy, residual, or convergence reference results when required.
|
|
- `notes.md`: manual review notes.
|
|
|
|
## Metadata JSON Contract
|
|
|
|
```json
|
|
{
|
|
"feature_id": "<feature-id>",
|
|
"model_id": "<model-id>",
|
|
"artifact_status": "draft | needs-reference-artifacts | ready-for-implementation-planning | blocked",
|
|
"abaqus_version": "<version or needs-user-decision>",
|
|
"generation_owner": "<person/procedure>",
|
|
"generation_date": "<YYYY-MM-DD>",
|
|
"source_documents": ["docs/requirements/<feature-id>.md"],
|
|
"units": "<unit system>",
|
|
"coordinate_system": "global Cartesian unless otherwise documented",
|
|
"analysis_type": "<analysis type>",
|
|
"element_types": ["<Abaqus element type>"],
|
|
"material_values": {},
|
|
"boundary_condition_summary": "<summary>",
|
|
"load_summary": "<summary>",
|
|
"output_requests": ["U", "RF", "S", "<feature-specific quantities>"],
|
|
"csv_schema_version": "<version>",
|
|
"tolerance_policy": "<absolute/relative/norm policy>",
|
|
"limitations": ["<known limitation>"]
|
|
}
|
|
```
|
|
|
|
## Reference CSV Requirements
|
|
|
|
### displacements.csv
|
|
- Required when nodal displacement is a verification quantity.
|
|
- Must include step/frame identity, node id, displacement components, coordinate system, and units.
|
|
|
|
### reactions.csv
|
|
- Required when constrained DOF reactions or global equilibrium are verification quantities.
|
|
- Must include step/frame identity, node id, reaction components, coordinate system, and units.
|
|
|
|
### element_forces.csv
|
|
- Required when element internal force is a verification quantity.
|
|
- Must include step/frame identity, element id, output location, component, value, and units.
|
|
|
|
### stresses.csv
|
|
- Required when stress is a verification quantity.
|
|
- Must include step/frame identity, element id, integration point or recovery location, component, value, coordinate system, and units.
|
|
|
|
### Optional CSVs
|
|
- `strains.csv`: required when strain is part of the acceptance criteria.
|
|
- `energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
|
|
|
|
## Coverage Matrix
|
|
|
|
| requirement_id | model_id | compared_quantity | artifact_file | tolerance | verification_method | status |
|
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
| <req-id> | <model-id> | displacement | displacements.csv | <policy> | reference-comparison | draft |
|
|
| <req-id> | <model-id> | reaction | reactions.csv | <policy> | reference-comparison | draft |
|
|
| <req-id> | <model-id> | element force | element_forces.csv | <policy> | reference-comparison | draft |
|
|
| <req-id> | <model-id> | stress | stresses.csv | <policy> | reference-comparison | draft |
|
|
|
|
## Artifact Acceptance Checklist
|
|
- 모든 `must` requirement가 최소 하나의 `model_id`와 `compared_quantity`에 연결되어 있다.
|
|
- `model.inp`가 기능별 supported Abaqus keyword subset을 벗어나지 않는다.
|
|
- `metadata.json`에 provenance, Abaqus version/source, units, coordinate system, tolerance, CSV schema version이 기록되어 있다.
|
|
- 필수 CSV 파일이 존재하거나, 기능상 불필요한 파일은 명확한 reason과 함께 제외되어 있다.
|
|
- output request가 필요한 CSV 물리량을 생성할 수 있도록 정의되어 있다.
|
|
- reference CSV가 없으면 status는 `needs-reference-artifacts`다.
|
|
- tolerance, source, units, coordinate system이 불명확하면 status는 `needs-user-decision`이다.
|
|
|
|
## Open Issues and Downstream Handoff
|
|
|
|
### I/O Definition Agent
|
|
- <supported keyword, output request, CSV schema clarification>
|
|
|
|
### Implementation Planning Agent
|
|
- <tests that should fail before implementation, model order, acceptance criteria>
|
|
|
|
### Reference Verification Agent
|
|
- <CSV schema, ID matching, units, coordinate conventions, output locations, tolerance mapping>
|
|
|
|
### Physics Evaluation Agent
|
|
- <equilibrium, symmetry, displacement direction, stress location, rigid body mode, load path sanity checks>
|
|
```
|
|
|
|
## 품질 기준
|
|
|
|
- Reference model의 목적과 검증 대상 requirement가 명확해야 한다.
|
|
- `model.inp`는 Abaqus input file이며, 기능별 supported keyword subset을 따라야 한다.
|
|
- model data와 history data를 구분해야 한다.
|
|
- output request와 required CSV 사이의 연결이 명확해야 한다.
|
|
- `references/<feature-id>/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
|
|
- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, CSV schema version이 포함되어야 한다.
|
|
- reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
|
|
- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, tolerance, verification method로 추적되어야 한다.
|
|
|
|
## Abaqus UserSubroutine artifact metadata v1
|
|
|
|
For Fortran Abaqus UserSubroutine work, each stored artifact bundle may include `metadata.json` with:
|
|
|
|
```json
|
|
{
|
|
"schema_version": "abaqus-user-subroutine-artifact-v1",
|
|
"feature_id": "<feature-id>",
|
|
"model_id": "<model-id>",
|
|
"artifact_status": "draft | needs-reference-artifacts | ready-for-comparison | blocked",
|
|
"abaqus": {
|
|
"version": "<Abaqus version>",
|
|
"precision": "single | double"
|
|
},
|
|
"compiler": {
|
|
"vendor": "Intel oneAPI",
|
|
"name": "ifx | ifort",
|
|
"version": "<compiler version>"
|
|
},
|
|
"subroutine": {
|
|
"entry_points": ["UMAT"],
|
|
"source_files": [
|
|
{
|
|
"path": "src/fortran/abaqus/UMAT.for",
|
|
"language": "Fortran",
|
|
"sha256": "<source sha256>"
|
|
}
|
|
]
|
|
},
|
|
"input_file": "model.inp",
|
|
"outputs": {
|
|
"tails": {
|
|
"msg": "job.msg.tail.txt",
|
|
"dat": "job.dat.tail.txt",
|
|
"log": "job.log.tail.txt",
|
|
"sta": "job.sta.tail.txt"
|
|
},
|
|
"csv": {
|
|
"stresses": "extracted/stresses.csv"
|
|
}
|
|
},
|
|
"extraction": {
|
|
"source_odb": "job.odb",
|
|
"tool": "Abaqus Python",
|
|
"extracted_at": "<ISO-8601 datetime>",
|
|
"csv_directory": "extracted",
|
|
"script": "extraction/extract_odb_to_csv.py",
|
|
"odb_sha256_file": "result.odb.sha256"
|
|
},
|
|
"comparisons": {
|
|
"stresses": {
|
|
"reference_csv": "extracted/stresses.csv",
|
|
"actual_csv": "extracted/stresses.csv",
|
|
"required_columns": [
|
|
"step",
|
|
"frame",
|
|
"instance",
|
|
"element_label",
|
|
"integration_point",
|
|
"section_point",
|
|
"output_position",
|
|
"component",
|
|
"coordinate_system",
|
|
"unit",
|
|
"value"
|
|
],
|
|
"key_columns": [
|
|
"step",
|
|
"frame",
|
|
"instance",
|
|
"element_label",
|
|
"integration_point",
|
|
"section_point",
|
|
"output_position",
|
|
"component"
|
|
],
|
|
"value_column": "value",
|
|
"unit_column": "unit",
|
|
"coordinate_system_column": "coordinate_system",
|
|
"tolerance": {
|
|
"absolute": 1.0e-8,
|
|
"relative": 1.0e-6,
|
|
"relative_floor": 1.0e-12
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
`artifact_status=ready-for-comparison` means `scripts/validate_reference_artifacts.py` must find all declared files, confirm source SHA-256 values, require `.msg/.dat/.log/.sta` tails, require ODB extraction provenance, and require declared CSVs to match `extracted/*.csv`. `comparisons` defines the executable CSV schema, row key, and tolerance contract for `scripts/compare_extracted_csv.py`. Agents must not generate or edit the declared reference CSVs unless an explicit reference-artifact phase authorizes that work.
|