---

ISTHMUS: Interfacing Surface Triangles for Heterogenous MUltiphysics Simulations

ISTHMUS, originally developed at the Computational Thermophysics and Fluids Laboratory (CFTL) of University of Kentucky, provides a bridge between voxelized geometries and their surface representations. While voxels and pixels are commonly used to approximate solid structures in imaging and simulations, voxelized surfaces fail to capture curved interfaces, creating challenges when modeling fluid flow around them. Isthmus introduces Marching Windows, a method to generate accurate surface definitions for voxelized structures and consistently transfer fluxes between the surface mesh and voxels.

ISTHMUS is built for multiphysics simulations involving voxelized solids immersed in fluids, making it especially useful for problems such as fluid–structure interaction and thermochemical material response.

For examples of the capabilities of ISTHMUS, see the tutorials located in the examples/ directory.

License

This software is licensed under the MIT License (see LICENSE file). Please also see third-party-licenses/ for licensing information on bundled dependencies.

Table of Contents

• System Requirements
• Installation
  • Step 1: build environment
    • Install conda
    • Create the Conda environment
    • Activate environment
  • Step 2: build marching cubes package
  • Step 3: Add ISTHMUS to PYTHONPATH
  • Step 4: using GPU acceleration with Numba (optional)
    • Set up CUDA Python
    • Test Numba installation
• ISTHMUSIsthmus test](#isthmus-test)

System Requirements

• Memory needs scale with voxel grid size.
• Optional GPU (Numba CUDA, does not work on MacOS):
  • NVIDIA GPU + driver compatible with the selected CUDA runtime
  • Numba/llvmlite pair (e.g., Numba ~0.55.1 with llvmlite ~0.38.0)

Installation

Step 1: build environment

To work with ISTHMUS, using conda (miniconda is fine too) along with the virtual environments shipped in the envs folder of this repository is highly recommended to avoid package dependency headaches. If insisting of not using conda, you need to install the numba package and its dependencies manually and solve any conflicts.

Install conda

To test whether it is installed, run conda --version from terminal to check the current version. If not, conda can be installed by following the instructions here.

Note: Using HPC, load conda module using your administrator guidelines, for example, on University of Kentucky's Lipscomb Compute Cluster (LCC) use:

module load ccs/anaconda/3

Create the Conda environment:

To install the default virtual environment for ISTHMUS, run:

conda env create -n <your_env_name> -f envs/environment.yml
# or in custom location using:
conda env create -p </path/to/your_env_name> -f envs/environment.yml

Note: Several Conda environment YAML files are located in the envs folder. Use environment.yml for complete environment to build ISTHMUS and utilize GPU acceleration using Numba and CUDA. Other environment files are listed in below table.

Environment File	Description
environment.yml	Complete environment that contains cudatoolkit, numba, cython, and marching cubes dependencies.
environment_LCC.yml	Build for LCC, without driver and cudatoolkit. Use module load ccs/cuda/12.2.0_535.54.03 instead.
environment_wout_gpu.yml	Environment with only cython and marching cubes dependencies. Does not run with GPU acceleration.

Activate environment:

Once the environment is created, you can activate it for your current shell session by running:

conda activate <your_env_name>
# or 
conda activate </path/to/your_env_name>

Step 2: build marching cubes package

The ISTHMUS package includes an open source build of marching cubes which must be compiled before moving forward. It needs these modules: trimesh, lazy_loader, numpy, cython, and scipy. They should be loaded within any conda environment defined in the above table. To compile, run the following from src directory.

python -W ignore setup.py build_ext --inplace

Step 3: Add ISTHMUS to PYTHONPATH

At the end of your .bashrc, add the path to isthmus/src/ to your PYTHONPATH environment variable.

export PYTHONPATH="/path/to/isthmus/src:$PYTHONPATH"

Step 4: using GPU acceleration with Numba (optional)

Numba is a python compiler of python code for excution on CUDA-capable GPUs.

Set up CUDA Python

• Starting from scratch, CUDA python enviroment can be installed by following the instructions here,

Or

• Simply by loading the complete environment environment.yml contains cudatoolkit, numba, cython, and marching cubes dependencies.

Or

• If running on LCC use environment_LCC.yml and load the cuda module using,

  module load ccs/cuda/12.2.0_535.54.03

  Note: Using HPC, you might get out of storage quota. It is recommended to clean old tarballs and caches using conda clean -a. If still not working, consider relocating the conda pkgs directory from your $HOME to your #SCRATCH folder (for higher quota), before creating the environment.

  conda config --add pkgs_dirs /your/custom/path

Test Numba installation

Validate with check_numba_cuda.sh (lists GPUs and runs a tiny GPU kernel)

chmod +x check_numba_cuda.sh
./check_numba_cuda.sh

You should recieve a message contains All checks passed ✅ at the end.

ISTHMUS test

To confirm everything is working as expected, change directory to the tests/ folder and type

pytest -v

You should recieve a message indicating that all tests have passed and no errors. If did not install CUDA Python environment, you will see the gpu tests skipped, which is fine.

---