Merge oneMKL TBB threading configuration

2026-10-20 23:11:41 +09:00
parent 649ffe4085 d1c0e36566
commit 9ae7e6d414
9 changed files with 52 additions and 27 deletions
@@ -8,7 +8,7 @@ set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL")
 # Pin the original backend ABI/link/thread choices rather than package defaults.
 set(MKL_INTERFACE ilp64)
 set(MKL_LINK dynamic)
-set(MKL_THREADING intel_thread)
+set(MKL_THREADING tbb_thread)
 include(cmake/FesaDependencies.cmake)
 find_package(Doxygen QUIET)
 if(Doxygen_FOUND)
@@ -44,6 +44,15 @@ if(NOT TARGET TBB::tbb)
    message(FATAL_ERROR "The oneTBB CONFIG package did not define TBB::tbb")
 endif()

+if(WIN32)
+    set(FESA_MKL_THREAD_TARGET MKL::mkl_tbb_thread)
+    if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+        set(FESA_MKL_THREAD_TARGET MKL::mkl_tbb_threadd)
+    endif()
+    # HDF5 requires the Intel math runtime independently of MKL threading.
+    set(FESA_INTEL_MATH_RUNTIME "$ENV{FESA_OMP_ROOT}/bin/libmmd.dll")
+endif()
+
 # Prefer the packaged shared C runtime when both variants exist. The Windows
 # static archive may carry compiler-runtime requirements that are not part of
 # the HDF5 imported target's transitive link interface.
@@ -2,6 +2,19 @@

 Hex8와 reduced-coordinate shell HHT의 실제 병목을 VTune으로 조사하고, 승인된 물리·입력·정밀도·결과 의미를 유지하며 실행 시간을 줄이는 작업이다. 새 요소·하중·적분법·공용 cache framework 추가는 범위 밖이다. 요구사항 `FEM-REQ-PERF-001..009`의 시간 목표와 검증은 별개이며 현재 최종 완료 상태는 아니다.

+## 현재 MKL 연결과 확인 범위
+
+2026-10-20 MKL threading layer를 TBB로 변경했다. 직접 MSBuild와 CMake의 x64
+Debug·Release 네 빌드는 모두 종료0이며 CLI와 세 테스트 실행 파일 총16개의 링크 및
+인접 DLL48개의 일반·지연 PE 의존성과 설치 원본 해시를 정적으로 확인했다.
+Debug는 `mkl_tbb_threadd`·`tbb12_debug`, Release는 `mkl_tbb_thread`·`tbb12`를 사용하고
+HDF5의 `libmmd.dll`을 유지한다. 근거는 `.build/mkl-tbb-20261020-01/`에 보관했다.
+
+사용자 지시로 이번 설정 변경에서는 테스트·모델·수치 비교·성능 측정·VTune을 실행하지
+않았다. 실제 DLL loading, 수치 정확성, 속도 향상과 OpenMP 대기 제거는 미검증이다.
+기존 OpenMP 전용 local-thread/TLS helper와 HHT cache 진단 코드는 유지했으며 TBB에서의
+동등성도 확인하지 않았다. 아래 과거 시간·검증 기록을 새 TBB 구성의 결과로 승계하지 않는다.
+
 ## 채택한 계산 경로와 수명

 [Matrix::Multiply](../../src/fesa/math/matrix.cpp)는 dense GEMV/GEMM, [SparseMatrix::Multiply](../../src/fesa/math/sparse_matrix.cpp)는 CSR validate·finite/RHS/checked MKL_INT 확인 후 `mkl_sparse_d_create_csr → mkl_sparse_d_mv → destroy`를 사용한다. Const 호출마다 변환 배열·values 복사·handle을 소유하므로 copy/move·동시 호출에 backend pointer를 공유하지 않는다. Empty shape도 입력 검증 뒤 zero vector를 반환한다. 지속 symbolic cache나 scalar fallback은 없다. 호출마다 CSR 배열 복사 비용이 있으므로 MKL 연결만으로 전체 성능 향상을 주장하지 않는다.
@@ -3,7 +3,7 @@
 ## 준비 순서

 저장소 root에서 VS x64 개발 환경을 사용한다. 직접 프로젝트는 v145 toolset과 Windows SDK를
-요구한다. 필요한 로컬 설치는 MKL·TBB·HDF5·OpenMP/Intel runtime과 승인된 GoogleTest
+요구한다. 필요한 로컬 설치는 MKL·TBB·HDF5·Intel 수학 runtime과 승인된 GoogleTest
 source checkout이다. CMake 경로에는 추가로 CMake 3.25 이상과 Ninja가 필요하다.
 Dependency 설치·다운로드·외부 source 수정은 아래 명령에 포함되지 않는다.

