From 4ee3895915accf69c3f988bf14119fab7c318ed5 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Fri, 31 Jul 2026 01:08:05 +0900 Subject: [PATCH] modify handoff.md --- docs/HANDOFF.md | 300 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 200 insertions(+), 100 deletions(-) diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 11cb766..20c28f2 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -2,8 +2,8 @@ ## 1. 문서 목적 -이 문서는 `solver-bootstrap` 완료 후 다음 세션에서 -`domain-and-input-skeleton` Phase를 바로 시작하기 위한 인수인계 기록이다. +이 문서는 `domain-and-input-skeleton` 완료 후 새 세션에서 +`fem-and-beam-kernel` Phase를 바로 시작하기 위한 인수인계 기록이다. 요구사항과 설계의 기준은 이 문서가 아니라 다음 파일이다. - `/AGENTS.md` @@ -11,35 +11,72 @@ - `/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/fem-and-beam-kernel/index.json` +- `/phases/fem-and-beam-kernel/step0.md`부터 `step3.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는 없다. +2026-07-31 확인 기준: -`solver-bootstrap`에서 다음 기반이 구현되었다. +- 현재 브랜치: `dev` +- `dev`, `origin/dev`, `origin/HEAD` 기준 커밋: + `e7f0d53406bfdff0fbd610c2b595a8d214341353` +- 완료 Phase: + - `solver-bootstrap` + - `domain-and-input-skeleton` +- 다음 Phase: `fem-and-beam-kernel` +- 다음 Step: `0 - quadrature-and-shape-functions` +- `fem-and-beam-kernel`의 Step 0~3은 모두 `pending` +- 활성 제품 코드 blocker는 없다. +- `include/fesa/fem/`, `include/fesa/elements/beam/`, + `docs/formulation/timoshenko-beam-3d.md`는 아직 존재하지 않는다. 해당 Step에서 + 실제 구현과 함께 만든다. -- Visual Studio 2026, MSVC v145, Windows x64용 CMake Preset -- C++20 `fesa_core`와 `fesa` CLI 골격 +이 문서를 갱신하기 직전 작업 트리는 clean이었다. 문서 수정 자체가 아직 커밋되지 않은 +경우 Harness 실행 전에 `docs/HANDOFF.md` 변경을 먼저 커밋하거나 별도로 정리해야 한다. + +## 3. 완료된 기반 + +### `solver-bootstrap` + +- Visual Studio 2026 MSVC v145, Windows x64, C++20 CMake Preset +- `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 +- Harness Python characterization test와 CMake/CTest 실행 계약 -## 3. 검증된 개발환경 +### `domain-and-input-skeleton` + +- solver semantic 값 타입: + - `Node`, `BeamElement`, `IsotropicElastic`, `BeamSection` + - `NodeSet`, `ElementSet`, `StepDefinition` + - `EntityOrigin`과 typed internal ID +- build 이후 const view만 제공하는 `Domain` +- `DomainBuilder`의 중복 ID/origin, 참조, 유한값, 물성, 길이, orientation, + 경계조건 검증 +- flat/orphan mesh와 Part/Assembly/단일 무변환 Instance scope를 보존하는 Abaqus + syntax parser +- 활성 Part만 선택해 flat `Domain`으로 정규화하는 semantic mapper +- 실제 Part/Instance/local label provenance 보존 +- 생략된 전단강성에 + \(A_{sy}=A_{sz}=5A/6\)과 + `ShearPropertySource::phase1_default` 적용 +- 여러 Instance, Instance transform, missing Part 등 최소 조직 오류의 source + diagnostic +- public parser/mapper 경로를 사용하는 flat/계층형 통합 테스트 + +현재 parser/mapper는 다음 Phase의 Beam kernel 테스트에 필요한 최소 semantic +`Domain`을 제공한다. 전체 Abaqus 부분집합, nested/`GENERATE` set, 완전한 scope +resolution, explicit transverse shear, no-op directive와 단일 step의 모든 option은 +후속 `abaqus-subset-completion` Phase 책임이다. 이번 Phase에서 선행 구현하지 않는다. + +## 4. 검증된 개발환경과 baseline 새 PowerShell 세션에서 configure 또는 Harness 실행 전에 다음 환경 변수를 설정한다. -절대경로를 tracked CMake 파일에 넣지 않는다. +절대경로를 tracked CMake 파일이나 Preset에 넣지 않는다. ```powershell $env:MKL_DIR = "C:\Program Files (x86)\Intel\oneAPI\2026.1\lib\cmake\mkl" @@ -53,125 +90,188 @@ 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-31 위 네 경로가 모두 존재함을 확인했다. 같은 환경에서 다음 baseline을 +새로 검증했다. -2026-07-30 `dev` baseline에서 다음 검증을 통과했다. - -- Debug configure와 build 성공 -- CTest 4개 중 4개 성공 +- MSVC v145 Debug build 성공, 새 경고 없음 +- CTest 12개 중 12개 성공 - Harness pytest 20개 중 20개 성공 -- dependency smoke test에서 MKL 2026.1, TBB, HDF5와 GoogleTest runtime 확인 +- pytest가 실제로 20개를 수집했으므로 0-test 성공이 아님 검증 명령: ```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`부터 다시 실행한다. +CMake cache가 없거나 package 경로가 바뀐 경우에만 같은 환경 변수 세션에서 먼저 +다음을 실행한다. -## 4. 확정된 Phase 1 범위 +```powershell +cmake --fresh --preset windows-debug +``` -- 소변형 선형 정적해석과 단일 `*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 +## 5. 다음 Phase 목표와 Step 순서 -이번 Phase에서 여러 Instance, Instance 좌표변환, 다른 요소, 해석 equation 구성, -Beam stiffness kernel, MKL solve와 HDF5 writer를 구현하지 않는다. +`fem-and-beam-kernel`의 독립 deliverable은 실제 2절점 3D Timoshenko Beam의 +local/global stiffness와 해석적 sanity test다. 네 Step을 순서대로 실행한다. -## 5. 입력 및 semantic model 결정사항 +### Step 0 — `quadrature-and-shape-functions` -- `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`는 지원하지 않고 거부한다. +- `fem`에 1점/2점 1D Gauss rule, 2절점 선형 shape function과 derivative, + `length/2` Jacobian을 구현한다. +- partition of unity, endpoint interpolation, derivative sum zero, 적분 정확도, + invalid order/length를 실패 테스트로 먼저 고정한다. +- runtime registry나 Beam stiffness를 만들지 않는다. -## 6. 다음 Phase 실행 순서 +### Step 1 — `dof-manager` -Phase 정의는 `/phases/domain-and-input-skeleton/`에 있다. +- 절점당 자유도 순서는 + \(u_x,u_y,u_z,r_x,r_y,r_z\)의 6개다. +- `DofManager`가 full DOF, constrained/free equation numbering, + 12개 요소 DOF mapping과 prescribed value를 포함한 full-vector reconstruction을 + 전담한다. +- external label이나 입력 선언 순서에 흔들리지 않는 deterministic numbering을 + 테스트로 고정한다. +- equation ID를 `Node`나 `BeamElement`에 저장하지 않는다. +- sparse pattern, MPC, penalty DOF는 이 Step 범위가 아니다. -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 2 — `beam-local-frame` -각 Step은 TDD 순서를 지킨다. +- 두 절점과 mandatory orientation vector로 오른손 직교 + `BeamFrame {ex, ey, ez}`를 만든다. +- Gram-Schmidt, 정규화, 직교성, determinant \(+1\), 회전/에너지 invariant를 + 테스트한다. +- zero length, zero orientation, 요소축과 평행한 orientation은 diagnostic으로 + 실패시킨다. +- `Matrix12`는 현재 코드에 없으므로 이 Step의 transformation 계약에 필요한 최소 + 고정 크기 타입만 만든다. 범용 동적 matrix 계층이나 registry를 만들지 않는다. -1. Step 파일과 선행 파일을 모두 읽는다. -2. 요청된 동작을 보여주는 실패 테스트를 먼저 작성하고 실패를 확인한다. -3. 테스트를 통과시키는 최소 구현만 추가한다. -4. focused test와 전체 CTest를 실행한다. -5. Harness가 Step 상태와 summary를 기록하게 한다. +### Step 3 — `timoshenko-stiffness-kernel` -Harness 실행 전에는 작업 트리가 clean이어야 한다. 이 `HANDOFF.md`를 포함한 필요한 -변경을 먼저 커밋하고 `dev`가 clean인지 확인한다. +- production code보다 먼저 + `/docs/formulation/timoshenko-beam-3d.md`를 작성한다. +- 문서에는 최소한 다음을 고정한다. + - 12개 local/global DOF와 component 순서 + - 오른손 국부 좌표계 정의 + - 변형률과 부호 규약 + - \(G=E/[2(1+\nu)]\)와 constitutive matrix + - 자연좌표, shape derivative와 \(J=L/2\) + - 축·굽힘·비틀림 2점, 전단 1점 선택적 감차적분 + - local/global transformation 규칙 +- 실제 `Beam3D2Input`, `Beam3D2Contribution`, `compute_beam3d2` kernel을 구현한다. +- 대칭성, 강체운동 zero energy, 축/비틀림/단축·이축 굽힘 해석해, + shear-dominant 문제, 세장비 sweep과 회전 invariant를 실패 테스트로 먼저 만든다. +- 임시 가짜/닫힌형 stiffness로 파이프라인만 통과시키지 않는다. + +## 6. 수치·정식화 계약 + +- 요소: 2절점 직선 3D Isoparametric Timoshenko Beam +- 절점당 6 DOF: + \(u_x,u_y,u_z,\theta_x,\theta_y,\theta_z\) +- 선형 shape function, \(\xi\in[-1,1]\) +- 축·굽힘·비틀림: 2점 Gauss 적분 +- 전단: 1점 Gauss 적분 +- 재료: 등방성 선형 탄성, + \(G=E/[2(1+\nu)]\) +- 단면: + \(A,I_y,I_z,J,A_{sy},A_{sz}\) +- 제한: + \(I_{yz}=0\), 도심/전단중심 일치, offset/warping 없음 +- orientation은 필수이며 자동 추측하거나 임의 축으로 대체하지 않는다. +- tolerance는 테스트 이름이나 주석에 수학적/scale-aware 근거를 기록한다. +- FESA는 단위 변환을 하지 않는다. + +정식화는 `docs/PRD.md` 3.2절, `docs/ARCHITECTURE.md` 8절, +`docs/ADR.md` ADR-005와 ADR-014를 우선한다. + +## 7. 아키텍처 경계와 이번 Phase 제외 범위 + +- public header는 `include/fesa/`, 구현은 `src/fesa/`, 테스트는 `tests/`에 둔다. +- `core`, `model`, `fem`, `elements`는 Abaqus, MKL, TBB, HDF5 API에 의존하지 + 않는다. +- `fem`은 DOF, equation mapping, quadrature, shape function, Jacobian, + local/global mapping만 담당한다. +- `elements/beam`은 Beam local contribution과 kernel 계약을 담당한다. +- `Domain`은 읽기 전용 view로 사용하고 복제하거나 mutable accessor를 추가하지 않는다. +- 이번 Phase에서는 다음을 구현하지 않는다. + - sparse COO/CSR pattern과 조립 + - essential BC elimination system + - MKL PARDISO solve + - oneTBB parallel assembly + - HDF5 writer와 result recovery + - 여러 요소 타입을 위한 registry/factory + - 비선형, warping, offset, \(I_{yz}\ne0\), 여러 Instance + +## 8. 새 세션 시작 절차 + +먼저 이 문서와 Step 파일을 읽고 현재 상태를 재검증한다. ```powershell git switch dev git status --short --branch -git fetch origin -git rev-parse dev +git rev-parse HEAD git rev-parse origin/dev -python scripts/execute.py domain-and-input-skeleton ``` -executor는 `feat-domain-and-input-skeleton` 브랜치를 생성하거나 checkout한다. -원격 push는 사용자가 명시적으로 요청한 경우에만 `--push`를 사용한다. +작업 트리가 clean이고 `dev`가 의도한 기준인지 확인한 뒤 4절의 package 환경 변수를 +설정하고 baseline을 실행한다. 그 다음: -## 7. 구현 시 지켜야 할 경계 +```powershell +python scripts/execute.py fem-and-beam-kernel +``` -- 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를 만들지 않는다. +executor는 `feat-fem-and-beam-kernel` 브랜치를 생성하거나 checkout하고 Step 상태와 +output metadata를 기록한다. 사용자가 명시적으로 요청하지 않은 한 `--push`를 +사용하지 않는다. -## 8. Reference 검증 상태 +각 Step은 다음 순서를 지킨다. -현재 샘플은 `/reference/cantilever beam/`에 있다. +1. Step 파일의 필수 문서와 선행 구현을 모두 읽는다. +2. 성공 기준과 수학 invariant를 명시한다. +3. 실패 테스트를 먼저 작성하고 예상한 이유로 실패함을 확인한다. +4. 테스트를 통과시키는 최소 production code만 구현한다. +5. focused test, 전체 CTest, Harness pytest를 실행한다. +6. Step summary와 output metadata가 실제 결과와 일치하는지 확인한다. +7. Phase 종료 전 전체 diff를 아키텍처·정식화·테스트 기준으로 review한다. -- Abaqus input -- displacement CSV -- reaction CSV +## 9. 알려진 Harness 실행 이력과 복구 주의사항 -per-model metadata는 사용하지 않는다. 현재 샘플 검증은 변위와 반력만 요청한다. -요소 내력과 요소 절점 단면 도심 `Sxx` CSV는 추후 추가한다. 다만 해당 CSV reader와 -비교 kernel은 이후 계획된 Phase에서 synthetic CSV로 함께 구현하고 검증해야 한다. +이전 Phase에서 production 코드와 무관한 두 executor 문제가 있었다. -## 9. 다음 Phase 완료 조건 +- Step 2 child sandbox에서 MSBuild가 사용자 profile의 Microsoft SDK/FileTracker + 경로를 읽거나 child compiler process를 실행하지 못했다. 같은 checkout의 root + PowerShell에서는 정확한 build와 focused/full CTest가 통과했다. +- Step 3 child Codex 실행은 2026-07-30 usage limit에 도달해 + `2026-08-05 15:07` 이후 재시도하라는 응답을 냈다. 당시 Step은 root 세션에서 + TDD와 수용 조건을 직접 수행해 완료했다. -- `phases/domain-and-input-skeleton/index.json`의 Step 0~3이 모두 `completed` -- `phases/index.json`에서 `domain-and-input-skeleton`이 `completed` +새 세션에서는 이 상태가 여전히 유효하다고 단정하지 말고 Harness를 한 번 정상 +실행해 확인한다. 같은 외부 문제가 반복되면: + +1. 저장소 변경 전후 상태와 정확한 실패 stage를 보존한다. +2. 제품 코드 문제인지 child sandbox/quota 문제인지 root의 동일 명령으로 분리한다. +3. 수동 fallback 시에도 Step의 TDD, focused/full test, review를 생략하지 않는다. +4. 실패 output을 성공으로 위장하지 말고 이후 성공 증거와 복구 commit을 분리해 + metadata와 Git 이력에 남긴다. +5. 광범위한 사용자 profile 경로를 `--codex-add-dir`로 허용하지 않는다. + +## 10. 다음 Phase 완료 조건 + +- `phases/fem-and-beam-kernel/index.json`의 Step 0~3이 모두 `completed` +- `phases/index.json`에서 `fem-and-beam-kernel`이 `completed` +- formulation 문서와 production kernel의 DOF, 좌표계, 부호, 적분 규칙 일치 - focused test와 전체 CTest 통과 - Harness pytest가 0개가 아닌 상태로 전체 통과 - 새 MSVC 경고 없음 -- flat fixture와 단일 무변환 Instance fixture가 동등한 활성 `Domain` 생성 -- 복합 origin 보존, 미참조 Part 제외와 미지원 scope/transform diagnostic 검증 -- 변경사항 review 후 `feat-domain-and-input-skeleton`을 `dev`에 병합 +- 강체운동, 해석해, shear-dominant, 세장비와 회전 invariant 검증 통과 +- `fem`/`elements`에 Abaqus 또는 외부 library API 유입 없음 +- 코드 review의 Critical/Important 항목 해결 +- 사용자 선택 전 원격 push나 `dev` 병합을 수행하지 않음 + +새 세션의 권장 첫 요청: + +> `docs/HANDOFF.md`와 `phases/fem-and-beam-kernel/step0.md`부터 `step3.md`를 읽고 +> 현재 baseline을 확인한 뒤 `fem-and-beam-kernel` Phase를 시작해주세요.