From b851575554e5743ca20e10406486f9ecb1b188a8 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Thu, 30 Jul 2026 16:00:44 +0900 Subject: [PATCH] add handoff.md --- docs/HANDOFF.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 docs/HANDOFF.md diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md new file mode 100644 index 0000000..11cb766 --- /dev/null +++ b/docs/HANDOFF.md @@ -0,0 +1,177 @@ +# FESA Session Handoff + +## 1. 문서 목적 + +이 문서는 `solver-bootstrap` 완료 후 다음 세션에서 +`domain-and-input-skeleton` Phase를 바로 시작하기 위한 인수인계 기록이다. +요구사항과 설계의 기준은 이 문서가 아니라 다음 파일이다. + +- `/AGENTS.md` +- `/docs/PRD.md` +- `/docs/ARCHITECTURE.md` +- `/docs/ADR.md` +- `/docs/HARNESS.md` +- `/docs/superpowers/specs/2026-07-29-abaqus-assembly-reference-design.md` +- `/docs/superpowers/plans/2026-07-29-fesa-phase-1.md` + +내용이 충돌하면 위 기준 문서와 `phases/`의 현재 상태를 우선한다. + +## 2. 현재 저장소 상태 + +- 기준 브랜치: `dev` +- 원격 브랜치: `origin/dev` +- `solver-bootstrap`이 병합된 기준 커밋: + `8faaf4db9948f7a83f9341397d2a4177dce51fd7` +- 완료 Phase: `solver-bootstrap` +- 다음 Phase: `domain-and-input-skeleton` +- 다음 Step: `0 - semantic-domain-and-origin-types` +- `domain-and-input-skeleton`의 네 Step은 모두 `pending`이다. +- 활성 blocker는 없다. + +`solver-bootstrap`에서 다음 기반이 구현되었다. + +- Visual Studio 2026, MSVC v145, Windows x64용 CMake Preset +- C++20 `fesa_core`와 `fesa` CLI 골격 +- MKL, TBB, HDF5, GoogleTest package discovery와 dependency smoke test +- typed entity ID, `Vec3`, source location, diagnostic, status 값 타입 +- Harness Python characterization test와 workspace validation + +## 3. 검증된 개발환경 + +새 PowerShell 세션에서 configure 또는 Harness 실행 전에 다음 환경 변수를 설정한다. +절대경로를 tracked 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" +``` + +네 확인 결과가 모두 `True`여야 한다. GoogleTest 원본 clone은 +`C:\git\googletest`에 있지만 FESA configure에는 v145/x64/CRT 조건으로 설치한 위 +package directory를 사용한다. + +2026-07-30 `dev` baseline에서 다음 검증을 통과했다. + +- Debug configure와 build 성공 +- CTest 4개 중 4개 성공 +- Harness pytest 20개 중 20개 성공 +- dependency smoke test에서 MKL 2026.1, TBB, HDF5와 GoogleTest runtime 확인 + +검증 명령: + +```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 +``` + +환경 변수를 설정하지 않은 불완전한 CMake cache에서는 +`ALL_BUILD.vcxproj`가 없다는 빌드 오류가 발생할 수 있다. 이 경우 위 환경 변수를 +먼저 설정하고 `cmake --fresh --preset windows-debug`부터 다시 실행한다. + +## 4. 확정된 Phase 1 범위 + +- 소변형 선형 정적해석과 단일 `*STEP`, `*STATIC` +- 절점당 6자유도를 갖는 2절점 3D Isoparametric Timoshenko Beam +- 등방성 선형 탄성, 일반 Beam 단면, `*BOUNDARY`, `*CLOAD` +- Abaqus 2024 `.inp` 제한 부분집합 +- flat/orphan mesh 또는 좌표변환이 없는 단일 Assembly·단일 Instance +- C++20, MSVC v145, MKL PARDISO, oneTBB, HDF5 + +이번 Phase에서 여러 Instance, Instance 좌표변환, 다른 요소, 해석 equation 구성, +Beam stiffness kernel, MKL solve와 HDF5 writer를 구현하지 않는다. + +## 5. 입력 및 semantic model 결정사항 + +- `io/abaqus`는 syntax와 scope를 보존하고 해석 알고리즘을 알지 않는다. +- `model`은 Abaqus keyword record가 아니라 정규화된 solver semantic model을 + 소유한다. +- 계층형 입력에서는 모든 Part를 파싱하되 Assembly의 단일 Instance가 참조하는 + Part만 `Domain`에 포함한다. +- 외부 entity는 `(instance name, part-local label)` 복합 식별자를 사용하고 내부 + dense ID와 분리한다. +- flat mesh는 `part_name`과 `instance_name`을 빈 값으로 표현한다. +- 여러 Assembly/Instance, Instance transform, instance-local mesh 수정과 + flat/계층 mesh 혼합은 source location이 포함된 diagnostic으로 거부한다. +- `Domain`은 build 이후 불변으로 취급한다. +- equation ID를 `Node`나 `Element`에 저장하지 않는다. +- `*TRANSVERSE SHEAR STIFFNESS`가 생략되면 + \(A_{sy}=A_{sz}=5A/6\), `SCF=0`과 + `ShearPropertySource::phase1_default`를 적용한다. +- 명시된 nonzero `SCF`는 지원하지 않고 거부한다. + +## 6. 다음 Phase 실행 순서 + +Phase 정의는 `/phases/domain-and-input-skeleton/`에 있다. + +1. `step0.md` — semantic domain과 entity origin 값 타입 +2. `step1.md` — `DomainBuilder` validation과 불변 `Domain` +3. `step2.md` — Part/Assembly/Instance scope를 보존하는 Abaqus syntax parser +4. `step3.md` — flat 또는 단일 활성 Instance를 동일한 `Domain`으로 정규화 + +각 Step은 TDD 순서를 지킨다. + +1. Step 파일과 선행 파일을 모두 읽는다. +2. 요청된 동작을 보여주는 실패 테스트를 먼저 작성하고 실패를 확인한다. +3. 테스트를 통과시키는 최소 구현만 추가한다. +4. focused test와 전체 CTest를 실행한다. +5. Harness가 Step 상태와 summary를 기록하게 한다. + +Harness 실행 전에는 작업 트리가 clean이어야 한다. 이 `HANDOFF.md`를 포함한 필요한 +변경을 먼저 커밋하고 `dev`가 clean인지 확인한다. + +```powershell +git switch dev +git status --short --branch +git fetch origin +git rev-parse dev +git rev-parse origin/dev +python scripts/execute.py domain-and-input-skeleton +``` + +executor는 `feat-domain-and-input-skeleton` 브랜치를 생성하거나 checkout한다. +원격 push는 사용자가 명시적으로 요청한 경우에만 `--push`를 사용한다. + +## 7. 구현 시 지켜야 할 경계 + +- public header는 `include/fesa/`, 구현은 `src/fesa/`, 테스트는 `tests/`에 둔다. +- `core`와 `model` public API에 Abaqus, MKL, TBB 또는 HDF5 타입을 노출하지 않는다. +- parser record를 `Domain`에 저장하지 않는다. +- parser 단계에서 active Part를 선택하거나 `Domain`을 생성하지 않는다. +- semantic mapper가 Instance transform을 조용히 무시하지 않게 한다. +- 잘못된 model 값을 자동 보정하지 않고 가능한 diagnostic을 수집한다. +- public mutable `Domain` accessor를 추가하지 않는다. +- 여러 Instance container, 범용 factory/registry와 미래 기능용 빈 클래스를 만들지 + 않는다. +- production parser와 validation 경로를 우회하는 test helper를 만들지 않는다. + +## 8. Reference 검증 상태 + +현재 샘플은 `/reference/cantilever beam/`에 있다. + +- Abaqus input +- displacement CSV +- reaction CSV + +per-model metadata는 사용하지 않는다. 현재 샘플 검증은 변위와 반력만 요청한다. +요소 내력과 요소 절점 단면 도심 `Sxx` CSV는 추후 추가한다. 다만 해당 CSV reader와 +비교 kernel은 이후 계획된 Phase에서 synthetic CSV로 함께 구현하고 검증해야 한다. + +## 9. 다음 Phase 완료 조건 + +- `phases/domain-and-input-skeleton/index.json`의 Step 0~3이 모두 `completed` +- `phases/index.json`에서 `domain-and-input-skeleton`이 `completed` +- focused test와 전체 CTest 통과 +- Harness pytest가 0개가 아닌 상태로 전체 통과 +- 새 MSVC 경고 없음 +- flat fixture와 단일 무변환 Instance fixture가 동등한 활성 `Domain` 생성 +- 복합 origin 보존, 미참조 Part 제외와 미지원 scope/transform diagnostic 검증 +- 변경사항 review 후 `feat-domain-and-input-skeleton`을 `dev`에 병합