From 6ac474f19b9d5ad7b588cbce807df11f45c7bcb1 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Sat, 1 Aug 2026 20:53:18 +0900 Subject: [PATCH] docs(handoff): prepare parallel assembly phase --- docs/HANDOFF.md | 705 ++++++++++++++++++++++++------------------------ 1 file changed, 348 insertions(+), 357 deletions(-) diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index f472e5a..d6c9078 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -2,467 +2,458 @@ ## 1. 문서 목적 -이 문서는 `equation-and-linear-solve` 완료 후 새 세션에서 -`results-and-pipeline` Phase를 바로 시작하기 위한 인수인계 기록이다. +이 문서는 results-and-pipeline과 abaqus-subset-completion 완료 후 새 세션에서 +deterministic-parallel-assembly Phase를 바로 시작하기 위한 인수인계 기록이다. 요구사항과 설계의 기준은 이 문서가 아니라 다음 파일이다. -- `/AGENTS.md` -- `/docs/PRD.md` -- `/docs/ARCHITECTURE.md` -- `/docs/ADR.md` -- `/docs/HARNESS.md` -- `/docs/HDF5_SCHEMA.md` — 다음 Phase Step 1에서 writer보다 먼저 생성할 문서 -- `/docs/superpowers/plans/2026-07-29-fesa-phase-1.md` -- `/phases/results-and-pipeline/index.json` -- `/phases/results-and-pipeline/step0.md`부터 `step3.md` +- /AGENTS.md +- /docs/PRD.md +- /docs/ARCHITECTURE.md +- /docs/ADR.md +- /docs/HARNESS.md +- /docs/ABAQUS_INPUT_SUBSET.md +- /docs/HDF5_SCHEMA.md +- /phases/deterministic-parallel-assembly/index.json +- /phases/deterministic-parallel-assembly/step0.md부터 step2.md -내용이 충돌하면 `AGENTS.md`, 제품·아키텍처 문서와 `phases/`의 현재 상태를 -우선한다. 이 문서는 현재 구현과 실행환경에서 특히 놓치기 쉬운 계약을 보충한다. +내용이 충돌하면 AGENTS.md, 제품·아키텍처 문서와 phases/의 현재 상태를 우선한다. +이 문서는 현재 구현, 검증 baseline과 실행환경에서 특히 놓치기 쉬운 계약을 +보충한다. ## 2. 현재 저장소 상태 -2026-07-31 확인 기준: +2026-08-01 확인 기준: -- 현재 브랜치: `dev` -- 현재 `dev` HEAD: - `a02024929ca62c714335dd9811eea6eab816af38` -- `origin/dev`, `origin/HEAD`: - `d39340217421006c33bb7c61a0111d320cbaab2e` -- 로컬 `dev`는 `origin/dev`보다 9 commit 앞서고 0 commit 뒤처져 있다. +- 기준 브랜치: dev +- 이 HANDOFF 작성 직전 구현 HEAD: cbb621bb282a301b6708d95ff697b40644188e46 +- cbb621b는 abaqus-subset-completion의 최종 보완 commit이다. +- 이 문서는 cbb621b 다음 commit으로 dev에 기록하고 origin/dev에 함께 push한다. + 새 세션에서는 아래 명령으로 실제 동기화 상태를 다시 확인한다. - 완료 Phase: - - `solver-bootstrap` - - `domain-and-input-skeleton` - - `fem-and-beam-kernel` - - `equation-and-linear-solve` -- 다음 Phase: `results-and-pipeline` -- 다음 Step: `0 - result-database` -- `results-and-pipeline`의 Step 0~3은 모두 `pending`이다. -- `equation-and-linear-solve`는 `dev`에 fast-forward 병합되었고 로컬 - `feat-equation-and-linear-solve` 브랜치는 삭제되었다. -- 원격 push는 수행하지 않았다. + - solver-bootstrap + - domain-and-input-skeleton + - fem-and-beam-kernel + - equation-and-linear-solve + - results-and-pipeline + - abaqus-subset-completion +- 다음 Phase: deterministic-parallel-assembly +- 다음 Step: 0 - canonical-contribution-order +- deterministic-parallel-assembly의 Step 0~2는 모두 pending이다. +- 후속 Phase인 result-contract-completion, beam-reference-qualification, + internal-release도 아직 pending이다. +- feat-abaqus-subset-completion은 dev에 fast-forward 병합된 뒤 삭제되었다. +- 이 문서 갱신 전 작업 트리는 clean이었다. -이 문서를 갱신하기 직전 작업 트리는 clean이었다. 현재 -`docs/HANDOFF.md` 변경은 사용자가 별도로 요청하지 않는 한 커밋하지 않는다. -새 세션에서 Harness를 실행하기 전에 이 변경을 먼저 커밋하거나 별도로 정리해야 -한다. 그렇지 않으면 executor의 feature branch와 Step commit에 인수인계 문서가 -섞일 수 있다. +새 세션에서 원격에 맞추기 위한 reset, rebase, force push를 수행하지 않는다. +먼저 다음 상태를 확인하고 dev와 origin/dev가 다르면 원인을 조사한다. -로컬 `dev`의 미push 9 commit을 보존한다. 원격에 맞추기 위한 reset, 강제 checkout, -rebase 또는 force push를 수행하지 않는다. + 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 -## 3. 완료된 `equation-and-linear-solve` +## 3. 완료된 results-and-pipeline -Phase metadata는 `/phases/equation-and-linear-solve/index.json`에 기록되어 있으며 -Step 0~2가 모두 `completed`다. +Phase metadata는 /phases/results-and-pipeline/index.json에 기록되어 있으며 Step +0~3이 모두 completed다. -주요 commit: +주요 결과: -- `8342774` — deterministic serial symmetric CSR assembly -- `1bf277c` — essential BC elimination과 reaction recovery -- `e216660` — MKL PARDISO linear solver adapter -- `2dd17be` — Phase 완료 metadata -- `741fc9e` — 독립 review 지적과 HANDOFF 계약 수정 -- `a020249` — 완료된 Step 계약 문서 정합화 - -독립 재검토 결과 남은 Critical, Important, Minor 항목 없이 merge-ready 판정을 -받았으며, 아래 계약이 테스트로 고정되어 있다. - -### 3.1 Symmetric CSR과 serial assembly +- HDF5 API에 의존하지 않는 ResultDatabase, ResultStep, ResultFrame, NodalFrame + semantic model과 results-stage validation +- /docs/HDF5_SCHEMA.md의 schema 1.0.0 계약 +- move-only HDF5 RAII writer와 public reader round trip +- serial assembly, essential BC, PARDISO, full reconstruction과 reaction recovery를 + 조율하는 LinearStaticAnalysis +- free equation이 0인 all-constrained 해석의 PARDISO 우회 +- parser부터 HDF5 writer까지 연결하는 run_solver와 solve CLI +- fesa solve --output 수직 파이프라인 관련 파일: -- `/include/fesa/assembly/symmetric_csr.hpp` -- `/include/fesa/assembly/equation_system.hpp` -- `/include/fesa/assembly/serial_assembler.hpp` -- `/src/fesa/assembly/serial_assembler.cpp` -- `/tests/unit/assembly/serial_assembler_test.cpp` +- /include/fesa/results/ +- /src/fesa/results/ +- /include/fesa/io/hdf5/ +- /src/fesa/io/hdf5/ +- /include/fesa/analysis/ +- /src/fesa/analysis/ +- /include/fesa/analysis/run_solver.hpp +- /src/fesa/analysis/run_solver.cpp +- /docs/HDF5_SCHEMA.md +- /tests/integration/pipeline/minimal_cantilever_test.cpp 핵심 계약: -- `SymmetricCsr`는 0-based upper triangle만 저장한다. -- 각 row의 column index는 strictly increasing이다. -- 연결되지 않은 절점의 자유도를 포함해 모든 row가 diagonal entry를 갖는다. - contribution이 없으면 값은 0이다. 따라서 이후 solver가 구조 오류가 아니라 - singular equation system으로 진단할 수 있다. -- sparsity pattern 생성과 numeric merge는 분리되어 있다. -- numeric contribution은 - `(row,column,element-origin,local-order)` 순서로 정렬·합산한다. -- 비결합적인 `1 + 1 + 1e16` 규모의 테스트가 element origin 순서를 bit pattern으로 - 고정한다. Domain storage order로 합산하도록 바꾸면 안 된다. -- Beam kernel failure를 0 stiffness로 대체하지 않고 assembly 오류로 전달한다. -- `EquationSystem`은 원래 full `stiffness`와 `force`를 소유하며 constraint 처리 전 - 상태로 보존한다. +- results semantic model은 HDF5 타입이나 handle을 노출하지 않는다. +- 모든 HDF5 resource는 adapter 내부의 move-only RAII wrapper가 소유한다. +- nodal result의 node ID와 6성분 displacement/reaction 배열 순서는 DofManager의 + full-vector 순서와 일치한다. +- 반력은 reduced system이 아니라 원래 full system의 r=Ku-f에서 계산한다. +- all-constrained system은 유효한 analysis case이며 PARDISO order 0 입력으로 + 전달하지 않는다. +- CLI와 run_solver는 parser, semantic mapper, analysis와 writer를 조율하는 + application orchestration 경계다. LinearStaticAnalysis 자체는 parser나 HDF5를 + 호출하지 않는다. +- CTest의 CLI test에는 설치된 oneAPI/HDF5 runtime PATH가 test property로 + 전달된다. 기본 셸 PATH에 해당 디렉터리가 없어도 CTest가 성공해야 한다. -이 serial assembler는 후속 `deterministic-parallel-assembly` Phase의 oracle이다. -이번 다음 Phase에서 TBB assembly를 선행 구현하지 않는다. +이 vertical slice 완료는 요소 결과 계약, Abaqus reference 자격 또는 내부 배포 +완료를 의미하지 않는다. -### 3.2 `DofManager`와 essential BC +## 4. 완료된 abaqus-subset-completion + +Phase metadata는 /phases/abaqus-subset-completion/index.json에 기록되어 있으며 +Step 0~4가 모두 completed다. + +주요 결과: + +- /docs/ABAQUS_INPUT_SUBSET.md에 Phase 1 입력 계약을 명문화 +- public parser/mapper fixture matrix를 74 cases로 확대 +- strict keyword scope, parameter form, data ownership과 정확한 source diagnostic +- Part/Assembly의 명시적, GENERATE, nested, forward set resolution +- flat mesh 또는 좌표변환 없는 단일 Part/Assembly/Instance 선택 +- 전역 material, Part-local Beam section과 ELSET assignment +- 명시적 transverse shear와 Phase 1 기본값 Asy=Asz=5A/6, SCF=0 +- 단일 Step/Static, Boundary, Cload와 명시적 no-op directive +- active Part뿐 아니라 inactive Part의 NODE, ELEMENT, section record와 reference + 유효성 검증 관련 파일: -- `/include/fesa/fem/dof_manager.hpp` -- `/include/fesa/constraints/essential_bc.hpp` -- `/src/fesa/constraints/essential_bc.cpp` -- `/tests/unit/constraints/essential_bc_test.cpp` +- /docs/ABAQUS_INPUT_SUBSET.md +- /include/fesa/io/abaqus/active_input.hpp +- /include/fesa/io/abaqus/set_resolver.hpp +- /src/fesa/io/abaqus/parser.cpp +- /src/fesa/io/abaqus/active_input.cpp +- /src/fesa/io/abaqus/set_resolver.cpp +- /src/fesa/io/abaqus/semantic_mapper.cpp +- /tests/fixtures/abaqus/contract.tsv +- /tests/unit/io/abaqus/ +- /tests/integration/io/minimal_deck_to_domain_test.cpp -핵심 계약: +특히 유지할 계약: -- `DofManager`가 full DOF, free equation mapping과 prescribed value를 단독 소유한다. -- full index 기반 `equation(std::size_t)`와 - `prescribed_value(std::size_t)` query가 추가되어 있다. -- `eliminate_essential_bcs(const EquationSystem&, const DofManager&)`에는 별도 - prescribed 목록을 전달하지 않는다. -- `ReducedSystem`은 reduced `stiffness`와 `force`만 소유한다. free/full mapping이나 - prescribed full vector를 중복 저장하지 않는다. -- full solution은 `DofManager::reconstruct_full()`로 복원한다. -- 0과 비영 prescribed value의 RHS shift, all-constrained order 0 system, 원본 system - 불변성이 검증되어 있다. -- 반력은 reduced system이 아니라 원래 full system의 `r=Ku-f`에서 계산한다. -- 입력뿐 아니라 RHS shift와 reaction 산술 결과가 NaN/Inf가 되는 경우도 성공 - 결과로 반환하지 않는다. +- 사용되지 않는 Part는 파싱·record/reference validation하지만 Domain에는 넣지 않는다. +- NODE와 ELEMENT data row의 field 수는 정확해야 한다. +- enum 값 B31과 GENERAL은 대소문자를 구분하지 않는다. +- 계층형 Step의 Boundary/Cload target은 Assembly node set으로 해석한다. +- 모든 active B31 element만 정확히 하나의 section assignment를 가져야 한다. + inactive Part의 완전한 해석 가능성을 요구하도록 범위를 넓히지 않는다. +- missing_section diagnostic은 element keyword가 아니라 해당 element data row를 + source로 사용한다. +- unsupported keyword/parameter를 일반 ignore 경로로 숨기지 않는다. +- Heading, Preprint, Restart, Output만 문서화된 조건에서 no-op으로 허용한다. -`Domain::step().prescribed_dofs`를 다시 순회해 별도 constraint 상태를 만들지 않는다. +최종 독립 review에서 Critical, Important, Minor finding은 모두 0건이었다. -### 3.3 MKL PARDISO adapter +## 5. 현재 serial assembly oracle -관련 파일: +다음 Phase가 변경할 핵심 코드는 현재 /src/fesa/assembly/serial_assembler.cpp 한 +파일에 private helper로 모여 있다. -- `/include/fesa/solvers/linear/linear_solver.hpp` -- `/include/fesa/solvers/linear/pardiso_linear_solver.hpp` -- `/src/fesa/solvers/linear/pardiso_linear_solver.cpp` -- `/tests/unit/solvers/linear/pardiso_linear_solver_test.cpp` +현재 흐름: -핵심 계약: +1. 모든 full DOF의 diagonal을 포함하는 upper-triangle CSR sparsity pattern 생성 +2. 각 Beam 요소의 compute_beam3d2 호출 +3. local upper triangle 78개를 NumericContribution으로 수집 +4. row, column, EntityOrigin, local_order 순으로 정렬 +5. 같은 row/column을 고정된 순서로 합산 +6. nodal load를 full force vector로 조립 -- public `LinearSolver` 계약에는 MKL 타입이 노출되지 않는다. -- `PardisoLinearSolver`는 noncopyable이다. -- MKL LP64 `MKL_INT == std::int32_t`, `mtype=2`, `iparm[26]=1` matrix checker, - `iparm[34]=1` 0-based indexing을 사용한다. -- analysis, factorization, solve와 release phase를 adapter 내부에서 관리한다. -- release는 destructor fallback 외에 명시적으로 호출되어 release error도 - `DiagnosticStage::solver`의 `solver.release_failed`로 변환된다. -- matrix/RHS validation, singular diagnostic, repeated solve와 adapter 밖의 독립 - 상대잔차 계산이 검증되어 있다. -- order 0 reduced system은 constraint 계층에서는 유효하지만 PARDISO 입력으로는 - 거부된다. analysis orchestration이 all-constrained case를 별도로 처리해야 한다. +관련 public 계약: -## 4. 검증된 baseline과 개발환경 +- /include/fesa/assembly/symmetric_csr.hpp +- /include/fesa/assembly/equation_system.hpp +- /include/fesa/assembly/serial_assembler.hpp +- /src/fesa/assembly/serial_assembler.cpp +- /tests/unit/assembly/serial_assembler_test.cpp + +현재 테스트가 고정하는 oracle: + +- SymmetricCsr는 0-based upper triangle만 저장한다. +- row_offsets와 column_indices는 유효하며 각 row의 column이 strictly increasing이다. +- 연결되지 않은 node DOF도 값 0의 diagonal entry를 갖는다. +- element storage order와 external label 순열이 결과를 바꾸지 않는다. +- 1 + 1 + 1e16 규모의 contribution은 EntityOrigin 순으로 합산한 bit pattern을 + 고정한다. +- Beam kernel failure를 0 contribution으로 바꾸지 않고 assembly failure로 + 전달한다. +- full force vector의 load accumulation도 기존 결과와 같아야 한다. + +parallel 구현을 이유로 이 serial oracle을 먼저 변경하거나 tolerance 비교로 +약화하지 않는다. + +## 6. 검증된 baseline과 개발환경 + +2026-08-01 현재 확인한 도구: + +- CMake 4.4.0 +- MSBuild 18.8.2.30814 +- Visual Studio 2026 MSVC v145, Windows x64 +- codex-cli 0.146.0 +- Intel oneAPI MKL/TBB 2026.1 +- HDF5 2.1.1 +- GoogleTest 1.17.0, v145 x64 CRT build 새 PowerShell 세션에서 configure 또는 Harness 실행 전에 다음 환경 변수를 설정한다. 절대경로를 tracked CMake 파일이나 Preset에 넣지 않는다. -```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" + $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" -``` + 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 현재 네 package 경로가 모두 존재한다. 현재 `dev` HEAD에서 다음 -baseline을 검증했다. +네 package config와 다음 h5ls 경로가 존재함을 확인했다. -- MSBuild 18.8.2, MSVC v145 Debug build 성공 -- build 출력에 새 warning 없음 -- CTest 29개 중 29개 성공 -- Harness pytest 20개 중 20개 성공 -- pytest가 실제로 20개를 수집했으므로 0-test 성공이 아님 + C:\Program Files\HDF_Group\HDF5\2.1.1\bin\h5ls.exe 검증 명령: -```powershell -cmake --build --preset windows-debug -ctest --preset windows-debug --output-on-failure -uv run --with pytest python -m pytest -v -rs -``` + cmake --build --preset windows-debug + ctest --preset windows-debug --output-on-failure + uv run --with pytest python -m pytest -v -rs + +현재 baseline: + +- MSVC Debug build 성공, 새 warning 없음 +- CTest 49개 중 49개 성공 +- Harness pytest 20개 중 20개 성공 +- pytest가 실제 20개를 수집했으므로 0-test 성공이 아님 +- 최소 cantilever CLI solve와 HDF5 public schema inspection 성공 CMake cache가 없거나 package 경로가 바뀐 경우에만 같은 환경 변수 세션에서 먼저 다음을 실행한다. -```powershell -cmake --fresh --preset windows-debug -``` + cmake --fresh --preset windows-debug -HDF5 command-line tool은 현재 PATH에 없지만 다음 파일은 존재한다. +h5ls를 직접 실행할 때는 HDF5 DLL 외에 Intel libmmd.dll이 필요하다. HDF5 bin만 +PATH에 추가하면 Windows exit 0xC0000135가 발생할 수 있으므로 두 runtime +디렉터리를 현재 세션 PATH에 추가한다. 시스템 PATH는 영구 변경하지 않는다. -```text -C:\Program Files\HDF_Group\HDF5\2.1.1\bin\h5ls.exe -``` + $env:PATH = @( + "C:\Program Files\HDF_Group\HDF5\2.1.1\bin", + "C:\Program Files (x86)\Intel\oneAPI\2026.1\bin", + $env:PATH + ) -join ";" + h5ls --version -`h5ls.exe`는 HDF5 DLL 외에 Intel `libmmd.dll`도 요구한다. HDF5 `bin`만 PATH에 -추가하면 Windows exit `0xC0000135`로 실패하므로 Step 1과 Step 3 Acceptance -Criteria에서는 HDF5와 oneAPI `bin`을 모두 현재 세션 PATH에 추가한다. 시스템 -PATH를 영구 변경하지 않는다. +## 7. 다음 Phase 목표와 Step 순서 -```powershell -$env:PATH = @( - "C:\Program Files\HDF_Group\HDF5\2.1.1\bin", - "C:\Program Files (x86)\Intel\oneAPI\2026.1\bin", - $env:PATH -) -join ";" -h5ls --version -``` +deterministic-parallel-assembly의 목표는 oneTBB로 요소 계산을 병렬화하면서 +serial oracle과 thread count 사이의 CSR, RHS와 최종 해석 결과를 bit-for-bit +동일하게 유지하는 것이다. -2026-07-31 현재 이 설정에서 `h5ls: Version 2.1.1`과 exit code 0을 확인했다. +### Step 0 - canonical-contribution-order -## 5. 다음 Phase 목표와 Step 순서 +- serial assembly를 변경하지 않은 상태에서 병렬 경로가 공유할 + MatrixContribution과 canonical merge contract를 분리한다. +- 입력 순열, 같은 row/column의 여러 element, cancellation과 signed zero를 포함한 + 실패 테스트를 먼저 작성한다. +- 정렬 key는 row, column, stable element identity, local_order다. +- canonicalize_contributions와 merge_contributions는 하나의 고정 total order와 + 하나의 merge 구현만 가져야 한다. +- 아직 TBB code를 추가하지 않는다. -`results-and-pipeline`의 독립 deliverable은 nodal result semantic model과 최소 HDF5 -schema를 만들고, 이미 구현된 parser부터 linear solve까지 production 경로를 -조율해 `fesa solve ... --output ...` 수직 슬라이스를 완성하는 것이다. +Focused acceptance: -이 milestone은 입력-해석-출력 경로가 연결되었다는 뜻일 뿐 Beam의 수치 자격 완료나 -Phase 1 내부 배포 완료를 의미하지 않는다. 요소 결과 회복, 완전한 자기완결 HDF5, -Abaqus reference qualification은 뒤의 별도 Phase에 남아 있다. + cmake --build --preset windows-debug + ctest --preset windows-debug -R "CanonicalContribution|DeterministicMerge" --output-on-failure + ctest --preset windows-debug --output-on-failure -### Step 0 — `result-database` +### Step 1 - tbb-element-evaluation -- `/include/fesa/results/`와 `/src/fesa/results/`에 HDF5와 독립적인 최소 semantic - result model을 만든다. -- 현재 Step 계약의 실체는 `ResultDatabase -> ResultStep -> ResultFrame -> - NodalFrame`이다. -- 이 Phase에는 전역 좌표계 nodal displacement/rotation과 reaction/moment만 담는다. -- node ID와 6-component field의 size 일치, duplicate node, duplicate step/frame, - nonfinite 값을 실패 테스트로 먼저 고정한다. -- aggregate를 그대로 공개하면서 invalid state를 나중에 검사할지, 검증된 factory를 - 둘지 구현 전에 하나로 정한다. 현재 Step의 “invalid result model을 거부” 조건을 - 실제 호출 가능한 API로 표현해야 한다. -- element result, field/history 범용 hierarchy, velocity, acceleration, temperature를 - 미리 만들지 않는다. +- oneTBB는 독립적인 Beam element evaluation에만 사용한다. +- worker는 thread-local contribution을 만들며 공유 CSR values에 쓰지 않는다. +- merge는 Step 0의 canonical serial 순서를 그대로 사용한다. +- AssemblyOptions의 max_threads와 grain_size로 실행을 제한한다. +- max_threads=1과 2 이상에서 serial/parallel CSR와 force를 bit-for-bit 비교한다. +- PARDISO를 TBB task 안에서 호출하지 않는다. -### Step 1 — `minimal-hdf5-schema` +Focused acceptance: -- writer code보다 먼저 `/docs/HDF5_SCHEMA.md`에 schema `1.0.0`의 정확한 계약을 - 작성한다. -- 최소 writer/reader adapter는 `/include/fesa/io/hdf5/`와 - `/src/fesa/io/hdf5/`에 둔다. -- schema/version, node origin `(part,instance,local label)`, dense ID map, 좌표, - connectivity, 적용 전단강성과 input/default source, nodal displacement/reaction을 - round trip한다. -- public reader와 `h5ls`로 writer 산출물을 다시 연다. production writer 내부 상태나 - test-only parser로 검증하지 않는다. -- 모든 `hid_t`와 HDF5 resource는 move-only RAII wrapper 내부에 둔다. -- 모든 HDF5 실패를 `DiagnosticStage::results`의 diagnostic 또는 adapter 경계에서 - 포착되는 오류로 변환한다. -- reference CSV와 아직 존재하지 않는 결과를 위한 빈 group을 추가하지 않는다. + cmake --build --preset windows-debug + ctest --preset windows-debug -R "ParallelAssembly|TbbElementEvaluation" --output-on-failure + ctest --preset windows-debug --output-on-failure -### Step 2 — `linear-static-analysis` +### Step 2 - thread-count-determinism -- `/include/fesa/analysis/`와 `/src/fesa/analysis/`에 orchestration만 구현한다. -- 이미 검증된 `Domain`을 입력받으며 parser, CLI, HDF5를 호출하지 않는다. -- 실행 순서는 `DofManager -> serial assembly -> essential BC -> PARDISO -> full - reconstruction -> reaction -> nodal ResultDatabase`다. -- free equation 수가 0이면 PARDISO를 호출하지 않고 prescribed full vector와 원래 - 평형식으로 결과를 만든다. -- nodal result의 ID 순서와 full vector의 6-DOF block 순서가 반드시 일치해야 한다. - `DofManager` numbering이 internal `NodeId` 정렬 기반이므로 Domain storage order를 - 묵시적으로 사용하지 않는다. -- hand-check 가능한 한 요소 Domain으로 displacement, reaction, solver residual과 - `Ku-f-r` 평형을 실패 테스트로 먼저 고정한다. -- 수치 kernel, constraint 또는 solver 로직을 analysis에 복제하지 않는다. +- thread count 1, 2, available concurrency에서 CSR, RHS, displacement와 reaction을 + bit-for-bit 비교한다. +- 최소 10회 반복해 scheduling 변화 회귀를 검사한다. +- 측정용 fesa_assembly_benchmark를 추가해 serial/parallel 시간과 element count를 + 출력한다. +- benchmark speedup은 환경 의존적이므로 pass 조건으로 만들지 않는다. +- assembly test 동안 MKL thread 수를 중첩해 키우지 않는다. -### Step 3 — `cli-pipeline-integration` +Focused acceptance: -- `run_solver(const AnalysisRequest&)`가 parser, semantic mapper, Domain, analysis와 - HDF5 writer를 application 경계에서 조율한다. -- 현재 parser API는 `parse_deck(path)`, semantic mapping API는 - `map_deck_to_domain(deck)`이다. -- CLI 계약은 다음 두 가지다. + cmake --build --preset windows-debug + ctest --preset windows-debug -R ThreadCountDeterminism --output-on-failure + .\out\build\windows-debug\Debug\fesa_assembly_benchmark.exe + ctest --preset windows-debug --output-on-failure -```text -fesa solve --output -fesa --version -``` +## 8. 구현 전에 정렬할 설계점 -- `/tests/fixtures/abaqus/minimal_cantilever.inp`는 이미 존재한다. -- `MinimalCantileverPipeline`은 `run_solver` 또는 CLI와 public HDF5 reader만 사용한다. -- 성공 시 node ID, finite displacement, reaction/equilibrium diagnostic과 schema path를 - 검증한다. -- parse, semantic, equation, solver 또는 results 실패는 원래 diagnostic stage와 - source 정보를 보존하고 CLI nonzero exit로 전달한다. -- hierarchical fixture의 아직 미지원 keyword를 Step 3에서 우회 처리하지 않는다. - 전체 Abaqus subset은 다음 `abaqus-subset-completion` Phase의 책임이다. +아래 항목은 범위를 늘리라는 의미가 아니다. Step 계약과 현재 serial oracle 사이에서 +구현 전에 결정하고 테스트로 고정할 최소 질문이다. -## 6. 구현 전에 명시적으로 정렬할 설계점 +1. Stable element identity + - Step 0 초안의 MatrixContribution은 ElementId를 제시한다. + - 현재 oracle은 EntityOrigin의 instance_name, local_label, part_name 순으로 + 정렬한다. + - ElementId만으로 기존 bit pattern과 storage-order 독립성을 보존할 수 있는지 + 먼저 확인한다. 확인 없이 oracle의 정렬 key를 바꾸지 않는다. -아래 항목은 범위를 늘리라는 의미가 아니다. 현재 Step 문서와 최종 PRD 사이의 -모호함을 구현 전에 드러내고 가장 단순한 일관된 계약을 선택하기 위한 확인 목록이다. +2. Canonical API와 serial 경로 + - Step 0은 serial assembly를 변경하지 말라고 요구하면서 공통 merge contract를 + 분리한다. + - 먼저 public/internal 경계를 최소화하고, 기존 assemble_serial의 관찰 가능한 + 결과가 bit-for-bit 유지되는 테스트를 둔다. + - 실제 두 번째 사용처가 생기기 전에 범용 registry나 backend hierarchy를 만들지 + 않는다. -1. **Result model 유효성 API** - - Step 0은 invalid model을 거부하라고 하지만 제시된 타입은 public aggregate다. - - raw aggregate + 별도 validation과 validated factory 중 하나를 선택하고 테스트가 - production validation 경로를 통과하게 한다. +3. Parallel failure ordering + - worker에서 여러 Beam kernel failure가 발생해도 scheduling 순서로 어느 오류를 + 반환할지 결정하면 재현성이 깨진다. + - shared CSR write나 first-writer-wins exception 상태를 만들지 말고 canonical + element identity 기준으로 deterministic하게 처리한다. -2. **HDF5 reader의 model metadata 반환 범위** - - Step 1의 `Hdf5ReadResult` 초안은 `ResultDatabase`만 반환하지만 round-trip 조건은 - node origin, 좌표, connectivity, shear source까지 재검증하라고 한다. - - 이 metadata를 `ResultDatabase`에 억지로 넣지 말고, reader inspection model을 - 최소로 추가하거나 read result 계약을 정렬한다. `Domain`을 HDF5 API 타입으로 - 오염시키지 않는다. +4. AssemblyOptions validation + - max_threads와 grain_size의 0 의미를 묵시적으로 정하지 않는다. + - automatic 또는 invalid 중 가장 단순한 계약을 선택하고 focused test로 고정한다. -3. **schema `1.0.0`의 최소/최종 범위** - - 이번 Phase는 nodal vertical slice만 구현하고 `result-contract-completion`이 - element 결과와 완전한 자기완결 계약을 뒤에서 채운다. - - 빈 미래 hierarchy는 만들지 않되, `/docs/HDF5_SCHEMA.md`에 이번 최소 required - dataset과 이후 additive compatibility 규칙을 분명히 구분한다. +5. Force assembly + - 현재 RHS는 nodal load를 serial full-vector 순서로 누적한다. + - 이번 Phase는 element evaluation 병렬화가 목적이다. force accumulation을 별도 + 병렬 기능으로 확장하지 말고 serial oracle과 bitwise equality를 유지한다. -4. **deterministic nodal ordering** - - `DofManager` full vector는 sorted internal `NodeId` 순서다. - - `NodalFrame::node_ids`와 6-component displacement/reaction 배열을 같은 순서로 - 만드는 최소 query 또는 정렬 로직을 한 곳에서만 소유한다. +6. Benchmark 격리 + - benchmark는 제품 correctness test를 우회하는 별도 assembly를 사용하지 않는다. + - fixed Domain과 production serial/parallel API를 호출한다. + - speedup이나 release 성능 목표를 임의 assertion으로 추가하지 않는다. -5. **all-constrained analysis** - - reduced order 0은 constraint 성공이고 PARDISO invalid input이다. - - Step 2가 solver 호출을 생략하는 명시적 branch를 갖고 prescribed displacement와 - full reaction을 계산한다. +## 9. 아키텍처와 범위 경계 -6. **analysis와 application 경계** - - Step 2 `LinearStaticAnalysis`는 Domain-to-ResultDatabase만 담당한다. - - Step 3 `run_solver`가 parser와 HDF5를 담당한다. ARCHITECTURE의 포괄적 lifecycle - 설명을 이유로 HDF5 API를 analysis에 직접 넣지 않는다. +- oneTBB 의존성은 assembly adapter/implementation 경계에 가둔다. +- core, model, fem, elements의 public contract에 TBB type을 노출하지 않는다. +- Beam kernel은 element-local contribution만 계산하고 전역 CSR을 알지 않는다. +- DofManager가 DOF와 equation mapping을 계속 단독 소유한다. +- worker는 공유 CSR values에 atomic add하지 않는다. +- contribution의 부동소수점 합산 순서를 thread scheduling과 분리한다. +- TBB element work가 모두 끝난 후에만 PARDISO를 호출한다. +- 기존 assemble_serial은 oracle로 유지한다. +- tolerance 비교를 bitwise 재현성의 대체물로 사용하지 않는다. +- result-contract-completion의 element result, HDF5 확장, CSV adapter를 선행하지 + 않는다. +- beam-reference-qualification의 Abaqus 골든 비교와 tolerance 작업을 선행하지 + 않는다. +- internal-release의 installer, Release package와 validation report를 선행하지 + 않는다. -## 7. 아키텍처와 범위 경계 +## 10. Harness child 환경 -- `results`는 HDF5 API에 의존하지 않는 semantic model이다. -- `io/hdf5`만 HDF5 C API, schema version과 resource lifetime을 안다. -- `analysis`는 기존 production 모듈을 조율하지만 수치 kernel과 외부 API를 - 재구현하지 않는다. -- `run_solver`와 CLI는 application 경계다. CLI parsing을 `fesa_core`의 analysis - 객체에 넣지 않는다. -- `core`, `model`, `fem`, `elements`는 HDF5 API에 의존하지 않는다. -- 외부 ID와 internal dense index mapping을 혼동하지 않는다. -- HDF5 파일에 단위 변환을 추가하지 않는다. FESA 입력과 결과는 일관 단위계를 - 전제로 한다. -- element section result, point stress, reference CSV, TBB parallel assembly, - 다중 Step/Instance와 미지원 Abaqus keyword를 선행 구현하지 않는다. -- 성공 경로에 fake stiffness, fake result 또는 test-only solver를 사용하지 않는다. +이전 Harness 실행에서 WindowsApps PowerShell을 child process로 시작할 때 access +denied가 발생했다. 확인된 구성: -## 8. Child sandbox의 MSBuild 실행 조건 +- standalone Codex release: + C:\Users\baram\.codex\packages\standalone\releases\0.146.0-x86_64-pc-windows-msvc +- WindowsApps가 제거된 PATH +- Windows PowerShell 5.1 +- Harness 실행 동안만 [windows] sandbox = "unelevated" -이전 두 Harness Phase에서 child sandbox를 조사한 결과: +현재 C:\Users\baram\.codex\config.toml은 원래 값인 +[windows] sandbox = "elevated"로 복원되어 있음을 2026-08-01에 확인했다. -- 앱 설치 경로의 `codex-cli 0.146.0`은 matching `codex-resources`를 찾지 못했다. -- 완전한 standalone 배포는 다음 위치에 있으며 현재 `codex.exe`와 - `codex-resources`가 모두 존재한다. - `C:\Users\baram\.codex\packages\standalone\releases\0.146.0-x86_64-pc-windows-msvc` -- WindowsApps 경유 PowerShell에서는 child command가 실패했고 Windows PowerShell - 5.1에서는 정상 동작했다. -- `[windows] sandbox = "elevated"`에서는 MSBuild FileTracker가 access denied로 - 실패했다. -- standalone Codex, WindowsApps가 제거된 PATH와 - `[windows] sandbox = "unelevated"` 조합에서는 child MSBuild가 성공했다. - -현재 `C:\Users\baram\.codex\config.toml`은 원래 값인 -`[windows] sandbox = "elevated"`로 복원되어 있다. 다음 Harness 실행에서도 같은 -문제가 재현되면 사용자가 이전에 승인한 임시 전환 방식에 따라 다음 순서를 사용한다. - -1. 다른 Codex 작업에 미칠 영향을 확인하고 global config 원래 값을 기록한다. -2. Harness 실행 동안만 `[windows] sandbox = "unelevated"`로 바꾼다. -3. 현재 PowerShell 세션의 PATH 앞에 standalone `bin`과 Windows PowerShell 5.1을 - 둔다. 모든 `WindowsApps` entry를 제거해야 하며 alias 디렉터리 하나만 제거하면 - direct package 경로가 남을 수 있다. - -```powershell -$codexReleaseBin = "C:\Users\baram\.codex\packages\standalone\releases\0.146.0-x86_64-pc-windows-msvc\bin" -$windowsPowerShell = "$env:SystemRoot\System32\WindowsPowerShell\v1.0" -$filteredPath = $env:PATH -split ";" | Where-Object { - $_ -and - $_ -ne $codexReleaseBin -and - $_ -ne $windowsPowerShell -and - $_ -notmatch "WindowsApps" -and - $_ -notmatch "\\OpenAI\\Codex\\bin$" -} -$env:PATH = (@($codexReleaseBin, $windowsPowerShell) + $filteredPath) -join ";" - -(Get-Command codex).Source -(Get-Command powershell).Source -``` +같은 문제가 재현될 때만 다음 순서를 사용한다. +1. 다른 Codex 작업에 미칠 영향을 확인하고 config 원래 값을 기록한다. +2. Harness 실행 동안만 sandbox를 unelevated로 바꾼다. +3. 현재 PowerShell 세션 PATH 앞에 standalone bin과 Windows PowerShell 5.1을 + 두고 모든 WindowsApps entry를 제거한다. 4. package 환경 변수와 baseline을 확인한 뒤 같은 세션에서 Harness를 실행한다. -5. 성공·실패와 무관하게 `finally`에 해당하는 정리 단계에서 global config를 즉시 - `[windows] sandbox = "elevated"`로 복원하고 실제 값을 다시 읽어 확인한다. +5. 성공·실패와 무관하게 finally에 해당하는 정리 단계에서 global config를 즉시 + elevated로 복원하고 실제 값을 다시 읽는다. -사용자 profile 전체나 드라이브 루트를 `--codex-add-dir`로 허용하지 않는다. 설치 -버전이나 경로가 달라졌다면 위 절대경로를 맹목적으로 사용하지 말고 실제 standalone -release와 `codex-resources` 존재를 먼저 확인한다. + $codexReleaseBin = "C:\Users\baram\.codex\packages\standalone\releases\0.146.0-x86_64-pc-windows-msvc\bin" + $windowsPowerShell = "$env:SystemRoot\System32\WindowsPowerShell\v1.0" + $filteredPath = $env:PATH -split ";" | Where-Object { + $_ -and + $_ -ne $codexReleaseBin -and + $_ -ne $windowsPowerShell -and + $_ -notmatch "WindowsApps" -and + $_ -notmatch "\\OpenAI\\Codex\\bin$" + } + $env:PATH = (@($codexReleaseBin, $windowsPowerShell) + $filteredPath) -join ";" -이전 Harness는 모든 Step과 phase commit을 완료한 뒤 stderr reader의 CP949/UTF-8 -decode 예외를 출력한 적이 있다. exit code, phase metadata와 Git commit이 정상이면 -그 메시지만으로 제품 실패로 단정하지 않는다. + (Get-Command codex).Source + (Get-Command powershell).Source -## 9. 새 세션 시작 절차 +사용자 profile 전체나 drive root를 --codex-add-dir로 허용하지 않는다. 설치 버전이나 +경로가 달라졌다면 위 절대경로를 그대로 사용하지 말고 실제 standalone release와 +codex-resources 존재를 먼저 확인한다. -먼저 이 문서와 다음 Phase 파일을 모두 읽는다. +Harness가 모든 Step과 phase commit을 완료한 뒤 stderr reader의 CP949/UTF-8 decode +예외를 출력할 수 있다. exit code만 보지 말고 phase metadata, output JSON, Git +commit과 전체 검증 결과를 함께 확인한다. -```text -/phases/results-and-pipeline/index.json -/phases/results-and-pipeline/step0.md -/phases/results-and-pipeline/step1.md -/phases/results-and-pipeline/step2.md -/phases/results-and-pipeline/step3.md -``` +## 11. 새 세션 시작 절차 -그 다음 저장소 상태를 재검증한다. +먼저 이 문서와 다음 파일을 모두 읽는다. -```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 -``` + /phases/deterministic-parallel-assembly/index.json + /phases/deterministic-parallel-assembly/step0.md + /phases/deterministic-parallel-assembly/step1.md + /phases/deterministic-parallel-assembly/step2.md + /src/fesa/assembly/serial_assembler.cpp + /tests/unit/assembly/serial_assembler_test.cpp -`docs/HANDOFF.md` 변경이 남아 있으면 먼저 사용자의 의도대로 커밋하거나 정리한다. -4절의 package 환경 변수를 설정하고 baseline을 실행한다. 필요하면 8절의 child -sandbox 조건을 적용한 뒤 다음을 실행한다. +그 다음 Git과 package 상태를 재검증하고 6절의 baseline 명령을 실행한다. 필요하면 +10절의 child sandbox 조건을 적용한 뒤 다음을 실행한다. -```powershell -python scripts/execute.py results-and-pipeline -``` + python scripts/execute.py deterministic-parallel-assembly -executor는 `feat-results-and-pipeline` 브랜치를 생성하거나 checkout하고 Step 상태와 -output metadata를 기록한다. 사용자가 명시적으로 요청하지 않은 한 `--push`를 -사용하지 않는다. +executor는 feat-deterministic-parallel-assembly 브랜치를 생성하거나 checkout하고 +Step 상태와 output metadata를 기록한다. 사용자가 명시적으로 요청하지 않은 한 +--push를 사용하지 않는다. 각 Step은 다음 순서를 지킨다. 1. Step 파일의 필수 문서와 선행 구현을 모두 읽는다. -2. 성공 기준과 semantic/schema/lifecycle invariant를 명시한다. -3. 모호한 계약은 6절을 기준으로 구현 전에 정렬한다. +2. 성공 기준과 canonical ordering/threading invariant를 명시한다. +3. 8절의 모호한 계약을 구현 전에 정렬한다. 4. 실패 테스트를 먼저 작성하고 예상한 이유로 실패함을 확인한다. 5. 테스트를 통과시키는 최소 production code만 구현한다. 6. focused test, 전체 CTest와 Harness pytest를 실행한다. 7. Step summary와 output metadata가 실제 결과와 일치하는지 확인한다. -8. Phase 종료 전 전체 diff를 아키텍처, schema, diagnostic과 resource lifetime - 기준으로 review한다. +8. Phase 종료 전 전체 diff를 determinism, race avoidance, TBB 경계와 기존 serial + oracle 기준으로 review한다. -## 10. 다음 Phase 완료 조건 +## 12. 다음 Phase 완료 조건 -- `/phases/results-and-pipeline/index.json`의 Step 0~3이 모두 `completed` -- `/phases/index.json`에서 `results-and-pipeline`이 `completed` -- invalid nodal result model과 finite-data invariant 테스트 통과 -- `/docs/HDF5_SCHEMA.md`가 writer보다 먼저 작성되고 실제 산출물과 일치 -- public HDF5 reader round trip과 `h5ls` schema inspection 통과 -- 모든 HDF5 handle이 adapter 내부 RAII wrapper에서 해제됨 -- one-element linear static displacement, reaction, residual과 equilibrium 검증 통과 -- all-constrained analysis가 PARDISO 없이 성공 -- `fesa solve tests\fixtures\abaqus\minimal_cantilever.inp --output ...` 성공 -- CLI 실패 입력이 nonzero exit와 원래 stage/source diagnostic을 반환 +- /phases/deterministic-parallel-assembly/index.json의 Step 0~2가 모두 completed +- /phases/index.json에서 deterministic-parallel-assembly가 completed +- shuffled/cancellation/signed-zero contribution의 canonical 결과가 bit-for-bit 동일 +- serial과 parallel의 CSR row offsets, column indices, values와 force가 동일 +- thread count 1, 2, available concurrency와 최소 10회 반복에서 결과가 동일 +- 최종 linear static displacement와 reaction이 thread count에 무관하게 동일 +- worker가 thread-local contribution만 생성하고 공유 CSR에 atomic add하지 않음 +- TBB task와 PARDISO 실행이 중첩되지 않음 +- deterministic Beam kernel failure propagation 검증 +- benchmark가 production API를 사용하고 speedup을 pass 조건으로 만들지 않음 - focused test와 전체 CTest 통과 - Harness pytest가 0개가 아닌 상태로 전체 통과 - 새 MSVC warning 없음 -- HDF5 API가 `io/hdf5` 밖의 public semantic contract로 노출되지 않음 -- element result, full Abaqus subset, TBB assembly, reference 비교를 선행 구현하지 않음 -- 이 결과를 Beam 수치 자격 완료나 Phase 1 내부 배포 완료로 표시하지 않음 -- review의 Critical/Important 항목 해결 -- 사용자 선택 전 원격 push나 `dev` 병합을 수행하지 않음 +- 독립 review의 Critical/Important finding 해결 +- 사용자 선택 전 원격 push나 dev 병합을 수행하지 않음 새 세션의 권장 첫 요청: -> `docs/HANDOFF.md`와 `phases/results-and-pipeline/step0.md`부터 `step3.md`를 읽고 -> 현재 baseline, HDF5 도구 경로와 child sandbox의 MSBuild 실행 조건을 확인한 뒤 -> `results-and-pipeline` Phase를 시작해주세요. +> docs/HANDOFF.md와 deterministic-parallel-assembly의 index/step0~2를 읽고 현재 +> dev baseline, oneTBB 환경과 Harness child 실행 조건을 확인한 뒤 +> deterministic-parallel-assembly Phase를 시작해주세요.