Combine 2D and 3D Python modules (#128)

* Use new python stub generator

* Bindings with dim submodules

* Correct bindings order

* Add common module and fix setup

* Adjust examples

* Remove common module

* Improve material map

* Fix examples

* Small improvements

* Reuse ViennaCore test assert

* Improve SLLF scheme

* Wrap SLLF prepare and finalize function

* Bump dependencies

* Update Python stubs

* Add Python doc

* Format

* Fix actions Python test

* Bump VTK version and remove macOS deployment target

* Downgrade to previous VTK, use macOS fixes

* Add version header

* Format

* Fix Windows init path

Author: tobre1

.github/actions/setup/action.yml

@@ -22,11 +22,11 @@ runs:
       shell: bash
       if: ${{ inputs.os == 'macos-latest' }}
       run: |
-        brew reinstall --build-from-source libomp
+        brew install libomp
         echo "OpenMP_ROOT=$(brew --prefix)/opt/libomp" >> $GITHUB_ENV
 
     - name: 💻 Setup Deployment Target
       shell: bash
       if: ${{ inputs.os == 'macos-latest' }}
       run: |
-        echo "MACOSX_DEPLOYMENT_TARGET=14.0" >> $GITHUB_ENV
+        echo "MACOSX_DEPLOYMENT_TARGET=15.0" >> $GITHUB_ENV

.github/workflows/python.yml

@@ -58,14 +58,14 @@ jobs:
           python -m venv venv
           ./venv/Scripts/activate.bat
           pip install .
-          python -c "import viennals2d; print(viennals2d.__doc__)"
+          python -c "import viennals; print(viennals.__doc__)"
 
       - name: 🐍 Build and check Python Module (Other)
         if: ${{ matrix.os != 'windows-latest' }}
         run: |
           python -m venv venv
           CMAKE_ARGS=-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=OFF ./venv/bin/pip install . # Alpine does not like LTO
-          ./venv/bin/python -c "import viennals2d; print(viennals2d.__doc__)"
+          ./venv/bin/python -c "import viennals; print(viennals.__doc__)"
 
       - name: 📦 Upload Artifact
         uses: actions/upload-artifact@v4

.gitignore

@@ -22,4 +22,5 @@ _generate/
 *.egg-info
 *env*
 .mypy_cache/
-.eggs/
+.eggs/
+test.ipynb

CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
 project(
   ViennaLS
   LANGUAGES CXX
-  VERSION 4.5.0)
+  VERSION 5.0.0)
 
 # --------------------------------------------------------------------------------------------------------
 # Library options
@@ -90,6 +90,10 @@ endif()
 # Include directories
 # --------------------------------------------------------------------------------------------------------
 
+# Generate version header
+configure_file("${PROJECT_SOURCE_DIR}/cmake/lsVersion.hpp.in"
+               "${PROJECT_SOURCE_DIR}/include/viennals/lsVersion.hpp" @ONLY)
+
 target_include_directories(
   ${PROJECT_NAME} INTERFACE $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include/viennals>
                             $<INSTALL_INTERFACE:include/viennals-${PROJECT_VERSION}>)
@@ -103,7 +107,7 @@ include(cmake/vtk.cmake)
 
 CPMAddPackage(
   NAME ViennaCore
-  VERSION 1.5.0
+  VERSION 1.6.0
   GIT_REPOSITORY "https://github.com/ViennaTools/ViennaCore"
   OPTIONS "VIENNACORE_FORMAT_EXCLUDE docs/ build/"
   EXCLUDE_FROM_ALL ${VIENNALS_BUILD_PYTHON})
