omegah2csg 0.0.2

Convert Omega_h mesh files generated using TOMMS for TOKAMAKs to CSG format for OpenMC and Degas2.

Convert Omega_h Mesh to CSG Format

Efficiently convert Tokamak mesh of Omega_h (.osh) format to Constructive Solid Geometry (CSG). It supports creating CSG representation in

1. Degas2's geometry.nc format
2. OpenMC's geometry XML or a Python openmc.Universe object.

Installation

1. Pre-built Wheel

This is the recommended way to install this package. We provide a pre-built wheel (Kokkos with OpenMP backend) for Python. Follow these steps to install the latest version of readOH2csg using pip:

Wheels are built in CI and uploaded as workflow artifacts for each Python version and build type.

1. On any Linux system, make sure you have Python (Version ≥ 3.11) installed. Go to the terminal and cd to the directory where you want to install the Python virtual environment.

python -m venv readoh2csg-env # or any name you prefer
source readoh2csg-env/bin/activate

[!TIP] Make sure that the Python version of the virtual environment is 3.11 or higher. You can check it by running python --version.

2. Install dependencies:

pip install --extra-index-url https://shimwell.github.io/wheels openmc
pip install netCDF4==1.7.2

3. Install readOH2csg:

pip install omegah2csg

Or if you want to install the latest release from GitHub:

pip install <link-to-release-wheel-file> omegah2csg

[!TIP] Find the latest release on the Releases Page and copy the link to the wheel file for your Python version and system architecture.

4. Try running the CLI tool, and it should print the help message:

convert2degas2 --help

2. From Source

It depends on Omega_h. Omega_h has to be built with Kokkos and it supports any Kokkos backend.

Follow these steps to build and install readOH2csg from source:

1. Make sure you have compilers (at least g++ or some alternative), Python (Version ≥ 3.11), and CMake available.
2. Install Kokkos following the instructions in Kokkos Build Documentation. You can choose any backend supported. Here's an example for building with the OpenMP backend:

git clone --depth=2 --branch 4.7.02 https://github.com/kokkos/kokkos.git
cd kokkos
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_COMPILER=g++ \
  -DBUILD_SHARED_LIBS=ON \
  -DKokkos_ENABLE_OPENMP=ON \
  -DCMAKE_INSTALL_PREFIX=<Kokkos_install_dir>

cmake --build build -j4 --target install

3. Install Omega_h with Kokkos support:

git clone https://github.com/SCOREC/omega_h.git
cd omega_h
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_COMPILER=g++ \
  -DBUILD_SHARED_LIBS=ON \
  -DOmega_h_USE_Kokkos=ON \
  -DKokkos_ROOT=<Kokkos_install_dir> \
  -DCMAKE_INSTALL_PREFIX=<Omega_h_install_dir>

cmake --build build -j4 --target install

4. Now, install readOH2csg:

git clone https://github.com/Fuad-HH/readOH2csg.git --branch parallel
cd readOH2csg

# configure
cmake -S . -B build \
  -DOmega_h_ROOT=<Omega_h_install_dir> \
  -DKokkos_ROOT=<Kokkos_install_dir> \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=<readOH2csg_install_dir>

# build
cmake --build build -j4 --target install

[!WARNING] For now, only the Python API and CLI work. Please do not turn off the option for Python bindings. It is enabled by default.

5. Create Python virtual environment and install dependencies as described in the Pre-built Wheel section.
6. Install readOH2csg and run the CLI tool, and it should print the help message:

# from the source directory
export KOKKOS_ROOT=<Kokkos_install_dir>
export OMEGA_H_ROOT=<Omega_h_install_dir>
python -m pip install .
convert2degas2 --help

Usage

Check an example case in tests/assets/simple_degas2_case/degas2-case. Please read the README.md file first for detailed instructions on how to run the example case.

To run an OpenMC example, running convert2openmc <mesh-name> will generate the geometry.xml file and, run the case following OpenMC Documentation.

[!TIP] If omegah2csg was installed with Kokkos OpenMP backend or using pip, try setting OpenMP environment variables for faster execution.

export OMP_PROC_BIND=spread && export OMP_PLACES=threads && export OMP_NUM_THREADS=<number of threads you want>

Documentation

More details on strategies, logic, and math are included in the doc/ directory.

Developer's Guide

For myself and future development, use the Developer's Guide to understand the code structure, design decisions, and how to contribute to this project.