diff --git a/.github/workflows/pypi-wheels-cpu.yml b/.github/workflows/pypi-wheels-cpu.yml index 970b28e..36e72b0 100644 --- a/.github/workflows/pypi-wheels-cpu.yml +++ b/.github/workflows/pypi-wheels-cpu.yml @@ -6,9 +6,12 @@ on: - published workflow_dispatch: +env: + DEPS_CACHE_KEY: cibw-deps-manylinux_2_28-x86_64-hdf5_1.14.6-tiff_4.6.0-hypre_2.31.0-amrex_25.03-tinyprof-noeb-nofort-nompicxx-v9 + jobs: - build_wheels: - name: Build manylinux wheels on ubuntu-latest + build_core_and_cp39: + name: Build C++ core, cp39 & pure-Python wheels runs-on: ubuntu-latest steps: @@ -32,35 +35,50 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: "3.x" + python-version: "3.12" - - name: Install cibuildwheel - run: python -m pip install cibuildwheel==2.22.0 + - name: Install cibuildwheel and build + run: python -m pip install cibuildwheel==2.22.0 build - name: Cache native dependencies uses: actions/cache@v4 with: - path: .cibw-deps-cache - key: cibw-deps-manylinux_2_28-x86_64-hdf5_1.14.6-tiff_4.6.0-hypre_2.31.0-amrex_25.03-tinyprof-noeb-nofort-nompicxx-v8 + path: /tmp/cibw-deps-cache + key: ${{ env.DEPS_CACHE_KEY }} + + - name: Cache ccache objects (core + cp39) + uses: actions/cache@v4 + with: + path: /tmp/cibw-ccache + key: ccache-cpu-manylinux_2_28-cp39-${{ github.sha }} + restore-keys: | + ccache-cpu-manylinux_2_28-cp39- - - name: Build wheels + - name: Build cp39 wheel and populate core ccache run: python -m cibuildwheel --output-dir wheelhouse env: - CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*" + CIBW_BUILD: "cp39-*" CIBW_SKIP: "*musllinux* *i686*" CIBW_ARCHS_LINUX: "x86_64" CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28 CIBW_BEFORE_ALL_LINUX: > + set -e && + export CCACHE_DISABLE=1 && dnf install -y epel-release && dnf --enablerepo=powertools install -y - openmpi-devel gcc-c++ wget git + openmpi-devel gcc-c++ wget git xz zlib-devel libjpeg-turbo-devel python3-pip && + wget -q https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-linux-x86_64.tar.xz -O /tmp/ccache.tar.xz && + tar xf /tmp/ccache.tar.xz -C /usr/bin --strip-components=1 && + rm -f /tmp/ccache.tar.xz && + mkdir -p /host/tmp/cibw-ccache && + chmod -R a+rwX /host/tmp/cibw-ccache && pip3 install "cmake>=3.28,<4" && - export PATH=/usr/lib64/openmpi/bin:$PATH && - if [ -f /project/.cibw-deps-cache/deps.tar.gz ]; then + export PATH=/usr/local/bin:/usr/lib64/openmpi/bin:$PATH && + if [ -f /host/tmp/cibw-deps-cache/deps.tar.gz ]; then echo "=== Restoring cached dependencies ===" && - tar xzf /project/.cibw-deps-cache/deps.tar.gz -C / ; + tar xzf /host/tmp/cibw-deps-cache/deps.tar.gz -C / ; else echo "=== Building dependencies from source ===" && wget -q https://github.com/HDFGroup/hdf5/releases/download/hdf5_1.14.6/hdf5-1.14.6.tar.gz && @@ -113,22 +131,32 @@ jobs: -DCMAKE_POSITION_INDEPENDENT_CODE=ON && cmake --build /tmp/amrex/build -j$(nproc) && cmake --install /tmp/amrex/build && - strip --strip-debug /usr/local/lib/libamrex_3d.a /usr/local/lib/libHYPRE.a /usr/local/lib/libhdf5*.a /usr/local/lib/libtiff.a 2>/dev/null || true && - mkdir -p /project/.cibw-deps-cache && - tar czf /project/.cibw-deps-cache/deps.tar.gz /usr/local ; + (strip --strip-debug /usr/local/lib/libamrex_3d.a /usr/local/lib/libHYPRE.a /usr/local/lib/libhdf5*.a /usr/local/lib/libtiff.a 2>/dev/null || true) && + mkdir -p /host/tmp/cibw-deps-cache && + tar czf /host/tmp/cibw-deps-cache/deps.tar.gz /usr/local && + chmod -R a+rwX /host/tmp/cibw-deps-cache ; fi - CIBW_BEFORE_BUILD: pip install "cmake>=3.28,<4" + CIBW_BEFORE_BUILD: pip install "cmake>=3.28,<4" && rm -rf /tmp/oi-build CIBW_ENVIRONMENT_LINUX: > - PATH="/usr/lib64/openmpi/bin:$PATH" + PATH="/usr/local/bin:/usr/lib64/openmpi/bin:$PATH" + CCACHE_DIR="/host/tmp/cibw-ccache" + CCACHE_BASEDIR="/project" + CCACHE_NOHASHDIR="true" + SKBUILD_BUILD_DIR="/tmp/oi-build" CMAKE_C_COMPILER="mpicc" CMAKE_CXX_COMPILER="mpicxx" + CMAKE_C_COMPILER_LAUNCHER="ccache" + CMAKE_CXX_COMPILER_LAUNCHER="ccache" CMAKE_PREFIX_PATH="/usr/local" CMAKE_GENERATOR="Unix Makefiles" + CMAKE_ARGS="-DFETCHCONTENT_BASE_DIR=/tmp/fc-deps" SETUPTOOLS_SCM_PRETEND_VERSION="${{ steps.version.outputs.version }}" CIBW_REPAIR_WHEEL_COMMAND_LINUX: > + ccache -s && + chmod -R a+rwX /host/tmp/cibw-ccache && auditwheel repair -w {dest_dir} {wheel} --exclude libmpi.so --exclude libmpi.so.12 @@ -144,7 +172,169 @@ jobs: --exclude libmpi_mpifh.so.40 --exclude libgomp.so.1 - - name: Upload wheels as artifacts + - name: Verify host caches populated + run: | + ls -lh /tmp/cibw-deps-cache/deps.tar.gz + du -sh /tmp/cibw-ccache + + - name: Build pure-Python fallback wheel (py3-none-any) + env: + SETUPTOOLS_SCM_PRETEND_VERSION: ${{ steps.version.outputs.version }} + run: | + python -m build --wheel --outdir wheelhouse \ + -Cwheel.platlib=false \ + -Ccmake.define.OPENIMPALA_PURE_PYTHON=ON + ls -lh wheelhouse/ + python -m zipfile -l wheelhouse/*-py3-none-any.whl + if python -m zipfile -l wheelhouse/*-py3-none-any.whl | grep -q '_core'; then + echo "::error::Pure-Python wheel unexpectedly contains compiled _core module" + exit 1 + fi + + - name: Upload cp39 and pure-Python wheels + uses: actions/upload-artifact@v4 + with: + name: cibw-wheels-part-cp39 + path: ./wheelhouse/*.whl + retention-days: 1 + + build_matrix_wheels: + name: Build ${{ matrix.py }} manylinux wheel + needs: build_core_and_cp39 + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + py: [cp310, cp311, cp312, cp313] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + fetch-depth: 0 + + - name: Extract version from tag + id: version + run: | + if [[ "$GITHUB_REF_NAME" == v* ]]; then + VERSION="${GITHUB_REF_NAME#v}" + else + VERSION="$(git describe --tags --abbrev=0 | sed 's/^v//')" + fi + echo "version=${VERSION}" >> "$GITHUB_OUTPUT" + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install cibuildwheel + run: python -m pip install cibuildwheel==2.22.0 + + - name: Restore native dependencies cache + uses: actions/cache/restore@v4 + with: + path: /tmp/cibw-deps-cache + key: ${{ env.DEPS_CACHE_KEY }} + + - name: Cache ccache objects (${{ matrix.py }}) + uses: actions/cache@v4 + with: + path: /tmp/cibw-ccache + key: ccache-cpu-manylinux_2_28-${{ matrix.py }}-${{ github.sha }} + restore-keys: | + ccache-cpu-manylinux_2_28-cp39-${{ github.sha }} + ccache-cpu-manylinux_2_28-${{ matrix.py }}- + ccache-cpu-manylinux_2_28-cp39- + + - name: Build ${{ matrix.py }} wheel + run: python -m cibuildwheel --output-dir wheelhouse + env: + CIBW_BUILD: "${{ matrix.py }}-*" + CIBW_SKIP: "*musllinux* *i686*" + CIBW_ARCHS_LINUX: "x86_64" + CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28 + + CIBW_BEFORE_ALL_LINUX: > + set -e && + dnf install -y epel-release && + dnf --enablerepo=powertools install -y + openmpi-devel gcc-c++ wget git xz + zlib-devel libjpeg-turbo-devel python3-pip && + tar xzf /host/tmp/cibw-deps-cache/deps.tar.gz -C / && + wget -q https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-linux-x86_64.tar.xz -O /tmp/ccache.tar.xz && + tar xf /tmp/ccache.tar.xz -C /usr/bin --strip-components=1 && + rm -f /tmp/ccache.tar.xz && + mkdir -p /host/tmp/cibw-ccache && + chmod -R a+rwX /host/tmp/cibw-ccache && + pip3 install "cmake>=3.28,<4" + + CIBW_BEFORE_BUILD: pip install "cmake>=3.28,<4" && rm -rf /tmp/oi-build + + CIBW_ENVIRONMENT_LINUX: > + PATH="/usr/local/bin:/usr/lib64/openmpi/bin:$PATH" + CCACHE_DIR="/host/tmp/cibw-ccache" + CCACHE_BASEDIR="/project" + CCACHE_NOHASHDIR="true" + SKBUILD_BUILD_DIR="/tmp/oi-build" + CMAKE_C_COMPILER="mpicc" + CMAKE_CXX_COMPILER="mpicxx" + CMAKE_C_COMPILER_LAUNCHER="ccache" + CMAKE_CXX_COMPILER_LAUNCHER="ccache" + CMAKE_PREFIX_PATH="/usr/local" + CMAKE_GENERATOR="Unix Makefiles" + CMAKE_ARGS="-DFETCHCONTENT_BASE_DIR=/tmp/fc-deps" + SETUPTOOLS_SCM_PRETEND_VERSION="${{ steps.version.outputs.version }}" + + CIBW_REPAIR_WHEEL_COMMAND_LINUX: > + ccache -s && + chmod -R a+rwX /host/tmp/cibw-ccache && + auditwheel repair -w {dest_dir} {wheel} + --exclude libmpi.so + --exclude libmpi.so.12 + --exclude libmpi.so.40 + --exclude libmpi_cxx.so + --exclude libmpi_cxx.so.1 + --exclude libmpi_cxx.so.40 + --exclude libopen-rte.so + --exclude libopen-rte.so.40 + --exclude libopen-pal.so + --exclude libopen-pal.so.40 + --exclude libmpi_mpifh.so + --exclude libmpi_mpifh.so.40 + --exclude libgomp.so.1 + + - name: Upload ${{ matrix.py }} wheel + uses: actions/upload-artifact@v4 + with: + name: cibw-wheels-part-${{ matrix.py }} + path: ./wheelhouse/*.whl + retention-days: 1 + + bundle_wheels: + name: Bundle CPU & pure-Python wheels + needs: [build_core_and_cp39, build_matrix_wheels] + runs-on: ubuntu-latest + + steps: + - name: Download all wheel parts + uses: actions/download-artifact@v4 + with: + pattern: cibw-wheels-part-* + merge-multiple: true + path: wheelhouse/ + + - name: Verify complete wheelhouse (5 manylinux + 1 pure-Python) + run: | + ls -lh wheelhouse/ + COUNT=$(ls -1 wheelhouse/*.whl | wc -l) + if [ "$COUNT" -ne 6 ]; then + echo "::error::Expected 6 wheels (cp39..cp313 + py3-none-any), found $COUNT" + exit 1 + fi + + - name: Upload unified wheelhouse artifact uses: actions/upload-artifact@v4 with: name: cibw-wheels @@ -152,7 +342,7 @@ jobs: publish_to_pypi: name: Publish wheels to PyPI - needs: build_wheels + needs: bundle_wheels runs-on: ubuntu-latest # Only publish on release; workflow_dispatch leaves the artifact for manual # inspection without touching PyPI. diff --git a/.github/workflows/pypi-wheels-gpu.yml b/.github/workflows/pypi-wheels-gpu.yml index 98a835b..f3be75c 100644 --- a/.github/workflows/pypi-wheels-gpu.yml +++ b/.github/workflows/pypi-wheels-gpu.yml @@ -6,9 +6,12 @@ on: - published workflow_dispatch: +env: + GPU_DEPS_CACHE_KEY: cibw-deps-gpu-cuda12.6-manylinux_2_34-x86_64-hdf5_1.14.6-tiff_4.6.0-hypre_2.31.0-amrex_25.03-gcc13-nvtx3.1.1-arch75v-80r-89r-nordc-noeb-nofort-nompicxx-compressall-v17 + jobs: - build_gpu_wheels: - name: Build CUDA GPU wheels + build_core_and_cp39: + name: Build CUDA C++ core & cp39 GPU wheel runs-on: ubuntu-latest steps: @@ -21,8 +24,6 @@ jobs: - name: Extract version from tag id: version run: | - # For release events, GITHUB_REF_NAME is the tag (e.g. v4.0.2). - # For workflow_dispatch, fall back to git describe. if [[ "$GITHUB_REF_NAME" == v* ]]; then VERSION="${GITHUB_REF_NAME#v}" else @@ -34,48 +35,55 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: "3.x" + python-version: "3.12" - name: Install cibuildwheel run: python -m pip install cibuildwheel==2.22.0 - # Cache the compiled GPU dependencies (HDF5, libtiff, HYPRE+CUDA, AMReX+CUDA) - # These take ~15-20 minutes to build from source with CUDA support. - - name: Cache native GPU dependencies + - name: Restore native GPU dependencies cache + id: deps-cache + uses: actions/cache/restore@v4 + with: + path: /tmp/cibw-deps-cache + key: ${{ env.GPU_DEPS_CACHE_KEY }} + + - name: Cache CUDA ccache objects (core + cp39) uses: actions/cache@v4 with: - path: .cibw-deps-cache - key: cibw-deps-gpu-cuda12.6-manylinux_2_34-x86_64-hdf5_1.14.6-tiff_4.6.0-hypre_2.31.0-amrex_25.03-gcc13-nvtx3.1.1-arch75-80-89-noeb-nofort-nompicxx-v13 + path: /tmp/cibw-ccache + key: ccache-gpu-nordc-cuda12.6-cp39-${{ github.sha }} + restore-keys: | + ccache-gpu-nordc-cuda12.6-cp39- - - name: Build GPU wheels + - name: Build cp39 GPU wheel and populate CUDA core ccache run: python -m cibuildwheel --output-dir wheelhouse env: - CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*" + CIBW_BUILD: "cp39-*" CIBW_SKIP: "*musllinux* *i686*" CIBW_ARCHS_LINUX: "x86_64" - - # Use NVIDIA's CUDA-enabled manylinux image (CUDA 12.6, AlmaLinux 8) - # This provides nvcc, CUDA runtime, and cuBLAS/cuSPARSE out of the box. CIBW_MANYLINUX_X86_64_IMAGE: sameli/manylinux_2_34_x86_64_cuda_12.6 - # Build all dependencies with CUDA support. - # HDF5 and libtiff are CPU-only (no GPU path needed). - # HYPRE is built with --with-cuda for GPU-accelerated solves. - # AMReX is built with -DAMReX_GPU_BACKEND=CUDA for device kernels. CIBW_BEFORE_ALL_LINUX: > + set -e && + export CCACHE_DISABLE=1 && dnf install -y epel-release && dnf --enablerepo=crb install -y - openmpi-devel gcc-c++ wget git + openmpi-devel gcc-c++ wget git xz zlib-devel libjpeg-turbo-devel python3-pip gcc-toolset-13 gcc-toolset-13-gcc gcc-toolset-13-gcc-c++ && + wget -q https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-linux-x86_64.tar.xz -O /tmp/ccache.tar.xz && + tar xf /tmp/ccache.tar.xz -C /usr/bin --strip-components=1 && + rm -f /tmp/ccache.tar.xz && + mkdir -p /host/tmp/cibw-ccache && + chmod -R a+rwX /host/tmp/cibw-ccache && pip3 install "cmake>=3.28,<4" && - export PATH=/opt/rh/gcc-toolset-13/root/usr/bin:/usr/lib64/openmpi/bin:/usr/local/cuda/bin:$PATH && + export PATH=/usr/local/bin:/opt/rh/gcc-toolset-13/root/usr/bin:/usr/lib64/openmpi/bin:/usr/local/cuda/bin:$PATH && export CC=/opt/rh/gcc-toolset-13/root/usr/bin/gcc && export CXX=/opt/rh/gcc-toolset-13/root/usr/bin/g++ && export CUDA_HOME=/usr/local/cuda && - if [ -f /project/.cibw-deps-cache/deps.tar.gz ]; then + if [ -f /host/tmp/cibw-deps-cache/deps.tar.gz ]; then echo "=== Restoring cached GPU dependencies ===" && - tar xzf /project/.cibw-deps-cache/deps.tar.gz -C / ; + tar xzf /host/tmp/cibw-deps-cache/deps.tar.gz -C / ; else echo "=== Building GPU dependencies from source ===" && wget -q https://github.com/HDFGroup/hdf5/releases/download/hdf5_1.14.6/hdf5-1.14.6.tar.gz && @@ -111,7 +119,7 @@ jobs: CC=mpicc CXX=mpicxx CFLAGS="-O2 -fPIC" CXXFLAGS="-O2 -fPIC -DOMPI_SKIP_MPICXX=1" CUDA_HOME=/usr/local/cuda && - sed -i '/^CUDA_ARCH/s/$/ -gencode arch=compute_75,code=compute_75/' config/Makefile.config && + sed -i '/^CUDA_ARCH/s/$/ -gencode arch=compute_75,code=compute_75 -Xfatbin --compress-all/' config/Makefile.config && grep '^CUDA_ARCH' config/Makefile.config && make -j$(nproc) && make install && @@ -123,7 +131,9 @@ jobs: cp -rf NVTX-3.1.1/c/include/nvtx3/. /usr/local/include/nvtx3/ && git clone --depth 1 --branch 25.03 https://github.com/AMReX-Codes/amrex.git /tmp/amrex && sed -i 's|CUDA::nvToolsExt|CUDA::nvtx3|g' /tmp/amrex/Tools/CMake/AMReXParallelBackends.cmake && - sed -i 's|@AMREX_CUDA_ARCHS@|75;80;89|g' /tmp/amrex/Tools/CMake/AMReXConfig.cmake.in && + sed -i 's|set(AMREX_CUDA_ARCHS ${_tmp} CACHE INTERNAL|set(AMREX_CUDA_ARCHS "80-real;89-real;75-virtual" CACHE INTERNAL|' /tmp/amrex/Tools/CMake/AMReXUtils.cmake && + sed -i 's|@AMREX_CUDA_ARCHS@|"80-real;89-real;75-virtual"|g' /tmp/amrex/Tools/CMake/AMReXConfig.cmake.in && + sed -i 's|CUDA_ARCHITECTURES ${AMREX_CUDA_ARCHS})|CUDA_ARCHITECTURES "${AMREX_CUDA_ARCHS}")|' /tmp/amrex/Tools/CMake/AMReXConfig.cmake.in && cmake -S /tmp/amrex -B /tmp/amrex/build -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release @@ -136,6 +146,7 @@ jobs: -DAMReX_PARTICLES=OFF -DAMReX_TINY_PROFILE=ON -DAMReX_GPU_BACKEND=CUDA + -DAMReX_GPU_RDC=OFF '-DAMReX_CUDA_ARCH=75;80;89' -DMPI_CXX_SKIP_MPICXX=ON '-DCMAKE_CXX_FLAGS=-DOMPI_SKIP_MPICXX=1' @@ -145,48 +156,208 @@ jobs: '-DCMAKE_CUDA_FLAGS=-Xfatbin --compress-all' && cmake --build /tmp/amrex/build -j$(nproc) && cmake --install /tmp/amrex/build && - strip --strip-debug /usr/local/lib/libamrex_3d.a /usr/local/lib/libHYPRE.a /usr/local/lib/libhdf5*.a /usr/local/lib/libtiff.a 2>/dev/null || true && - mkdir -p /project/.cibw-deps-cache && - tar czf /project/.cibw-deps-cache/deps.tar.gz /usr/local ; + mkdir -p /host/tmp/cibw-deps-cache && + tar czf /host/tmp/cibw-deps-cache/deps.tar.gz /usr/local && + chmod -R a+rwX /host/tmp/cibw-deps-cache ; fi && - echo "=== Patching installed AMReXConfig.cmake (runs on cache hit AND miss) ===" && - sed -i 's|set(AMREX_CUDA_ARCHS CACHE INTERNAL|set(AMREX_CUDA_ARCHS "75;80;89" CACHE INTERNAL|' /usr/local/lib/cmake/AMReX/AMReXConfig.cmake && - sed -i 's|CUDA_ARCHITECTURES ${AMREX_CUDA_ARCHS})|CUDA_ARCHITECTURES "${AMREX_CUDA_ARCHS}")|' /usr/local/lib/cmake/AMReX/AMReXConfig.cmake && + echo "=== Verified installed AMReXConfig.cmake ===" && + grep -n 'AMREX_CUDA_ARCHS\|AMReX_GPU_RDC' /usr/local/lib/cmake/AMReX/AMReXConfig.cmake + + CIBW_BEFORE_BUILD: > + pip install "cmake>=3.28,<4" && + rm -rf /tmp/oi-build && + sed -i 's/^name = "openimpala"/name = "openimpala-cuda"/' /project/pyproject.toml && + sed -i 's/^ #"nvidia-/ "nvidia-/' /project/pyproject.toml + + CIBW_ENVIRONMENT_LINUX: > + PATH="/usr/local/bin:/opt/rh/gcc-toolset-13/root/usr/bin:/usr/lib64/openmpi/bin:/usr/local/cuda/bin:$PATH" + CC="/opt/rh/gcc-toolset-13/root/usr/bin/gcc" + CXX="/opt/rh/gcc-toolset-13/root/usr/bin/g++" + CUDA_HOME="/usr/local/cuda" + CUDAHOSTCXX="/opt/rh/gcc-toolset-13/root/usr/bin/g++" + CCACHE_DIR="/host/tmp/cibw-ccache" + CCACHE_BASEDIR="/project" + CCACHE_NOHASHDIR="true" + CCACHE_MAXSIZE="4G" + SKBUILD_BUILD_DIR="/tmp/oi-build" + CMAKE_C_COMPILER="mpicc" + CMAKE_CXX_COMPILER="mpicxx" + CMAKE_C_COMPILER_LAUNCHER="ccache" + CMAKE_CXX_COMPILER_LAUNCHER="ccache" + CMAKE_CUDA_COMPILER_LAUNCHER="ccache" + CMAKE_PREFIX_PATH="/usr/local" + CMAKE_GENERATOR="Unix Makefiles" + CMAKE_ARGS="-DGPU_BACKEND=CUDA '-DCMAKE_CUDA_ARCHITECTURES=80-real;89-real;75-virtual' -DCMAKE_CUDA_HOST_COMPILER=/opt/rh/gcc-toolset-13/root/usr/bin/g++ -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_CUDA_COMPILER_LAUNCHER=ccache -DFETCHCONTENT_BASE_DIR=/tmp/fc-deps" + CUDAFLAGS="-Xfatbin --compress-all" + SETUPTOOLS_SCM_PRETEND_VERSION="${{ steps.version.outputs.version }}" + + CIBW_REPAIR_WHEEL_COMMAND_LINUX: > + ccache -s && + chmod -R a+rwX /host/tmp/cibw-ccache && + auditwheel repair --strip -w {dest_dir} {wheel} + --exclude libmpi.so + --exclude libmpi.so.12 + --exclude libmpi.so.40 + --exclude libmpi_cxx.so + --exclude libmpi_cxx.so.1 + --exclude libmpi_cxx.so.40 + --exclude libopen-rte.so + --exclude libopen-rte.so.40 + --exclude libopen-pal.so + --exclude libopen-pal.so.40 + --exclude libmpi_mpifh.so + --exclude libmpi_mpifh.so.40 + --exclude libgomp.so.1 + --exclude libcuda.so + --exclude libcuda.so.1 + --exclude libcudart.so + --exclude libcudart.so.12 + --exclude libcublas.so + --exclude libcublas.so.12 + --exclude libcublasLt.so + --exclude libcublasLt.so.12 + --exclude libcusparse.so + --exclude libcusparse.so.12 + --exclude libcurand.so + --exclude libcurand.so.10 + --exclude libnvJitLink.so + --exclude libnvJitLink.so.12 + + - name: Check GPU dependencies tarball + id: check-deps + if: always() + run: | + if [ -f /tmp/cibw-deps-cache/deps.tar.gz ]; then + ls -lh /tmp/cibw-deps-cache/deps.tar.gz + echo "exists=true" >> "$GITHUB_OUTPUT" + else + echo "exists=false" >> "$GITHUB_OUTPUT" + fi + + - name: Save native GPU dependencies cache + if: always() && steps.deps-cache.outputs.cache-hit != 'true' && steps.check-deps.outputs.exists == 'true' + uses: actions/cache/save@v4 + with: + path: /tmp/cibw-deps-cache + key: ${{ env.GPU_DEPS_CACHE_KEY }} + + - name: Verify host GPU caches populated + run: | + ls -lh /tmp/cibw-deps-cache/deps.tar.gz + du -sh /tmp/cibw-ccache + + - name: Upload cp39 GPU wheel + uses: actions/upload-artifact@v4 + with: + name: cibw-wheels-gpu-part-cp39 + path: ./wheelhouse/*.whl + retention-days: 1 + + build_matrix_wheels: + name: Build ${{ matrix.py }} CUDA GPU wheel + needs: build_core_and_cp39 + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + py: [cp310, cp311, cp312, cp313] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + fetch-depth: 0 + + - name: Extract version from tag + id: version + run: | + if [[ "$GITHUB_REF_NAME" == v* ]]; then + VERSION="${GITHUB_REF_NAME#v}" + else + VERSION="$(git describe --tags --abbrev=0 | sed 's/^v//')" + fi + echo "version=${VERSION}" >> "$GITHUB_OUTPUT" + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install cibuildwheel + run: python -m pip install cibuildwheel==2.22.0 + + - name: Restore native GPU dependencies cache + uses: actions/cache/restore@v4 + with: + path: /tmp/cibw-deps-cache + key: ${{ env.GPU_DEPS_CACHE_KEY }} + + - name: Cache CUDA ccache objects (${{ matrix.py }}) + uses: actions/cache@v4 + with: + path: /tmp/cibw-ccache + key: ccache-gpu-nordc-cuda12.6-${{ matrix.py }}-${{ github.sha }} + restore-keys: | + ccache-gpu-nordc-cuda12.6-cp39-${{ github.sha }} + ccache-gpu-nordc-cuda12.6-${{ matrix.py }}- + ccache-gpu-nordc-cuda12.6-cp39- + + - name: Build ${{ matrix.py }} GPU wheel + run: python -m cibuildwheel --output-dir wheelhouse + env: + CIBW_BUILD: "${{ matrix.py }}-*" + CIBW_SKIP: "*musllinux* *i686*" + CIBW_ARCHS_LINUX: "x86_64" + CIBW_MANYLINUX_X86_64_IMAGE: sameli/manylinux_2_34_x86_64_cuda_12.6 + + CIBW_BEFORE_ALL_LINUX: > + set -e && + dnf install -y epel-release && + dnf --enablerepo=crb install -y + openmpi-devel gcc-c++ wget git xz + zlib-devel libjpeg-turbo-devel python3-pip + gcc-toolset-13 gcc-toolset-13-gcc gcc-toolset-13-gcc-c++ && + tar xzf /host/tmp/cibw-deps-cache/deps.tar.gz -C / && + wget -q https://github.com/ccache/ccache/releases/download/v4.10.2/ccache-4.10.2-linux-x86_64.tar.xz -O /tmp/ccache.tar.xz && + tar xf /tmp/ccache.tar.xz -C /usr/bin --strip-components=1 && + rm -f /tmp/ccache.tar.xz && + mkdir -p /host/tmp/cibw-ccache && + chmod -R a+rwX /host/tmp/cibw-ccache && + pip3 install "cmake>=3.28,<4" && grep -n 'AMREX_CUDA_ARCHS' /usr/local/lib/cmake/AMReX/AMReXConfig.cmake - # Rename the package to openimpala-cuda and uncomment the nvidia-*-cu12 - # runtime deps (kept commented in pyproject.toml so they don't pollute - # the CPU wheel). auditwheel --exclude drops the CUDA .so's from the - # wheel payload, so without these PyPI deps the wheel breaks on any - # machine that doesn't already have the CUDA toolkit installed. - # The import name stays 'openimpala' — only the PyPI distribution name changes. CIBW_BEFORE_BUILD: > pip install "cmake>=3.28,<4" && + rm -rf /tmp/oi-build && sed -i 's/^name = "openimpala"/name = "openimpala-cuda"/' /project/pyproject.toml && sed -i 's/^ #"nvidia-/ "nvidia-/' /project/pyproject.toml - # Point to MPI, CUDA, and our compiled GPU dependencies. CIBW_ENVIRONMENT_LINUX: > - PATH="/opt/rh/gcc-toolset-13/root/usr/bin:/usr/lib64/openmpi/bin:/usr/local/cuda/bin:$PATH" + PATH="/usr/local/bin:/opt/rh/gcc-toolset-13/root/usr/bin:/usr/lib64/openmpi/bin:/usr/local/cuda/bin:$PATH" CC="/opt/rh/gcc-toolset-13/root/usr/bin/gcc" CXX="/opt/rh/gcc-toolset-13/root/usr/bin/g++" CUDA_HOME="/usr/local/cuda" CUDAHOSTCXX="/opt/rh/gcc-toolset-13/root/usr/bin/g++" + CCACHE_DIR="/host/tmp/cibw-ccache" + CCACHE_BASEDIR="/project" + CCACHE_NOHASHDIR="true" + CCACHE_MAXSIZE="4G" + SKBUILD_BUILD_DIR="/tmp/oi-build" CMAKE_C_COMPILER="mpicc" CMAKE_CXX_COMPILER="mpicxx" + CMAKE_C_COMPILER_LAUNCHER="ccache" + CMAKE_CXX_COMPILER_LAUNCHER="ccache" + CMAKE_CUDA_COMPILER_LAUNCHER="ccache" CMAKE_PREFIX_PATH="/usr/local" CMAKE_GENERATOR="Unix Makefiles" - CMAKE_ARGS="-DGPU_BACKEND=CUDA '-DCMAKE_CUDA_ARCHITECTURES=80-real;89-real;75-virtual' -DCMAKE_CUDA_HOST_COMPILER=/opt/rh/gcc-toolset-13/root/usr/bin/g++" + CMAKE_ARGS="-DGPU_BACKEND=CUDA '-DCMAKE_CUDA_ARCHITECTURES=80-real;89-real;75-virtual' -DCMAKE_CUDA_HOST_COMPILER=/opt/rh/gcc-toolset-13/root/usr/bin/g++ -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_CUDA_COMPILER_LAUNCHER=ccache -DFETCHCONTENT_BASE_DIR=/tmp/fc-deps" CUDAFLAGS="-Xfatbin --compress-all" SETUPTOOLS_SCM_PRETEND_VERSION="${{ steps.version.outputs.version }}" - # Vendor libraries but exclude host-specific MPI, OpenMP, - # and CUDA runtime libraries (pulled via nvidia-*-cu12 PyPI wheels). - # auditwheel --strip strips both vendored libs AND the main _core.so — - # combined with AMReX_EB=OFF and the 2 SASS + 1 PTX arch target - # (sm_80 + sm_89 native SASS, compute_75 PTX for T4/H100), this keeps - # the wheel well under PyPI's 320 MiB ceiling. CIBW_REPAIR_WHEEL_COMMAND_LINUX: > + ccache -s && + chmod -R a+rwX /host/tmp/cibw-ccache && auditwheel repair --strip -w {dest_dir} {wheel} --exclude libmpi.so --exclude libmpi.so.12 @@ -216,7 +387,45 @@ jobs: --exclude libnvJitLink.so --exclude libnvJitLink.so.12 - - name: Upload wheels as artifacts + - name: Upload ${{ matrix.py }} GPU wheel + uses: actions/upload-artifact@v4 + with: + name: cibw-wheels-gpu-part-${{ matrix.py }} + path: ./wheelhouse/*.whl + retention-days: 1 + + bundle_gpu_wheels: + name: Bundle & verify CUDA GPU wheels + needs: [build_core_and_cp39, build_matrix_wheels] + runs-on: ubuntu-latest + + steps: + - name: Download all GPU wheel parts + uses: actions/download-artifact@v4 + with: + pattern: cibw-wheels-gpu-part-* + merge-multiple: true + path: wheelhouse/ + + - name: Verify complete GPU wheelhouse and PyPI 320 MB limit + run: | + ls -lh wheelhouse/ + COUNT=$(ls -1 wheelhouse/*.whl | wc -l) + if [ "$COUNT" -ne 5 ]; then + echo "::error::Expected 5 GPU wheels (cp39..cp313), found $COUNT" + exit 1 + fi + MAX_BYTES=315000000 + for whl in wheelhouse/*.whl; do + SZ=$(stat -c%s "$whl") + echo "$whl: $SZ bytes ($((SZ / 1000000)) MB)" + if [ "$SZ" -gt "$MAX_BYTES" ]; then + echo "::error::Wheel $whl ($SZ bytes) exceeds PyPI 320 MB limit" + exit 1 + fi + done + + - name: Upload unified GPU wheelhouse artifact uses: actions/upload-artifact@v4 with: name: cibw-wheels-gpu @@ -224,7 +433,7 @@ jobs: publish_to_pypi: name: Publish GPU wheels to PyPI (openimpala-cuda) - needs: build_gpu_wheels + needs: bundle_gpu_wheels runs-on: ubuntu-latest # Only publish on release; workflow_dispatch leaves the artifact for manual # inspection without touching PyPI. diff --git a/CMakeLists.txt b/CMakeLists.txt index 3006522..edbe16e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -44,6 +44,29 @@ else() message(STATUS "Version from Git tag: ${_detected_version}") endif() +option(OPENIMPALA_PURE_PYTHON + "Install only the pure-Python openimpala package without compiling the C++ _core extension" + OFF +) + +if(OPENIMPALA_PURE_PYTHON) + project(OpenImpala + VERSION ${_detected_version} + LANGUAGES NONE + DESCRIPTION "Image-based simulation of transport properties in porous media" + ) + message(STATUS "OPENIMPALA_PURE_PYTHON=ON: installing pure-Python package only") + add_custom_target(_core) + file(GLOB _OPENIMPALA_PY_FILES CONFIGURE_DEPENDS + "${CMAKE_CURRENT_SOURCE_DIR}/python/openimpala/*.py" + ) + install(FILES ${_OPENIMPALA_PY_FILES} + DESTINATION openimpala + COMPONENT python + ) + return() +endif() + project(OpenImpala VERSION ${_detected_version} LANGUAGES C CXX diff --git a/README.md b/README.md index 92e9e12..bae1a6b 100644 --- a/README.md +++ b/README.md @@ -47,13 +47,15 @@ with oi.Session(): ### Python (recommended) ```bash -pip install openimpala # CPU + optional CuPy GPU acceleration +pip install openimpala # Linux x86_64 AMReX/HYPRE wheel + universal pure-Python fallback pip install openimpala-cuda # compiled HYPRE/AMReX CUDA wheel (Linux x86_64) ``` -OpenImpala uses MPI for distributed parallelism — install an MPI runtime -(`libopenmpi-dev`, `openmpi`, `brew install open-mpi`, or -`conda install -c conda-forge openmpi`) before `pip install`. See +On Linux `x86_64`, `openimpala` installs pre-built AMReX/HYPRE C++ bindings — +install an MPI runtime (`libopenmpi-dev`, `openmpi`, or +`conda install -c conda-forge openmpi`) to enable multi-rank C++ execution. On +macOS, Windows, and ARM64 (or when MPI is absent), `openimpala` automatically +uses its pure-Python SciPy/CuPy solver with the same API. See [Getting Started](https://base-laboratory.github.io/OpenImpala/getting-started.html) for full details. diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt index 909e46e..7262846 100644 --- a/python/CMakeLists.txt +++ b/python/CMakeLists.txt @@ -35,13 +35,14 @@ pybind11_add_module(_core ${BINDING_SOURCES}) # that require compilation by nvcc. if(GPU_BACKEND STREQUAL "CUDA") set_source_files_properties(${BINDING_SOURCES} PROPERTIES LANGUAGE CUDA) - # AMReX's static library contains relocatable device code (RDC). The _core - # shared library must run CUDA's device linker to resolve __cudaRegister* - # symbols from AMReX and HYPRE device objects. - set_target_properties(_core PROPERTIES - CUDA_SEPARABLE_COMPILATION ON - CUDA_RESOLVE_DEVICE_SYMBOLS ON - ) + if(AMReX_GPU_RDC) + # When AMReX is built with relocatable device code (RDC), _core must + # run CUDA's device linker to resolve __cudaRegister* device symbols. + set_target_properties(_core PROPERTIES + CUDA_SEPARABLE_COMPILATION ON + CUDA_RESOLVE_DEVICE_SYMBOLS ON + ) + endif() endif() target_link_libraries(_core PRIVATE @@ -145,6 +146,8 @@ if(BUILD_TESTING) "${PYTHON_TEST_DIR}/test_tortuosity.py") openimpala_add_pytest(pytest_plane_flux_diagnostic "${PYTHON_TEST_DIR}/test_plane_flux_diagnostic.py") + openimpala_add_pytest(pytest_v460_features + "${PYTHON_TEST_DIR}/test_v460_features.py") message(STATUS "Python tests registered with CTest (label: python)") else() diff --git a/python/bindings/VoxelImage.H b/python/bindings/VoxelImage.H index ecc967d..ec963dd 100644 --- a/python/bindings/VoxelImage.H +++ b/python/bindings/VoxelImage.H @@ -1,5 +1,5 @@ /** @file VoxelImage.H - * @brief Opaque container for AMReX grid objects, exposed to Python via pybind11. + * @brief Opaque container for AMReX grid objects and field-export helpers for pybind11. * * Encapsulates the Geometry, BoxArray, DistributionMapping, and iMultiFab * so that Python users never need to interact with AMReX types directly. @@ -8,14 +8,32 @@ #ifndef OPENIMPALA_VOXEL_IMAGE_H #define OPENIMPALA_VOXEL_IMAGE_H +#include +#include +#include +#include #include +#include + +#include +#include #include #include #include #include +#include +#include +#include +#include +#include +#include #include +#ifdef AMREX_USE_GPU +#include +#endif + namespace OpenImpala { /** @brief Opaque handle that bundles AMReX grid infrastructure for a 3-D voxel image. @@ -30,6 +48,188 @@ struct VoxelImage { std::shared_ptr mf; }; +/** @brief Gather a 3-D AMReX MultiFab component into a C-contiguous (nz, ny, nx) float64 NumPy + * array. + * + * Safe across CPU, OpenMP, CUDA device memory, and multi-rank MPI decompositions. + */ +inline pybind11::array_t multifab_to_numpy(const amrex::MultiFab& mf, + const amrex::Geometry& geom, int comp = 0) { + const amrex::Box& domain = geom.Domain(); + const int lo_x = domain.smallEnd(0); + const int lo_y = domain.smallEnd(1); + const int lo_z = domain.smallEnd(2); + const int nx = domain.length(0); + const int ny = domain.length(1); + const int nz = domain.length(2); + const std::size_t total = + static_cast(nx) * static_cast(ny) * static_cast(nz); + + pybind11::array_t out({static_cast(nz), + static_cast(ny), + static_cast(nx)}); + auto* host_buf = static_cast(out.request().ptr); + if (total == 0) { + return out; + } + std::memset(host_buf, 0, total * sizeof(double)); + + for (amrex::MFIter mfi(mf); mfi.isValid(); ++mfi) { + const amrex::Box bx = mfi.validbox() & domain; + if (!bx.ok()) { + continue; + } + const auto arr = mf.const_array(mfi, comp); + const auto lo = amrex::lbound(bx); + const int bx_nx = bx.length(0); + const int bx_ny = bx.length(1); + const int bx_nz = bx.length(2); + const std::size_t bx_pts = static_cast(bx.numPts()); + +#ifdef AMREX_USE_GPU + amrex::Gpu::DeviceVector d_tmp(bx_pts); + double* dst_ptr = d_tmp.data(); +#else + std::vector h_tmp(bx_pts); + double* dst_ptr = h_tmp.data(); +#endif + + amrex::ParallelFor(bx, [=] AMREX_GPU_DEVICE(int i, int j, int k) noexcept { + const std::size_t lin = + (static_cast(k - lo.z) * static_cast(bx_ny) + + static_cast(j - lo.y)) * + static_cast(bx_nx) + + static_cast(i - lo.x); + dst_ptr[lin] = static_cast(arr(i, j, k)); + }); + +#ifdef AMREX_USE_GPU + std::vector h_tmp(bx_pts); + amrex::Gpu::copy(amrex::Gpu::deviceToHost, d_tmp.begin(), d_tmp.end(), h_tmp.begin()); +#endif + + for (int k = 0; k < bx_nz; ++k) { + for (int j = 0; j < bx_ny; ++j) { + const std::size_t src_row = + (static_cast(k) * static_cast(bx_ny) + + static_cast(j)) * + static_cast(bx_nx); + const std::size_t dst_row = + (static_cast(lo.z + k - lo_z) * static_cast(ny) + + static_cast(lo.y + j - lo_y)) * + static_cast(nx) + + static_cast(lo.x - lo_x); + std::memcpy(&host_buf[dst_row], &h_tmp[src_row], + static_cast(bx_nx) * sizeof(double)); + } + } + } + + if (amrex::ParallelDescriptor::NProcs() > 1) { + constexpr std::size_t max_chunk = 1ULL << 29; + std::size_t offset = 0; + while (offset < total) { + const std::size_t chunk = std::min(max_chunk, total - offset); + amrex::ParallelAllReduce::Sum(host_buf + offset, static_cast(chunk), + amrex::ParallelContext::CommunicatorSub()); + offset += chunk; + } + } + + return out; +} + +/** @brief Gather a 3-D AMReX iMultiFab component into a C-contiguous (nz, ny, nx) int32 NumPy + * array. + * + * Safe across CPU, OpenMP, CUDA device memory, and multi-rank MPI decompositions. + */ +inline pybind11::array_t +imultifab_to_numpy(const amrex::iMultiFab& mf, const amrex::Geometry& geom, int comp = 0) { + const amrex::Box& domain = geom.Domain(); + const int lo_x = domain.smallEnd(0); + const int lo_y = domain.smallEnd(1); + const int lo_z = domain.smallEnd(2); + const int nx = domain.length(0); + const int ny = domain.length(1); + const int nz = domain.length(2); + const std::size_t total = + static_cast(nx) * static_cast(ny) * static_cast(nz); + + pybind11::array_t out({static_cast(nz), + static_cast(ny), + static_cast(nx)}); + auto* host_buf = static_cast(out.request().ptr); + if (total == 0) { + return out; + } + std::memset(host_buf, 0, total * sizeof(std::int32_t)); + + for (amrex::MFIter mfi(mf); mfi.isValid(); ++mfi) { + const amrex::Box bx = mfi.validbox() & domain; + if (!bx.ok()) { + continue; + } + const auto arr = mf.const_array(mfi, comp); + const auto lo = amrex::lbound(bx); + const int bx_nx = bx.length(0); + const int bx_ny = bx.length(1); + const int bx_nz = bx.length(2); + const std::size_t bx_pts = static_cast(bx.numPts()); + +#ifdef AMREX_USE_GPU + amrex::Gpu::DeviceVector d_tmp(bx_pts); + std::int32_t* dst_ptr = d_tmp.data(); +#else + std::vector h_tmp(bx_pts); + std::int32_t* dst_ptr = h_tmp.data(); +#endif + + amrex::ParallelFor(bx, [=] AMREX_GPU_DEVICE(int i, int j, int k) noexcept { + const std::size_t lin = + (static_cast(k - lo.z) * static_cast(bx_ny) + + static_cast(j - lo.y)) * + static_cast(bx_nx) + + static_cast(i - lo.x); + dst_ptr[lin] = static_cast(arr(i, j, k)); + }); + +#ifdef AMREX_USE_GPU + std::vector h_tmp(bx_pts); + amrex::Gpu::copy(amrex::Gpu::deviceToHost, d_tmp.begin(), d_tmp.end(), h_tmp.begin()); +#endif + + for (int k = 0; k < bx_nz; ++k) { + for (int j = 0; j < bx_ny; ++j) { + const std::size_t src_row = + (static_cast(k) * static_cast(bx_ny) + + static_cast(j)) * + static_cast(bx_nx); + const std::size_t dst_row = + (static_cast(lo.z + k - lo_z) * static_cast(ny) + + static_cast(lo.y + j - lo_y)) * + static_cast(nx) + + static_cast(lo.x - lo_x); + std::memcpy(&host_buf[dst_row], &h_tmp[src_row], + static_cast(bx_nx) * sizeof(std::int32_t)); + } + } + } + + if (amrex::ParallelDescriptor::NProcs() > 1) { + constexpr std::size_t max_chunk = 1ULL << 29; + std::size_t offset = 0; + while (offset < total) { + const std::size_t chunk = std::min(max_chunk, total - offset); + amrex::ParallelAllReduce::Sum(host_buf + offset, static_cast(chunk), + amrex::ParallelContext::CommunicatorSub()); + offset += chunk; + } + } + + return out; +} + } // namespace OpenImpala #endif // OPENIMPALA_VOXEL_IMAGE_H diff --git a/python/bindings/module.cpp b/python/bindings/module.cpp index 2553f3e..6dabcce 100644 --- a/python/bindings/module.cpp +++ b/python/bindings/module.cpp @@ -5,13 +5,15 @@ * the VoxelImage opaque handle, and delegates to per-subsystem init functions. */ +#include #include #include +#include #include #include -#include #include +#include #include #include @@ -51,10 +53,9 @@ void init_config(py::module_& m); // ========================================================================= static void init_amrex() { if (!amrex::Initialized()) { - // Initialise with ParmParse defaults that play nicely with EB on - // smaller GPUs (T4 on Colab has ~15 GB and AMReX's default arena - // tries to grab most of it upfront; with EB metadata the - // preallocation can OOM). Use lazy allocation instead. + // Initialise with ParmParse defaults that play nicely with smaller GPUs + // (T4 on Colab has ~15 GB and AMReX's default arena tries to grab most + // of it upfront). Use lazy allocation instead. std::vector argv_storage = { "openimpala", "amrex.the_arena_init_size=0", @@ -167,13 +168,17 @@ static py::dict build_info() { // ========================================================================= static std::shared_ptr voxelimage_from_numpy(py::array_t arr, - int max_grid_size) { + int max_grid_size, double dx, double dy, double dz, + std::array periodic) { py::buffer_info buf = arr.request(); if (buf.ndim != 3) { throw std::runtime_error("Input must be a 3-D NumPy array, got ndim=" + std::to_string(buf.ndim)); } + if (dx <= 0.0 || dy <= 0.0 || dz <= 0.0) { + throw std::invalid_argument("Voxel sizes (dx, dy, dz) must all be strictly positive."); + } // NumPy C-contiguous arrays are shaped (Z, Y, X) int nz = static_cast(buf.shape[0]); @@ -181,9 +186,10 @@ voxelimage_from_numpy(py::array_t(buf.shape[2]); amrex::Box domain(amrex::IntVect(0, 0, 0), amrex::IntVect(nx - 1, ny - 1, nz - 1)); - amrex::RealBox rb({0.0, 0.0, 0.0}, - {static_cast(nx), static_cast(ny), static_cast(nz)}); - amrex::Array is_periodic{0, 0, 0}; + amrex::RealBox rb({0.0, 0.0, 0.0}, {static_cast(nx) * dx, static_cast(ny) * dy, + static_cast(nz) * dz}); + amrex::Array is_periodic{periodic[0] ? 1 : 0, periodic[1] ? 1 : 0, + periodic[2] ? 1 : 0}; auto img = std::make_shared(); img->geom.define(domain, &rb, amrex::CoordSys::cartesian, is_periodic.data()); @@ -236,6 +242,44 @@ voxelimage_from_numpy(py::array_t +voxelimage_with_voxel_size(std::shared_ptr src, double dx, double dy, + double dz, std::array periodic) { + if (!src || !src->mf) { + throw std::runtime_error("Cannot update voxel_size on an empty VoxelImage."); + } + if (dx <= 0.0 || dy <= 0.0 || dz <= 0.0) { + throw std::invalid_argument("Voxel sizes (dx, dy, dz) must all be strictly positive."); + } + + const amrex::Box& domain = src->geom.Domain(); + const int nx = domain.length(0); + const int ny = domain.length(1); + const int nz = domain.length(2); + + amrex::RealBox rb({0.0, 0.0, 0.0}, {static_cast(nx) * dx, static_cast(ny) * dy, + static_cast(nz) * dz}); + amrex::Array is_periodic{periodic[0] ? 1 : 0, periodic[1] ? 1 : 0, + periodic[2] ? 1 : 0}; + + auto img = std::make_shared(); + img->geom.define(domain, &rb, amrex::CoordSys::cartesian, is_periodic.data()); + img->ba = src->ba; + img->dm = src->dm; + + const bool same_periodicity = (src->geom.isPeriodic(0) == periodic[0]) && + (src->geom.isPeriodic(1) == periodic[1]) && + (src->geom.isPeriodic(2) == periodic[2]); + if (same_periodicity) { + img->mf = src->mf; + } else { + img->mf = std::make_shared(img->ba, img->dm, 1, 1); + amrex::Copy(*(img->mf), *(src->mf), 0, 0, 1, 0); + img->mf->FillBoundary(img->geom.periodicity()); + } + return img; +} + // ========================================================================= // PYBIND11_MODULE // ========================================================================= @@ -265,8 +309,62 @@ PYBIND11_MODULE(_core, m) { "one from ``read_image()``. Pass to solver functions directly.") .def_static("from_numpy", &voxelimage_from_numpy, py::arg("arr"), - py::arg("max_grid_size") = 32, - "Construct a VoxelImage from a 3-D int32 NumPy array (Z, Y, X order).") + py::arg("max_grid_size") = 32, py::arg("dx") = 1.0, py::arg("dy") = 1.0, + py::arg("dz") = 1.0, + py::arg("periodic") = std::array{false, false, false}, + "Construct a VoxelImage from a 3-D int32 NumPy array (Z, Y, X order) with " + "optional physical cell sizes (dx, dy, dz) and periodicity flags.") + + .def("with_voxel_size", &voxelimage_with_voxel_size, py::arg("dx") = 1.0, + py::arg("dy") = 1.0, py::arg("dz") = 1.0, + py::arg("periodic") = std::array{false, false, false}, + "Return a VoxelImage view sharing the underlying voxel data with updated " + "physical cell sizes (dx, dy, dz).") + + .def_property_readonly( + "shape", + [](const OpenImpala::VoxelImage& v) { + if (!v.mf) { + return py::make_tuple(0, 0, 0); + } + const auto& dom = v.geom.Domain(); + return py::make_tuple(dom.length(2), dom.length(1), dom.length(0)); + }, + "3-D shape in NumPy (nz, ny, nx) order.") + + .def_property_readonly( + "voxel_size", + [](const OpenImpala::VoxelImage& v) { + if (!v.mf) { + return py::make_tuple(1.0, 1.0, 1.0); + } + const amrex::Real* cs = v.geom.CellSize(); + return py::make_tuple(static_cast(cs[2]), static_cast(cs[1]), + static_cast(cs[0])); + }, + "Physical voxel spacing in NumPy (dz, dy, dx) order.") + + .def_property_readonly( + "cell_size_xyz", + [](const OpenImpala::VoxelImage& v) { + if (!v.mf) { + return py::make_tuple(1.0, 1.0, 1.0); + } + const amrex::Real* cs = v.geom.CellSize(); + return py::make_tuple(static_cast(cs[0]), static_cast(cs[1]), + static_cast(cs[2])); + }, + "Physical voxel spacing in AMReX (dx, dy, dz) order.") + + .def( + "to_numpy", + [](const OpenImpala::VoxelImage& v) { + if (!v.mf) { + throw std::runtime_error("Cannot export empty VoxelImage to NumPy."); + } + return OpenImpala::imultifab_to_numpy(*(v.mf), v.geom, 0); + }, + "Export the 3-D phase array to a C-contiguous int32 NumPy array (nz, ny, nx).") .def("__repr__", [](const OpenImpala::VoxelImage& v) { if (!v.mf) @@ -282,10 +380,10 @@ PYBIND11_MODULE(_core, m) { // I/O readers init_io(m); - // Lightweight property calculators (VolumeFraction, PercolationCheck) + // Microstructural property calculators init_props(m); - // Heavy solvers (TortuosityHypre, TortuosityDirect, EffectiveDiffusivityHypre) + // Heavy solvers (TortuosityHypre, TortuosityMLMG, TortuosityDirect, EffectiveDiffusivityHypre) init_solvers(m); // Configuration and output helpers (PhysicsConfig, ResultsJSON, CathodeWrite) diff --git a/python/bindings/props.cpp b/python/bindings/props.cpp index 5d54282..ee94f64 100644 --- a/python/bindings/props.cpp +++ b/python/bindings/props.cpp @@ -1,16 +1,29 @@ /** @file props.cpp - * @brief pybind11 bindings for lightweight property calculators. + * @brief pybind11 bindings for microstructural property calculators and REV studies. * * Accepts VoxelImage handles — no pyamrex dependency. */ +#include +#include #include +#include +#include +#include +#include #include #include -#include "VolumeFraction.H" +#include + +#include "ConnectedComponents.H" +#include "ParticleSizeDistribution.H" #include "PercolationCheck.H" +#include "REVStudy.H" +#include "SpecificSurfaceArea.H" +#include "ThroughThicknessProfile.H" +#include "VolumeFraction.H" #include "VoxelImage.H" namespace py = pybind11; @@ -74,4 +87,187 @@ void init_props(py::module_& m) { .def_static("direction_string", &PercolationCheck::directionString, py::arg("dir"), "Convert a Direction enum value to its string label (\"X\", \"Y\", or \"Z\")."); + + // ========================================================================= + // SpecificSurfaceArea + // ========================================================================= + py::class_( + m, "SpecificSurfaceArea", + "Computes interfacial specific surface area between two phases in a VoxelImage.") + + .def(py::init([](std::shared_ptr img, int phase_a, int phase_b, int comp, + int boundary_padding) { + return new SpecificSurfaceArea(img->geom, *(img->mf), phase_a, phase_b, comp, + boundary_padding); + }), + py::arg("img"), py::arg("phase_a") = 0, py::arg("phase_b") = 1, py::arg("comp") = 0, + py::arg("boundary_padding") = 0, py::keep_alive<1, 2>(), + "Create a specific surface area calculator between *phase_a* and *phase_b*.") + + .def( + "value", + [](const SpecificSurfaceArea& self, bool local) { + long long face_count = 0; + long long total_count = 0; + self.value(face_count, total_count, local); + return py::make_tuple(face_count, total_count); + }, + py::arg("local") = false, "Return (face_count, total_count).") + + .def( + "direction_face_counts", + [](const SpecificSurfaceArea& self, bool local) { + amrex::Array dir_faces{}; + long long total_count = 0; + self.directionFaceCounts(dir_faces, total_count, local); + return py::make_tuple(py::make_tuple(dir_faces[0], dir_faces[1], dir_faces[2]), + total_count); + }, + py::arg("local") = false, "Return ((faces_x, faces_y, faces_z), total_count).") + + .def("value_ssa", &SpecificSurfaceArea::value_ssa, py::arg("local") = false, + "Raw voxel-unit SSA = face_count / total_count.") + + .def("value_corrected", &SpecificSurfaceArea::value_corrected, py::arg("local") = false, + "Cauchy-Crofton (2/3) corrected voxel-unit SSA.") + + .def("value_physical", &SpecificSurfaceArea::value_physical, py::arg("local") = false, + "Raw physical SSA accounting for (dx, dy, dz) cell sizes [1/length].") + + .def("value_physical_corrected", &SpecificSurfaceArea::value_physical_corrected, + py::arg("local") = false, + "Cauchy-Crofton (2/3) corrected physical SSA accounting for (dx, dy, dz) [1/length]."); + + // ========================================================================= + // ConnectedComponents + // ========================================================================= + py::class_( + m, "ConnectedComponents", + "Labels 6-connected components of a target phase via parallel flood-fill.") + + .def(py::init([](std::shared_ptr img, int phase_id, int verbose) { + return new ConnectedComponents(img->geom, img->ba, img->dm, *(img->mf), phase_id, + verbose); + }), + py::arg("img"), py::arg("phase_id") = 1, py::arg("verbose") = 0, + py::keep_alive<1, 2>(), "Run 6-connected component labeling for *phase_id*.") + + .def_property_readonly("num_components", &ConnectedComponents::numComponents, + "Number of connected components found.") + + .def_property_readonly("component_volumes", &ConnectedComponents::componentVolumes, + "Voxel count of each connected component (1-indexed labels 1..N).") + + .def( + "label_field", + [](const ConnectedComponents& self) { + return OpenImpala::imultifab_to_numpy(self.labelField(), self.getGeometry(), 0); + }, + "Export the 3-D component label field (0 = background, 1..N = component ID) as a " + "C-contiguous int32 NumPy array of shape (nz, ny, nx)."); + + // ========================================================================= + // ParticleSizeDistribution + // ========================================================================= + py::class_( + m, "ParticleSizeDistribution", + "Computes equivalent-sphere radii R = (3V / (4*pi))^(1/3) from connected components.") + + .def(py::init(), py::arg("ccl"), + "Compute particle size distribution from an existing ConnectedComponents object.") + + .def(py::init([](std::shared_ptr img, int phase_id, int verbose) { + ConnectedComponents ccl(img->geom, img->ba, img->dm, *(img->mf), phase_id, + verbose); + return new ParticleSizeDistribution(ccl); + }), + py::arg("img"), py::arg("phase_id") = 1, py::arg("verbose") = 0, + "Run connected component labeling and compute equivalent-sphere radii directly.") + + .def_property_readonly("num_particles", &ParticleSizeDistribution::numParticles, + "Number of discrete particles/components.") + + .def_property_readonly("mean_radius", &ParticleSizeDistribution::meanRadius, + "Mean equivalent-sphere radius in voxel units.") + + .def_property_readonly("radii", &ParticleSizeDistribution::radii, + "Equivalent-sphere radius of each component in voxel units.") + + .def_property_readonly("volumes", &ParticleSizeDistribution::volumes, + "Voxel count of each component."); + + // ========================================================================= + // ThroughThicknessProfile + // ========================================================================= + py::class_( + m, "ThroughThicknessProfile", + "Computes per-slice volume fraction profile along a coordinate direction.") + + .def(py::init([](std::shared_ptr img, int phase_id, OpenImpala::Direction dir, + int comp) { + return new ThroughThicknessProfile(img->geom, *(img->mf), phase_id, dir, comp); + }), + py::arg("img"), py::arg("phase_id") = 1, py::arg("dir") = OpenImpala::Direction::X, + py::arg("comp") = 0, py::keep_alive<1, 2>(), + "Compute slice-by-slice volume fraction of *phase_id* along *dir*.") + + .def_property_readonly("num_slices", &ThroughThicknessProfile::numSlices, + "Number of 1-voxel slices along the chosen direction.") + + .def_property_readonly("volume_fraction_profile", + &ThroughThicknessProfile::volumeFractionProfile, + "List of local volume fractions (one float per slice)."); + + // ========================================================================= + // REV convergence study + // ========================================================================= + m.def( + "run_rev_study", + [](std::shared_ptr img, const std::vector& sizes, int num_samples, + int phase_id, int box_size, OpenImpala::SolverType solver_type, + const std::string& results_path, const std::string& csv_filename, int verbose, + bool write_plotfiles) { + REVConfig cfg; + cfg.sizes = sizes; + cfg.num_samples = num_samples; + cfg.phase_id = phase_id; + cfg.box_size = box_size; + cfg.solver_type = solver_type; + cfg.results_path = std::filesystem::path(results_path); + cfg.csv_filename = csv_filename; + cfg.verbose = verbose; + cfg.write_plotfiles = write_plotfiles; + runREVStudy(img->geom, img->ba, img->dm, *(img->mf), cfg); + amrex::ParallelDescriptor::Barrier(); + + const std::string out_path = (cfg.results_path / cfg.csv_filename).string(); + std::string csv_content; + if (amrex::ParallelDescriptor::IOProcessor()) { + std::ifstream ifs(out_path); + if (ifs) { + std::ostringstream oss; + oss << ifs.rdbuf(); + csv_content = oss.str(); + } + } + if (amrex::ParallelDescriptor::NProcs() > 1) { + int len = static_cast(csv_content.size()); + amrex::ParallelDescriptor::Bcast(&len, 1, + amrex::ParallelDescriptor::IOProcessorNumber()); + if (!amrex::ParallelDescriptor::IOProcessor()) { + csv_content.resize(static_cast(len)); + } + if (len > 0) { + amrex::ParallelDescriptor::Bcast( + csv_content.data(), len, amrex::ParallelDescriptor::IOProcessorNumber()); + } + } + return py::make_tuple(out_path, csv_content); + }, + py::arg("img"), py::arg("sizes"), py::arg("num_samples") = 3, py::arg("phase_id") = 1, + py::arg("box_size") = 32, py::arg("solver_type") = OpenImpala::SolverType::FlexGMRES, + py::arg("results_path") = ".", py::arg("csv_filename") = "rev_study_Deff.csv", + py::arg("verbose") = 0, py::arg("write_plotfiles") = false, + "Run a Representative Elementary Volume (REV) convergence study and return " + "(csv_path, csv_content)."); } diff --git a/python/bindings/solvers.cpp b/python/bindings/solvers.cpp index 429a500..d5c8d2a 100644 --- a/python/bindings/solvers.cpp +++ b/python/bindings/solvers.cpp @@ -4,45 +4,187 @@ * Accepts VoxelImage handles — no pyamrex dependency. */ +#include #include +#include +#include #include #include #include +#include #include #include +#include +#include +#include +#include +#include + +#include "DeffTensor.H" +#include "EffectiveDiffusivityHypre.H" #include "HypreStructSolver.H" +#include "TortuosityDirect.H" #include "TortuosityHypre.H" #include "TortuosityMLMG.H" -#include "TortuosityDirect.H" -#include "EffectiveDiffusivityHypre.H" +#include "VolumeFraction.H" #include "VoxelImage.H" namespace py = pybind11; using namespace OpenImpala; +namespace { + +py::dict compute_effective_diffusivity_tensor(std::shared_ptr img, int phase_id, + OpenImpala::SolverType solver_type, + const std::string& results_path, int verbose, + bool write_plotfile, + const std::map& phase_coeffs, + bool return_chi) { + if (!img || !img->mf) { + throw std::runtime_error("Cannot compute effective diffusivity on an empty VoxelImage."); + } + + // Build a periodic Geometry matching img->geom's index box and physical RealBox + amrex::Array is_periodic{AMREX_D_DECL(1, 1, 1)}; + amrex::Geometry geom_per; + geom_per.define(img->geom.Domain(), &(img->geom.ProbDomain()), amrex::CoordSys::cartesian, + is_periodic.data()); + + // Copy phase data into a periodic iMultiFab so periodic ghost cells are populated + amrex::iMultiFab mf_phase_per(img->ba, img->dm, 1, 1); + amrex::Copy(mf_phase_per, *(img->mf), 0, 0, 1, 0); + mf_phase_per.FillBoundary(geom_per.periodicity()); + + amrex::MultiFab mf_chi_x(img->ba, img->dm, 1, 1); + amrex::MultiFab mf_chi_y(img->ba, img->dm, 1, 1); + amrex::MultiFab mf_chi_z(img->ba, img->dm, 1, 1); + mf_chi_x.setVal(0.0); + mf_chi_y.setVal(0.0); + mf_chi_z.setVal(0.0); + + amrex::iMultiFab active_mask_0g(img->ba, img->dm, 1, 0); + amrex::MultiFab diff_coeff_0g(img->ba, img->dm, 1, 0); + active_mask_0g.setVal(0); + diff_coeff_0g.setVal(0.0); + + const std::array dirs = { + OpenImpala::Direction::X, OpenImpala::Direction::Y, OpenImpala::Direction::Z}; + amrex::MultiFab* chi_ptrs[3] = {&mf_chi_x, &mf_chi_y, &mf_chi_z}; + + std::array dir_converged = {false, false, false}; + std::array dir_iterations = {0, 0, 0}; + std::array dir_residuals = {0.0, 0.0, 0.0}; + long active_cells = 0; + bool empty_active_phase = false; + bool all_converged = true; + + for (int d = 0; d < 3; ++d) { + EffectiveDiffusivityHypre solver(geom_per, img->ba, img->dm, mf_phase_per, phase_id, + dirs[d], solver_type, results_path, verbose, + write_plotfile, phase_coeffs); + + if (d == 0) { + amrex::Copy(active_mask_0g, solver.getActiveMask(), 0, 0, 1, 0); + amrex::Copy(diff_coeff_0g, solver.getDiffCoeff(), 0, 0, 1, 0); + VolumeFraction vf_calc(active_mask_0g, 1, 0); + long long active_ll = 0; + long long total_ll = 0; + vf_calc.value(active_ll, total_ll, false); + active_cells = static_cast(active_ll); + if (active_cells == 0) { + empty_active_phase = true; + dir_converged = {true, true, true}; + break; + } + } + + const bool ok = solver.solve(); + dir_converged[d] = ok && solver.getSolverConverged(); + dir_iterations[d] = solver.getSolverIterations(); + dir_residuals[d] = static_cast(solver.getFinalRelativeResidualNorm()); + + if (!dir_converged[d]) { + all_converged = false; + break; + } + + solver.getChiSolution(*chi_ptrs[d]); + chi_ptrs[d]->FillBoundary(geom_per.periodicity()); + } + + const long total_cells = geom_per.Domain().numPts(); + const double active_vf = + (total_cells > 0) ? static_cast(active_cells) / static_cast(total_cells) + : 0.0; + + py::array_t tensor_arr({static_cast(3), static_cast(3)}); + auto* tensor_ptr = static_cast(tensor_arr.request().ptr); + + if (empty_active_phase) { + for (int i = 0; i < 9; ++i) { + tensor_ptr[i] = 0.0; + } + } else if (all_converged) { + amrex::Real Deff_raw[AMREX_SPACEDIM][AMREX_SPACEDIM]; + OpenImpala::calculateDeffTensor(Deff_raw, mf_chi_x, mf_chi_y, mf_chi_z, active_mask_0g, + geom_per, verbose, &diff_coeff_0g); + for (int r = 0; r < 3; ++r) { + for (int c = 0; c < 3; ++c) { + tensor_ptr[r * 3 + c] = static_cast(Deff_raw[r][c]); + } + } + } else { + for (int i = 0; i < 9; ++i) { + tensor_ptr[i] = std::numeric_limits::quiet_NaN(); + } + } + + py::dict out; + out["tensor"] = tensor_arr; + out["active_volume_fraction"] = active_vf; + out["converged"] = all_converged; + out["dir_converged"] = py::make_tuple(dir_converged[0], dir_converged[1], dir_converged[2]); + out["iterations"] = py::make_tuple(dir_iterations[0], dir_iterations[1], dir_iterations[2]); + out["residuals"] = py::make_tuple(dir_residuals[0], dir_residuals[1], dir_residuals[2]); + + if (return_chi) { + py::dict chi_dict; + chi_dict["x"] = OpenImpala::multifab_to_numpy(mf_chi_x, geom_per, 0); + chi_dict["y"] = OpenImpala::multifab_to_numpy(mf_chi_y, geom_per, 0); + chi_dict["z"] = OpenImpala::multifab_to_numpy(mf_chi_z, geom_per, 0); + out["chi"] = chi_dict; + } + + return out; +} + +} // namespace + void init_solvers(py::module_& m) { // ========================================================================= // TortuosityHypre // ========================================================================= py::class_(m, "TortuosityHypre", "HYPRE-based tortuosity solver. Solves the steady-state diffusion " - "equation on a masked phase and computes tortuosity from the " - "resulting flux.") + "equation on a masked or multi-phase domain and computes " + "tortuosity and effective diffusivity from the resulting flux.") .def(py::init([](std::shared_ptr img, amrex::Real vf, int phase, OpenImpala::Direction dir, TortuosityHypre::SolverType solver_type, const std::string& results_path, amrex::Real vlo, amrex::Real vhi, - int verbose, bool write_plotfile, OpenImpala::PrecondType preconditioner) { + int verbose, bool write_plotfile, OpenImpala::PrecondType preconditioner, + const std::map& phase_coeffs) { return new TortuosityHypre(img->geom, img->ba, img->dm, *(img->mf), vf, phase, dir, solver_type, results_path, vlo, vhi, verbose, - write_plotfile, preconditioner); + write_plotfile, preconditioner, phase_coeffs); }), py::arg("img"), py::arg("vf"), py::arg("phase"), py::arg("dir"), py::arg("solver_type"), py::arg("results_path"), py::arg("vlo") = 0.0, py::arg("vhi") = 1.0, py::arg("verbose") = 0, py::arg("write_plotfile") = false, py::arg("preconditioner") = OpenImpala::PrecondType::SMG, + py::arg("phase_coeffs") = std::map{}, // keep VoxelImage alive while this object lives py::keep_alive<1, 2>()) @@ -67,6 +209,15 @@ void init_solvers(py::module_& m) { "value_raw", [](TortuosityHypre& self, bool refresh) { return self.value(refresh); }, py::arg("refresh") = false, "Return tortuosity (NaN on failure, no exception).") + .def( + "solution_field", + [](const TortuosityHypre& self) { + return OpenImpala::multifab_to_numpy(self.getSolutionField(), self.getGeometry(), + 0); + }, + "Return the solved 3-D steady-state potential field as a float64 NumPy array " + "of shape (nz, ny, nx).") + .def("check_matrix_properties", &TortuosityHypre::checkMatrixProperties, "Verify HYPRE matrix / RHS properties (for debugging).") @@ -76,6 +227,7 @@ void init_solvers(py::module_& m) { .def_property_readonly("iterations", &TortuosityHypre::getSolverIterations) .def_property_readonly("flux_in", &TortuosityHypre::getFluxIn) .def_property_readonly("flux_out", &TortuosityHypre::getFluxOut) + .def_property_readonly("effective_diffusivity", &TortuosityHypre::getEffectiveDiffusivity) .def_property_readonly("active_volume_fraction", &TortuosityHypre::getActiveVolumeFraction) .def_property_readonly("plane_fluxes", &TortuosityHypre::getPlaneFluxes) .def_property_readonly("plane_flux_max_deviation", @@ -95,15 +247,17 @@ void init_solvers(py::module_& m) { .def(py::init([](std::shared_ptr img, amrex::Real vf, int phase, OpenImpala::Direction dir, const std::string& results_path, amrex::Real vlo, amrex::Real vhi, int verbose, bool write_plotfile, - amrex::Real eps, int maxiter, int max_coarsening_level) { + amrex::Real eps, int maxiter, int max_coarsening_level, + const std::map& phase_coeffs) { return new TortuosityMLMG(img->geom, img->ba, img->dm, *(img->mf), vf, phase, dir, results_path, vlo, vhi, verbose, write_plotfile, eps, - maxiter, max_coarsening_level); + maxiter, max_coarsening_level, phase_coeffs); }), py::arg("img"), py::arg("vf"), py::arg("phase"), py::arg("dir"), py::arg("results_path"), py::arg("vlo") = 0.0, py::arg("vhi") = 1.0, py::arg("verbose") = 0, py::arg("write_plotfile") = false, py::arg("eps") = 1.0e-8, - py::arg("maxiter") = 200, py::arg("max_coarsening_level") = 30, py::keep_alive<1, 2>()) + py::arg("maxiter") = 200, py::arg("max_coarsening_level") = 30, + py::arg("phase_coeffs") = std::map{}, py::keep_alive<1, 2>()) .def( "value", @@ -124,15 +278,26 @@ void init_solvers(py::module_& m) { "value_raw", [](TortuosityMLMG& self, bool refresh) { return self.value(refresh); }, py::arg("refresh") = false, "Return tortuosity (NaN on failure, no exception).") + .def( + "solution_field", + [](const TortuosityMLMG& self) { + return OpenImpala::multifab_to_numpy(self.getSolutionField(), self.getGeometry(), + 0); + }, + "Return the solved 3-D steady-state potential field as a float64 NumPy array " + "of shape (nz, ny, nx).") + .def_property_readonly("solver_converged", &TortuosityMLMG::getSolverConverged) .def_property_readonly("residual_norm", &TortuosityMLMG::getFinalRelativeResidualNorm) .def_property_readonly("iterations", &TortuosityMLMG::getSolverIterations) .def_property_readonly("flux_in", &TortuosityMLMG::getFluxIn) .def_property_readonly("flux_out", &TortuosityMLMG::getFluxOut) + .def_property_readonly("effective_diffusivity", &TortuosityMLMG::getEffectiveDiffusivity) .def_property_readonly("active_volume_fraction", &TortuosityMLMG::getActiveVolumeFraction) .def_property_readonly("plane_fluxes", &TortuosityMLMG::getPlaneFluxes) .def_property_readonly("plane_flux_max_deviation", - &TortuosityMLMG::getPlaneFluxMaxDeviation); + &TortuosityMLMG::getPlaneFluxMaxDeviation) + .def_property_readonly("is_multi_phase", &TortuosityMLMG::isMultiPhase); // ========================================================================= // TortuosityDirect @@ -181,13 +346,15 @@ void init_solvers(py::module_& m) { .def(py::init([](std::shared_ptr img, int phase_id, OpenImpala::Direction dir, EffectiveDiffusivityHypre::SolverType solver_type, - const std::string& results_path, int verbose, bool write_plotfile) { + const std::string& results_path, int verbose, bool write_plotfile, + const std::map& phase_coeffs) { return new EffectiveDiffusivityHypre(img->geom, img->ba, img->dm, *(img->mf), phase_id, dir, solver_type, results_path, - verbose, write_plotfile); + verbose, write_plotfile, phase_coeffs); }), py::arg("img"), py::arg("phase_id"), py::arg("dir"), py::arg("solver_type"), py::arg("results_path"), py::arg("verbose") = 1, py::arg("write_plotfile") = false, + py::arg("phase_coeffs") = std::map{}, // keep VoxelImage alive while this object lives py::keep_alive<1, 2>()) @@ -201,4 +368,15 @@ void init_solvers(py::module_& m) { .def_property_readonly("residual_norm", &EffectiveDiffusivityHypre::getFinalRelativeResidualNorm) .def_property_readonly("iterations", &EffectiveDiffusivityHypre::getSolverIterations); + + // ========================================================================= + // Full 3x3 D_eff tensor homogenization helper + // ========================================================================= + m.def("compute_effective_diffusivity_tensor", &compute_effective_diffusivity_tensor, + py::arg("img"), py::arg("phase_id") = 1, + py::arg("solver_type") = OpenImpala::SolverType::FlexGMRES, py::arg("results_path") = ".", + py::arg("verbose") = 0, py::arg("write_plotfile") = false, + py::arg("phase_coeffs") = std::map{}, py::arg("return_chi") = false, + "Solve the 3 periodic homogenization cell problems and assemble the 3x3 effective " + "diffusivity tensor D_eff (in X=0, Y=1, Z=2 order)."); } diff --git a/python/openimpala/__init__.py b/python/openimpala/__init__.py index fa1b538..aeff0b6 100644 --- a/python/openimpala/__init__.py +++ b/python/openimpala/__init__.py @@ -6,7 +6,8 @@ Direct pybind11 wrappers around C++ classes; operates via ``VoxelImage`` handles. * **High-level (general) API** — module-level functions - NumPy-native helpers that set up AMReX objects automatically. + NumPy-native helpers that set up AMReX objects automatically (with automatic + pure-Python SciPy/CuPy fallback on platforms without compiled extensions). Quick-start:: @@ -21,8 +22,7 @@ """ import importlib - -from importlib.metadata import version, PackageNotFoundError +from importlib.metadata import PackageNotFoundError, version try: __version__ = version("openimpala") @@ -34,27 +34,10 @@ def _preload_cuda_libs(): - """Pre-load CUDA shared libs shipped by PyPI nvidia-*-cu12 packages. - - The openimpala-cuda wheel uses ``auditwheel --exclude libcublas.so.12`` - (etc.) to keep the wheel under PyPI's 320 MiB cap, then declares - ``nvidia-cublas-cu12`` and friends as runtime deps. Those wheels install - their .so's under ``site-packages/nvidia//lib/``, which the - dynamic linker does NOT search by default — so loading ``_core.so`` - fails with ``undefined symbol: cublasSetStream_v2`` (and similar) until - the libs are dlopened with RTLD_GLOBAL. - - Same trick as PyTorch / CuPy / JAX. For each lib we try the bare soname - first (so HPC nodes with system CUDA on LD_LIBRARY_PATH win the race), - then fall back to the PyPI bundled path. No-op for pure-Python wheels - where the nvidia/ dir doesn't exist. - - Load order matters: cudart first, cublasLt before cublas (cublas links - against cublasLt at the symbol level). - """ + """Pre-load CUDA shared libs shipped by PyPI nvidia-*-cu12 packages.""" + import ctypes import os import sys - import ctypes if sys.platform != "linux": return @@ -64,12 +47,12 @@ def _preload_cuda_libs(): nvidia_root = os.path.join(site_pkgs, "nvidia") libs = ( - ("libcudart.so.12", "cuda_runtime/lib/libcudart.so.12"), - ("libnvJitLink.so.12", "nvjitlink/lib/libnvJitLink.so.12"), - ("libcublasLt.so.12", "cublas/lib/libcublasLt.so.12"), - ("libcublas.so.12", "cublas/lib/libcublas.so.12"), - ("libcusparse.so.12", "cusparse/lib/libcusparse.so.12"), - ("libcurand.so.10", "curand/lib/libcurand.so.10"), + ("libcudart.so.12", "cuda_runtime/lib/libcudart.so.12"), + ("libnvJitLink.so.12", "nvjitlink/lib/libnvJitLink.so.12"), + ("libcublasLt.so.12", "cublas/lib/libcublasLt.so.12"), + ("libcublas.so.12", "cublas/lib/libcublas.so.12"), + ("libcusparse.so.12", "cusparse/lib/libcusparse.so.12"), + ("libcurand.so.10", "curand/lib/libcurand.so.10"), ) for soname, fallback in libs: @@ -93,35 +76,53 @@ def _preload_cuda_libs(): # Custom exceptions (pure Python — always available) from .exceptions import ( - OpenImpalaError, ConvergenceError, + OpenImpalaError, PercolationError, ) def _load_core(): - """Load the _core C extension. - - Repeated calls are cheap — Python caches the import. - """ + """Load the _core C extension.""" return importlib.import_module("openimpala._core") def __getattr__(name): - """Lazy-load C extension symbols on first access. - - This allows ``from openimpala.cli import _build_parser`` and other - pure-Python imports to succeed without loading the compiled backend. - """ - # Symbols that live in the _core C extension + """Lazy-load C extension and facade symbols on first access.""" _CORE_ATTRS = { - "core", "_core", "VoxelImage", "Direction", "CellType", "RawDataType", - "SolverType", "EffDiffSolverType", "PhysicsType", + "core", + "_core", + "VoxelImage", + "Direction", + "CellType", + "RawDataType", + "SolverType", + "PrecondType", + "EffDiffSolverType", + "PhysicsType", } - # Symbols that live in the facade module _FACADE_ATTRS = { - "volume_fraction", "percolation_check", "tortuosity", "estimate_memory", - "read_image", "build_info", + "volume_fraction", + "percolation_check", + "tortuosity", + "effective_diffusivity", + "specific_surface_area", + "connected_components", + "particle_size_distribution", + "through_thickness_profile", + "rev_study", + "estimate_memory", + "read_image", + "build_info", + "VolumeFractionResult", + "PercolationResult", + "TortuosityResult", + "EffectiveDiffusivityResult", + "SpecificSurfaceAreaResult", + "ConnectedComponentsResult", + "ParticleSizeDistributionResult", + "ThroughThicknessResult", + "REVStudyResult", } if name in _CORE_ATTRS: @@ -131,7 +132,7 @@ def __getattr__(name): raise AttributeError( f"'openimpala.{name}' requires the compiled C++ backend (_core). " f"In pure-Python mode, use the high-level API: " - f"openimpala.volume_fraction(), tortuosity(), etc." + f"openimpala.volume_fraction(), tortuosity(), effective_diffusivity(), etc." ) if name in ("core", "_core"): return _core @@ -139,12 +140,12 @@ def __getattr__(name): if name in _FACADE_ATTRS: from . import facade + return getattr(facade, name) raise AttributeError(f"module 'openimpala' has no attribute {name!r}") -# Explicitly define the public API for IDEs and static analysis __all__ = [ "__version__", "core", @@ -153,6 +154,7 @@ def __getattr__(name): "CellType", "RawDataType", "SolverType", + "PrecondType", "EffDiffSolverType", "PhysicsType", "Session", @@ -162,7 +164,22 @@ def __getattr__(name): "volume_fraction", "percolation_check", "tortuosity", + "effective_diffusivity", + "specific_surface_area", + "connected_components", + "particle_size_distribution", + "through_thickness_profile", + "rev_study", "estimate_memory", "read_image", "build_info", + "VolumeFractionResult", + "PercolationResult", + "TortuosityResult", + "EffectiveDiffusivityResult", + "SpecificSurfaceAreaResult", + "ConnectedComponentsResult", + "ParticleSizeDistributionResult", + "ThroughThicknessResult", + "REVStudyResult", ] diff --git a/python/openimpala/_solver.py b/python/openimpala/_solver.py index 6812cdf..67fa919 100644 --- a/python/openimpala/_solver.py +++ b/python/openimpala/_solver.py @@ -1,19 +1,27 @@ -"""Pure-Python tortuosity solver using sparse matrices (SciPy / CuPy). - -This module provides a drop-in replacement for the C++ HYPRE-based solver, -enabling ``pip install openimpala`` to work without any compiled extensions. -GPU acceleration is available automatically when CuPy is installed. - -The algorithm matches the C++ implementation exactly: - 1. Flood-fill percolation check (6-connected BFS) - 2. 7-point stencil Laplacian with harmonic-mean face coefficients - 3. Dirichlet BCs at inlet/outlet, zero-flux Neumann on sides - 4. Sparse CG solve (CuPy on GPU, SciPy on CPU) - 5. Flux integration for D_eff, then tau = active_vf / D_eff +"""Pure-Python transport and microstructure solvers using NumPy / SciPy (or CuPy). + +This module provides a drop-in pure-Python backend for OpenImpala's high-level API, +enabling ``pip install openimpala`` to work out-of-the-box on macOS, Windows, +Linux ARM64, and new Python versions without requiring AMReX, HYPRE, or MPI. +GPU acceleration is used automatically when CuPy is installed. + +Supported features (matching the C++ backend): + * Volume fraction and 6-connected percolation checks (single- and multi-phase) + * Steady-state tortuosity and effective diffusivity (anisotropic voxels, + multi-phase harmonic-mean conductances, 3-D potential field output) + * Homogenised 3x3 effective diffusivity tensor D_eff (periodic cell problems) + * Specific surface area (voxel and physical units, Cauchy-Crofton 2/3 correction) + * Connected-component labeling and equivalent-sphere particle size distribution + * Through-thickness volume-fraction profiles + * Representative Elementary Volume (REV) convergence studies """ from __future__ import annotations +import csv +from pathlib import Path +from typing import Mapping, Optional, Sequence + import numpy as np # --------------------------------------------------------------------------- @@ -32,9 +40,9 @@ except Exception: cp = None +import scipy.ndimage as ndimage import scipy.sparse as sp import scipy.sparse.linalg as sp_linalg -import scipy.ndimage as ndimage def _xp(): @@ -51,6 +59,21 @@ def backend_name() -> str: return "SciPy (CPU)" +def _build_phase_diff_field( + data: np.ndarray, + phase_diffusivities: Mapping[int, float], +) -> np.ndarray: + """Map integer phase IDs in *data* to non-negative float64 diffusivities.""" + diff = np.zeros(data.shape, dtype=np.float64) + for pid, val in phase_diffusivities.items(): + d_val = float(val) + if d_val < 0.0: + raise ValueError(f"Diffusivity for phase {pid} must be >= 0, got {d_val}") + if d_val > 0.0: + diff[data == int(pid)] = d_val + return diff + + # --------------------------------------------------------------------------- # Volume fraction # --------------------------------------------------------------------------- @@ -71,23 +94,28 @@ def percolation_check( data: np.ndarray, phase: int = 0, direction: int = 0, + phase_diffusivities: Optional[Mapping[int, float]] = None, ) -> tuple[bool, float, np.ndarray]: - """Check if *phase* percolates in *direction* (0=x, 1=y, 2=z). + """Check if conducting cells percolate along NumPy axis *direction* (0=z, 1=y, 2=x). Returns (percolates, active_vf, active_mask). The active_mask marks cells reachable from BOTH inlet and outlet. """ - phase_mask = data == phase + if phase_diffusivities: + conducting_mask = np.zeros(data.shape, dtype=bool) + for pid, val in phase_diffusivities.items(): + if float(val) > 0.0: + conducting_mask |= data == int(pid) + else: + conducting_mask = data == phase # Label connected components using 6-connectivity (faces only) - struct = ndimage.generate_binary_structure(3, 1) # 6-connected - labels, num_features = ndimage.label(phase_mask, structure=struct) + struct = ndimage.generate_binary_structure(3, 1) + labels, num_features = ndimage.label(conducting_mask, structure=struct) if num_features == 0: return False, 0.0, np.zeros_like(data, dtype=np.int32) - # Find labels touching inlet face (first slice along direction) - # and outlet face (last slice along direction) inlet_slice = [slice(None)] * 3 inlet_slice[direction] = 0 outlet_slice = [slice(None)] * 3 @@ -95,17 +123,13 @@ def percolation_check( inlet_labels = set(labels[tuple(inlet_slice)].ravel()) - {0} outlet_labels = set(labels[tuple(outlet_slice)].ravel()) - {0} - - # Active labels are those touching both inlet and outlet active_labels = inlet_labels & outlet_labels if not active_labels: return False, 0.0, np.zeros_like(data, dtype=np.int32) - # Build active mask active_mask = np.isin(labels, list(active_labels)).astype(np.int32) active_vf = float(np.count_nonzero(active_mask)) / float(data.size) - return True, active_vf, active_mask @@ -121,79 +145,60 @@ def _build_laplacian( vlo: float = 0.0, vhi: float = 1.0, ): - """Assemble the sparse linear system Ax = b. + """Assemble the sparse linear system Ax = b for steady-state flow-through diffusion. Parameters ---------- active_mask : (Nz, Ny, Nx) int32 — 1 for active cells, 0 for inactive diff_coeff : (Nz, Ny, Nx) float — diffusion coefficient per cell - direction : 0=x, 1=y, 2=z flow direction + direction : NumPy axis index (0=z, 1=y, 2=x) dx : grid spacing (dz, dy, dx) matching array axis order vlo, vhi : Dirichlet BC values at inlet/outlet - - Returns - ------- - A : sparse CSR matrix (N x N) - b : RHS vector (N,) """ shape = active_mask.shape # (Nz, Ny, Nx) N = int(np.prod(shape)) - # Flat index helper - def flat(i, j, k): - return i * shape[1] * shape[2] + j * shape[2] + k - - # Pre-flatten arrays for fast indexing mask_flat = active_mask.ravel() diff_flat = diff_coeff.ravel() - # Strides for each axis in the flattened array strides = [shape[1] * shape[2], shape[2], 1] - - # Inverse squared grid spacing for each axis dxinv2 = [1.0 / (dx[d] * dx[d]) for d in range(3)] - # Neighbor offsets: (axis, delta, stride) + d_max = float(np.max(diff_flat)) if N > 0 else 1.0 + d_scale = d_max if d_max > 0.0 else 1.0 + pin_diag = d_scale * max(dxinv2) + neighbors = [] for axis in range(3): neighbors.append((axis, -1, -strides[axis])) neighbors.append((axis, +1, +strides[axis])) - # Build COO data rows = [] cols = [] vals = [] rhs = np.zeros(N, dtype=np.float64) - # Vectorized assembly using NumPy indices = np.arange(N) - i3d = np.unravel_index(indices, shape) # (iz, iy, ix) arrays - - # For each cell: if inactive, diagonal=1, rhs=0 - # If active interior: build 7-point stencil - + i3d = np.unravel_index(indices, shape) is_active = mask_flat == 1 - # Identify Dirichlet boundary cells (inlet/outlet faces) is_inlet = np.zeros(N, dtype=bool) is_outlet = np.zeros(N, dtype=bool) is_inlet[is_active] = i3d[direction][is_active] == 0 is_outlet[is_active] = i3d[direction][is_active] == shape[direction] - 1 - - # --- Inactive cells: A_ii = 1, rhs = 0 --- + # Inactive cells: scale-matched diagonal pin, rhs = 0 inactive_idx = indices[~is_active] rows.append(inactive_idx) cols.append(inactive_idx) - vals.append(np.ones(len(inactive_idx))) + vals.append(np.full(len(inactive_idx), pin_diag, dtype=np.float64)) - # Exterior faces add a half-cell conductance to the normal voxel row. active_idx = indices[is_active] if len(active_idx) > 0: D_center = diff_flat[active_idx] diag = np.zeros_like(D_center, dtype=np.float64) for boundary, value in ((is_inlet, vlo), (is_outlet, vhi)): - weight = 2 * diff_flat[boundary] * dxinv2[direction] + weight = 2.0 * diff_flat[boundary] * dxinv2[direction] diag[boundary[active_idx]] += weight rhs[boundary] += weight * value @@ -201,19 +206,12 @@ def flat(i, j, k): nbr_idx = active_idx + stride coord = i3d[axis][active_idx] + delta - # Check bounds in_bounds = (coord >= 0) & (coord < shape[axis]) + valid_nbr = nbr_idx[in_bounds] - # For out-of-bounds neighbors (domain boundary), zero-flux Neumann - # means we simply don't add a coupling term. - valid = in_bounds.copy() - valid_nbr = nbr_idx[valid] - - # Check neighbor is active nbr_active = np.zeros(len(active_idx), dtype=bool) - nbr_active[valid] = mask_flat[valid_nbr] == 1 + nbr_active[in_bounds] = mask_flat[valid_nbr] == 1 - # Compute harmonic mean face coefficient for valid+active neighbors coupled = nbr_active coupled_idx = active_idx[coupled] coupled_nbr = active_idx[coupled] + stride @@ -221,29 +219,23 @@ def flat(i, j, k): D_n = diff_flat[coupled_nbr] denom = D_c + D_n - # Harmonic mean: 2*D_c*D_n / (D_c + D_n), zero if denom==0 - D_face = np.where(denom > 0, 2.0 * D_c * D_n / denom, 0.0) - + D_face = np.where(denom > 0.0, 2.0 * D_c * D_n / denom, 0.0) coeff = -D_face * dxinv2[axis] rows.append(coupled_idx) cols.append(coupled_nbr) vals.append(coeff) - - # Accumulate diagonal (negative of off-diagonal sum) diag[coupled] -= coeff rows.append(active_idx) cols.append(active_idx) vals.append(diag) - # Assemble sparse matrix all_rows = np.concatenate(rows) all_cols = np.concatenate(cols) all_vals = np.concatenate(vals) A = sp.coo_matrix((all_vals, (all_rows, all_cols)), shape=(N, N)).tocsr() - return A, rhs @@ -258,73 +250,57 @@ def _compute_flux( direction: int, dx: tuple[float, float, float], ) -> tuple[float, float, float]: - """Compute inlet flux, outlet flux, and D_eff from the solved potential. - - Returns (flux_in, flux_out, D_eff). - """ + """Compute inlet flux, outlet flux, and D_eff from the solved potential.""" shape = active_mask.shape # (Nz, Ny, Nx) sol = solution.reshape(shape) - # Cross-sectional area perpendicular to flow direction perp_axes = [a for a in range(3) if a != direction] cross_area = dx[perp_axes[0]] * dx[perp_axes[1]] - - # Domain length in flow direction L = shape[direction] * dx[direction] - # --- Compute flux through each interior plane perpendicular to flow --- - # For plane between cell i and i+1: - # flux = sum over plane of: -D_face * (phi[i+1] - phi[i]) / dx * cell_area n_planes = shape[direction] - 1 - plane_fluxes = np.zeros(n_planes) + plane_fluxes = np.zeros(n_planes, dtype=np.float64) for p in range(n_planes): - # Build slices for left and right cells left_sl = [slice(None)] * 3 left_sl[direction] = p right_sl = [slice(None)] * 3 right_sl[direction] = p + 1 - left_sl = tuple(left_sl) - right_sl = tuple(right_sl) + left_sl_t = tuple(left_sl) + right_sl_t = tuple(right_sl) - mask_l = active_mask[left_sl] - mask_r = active_mask[right_sl] + mask_l = active_mask[left_sl_t] + mask_r = active_mask[right_sl_t] both_active = (mask_l == 1) & (mask_r == 1) - if not np.any(both_active): continue - D_l = diff_coeff[left_sl][both_active] - D_r = diff_coeff[right_sl][both_active] + D_l = diff_coeff[left_sl_t][both_active] + D_r = diff_coeff[right_sl_t][both_active] denom = D_l + D_r - D_face = np.where(denom > 0, 2.0 * D_l * D_r / denom, 0.0) + D_face = np.where(denom > 0.0, 2.0 * D_l * D_r / denom, 0.0) - grad = (sol[right_sl][both_active] - sol[left_sl][both_active]) / dx[direction] + grad = (sol[right_sl_t][both_active] - sol[left_sl_t][both_active]) / dx[direction] plane_fluxes[p] = np.sum(-D_face * grad * cross_area) - conductance = 2 * active_mask * diff_coeff * cross_area / dx[direction] - flux_in = -np.sum(np.take(conductance * sol, 0, axis=direction)) - flux_out = -np.sum(np.take(conductance * (1.0 - sol), -1, axis=direction)) + conductance = 2.0 * active_mask * diff_coeff * cross_area / dx[direction] + flux_in = -float(np.sum(np.take(conductance * sol, 0, axis=direction))) + flux_out = -float(np.sum(np.take(conductance * (1.0 - sol), -1, axis=direction))) - # Average flux magnitude from all interior planes - nonzero_planes = plane_fluxes[plane_fluxes != 0.0] - if len(nonzero_planes) > 0: - avg_flux = float(np.mean(np.abs(nonzero_planes))) + if n_planes > 0: + avg_flux = float(np.mean(np.abs(plane_fluxes))) else: avg_flux = 0.5 * (abs(flux_in) + abs(flux_out)) - # Total cross-section area of the domain total_cross_area = 1.0 for a in perp_axes: total_cross_area *= shape[a] * dx[a] - # Imposed gradient vlo, vhi = 0.0, 1.0 grad_imposed = abs(vhi - vlo) / L - # D_eff = avg_flux / (A_total * grad_imposed) - if total_cross_area * grad_imposed > 0: + if total_cross_area * grad_imposed > 0.0: D_eff = avg_flux / (total_cross_area * grad_imposed) else: D_eff = 0.0 @@ -332,8 +308,66 @@ def _compute_flux( return float(flux_in), float(flux_out), float(D_eff) +def _solve_spd_cg( + A_sp: sp.csr_matrix, + rhs: np.ndarray, + x0: np.ndarray, + tol: float, + maxiter: int, +) -> tuple[np.ndarray, bool, int, float]: + """Solve SPD system A_sp x = rhs via Jacobi-preconditioned CG.""" + rhs_norm = float(np.linalg.norm(rhs)) + if rhs_norm == 0.0: + return np.zeros_like(rhs), True, 0, 0.0 + + if _USE_CUPY: + A_gpu = cusp.csr_matrix(A_sp) + rhs_gpu = cp.asarray(rhs) + x0_gpu = cp.asarray(x0) + diag_gpu = A_gpu.diagonal() + inv_diag_gpu = cp.where(cp.abs(diag_gpu) > 0.0, 1.0 / diag_gpu, 1.0) + M_gpu = cusp.diags(inv_diag_gpu) + try: + solution_gpu, info = cusp_linalg.cg( + A_gpu, rhs_gpu, x0=x0_gpu, M=M_gpu, rtol=tol, maxiter=maxiter + ) + except TypeError: + solution_gpu, info = cusp_linalg.cg( + A_gpu, rhs_gpu, x0=x0_gpu, M=M_gpu, tol=tol, maxiter=maxiter + ) + solution = cp.asnumpy(solution_gpu) + converged = info == 0 + iterations = maxiter if not converged else -1 + res = cp.asnumpy(rhs_gpu - A_gpu @ solution_gpu) + residual_norm = float(np.linalg.norm(res) / max(rhs_norm, 1e-300)) + return solution, converged, iterations, residual_norm + + diag = A_sp.diagonal() + inv_diag = np.where(np.abs(diag) > 0.0, 1.0 / diag, 1.0) + M = sp.diags(inv_diag) + + iter_count = [0] + + def _callback(_xk): + iter_count[0] += 1 + + try: + solution, info = sp_linalg.cg( + A_sp, rhs, x0=x0, M=M, rtol=tol, atol=0.0, maxiter=maxiter, callback=_callback + ) + except TypeError: + solution, info = sp_linalg.cg( + A_sp, rhs, x0=x0, M=M, tol=tol, maxiter=maxiter, callback=_callback + ) + converged = info == 0 + iterations = iter_count[0] + res = rhs - A_sp @ solution + residual_norm = float(np.linalg.norm(res) / max(rhs_norm, 1e-300)) + return solution, converged, iterations, residual_norm + + # --------------------------------------------------------------------------- -# Main solver entry point +# Main tortuosity solver entry point # --------------------------------------------------------------------------- def solve_tortuosity( @@ -342,119 +376,73 @@ def solve_tortuosity( direction: int = 0, tol: float = 1e-9, maxiter: int = 2000, + voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0), + phase_diffusivities: Optional[Mapping[int, float]] = None, + return_field: bool = True, ) -> dict: - """Compute tortuosity of *phase* in *direction*. - - Parameters - ---------- - data : (Nz, Ny, Nx) int32 array of phase IDs - phase : target phase ID - direction : 0=x, 1=y, 2=z (axis index in the NumPy array) - tol : solver tolerance - maxiter : max solver iterations - - Returns - ------- - dict with keys: tortuosity, solver_converged, iterations, residual_norm, - flux_in, flux_out, active_volume_fraction, backend - """ + """Compute tortuosity and effective diffusivity along NumPy axis *direction* (0=z, 1=y, 2=x).""" data = np.ascontiguousarray(data, dtype=np.int32) if data.ndim != 3: raise ValueError(f"Expected 3-D array, got shape {data.shape}") + dx = (float(voxel_size[0]), float(voxel_size[1]), float(voxel_size[2])) + if any(h <= 0.0 for h in dx): + raise ValueError(f"voxel_size components must all be > 0, got {dx}") + shape = data.shape # (Nz, Ny, Nx) - # --- Percolation check --- - percolates, active_vf, active_mask = percolation_check(data, phase, direction) + percolates, active_vf, active_mask = percolation_check( + data, phase, direction, phase_diffusivities=phase_diffusivities + ) if not percolates: from .exceptions import PercolationError + dir_names = {0: "z", 1: "y", 2: "x"} + if phase_diffusivities: + raise PercolationError( + f"Conducting phases do not percolate in the {dir_names[direction]} direction. " + f"The solver cannot converge when conducting phases are " + f"disconnected between the inlet and outlet faces." + ) raise PercolationError( f"Phase {phase} does not percolate in the {dir_names[direction]} direction. " f"The solver cannot converge when the conducting phase is " f"disconnected between the inlet and outlet faces." ) - # --- Build diffusion coefficient field --- - # All active cells get D=1.0, inactive get D=0.0 - diff_coeff = np.where(active_mask == 1, 1.0, 0.0) - - # --- Grid spacing (uniform unit grid) --- - dx = (1.0, 1.0, 1.0) + if phase_diffusivities: + raw_diff = _build_phase_diff_field(data, phase_diffusivities) + diff_coeff = np.where(active_mask == 1, raw_diff, 0.0) + else: + diff_coeff = np.where(active_mask == 1, 1.0, 0.0) - # --- Assemble sparse system --- A_sp, rhs = _build_laplacian(active_mask, diff_coeff, direction, dx) - # --- Initial guess: linear gradient in flow direction --- - x0 = np.zeros(A_sp.shape[0], dtype=np.float64) - coords = np.arange(shape[direction], dtype=np.float64) - grad_init = coords / max(shape[direction] - 1, 1) - - # Broadcast linear gradient to 3D then flatten + coords = (np.arange(shape[direction], dtype=np.float64) + 0.5) / max(shape[direction], 1) bcast_shape = [1, 1, 1] bcast_shape[direction] = shape[direction] tile_shape = list(shape) tile_shape[direction] = 1 - x0_3d = np.tile(grad_init.reshape(bcast_shape), tile_shape) - x0 = x0_3d.ravel() - # Zero out inactive cells + x0 = np.tile(coords.reshape(bcast_shape), tile_shape).ravel() x0[active_mask.ravel() == 0] = 0.0 - # --- Solve --- - if _USE_CUPY: - A_gpu = cusp.csr_matrix(A_sp) - rhs_gpu = cp.asarray(rhs) - x0_gpu = cp.asarray(x0) - - # CuPy CG solve — CuPy >= 13 renamed tol → rtol (mirroring scipy). - try: - solution_gpu, info = cusp_linalg.cg(A_gpu, rhs_gpu, x0=x0_gpu, - rtol=tol, maxiter=maxiter) - except TypeError: - solution_gpu, info = cusp_linalg.cg(A_gpu, rhs_gpu, x0=x0_gpu, - tol=tol, maxiter=maxiter) - solution = cp.asnumpy(solution_gpu) - converged = info == 0 - # CuPy doesn't return iteration count directly; estimate from info - iterations = maxiter if not converged else -1 # unknown exact count - # Compute residual - res = cp.asnumpy(rhs_gpu - A_gpu @ solution_gpu) - residual_norm = float(np.linalg.norm(res) / max(np.linalg.norm(rhs), 1e-30)) - else: - # SciPy CG solve with callback to count iterations - iter_count = [0] - - def _callback(xk): - iter_count[0] += 1 - - # scipy >= 1.12 renamed tol → rtol; older versions use tol. - try: - solution, info = sp_linalg.cg(A_sp, rhs, x0=x0, rtol=tol, - maxiter=maxiter, callback=_callback) - except TypeError: - solution, info = sp_linalg.cg(A_sp, rhs, x0=x0, tol=tol, - maxiter=maxiter, callback=_callback) - converged = info == 0 - iterations = iter_count[0] - res = rhs - A_sp @ solution - residual_norm = float(np.linalg.norm(res) / max(np.linalg.norm(rhs), 1e-30)) - - # --- Compute flux and D_eff --- - flux_in, flux_out, D_eff = _compute_flux( - solution, active_mask, diff_coeff, direction, dx, + solution, converged, iterations, residual_norm = _solve_spd_cg( + A_sp, rhs, x0, tol=tol, maxiter=maxiter ) - # --- Tortuosity: tau = active_vf / D_eff --- - if D_eff > 0: + flux_in, flux_out, D_eff = _compute_flux(solution, active_mask, diff_coeff, direction, dx) + + d_scale = float(np.max(diff_coeff)) + if D_eff > 1e-15 * max(d_scale, 1e-300): tau = active_vf / D_eff else: tau = float("inf") - # Reshape flat solution back to 3-D field - solution_field = solution.reshape(shape).copy() + solution_field = solution.reshape(shape).copy() if return_field else None return { "tortuosity": tau, + "effective_diffusivity": D_eff, "solver_converged": converged, "iterations": iterations, "residual_norm": residual_norm, @@ -464,3 +452,483 @@ def _callback(xk): "solution_field": solution_field, "backend": backend_name(), } + + +# --------------------------------------------------------------------------- +# Periodic homogenization 3x3 D_eff tensor solver +# --------------------------------------------------------------------------- + +def _build_cell_problem_system( + active_mask: np.ndarray, + diff_coeff: np.ndarray, + dir_k_xyz: int, + voxel_size: tuple[float, float, float], +) -> tuple[sp.csr_matrix, np.ndarray]: + """Assemble the periodic cell-problem matrix matching EffDiffFillMtx.H + EffectiveDiffusivityHypre.""" + shape = active_mask.shape # (Nz, Ny, Nx) + N = int(np.prod(shape)) + idx_grid = np.arange(N, dtype=np.int64).reshape(shape) + + is_active_3d = active_mask == 1 + active_idx = idx_grid[is_active_3d] + inactive_idx = idx_grid[~is_active_3d] + + d_max = float(np.max(diff_coeff)) if N > 0 else 1.0 + d_scale = d_max if d_max > 0.0 else 1.0 + inv_h2_max = max(1.0 / (h * h) for h in voxel_size) + pin_scale = d_scale * inv_h2_max + + rows = [inactive_idx] + cols = [inactive_idx] + vals = [np.full(len(inactive_idx), pin_scale, dtype=np.float64)] + rhs = np.zeros(N, dtype=np.float64) + + if len(active_idx) > 0: + D_c = diff_coeff[is_active_3d] + diag = np.zeros(len(active_idx), dtype=np.float64) + flux_bc_rhs = np.zeros(len(active_idx), dtype=np.float64) + + # Spatial directions d_xyz = 0(X -> axis 2), 1(Y -> axis 1), 2(Z -> axis 0) + for d_xyz in range(3): + ax = 2 - d_xyz + h = voxel_size[ax] + inv_h2 = 1.0 / (h * h) + + # -d face (index - 1 along ax -> np.roll +1) + m_nbr_idx = np.roll(idx_grid, 1, axis=ax)[is_active_3d] + m_nbr_active = np.roll(is_active_3d, 1, axis=ax)[is_active_3d] + m_D_nbr = np.roll(diff_coeff, 1, axis=ax)[is_active_3d] + + if np.any(m_nbr_active): + dc_m = D_c[m_nbr_active] + dn_m = m_D_nbr[m_nbr_active] + denom_m = dc_m + dn_m + d_face_m = np.where(denom_m > 0.0, 2.0 * dc_m * dn_m / denom_m, 0.0) + c_m = -d_face_m * inv_h2 + rows.append(active_idx[m_nbr_active]) + cols.append(m_nbr_idx[m_nbr_active]) + vals.append(c_m) + diag[m_nbr_active] -= c_m + + m_inact = ~m_nbr_active + if np.any(m_inact): + diag[m_inact] += D_c[m_inact] * inv_h2 + if dir_k_xyz == d_xyz: + flux_bc_rhs[m_inact] += D_c[m_inact] / h + + # +d face (index + 1 along ax -> np.roll -1) + p_nbr_idx = np.roll(idx_grid, -1, axis=ax)[is_active_3d] + p_nbr_active = np.roll(is_active_3d, -1, axis=ax)[is_active_3d] + p_D_nbr = np.roll(diff_coeff, -1, axis=ax)[is_active_3d] + + if np.any(p_nbr_active): + dc_p = D_c[p_nbr_active] + dn_p = p_D_nbr[p_nbr_active] + denom_p = dc_p + dn_p + d_face_p = np.where(denom_p > 0.0, 2.0 * dc_p * dn_p / denom_p, 0.0) + c_p = -d_face_p * inv_h2 + rows.append(active_idx[p_nbr_active]) + cols.append(p_nbr_idx[p_nbr_active]) + vals.append(c_p) + diag[p_nbr_active] -= c_p + + p_inact = ~p_nbr_active + if np.any(p_inact): + diag[p_inact] += D_c[p_inact] * inv_h2 + if dir_k_xyz == d_xyz: + flux_bc_rhs[p_inact] -= D_c[p_inact] / h + + ax_k = 2 - dir_k_xyz + h_k = voxel_size[ax_k] + rhs_div_De = -( + np.roll(diff_coeff, -1, axis=ax_k)[is_active_3d] + - np.roll(diff_coeff, 1, axis=ax_k)[is_active_3d] + ) / (2.0 * h_k) + rhs[active_idx] = rhs_div_De + flux_bc_rhs + + rows.append(active_idx) + cols.append(active_idx) + vals.append(diag) + + all_rows = np.concatenate(rows) + all_cols = np.concatenate(cols) + all_vals = np.concatenate(vals) + + # Pin the first active cell (matching EffectiveDiffusivityHypre.cpp) to remove constant nullspace + pin_idx = int(active_idx[0]) + keep = all_rows != pin_idx + all_rows = np.append(all_rows[keep], pin_idx) + all_cols = np.append(all_cols[keep], pin_idx) + all_vals = np.append(all_vals[keep], pin_scale) + rhs[pin_idx] = 0.0 + else: + all_rows = np.concatenate(rows) + all_cols = np.concatenate(cols) + all_vals = np.concatenate(vals) + + A = sp.coo_matrix((all_vals, (all_rows, all_cols)), shape=(N, N)).tocsr() + return A, rhs + + +def solve_effective_diffusivity( + data: np.ndarray, + phase: int = 1, + voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0), + phase_diffusivities: Optional[Mapping[int, float]] = None, + tol: float = 1e-9, + maxiter: int = 2000, + return_chi: bool = False, +) -> dict: + """Solve the 3 periodic cell problems and return the 3x3 D_eff tensor in (X, Y, Z) order.""" + data = np.ascontiguousarray(data, dtype=np.int32) + if data.ndim != 3: + raise ValueError(f"Expected 3-D array, got shape {data.shape}") + + vz = (float(voxel_size[0]), float(voxel_size[1]), float(voxel_size[2])) + if any(h <= 0.0 for h in vz): + raise ValueError(f"voxel_size components must all be > 0, got {vz}") + + shape = data.shape + N = int(data.size) + + if phase_diffusivities: + diff_coeff = _build_phase_diff_field(data, phase_diffusivities) + active_mask = (diff_coeff > 0.0).astype(np.int32) + else: + active_mask = (data == phase).astype(np.int32) + diff_coeff = active_mask.astype(np.float64) + + active_count = int(np.count_nonzero(active_mask)) + active_vf = float(active_count) / float(N) if N > 0 else 0.0 + + if active_count == 0: + out = { + "tensor": np.zeros((3, 3), dtype=np.float64), + "active_volume_fraction": 0.0, + "converged": True, + "iterations": (0, 0, 0), + "residuals": (0.0, 0.0, 0.0), + } + if return_chi: + zeros = np.zeros(shape, dtype=np.float64) + out["chi"] = {"x": zeros.copy(), "y": zeros.copy(), "z": zeros.copy()} + return out + + chi_fields: list[np.ndarray] = [] + dir_iters: list[int] = [] + dir_res: list[float] = [] + all_converged = True + + for dir_k_xyz in range(3): + A_sp, rhs = _build_cell_problem_system(active_mask, diff_coeff, dir_k_xyz, vz) + rhs_norm = float(np.linalg.norm(rhs)) + if rhs_norm == 0.0: + chi_fields.append(np.zeros(shape, dtype=np.float64)) + dir_iters.append(0) + dir_res.append(0.0) + continue + + diag = A_sp.diagonal() + inv_diag = np.where(np.abs(diag) > 0.0, 1.0 / diag, 1.0) + M = sp.diags(inv_diag) + + iters = [0] + + def _cb(_xk): + iters[0] += 1 + + try: + sol, info = sp_linalg.bicgstab( + A_sp, rhs, M=M, rtol=tol, atol=0.0, maxiter=maxiter, callback=_cb + ) + except TypeError: + sol, info = sp_linalg.bicgstab( + A_sp, rhs, M=M, tol=tol, maxiter=maxiter, callback=_cb + ) + + if info != 0: + iters[0] = 0 + try: + sol, info = sp_linalg.gmres( + A_sp, rhs, M=M, rtol=tol, atol=0.0, maxiter=maxiter, callback=_cb, + callback_type="legacy", + ) + except TypeError: + sol, info = sp_linalg.gmres( + A_sp, rhs, M=M, tol=tol, maxiter=maxiter, callback=_cb + ) + + res_norm = float(np.linalg.norm(rhs - A_sp @ sol) / max(rhs_norm, 1e-300)) + conv = info == 0 or res_norm <= tol * 10.0 + all_converged = all_converged and conv + chi_fields.append(sol.reshape(shape)) + dir_iters.append(iters[0]) + dir_res.append(res_norm) + + tensor = np.full((3, 3), np.nan, dtype=np.float64) + if all_converged and N > 0: + is_act = active_mask == 1 + D_act = diff_coeff[is_act] + for r in range(3): + ax_r = 2 - r + h_r = vz[ax_r] + for c in range(3): + chi_c = chi_fields[c] + dchi_dxr = (np.roll(chi_c, -1, axis=ax_r) - np.roll(chi_c, 1, axis=ax_r)) / ( + 2.0 * h_r + ) + delta_rc = 1.0 if r == c else 0.0 + tensor[r, c] = float(np.sum(D_act * (delta_rc + dchi_dxr[is_act]))) / float(N) + + out = { + "tensor": tensor, + "active_volume_fraction": active_vf, + "converged": all_converged, + "iterations": (dir_iters[0], dir_iters[1], dir_iters[2]), + "residuals": (dir_res[0], dir_res[1], dir_res[2]), + } + if return_chi: + out["chi"] = { + "x": chi_fields[0].copy(), + "y": chi_fields[1].copy(), + "z": chi_fields[2].copy(), + } + return out + + +# --------------------------------------------------------------------------- +# Microstructural metrics (pure-Python parity with C++ SpecificSurfaceArea, +# ConnectedComponents, ParticleSizeDistribution, ThroughThicknessProfile, REV) +# --------------------------------------------------------------------------- + +def specific_surface_area( + data: np.ndarray, + phase_a: int = 0, + phase_b: int = 1, + voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0), + boundary_padding: int = 0, +) -> dict: + """Compute interface face counts and specific surface area between *phase_a* and *phase_b*.""" + data = np.ascontiguousarray(data, dtype=np.int32) + if data.ndim != 3: + raise ValueError(f"Expected 3-D array, got shape {data.shape}") + if boundary_padding < 0: + raise ValueError(f"boundary_padding must be >= 0, got {boundary_padding}") + + dz, dy, dx = float(voxel_size[0]), float(voxel_size[1]), float(voxel_size[2]) + if dz <= 0.0 or dy <= 0.0 or dx <= 0.0: + raise ValueError(f"voxel_size components must all be > 0, got {voxel_size}") + + if boundary_padding > 0: + p = int(boundary_padding) + if any(s <= 2 * p for s in data.shape): + raise ValueError( + f"boundary_padding={p} is too large for array of shape {data.shape}" + ) + sub = data[p:-p, p:-p, p:-p] + else: + sub = data + + total_count = int(sub.size) + + def _count_axis(a: np.ndarray, b: np.ndarray) -> int: + return int( + np.count_nonzero(((a == phase_a) & (b == phase_b)) | ((a == phase_b) & (b == phase_a))) + ) + + fx = _count_axis(sub[:, :, :-1], sub[:, :, 1:]) if sub.shape[2] > 1 else 0 + fy = _count_axis(sub[:, :-1, :], sub[:, 1:, :]) if sub.shape[1] > 1 else 0 + fz = _count_axis(sub[:-1, :, :], sub[1:, :, :]) if sub.shape[0] > 1 else 0 + face_count = fx + fy + fz + + if total_count > 0: + ssa_voxel = float(face_count) / float(total_count) + ssa_physical = (fx / dx + fy / dy + fz / dz) / float(total_count) + else: + ssa_voxel = 0.0 + ssa_physical = 0.0 + + return { + "face_count": face_count, + "face_counts_xyz": (fx, fy, fz), + "total_count": total_count, + "ssa_voxel": ssa_voxel, + "ssa_voxel_corrected": (2.0 / 3.0) * ssa_voxel, + "ssa": ssa_physical, + "ssa_corrected": (2.0 / 3.0) * ssa_physical, + } + + +def connected_components( + data: np.ndarray, + phase: int = 1, + return_labels: bool = False, +) -> tuple[int, np.ndarray, Optional[np.ndarray]]: + """Label 6-connected components of *phase* and return (num_components, volumes, labels).""" + data = np.ascontiguousarray(data, dtype=np.int32) + if data.ndim != 3: + raise ValueError(f"Expected 3-D array, got shape {data.shape}") + + struct = ndimage.generate_binary_structure(3, 1) + labels, num_comp = ndimage.label(data == phase, structure=struct) + if num_comp > 0: + volumes = np.bincount(labels.ravel())[1 : num_comp + 1].astype(np.int64) + else: + volumes = np.zeros(0, dtype=np.int64) + label_arr = labels.astype(np.int32) if return_labels else None + return int(num_comp), volumes, label_arr + + +def particle_size_distribution( + data: np.ndarray, + phase: int = 1, + voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0), +) -> dict: + """Compute equivalent-sphere radii R = (3V / (4*pi))^(1/3) for 6-connected components.""" + dz, dy, dx = float(voxel_size[0]), float(voxel_size[1]), float(voxel_size[2]) + if dz <= 0.0 or dy <= 0.0 or dx <= 0.0: + raise ValueError(f"voxel_size components must all be > 0, got {voxel_size}") + + num_particles, volumes_vox, _ = connected_components(data, phase=phase, return_labels=False) + cell_vol = dz * dy * dx + length_scale = cell_vol ** (1.0 / 3.0) + + if num_particles > 0: + radii_vox = ((3.0 * volumes_vox.astype(np.float64)) / (4.0 * np.pi)) ** (1.0 / 3.0) + radii_phys = radii_vox * length_scale + mean_radius_vox = float(np.mean(radii_vox)) + mean_radius_phys = float(np.mean(radii_phys)) + else: + radii_vox = np.zeros(0, dtype=np.float64) + radii_phys = np.zeros(0, dtype=np.float64) + mean_radius_vox = 0.0 + mean_radius_phys = 0.0 + + return { + "num_particles": num_particles, + "volumes_voxels": volumes_vox, + "volumes": volumes_vox.astype(np.float64) * cell_vol, + "radii_voxels": radii_vox, + "radii": radii_phys, + "mean_radius_voxels": mean_radius_vox, + "mean_radius": mean_radius_phys, + } + + +def through_thickness_profile( + data: np.ndarray, + phase: int = 1, + direction_xyz: int = 0, + voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0), +) -> tuple[np.ndarray, np.ndarray]: + """Compute per-slice volume fraction profile along *direction_xyz* (0=X, 1=Y, 2=Z).""" + data = np.ascontiguousarray(data, dtype=np.int32) + if data.ndim != 3: + raise ValueError(f"Expected 3-D array, got shape {data.shape}") + + ax = 2 - direction_xyz + perp_axes = tuple(a for a in range(3) if a != ax) + profile = np.mean(data == phase, axis=perp_axes, dtype=np.float64) + h = float(voxel_size[ax]) + positions = (np.arange(data.shape[ax], dtype=np.float64) + 0.5) * h + return profile, positions + + +def rev_study( + data: np.ndarray, + sizes: Sequence[int], + num_samples: int = 3, + phase: int = 1, + voxel_size: tuple[float, float, float] = (1.0, 1.0, 1.0), + csv_path: Optional[str] = None, + seed: int = 42, +) -> list[dict]: + """Run an REV convergence study in pure Python and optionally write CSV matching REVStudy.cpp.""" + data = np.ascontiguousarray(data, dtype=np.int32) + if data.ndim != 3: + raise ValueError(f"Expected 3-D array, got shape {data.shape}") + + nz, ny, nx = data.shape + rng = np.random.default_rng(seed) + records: list[dict] = [] + + if csv_path is not None: + out_path = Path(csv_path) + out_path.parent.mkdir(parents=True, exist_ok=True) + else: + out_path = None + + for target in sizes: + t = int(target) + if t <= 0: + continue + act_x = min(t, nx) + act_y = min(t, ny) + act_z = min(t, nz) + for s_idx in range(1, int(num_samples) + 1): + sx = int(rng.integers(0, nx - act_x + 1)) if nx > act_x else 0 + sy = int(rng.integers(0, ny - act_y + 1)) if ny > act_y else 0 + sz = int(rng.integers(0, nz - act_z + 1)) if nz > act_z else 0 + sub = data[sz : sz + act_z, sy : sy + act_y, sx : sx + act_x] + eff = solve_effective_diffusivity(sub, phase=phase, voxel_size=voxel_size) + D = eff["tensor"] + records.append( + { + "sample": s_idx, + "seed_xyz": (sx, sy, sz), + "target_size": t, + "actual_size_xyz": (act_x, act_y, act_z), + "D_xx": float(D[0, 0]), + "D_yy": float(D[1, 1]), + "D_zz": float(D[2, 2]), + "D_xy": float(D[0, 1]), + "D_xz": float(D[0, 2]), + "D_yz": float(D[1, 2]), + "tensor": D.copy(), + } + ) + + if out_path is not None: + with open(out_path, "w", newline="") as f: + writer = csv.writer(f) + writer.writerow( + [ + "SampleNo", + "SeedX", + "SeedY", + "SeedZ", + "REV_Size_Target", + "ActualSizeX", + "ActualSizeY", + "ActualSizeZ", + "D_xx", + "D_yy", + "D_zz", + "D_xy", + "D_xz", + "D_yz", + ] + ) + for r in records: + sx, sy, sz = r["seed_xyz"] + ax_x, ax_y, ax_z = r["actual_size_xyz"] + writer.writerow( + [ + r["sample"], + sx, + sy, + sz, + r["target_size"], + ax_x, + ax_y, + ax_z, + f"{r['D_xx']:.8e}", + f"{r['D_yy']:.8e}", + f"{r['D_zz']:.8e}", + f"{r['D_xy']:.8e}", + f"{r['D_xz']:.8e}", + f"{r['D_yz']:.8e}", + ] + ) + + return records diff --git a/python/openimpala/cli.py b/python/openimpala/cli.py index dea08b9..7e2d45d 100644 --- a/python/openimpala/cli.py +++ b/python/openimpala/cli.py @@ -58,6 +58,13 @@ def _build_parser() -> argparse.ArgumentParser: default="smg", help="HYPRE Krylov preconditioner: smg or pfmg (default: smg)", ) + p_analyze.add_argument( + "--voxel-size", + nargs="+", + type=float, + default=None, + help="Physical voxel size: single float (isotropic) or 3 floats DZ DY DX", + ) p_analyze.add_argument("--output", default=None, help="Output JSON path (default: stdout)") p_analyze.add_argument("--max-grid-size", type=_parse_max_grid_size, default="auto") p_analyze.add_argument("--verbose", type=int, default=0) @@ -147,9 +154,21 @@ def _cmd_percolation(args: argparse.Namespace) -> int: def _cmd_analyze(args: argparse.Namespace) -> int: import openimpala as oi + vz = None + if args.voxel_size is not None: + if len(args.voxel_size) == 1: + vz = args.voxel_size[0] + elif len(args.voxel_size) == 3: + vz = tuple(args.voxel_size) + else: + raise SystemExit( + f"Error: --voxel-size expects 1 value (isotropic) or 3 values (DZ DY DX), got {len(args.voxel_size)}" + ) + _, img = oi.read_image( args.image, threshold=args.threshold, + voxel_size=vz, max_grid_size=args.max_grid_size, ) @@ -161,6 +180,8 @@ def _cmd_analyze(args: argparse.Namespace) -> int: "direction": args.direction.upper(), "volume_fraction": vf_res.fraction, } + if vz is not None: + result["voxel_size"] = list(img.voxel_size) try: tau_res = oi.tortuosity( @@ -187,6 +208,7 @@ def _cmd_analyze(args: argparse.Namespace) -> int: result["percolates"] = True result["active_volume_fraction"] = tau_res.active_volume_fraction result["tortuosity"] = tau_res.tortuosity + result["effective_diffusivity"] = tau_res.effective_diffusivity result["solver_converged"] = tau_res.solver_converged result["iterations"] = tau_res.iterations result["residual_norm"] = tau_res.residual_norm diff --git a/python/openimpala/facade.py b/python/openimpala/facade.py index 9a1bbbb..a847b13 100644 --- a/python/openimpala/facade.py +++ b/python/openimpala/facade.py @@ -1,22 +1,27 @@ -"""High-level, NumPy-native facade for common OpenImpala workflows. +"""High-level, NumPy-native facade for OpenImpala workflows. -These functions accept plain ``numpy.ndarray`` inputs and return rich -Python dataclasses, hiding all AMReX boilerplate from general users. +These functions accept plain ``numpy.ndarray`` inputs (or ``VoxelImage`` handles) +and return rich Python dataclasses, hiding all AMReX boilerplate from users. -When the compiled C++ backend (_core) is unavailable, functions -transparently fall back to the pure-Python solver (SciPy/CuPy). +When the compiled C++ backend (``_core``) is unavailable, all high-level analysis +functions transparently fall back to the pure-Python solver (NumPy / SciPy / CuPy). """ from __future__ import annotations +import csv import dataclasses -from typing import Optional, Union +import tempfile +from pathlib import Path +from typing import Mapping, Optional, Sequence, Union import numpy as np from .exceptions import ConvergenceError, PercolationError from .session import Session, _has_core +VoxelSizeArg = Union[float, int, Sequence[float]] + # --------------------------------------------------------------------------- # Return dataclasses @@ -53,7 +58,7 @@ class PercolationResult: @dataclasses.dataclass class TortuosityResult: - """Result of a tortuosity calculation.""" + """Result of a tortuosity / multi-phase steady-state transport calculation.""" tortuosity: float solver_converged: bool @@ -63,13 +68,20 @@ class TortuosityResult: flux_out: float active_volume_fraction: float solution_field: "np.ndarray | None" = None + effective_diffusivity: Optional[float] = None def _repr_html_(self) -> str: status = "converged" if self.solver_converged else "NOT converged" + deff_row = ( + f"Effective diffusivity{self.effective_diffusivity:.6e}" + if self.effective_diffusivity is not None + else "" + ) return ( "" "" f"" + f"{deff_row}" f"" f"" f"" @@ -80,8 +92,104 @@ def _repr_html_(self) -> str: ) +@dataclasses.dataclass +class EffectiveDiffusivityResult: + """Result of a 3-D periodic homogenisation effective-diffusivity tensor calculation. + + ``tensor`` is a ``(3, 3)`` ``float64`` NumPy array ordered ``(x, y, z)``: + ``tensor[0, 0] = D_xx``, ``tensor[1, 1] = D_yy``, ``tensor[2, 2] = D_zz``, + ``tensor[0, 1] = D_xy``, etc. + """ + + tensor: np.ndarray + active_volume_fraction: float + solver_converged: bool + iterations: tuple[int, int, int] + residuals: tuple[float, float, float] + corrector_fields: Optional[dict[str, np.ndarray]] = None + + @property + def diagonal(self) -> tuple[float, float, float]: + """Principal diagonal entries ``(D_xx, D_yy, D_zz)``.""" + return ( + float(self.tensor[0, 0]), + float(self.tensor[1, 1]), + float(self.tensor[2, 2]), + ) + + def _repr_html_(self) -> str: + dxx, dyy, dzz = self.diagonal + return ( + "
MetricValue
Tortuosity{self.tortuosity:.6f}
Solver status{status}
Iterations{self.iterations}
Residual norm{self.residual_norm:.2e}
" + "" + f"" + f"" + f"" + f"" + f"" + f"" + f"" + "
ComponentValue
D_xx{dxx:.6e}
D_yy{dyy:.6e}
D_zz{dzz:.6e}
D_xy{float(self.tensor[0, 1]):.6e}
D_xz{float(self.tensor[0, 2]):.6e}
D_yz{float(self.tensor[1, 2]):.6e}
Active VF{self.active_volume_fraction:.6f}
" + ) + + +@dataclasses.dataclass +class SpecificSurfaceAreaResult: + """Result of an interfacial specific surface area calculation.""" + + ssa: float + ssa_corrected: float + ssa_voxel: float + ssa_voxel_corrected: float + face_count: int + total_count: int + face_counts_xyz: tuple[int, int, int] + + +@dataclasses.dataclass +class ConnectedComponentsResult: + """Result of 6-connected component labeling.""" + + num_components: int + volumes: np.ndarray + labels: Optional[np.ndarray] = None + + +@dataclasses.dataclass +class ParticleSizeDistributionResult: + """Result of equivalent-sphere particle size distribution analysis.""" + + num_particles: int + mean_radius: float + radii: np.ndarray + volumes: np.ndarray + radii_voxels: np.ndarray + volumes_voxels: np.ndarray + + +@dataclasses.dataclass +class ThroughThicknessResult: + """Result of a slice-by-slice through-thickness volume fraction profile.""" + + direction: str + num_slices: int + profile: np.ndarray + positions: np.ndarray + + +@dataclasses.dataclass +class REVStudyResult: + """Result of a Representative Elementary Volume (REV) convergence study.""" + + sizes: list[int] + samples: list[dict] + mean_diagonal: dict[int, np.ndarray] + std_diagonal: dict[int, np.ndarray] + csv_path: Optional[str] = None + + # --------------------------------------------------------------------------- -# Backend detection +# Backend detection & input normalisation helpers # --------------------------------------------------------------------------- def _is_pure_python() -> bool: @@ -92,26 +200,66 @@ def _is_pure_python() -> bool: def _get_core(): """Import and return the _core C extension (lazy, cached by Python).""" import importlib + return importlib.import_module("openimpala._core") -# --------------------------------------------------------------------------- -# Direction / solver helpers -# --------------------------------------------------------------------------- - _DIR_MAP = {"x": 0, "y": 1, "z": 2} _DIR_NAMES = {0: "x", 1: "y", 2: "z"} +def _normalize_voxel_size(voxel_size: Optional[VoxelSizeArg]) -> tuple[float, float, float]: + """Normalise scalar or 3-element ``voxel_size`` into ``(dz, dy, dx)`` positive floats.""" + if voxel_size is None: + return (1.0, 1.0, 1.0) + if isinstance(voxel_size, (int, float, np.floating, np.integer)): + v = float(voxel_size) + if not np.isfinite(v) or v <= 0.0: + raise ValueError(f"voxel_size must be a finite positive number, got {voxel_size!r}") + return (v, v, v) + try: + seq = tuple(float(x) for x in voxel_size) + except TypeError as exc: + raise TypeError( + "voxel_size must be a positive float or a 3-tuple (dz, dy, dx)" + ) from exc + if len(seq) != 3 or any((not np.isfinite(v) or v <= 0.0) for v in seq): + raise ValueError( + f"voxel_size must have 3 positive finite entries (dz, dy, dx), got {voxel_size!r}" + ) + return (seq[0], seq[1], seq[2]) + + +def _normalize_phase_diffusivities( + phase_diffusivities: Optional[Mapping[int, float]], +) -> dict[int, float]: + """Validate and normalise ``phase_diffusivities`` into ``dict[int, float]``.""" + if phase_diffusivities is None: + return {} + if not isinstance(phase_diffusivities, Mapping) or len(phase_diffusivities) == 0: + raise ValueError("phase_diffusivities must be a non-empty mapping {phase_id: coeff}") + out: dict[int, float] = {} + for k, v in phase_diffusivities.items(): + pid = int(k) + coeff = float(v) + if not np.isfinite(coeff) or coeff < 0.0: + raise ValueError( + f"Diffusivity for phase {pid} must be finite and >= 0, got {v!r}" + ) + out[pid] = coeff + return out + + def _parse_direction_int(d) -> int: """Parse a direction to an integer (0=x, 1=y, 2=z).""" if isinstance(d, int): - return d + if d in (0, 1, 2): + return d + raise ValueError(f"Unknown direction '{d}'. Use 'x', 'y', or 'z'.") if isinstance(d, str): key = d.strip().lower() if key in _DIR_MAP: return _DIR_MAP[key] - # Might be a _core.Direction enum try: return {"X": 0, "Y": 1, "Z": 2}[str(d).split(".")[-1]] except (KeyError, AttributeError): @@ -151,21 +299,10 @@ def _ensure_initialized(): def _parse_solver(s): - """Parse a solver string or SolverType enum value. - - The special value ``"auto"`` (and ``"mlmg"``) selects AMReX's matrix-free - geometric multigrid solver with face conductances on the voxel grid. - - Fallback Krylov solvers (PCG, FlexGMRES, BiCGSTAB, GMRES) and their - multigrid preconditioners (SMG, PFMG) remain available by name. The - recommended HYPRE fallback for users hitting MLMG convergence issues - is ``solver="pcg", preconditioner="smg"`` — slower but robust against - masked rows arising from porous-media inputs. - """ + """Parse a solver string or SolverType enum value.""" _core = _get_core() if isinstance(s, _core.SolverType): return s - # "auto" and "mlmg" both map to the matrix-free MLMG path. key = s.strip().lower() if isinstance(s, str) else s if isinstance(key, str) and key in ("mlmg", "auto"): return "mlmg" @@ -177,7 +314,7 @@ def _parse_solver(s): "bicgstab": _core.SolverType.BiCGSTAB, "smg": _core.SolverType.SMG, "pfmg": _core.SolverType.PFMG, - "hypre": _core.SolverType.FlexGMRES, # convenience alias for fastest HYPRE + "hypre": _core.SolverType.FlexGMRES, } if not isinstance(key, str) or key not in solver_map: raise ValueError( @@ -186,7 +323,29 @@ def _parse_solver(s): return solver_map[key] -# Krylov solvers that accept a multigrid preconditioner +def _parse_hypre_solver(s): + """Parse a HYPRE SolverType for homogenization / REV cell problems.""" + _core = _get_core() + if isinstance(s, _core.SolverType): + return s + key = s.strip().lower() if isinstance(s, str) else s + if isinstance(key, str) and key in ("auto", "hypre", "flexgmres"): + return _core.SolverType.FlexGMRES + solver_map = { + "jacobi": _core.SolverType.Jacobi, + "gmres": _core.SolverType.GMRES, + "pcg": _core.SolverType.PCG, + "bicgstab": _core.SolverType.BiCGSTAB, + "smg": _core.SolverType.SMG, + "pfmg": _core.SolverType.PFMG, + } + if not isinstance(key, str) or key not in solver_map: + raise ValueError( + f"Unknown homogenization solver '{s}'. Options: {list(solver_map) + ['flexgmres', 'auto']}" + ) + return solver_map[key] + + _KRYLOV_SOLVERS = {"pcg", "gmres", "flexgmres", "bicgstab"} @@ -206,13 +365,7 @@ def _parse_preconditioner(p): def _auto_grid_size(shape: tuple[int, ...]) -> int: - """Pick a good AMReX max_grid_size based on domain dimensions and MPI ranks. - - On a single MPI rank, keep domains up to 256^3 in a single contiguous box - (OpenMP tiling and GPU thread blocks provide intra-box parallelism without - cross-box ghost-exchange overhead). When multiple MPI ranks are active, - split into power-of-two boxes so AMReX can distribute boxes across ranks. - """ + """Pick a good AMReX max_grid_size based on domain dimensions and MPI ranks.""" n_max = max(shape) n_ranks = 1 if not _is_pure_python(): @@ -228,7 +381,7 @@ def _auto_grid_size(shape: tuple[int, ...]) -> int: total_voxels = int(np.prod(shape)) mgs = 16 for candidate in (128, 64, 32, 16): - if n_min >= candidate and (total_voxels // (candidate ** 3)) >= n_ranks: + if n_min >= candidate and (total_voxels // (candidate**3)) >= n_ranks: mgs = candidate break return mgs @@ -237,21 +390,29 @@ def _auto_grid_size(shape: tuple[int, ...]) -> int: def _numpy_to_voxelimage( data: np.ndarray, max_grid_size: Union[int, str] = "auto", + voxel_size: Optional[VoxelSizeArg] = None, ): - """Convert a 3-D int32 NumPy array to a VoxelImage (native C++ ingestion). - - Returns a VoxelImage handle that encapsulates all AMReX objects. - """ + """Convert a 3-D int32 NumPy array (or VoxelImage) into a VoxelImage with physical cell sizes.""" _core = _get_core() + if isinstance(data, _core.VoxelImage): + if voxel_size is None: + return data + dz, dy, dx = _normalize_voxel_size(voxel_size) + return data.with_voxel_size(dx=dx, dy=dy, dz=dz) + + if not isinstance(data, np.ndarray): + raise TypeError("data must be a 3-D NumPy array or a VoxelImage") + if data.ndim != 3: raise ValueError(f"Expected a 3-D array, got shape {data.shape}") if isinstance(max_grid_size, str) and max_grid_size.lower() == "auto": max_grid_size = _auto_grid_size(data.shape) - data = np.ascontiguousarray(data, dtype=np.int32) - return _core.VoxelImage.from_numpy(data, max_grid_size) + dz, dy, dx = _normalize_voxel_size(voxel_size) + arr = np.ascontiguousarray(data, dtype=np.int32) + return _core.VoxelImage.from_numpy(arr, max_grid_size, dx=dx, dy=dy, dz=dz) # --------------------------------------------------------------------------- @@ -264,38 +425,18 @@ def volume_fraction( *, max_grid_size: Union[int, str] = "auto", ) -> VolumeFractionResult: - """Compute the volume fraction of *phase* in a 3-D NumPy array. - - Parameters - ---------- - data : np.ndarray - 3-D integer array of phase IDs (shape: z, y, x). - phase : int - Phase ID to count. - max_grid_size : int or str - AMReX box decomposition size. ``'auto'`` picks based on domain size. - - Returns - ------- - VolumeFractionResult - """ + """Compute the volume fraction of *phase* in a 3-D NumPy array or VoxelImage.""" _ensure_initialized() if _is_pure_python(): from . import _solver - data = np.ascontiguousarray(data, dtype=np.int32) - pc, tc, frac = _solver.volume_fraction(data, phase) + + arr = np.ascontiguousarray(data, dtype=np.int32) + pc, tc, frac = _solver.volume_fraction(arr, phase) return VolumeFractionResult(phase_count=pc, total_count=tc, fraction=frac) _core = _get_core() - - if isinstance(data, np.ndarray): - img = _numpy_to_voxelimage(data, max_grid_size) - elif isinstance(data, _core.VoxelImage): - img = data - else: - raise TypeError("data must be a NumPy array or a VoxelImage") - + img = _numpy_to_voxelimage(data, max_grid_size) vf = _core.VolumeFraction(img, phase, 0) pc, tc = vf.value() frac = pc / tc if tc > 0 else 0.0 @@ -310,30 +451,15 @@ def percolation_check( max_grid_size: Union[int, str] = "auto", verbose: int = 0, ) -> PercolationResult: - """Check whether *phase* percolates across the domain in *direction*. - - Parameters - ---------- - data : np.ndarray - 3-D integer array of phase IDs. - phase : int - Phase ID to check. - direction : str or Direction - 'x', 'y', or 'z'. - max_grid_size : int or str - AMReX box decomposition size. ``'auto'`` picks based on domain size. - - Returns - ------- - PercolationResult - """ + """Check whether *phase* percolates across the domain in *direction*.""" _ensure_initialized() if _is_pure_python(): from . import _solver - data = np.ascontiguousarray(data, dtype=np.int32) + + arr = np.ascontiguousarray(data, dtype=np.int32) d = _parse_direction_int(direction) - percolates, active_vf, _ = _solver.percolation_check(data, phase, 2 - d) + percolates, active_vf, _ = _solver.percolation_check(arr, phase, 2 - d) return PercolationResult( percolates=percolates, active_volume_fraction=active_vf, @@ -342,14 +468,7 @@ def percolation_check( _core = _get_core() d = _parse_direction(direction) - - if isinstance(data, np.ndarray): - img = _numpy_to_voxelimage(data, max_grid_size) - elif isinstance(data, _core.VoxelImage): - img = data - else: - raise TypeError("data must be a NumPy array or a VoxelImage") - + img = _numpy_to_voxelimage(data, max_grid_size) pc = _core.PercolationCheck(img, phase, d, verbose) return PercolationResult( percolates=pc.percolates, @@ -364,6 +483,9 @@ def tortuosity( direction: Union[str, "Direction"] = "x", solver: Union[str, "SolverType"] = "auto", *, + voxel_size: Optional[VoxelSizeArg] = None, + phase_diffusivities: Optional[Mapping[int, float]] = None, + return_field: bool = False, preconditioner: Union[str, "PrecondType"] = "smg", max_grid_size: Union[int, str] = "auto", results_path: str = ".", @@ -372,58 +494,49 @@ def tortuosity( mlmg_maxiter: Optional[int] = None, mlmg_max_coarsening_level: Optional[int] = None, ) -> TortuosityResult: - """Compute the tortuosity of *phase* in *direction*. + """Compute steady-state tortuosity and effective diffusivity along *direction*. Parameters ---------- - data : np.ndarray - 3-D integer array of phase IDs. + data : np.ndarray or VoxelImage + 3-D integer array of phase IDs ``(Nz, Ny, Nx)`` or a ``VoxelImage`` handle. phase : int - Phase ID for the conducting phase. + Conducting phase ID when *phase_diffusivities* is ``None``. direction : str or Direction - Flow direction ('x', 'y', 'z'). + Flow direction (``'x'``, ``'y'``, or ``'z'``). solver : str or SolverType - Solver algorithm. ``'auto'`` (default) selects AMReX MLMG — - matrix-free geometric multigrid on the active voxel network. Explicit aliases: - ``'mlmg'`` (same as ``'auto'``); HYPRE Krylov methods - ``'flexgmres'``, ``'pcg'``, ``'gmres'``, ``'bicgstab'``; standalone - HYPRE multigrid ``'smg'``, ``'pfmg'``, ``'jacobi'``. Recommended - HYPRE fallback for diagnostic comparison: - ``solver='pcg', preconditioner='smg'``. - preconditioner : str or PrecondType, keyword-only - Multigrid preconditioner for Krylov solvers (PCG/GMRES/FlexGMRES/BiCGSTAB): - ``'smg'`` (default) or ``'pfmg'``. Ignored for standalone SMG/PFMG/Jacobi - and for MLMG. SMG is the default because its point-based smoothing - handles the decoupled inactive rows that arise from masked porous-media - inputs; PFMG's semicoarsening tends to stall on those rows and may not - converge. Use PFMG for fully-active grids (no masked cells) — it scales - better. Both work on CPU and GPU. - max_grid_size : int or str - AMReX box decomposition size. ``'auto'`` picks a value based on the - domain dimensions and active MPI rank count. - mlmg_eps, mlmg_maxiter, mlmg_max_coarsening_level - Tuning knobs for ``solver='mlmg'``. ``None`` leaves the C++ default - (``mlmg_eps=1e-8`` with GMRES-preconditioned MLMG and boundary-scaled - stopping tolerance, yielding ~8+ digits of tortuosity accuracy). - - Returns - ------- - TortuosityResult - - Raises - ------ - ConvergenceError - If the solver does not converge. - PercolationError - If the phase does not percolate in the given direction. + ``'auto'`` / ``'mlmg'`` (default matrix-free AMReX geometric multigrid), + or HYPRE solvers ``'pcg'``, ``'flexgmres'``, ``'gmres'``, ``'bicgstab'``, + ``'smg'``, ``'pfmg'``, ``'jacobi'``. + voxel_size : float or tuple of 3 floats, optional + Physical voxel spacing: either a scalar ``h`` (cubic voxels) or + ``(dz, dy, dx)`` matching NumPy ``(Nz, Ny, Nx)`` axis order. + phase_diffusivities : Mapping[int, float], optional + Multi-phase transport map ``{phase_id: D_phase}``. Phases with ``D > 0`` + participate in 6-connected transport with harmonic-mean face conductances; + unlisted phases or phases with ``D == 0`` are insulating. + return_field : bool + If ``True``, populate ``result.solution_field`` with the solved 3-D + potential field ``(Nz, Ny, Nx)`` (``float64``). Defaults to ``False`` + to avoid host memory copies on large grids. """ _ensure_initialized() + phase_map = _normalize_phase_diffusivities(phase_diffusivities) if _is_pure_python(): from . import _solver - data = np.ascontiguousarray(data, dtype=np.int32) + + arr = np.ascontiguousarray(data, dtype=np.int32) + vz = _normalize_voxel_size(voxel_size) d = _parse_direction_int(direction) - result = _solver.solve_tortuosity(data, phase, 2 - d) + result = _solver.solve_tortuosity( + arr, + phase=phase, + direction=2 - d, + voxel_size=vz, + phase_diffusivities=phase_map if phase_map else None, + return_field=return_field, + ) if not result["solver_converged"]: raise ConvergenceError( f"Solver did not converge after {result['iterations']} " @@ -437,24 +550,25 @@ def tortuosity( flux_in=result["flux_in"], flux_out=result["flux_out"], active_volume_fraction=result["active_volume_fraction"], - solution_field=result["solution_field"], + solution_field=result["solution_field"] if return_field else None, + effective_diffusivity=result["effective_diffusivity"], ) # --- C++ backend path --- _core = _get_core() d = _parse_direction(direction) st = _parse_solver(solver) + img = _numpy_to_voxelimage(data, max_grid_size, voxel_size=voxel_size) - if isinstance(data, np.ndarray): - img = _numpy_to_voxelimage(data, max_grid_size) - elif isinstance(data, _core.VoxelImage): - img = data + if phase_map: + vf_val = sum( + _core.VolumeFraction(img, pid, 0).value_vf() + for pid, coeff in phase_map.items() + if coeff > 0.0 + ) else: - raise TypeError("data must be a NumPy array or a VoxelImage") + vf_val = _core.VolumeFraction(img, phase, 0).value_vf() - # Volume fraction (cheap — pure counting, no flood fill) - vf_calc = _core.VolumeFraction(img, phase, 0) - vf_val = vf_calc.value_vf() if vf_val <= 0.0: dir_name = _core.PercolationCheck.direction_string(d) raise PercolationError( @@ -463,12 +577,7 @@ def tortuosity( f"disconnected between the inlet and outlet faces." ) - # Route to the appropriate solver backend. - # Both TortuosityMLMG and TortuosityHypre compute the two-sided flood-fill - # activity mask in their constructors and return early (skipping matrix - # assembly) when active_volume_fraction == 0, avoiding duplicate flood fills. if st == "mlmg": - # Matrix-free AMReX MLMG solver — no HYPRE, lower memory mlmg_kwargs = {} if mlmg_eps is not None: mlmg_kwargs["eps"] = float(mlmg_eps) @@ -476,19 +585,35 @@ def tortuosity( mlmg_kwargs["maxiter"] = int(mlmg_maxiter) if mlmg_max_coarsening_level is not None: mlmg_kwargs["max_coarsening_level"] = int(mlmg_max_coarsening_level) + if phase_map: + mlmg_kwargs["phase_coeffs"] = phase_map solver_obj = _core.TortuosityMLMG( - img, vf_val, phase, d, results_path, - 0.0, 1.0, verbose, False, + img, + vf_val, + phase, + d, + results_path, + 0.0, + 1.0, + verbose, + False, **mlmg_kwargs, ) else: - # HYPRE-based solver (PCG, FlexGMRES, etc.). The preconditioner is applied - # to Krylov solvers; HYPRE ignores it for standalone SMG/PFMG/Jacobi. pc = _parse_preconditioner(preconditioner) solver_obj = _core.TortuosityHypre( - img, vf_val, phase, d, st, results_path, - 0.0, 1.0, verbose, False, + img, + vf_val, + phase, + d, + st, + results_path, + 0.0, + 1.0, + verbose, + False, pc, + phase_map, ) if solver_obj.active_volume_fraction <= 0.0: @@ -511,6 +636,8 @@ def tortuosity( f"iterations (residual={solver_obj.residual_norm:.2e})" ) + field = solver_obj.solution_field() if return_field else None + return TortuosityResult( tortuosity=tau, solver_converged=solver_obj.solver_converged, @@ -519,32 +646,421 @@ def tortuosity( flux_in=solver_obj.flux_in, flux_out=solver_obj.flux_out, active_volume_fraction=solver_obj.active_volume_fraction, + solution_field=field, + effective_diffusivity=float(solver_obj.effective_diffusivity), ) +def effective_diffusivity( + data: np.ndarray, + phase: int = 1, + *, + voxel_size: Optional[VoxelSizeArg] = None, + phase_diffusivities: Optional[Mapping[int, float]] = None, + solver: Union[str, "SolverType"] = "flexgmres", + return_fields: bool = False, + max_grid_size: Union[int, str] = "auto", + results_path: str = ".", + verbose: int = 0, +) -> EffectiveDiffusivityResult: + """Compute the full 3x3 homogenised effective-diffusivity tensor ``D_eff``. + + Solves the three periodic homogenisation cell problems in ``x``, ``y``, ``z`` + and returns ``EffectiveDiffusivityResult`` with ``tensor`` ordered ``(x, y, z)``. + """ + _ensure_initialized() + phase_map = _normalize_phase_diffusivities(phase_diffusivities) + + if _is_pure_python(): + from . import _solver + + arr = np.ascontiguousarray(data, dtype=np.int32) + vz = _normalize_voxel_size(voxel_size) + raw = _solver.solve_effective_diffusivity( + arr, + phase=phase, + voxel_size=vz, + phase_diffusivities=phase_map if phase_map else None, + return_chi=return_fields, + ) + if not raw["converged"]: + raise ConvergenceError( + f"Effective diffusivity cell-problem solver failed to converge " + f"(residuals={raw['residuals']})" + ) + return EffectiveDiffusivityResult( + tensor=np.asarray(raw["tensor"], dtype=np.float64), + active_volume_fraction=float(raw["active_volume_fraction"]), + solver_converged=bool(raw["converged"]), + iterations=tuple(int(i) for i in raw["iterations"]), + residuals=tuple(float(r) for r in raw["residuals"]), + corrector_fields=raw.get("chi") if return_fields else None, + ) + + _core = _get_core() + st = _parse_hypre_solver(solver) + img = _numpy_to_voxelimage(data, max_grid_size, voxel_size=voxel_size) + raw = _core.compute_effective_diffusivity_tensor( + img, + phase_id=phase, + solver_type=st, + results_path=results_path, + verbose=verbose, + write_plotfile=False, + phase_coeffs=phase_map, + return_chi=return_fields, + ) + if not raw["converged"]: + raise ConvergenceError( + f"Effective diffusivity HYPRE cell-problem solver failed to converge " + f"(iterations={raw['iterations']}, residuals={raw['residuals']})" + ) + return EffectiveDiffusivityResult( + tensor=np.asarray(raw["tensor"], dtype=np.float64), + active_volume_fraction=float(raw["active_volume_fraction"]), + solver_converged=bool(raw["converged"]), + iterations=tuple(int(i) for i in raw["iterations"]), + residuals=tuple(float(r) for r in raw["residuals"]), + corrector_fields=dict(raw["chi"]) if return_fields else None, + ) + + +def specific_surface_area( + data: np.ndarray, + phase_a: int = 0, + phase_b: int = 1, + *, + voxel_size: Optional[VoxelSizeArg] = None, + boundary_padding: int = 0, + max_grid_size: Union[int, str] = "auto", +) -> SpecificSurfaceAreaResult: + """Compute interfacial specific surface area between *phase_a* and *phase_b*.""" + _ensure_initialized() + if boundary_padding < 0: + raise ValueError(f"boundary_padding must be >= 0, got {boundary_padding}") + + if _is_pure_python(): + from . import _solver + + arr = np.ascontiguousarray(data, dtype=np.int32) + vz = _normalize_voxel_size(voxel_size) + raw = _solver.specific_surface_area( + arr, phase_a=phase_a, phase_b=phase_b, voxel_size=vz, boundary_padding=boundary_padding + ) + return SpecificSurfaceAreaResult( + ssa=raw["ssa"], + ssa_corrected=raw["ssa_corrected"], + ssa_voxel=raw["ssa_voxel"], + ssa_voxel_corrected=raw["ssa_voxel_corrected"], + face_count=raw["face_count"], + total_count=raw["total_count"], + face_counts_xyz=raw["face_counts_xyz"], + ) + + _core = _get_core() + img = _numpy_to_voxelimage(data, max_grid_size, voxel_size=voxel_size) + dom_shape = img.shape # (nz, ny, nx) + if boundary_padding > 0 and any(s <= 2 * boundary_padding for s in dom_shape): + raise ValueError( + f"boundary_padding={boundary_padding} is too large for domain of shape {dom_shape}" + ) + + calc = _core.SpecificSurfaceArea( + img, phase_a=phase_a, phase_b=phase_b, comp=0, boundary_padding=boundary_padding + ) + (fx, fy, fz), tc = calc.direction_face_counts() + fc = int(fx + fy + fz) + ssa_vox = float(fc) / float(tc) if tc > 0 else 0.0 + dx, dy, dz = img.cell_size_xyz + ssa_phys = (fx / dx + fy / dy + fz / dz) / float(tc) if tc > 0 else 0.0 + + return SpecificSurfaceAreaResult( + ssa=float(ssa_phys), + ssa_corrected=(2.0 / 3.0) * float(ssa_phys), + ssa_voxel=ssa_vox, + ssa_voxel_corrected=(2.0 / 3.0) * ssa_vox, + face_count=fc, + total_count=int(tc), + face_counts_xyz=(int(fx), int(fy), int(fz)), + ) + + +def connected_components( + data: np.ndarray, + phase: int = 1, + *, + return_labels: bool = False, + max_grid_size: Union[int, str] = "auto", + verbose: int = 0, +) -> ConnectedComponentsResult: + """Label 6-connected components of *phase*.""" + _ensure_initialized() + + if _is_pure_python(): + from . import _solver + + arr = np.ascontiguousarray(data, dtype=np.int32) + n_comp, vols, labels = _solver.connected_components( + arr, phase=phase, return_labels=return_labels + ) + return ConnectedComponentsResult( + num_components=n_comp, + volumes=vols, + labels=labels, + ) + + _core = _get_core() + img = _numpy_to_voxelimage(data, max_grid_size) + ccl = _core.ConnectedComponents(img, phase_id=phase, verbose=verbose) + vols = np.asarray(ccl.component_volumes, dtype=np.int64) + labels = ccl.label_field() if return_labels else None + return ConnectedComponentsResult( + num_components=int(ccl.num_components), + volumes=vols, + labels=labels, + ) + + +def particle_size_distribution( + data: np.ndarray, + phase: int = 1, + *, + voxel_size: Optional[VoxelSizeArg] = None, + max_grid_size: Union[int, str] = "auto", + verbose: int = 0, +) -> ParticleSizeDistributionResult: + """Compute equivalent-sphere radii ``R = (3V / (4*pi))^(1/3)`` of 6-connected components.""" + _ensure_initialized() + + if _is_pure_python(): + from . import _solver + + arr = np.ascontiguousarray(data, dtype=np.int32) + vz = _normalize_voxel_size(voxel_size) + raw = _solver.particle_size_distribution(arr, phase=phase, voxel_size=vz) + return ParticleSizeDistributionResult( + num_particles=raw["num_particles"], + mean_radius=raw["mean_radius"], + radii=raw["radii"], + volumes=raw["volumes"], + radii_voxels=raw["radii_voxels"], + volumes_voxels=raw["volumes_voxels"], + ) + + _core = _get_core() + img = _numpy_to_voxelimage(data, max_grid_size, voxel_size=voxel_size) + psd = _core.ParticleSizeDistribution(img, phase_id=phase, verbose=verbose) + dx, dy, dz = img.cell_size_xyz + cell_vol = float(dx * dy * dz) + length_scale = cell_vol ** (1.0 / 3.0) + + radii_vox = np.asarray(psd.radii, dtype=np.float64) + vols_vox = np.asarray(psd.volumes, dtype=np.int64) + radii_phys = radii_vox * length_scale + vols_phys = vols_vox.astype(np.float64) * cell_vol + mean_r_phys = float(psd.mean_radius) * length_scale + + return ParticleSizeDistributionResult( + num_particles=int(psd.num_particles), + mean_radius=mean_r_phys, + radii=radii_phys, + volumes=vols_phys, + radii_voxels=radii_vox, + volumes_voxels=vols_vox, + ) + + +def through_thickness_profile( + data: np.ndarray, + phase: int = 1, + direction: Union[str, "Direction"] = "x", + *, + voxel_size: Optional[VoxelSizeArg] = None, + max_grid_size: Union[int, str] = "auto", +) -> ThroughThicknessResult: + """Compute slice-by-slice volume fraction profile of *phase* along *direction*.""" + _ensure_initialized() + d_int = _parse_direction_int(direction) + dir_label = _DIR_NAMES[d_int] + + if _is_pure_python(): + from . import _solver + + arr = np.ascontiguousarray(data, dtype=np.int32) + vz = _normalize_voxel_size(voxel_size) + prof, pos = _solver.through_thickness_profile( + arr, phase=phase, direction_xyz=d_int, voxel_size=vz + ) + return ThroughThicknessResult( + direction=dir_label, + num_slices=int(len(prof)), + profile=prof, + positions=pos, + ) + + _core = _get_core() + d_enum = _parse_direction(dir_label) + img = _numpy_to_voxelimage(data, max_grid_size, voxel_size=voxel_size) + ttp = _core.ThroughThicknessProfile(img, phase_id=phase, dir=d_enum, comp=0) + prof = np.asarray(ttp.volume_fraction_profile, dtype=np.float64) + cs_xyz = img.cell_size_xyz + h = float(cs_xyz[d_int]) + pos = (np.arange(len(prof), dtype=np.float64) + 0.5) * h + return ThroughThicknessResult( + direction=dir_label, + num_slices=int(ttp.num_slices), + profile=prof, + positions=pos, + ) + + +def _summarize_rev_records( + records: list[dict], csv_path: Optional[str] +) -> REVStudyResult: + seen_sizes: list[int] = [] + grouped: dict[int, list[np.ndarray]] = {} + for rec in records: + sz = int(rec["target_size"]) + if sz not in grouped: + seen_sizes.append(sz) + grouped[sz] = [] + grouped[sz].append( + np.array([rec["D_xx"], rec["D_yy"], rec["D_zz"]], dtype=np.float64) + ) + + mean_diag: dict[int, np.ndarray] = {} + std_diag: dict[int, np.ndarray] = {} + for sz in seen_sizes: + arr = np.vstack(grouped[sz]) + mean_diag[sz] = np.mean(arr, axis=0) + std_diag[sz] = np.std(arr, axis=0) + + return REVStudyResult( + sizes=seen_sizes, + samples=records, + mean_diagonal=mean_diag, + std_diagonal=std_diag, + csv_path=csv_path, + ) + + +def rev_study( + data: np.ndarray, + sizes: Sequence[int], + *, + num_samples: int = 3, + phase: int = 1, + voxel_size: Optional[VoxelSizeArg] = None, + solver: Union[str, "SolverType"] = "flexgmres", + csv_path: Optional[str] = None, + max_grid_size: Union[int, str] = "auto", + verbose: int = 0, +) -> REVStudyResult: + """Run a Representative Elementary Volume (REV) convergence study.""" + _ensure_initialized() + size_list = [int(s) for s in sizes if int(s) > 0] + if not size_list: + return REVStudyResult( + sizes=[], samples=[], mean_diagonal={}, std_diagonal={}, csv_path=csv_path + ) + + if _is_pure_python(): + from . import _solver + + arr = np.ascontiguousarray(data, dtype=np.int32) + vz = _normalize_voxel_size(voxel_size) + records = _solver.rev_study( + arr, + sizes=size_list, + num_samples=num_samples, + phase=phase, + voxel_size=vz, + csv_path=csv_path, + ) + return _summarize_rev_records(records, csv_path) + + _core = _get_core() + st = _parse_hypre_solver(solver) + img = _numpy_to_voxelimage(data, max_grid_size, voxel_size=voxel_size) + box_sz = 32 if isinstance(max_grid_size, str) else int(max_grid_size) + + def _parse_csv_text(csv_text: str) -> list[dict]: + rows: list[dict] = [] + if not csv_text.strip(): + return rows + reader = csv.DictReader(csv_text.splitlines()) + for r in reader: + dxx = float(r["D_xx"]) + dyy = float(r["D_yy"]) + dzz = float(r["D_zz"]) + dxy = float(r["D_xy"]) + dxz = float(r["D_xz"]) + dyz = float(r["D_yz"]) + tensor = np.array( + [[dxx, dxy, dxz], [dxy, dyy, dyz], [dxz, dyz, dzz]], + dtype=np.float64, + ) + rows.append( + { + "sample": int(r["SampleNo"]), + "seed_xyz": (int(r["SeedX"]), int(r["SeedY"]), int(r["SeedZ"])), + "target_size": int(r["REV_Size_Target"]), + "actual_size_xyz": ( + int(r["ActualSizeX"]), + int(r["ActualSizeY"]), + int(r["ActualSizeZ"]), + ), + "D_xx": dxx, + "D_yy": dyy, + "D_zz": dzz, + "D_xy": dxy, + "D_xz": dxz, + "D_yz": dyz, + "tensor": tensor, + } + ) + return rows + + if csv_path is not None: + target_p = Path(csv_path) + target_p.parent.mkdir(parents=True, exist_ok=True) + _written, csv_content = _core.run_rev_study( + img, + sizes=size_list, + num_samples=num_samples, + phase_id=phase, + box_size=box_sz, + solver_type=st, + results_path=str(target_p.parent), + csv_filename=target_p.name, + verbose=verbose, + write_plotfiles=False, + ) + records = _parse_csv_text(csv_content) + return _summarize_rev_records(records, str(target_p)) + + with tempfile.TemporaryDirectory() as tmpdir: + _written, csv_content = _core.run_rev_study( + img, + sizes=size_list, + num_samples=num_samples, + phase_id=phase, + box_size=box_sz, + solver_type=st, + results_path=tmpdir, + csv_filename="rev_study_Deff.csv", + verbose=verbose, + write_plotfiles=False, + ) + records = _parse_csv_text(csv_content) + return _summarize_rev_records(records, None) + + def estimate_memory( shape: tuple[int, ...], num_ranks: int = 1, ) -> dict: - """Estimate per-rank memory usage for a tortuosity solve. - - Uses the rule of thumb: ~80 bytes per active voxel (4 bytes phase data, - 56 bytes HYPRE matrix for 7-point stencil, 8 bytes solution field, - ~12 bytes work arrays and ghost cells). - - Parameters - ---------- - shape : tuple of int - Domain dimensions (Nz, Ny, Nx). - num_ranks : int - Number of MPI ranks. - - Returns - ------- - dict - Keys: ``total_voxels``, ``voxels_per_rank``, ``bytes_per_rank``, - ``mb_per_rank``, ``gb_per_rank``, ``num_ranks``. - """ + """Estimate per-rank memory usage for a tortuosity solve.""" total = int(np.prod(shape)) per_rank = total / max(num_ranks, 1) bytes_per_rank = per_rank * 80 @@ -559,32 +1075,13 @@ def estimate_memory( def build_info() -> dict: - """Return compile-time + runtime feature flags for the installed wheel. - - Critical for Colab users who need to verify they got the GPU wheel - (``pip install openimpala-cuda``) and not the default CPU wheel. - - Returns - ------- - dict - Keys: - - * ``backend``: ``"cpp-cuda"``, ``"cpp-hip"``, ``"cpp-cpu"``, or ``"pure-python"`` - * ``cuda_enabled`` / ``hip_enabled`` / ``gpu_enabled``: bool - * ``openmp_enabled``: bool; ``openmp_max_threads``: int - * ``mpi_enabled``: bool - * ``tiny_profile``: bool (BL_PROFILE regions emit a table at shutdown) - * ``hypre_cuda`` / ``hypre_hip``: bool (HYPRE solver device support) - * ``gpu_device_count``: int (runtime — ``-1`` if AMReX not yet initialised) - * ``version``: str (package version) - """ + """Return compile-time + runtime feature flags for the installed wheel.""" from . import __version__ if _is_pure_python() or not _has_core(): - # Pure-Python fallback (SciPy/CuPy) — no compiled backend at all. - # CuPy CG is GPU-accelerated but has no OpenMP / HYPRE / TinyProfile. try: import cupy # noqa: F401 + has_cupy = True except ImportError: has_cupy = False @@ -620,6 +1117,7 @@ def read_image( path: str, threshold: float = 0.5, *, + voxel_size: Optional[VoxelSizeArg] = None, file_format: Optional[str] = None, hdf5_dataset: str = "/data", raw_width: int = 0, @@ -628,27 +1126,7 @@ def read_image( raw_data_type=None, max_grid_size: Union[int, str] = "auto", ) -> tuple: - """Read a 3-D image file and threshold it into a VoxelImage. - - Automatically detects format from the file extension unless *file_format* - is explicitly set. - - Parameters - ---------- - path : str - Path to the image file. - threshold : float - Threshold value for binarisation. - file_format : str, optional - Force format: 'tiff', 'hdf5', 'raw', or 'dat'. - max_grid_size : int or str - AMReX box decomposition size. ``'auto'`` picks based on domain size. - - Returns - ------- - (reader, VoxelImage) - The reader object and the VoxelImage handle. - """ + """Read a 3-D image file and threshold it into a VoxelImage.""" _ensure_initialized() if _is_pure_python(): @@ -663,7 +1141,6 @@ def read_image( if raw_data_type is None: raw_data_type = _core.RawDataType.UINT8 - # Auto-detect format if file_format is None: lower = path.lower() if lower.endswith((".tif", ".tiff")): @@ -677,7 +1154,6 @@ def read_image( else: raise ValueError(f"Cannot auto-detect format for '{path}'. Set file_format explicitly.") - # Create reader and read metadata if file_format == "tiff": reader = _core.TiffReader(path) elif file_format == "hdf5": @@ -689,11 +1165,12 @@ def read_image( else: raise ValueError(f"Unknown file_format '{file_format}'") - # Resolve "auto" — keep single-rank file reads in large contiguous boxes. if isinstance(max_grid_size, str) and max_grid_size.lower() == "auto": max_grid_size = 256 if _core.mpi_ranks() <= 1 else 64 - # Threshold directly into a VoxelImage (all AMReX setup happens in C++) img = reader.threshold(threshold, max_grid_size) + if voxel_size is not None: + dz, dy, dx = _normalize_voxel_size(voxel_size) + img = img.with_voxel_size(dx=dx, dy=dy, dz=dz) return reader, img diff --git a/python/tests/test_mpi_smoke.py b/python/tests/test_mpi_smoke.py index 102badf..78d9bd7 100644 --- a/python/tests/test_mpi_smoke.py +++ b/python/tests/test_mpi_smoke.py @@ -68,3 +68,39 @@ def test_mpi_distributed_tiff_reader(): assert perc.percolates is True assert perc.active_volume_fraction == pytest.approx(0.397743, rel=1e-6) del reader, img + + +def test_mpi_v460_fields_and_metrics(): + """Verify multi-rank gathering of 3-D fields, labels, SSA, profiles, and D_eff tensor.""" + data = np.zeros((16, 16, 16), dtype=np.int32) + data[:, :, 8:] = 1 + data[2:5, 2:5, 2:5] = 2 # 27-voxel isolated inclusion + + ssa = oi.specific_surface_area( + data, phase_a=0, phase_b=1, voxel_size=(2.0, 1.0, 0.5), max_grid_size=8 + ) + assert ssa.face_counts_xyz == (256, 0, 0) + assert ssa.ssa == pytest.approx((256.0 / 0.5) / float(16**3), rel=1e-10) + + ccl = oi.connected_components(data, phase=2, return_labels=True, max_grid_size=8) + assert ccl.num_components == 1 + assert ccl.volumes.tolist() == [27] + assert ccl.labels is not None + assert int(np.count_nonzero(ccl.labels == 1)) == 27 + + tau = oi.tortuosity( + data, + direction="x", + phase_diffusivities={0: 1.0, 1: 0.25, 2: 1.0}, + return_field=True, + max_grid_size=8, + ) + assert tau.effective_diffusivity == pytest.approx(0.4, rel=1e-5) + assert tau.solution_field is not None + assert tau.solution_field.shape == (16, 16, 16) + assert np.all((tau.solution_field > 0.0) & (tau.solution_field < 1.0)) + + deff = oi.effective_diffusivity( + np.ones((12, 12, 12), dtype=np.int32), phase=1, max_grid_size=6 + ) + np.testing.assert_allclose(deff.tensor, np.eye(3), atol=1e-5) diff --git a/python/tests/test_v460_features.py b/python/tests/test_v460_features.py new file mode 100644 index 0000000..2928364 --- /dev/null +++ b/python/tests/test_v460_features.py @@ -0,0 +1,328 @@ +"""Comprehensive tests for OpenImpala v4.6.0 Python API features: + 1. 3-D solution field output (return_field=True / False) + 2. Multi-phase variable-diffusivity transport (phase_diffusivities) + 3. Non-cubic / anisotropic and physical SI voxel_size support + 4. Full 3x3 homogenised effective diffusivity tensor (effective_diffusivity) + 5. Microstructural metrics (specific_surface_area, connected_components, + particle_size_distribution, through_thickness_profile, rev_study) + 6. C++ (_core) vs pure-Python (_solver) parity when _core is compiled +""" + +from __future__ import annotations + +from pathlib import Path + +import numpy as np +import pytest + +import openimpala as oi +from openimpala import _solver +from openimpala.session import Session, _has_core + + +SOLVERS_TO_TEST = ["auto", "pcg"] if _has_core() else ["auto"] + + +class TestSolutionFieldOutput: + """Tests for return_field=False (default) and return_field=True.""" + + def test_default_does_not_materialize_field(self, uniform_block): + res = oi.tortuosity(uniform_block, phase=0, direction="x") + assert res.solution_field is None + assert res.effective_diffusivity == pytest.approx(1.0, rel=1e-6) + + @pytest.mark.parametrize("direction", ["x", "y", "z"]) + @pytest.mark.parametrize("solver", SOLVERS_TO_TEST) + def test_linear_potential_profile_on_uniform_block(self, direction, solver): + n = 12 + data = np.zeros((n, n, n), dtype=np.int32) + res = oi.tortuosity( + data, phase=0, direction=direction, solver=solver, return_field=True + ) + assert res.solution_field is not None + assert res.solution_field.shape == (n, n, n) + assert res.solution_field.dtype == np.float64 + + axis = {"z": 0, "y": 1, "x": 2}[direction] + expected_1d = (np.arange(n, dtype=np.float64) + 0.5) / float(n) + slice_means = np.mean( + res.solution_field, axis=tuple(a for a in range(3) if a != axis) + ) + np.testing.assert_allclose(slice_means, expected_1d, atol=1e-5) + + def test_inactive_voxels_zero_in_solution_field(self, connected_channel): + res = oi.tortuosity( + connected_channel, phase=0, direction="x", return_field=True + ) + assert res.solution_field is not None + solid_vals = res.solution_field[connected_channel != 0] + np.testing.assert_allclose(solid_vals, 0.0, atol=1e-12) + channel_vals = res.solution_field[connected_channel == 0] + assert np.all((channel_vals > 0.0) & (channel_vals < 1.0)) + + +class TestMultiPhaseTransport: + """Analytical Reuss (series) and Voigt (parallel) multi-phase transport tests.""" + + @pytest.mark.parametrize("solver", SOLVERS_TO_TEST) + def test_series_laminate_harmonic_mean(self, solver): + # Layers perpendicular to X: x < 8 has D=1.0 (phase 1), x >= 8 has D=0.25 (phase 2) + # Exact harmonic mean: D_eff = 2 * 1.0 * 0.25 / (1.0 + 0.25) = 0.4, tau = 1.0 / 0.4 = 2.5 + data = np.ones((8, 8, 16), dtype=np.int32) + data[:, :, 8:] = 2 + res = oi.tortuosity( + data, + direction="x", + solver=solver, + phase_diffusivities={1: 1.0, 2: 0.25}, + return_field=True, + ) + assert res.solver_converged + assert res.active_volume_fraction == pytest.approx(1.0, rel=1e-6) + assert res.effective_diffusivity == pytest.approx(0.4, rel=1e-5) + assert res.tortuosity == pytest.approx(2.5, rel=1e-5) + assert res.solution_field is not None + + @pytest.mark.parametrize("solver", SOLVERS_TO_TEST) + def test_parallel_laminate_arithmetic_mean(self, solver): + # Layers parallel to X (split along Y): y < 4 has D=1.0, y >= 4 has D=0.5 + # Exact arithmetic mean: D_eff = 0.5 * (1.0 + 0.5) = 0.75, tau = 1.0 / 0.75 = 4/3 + data = np.ones((8, 8, 16), dtype=np.int32) + data[:, 4:, :] = 2 + res = oi.tortuosity( + data, + direction="x", + solver=solver, + phase_diffusivities={1: 1.0, 2: 0.5}, + ) + assert res.solver_converged + assert res.effective_diffusivity == pytest.approx(0.75, rel=1e-5) + assert res.tortuosity == pytest.approx(4.0 / 3.0, rel=1e-5) + + @pytest.mark.parametrize("solver", SOLVERS_TO_TEST) + def test_physical_si_diffusivity_and_insulating_solid(self, solver): + # Three-phase battery electrode style: pore (1: 2e-10 m^2/s), CBD (2: 5e-11 m^2/s), AM (0: 0) + # Parallel channels along Z: 25% pore, 25% CBD, 50% solid AM + # Exact D_eff = 0.25 * 2e-10 + 0.25 * 5e-11 = 6.25e-11 m^2/s, active_vf = 0.5 + data = np.zeros((16, 8, 8), dtype=np.int32) + data[:, 0:2, :] = 1 + data[:, 2:4, :] = 2 + res = oi.tortuosity( + data, + direction="z", + solver=solver, + voxel_size=50e-9, + phase_diffusivities={0: 0.0, 1: 2.0e-10, 2: 0.5e-10}, + ) + assert res.solver_converged + assert res.active_volume_fraction == pytest.approx(0.5, rel=1e-6) + assert res.effective_diffusivity == pytest.approx(6.25e-11, rel=1e-4) + + +class TestAnisotropicVoxelSize: + """Tests for scalar SI voxel_size and anisotropic (dz, dy, dx) voxel_size.""" + + @pytest.mark.parametrize("solver", SOLVERS_TO_TEST) + def test_isotropic_scale_invariance_on_porous_media(self, solver): + with np.load(Path(__file__).parent / "data" / "porous24.npz") as fixture: + image = fixture["pore"].astype(np.int32) + + res_unit = oi.tortuosity(image, phase=1, direction="z", solver=solver) + res_nm = oi.tortuosity( + image, phase=1, direction="z", solver=solver, voxel_size=50e-9 + ) + assert res_nm.tortuosity == pytest.approx(res_unit.tortuosity, rel=1e-5) + assert res_nm.effective_diffusivity == pytest.approx( + res_unit.effective_diffusivity, rel=1e-5 + ) + + @pytest.mark.parametrize("solver", SOLVERS_TO_TEST) + def test_anisotropic_tortuosity_sensitivity(self, solver): + # Zig-zag / obstructed path where lateral Y detour distance depends on dy vs dx + data = np.ones((8, 12, 12), dtype=np.int32) + data[:, :7, 4] = 0 # baffle 1 forcing flow to high Y + data[:, 5:, 8] = 0 # baffle 2 forcing flow back to low Y + + tau_fine_y = oi.tortuosity( + data, phase=1, direction="x", solver=solver, voxel_size=(1.0, 0.5, 1.0) + ).tortuosity + tau_coarse_y = oi.tortuosity( + data, phase=1, direction="x", solver=solver, voxel_size=(1.0, 2.0, 1.0) + ).tortuosity + # Stretching dy increases lateral detour length relative to axial length -> higher tortuosity + assert tau_coarse_y > tau_fine_y * 1.3 + + def test_invalid_voxel_size_raises(self, uniform_block): + with pytest.raises(ValueError): + oi.tortuosity(uniform_block, phase=0, voxel_size=-1.0) + with pytest.raises(ValueError): + oi.tortuosity(uniform_block, phase=0, voxel_size=(1.0, 0.0, 1.0)) + with pytest.raises(ValueError): + oi.tortuosity(uniform_block, phase=0, voxel_size=(1.0, 2.0)) + + +class TestEffectiveDiffusivityTensor: + """Tests for 3x3 periodic homogenisation D_eff tensor.""" + + def test_uniform_medium_is_identity(self): + data = np.ones((10, 10, 10), dtype=np.int32) + res = oi.effective_diffusivity(data, phase=1, return_fields=True) + assert res.solver_converged + assert res.active_volume_fraction == pytest.approx(1.0) + np.testing.assert_allclose(res.tensor, np.eye(3), atol=1e-6) + assert res.corrector_fields is not None + assert set(res.corrector_fields.keys()) == {"x", "y", "z"} + assert res.corrector_fields["x"].shape == (10, 10, 10) + + def test_empty_phase_returns_zero_tensor(self): + data = np.zeros((8, 8, 8), dtype=np.int32) + res = oi.effective_diffusivity(data, phase=1) + assert res.solver_converged + assert res.active_volume_fraction == 0.0 + np.testing.assert_allclose(res.tensor, np.zeros((3, 3)), atol=1e-12) + + def test_diagonal_channels_off_diagonal_symmetry(self): + # Periodic 45-degree diagonal sheets in the (x, y) plane: (ix - iy) % 4 < 2 + # Transport is preferential along x+y => D_xy = D_yx > 0 and D_xx == D_yy, D_xz == D_yz == 0 + nz, ny, nx = 8, 12, 12 + iz, iy, ix = np.meshgrid( + np.arange(nz), np.arange(ny), np.arange(nx), indexing="ij" + ) + data = (((ix - iy) % 4) < 2).astype(np.int32) + + res = oi.effective_diffusivity(data, phase=1) + assert res.solver_converged + D = res.tensor + np.testing.assert_allclose(D, D.T, atol=1e-6) + assert D[0, 0] == pytest.approx(D[1, 1], rel=1e-5) + assert D[2, 2] == pytest.approx(0.5, rel=1e-5) + assert D[0, 1] > 0.02 + assert abs(D[0, 2]) < 1e-6 + assert abs(D[1, 2]) < 1e-6 + + +class TestMicrostructuralMetrics: + """Tests for SSA, CCL, PSD, through-thickness profile, and REV study.""" + + def test_specific_surface_area_planar_and_anisotropic(self): + # Single planar interface normal to X (between ix=3 and ix=4 in an 8x8x8 cube): + # 8*8 = 64 x-normal faces, 0 y-faces, 0 z-faces; total_count = 512. + data = np.zeros((8, 8, 8), dtype=np.int32) + data[:, :, 4:] = 1 + + ssa_unit = oi.specific_surface_area(data, phase_a=0, phase_b=1) + assert ssa_unit.face_count == 64 + assert ssa_unit.face_counts_xyz == (64, 0, 0) + assert ssa_unit.total_count == 512 + assert ssa_unit.ssa == pytest.approx(64.0 / 512.0, rel=1e-12) + assert ssa_unit.ssa_corrected == pytest.approx((2.0 / 3.0) * 64.0 / 512.0, rel=1e-12) + + # With anisotropic voxel_size = (dz=5.0, dy=3.0, dx=0.25): + # Physical area = 64 * (dy * dz), physical volume = 512 * (dx * dy * dz) + # => SSA_phys = 64 / (512 * dx) = 0.125 / 0.25 = 0.5 + ssa_aniso = oi.specific_surface_area( + data, phase_a=0, phase_b=1, voxel_size=(5.0, 3.0, 0.25) + ) + assert ssa_aniso.ssa_voxel == pytest.approx(0.125, rel=1e-12) + assert ssa_aniso.ssa == pytest.approx(0.5, rel=1e-12) + + def test_connected_components_and_psd(self): + data = np.zeros((12, 12, 12), dtype=np.int32) + data[1:3, 1:3, 1:3] = 1 # 2x2x2 = 8 voxels + data[6:9, 6:9, 6:9] = 1 # 3x3x3 = 27 voxels + + ccl = oi.connected_components(data, phase=1, return_labels=True) + assert ccl.num_components == 2 + assert sorted(ccl.volumes.tolist()) == [8, 27] + assert ccl.labels is not None + assert ccl.labels.shape == (12, 12, 12) + assert set(np.unique(ccl.labels)).issubset({0, 1, 2}) + assert np.all(ccl.labels[data == 0] == 0) + assert len(set(ccl.labels[1:3, 1:3, 1:3].ravel())) == 1 + assert len(set(ccl.labels[6:9, 6:9, 6:9].ravel())) == 1 + assert ccl.labels[1, 1, 1] != ccl.labels[6, 6, 6] + + psd = oi.particle_size_distribution(data, phase=1, voxel_size=2.0) + assert psd.num_particles == 2 + expected_r_vox = sorted( + [((3.0 * v) / (4.0 * np.pi)) ** (1.0 / 3.0) for v in (8.0, 27.0)] + ) + np.testing.assert_allclose(sorted(psd.radii_voxels), expected_r_vox, rtol=1e-6) + # Physical radius scales linearly with isotropic voxel_size = 2.0 + np.testing.assert_allclose( + sorted(psd.radii), [2.0 * r for r in expected_r_vox], rtol=1e-6 + ) + + def test_through_thickness_profile(self): + # Graded porosity along Z: slice k has k rows of phase 1 out of 8 -> vf(k) = k / 8 + data = np.zeros((8, 8, 8), dtype=np.int32) + for k in range(8): + data[k, :k, :] = 1 + + prof = oi.through_thickness_profile( + data, phase=1, direction="z", voxel_size=(2.0, 1.0, 1.0) + ) + assert prof.direction == "z" + assert prof.num_slices == 8 + np.testing.assert_allclose(prof.profile, np.arange(8) / 8.0, atol=1e-12) + np.testing.assert_allclose(prof.positions, (np.arange(8) + 0.5) * 2.0, atol=1e-12) + + def test_rev_study_uniform_domain(self, tmp_path): + data = np.ones((16, 16, 16), dtype=np.int32) + csv_file = tmp_path / "rev_out.csv" + rev = oi.rev_study( + data, sizes=[8, 12], num_samples=2, phase=1, csv_path=str(csv_file) + ) + assert rev.sizes == [8, 12] + assert len(rev.samples) == 4 + assert csv_file.exists() + for sz in (8, 12): + np.testing.assert_allclose(rev.mean_diagonal[sz], [1.0, 1.0, 1.0], atol=1e-5) + + +@pytest.mark.skipif(not _has_core(), reason="Requires compiled _core extension for parity check") +class TestCppPurePythonParity: + """Verify compiled C++ backend and pure-Python fallback agree closely.""" + + def test_parity_across_all_v460_apis(self, monkeypatch): + rng = np.random.default_rng(123) + data = (rng.random((12, 12, 12)) < 0.7).astype(np.int32) + # Guarantee straight percolation path along X, Y, Z plus multi-phase values + data[4:8, 4:8, :] = 1 + data[4:8, :, 4:8] = 1 + data[:, 4:8, 4:8] = 1 + vsize = (1.5, 1.0, 0.75) + + tau_cpp = oi.tortuosity( + data, phase=1, direction="x", voxel_size=vsize, return_field=True + ) + deff_cpp = oi.effective_diffusivity(data, phase=1, voxel_size=vsize) + ssa_cpp = oi.specific_surface_area(data, phase_a=0, phase_b=1, voxel_size=vsize) + ccl_cpp = oi.connected_components(data, phase=0, return_labels=True) + ttp_cpp = oi.through_thickness_profile( + data, phase=1, direction="x", voxel_size=vsize + ) + + monkeypatch.setattr(Session, "_pure_python", True) + tau_py = oi.tortuosity( + data, phase=1, direction="x", voxel_size=vsize, return_field=True + ) + deff_py = oi.effective_diffusivity(data, phase=1, voxel_size=vsize) + ssa_py = oi.specific_surface_area(data, phase_a=0, phase_b=1, voxel_size=vsize) + ccl_py = oi.connected_components(data, phase=0, return_labels=True) + ttp_py = oi.through_thickness_profile( + data, phase=1, direction="x", voxel_size=vsize + ) + + assert tau_cpp.tortuosity == pytest.approx(tau_py.tortuosity, rel=1e-4) + assert tau_cpp.effective_diffusivity == pytest.approx( + tau_py.effective_diffusivity, rel=1e-4 + ) + np.testing.assert_allclose( + tau_cpp.solution_field, tau_py.solution_field, atol=1e-4 + ) + np.testing.assert_allclose(deff_cpp.tensor, deff_py.tensor, atol=1e-4) + assert ssa_cpp.ssa == pytest.approx(ssa_py.ssa, rel=1e-12) + assert ccl_cpp.num_components == ccl_py.num_components + assert sorted(ccl_cpp.volumes.tolist()) == sorted(ccl_py.volumes.tolist()) + np.testing.assert_allclose(ttp_cpp.profile, ttp_py.profile, atol=1e-12) diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index b33b9f0..1820cd0 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -78,9 +78,9 @@ if(OPENIMPALA_PYTHON) endif() # ============================================================================== -# CUDA Separable Compilation (required for device linking with AMReX/HYPRE) +# CUDA Separable Compilation (only when AMReX is built with AMReX_GPU_RDC=ON) # ============================================================================== -if(GPU_BACKEND STREQUAL "CUDA") +if(GPU_BACKEND STREQUAL "CUDA" AND AMReX_GPU_RDC) set_target_properties(openimpala_io openimpala_props PROPERTIES CUDA_SEPARABLE_COMPILATION ON ) diff --git a/src/props/ConnectedComponents.H b/src/props/ConnectedComponents.H index b8bf127..49fa66e 100644 --- a/src/props/ConnectedComponents.H +++ b/src/props/ConnectedComponents.H @@ -59,6 +59,11 @@ public: return m_labels; } + /** @brief Geometry associated with the label field. */ + const amrex::Geometry& getGeometry() const { + return m_geom; + } + // --- Implementation methods (public for CUDA __device__ lambda compatibility) --- void run(const amrex::iMultiFab& mf_phase, int phase_id); diff --git a/src/props/DeffTensor.H b/src/props/DeffTensor.H index 08091c2..f3651fc 100644 --- a/src/props/DeffTensor.H +++ b/src/props/DeffTensor.H @@ -33,7 +33,8 @@ namespace OpenImpala { void calculateDeffTensor(amrex::Real Deff_tensor[AMREX_SPACEDIM][AMREX_SPACEDIM], const amrex::MultiFab& mf_chi_x, const amrex::MultiFab& mf_chi_y, const amrex::MultiFab& mf_chi_z, const amrex::iMultiFab& active_mask, - const amrex::Geometry& geom, int verbose = 0); + const amrex::Geometry& geom, int verbose = 0, + const amrex::MultiFab* mf_diff_coeff = nullptr); } // namespace OpenImpala diff --git a/src/props/DeffTensor.cpp b/src/props/DeffTensor.cpp index 74484db..e929954 100644 --- a/src/props/DeffTensor.cpp +++ b/src/props/DeffTensor.cpp @@ -15,7 +15,8 @@ namespace OpenImpala { void calculateDeffTensor(amrex::Real Deff_tensor[AMREX_SPACEDIM][AMREX_SPACEDIM], const amrex::MultiFab& mf_chi_x, const amrex::MultiFab& mf_chi_y, const amrex::MultiFab& mf_chi_z, const amrex::iMultiFab& active_mask, - const amrex::Geometry& geom, int verbose) { + const amrex::Geometry& geom, int verbose, + const amrex::MultiFab* mf_diff_coeff) { BL_PROFILE("OpenImpala::calculateDeffTensor"); for (int i = 0; i < AMREX_SPACEDIM; ++i) { @@ -45,6 +46,8 @@ void calculateDeffTensor(amrex::Real Deff_tensor[AMREX_SPACEDIM][AMREX_SPACEDIM] amrex::Real, amrex::Real, amrex::Real> reduce_data(reduce_op); + const bool has_dc = (mf_diff_coeff != nullptr && mf_diff_coeff->isDefined()); + for (amrex::MFIter mfi(active_mask); mfi.isValid(); ++mfi) { const amrex::Box& bx = mfi.validbox(); amrex::Array4 const mask_arr = active_mask.const_array(mfi); @@ -53,6 +56,8 @@ void calculateDeffTensor(amrex::Real Deff_tensor[AMREX_SPACEDIM][AMREX_SPACEDIM] amrex::Array4 const chi_z_arr = (AMREX_SPACEDIM == 3 && mf_chi_z.isDefined()) ? mf_chi_z.const_array(mfi) : mf_chi_x.const_array(mfi); + amrex::Array4 const dc_arr = + has_dc ? mf_diff_coeff->const_array(mfi) : mf_chi_x.const_array(mfi); reduce_op.eval( bx, reduce_data, @@ -63,6 +68,8 @@ void calculateDeffTensor(amrex::Real Deff_tensor[AMREX_SPACEDIM][AMREX_SPACEDIM] return {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0}; } + const amrex::Real D_val = has_dc ? dc_arr(i, j, k, 0) : 1.0; + amrex::Real dchix_dx = (chi_x_arr(i + 1, j, k, 0) - chi_x_arr(i - 1, j, k, 0)) * inv_2dx_0; amrex::Real dchix_dy = @@ -82,10 +89,12 @@ void calculateDeffTensor(amrex::Real Deff_tensor[AMREX_SPACEDIM][AMREX_SPACEDIM] dchiz_dz = (chi_z_arr(i, j, k + 1, 0) - chi_z_arr(i, j, k - 1, 0)) * inv_2dx_2; } - // D_eff[r][c] = delta_rc + d(chi_c)/d(x_r), summed over active cells + // D_eff[r][c] = D(x) * (delta_rc + d(chi_c)/d(x_r)), summed over active cells // Cell problem: div(D grad chi_k) = -div(D e_k) => plus sign - return {1.0 + dchix_dx, dchiy_dx, dchiz_dx, dchix_dy, 1.0 + dchiy_dy, - dchiz_dy, dchix_dz, dchiy_dz, 1.0 + dchiz_dz}; + return { + D_val * (1.0 + dchix_dx), D_val * dchiy_dx, D_val * dchiz_dx, + D_val * dchix_dy, D_val * (1.0 + dchiy_dy), D_val * dchiz_dy, + D_val * dchix_dz, D_val * dchiy_dz, D_val * (1.0 + dchiz_dz)}; }); } diff --git a/src/props/EffectiveDiffusivityHypre.H b/src/props/EffectiveDiffusivityHypre.H index ef8ad5b..54c3884 100644 --- a/src/props/EffectiveDiffusivityHypre.H +++ b/src/props/EffectiveDiffusivityHypre.H @@ -68,7 +68,8 @@ public: const amrex::iMultiFab& mf_phase_input, const int phase_id, const OpenImpala::Direction dir_of_chi_k, const SolverType solver_type, const std::string& resultspath, - int verbose_level = 1, bool write_plotfile_flag = false); + int verbose_level = 1, bool write_plotfile_flag = false, + const std::map& phase_coeffs = {}); /** @brief Destructor. Base class handles HYPRE resource cleanup. */ ~EffectiveDiffusivityHypre() override = default; diff --git a/src/props/EffectiveDiffusivityHypre.cpp b/src/props/EffectiveDiffusivityHypre.cpp index 34031eb..12e0854 100644 --- a/src/props/EffectiveDiffusivityHypre.cpp +++ b/src/props/EffectiveDiffusivityHypre.cpp @@ -88,7 +88,8 @@ EffectiveDiffusivityHypre::EffectiveDiffusivityHypre( const amrex::Geometry& geom, const amrex::BoxArray& ba, const amrex::DistributionMapping& dm, const amrex::iMultiFab& mf_phase_input, const int phase_id_arg, const OpenImpala::Direction dir_of_chi_k, const SolverType solver_type, - const std::string& resultspath, int verbose_level, bool write_plotfile_flag) + const std::string& resultspath, int verbose_level, bool write_plotfile_flag, + const std::map& phase_coeffs) : HypreStructSolver(geom, ba, dm, solver_type, 1e-9, 1000, verbose_level), m_mf_phase_original(ba, dm, mf_phase_input.nComp(), mf_phase_input.nGrow()), m_phase_id(phase_id_arg), m_dir_solve(dir_of_chi_k), m_resultspath(resultspath), @@ -141,24 +142,33 @@ EffectiveDiffusivityHypre::EffectiveDiffusivityHypre( // --- Multi-phase transport coefficient parsing --- { - amrex::ParmParse pp_tort("tortuosity"); - amrex::Vector active_phases_vec; - amrex::Vector phase_diffs_vec; - pp_tort.queryarr("active_phases", active_phases_vec); - pp_tort.queryarr("phase_diffusivities", phase_diffs_vec); - - if (!active_phases_vec.empty() && !phase_diffs_vec.empty()) { - AMREX_ALWAYS_ASSERT_WITH_MESSAGE( - active_phases_vec.size() == phase_diffs_vec.size(), - "tortuosity.active_phases and tortuosity.phase_diffusivities must have the same " - "length"); - for (size_t idx = 0; idx < active_phases_vec.size(); ++idx) { - m_phase_coeff_map[active_phases_vec[idx]] = phase_diffs_vec[idx]; + if (!phase_coeffs.empty()) { + for (const auto& kv : phase_coeffs) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE(kv.second >= 0.0, + "Phase diffusivities must be non-negative"); + m_phase_coeff_map[kv.first] = kv.second; } m_is_multi_phase = true; } else { - m_phase_coeff_map[m_phase_id] = 1.0; - m_is_multi_phase = false; + amrex::ParmParse pp_tort("tortuosity"); + amrex::Vector active_phases_vec; + amrex::Vector phase_diffs_vec; + pp_tort.queryarr("active_phases", active_phases_vec); + pp_tort.queryarr("phase_diffusivities", phase_diffs_vec); + + if (!active_phases_vec.empty() && !phase_diffs_vec.empty()) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE( + active_phases_vec.size() == phase_diffs_vec.size(), + "tortuosity.active_phases and tortuosity.phase_diffusivities must have the " + "same length"); + for (size_t idx = 0; idx < active_phases_vec.size(); ++idx) { + m_phase_coeff_map[active_phases_vec[idx]] = phase_diffs_vec[idx]; + } + m_is_multi_phase = true; + } else { + m_phase_coeff_map[m_phase_id] = 1.0; + m_is_multi_phase = false; + } } } diff --git a/src/props/SpecificSurfaceArea.H b/src/props/SpecificSurfaceArea.H index 2cecc97..627f02f 100644 --- a/src/props/SpecificSurfaceArea.H +++ b/src/props/SpecificSurfaceArea.H @@ -4,6 +4,7 @@ #ifndef OPENIMPALA_SPECIFIC_SURFACE_AREA_H #define OPENIMPALA_SPECIFIC_SURFACE_AREA_H +#include #include #include #include @@ -93,6 +94,29 @@ public: return (2.0 / 3.0) * value_ssa(local); } + /** + * @brief Compute interface face counts along each coordinate direction and total cells. + * + * @param[out] dir_faces Number of interface faces normal to each direction (X=0, Y=1, Z=2). + * @param[out] total_count Total number of cells in the (padded) domain. + * @param[in] local If true, skip MPI reduction (default false). + */ + void directionFaceCounts(amrex::Array& dir_faces, + long long& total_count, bool local = false) const; + + /** + * @brief Physical specific surface area accounting for potentially anisotropic cell sizes: + * SSA_raw = (1 / total_count) * sum_d (dir_faces[d] / dx[d]). + */ + amrex::Real value_physical(bool local = false) const; + + /** + * @brief Cauchy-Crofton (2/3) corrected physical specific surface area. + */ + amrex::Real value_physical_corrected(bool local = false) const { + return (2.0 / 3.0) * value_physical(local); + } + private: const amrex::Geometry& m_geom; const amrex::iMultiFab& m_mf; diff --git a/src/props/SpecificSurfaceArea.cpp b/src/props/SpecificSurfaceArea.cpp index c747ba9..1f1b831 100644 --- a/src/props/SpecificSurfaceArea.cpp +++ b/src/props/SpecificSurfaceArea.cpp @@ -20,7 +20,8 @@ SpecificSurfaceArea::SpecificSurfaceArea(const amrex::Geometry& geom, const amre "SpecificSurfaceArea: boundary_padding must be non-negative."); } -void SpecificSurfaceArea::value(long long& face_count, long long& total_count, bool local) const { +void SpecificSurfaceArea::directionFaceCounts(amrex::Array& dir_faces, + long long& total_count, bool local) const { AMREX_ALWAYS_ASSERT_WITH_MESSAGE( m_mf.nGrow() >= 1, "SpecificSurfaceArea: iMultiFab must have at least 1 ghost cell for neighbor access."); @@ -35,25 +36,18 @@ void SpecificSurfaceArea::value(long long& face_count, long long& total_count, b AMREX_ALWAYS_ASSERT_WITH_MESSAGE(padded_domain.ok(), "SpecificSurfaceArea: boundary_padding too large for domain."); - // GPU-compatible reduction for face and cell counting - amrex::ReduceOps reduce_op; - amrex::ReduceData reduce_data(reduce_op); + for (int d = 0; d < AMREX_SPACEDIM; ++d) { + amrex::ReduceOps reduce_op; + amrex::ReduceData reduce_data(reduce_op); - for (amrex::MFIter mfi(m_mf); mfi.isValid(); ++mfi) { - const amrex::Box& bx = mfi.validbox(); - const auto& fab = m_mf.const_array(mfi, phase_comp); + amrex::IntVect offset(amrex::IntVect::TheZeroVector()); + offset[d] = 1; + const int od0 = offset[0], od1 = offset[1], od2 = offset[2]; + + for (amrex::MFIter mfi(m_mf); mfi.isValid(); ++mfi) { + const amrex::Box& bx = mfi.validbox(); + const auto& fab = m_mf.const_array(mfi, phase_comp); - // Count total cells in padded interior - const amrex::Box count_bx = bx & padded_domain; - long long box_total = count_bx.ok() ? count_bx.numPts() : 0; - - // Count interface faces in each direction. - // For each direction d, we check the face between cell (i,j,k) and its - // neighbor in the +d direction. Both cells must lie within the padded - // domain. The face is "owned" by the cell on its low side. - // We also clamp to the valid box to avoid accessing ghost cells that - // may not be filled (the +d neighbor must be within this FAB's valid region). - for (int d = 0; d < AMREX_SPACEDIM; ++d) { amrex::Box check_bx = bx & padded_domain; if (!check_bx.ok()) { continue; @@ -65,35 +59,23 @@ void SpecificSurfaceArea::value(long long& face_count, long long& total_count, b check_bx.setBig(d, hi_limit); if (check_bx.ok()) { - amrex::IntVect offset(amrex::IntVect::TheZeroVector()); - offset[d] = 1; - const int od0 = offset[0], od1 = offset[1], od2 = offset[2]; - reduce_op.eval( - check_bx, reduce_data, - [=] AMREX_GPU_DEVICE(int i, int j, - int k) noexcept -> amrex::GpuTuple { - int val = fab(i, j, k); - int nbr = fab(i + od0, j + od1, k + od2); - long long fc = - ((val == pa && nbr == pb) || (val == pb && nbr == pa)) ? 1LL : 0LL; - // total_contrib is added only for the first cell evaluated when d==0 - return {fc, 0LL}; - }); - - // Accumulate total count outside the kernel (it's a box property, not per-cell) - if (d == 0) { - // We need to add box_total to the total_count. Since this is a constant - // per MFIter iteration, we handle it after the reduce. - } + reduce_op.eval(check_bx, reduce_data, + [=] AMREX_GPU_DEVICE(int i, int j, + int k) noexcept -> amrex::GpuTuple { + int val = fab(i, j, k); + int nbr = fab(i + od0, j + od1, k + od2); + long long fc = + ((val == pa && nbr == pb) || (val == pb && nbr == pa)) ? 1LL + : 0LL; + return {fc}; + }); } } + + dir_faces[d] = amrex::get<0>(reduce_data.value()); } - auto hv = reduce_data.value(); - long long local_face_count = amrex::get<0>(hv); long long local_total_count = 0; - - // Compute total count on host (it's a box-level quantity, not per-cell) for (amrex::MFIter mfi(m_mf); mfi.isValid(); ++mfi) { const amrex::Box& bx = mfi.validbox(); const amrex::Box count_bx = bx & padded_domain; @@ -103,12 +85,40 @@ void SpecificSurfaceArea::value(long long& face_count, long long& total_count, b } if (!local) { - amrex::ParallelAllReduce::Sum(local_face_count, amrex::ParallelContext::CommunicatorSub()); + for (int d = 0; d < AMREX_SPACEDIM; ++d) { + amrex::ParallelAllReduce::Sum(dir_faces[d], amrex::ParallelContext::CommunicatorSub()); + } amrex::ParallelAllReduce::Sum(local_total_count, amrex::ParallelContext::CommunicatorSub()); } - face_count = local_face_count; total_count = local_total_count; } +void SpecificSurfaceArea::value(long long& face_count, long long& total_count, bool local) const { + amrex::Array dir_faces{}; + directionFaceCounts(dir_faces, total_count, local); + face_count = 0; + for (int d = 0; d < AMREX_SPACEDIM; ++d) { + face_count += dir_faces[d]; + } +} + +amrex::Real SpecificSurfaceArea::value_physical(bool local) const { + amrex::Array dir_faces{}; + long long total_count = 0; + directionFaceCounts(dir_faces, total_count, local); + if (total_count <= 0) { + return 0.0; + } + + const amrex::Real* dx = m_geom.CellSize(); + amrex::Real weighted_sum = 0.0; + for (int d = 0; d < AMREX_SPACEDIM; ++d) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE(dx[d] > 0.0, + "SpecificSurfaceArea: non-positive cell size."); + weighted_sum += static_cast(dir_faces[d]) / dx[d]; + } + return weighted_sum / static_cast(total_count); +} + } // namespace OpenImpala diff --git a/src/props/TortuosityHypre.H b/src/props/TortuosityHypre.H index 75738fe..ab7a8bb 100644 --- a/src/props/TortuosityHypre.H +++ b/src/props/TortuosityHypre.H @@ -75,7 +75,8 @@ public: const amrex::Real vf, const int phase, const OpenImpala::Direction dir, const SolverType solvertype, const std::string& resultspath, const amrex::Real vlo = 0.0, const amrex::Real vhi = 1.0, int verbose = 0, - bool write_plotfile = false, const PrecondType precond_type = PrecondType::SMG); + bool write_plotfile = false, const PrecondType precond_type = PrecondType::SMG, + const std::map& phase_coeffs = {}); /** Destructor. Base class handles HYPRE resource cleanup. */ virtual ~TortuosityHypre() override = default; @@ -117,6 +118,15 @@ public: amrex::Real getActiveVolumeFraction() const { return m_active_vf; } + amrex::Real getEffectiveDiffusivity() const { + return m_deff; + } + const amrex::MultiFab& getSolutionField() const { + return m_mf_phi; + } + const amrex::Geometry& getGeometry() const { + return m_geom; + } /** @brief Returns the per-plane flux profile computed after solving. */ const std::vector& getPlaneFluxes() const { @@ -198,9 +208,11 @@ private: // Multi-phase configuration std::map m_phase_coeff_map; ///< Maps phase ID -> transport coefficient bool m_is_multi_phase = false; ///< True if multiple conducting phases configured + amrex::Real m_max_diff_coeff = 1.0; // State amrex::Real m_value = std::numeric_limits::quiet_NaN(); + amrex::Real m_deff = std::numeric_limits::quiet_NaN(); bool m_first_call = true; // Results (solver stats m_num_iterations/m_final_res_norm/m_converged are in base class) diff --git a/src/props/TortuosityHypre.cpp b/src/props/TortuosityHypre.cpp index 294b118..be9a043 100644 --- a/src/props/TortuosityHypre.cpp +++ b/src/props/TortuosityHypre.cpp @@ -88,7 +88,8 @@ OpenImpala::TortuosityHypre::TortuosityHypre(const amrex::Geometry& geom, const const SolverType st, const std::string& resultspath, const amrex::Real vlo, const amrex::Real vhi, int verbose, bool write_plotfile, - const PrecondType precond_type) + const PrecondType precond_type, + const std::map& phase_coeffs) : HypreStructSolver(geom, ba, dm, st, 1e-9, 200, verbose), m_mf_phase(ba, dm, mf_phase_input.nComp(), mf_phase_input.nGrow()), m_phase(phase), m_vf(vf), m_dir(dir), m_vlo(vlo), m_vhi(vhi), m_resultspath(resultspath), @@ -174,20 +175,11 @@ OpenImpala::TortuosityHypre::TortuosityHypre(const amrex::Geometry& geom, const // --- Multi-phase transport coefficient parsing --- { - amrex::Vector active_phases_vec; - amrex::Vector phase_diffs_vec; - pp_tort.queryarr("active_phases", active_phases_vec); - pp_tort.queryarr("phase_diffusivities", phase_diffs_vec); - - if (!active_phases_vec.empty() && !phase_diffs_vec.empty()) { - AMREX_ALWAYS_ASSERT_WITH_MESSAGE( - active_phases_vec.size() == phase_diffs_vec.size(), - "tortuosity.active_phases and tortuosity.phase_diffusivities must have the same " - "length"); - for (size_t idx = 0; idx < active_phases_vec.size(); ++idx) { - AMREX_ALWAYS_ASSERT_WITH_MESSAGE(phase_diffs_vec[idx] >= 0.0, + if (!phase_coeffs.empty()) { + for (const auto& kv : phase_coeffs) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE(kv.second >= 0.0, "Phase diffusivities must be non-negative"); - m_phase_coeff_map[active_phases_vec[idx]] = phase_diffs_vec[idx]; + m_phase_coeff_map[kv.first] = kv.second; } m_is_multi_phase = true; if (m_verbose > 0 && amrex::ParallelDescriptor::IOProcessor()) { @@ -199,14 +191,50 @@ OpenImpala::TortuosityHypre::TortuosityHypre(const amrex::Geometry& geom, const } } } else { - // Default single-phase behaviour: target phase has D=1, everything else D=0 - m_phase_coeff_map[m_phase] = 1.0; - m_is_multi_phase = false; - if (m_verbose > 0 && amrex::ParallelDescriptor::IOProcessor()) { - amrex::Print() << " Single-phase mode: Phase " << m_phase << " -> D = 1.0" - << std::endl; + amrex::Vector active_phases_vec; + amrex::Vector phase_diffs_vec; + pp_tort.queryarr("active_phases", active_phases_vec); + pp_tort.queryarr("phase_diffusivities", phase_diffs_vec); + + if (!active_phases_vec.empty() && !phase_diffs_vec.empty()) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE( + active_phases_vec.size() == phase_diffs_vec.size(), + "tortuosity.active_phases and tortuosity.phase_diffusivities must have the " + "same length"); + for (size_t idx = 0; idx < active_phases_vec.size(); ++idx) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE(phase_diffs_vec[idx] >= 0.0, + "Phase diffusivities must be non-negative"); + m_phase_coeff_map[active_phases_vec[idx]] = phase_diffs_vec[idx]; + } + m_is_multi_phase = true; + if (m_verbose > 0 && amrex::ParallelDescriptor::IOProcessor()) { + amrex::Print() << " Multi-phase mode enabled with " << m_phase_coeff_map.size() + << " phases:" << std::endl; + for (const auto& kv : m_phase_coeff_map) { + amrex::Print() + << " Phase " << kv.first << " -> D = " << kv.second << std::endl; + } + } + } else { + // Default single-phase behaviour: target phase has D=1, everything else D=0 + m_phase_coeff_map[m_phase] = 1.0; + m_is_multi_phase = false; + if (m_verbose > 0 && amrex::ParallelDescriptor::IOProcessor()) { + amrex::Print() + << " Single-phase mode: Phase " << m_phase << " -> D = 1.0" << std::endl; + } } } + + m_max_diff_coeff = 0.0; + for (const auto& kv : m_phase_coeff_map) { + if (kv.second > m_max_diff_coeff) { + m_max_diff_coeff = kv.second; + } + } + if (m_max_diff_coeff <= 0.0) { + m_max_diff_coeff = 1.0; + } } if (m_verbose > 1 && amrex::ParallelDescriptor::IOProcessor()) @@ -245,7 +273,8 @@ OpenImpala::TortuosityHypre::TortuosityHypre(const amrex::Geometry& geom, const // No need to setup HYPRE if there's no active phase m_first_call = false; // Mark as "calculated" (result is NaN or Inf) m_value = std::numeric_limits::quiet_NaN(); // Or Inf if you prefer for zero VF - return; // Exit constructor early + m_deff = 0.0; + return; // Exit constructor early } // Setup HYPRE structures only if there's an active phase @@ -865,6 +894,27 @@ amrex::Real OpenImpala::TortuosityHypre::value(const bool refresh) { // and can exceed any fixed relative threshold for masked // porous-media inputs at 64³+. Now warning-only — boundary // conservation is the real correctness test. + amrex::Real L = m_geom.ProbLength(static_cast(m_dir)); + amrex::Real A = 1.0; + if (AMREX_SPACEDIM == 3) { + if (m_dir == OpenImpala::Direction::X) + A = m_geom.ProbLength(1) * m_geom.ProbLength(2); + else if (m_dir == OpenImpala::Direction::Y) + A = m_geom.ProbLength(0) * m_geom.ProbLength(2); + else + A = m_geom.ProbLength(0) * m_geom.ProbLength(1); + } else if (AMREX_SPACEDIM == 2) { + if (m_dir == OpenImpala::Direction::X) + A = m_geom.ProbLength(1); + else + A = m_geom.ProbLength(0); + } + amrex::Real gradPhi = (m_vhi - m_vlo) / L; + amrex::Real d_scale = (m_max_diff_coeff > 0.0) ? m_max_diff_coeff : 1.0; + amrex::Real ref_flux = + (A * std::abs(gradPhi) > 0.0) ? (d_scale * A * std::abs(gradPhi)) : 1.0; + amrex::Real scaled_flux_threshold = tiny_flux_threshold * ref_flux; + constexpr amrex::Real flux_tol = 1.0e-4; constexpr amrex::Real plane_dev_warn = 1.0e-3; bool flux_conserved = true; @@ -872,7 +922,7 @@ amrex::Real OpenImpala::TortuosityHypre::value(const bool refresh) { amrex::Real flux_mag_in = std::abs(m_flux_in); amrex::Real flux_mag_out = std::abs(m_flux_out); amrex::Real flux_mag_avg = 0.5 * (flux_mag_in + flux_mag_out); - if (flux_mag_avg > tiny_flux_threshold) { + if (flux_mag_avg > scaled_flux_threshold) { rel_diff = std::abs(flux_mag_in - flux_mag_out) / flux_mag_avg; if (rel_diff > flux_tol) { flux_conserved = false; @@ -921,29 +971,10 @@ amrex::Real OpenImpala::TortuosityHypre::value(const bool refresh) { << std::endl; } m_value = std::numeric_limits::quiet_NaN(); + m_deff = std::numeric_limits::quiet_NaN(); } else { // Flux is conserved, proceed with calculation using average flux magnitude - - // <<< CHANGE: Use m_active_vf instead of m_vf >>> amrex::Real vf_for_calc = m_active_vf; - // <<< END CHANGE >>> - - amrex::Real L = m_geom.ProbLength(static_cast(m_dir)); - amrex::Real A = 1.0; - if (AMREX_SPACEDIM == 3) { - if (m_dir == OpenImpala::Direction::X) - A = m_geom.ProbLength(1) * m_geom.ProbLength(2); - else if (m_dir == OpenImpala::Direction::Y) - A = m_geom.ProbLength(0) * m_geom.ProbLength(2); - else - A = m_geom.ProbLength(0) * m_geom.ProbLength(1); - } else if (AMREX_SPACEDIM == 2) { - if (m_dir == OpenImpala::Direction::X) - A = m_geom.ProbLength(1); - else - A = m_geom.ProbLength(0); - } - amrex::Real gradPhi = (m_vhi - m_vlo) / L; // Assumes L > 0 amrex::Real Deff = 0.0; // Use mean of interior plane fluxes when available (more robust @@ -961,49 +992,48 @@ amrex::Real OpenImpala::TortuosityHypre::value(const bool refresh) { } // Handle edge cases - if (avg_flux_mag < tiny_flux_threshold) { + if (avg_flux_mag < scaled_flux_threshold) { if (m_verbose >= 0 && amrex::ParallelDescriptor::IOProcessor()) { amrex::Print() << "WARNING: Average flux magnitude is near zero (" << avg_flux_mag << "). Tortuosity set to Inf (or NaN if ActiveVF=0)." << std::endl; } - // <<< CHANGE: Check vf_for_calc (active_vf) here >>> + m_deff = 0.0; m_value = (vf_for_calc > std::numeric_limits::epsilon()) ? std::numeric_limits::infinity() : std::numeric_limits::quiet_NaN(); - } - // <<< CHANGE: Check vf_for_calc (active_vf) here >>> - else if (vf_for_calc <= std::numeric_limits::epsilon()) { + } else if (vf_for_calc <= std::numeric_limits::epsilon()) { if (m_verbose >= 0 && amrex::ParallelDescriptor::IOProcessor()) { amrex::Print() << "WARNING: Active volume fraction is zero. Tortuosity set to NaN." << std::endl; } + m_deff = 0.0; m_value = std::numeric_limits::quiet_NaN(); - } else if (std::abs(gradPhi) < tiny_flux_threshold) { + } else if (std::abs(gradPhi) <= std::numeric_limits::min()) { if (m_verbose >= 0 && amrex::ParallelDescriptor::IOProcessor()) { amrex::Print() << "WARNING: Potential gradient is zero (vlo=vhi). Tortuosity set to Inf." << std::endl; } + m_deff = 0.0; m_value = std::numeric_limits::infinity(); } else { // Calculate Deff using average flux magnitude Deff = (avg_flux_mag / A) / std::abs(gradPhi); - if (std::abs(Deff) < tiny_flux_threshold) { + m_deff = Deff; + if (std::abs(Deff) < tiny_flux_threshold * d_scale) { if (m_verbose >= 0 && amrex::ParallelDescriptor::IOProcessor()) { amrex::Print() << "WARNING: Effective Diffusivity (Deff) is near zero (" << Deff << "). Tortuosity set to Inf." << std::endl; } m_value = std::numeric_limits::infinity(); } else { - // <<< CHANGE: This calculation now uses active VF >>> m_value = vf_for_calc / Deff; } } if (m_verbose > 0 && amrex::ParallelDescriptor::IOProcessor()) { - // <<< CHANGE: Update print statement label >>> amrex::Print() << " Calculation Details: ActiveVf=" << vf_for_calc << ", L=" << L << ", A=" << A << ", gradPhi=" << gradPhi << ", AvgFluxMag=" << avg_flux_mag << ", Deff=" << Deff << std::endl; @@ -1238,6 +1268,7 @@ void OpenImpala::TortuosityHypre::global_fluxes() { amrex::Gpu::streamSynchronize(); #endif mf_soln_temp.FillBoundary(m_geom.periodicity()); + amrex::Copy(m_mf_phi, mf_soln_temp, 0, SolnComp, 1, 1); m_mf_active_mask.FillBoundary(m_geom.periodicity()); m_mf_diff_coeff.FillBoundary(m_geom.periodicity()); @@ -1460,7 +1491,8 @@ void OpenImpala::TortuosityHypre::computePlaneFluxes(const amrex::MultiFab& mf_s } amrex::Real abs_mean = std::abs(mean_flux); - m_plane_flux_max_dev = (abs_mean > tiny_flux_threshold) ? max_abs_dev / abs_mean : 0.0; + m_plane_flux_max_dev = + (abs_mean > std::numeric_limits::min()) ? max_abs_dev / abs_mean : 0.0; if (m_verbose > 0 && amrex::ParallelDescriptor::IOProcessor()) { amrex::Print() << " Interior Plane Flux Check (" << n_faces << " faces):\n"; diff --git a/src/props/TortuosityMLMG.H b/src/props/TortuosityMLMG.H index cb7ea9d..cbd48f3 100644 --- a/src/props/TortuosityMLMG.H +++ b/src/props/TortuosityMLMG.H @@ -62,7 +62,8 @@ public: const amrex::Real vf, const int phase, const OpenImpala::Direction dir, const std::string& resultspath, const amrex::Real vlo = 0.0, const amrex::Real vhi = 1.0, int verbose = 0, bool write_plotfile = false, - amrex::Real eps = 1.0e-8, int maxiter = 200, int max_coarsening_level = 30); + amrex::Real eps = 1.0e-8, int maxiter = 200, int max_coarsening_level = 30, + const std::map& phase_coeffs = {}); ~TortuosityMLMG() override = default; diff --git a/src/props/TortuosityMLMG.cpp b/src/props/TortuosityMLMG.cpp index e6209a4..f994362 100644 --- a/src/props/TortuosityMLMG.cpp +++ b/src/props/TortuosityMLMG.cpp @@ -36,9 +36,10 @@ TortuosityMLMG::TortuosityMLMG(const amrex::Geometry& geom, const amrex::BoxArra const int phase, const OpenImpala::Direction dir, const std::string& resultspath, const amrex::Real vlo, const amrex::Real vhi, int verbose, bool write_plotfile, - amrex::Real eps, int maxiter, int max_coarsening_level) + amrex::Real eps, int maxiter, int max_coarsening_level, + const std::map& phase_coeffs) : TortuositySolverBase(geom, ba, dm, mf_phase_input, vf, phase, dir, resultspath, vlo, vhi, - verbose, write_plotfile) { + verbose, write_plotfile, phase_coeffs) { m_eps = eps; m_maxiter = maxiter; m_max_coarsening_level = max_coarsening_level; @@ -140,7 +141,8 @@ bool TortuosityMLMG::solve() { // diffusion operator so its coarse-grid average does not overwhelm the // diffusion mode on long connected paths. const amrex::Real length = m_geom.ProbLength(idir); - op.setScalars(1. / (length * length), 1.); + const amrex::Real d_scale = (m_max_diff_coeff > 0.0) ? m_max_diff_coeff : 1.0; + op.setScalars(d_scale / (length * length), 1.); amrex::MultiFab acoef(m_ba, m_dm, 1, 0); #ifdef AMREX_USE_OMP #pragma omp parallel if (amrex::Gpu::notInLaunchRegion()) @@ -197,7 +199,7 @@ bool TortuosityMLMG::solve() { const amrex::Real n_cross = static_cast(domain.numPts()) / static_cast(domain.length(idir)); const amrex::Real est_bndry_cells = std::max(1.0, m_active_vf * n_cross); - const amrex::Real bndry_scale = (dv > 0.0) ? (2.0 * dv / (dx_dir * dx_dir)) : 1.0; + const amrex::Real bndry_scale = (dv > 0.0) ? (2.0 * d_scale * dv / (dx_dir * dx_dir)) : d_scale; const amrex::Real tol_abs_inf = m_eps * bndry_scale; const amrex::Real tol_abs_2 = m_eps * bndry_scale * std::sqrt(est_bndry_cells); diff --git a/src/props/TortuositySolverBase.H b/src/props/TortuositySolverBase.H index 33c6af8..6f7366e 100644 --- a/src/props/TortuositySolverBase.H +++ b/src/props/TortuositySolverBase.H @@ -64,7 +64,8 @@ public: const amrex::iMultiFab& mf_phase_input, const amrex::Real vf, const int phase, const OpenImpala::Direction dir, const std::string& resultspath, const amrex::Real vlo, - const amrex::Real vhi, int verbose, bool write_plotfile); + const amrex::Real vhi, int verbose, bool write_plotfile, + const std::map& phase_coeffs = {}); ~TortuositySolverBase() override = default; @@ -99,6 +100,15 @@ public: amrex::Real getActiveVolumeFraction() const { return m_active_vf; } + amrex::Real getEffectiveDiffusivity() const { + return m_deff; + } + const amrex::MultiFab& getSolutionField() const { + return m_mf_solution; + } + const amrex::Geometry& getGeometry() const { + return m_geom; + } const std::vector& getPlaneFluxes() const { return m_plane_fluxes; } @@ -129,6 +139,7 @@ public: // --- Shared setup helpers --- void preconditionPhaseFab(); void buildDiffusionCoeffField(); + amrex::iMultiFab buildTraversableMask(); void generateActivityMask(const amrex::iMultiFab& phaseFab, int phaseID, OpenImpala::Direction dir); void parallelFloodFill(amrex::iMultiFab& reachabilityMask, const amrex::iMultiFab& phaseFab, @@ -164,9 +175,11 @@ protected: // --- Multi-phase configuration --- std::map m_phase_coeff_map; ///< Phase ID -> transport coefficient bool m_is_multi_phase = false; + amrex::Real m_max_diff_coeff = 1.0; // --- Cached results --- amrex::Real m_value = std::numeric_limits::quiet_NaN(); + amrex::Real m_deff = std::numeric_limits::quiet_NaN(); bool m_first_call = true; amrex::Real m_active_vf = 0.0; ///< Volume fraction of percolating phase diff --git a/src/props/TortuositySolverBase.cpp b/src/props/TortuositySolverBase.cpp index 92e90d7..f786323 100644 --- a/src/props/TortuositySolverBase.cpp +++ b/src/props/TortuositySolverBase.cpp @@ -43,7 +43,8 @@ TortuositySolverBase::TortuositySolverBase(const amrex::Geometry& geom, const am const amrex::Real vf, const int phase, const OpenImpala::Direction dir, const std::string& resultspath, const amrex::Real vlo, - const amrex::Real vhi, int verbose, bool write_plotfile) + const amrex::Real vhi, int verbose, bool write_plotfile, + const std::map& phase_coeffs) : m_geom(geom), m_ba(ba), m_dm(dm), m_mf_phase(ba, dm, mf_phase_input.nComp(), mf_phase_input.nGrow()), m_phase(phase), m_vf(vf), m_dir(dir), m_vlo(vlo), m_vhi(vhi), m_resultspath(resultspath), @@ -57,6 +58,46 @@ TortuositySolverBase::TortuositySolverBase(const amrex::Geometry& geom, const am AMREX_ALWAYS_ASSERT_WITH_MESSAGE(m_vf >= 0.0 && m_vf <= 1.0, "Volume fraction must be between 0 and 1"); + // Configure phase transport coefficients (explicit map overrides ParmParse) + if (!phase_coeffs.empty()) { + for (const auto& kv : phase_coeffs) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE(kv.second >= 0.0, + "Phase diffusivities must be non-negative"); + m_phase_coeff_map[kv.first] = kv.second; + } + m_is_multi_phase = true; + } else { + amrex::Vector active_phases_vec; + amrex::Vector phase_diffs_vec; + pp_tort.queryarr("active_phases", active_phases_vec); + pp_tort.queryarr("phase_diffusivities", phase_diffs_vec); + if (!active_phases_vec.empty() && !phase_diffs_vec.empty()) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE( + active_phases_vec.size() == phase_diffs_vec.size(), + "tortuosity.active_phases and tortuosity.phase_diffusivities must have the same " + "length"); + for (size_t idx = 0; idx < active_phases_vec.size(); ++idx) { + AMREX_ALWAYS_ASSERT_WITH_MESSAGE(phase_diffs_vec[idx] >= 0.0, + "Phase diffusivities must be non-negative"); + m_phase_coeff_map[active_phases_vec[idx]] = phase_diffs_vec[idx]; + } + m_is_multi_phase = true; + } else { + m_phase_coeff_map[m_phase] = 1.0; + m_is_multi_phase = false; + } + } + + m_max_diff_coeff = 0.0; + for (const auto& kv : m_phase_coeff_map) { + if (kv.second > m_max_diff_coeff) { + m_max_diff_coeff = kv.second; + } + } + if (m_max_diff_coeff <= 0.0) { + m_max_diff_coeff = 1.0; + } + // Precondition phase data (remove isolated cells) preconditionPhaseFab(); @@ -64,7 +105,12 @@ TortuositySolverBase::TortuositySolverBase(const amrex::Geometry& geom, const am buildDiffusionCoeffField(); // Generate activity mask via flood fill - generateActivityMask(m_mf_phase, m_phase, m_dir); + if (m_is_multi_phase) { + amrex::iMultiFab mf_traversable = buildTraversableMask(); + generateActivityMask(mf_traversable, 1, m_dir); + } else { + generateActivityMask(m_mf_phase, m_phase, m_dir); + } if (m_active_vf <= std::numeric_limits::epsilon()) { if (m_verbose >= 0 && amrex::ParallelDescriptor::IOProcessor()) { @@ -73,6 +119,7 @@ TortuositySolverBase::TortuositySolverBase(const amrex::Geometry& geom, const am } m_first_call = false; m_value = std::numeric_limits::quiet_NaN(); + m_deff = 0.0; } } @@ -129,19 +176,63 @@ void TortuositySolverBase::buildDiffusionCoeffField() { BL_PROFILE("TortuositySolverBase::buildDiffusionCoeffField"); m_mf_diff_coeff.setVal(0.0); + if (m_is_multi_phase) { + int max_pid = 0; + for (const auto& kv : m_phase_coeff_map) { + max_pid = std::max(max_pid, kv.first); + } + amrex::Gpu::DeviceVector d_coeff_lut(max_pid + 1, 0.0); + amrex::Gpu::HostVector h_coeff_lut(max_pid + 1, 0.0); + for (const auto& kv : m_phase_coeff_map) { + if (kv.first >= 0) { + h_coeff_lut[kv.first] = kv.second; + } + } + amrex::Gpu::copy(amrex::Gpu::hostToDevice, h_coeff_lut.begin(), h_coeff_lut.end(), + d_coeff_lut.begin()); + const amrex::Real* lut_ptr = d_coeff_lut.data(); + const int lut_size = max_pid + 1; + + for (amrex::MFIter mfi(m_mf_diff_coeff, amrex::TilingIfNotGPU()); mfi.isValid(); ++mfi) { + const amrex::Box& bx = mfi.growntilebox(); + amrex::Array4 const dc_arr = m_mf_diff_coeff.array(mfi); + amrex::Array4 const phase_arr = m_mf_phase.const_array(mfi); + amrex::ParallelFor(bx, [=] AMREX_GPU_DEVICE(int i, int j, int k) noexcept { + int pid = phase_arr(i, j, k, 0); + dc_arr(i, j, k, 0) = (pid >= 0 && pid < lut_size) ? lut_ptr[pid] : 0.0; + }); + } + } else { #ifdef AMREX_USE_OMP #pragma omp parallel if (amrex::Gpu::notInLaunchRegion()) #endif - for (amrex::MFIter mfi(m_mf_diff_coeff, amrex::TilingIfNotGPU()); mfi.isValid(); ++mfi) { + for (amrex::MFIter mfi(m_mf_diff_coeff, amrex::TilingIfNotGPU()); mfi.isValid(); ++mfi) { + const amrex::Box& bx = mfi.growntilebox(); + amrex::Array4 const dc_arr = m_mf_diff_coeff.array(mfi); + amrex::Array4 const phase_arr = m_mf_phase.const_array(mfi); + const int target_phase = m_phase; + amrex::ParallelFor(bx, [=] AMREX_GPU_DEVICE(int i, int j, int k) noexcept { + dc_arr(i, j, k, 0) = (phase_arr(i, j, k, 0) == target_phase) ? 1.0 : 0.0; + }); + } + } + m_mf_diff_coeff.FillBoundary(m_geom.periodicity()); +} + +// --- buildTraversableMask --- +amrex::iMultiFab TortuositySolverBase::buildTraversableMask() { + amrex::iMultiFab mf_binary_traversable(m_ba, m_dm, 1, m_mf_phase.nGrow()); + mf_binary_traversable.setVal(0); + for (amrex::MFIter mfi(mf_binary_traversable, amrex::TilingIfNotGPU()); mfi.isValid(); ++mfi) { const amrex::Box& bx = mfi.growntilebox(); - amrex::Array4 const dc_arr = m_mf_diff_coeff.array(mfi); - amrex::Array4 const phase_arr = m_mf_phase.const_array(mfi); - const int target_phase = m_phase; + amrex::Array4 const trav_arr = mf_binary_traversable.array(mfi); + amrex::Array4 const dc_arr = m_mf_diff_coeff.const_array(mfi); amrex::ParallelFor(bx, [=] AMREX_GPU_DEVICE(int i, int j, int k) noexcept { - dc_arr(i, j, k, 0) = (phase_arr(i, j, k, 0) == target_phase) ? 1.0 : 0.0; + trav_arr(i, j, k, 0) = (dc_arr(i, j, k, 0) > 0.0) ? 1 : 0; }); } - m_mf_diff_coeff.FillBoundary(m_geom.periodicity()); + mf_binary_traversable.FillBoundary(m_geom.periodicity()); + return mf_binary_traversable; } // --- generateActivityMask --- @@ -376,7 +467,8 @@ void TortuositySolverBase::computePlaneFluxes(const amrex::MultiFab& mf_soln) { } amrex::Real abs_mean = std::abs(mean_flux); - m_plane_flux_max_dev = (abs_mean > tiny_flux_threshold) ? max_abs_dev / abs_mean : 0.0; + m_plane_flux_max_dev = + (abs_mean > std::numeric_limits::min()) ? max_abs_dev / abs_mean : 0.0; if (m_verbose > 0 && amrex::ParallelDescriptor::IOProcessor()) { amrex::Print() << " Interior Plane Flux Check (" << n_faces << " faces):\n"; @@ -424,6 +516,7 @@ amrex::Real TortuositySolverBase::value(const bool refresh) { if (m_first_call || refresh) { if (m_active_vf <= std::numeric_limits::epsilon()) { m_value = std::numeric_limits::quiet_NaN(); + m_deff = 0.0; m_first_call = false; return m_value; } @@ -435,6 +528,7 @@ amrex::Real TortuositySolverBase::value(const bool refresh) { amrex::Print() << "WARNING: Solver did not converge. Returning NaN." << std::endl; } m_value = std::numeric_limits::quiet_NaN(); + m_deff = std::numeric_limits::quiet_NaN(); m_first_call = false; return m_value; } @@ -443,6 +537,24 @@ amrex::Real TortuositySolverBase::value(const bool refresh) { globalFluxes(); } + amrex::Real L = m_geom.ProbLength(static_cast(m_dir)); + amrex::Real A = 1.0; + if (AMREX_SPACEDIM == 3) { + if (m_dir == Direction::X) + A = m_geom.ProbLength(1) * m_geom.ProbLength(2); + else if (m_dir == Direction::Y) + A = m_geom.ProbLength(0) * m_geom.ProbLength(2); + else + A = m_geom.ProbLength(0) * m_geom.ProbLength(1); + } else if (AMREX_SPACEDIM == 2) { + A = (m_dir == Direction::X) ? m_geom.ProbLength(1) : m_geom.ProbLength(0); + } + amrex::Real gradPhi = (m_vhi - m_vlo) / L; + amrex::Real d_scale = (m_max_diff_coeff > 0.0) ? m_max_diff_coeff : 1.0; + amrex::Real ref_flux = + (A * std::abs(gradPhi) > 0.0) ? (d_scale * A * std::abs(gradPhi)) : 1.0; + amrex::Real scaled_flux_threshold = tiny_flux_threshold * ref_flux; + // Flux conservation check. // // Two distinct tests, with different roles: @@ -469,7 +581,7 @@ amrex::Real TortuositySolverBase::value(const bool refresh) { amrex::Real flux_mag_out = std::abs(m_flux_out); amrex::Real flux_mag_avg = 0.5 * (flux_mag_in + flux_mag_out); amrex::Real boundary_rel_diff = 0.0; - if (flux_mag_avg > tiny_flux_threshold) { + if (flux_mag_avg > scaled_flux_threshold) { boundary_rel_diff = std::abs(flux_mag_in - flux_mag_out) / flux_mag_avg; if (boundary_rel_diff > flux_tol) flux_conserved = false; @@ -492,26 +604,10 @@ amrex::Real TortuositySolverBase::value(const bool refresh) { << std::endl; } m_value = std::numeric_limits::quiet_NaN(); + m_deff = std::numeric_limits::quiet_NaN(); } else { amrex::Real vf_for_calc = m_active_vf; - amrex::Real L = m_geom.ProbLength(static_cast(m_dir)); - amrex::Real A = 1.0; - if (AMREX_SPACEDIM == 3) { - if (m_dir == Direction::X) - A = m_geom.ProbLength(1) * m_geom.ProbLength(2); - else if (m_dir == Direction::Y) - A = m_geom.ProbLength(0) * m_geom.ProbLength(2); - else - A = m_geom.ProbLength(0) * m_geom.ProbLength(1); - } else if (AMREX_SPACEDIM == 2) { - A = (m_dir == Direction::X) ? m_geom.ProbLength(1) : m_geom.ProbLength(0); - } - amrex::Real gradPhi = (m_vhi - m_vlo) / L; - // Use mean of interior plane fluxes when available and valid. - // Fall back to boundary fluxes if plane fluxes are NaN (can - // happen with EB solvers where computePlaneFluxes reads ghost - // cells across covered/regular FAB boundaries). amrex::Real avg_flux_mag; bool plane_fluxes_valid = false; if (!m_plane_fluxes.empty()) { @@ -525,17 +621,21 @@ amrex::Real TortuositySolverBase::value(const bool refresh) { avg_flux_mag = 0.5 * (std::abs(m_flux_in) + std::abs(m_flux_out)); } - if (avg_flux_mag < tiny_flux_threshold) { + if (avg_flux_mag < scaled_flux_threshold) { + m_deff = 0.0; m_value = (vf_for_calc > std::numeric_limits::epsilon()) ? std::numeric_limits::infinity() : std::numeric_limits::quiet_NaN(); } else if (vf_for_calc <= std::numeric_limits::epsilon()) { + m_deff = 0.0; m_value = std::numeric_limits::quiet_NaN(); - } else if (std::abs(gradPhi) < tiny_flux_threshold) { + } else if (std::abs(gradPhi) <= std::numeric_limits::min()) { + m_deff = 0.0; m_value = std::numeric_limits::infinity(); } else { amrex::Real Deff = (avg_flux_mag / A) / std::abs(gradPhi); - if (std::abs(Deff) < tiny_flux_threshold) { + m_deff = Deff; + if (std::abs(Deff) < tiny_flux_threshold * d_scale) { m_value = std::numeric_limits::infinity(); } else { m_value = vf_for_calc / Deff;