@@ -116,7 +120,7 @@ CPMAddPackage(
 
 CPMFindPackage(
   NAME ViennaHRLE
-  VERSION 0.6.1
+  VERSION 0.7.0
   GIT_REPOSITORY "https://github.com/ViennaTools/ViennaHRLE"
   EXCLUDE_FROM_ALL ${VIENNALS_BUILD_PYTHON})
 
@@ -128,37 +132,46 @@ if(VIENNALS_USE_VTK AND VIENNALS_VTK_PYTHON_LIBS)
 elseif(VIENNALS_USE_VTK)
   enable_language(C)
 
+  # Common VTK build options
+  set(VTK_OPTIONS
+      "VTK_LEGACY_REMOVE ON"
+      "VTK_SMP_IMPLEMENTATION_TYPE OpenMP"
+      "VTK_GROUP_ENABLE_Rendering NO"
+      "VTK_GROUP_ENABLE_Imaging NO"
+      "VTK_GROUP_ENABLE_Views NO"
+      "VTK_GROUP_ENABLE_Web NO"
+      "VTK_GROUP_ENABLE_Qt NO"
+      "VTK_GROUP_ENABLE_MPI NO"
+      "VTK_ENABLE_WRAPPING NO"
+      "VTK_MODULE_ENABLE_VTK_libproj NO"
+      "VTK_MODULE_ENABLE_VTK_CommonExecutionModel YES"
+      "VTK_MODULE_ENABLE_VTK_CommonMisc YES"
+      "VTK_MODULE_ENABLE_VTK_CommonSystem YES"
+      "VTK_MODULE_ENABLE_VTK_CommonMath YES"
+      "VTK_MODULE_ENABLE_VTK_CommonCore YES"
+      "VTK_MODULE_ENABLE_VTK_CommonTransforms YES"
+      "VTK_MODULE_ENABLE_VTK_CommonComputationalGeometry YES"
+      "VTK_MODULE_ENABLE_VTK_IOCore YES"
+      "VTK_MODULE_ENABLE_VTK_IOXMLParser YES"
+      "VTK_MODULE_ENABLE_VTK_IOXML YES"
+      "VTK_MODULE_ENABLE_VTK_FiltersCore YES"
+      "VTK_MODULE_ENABLE_VTK_FiltersGeneral YES"
+      "VTK_MODULE_ENABLE_VTK_FiltersGeometry YES"
+      "CMAKE_PROJECT_NAME VTK")
+
+  # macOS-specific adds
+  if(APPLE)
+    list(APPEND VTK_OPTIONS "VTK_MODULE_USE_EXTERNAL_VTK_png ON"
+         "VTK_MODULE_USE_EXTERNAL_VTK_zlib ON")
+  endif()
+
   CPMFindPackage(
     NAME VTK
     GIT_TAG v9.3.1
     VERSION 9.0.0
     GIT_REPOSITORY "https://gitlab.kitware.com/vtk/vtk"
     EXCLUDE_FROM_ALL ${VIENNALS_BUILD_PYTHON}
-    OPTIONS "VTK_LEGACY_REMOVE ON"
-            "VTK_SMP_IMPLEMENTATION_TYPE \"OpenMP\""
-            "VTK_GROUP_ENABLE_Rendering NO"
-            "VTK_GROUP_ENABLE_Imaging NO"
-            "VTK_GROUP_ENABLE_Views NO"
-            "TK_GROUP_ENABLE_Web NO"
-            "VTK_GROUP_ENABLE_Qt NO"
-            "VTK_GROUP_ENABLE_MPI NO"
-            "VTK_ENABLE_WRAPPING NO"
-            "VTK_MODULE_ENABLE_VTK_libproj NO"
-            "VTK_MODULE_ENABLE_VTK_CommonExecutionModel YES"
-            "VTK_MODULE_ENABLE_VTK_CommonMisc YES"
-            "VTK_MODULE_ENABLE_VTK_CommonSystem YES"
-            "VTK_MODULE_ENABLE_VTK_CommonMath YES"
-            "VTK_MODULE_ENABLE_VTK_CommonCore YES"
-            "VTK_MODULE_ENABLE_VTK_CommonTransforms YES"
-            "VTK_MODULE_ENABLE_VTK_CommonComputationalGeometry YES"
-            "VTK_MODULE_ENABLE_VTK_IOCore YES"
-            "VTK_MODULE_ENABLE_VTK_IOXMLParser YES"
-            "VTK_MODULE_ENABLE_VTK_IOXML YES"
-            "VTK_MODULE_ENABLE_VTK_FiltersCore YES"
-            "VTK_MODULE_ENABLE_VTK_FiltersGeneral YES"
-            "VTK_MODULE_ENABLE_VTK_FiltersGeometry YES"
-            # This fixes an issue with the install script that causes find_package to fail.
-            "CMAKE_PROJECT_NAME VTK")
+    OPTIONS ${VTK_OPTIONS})
 
   target_compile_definitions(${PROJECT_NAME} INTERFACE VIENNALS_USE_VTK=1)
 

