docs: make reference metadata optional
This commit is contained in:
KOKO\Mimi
@@ -12,7 +12,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
|
||||
- 기능별 reference model portfolio를 smoke, analytical, patch test, benchmark, regression, negative/invalid-input model로 구분한다.
|
||||
- `model.inp`가 I/O Definition Agent의 supported Abaqus keyword subset 안에 있는지 확인한다.
|
||||
- `reference/<model-id>/` artifact bundle 구조와 필수 파일을 정의한다.
|
||||
- `metadata.json` provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 정의한다.
|
||||
- provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 기능별 Reference Model Contract에 정의한다. 선택 `metadata.json`이 존재하면 read-only로 inventory하고 계약과 대조한다.
|
||||
- Abaqus reference CSV 파일 요구사항을 정의한다.
|
||||
- requirement와 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.
|
||||
|
||||
@@ -53,12 +53,12 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
|
||||
|
||||
| model_id | category | purpose | status | required_artifacts |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp, metadata.json |
|
||||
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | patch test | <element consistency check> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | regression | <known defect guard> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp |
|
||||
|
||||
## Model Record
|
||||
|
||||
@@ -90,7 +90,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
|
||||
reference/
|
||||
<model-id>/
|
||||
model.inp
|
||||
metadata.json
|
||||
metadata.json # optional
|
||||
<model-id>_displacements.csv
|
||||
<model-id>_reactions.csv
|
||||
<model-id>_internalforces.csv
|
||||
@@ -100,7 +100,6 @@ reference/
|
||||
|
||||
Required files:
|
||||
- `model.inp`: Abaqus input file for the reference model.
|
||||
- `metadata.json`: provenance and model contract metadata.
|
||||
- `<model-id>_displacements.csv`: required when nodal displacement is a verification quantity.
|
||||
- `<model-id>_reactions.csv`: required when constrained DOF reactions or global equilibrium are verification quantities.
|
||||
- `<model-id>_internalforces.csv`: required when element internal force is a verification quantity.
|
||||
@@ -108,12 +107,19 @@ Required files:
|
||||
- `README.md`: short description, generation notes, and limitations.
|
||||
|
||||
Optional files:
|
||||
- `metadata.json`: optional machine-readable copy of reference metadata; inspect read-only and cross-check against the approved Reference Model Contract when present.
|
||||
- `<model-id>_strains.csv`: required when strain is part of the acceptance criteria.
|
||||
- `<model-id>_energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
|
||||
- `<model-id>_<quantity>.csv`: feature-specific reference quantity when upstream contracts require it.
|
||||
- `notes.md`: manual review notes.
|
||||
|
||||
## Metadata JSON Contract
|
||||
## Reference Metadata Contract
|
||||
|
||||
The feature-specific Reference Model Contract is the required source of truth for every field
|
||||
below. A bundle does not need a `metadata.json` file. When the optional file exists, use this
|
||||
schema, inventory it read-only, and compare every overlapping field with the contract and stored
|
||||
artifacts. Absence is `absent-allowed`; a conflict is an upstream contract/provenance issue and
|
||||
must not be resolved by silently preferring either value.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -180,10 +186,11 @@ Optional files:
|
||||
## 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, reference CSV schema version이 기록되어 있다.
|
||||
- Reference Model Contract에 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version과 artifact inventory가 기록되어 있다.
|
||||
- 선택 `metadata.json`의 부재는 허용되고, 존재하면 read-only inventory와 계약 일치 검사가 기록되어 있다.
|
||||
- 필요한 Abaqus reference CSV 파일이 존재하거나, 기능상 불필요한 quantity는 명확한 reason과 함께 제외되어 있다.
|
||||
- output request가 필요한 Abaqus reference CSV 물리량을 생성할 수 있도록 정의되어 있다.
|
||||
- required Abaqus reference CSV 또는 metadata provenance가 없으면 status는 `needs-reference-artifacts`다.
|
||||
- required Abaqus reference CSV 또는 Reference Model Contract의 필수 provenance가 없으면 status는 `needs-reference-artifacts`다.
|
||||
- tolerance, source, units, coordinate system이 불명확하면 status는 `needs-user-decision`이다.
|
||||
|
||||
## Open Issues and Downstream Handoff
|
||||
@@ -208,6 +215,7 @@ Optional files:
|
||||
- model data와 history data를 구분해야 한다.
|
||||
- output request와 required Abaqus reference CSV 사이의 연결이 명확해야 한다.
|
||||
- `reference/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
|
||||
- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 포함되어야 한다.
|
||||
- Reference Model Contract에는 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 포함되어야 한다.
|
||||
- 선택 `metadata.json`은 없어도 되며, 존재할 때만 read-only로 참고하고 계약과 대조한다.
|
||||
- required Abaqus reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
|
||||
- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, verification method로 추적되어야 한다.
|
||||
|
||||
@@ -187,16 +187,16 @@ These files shall not be generated, modified, renamed, corrected or restored by
|
||||
Harness. Their spaces and existing CAE report headers are legacy aliases, not a naming pattern for
|
||||
new models.
|
||||
|
||||
Only for this approved legacy bundle:
|
||||
For this approved legacy bundle:
|
||||
|
||||
- `metadata.json`: N/A
|
||||
- `metadata.json`: absent-allowed under the project-wide optional metadata policy
|
||||
- `README.md`: N/A
|
||||
- stress CSV: N/A because beam stress reference comparison is outside the approved V0 scope
|
||||
|
||||
The approved design and this contract jointly replace those missing files by recording model ID,
|
||||
provenance, generator, source commit, units, coordinate systems, step/frame identity, logical CSV
|
||||
schema, exact inventory, tolerance policy and the stress N/A reason. Their absence therefore does
|
||||
not change the legacy record to `needs-reference-artifacts`.
|
||||
The approved design and this contract record model ID, provenance, generator, source commit,
|
||||
units, coordinate systems, step/frame identity, logical CSV schema, exact inventory, tolerance
|
||||
policy and the stress N/A reason. The optional metadata file's absence and the approved legacy
|
||||
README/stress exclusions therefore do not change the record to `needs-reference-artifacts`.
|
||||
|
||||
### Future reference bundles
|
||||
|
||||
@@ -207,7 +207,7 @@ marks a quantity N/A:
|
||||
reference/
|
||||
<model-id>/
|
||||
model.inp
|
||||
metadata.json
|
||||
metadata.json # optional
|
||||
<model-id>_displacements.csv
|
||||
<model-id>_reactions.csv
|
||||
<model-id>_internalforces.csv
|
||||
@@ -215,14 +215,15 @@ reference/
|
||||
README.md
|
||||
```
|
||||
|
||||
CSV names are canonical `<model-id>_*.csv` names. `metadata.json` and `README.md` are mandatory.
|
||||
A quantity CSV may be omitted only when the upstream acceptance contract explicitly records N/A
|
||||
and gives its verification replacement. Missing required files keep that model at
|
||||
`needs-reference-artifacts`.
|
||||
CSV names are canonical `<model-id>_*.csv` names. `README.md` is mandatory for later bundles;
|
||||
`metadata.json` is optional. A quantity CSV may be omitted only when the upstream acceptance
|
||||
contract explicitly records N/A and gives its verification replacement. Missing required files
|
||||
or required Reference Model Contract provenance keep that model at `needs-reference-artifacts`.
|
||||
|
||||
## Metadata JSON Contract
|
||||
## Reference Metadata Contract
|
||||
|
||||
`metadata.json` is N/A only for `cantilever-beam-b33`. Every later bundle shall include at least:
|
||||
This document is the required source of truth for the following metadata. A later bundle may
|
||||
optionally duplicate it in `metadata.json` using at least this schema:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -250,7 +251,8 @@ and gives its verification replacement. Missing required files keep that model a
|
||||
```
|
||||
|
||||
No agent may invent unknown provenance fields or mark a bundle ready merely because filenames
|
||||
exist.
|
||||
exist. An absent `metadata.json` is allowed. If the file exists, inventory it read-only and report
|
||||
any disagreement with this contract or stored artifacts as an upstream contract/provenance issue.
|
||||
|
||||
## Abaqus Reference CSV Requirements
|
||||
|
||||
@@ -365,7 +367,7 @@ Read-only inventory inspection on `2026-08-09` established the following pre-imp
|
||||
- every projected numeric field is finite and every row has the header arity;
|
||||
- generator, source commit, SI units, coordinates, step/increment/time and tolerance provenance are
|
||||
recorded in the approved design and this contract;
|
||||
- legacy `metadata.json`, `README.md` and stress CSV are accepted N/A exceptions;
|
||||
- absent `metadata.json` is allowed by project-wide policy; legacy `README.md` and stress CSV are accepted N/A exceptions;
|
||||
- no reference value was recalculated and no comparison was performed.
|
||||
|
||||
Before an actual comparison, tooling must repeat all artifact checks, verify the exact Frame and
|
||||
|
||||
Reference in New Issue
Block a user