KOKO\Mimi
325 lines
15 KiB
Markdown
325 lines
15 KiB
Markdown
# FESA Session Handoff
|
|
|
|
## 1. 목적과 기준 문서
|
|
|
|
이 문서는 `beam-reference-qualification` 완료 후 새 세션에서 마지막 Phase 1 단계인
|
|
`internal-release`를 시작하기 위한 인수인계 기록이다. 과거 phase의 구현 역사를
|
|
반복하기보다 현재 기준선, 검증 결과, 남은 작업과 실행 순서를 제공한다.
|
|
|
|
다음 문서를 우선 기준으로 사용한다.
|
|
|
|
- `AGENTS.md`
|
|
- `docs/PRD.md`
|
|
- `docs/ARCHITECTURE.md`
|
|
- `docs/ADR.md`
|
|
- `docs/HARNESS.md`
|
|
- `docs/HDF5_SCHEMA.md`
|
|
- `docs/ABAQUS_INPUT_SUBSET.md`
|
|
- `docs/formulation/timoshenko-beam-3d.md`
|
|
- `docs/VALIDATION.md`
|
|
- `phases/internal-release/index.json`
|
|
- `phases/internal-release/step0.md`부터 `step4.md`
|
|
|
|
내용이 충돌하면 `AGENTS.md`, PRD/ADR/아키텍처, 완료된 phase metadata와 실제
|
|
테스트를 우선한다. 특히 `internal-release`의 기존 Step 0과 Step 4에 남아 있는
|
|
reference 범위 설명은 4절의 최신 계약으로 바로잡은 뒤 release evidence에 사용한다.
|
|
|
|
## 2. Git과 Phase 상태
|
|
|
|
2026-08-03 기준 구현 상태는 다음과 같다.
|
|
|
|
- 기준 브랜치: `dev`
|
|
- 이 문서 갱신 직전 구현 HEAD: `6bc7cc3adadded6f1a2a0ed45449b2264c0f7a4e`
|
|
- `feat-beam-reference-qualification`은 `dev`에 fast-forward 병합된 뒤 로컬에서
|
|
삭제됐다.
|
|
- `internal-release`를 제외한 `phases/index.json`의 모든 phase가 `completed`다.
|
|
- 다음 Phase: `internal-release`
|
|
- 다음 Step: Step 0 `release-checklist`
|
|
- Step 0부터 Step 4까지 모두 `pending`이다.
|
|
- 이 문서의 갱신은 구현 기준선 다음의 docs-only commit이다.
|
|
|
|
새 세션에서는 기록된 hash를 강제로 맞추지 말고 로컬과 원격의 실제 상태를 먼저
|
|
확인한다. 이 HANDOFF commit이 push된 뒤에는 `dev`와 `origin/dev`가 같은 commit을
|
|
가리켜야 한다.
|
|
|
|
```powershell
|
|
git switch dev
|
|
git status --short --branch
|
|
git rev-parse HEAD
|
|
git rev-parse origin/dev
|
|
git rev-list --left-right --count origin/dev...dev
|
|
```
|
|
|
|
reset, rebase 또는 force push로 차이를 숨기지 않는다. 예상하지 못한 변경이 있으면
|
|
소유자를 확인하고 보존한다.
|
|
|
|
## 3. 완료된 Phase 1 기준선
|
|
|
|
현재 production 경로는 다음 기능을 제공한다.
|
|
|
|
- Abaqus `.inp` 제한 부분집합의 flat/orphan mesh 또는 좌표변환이 없는 단일
|
|
Part/Assembly/Instance 모델 파싱과 semantic validation
|
|
- 2절점 3D Isoparametric Timoshenko Beam, 등방성 선형 탄성, 일반 단면,
|
|
`*BOUNDARY`, `*CLOAD`, 단일 선형 정적 Step
|
|
- MSVC v145, Intel oneAPI MKL PARDISO와 TBB를 사용하는 Windows x64 해석 경로
|
|
- canonical contribution ordering에 기반한 결정론적 병렬 요소 평가와 조립
|
|
- 원래 full equation에서 변위, 반력과 평형을 복구하는 선형 정적 해석
|
|
- 두 요소 끝의 section strain, section force, centroid/recovery-point `Sxx` 회복
|
|
- node/element provenance, component와 좌표계 metadata를 포함한 완전한
|
|
`ResultDatabase`
|
|
- 입력 원본 없이 model, analysis와 결과를 재구성할 수 있는 HDF5 schema `2.0.0`
|
|
- 변위, 반력, 요소 단면력용 Abaqus CSV adapter와 component별 상관성 보고 CLI
|
|
|
|
결과 계약과 Beam reference phase의 세부 완료 기록은 다음 파일에 있다.
|
|
|
|
- `phases/result-contract-completion/index.json`
|
|
- `phases/beam-reference-qualification/index.json`
|
|
- `docs/HDF5_SCHEMA.md`
|
|
- `docs/VALIDATION.md`
|
|
|
|
`internal-release`에서는 위 solver 계약을 다시 설계하지 않는다. 설치, clean consumer,
|
|
scale measurement와 release evidence에 필요한 최소 변경만 수행한다.
|
|
|
|
## 4. 검증 상태와 남은 제한
|
|
|
|
### 4.1 이중 검증 gate
|
|
|
|
`docs/VALIDATION.md`가 검증 결과의 단일 상세 보고서다.
|
|
|
|
- Gate A — FESA 정식화 적합성: **PASS**
|
|
- Gate B — Abaqus 결과 상관성: **EVALUABLE**
|
|
|
|
Gate A는 해석해, strain energy, 강체 mode, 회전 불변성, 평형과 결정성을 엄격한
|
|
tolerance로 검증한다. Gate B는 Abaqus B31과 FESA 정식화의 차이를 인정하고
|
|
component별 RMSE와 Relative L2를 보고한다. Gate B의 `EVALUABLE`은 모든 요청
|
|
entity/component가 유일하게 매칭되고 metric이 유한하다는 뜻이며, 임의의 상관성
|
|
pass/fail threshold를 통과했다는 뜻은 아니다.
|
|
|
|
현재 cantilever reference의 주요 Relative L2는 다음과 같다.
|
|
|
|
| 결과 | Component | Relative L2 |
|
|
|---|---|---:|
|
|
| displacement | `Uz` | `0.0022349969291714038` |
|
|
| displacement | `Ry` | `0.0000010416581667076092` |
|
|
| reaction | `RFz` | `4.4393520322089023e-13` |
|
|
| reaction | `RMy` | `2.591919334788851e-13` |
|
|
| internal force | `Vz` | `2.7107472798172426e-13` |
|
|
| internal force | `My` | `0.082541022764834646` |
|
|
|
|
18개 전체 component의 count, RMSE와 Relative L2는 `docs/VALIDATION.md`를 사용한다.
|
|
|
|
### 4.2 Reference 모델과 축 매핑
|
|
|
|
- Abaqus provenance는 `reference/cantilever beam/cantilever beam.inp`와 세 CSV다.
|
|
- Abaqus 원본 모델의 `SCF=0.25`는 보존한다.
|
|
- FESA projection은 `reference/cantilever beam/cantilever beam fesa.inp`이며 다른
|
|
의미 입력을 유지하고 `SCF=0`을 사용한다.
|
|
- FESA에 Abaqus SCF 보정이나 결과 맞춤 계수를 추가하지 않는다.
|
|
|
|
요소력 CSV는 다음 순서로 매핑한다.
|
|
|
|
| FESA | Abaqus CSV |
|
|
|---|---|
|
|
| `N` | `SF1` |
|
|
| `Vy` | `SF3` |
|
|
| `Vz` | `SF2` |
|
|
| `T` | `SM3` |
|
|
| `My` | `SM1` |
|
|
| `Mz` | `SM2` |
|
|
|
|
### 4.3 아직 완료되지 않은 검증
|
|
|
|
- 실제 Abaqus 결과로 검증된 물리량은 변위, 반력과 요소 단면력이다.
|
|
- Abaqus 도심 응력 CSV는 제공되지 않았다. `StressCsv`는 synthetic fixture로 schema와
|
|
entity mapping만 검증했으며 응력은 **not yet Abaqus-qualified**다.
|
|
- synthetic internal-force fixture도 adapter 단위 검증에 계속 사용하지만, 요소
|
|
단면력 자체는 별도의 실제 Abaqus golden CSV와 상관성 비교가 완료됐다.
|
|
- 내부 배포용 Release build, install tree, clean consumer smoke test와 약 100,000 DOF
|
|
측정은 아직 실행되지 않았다. 증거 없이 완료 표시하지 않는다.
|
|
|
|
### 4.4 `internal-release` Step 문서의 계약 불일치
|
|
|
|
`phases/internal-release/step0.md`와 `step4.md`에는 beam reference phase 이전의 문구가
|
|
남아 있다.
|
|
|
|
- “현재 Abaqus displacement/reaction comparison”은 변위·반력·요소 단면력
|
|
correlation으로 갱신해야 한다.
|
|
- “내력·응력은 synthetic coverage”라는 묶음 표현은 요소 단면력과 응력을 분리해야
|
|
한다. 요소 단면력은 real golden correlation과 synthetic adapter coverage가 모두
|
|
있고, 응력만 synthetic adapter coverage다.
|
|
|
|
새 세션은 Harness 실행 전에 이 두 Step 문서와 관련 checklist 문구를 현재
|
|
`docs/PRD.md` 8절 및 `docs/VALIDATION.md`와 일치시켜야 한다. 이 정렬은 검증 범위의
|
|
확장이 아니라 이미 완료된 증거를 정확히 기술하는 작업이다.
|
|
|
|
## 5. 다음 Phase: `internal-release`
|
|
|
|
Phase metadata는 `phases/internal-release/index.json`에 있다. Step은 순서대로 실행한다.
|
|
|
|
### Step 0 — `release-checklist`
|
|
|
|
- `docs/BUILDING.md`, `docs/INPUT_FORMAT.md`, `docs/RELEASE_CHECKLIST.md`를 작성한다.
|
|
- PRD 8절의 각 내부 배포 기준에 고유 checklist ID를 부여한다.
|
|
- 실제 target, preset, example과 evidence command를 CMake에서 재확인한다.
|
|
- 미실행 Release/install/benchmark 항목을 완료 표시하지 않는다.
|
|
- 4.4절의 stale reference 문구를 먼저 바로잡는다.
|
|
|
|
### Step 1 — `cmake-install-package`
|
|
|
|
- `cmake --install`로 내부 배포용 install tree를 만든다.
|
|
- CLI, `fesa_core`, public headers, CMake package config, example, schema/input/validation
|
|
문서와 runtime DLL inventory를 포함한다.
|
|
- install config에 absolute build path가 남는 실패 검사를 먼저 작성한다.
|
|
- installer, registry write, 외부 dependency 다운로드와 public ABI 약속은 범위 밖이다.
|
|
|
|
### Step 2 — `install-tree-smoke-test`
|
|
|
|
- source/build tree를 참조하지 않는 consumer configure/link test를 만든다.
|
|
- 설치된 CLI의 `--version`, example solve와 생성 HDF5 open을 검증한다.
|
|
- 개발 PATH의 `fesa.exe`나 source include fallback으로 결함을 숨기지 않는다.
|
|
|
|
### Step 3 — `phase1-scale-benchmark`
|
|
|
|
- 약 100,000 DOF Beam chain에서 generation/parsing, assembly, PARDISO solve,
|
|
recovery와 HDF5 write 시간을 분리해 측정한다.
|
|
- 재현 가능한 Windows memory metric, thread/solver 설정과 실제 DOF 수를 기록한다.
|
|
- finite result, 평형과 정상 종료는 검사하되 임의 시간·speedup 기준은 만들지 않는다.
|
|
|
|
### Step 4 — `release-evidence-gate`
|
|
|
|
- Debug와 Release configure/build/test를 새로 실행한다.
|
|
- test count가 0이 아닌지 확인한다.
|
|
- Harness pytest, reference, determinism, HDF5 inspection, install-tree smoke test와 scale
|
|
benchmark 증거를 checklist ID에 연결한다.
|
|
- 모든 수용 조건에 현재 실행 증거가 있을 때만 Step과 Phase를 `completed`로 바꾼다.
|
|
- 실패나 미실행 항목이 있으면 정확한 blocker를 남기고 release 완료를 선언하지 않는다.
|
|
|
|
## 6. 유지해야 할 경계
|
|
|
|
- C++20, Visual Studio 2026 MSVC v145와 Windows x64 기준을 유지한다.
|
|
- `core`, `model`, `fem`, `elements`에 Abaqus, MKL, TBB 또는 HDF5 API를 노출하지
|
|
않는다.
|
|
- solver semantic model과 result contract에 installer 또는 serialization 전용 타입을
|
|
추가하지 않는다.
|
|
- dependency는 개발 환경에 사전 설치된 버전을 사용하며 package 중 다운로드하지
|
|
않는다.
|
|
- install tree는 source/build tree의 절대경로에 의존하지 않아야 한다.
|
|
- Debug와 Release artifact/runtime을 혼합하지 않는다.
|
|
- FESA는 단위 변환을 수행하지 않는다.
|
|
- performance 수치를 correctness gate로 바꾸지 않는다.
|
|
- stress를 Abaqus-qualified로 표현하지 않는다.
|
|
- 테스트를 disable하거나 제외해 release evidence를 만들지 않는다.
|
|
- 사용자가 명시적으로 요청하지 않은 phase 실행에서는 `--push`를 사용하지 않는다.
|
|
|
|
## 7. 검증 기준선과 개발환경
|
|
|
|
### 7.1 마지막 확인 결과
|
|
|
|
2026-08-03의 beam reference qualification 완료 및 `dev` 병합 후 다음을 확인했다.
|
|
|
|
- `cmake --build --preset windows-debug`: 성공, 새 MSVC warning 없음
|
|
- `ctest --preset windows-debug --output-on-failure`: 68/68 통과
|
|
- `uv run --with pytest python -m pytest -v -rs`: 20/20 통과
|
|
- thread `{1,2,16}`에서 10회 반복한 조립/해석 결과: bitwise 동일
|
|
|
|
이 수치는 새 세션이 유지해야 할 Debug baseline이다. Release와 install-tree 결과로
|
|
확대 해석하지 않는다.
|
|
|
|
### 7.2 Package 설정
|
|
|
|
새 PowerShell 세션에서 configure 전에 현재 설치 위치를 확인한다. tracked preset이나
|
|
CMake 파일에 사용자별 절대경로를 넣지 않는다.
|
|
|
|
```powershell
|
|
$env:MKL_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\mkl"
|
|
$env:TBB_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\tbb"
|
|
$env:HDF5_DIR = "C:\Program Files\HDF_Group\HDF5\2.1.1\cmake"
|
|
$env:GTest_DIR = "C:\Users\baram\AppData\Local\FESA\dependencies\googletest-1.17.0-v145-x64-crt\lib\cmake\GTest"
|
|
|
|
Test-Path "$env:MKL_DIR\MKLConfig.cmake"
|
|
Test-Path "$env:TBB_DIR\TBBConfig.cmake"
|
|
Test-Path "$env:HDF5_DIR\hdf5-config.cmake"
|
|
Test-Path "$env:GTest_DIR\GTestConfig.cmake"
|
|
```
|
|
|
|
네 경로가 모두 유효한 같은 셸에서 preset을 실행한다. cache가 없거나 package 위치가
|
|
변경됐을 때만 `--fresh` configure를 사용한다.
|
|
|
|
```powershell
|
|
cmake --fresh --preset windows-debug
|
|
cmake --build --preset windows-debug
|
|
ctest --preset windows-debug --output-on-failure
|
|
uv run --with pytest python -m pytest -v -rs
|
|
```
|
|
|
|
Release evidence는 `internal-release` Step에서 새로 생성한다.
|
|
|
|
```powershell
|
|
cmake --preset windows-release
|
|
cmake --build --preset windows-release
|
|
ctest --preset windows-release --output-on-failure
|
|
```
|
|
|
|
## 8. Harness 주의사항
|
|
|
|
표준 실행 명령은 다음과 같다.
|
|
|
|
```powershell
|
|
python scripts/execute.py internal-release
|
|
```
|
|
|
|
이전 beam reference phase에서 Harness child가 WindowsApps PowerShell을 시작하지 못해
|
|
`CreateProcessAsUserW` 오류가 반복됐다. 동일 저장소와 preset에서 직접 실행한 수용
|
|
명령은 성공했고, `stepN-output.json`에는 child 환경 blocker와 직접 실행 증거를
|
|
구분해 기록했다.
|
|
|
|
새 세션에서는 다음 원칙을 지킨다.
|
|
|
|
1. 먼저 표준 Harness 실행을 시도한다.
|
|
2. 같은 child shell 오류가 발생하면 중복 executor를 시작하지 말고 남은 process를
|
|
확인한다.
|
|
3. 직접 실행한 명령과 Harness 실행 결과를 혼동하지 않고 metadata에 사실대로 적는다.
|
|
4. 사용자 profile이나 drive root를 `--codex-add-dir`로 허용하지 않는다.
|
|
5. global Codex 설정을 임시 변경했다면 원래 값을 기록하고 종료 즉시 복원·재확인한다.
|
|
6. 사용자가 push를 명시하지 않은 phase 실행에는 `--push`를 추가하지 않는다.
|
|
|
|
## 9. 새 세션 시작 순서
|
|
|
|
1. `AGENTS.md`와 이 문서를 읽는다.
|
|
2. `docs/PRD.md` 8절, `docs/VALIDATION.md`, `phases/internal-release/index.json`과
|
|
Step 0~4를 읽는다.
|
|
3. Git 상태와 `dev == origin/dev`를 확인한다.
|
|
4. 4.4절의 Step 0/4 reference 범위 문구를 최신 계약에 맞춘다.
|
|
5. Debug baseline을 새로 실행한다.
|
|
6. Step 0의 release 문서와 checklist 요구조건을 먼저 테스트 가능한 형태로 고정한다.
|
|
7. 다음 명령으로 Phase를 실행한다.
|
|
|
|
```powershell
|
|
python scripts/execute.py internal-release
|
|
```
|
|
|
|
각 Step에서는 실패하는 검사 또는 미충족 evidence를 먼저 확인하고, 최소 변경으로
|
|
수용 조건을 만족시킨 뒤 focused test와 전체 test를 실행한다. Step output과 phase
|
|
metadata는 실제 명령 결과를 그대로 반영한다.
|
|
|
|
## 10. `internal-release` 완료 조건
|
|
|
|
- `phases/internal-release/index.json`의 Step 0~4가 모두 `completed`
|
|
- `phases/index.json`의 `internal-release`가 `completed`
|
|
- PRD 8절의 모든 기준이 고유 checklist ID와 실제 증거에 연결됨
|
|
- Debug/Release build에 새 MSVC warning이 없음
|
|
- Debug/Release CTest와 Harness pytest가 0개가 아닌 상태로 모두 통과
|
|
- `cmake --install` 결과에 요구 binary/library/header/document/example/runtime
|
|
inventory가 포함됨
|
|
- source/build tree를 숨긴 install consumer와 CLI/HDF5 smoke test 통과
|
|
- 약 100,000 DOF benchmark의 correctness, stage time, memory와 환경 기록 완료
|
|
- Gate A PASS와 Gate B EVALUABLE의 의미 및 Abaqus stress 제한을 release 문서가
|
|
정확히 유지함
|
|
- 실패하거나 미실행인 증거가 없는 경우에만 내부 배포 완료 선언
|
|
|
|
새 세션의 권장 첫 요청은 다음과 같다.
|
|
|
|
> `docs/HANDOFF.md`와 `internal-release`의 index/step0~4를 읽고 현재 `dev`
|
|
> baseline과 beam reference 검증 범위를 확인해주세요. Step 0과 Step 4의 stale
|
|
> reference 문구를 PRD/VALIDATION에 맞춘 뒤 `internal-release` Phase를 시작해주세요.
|