PythonAPI.md

@@ -0,0 +1,106 @@
+# ViennaLS Python API
+
+This document lists all functions, classes, and enums available in the **ViennaLS** Python package.  
+Functions are grouped into **dimension-bound** and **dimension-independent** components.
+
+---
+
+## **Dimension-Bound Functions**
+
+These functions are tied to either the **2D** or **3D** version of the library.  
+They must be imported from either `viennals.d2` or `viennals.d3`.
+
+### **Core Classes and Operations**
+- `Domain`
+- `Advect`
+- `BooleanOperation`
+- `CalculateCurvatures`
+- `CalculateNormalVectors`
+- `CalculateVisibilities`
+- `Check`
+- `PointCloud`
+- `ConvexHull`
+- `DetectFeatures`
+- `GeometricAdvect`
+- `GeometricAdvectDistributions`
+- `SphereDistribution`
+- `BoxDistribution`
+- `Expand`
+- `FromSurfaceMesh`
+- `FromVolumeMesh`
+- `FromMesh`
+- `Sphere`
+- `Plane`
+- `Box`
+- `Cylinder`
+- `MakeGeometry`
+- `MarkVoidPoints`
+- `Prune`
+- `Reader`
+- `Reduce`
+- `RemoveStrayPoints`
+- `ToDiskMesh`
+- `ToMesh`
+- `ToSurfaceMesh`
+- `ToVoxelMesh`
+- `Writer`
+- `WriteVisualizationMesh`
+
+### **2D-Only Functions**
+- `CompareArea`
+- `CompareNarrowBand`
+- `CompareSparseField`
+
+---
+
+## **Dimension-Independent Components**
+
+These are imported directly from the **root** `viennals` module.
+
+### **Enums**
+- `LogLevel`
+- `IntegrationSchemeEnum`
+- `BooleanOperationEnum`
+- `CurvatureEnum`
+- `FeatureDetectionEnum`
+- `BoundaryConditionEnum`
+- `FileFormatEnum`
+- `VoidTopSurfaceEnum`
+- `TransformEnum`
+
+### **Mesh and I/O Classes**
+- `Mesh`
+- `PointData`
+- `TransformMesh`
+- `VTKReader`
+- `VTKWriter`
+
+### **Utilities**
+- `Logger`
+- `MaterialMap`
+- `VelocityField`
+
+---
+
+## **Transformations Between Dimensions**
+
+These functions enable conversion between 2D and 3D representations and are also imported from the root `viennals` module:
+- `Slice`
+- `Extrude`
+
+---
+
+## **Example Imports**
+
+```python
+# 2D functions and domain-specific operations
+import viennals.d2 as vls
+
+domain = vls.Domain()
+vls.Advect(domain, ...)
+
+# Common functions and enums
+import viennals
+
+mesh = viennals.Mesh()
+enum = viennals.BooleanOperationEnum.UNION

README.md

@@ -111,14 +111,22 @@ pip install .
 
 All functions which are available in C++ are also available in Python. The 2D version of the library can be imported as follows:
 ```python
-import viennals2d as vls
+import viennals.d2 as vls 
+import viennals # for common functions
 ```
 
-In order to switch to three dimensions, only the import needs to be changed:
+To switch to 3D, only the import changes:
 
 ```python
-import viennals3d as vls
+import viennals.d3 as vls
 ```
+Functions that operate on a domain object (e.g. `Advect`, `ToSurfaceMesh`, ...) are provided in the respective `d2` or `d3` modules.
+Common functions, enums, and dimension-independent utilities (such as `Mesh`) are available directly in the `viennals` namespace.
+
+A complete list of functions and their locations can be found in the [API documentation](PythonAPI.md).
+
+For examples on how to use the Python package, please have a look at these examples: [Air Gap Deposition](https://github.com/ViennaTools/ViennaLS/blob/master/examples/AirGapDeposition/AirGapDeposition.py), [Deposition](https://github.com/ViennaTools/ViennaLS/blob/master/examples/Deposition/Deposition.py), [Geometric Advection](https://github.com/ViennaTools/ViennaLS/blob/master/examples/GeometricAdvection/GeometricAdvection.py).
+
 
 ## Running the Tests
 
@@ -149,7 +157,7 @@ We recommend using [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake) to consum
 
 * Installation with CPM
   ```cmake
