12 KiB

Raw Blame History

FESA Session Handoff

1. 문서 목적

이 문서는 domain-and-input-skeleton 완료 후 새 세션에서 fem-and-beam-kernel Phase를 바로 시작하기 위한 인수인계 기록이다. 요구사항과 설계의 기준은 이 문서가 아니라 다음 파일이다.

/AGENTS.md
/docs/PRD.md
/docs/ARCHITECTURE.md
/docs/ADR.md
/docs/HARNESS.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. 현재 저장소 상태

2026-07-31 확인 기준:

현재 브랜치: 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에서 실제 구현과 함께 만든다.

이 문서를 갱신하기 직전 작업 트리는 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와 CMake/CTest 실행 계약

`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 파일이나 Preset에 넣지 않는다.

$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"

2026-07-31 위 네 경로가 모두 존재함을 확인했다. 같은 환경에서 다음 baseline을 새로 검증했다.

MSVC v145 Debug build 성공, 새 경고 없음
CTest 12개 중 12개 성공
Harness pytest 20개 중 20개 성공
pytest가 실제로 20개를 수집했으므로 0-test 성공이 아님

검증 명령:

cmake --build --preset windows-debug
ctest --preset windows-debug --output-on-failure
uv run --with pytest python -m pytest -v -rs

CMake cache가 없거나 package 경로가 바뀐 경우에만 같은 환경 변수 세션에서 먼저 다음을 실행한다.

cmake --fresh --preset windows-debug

5. 다음 Phase 목표와 Step 순서

fem-and-beam-kernel의 독립 deliverable은 실제 2절점 3D Timoshenko Beam의 local/global stiffness와 해석적 sanity test다. 네 Step을 순서대로 실행한다.

Step 0 — `quadrature-and-shape-functions`

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를 만들지 않는다.

Step 1 — `dof-manager`

절점당 자유도 순서는 (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 범위가 아니다.

Step 2 — `beam-local-frame`

두 절점과 mandatory orientation vector로 오른손 직교 BeamFrame {ex, ey, ez}를 만든다.
Gram-Schmidt, 정규화, 직교성, determinant (+1), 회전/에너지 invariant를 테스트한다.
zero length, zero orientation, 요소축과 평행한 orientation은 diagnostic으로 실패시킨다.
Matrix12는 현재 코드에 없으므로 이 Step의 transformation 계약에 필요한 최소 고정 크기 타입만 만든다. 범용 동적 matrix 계층이나 registry를 만들지 않는다.

Step 3 — `timoshenko-stiffness-kernel`

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 파일을 읽고 현재 상태를 재검증한다.

git switch dev
git status --short --branch
git rev-parse HEAD
git rev-parse origin/dev

작업 트리가 clean이고 dev가 의도한 기준인지 확인한 뒤 4절의 package 환경 변수를 설정하고 baseline을 실행한다. 그 다음:

python scripts/execute.py fem-and-beam-kernel

executor는 feat-fem-and-beam-kernel 브랜치를 생성하거나 checkout하고 Step 상태와 output metadata를 기록한다. 사용자가 명시적으로 요청하지 않은 한 --push를 사용하지 않는다.

각 Step은 다음 순서를 지킨다.

Step 파일의 필수 문서와 선행 구현을 모두 읽는다.
성공 기준과 수학 invariant를 명시한다.
실패 테스트를 먼저 작성하고 예상한 이유로 실패함을 확인한다.
테스트를 통과시키는 최소 production code만 구현한다.
focused test, 전체 CTest, Harness pytest를 실행한다.
Step summary와 output metadata가 실제 결과와 일치하는지 확인한다.
Phase 종료 전 전체 diff를 아키텍처·정식화·테스트 기준으로 review한다.

9. 알려진 Harness 실행 이력과 복구 주의사항

이전 Phase에서 production 코드와 무관한 두 executor 문제가 있었다.

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와 수용 조건을 직접 수행해 완료했다.

새 세션에서는 이 상태가 여전히 유효하다고 단정하지 말고 Harness를 한 번 정상 실행해 확인한다. 같은 외부 문제가 반복되면:

저장소 변경 전후 상태와 정확한 실패 stage를 보존한다.
제품 코드 문제인지 child sandbox/quota 문제인지 root의 동일 명령으로 분리한다.
수동 fallback 시에도 Step의 TDD, focused/full test, review를 생략하지 않는다.
실패 output을 성공으로 위장하지 말고 이후 성공 증거와 복구 commit을 분리해 metadata와 Git 이력에 남긴다.
광범위한 사용자 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 경고 없음
강체운동, 해석해, 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를 시작해주세요.

12 KiB Raw Blame History