@@ -15,7 +15,7 @@ Dependency 설치·다운로드·외부 source 수정은 아래 명령에 포함
 | `FESA_MKL_ROOT` | MKL의 include·lib·runtime을 포함한 설치 root |
 | `FESA_TBB_ROOT` | TBB 설치 root; Debug와 Release runtime을 구분한다. |
 | `FESA_HDF5_ROOT` | HDF5 C library의 include·lib·runtime 설치 root |
-| `FESA_OMP_ROOT` | Intel OpenMP library와 runtime 설치 root |
+| `FESA_OMP_ROOT` | HDF5가 요구하는 `bin/libmmd.dll`의 Intel compiler runtime 설치 root; 기존 변수명을 유지한다. |
 | `MKL_DIR`·`TBB_DIR`·`HDF5_DIR` | CMake에서만 사용하는 각 CONFIG package 디렉터리; 설치 root와 혼동하지 않는다. |

 VS x64 Developer PowerShell에서 다음을 확인한다. 누락되면 해당 로컬 설치 경로를 설정한
@@ -33,7 +33,13 @@ foreach ($root_name in $required_roots) {
 ```

 위 확인은 환경변수 방식의 준비 절차다. `Fesa.Local.props`를 사용하는 경우에는 그 파일의
-동일 MSBuild property 값을 확인한다. CMake는 `Fesa.Local.props`를 읽지 않는다.
+동일 MSBuild property 값을 확인한다. CMake는 `Fesa.Local.props`를 읽지 않으며,
+HDF5용 `libmmd.dll`을 찾을 때 `FESA_OMP_ROOT` 환경변수를 사용한다.
+
+MKL은 ILP64·dynamic·TBB threading으로 연결한다. Debug는 `mkl_tbb_threadd`와
+`tbb12_debug.dll`, Release는 `mkl_tbb_thread`와 `tbb12.dll`을 사용한다. CLI와 세
+테스트 실행 파일 곁에 같은 구성의 DLL을 준비한다. MKL용 `mkl_intel_thread`와
+`libiomp5md.dll`은 연결·복사하지 않으며 HDF5의 `libmmd.dll`은 별도로 유지한다.

 ## 주 개발 빌드와 직접 검사

@@ -51,9 +51,11 @@ Configure/build/test의 compiler·구성·build tree를 함께 맞추고 discove

 직접 관리하는 [FESA.sln](../../FESA.sln)과 [msvc 지침](../../msvc/AGENTS.md)이 주 개발 빌드다.
 VS x64 개발 환경에서 저장소 root를 작업 디렉터리로 사용한다. v145 toolset과 로컬
-GoogleTest source checkout, MKL ILP64/dynamic/Intel threading·TBB·HDF5·OpenMP가 필요하다.
+GoogleTest source checkout, MKL ILP64/dynamic/TBB threading·oneTBB·HDF5와
+HDF5용 Intel 수학 runtime(`libmmd.dll`)이 필요하다.
 `FESA_GTEST_SOURCE_DIR`, `FESA_MKL_ROOT`, `FESA_TBB_ROOT`, `FESA_HDF5_ROOT`,
 `FESA_OMP_ROOT`에 설치 root를 지정하거나 ignored `msvc/Fesa.Local.props`로 주입한다.
+`FESA_OMP_ROOT`는 기존 변수명을 유지하며 현재 HDF5의 `libmmd.dll` 준비에 사용한다.
 개인 설치 경로를 추적 파일에 고정하거나 dependency를 자동 다운로드하지 않는다.

 ```bat
@@ -14,6 +14,8 @@
    <IntDir>$(FesaBuildRoot)obj\$(MSBuildProjectName)\</IntDir>
    <TargetName Condition="'$(MSBuildProjectName)'=='fesa_cli'">fesa</TargetName>
    <TbbSuffix Condition="'$(Configuration)'=='Debug'">_debug</TbbSuffix>
+    <FesaMklThreadName>mkl_tbb_thread</FesaMklThreadName>
+    <FesaMklThreadName Condition="'$(Configuration)'=='Debug'">mkl_tbb_threadd</FesaMklThreadName>
  </PropertyGroup>
  <PropertyGroup>
    <FesaExternalOptions Condition="'$(MSBuildProjectName)'=='fesa_solver'">/external:I&quot;$(FESA_MKL_ROOT)\include&quot; /external:I&quot;$(FESA_TBB_ROOT)\include&quot; /external:I&quot;$(FESA_HDF5_ROOT)\include&quot; /external:W0</FesaExternalOptions>
@@ -56,8 +58,8 @@
      <OptimizeReferences Condition="'$(Configuration)'=='Release' And '$(MSBuildProjectName)'=='fesa_cli'">true</OptimizeReferences>
      <EnableCOMDATFolding Condition="'$(Configuration)'=='Release' And '$(MSBuildProjectName)'=='fesa_cli'">true</EnableCOMDATFolding>
      <GenerateDebugInformation Condition="'$(Configuration)'=='Debug'">true</GenerateDebugInformation>
-      <AdditionalLibraryDirectories>$(FESA_MKL_ROOT)\lib;$(FESA_OMP_ROOT)\lib;$(FESA_TBB_ROOT)\lib;$(FESA_HDF5_ROOT)\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
-      <AdditionalDependencies>mkl_intel_ilp64_dll.lib;mkl_intel_thread_dll.lib;mkl_core_dll.lib;libiomp5md.lib;tbb12$(TbbSuffix).lib;hdf5.lib;shlwapi.lib;%(AdditionalDependencies)</AdditionalDependencies>
+      <AdditionalLibraryDirectories>$(FESA_MKL_ROOT)\lib;$(FESA_TBB_ROOT)\lib;$(FESA_HDF5_ROOT)\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
+      <AdditionalDependencies>mkl_intel_ilp64_dll.lib;$(FesaMklThreadName)_dll.lib;mkl_core_dll.lib;tbb12$(TbbSuffix).lib;hdf5.lib;shlwapi.lib;%(AdditionalDependencies)</AdditionalDependencies>
    </Link>
  </ItemDefinitionGroup>
  <ItemDefinitionGroup Condition="'$(MSBuildProjectName)'=='fesa_solver'">
@@ -4,18 +4,19 @@
    <Error Condition="'$(Platform)'!='x64'" Text="FESA requires MSVC x64." />
    <Error Condition="!Exists('$(FESA_GTEST_SOURCE_DIR)\googletest\src\gtest-all.cc')" Text="Set FESA_GTEST_SOURCE_DIR to the approved local GoogleTest source checkout." />
    <Error Condition="!Exists('$(FESA_MKL_ROOT)\lib\mkl_intel_ilp64_dll.lib')" Text="Set FESA_MKL_ROOT to the oneMKL installation root." />
+    <Error Condition="!Exists('$(FESA_MKL_ROOT)\lib\$(FesaMklThreadName)_dll.lib')" Text="The selected oneMKL TBB-thread import library was not resolved." />
    <Error Condition="!Exists('$(FESA_TBB_ROOT)\lib\tbb12$(TbbSuffix).lib')" Text="Set FESA_TBB_ROOT to the oneTBB installation root." />
    <Error Condition="!Exists('$(FESA_HDF5_ROOT)\lib\hdf5.lib')" Text="Set FESA_HDF5_ROOT to the shared HDF5 installation root." />
-    <Error Condition="!Exists('$(FESA_OMP_ROOT)\bin\libiomp5md.dll') Or !Exists('$(FESA_OMP_ROOT)\bin\libmmd.dll')" Text="Set FESA_OMP_ROOT to the Intel compiler runtime installation root." />
+    <Error Condition="!Exists('$(FESA_OMP_ROOT)\bin\libmmd.dll')" Text="Set FESA_OMP_ROOT to the Intel compiler runtime installation root required by HDF5." />
  </Target>
  <Target Name="StageFesaRuntime" AfterTargets="Build" Condition="'$(ConfigurationType)'=='Application'">
    <ItemGroup>
-      <FesaMklThread Include="$(FESA_MKL_ROOT)\bin\mkl_intel_thread.*.dll" />
+      <FesaMklThread Include="$(FESA_MKL_ROOT)\bin\$(FesaMklThreadName).*.dll" />
      <FesaMklCore Include="$(FESA_MKL_ROOT)\bin\mkl_core.*.dll" />
      <FesaMklDispatch Include="$(FESA_MKL_ROOT)\bin\mkl_def.*.dll" />
-      <FesaRuntime Include="@(FesaMklThread);@(FesaMklCore);@(FesaMklDispatch);$(FESA_TBB_ROOT)\bin\tbb12$(TbbSuffix).dll;$(FESA_OMP_ROOT)\bin\libiomp5md.dll;$(FESA_OMP_ROOT)\bin\libmmd.dll;$(FESA_HDF5_ROOT)\bin\hdf5.dll" />
+      <FesaRuntime Include="@(FesaMklThread);@(FesaMklCore);@(FesaMklDispatch);$(FESA_TBB_ROOT)\bin\tbb12$(TbbSuffix).dll;$(FESA_OMP_ROOT)\bin\libmmd.dll;$(FESA_HDF5_ROOT)\bin\hdf5.dll" />
    </ItemGroup>
-    <Error Condition="'@(FesaMklThread)'==''" Text="The oneMKL Intel-thread runtime DLL was not resolved." />
+    <Error Condition="'@(FesaMklThread)'==''" Text="The selected oneMKL TBB-thread runtime DLL was not resolved." />
    <Error Condition="'@(FesaMklCore)'==''" Text="The oneMKL core runtime DLL was not resolved." />
    <Error Condition="'@(FesaMklDispatch)'==''" Text="The oneMKL default-dispatch runtime DLL was not resolved." />
    <Copy SourceFiles="@(FesaRuntime)" DestinationFolder="$(OutDir)" SkipUnchangedFiles="true" />
@@ -159,11 +159,10 @@ target_link_options(fesa_cli PRIVATE
 unset(_fesa_target)

 if(WIN32)
-    if(NOT TARGET MKL::mkl_intel_thread OR NOT TARGET MKL::mkl_core OR
-       NOT OMP_DLL_DIR OR NOT OMP_DLLNAME)
+    if(NOT TARGET ${FESA_MKL_THREAD_TARGET} OR NOT TARGET MKL::mkl_core)
        message(FATAL_ERROR "The oneMKL runtime files required by fesa.exe were not resolved")
    endif()
-    if(NOT EXISTS "${OMP_DLL_DIR}/libmmd.dll")
+    if(NOT EXISTS "${FESA_INTEL_MATH_RUNTIME}")
        message(FATAL_ERROR "The Intel runtime required by the selected HDF5 DLL was not resolved")
    endif()

@@ -182,16 +181,13 @@ if(WIN32)
                "$<TARGET_FILE:TBB::tbb>"
                "$<TARGET_FILE_DIR:fesa_cli>"
        COMMAND "${CMAKE_COMMAND}" -E copy_if_different
-                "$<TARGET_FILE:MKL::mkl_intel_thread>"
+                "$<TARGET_FILE:${FESA_MKL_THREAD_TARGET}>"
                "$<TARGET_FILE_DIR:fesa_cli>"
        COMMAND "${CMAKE_COMMAND}" -E copy_if_different
                "$<TARGET_FILE:MKL::mkl_core>"
                "$<TARGET_FILE_DIR:fesa_cli>"
        COMMAND "${CMAKE_COMMAND}" -E copy_if_different
-                "${OMP_DLL_DIR}/${OMP_DLLNAME}"
-                "$<TARGET_FILE_DIR:fesa_cli>"
-        COMMAND "${CMAKE_COMMAND}" -E copy_if_different
-                "${OMP_DLL_DIR}/libmmd.dll"
+                "${FESA_INTEL_MATH_RUNTIME}"
                "$<TARGET_FILE_DIR:fesa_cli>"
        COMMAND "${CMAKE_COMMAND}" -E copy_if_different
                "${_fesa_cli_mkl_dispatch_dll}"
@@ -180,11 +180,10 @@ target_compile_definitions(
 )

 if(WIN32)
-    if(NOT TARGET MKL::mkl_intel_thread OR NOT TARGET MKL::mkl_core OR
-       NOT OMP_DLL_DIR OR NOT OMP_DLLNAME)
+    if(NOT TARGET ${FESA_MKL_THREAD_TARGET} OR NOT TARGET MKL::mkl_core)
        message(FATAL_ERROR "The oneMKL runtime files required by tests were not resolved")
    endif()
-    if(NOT EXISTS "${OMP_DLL_DIR}/libmmd.dll")
+    if(NOT EXISTS "${FESA_INTEL_MATH_RUNTIME}")
        message(FATAL_ERROR "The Intel runtime required by the selected HDF5 DLL was not resolved")
    endif()

@@ -205,16 +204,13 @@ if(WIN32)
                    "$<TARGET_FILE:TBB::tbb>"
                    "$<TARGET_FILE_DIR:${target_name}>"
            COMMAND "${CMAKE_COMMAND}" -E copy_if_different
-                    "$<TARGET_FILE:MKL::mkl_intel_thread>"
+                    "$<TARGET_FILE:${FESA_MKL_THREAD_TARGET}>"
                    "$<TARGET_FILE_DIR:${target_name}>"
            COMMAND "${CMAKE_COMMAND}" -E copy_if_different
                    "$<TARGET_FILE:MKL::mkl_core>"
                    "$<TARGET_FILE_DIR:${target_name}>"
            COMMAND "${CMAKE_COMMAND}" -E copy_if_different
-                    "${OMP_DLL_DIR}/${OMP_DLLNAME}"
-                    "$<TARGET_FILE_DIR:${target_name}>"
-            COMMAND "${CMAKE_COMMAND}" -E copy_if_different
-                    "${OMP_DLL_DIR}/libmmd.dll"
+                    "${FESA_INTEL_MATH_RUNTIME}"
                    "$<TARGET_FILE_DIR:${target_name}>"
            COMMAND "${CMAKE_COMMAND}" -E copy_if_different
                    "${_fesa_mkl_dispatch_dll}"