-  CPMAddPackage("gh:viennatools/viennals@4.5.0")
+  CPMAddPackage("gh:viennatools/viennals@5.0.0")
   ```
 
 * With a local installation

cmake/lsVersion.hpp.in

@@ -0,0 +1,37 @@
+#pragma once
+
+#include <cstdint>
+
+namespace viennals {
+
+// Version information generated by CMake
+inline constexpr const char *version = "@PROJECT_VERSION@";
+inline constexpr int versionMajor = @PROJECT_VERSION_MAJOR@;
+inline constexpr int versionMinor = @PROJECT_VERSION_MINOR@;
+inline constexpr int versionPatch = @PROJECT_VERSION_PATCH@;
+
+// Utility functions for version comparison
+inline constexpr uint32_t versionAsInteger() {
+  // Encode as MMmmpppp (2 digits major, 2 digits minor, 4 digits patch)
+  return static_cast<uint32_t>(versionMajor) * 1000000 +
+         static_cast<uint32_t>(versionMinor) * 10000 +
+         static_cast<uint32_t>(versionPatch);
+}
+
+inline constexpr bool isVersionAtLeast(int major, int minor = 0,
+                                       int patch = 0) {
+  if (versionMajor > major)
+    return true;
+  if (versionMajor < major)
+    return false;
+  if (versionMinor > minor)
+    return true;
+  if (versionMinor < minor)
+    return false;
+  return versionPatch >= patch;
+}
+
+// Version as string for display purposes
+inline constexpr const char *versionString() { return version; }
+
+} // namespace viennals

examples/AirGapDeposition/AirGapDeposition.py

@@ -1,12 +1,13 @@
-import viennals2d as vls
+import viennals.d2 as vls
+from viennals import VelocityField, Mesh, VTKWriter, BooleanOperationEnum
 
 # @example AirGapDeposition.py
 #  Example showing how to use the library for topography
 #  simulation, by creating a trench geometry. A layer of a different material is
 #  then grown directionally on top.
 
 
-class velocityField(vls.VelocityField):
+class velocityField(VelocityField):
     # coord and normalVec are lists with 3 elements
     # in 2D coord[2] and normalVec[2] are zero
     # getScalarVelocity must return a scalar
@@ -33,9 +34,9 @@ def getVectorVelocity(self, coord, material, normal, pointId):
 vls.MakeGeometry(substrate, vls.Plane(origin, planeNormal)).apply()
 
 print("Extracting")
-mesh = vls.Mesh()
+mesh = Mesh()
 vls.ToSurfaceMesh(substrate, mesh).apply()
-vls.VTKWriter(mesh, "plane.vtp").apply()
+VTKWriter(mesh, "plane.vtp").apply()
 
 # create layer used for booling
 print("Creating box...")
@@ -46,12 +47,12 @@ def getVectorVelocity(self, coord, material, normal, pointId):
 
 print("Extracting")
 vls.ToMesh(trench, mesh).apply()
-vls.VTKWriter(mesh, "box.vtp").apply()
+VTKWriter(mesh, "box.vtp").apply()
 
 # Create trench geometry
 print("Booling trench")
 vls.BooleanOperation(
-    substrate, trench, vls.BooleanOperationEnum.RELATIVE_COMPLEMENT
+    substrate, trench, BooleanOperationEnum.RELATIVE_COMPLEMENT
 ).apply()
 
 # Now grow new material
@@ -86,7 +87,7 @@ def getVectorVelocity(self, coord, material, normal, pointId):
     print("Advection step {} / {}".format(i, numberOfSteps))
 
     vls.ToSurfaceMesh(newLayer, mesh).apply()
-    writer = vls.VTKWriter(mesh, "trench{}.vtp".format(i))
+    writer = VTKWriter(mesh, "trench{}.vtp".format(i))
     writer.addMetaData("time", passedTime)
     writer.apply()