Refactor test methods and add RadiationModel support

Refactored test suite to align with updated method naming conventions in Helios (e.g., camelCase). Added a new RadiationModel module with Python bindings for radiation transport simulation, alongside supporting ctypes wrappers and CMake configurations for the radiation plugin. This extends functionality to handle radiative transfer models leveraging CUDA/OptiX.

Author: bnbailey-psl

.github/workflows/test-linux.yml

@@ -23,10 +23,12 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install system dependencies
+    - name: Install dependencies using Helios script
       run: |
-        sudo apt-get update
-        sudo apt-get install -y build-essential cmake
+        cd helios-core
+        chmod +x utilities/dependencies.sh
+        # Install BASE dependencies (includes build-essential, cmake)
+        bash utilities/dependencies.sh BASE
 
     - name: Install Python dependencies
       run: |

.github/workflows/test-macos.yml

@@ -23,11 +23,12 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install system dependencies
+    - name: Install dependencies using Helios script
       run: |
-        # Install Xcode command line tools (usually pre-installed on GitHub runners)
-        # xcode-select --install
-        brew install cmake
+        cd helios-core
+        chmod +x utilities/dependencies.sh
+        # Install BASE dependencies (includes cmake and build tools)
+        bash utilities/dependencies.sh BASE
 
     - name: Install Python dependencies
       run: |

.github/workflows/test-matrix.yml

@@ -27,16 +27,13 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install system dependencies (Linux)
-      if: matrix.os == 'ubuntu-latest'
+    - name: Install dependencies using Helios script (Linux/macOS)
+      if: matrix.os != 'windows-latest'
       run: |
-        sudo apt-get update
-        sudo apt-get install -y build-essential cmake
-
-    - name: Install system dependencies (macOS)
-      if: matrix.os == 'macos-latest'
-      run: |
-        brew install cmake
+        cd helios-core
+        chmod +x utilities/dependencies.sh
+        # Install BASE dependencies (GCC, G++, CMake) for matrix testing
+        bash utilities/dependencies.sh BASE
 
     - name: Set up MSVC (Windows)
       if: matrix.os == 'windows-latest'
@@ -202,16 +199,13 @@ jobs:
       with:
         python-version: "3.11"
 
-    - name: Install system dependencies (Linux)
-      if: matrix.os == 'ubuntu-latest'
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y build-essential cmake
-
-    - name: Install system dependencies (macOS)
-      if: matrix.os == 'macos-latest'
+    - name: Install dependencies using Helios script (Linux/macOS)  
+      if: matrix.os != 'windows-latest'
       run: |
-        brew install cmake
+        cd helios-core
+        chmod +x utilities/dependencies.sh
+        # Install BASE dependencies for build script testing
+        bash utilities/dependencies.sh BASE
 
     - name: Set up MSVC (Windows)
       if: matrix.os == 'windows-latest'

.github/workflows/test-native.yml

@@ -34,21 +34,25 @@ jobs:
       with:
         python-version: "3.11"
 
-    - name: Install system dependencies (Linux)
-      if: matrix.os == 'ubuntu-latest'
+    - name: Install dependencies using Helios script (Linux/macOS)
+      if: matrix.os != 'windows-latest'
       run: |
-        sudo apt-get update
-        sudo apt-get install -y build-essential cmake libx11-dev xorg-dev libgl1-mesa-dev libglu1-mesa-dev libxrandr-dev
-
-    - name: Install system dependencies (macOS)
-      if: matrix.os == 'macos-latest'
-      run: |
-        brew install cmake
+        cd helios-core
+        chmod +x utilities/dependencies.sh
+        # Install VIS dependencies (includes base + OpenGL/X11 for visualization)
+        bash utilities/dependencies.sh VIS
 
     - name: Set up MSVC (Windows)
       if: matrix.os == 'windows-latest'
       uses: ilammy/msvc-dev-cmd@v1
 
+    - name: Install basic dependencies (Windows)
+      if: matrix.os == 'windows-latest'
+      run: |
+        # Note: dependencies.sh doesn't handle Windows package installation
+        # but provides guidance. MSVC is already set up above.
+        echo "Windows dependencies: Visual Studio (MSVC) is already configured"
+
     - name: Install Python dependencies
       run: |
         python -m pip install --upgrade pip
@@ -97,17 +101,17 @@ jobs:
             from pyhelios import Context, DataTypes
             with Context() as ctx:
                 print(f'Context created successfully')
-                count = ctx.get_primitive_count()
+                count = ctx.getPrimitiveCount()
                 print(f'Initial primitive count: {count}')
                 
                 # Test adding a patch
-                center = DataTypes.Vec3(1, 2, 3)
-                size = DataTypes.Vec2(1, 1)
+                center = DataTypes.vec3(1, 2, 3)
+                size = DataTypes.vec2(1, 1)
                 color = DataTypes.RGBcolor(0.5, 0.5, 0.5)
-                patch_id = ctx.add_patch(center=center, size=size, color=color)
+                patch_id = ctx.addPatch(center=center, size=size, color=color)
                 print(f'Added patch with ID: {patch_id}')
                 
-                new_count = ctx.get_primitive_count()
+                new_count = ctx.getPrimitiveCount()
                 print(f'New primitive count: {new_count}')
                 assert new_count == count + 1, f'Expected {count + 1}, got {new_count}'
                 
@@ -136,10 +140,10 @@ jobs:
                 print('Testing WeberPennTree with native libraries...')
                 with Context() as ctx:
                     with WeberPennTree(ctx) as wpt:
-                        tree_id = wpt.build_tree(WPTType.LEMON)
+                        tree_id = wpt.buildTree(WPTType.LEMON)
                         print(f'✓ Built tree with ID: {tree_id}')
                         
-                        trunk_uuids = wpt.get_trunk_uuids(tree_id)
+                        trunk_uuids = wpt.getTrunkUUIDs(tree_id)
                         print(f'✓ Tree has {len(trunk_uuids)} trunk segments')
             else:
                 print('ERROR: Native libraries not available for WeberPennTree testing')

.github/workflows/test-quick.yml

@@ -51,7 +51,7 @@ jobs:
             print('✓ Context created (mock mode)')
             
             # This should work in mock mode
-            count = ctx.get_primitive_count()
+            count = ctx.getPrimitiveCount()
             print(f'✓ Primitive count: {count}')
             
         except RuntimeError as e:
@@ -61,7 +61,7 @@ jobs:
                 raise
         
         print('Testing DataTypes...')
-        v = DataTypes.Vec3(1.0, 2.0, 3.0)
+        v = DataTypes.vec3(1.0, 2.0, 3.0)
         print(f'✓ Vec3 created: {v}')
         
         c = DataTypes.RGBcolor(0.5, 0.7, 0.2)

.github/workflows/test-required.yml

@@ -61,7 +61,7 @@ jobs:
             print('✓ Context created successfully')
             
             # Test DataTypes
-            v = DataTypes.Vec3(1.0, 2.0, 3.0)
+            v = DataTypes.vec3(1.0, 2.0, 3.0)
             print(f'✓ Vec3 created: ({v.x}, {v.y}, {v.z})')
             
             c = DataTypes.RGBcolor(0.5, 0.7, 0.2)
@@ -93,21 +93,23 @@ jobs:
       with:
         python-version: "3.11"
 
-    - name: Install system dependencies (Linux)
-      if: matrix.os == 'ubuntu-latest'
+    - name: Install dependencies using Helios script (Linux/macOS)
+      if: matrix.os != 'windows-latest'
       run: |
-        sudo apt-get update
-        sudo apt-get install -y build-essential cmake libx11-dev xorg-dev libgl1-mesa-dev libglu1-mesa-dev libxrandr-dev
-
-    - name: Install system dependencies (macOS)
-      if: matrix.os == 'macos-latest'
-      run: |
-        brew install cmake
+        cd helios-core
+        chmod +x utilities/dependencies.sh
+        # Install VIS dependencies (includes base + OpenGL/X11 for visualization)
+        bash utilities/dependencies.sh VIS
 
     - name: Set up MSVC (Windows)
       if: matrix.os == 'windows-latest'
       uses: ilammy/msvc-dev-cmd@v1
 
+    - name: Install basic dependencies (Windows)
+      if: matrix.os == 'windows-latest'
+      run: |
+        echo "Windows dependencies: Visual Studio (MSVC) is already configured"
+
     - name: Install Python dependencies
       run: |
         python -m pip install --upgrade pip

README.md

@@ -19,24 +19,11 @@ PyHelios now works across multiple platforms:
 - ✅ **Windows** (x64) - Full native support
 - ✅ **macOS** (Intel/Apple Silicon) - Native support with build-from-source
 - ✅ **Linux** (x64) - Native support with build-from-source  
-- ✅ **Development Mode** - Mock mode for development on any platform
+- ✅ **Development Mode** - Explicit mock mode for development without native libraries
 
 ## Installation
 
-### Quick Start (Development/Mock Mode)
-
-For immediate use without native libraries (mock mode):
-
-```bash
-# Clone repository with Helios core
-git clone --recursive git@github.com:PlantSimulationLab/PyHelios.git
-cd PyHelios/
-
-# Install in development mode
-pip install -e .[dev]
-```
-
-### Full Installation with Native Libraries
+### Full Installation with Native Helios Libraries
 
 #### Windows
 ```bash
@@ -115,9 +102,9 @@ tree_id_lemon = wpt.buildTree(WPTType.LEMON)
 tree_id_olive = wpt.buildTree(WPTType.OLIVE)
 ```
 
-## Platform Status and Mock Mode
+## Platform Status and Library Requirements
 
-PyHelios automatically detects available native libraries and gracefully falls back to mock mode when they're not available:
+PyHelios detects available native libraries and provides clear feedback about the current status:
 
 ```python
 from pyhelios.plugins import print_plugin_status
@@ -131,7 +118,7 @@ print_plugin_status()
 #   Mock mode: True
 ```
 
-In mock mode, PyHelios provides full API compatibility but operations will raise informative errors explaining that native libraries are required for full functionality.
+**Important**: PyHelios follows a fail-fast philosophy. When native libraries are not available, operations will raise explicit `RuntimeError` exceptions with clear, actionable error messages explaining what failed and how to fix it. Mock mode is only used during development and testing - it does not silently provide fallback functionality.
 
 ## Development and Testing
 
@@ -163,9 +150,10 @@ python build_scripts/build_helios.py --cmake-args -DCMAKE_BUILD_TYPE=Debug --ver
 
 ## Troubleshooting
 
-### Mock Mode Issues
-- **Problem**: All operations raise "mock mode" errors
+### Native Library Requirements
+- **Problem**: Operations raise "mock mode" or "native library required" errors
 - **Solution**: Build and install native libraries using `python build_scripts/build_helios.py`
+- **Note**: PyHelios requires native libraries for full functionality - mock mode is only for development/testing
 
 ### Build Issues  
 - **Windows**: Ensure Visual Studio or Build Tools are installed

build_scripts/build_helios.py

@@ -101,8 +101,9 @@ def check_prerequisites(self) -> None:
                 except (subprocess.CalledProcessError, FileNotFoundError):
                     raise HeliosBuildError("No suitable compiler found (gcc or clang)")
 
-        # Check that helios-core directory exists and has the new build structure
-        pyhelios_cmake = self.helios_root / 'pyhelios_build' / 'CMakeLists.txt'
+        # Check that pyhelios_build directory exists in the main repo
+        pyhelios_build_dir = self.helios_root.parent / 'pyhelios_build'
+        pyhelios_cmake = pyhelios_build_dir / 'CMakeLists.txt'
         if not pyhelios_cmake.exists():
             raise HeliosBuildError(f"PyHelios build CMakeLists.txt not found: {pyhelios_cmake}")
 
@@ -125,7 +126,7 @@ def run_cmake_configure(self, additional_args: Optional[List[str]] = None) -> No
         """Run CMake configuration."""
         cmake_cmd = [
             'cmake',
-            str(self.helios_root / 'pyhelios_build'),  # Use new PyHelios build project
+            str(self.helios_root.parent / 'pyhelios_build'),  # Use PyHelios build project in main repo
             '-G', self.config['generator']
         ]
 
@@ -195,16 +196,69 @@ def find_built_library(self) -> Path:
         for path in self.build_dir.rglob(lib_name):
             print(f"Found built library: {path}")
             return path
+            
+        # If shared library not found, look for static library as fallback
+        if self.platform_name in ['Darwin', 'Linux']:
+            static_lib = 'libhelios.a'
+            static_paths = [
+                self.build_dir / 'lib' / static_lib,
+                self.build_dir / static_lib,
+            ]
+            for path in static_paths:
+                if path.exists():
+                    print(f"Found static library (will need conversion): {path}")
+                    return path
+            
+            # Search recursively for static library
+            for path in self.build_dir.rglob(static_lib):
+                print(f"Found static library (will need conversion): {path}")
+                return path
 
         raise HeliosBuildError(f"Built library {lib_name} not found in build directory")
 
     def copy_to_output(self, library_path: Path) -> None:
         """Copy built library to output directory."""
         self.output_dir.mkdir(parents=True, exist_ok=True)
-        output_path = self.output_dir / library_path.name
 
-        shutil.copy2(library_path, output_path)
-        print(f"Copied library to: {output_path}")
+        # Check if we found a static library but need a shared library
+        if library_path.name == 'libhelios.a' and self.platform_name in ['Darwin', 'Linux']:
+            print("Found static library but PyHelios needs shared library for ctypes")
+            print("Attempting to convert static to shared library...")
+            
+            # Create shared library from static library
+            shared_lib_name = self.config['lib_name']
+            output_path = self.output_dir / shared_lib_name
+            
+            try:
+                if self.platform_name == 'Darwin':
+                    # macOS: Use libtool to create shared library
+                    cmd = [
+                        'libtool', '-dynamic', '-o', str(output_path),
+                        str(library_path), '-lc++'
+                    ]
+                else:  # Linux
+                    # Linux: Use gcc to create shared library
+                    cmd = [
+                        'gcc', '-shared', '-o', str(output_path),
+                        '-Wl,--whole-archive', str(library_path), '-Wl,--no-whole-archive',
+                        '-lstdc++'
+                    ]
+                
+                subprocess.run(cmd, check=True)
+                print(f"Successfully converted static to shared library: {output_path}")
+                
+            except subprocess.CalledProcessError as e:
+                print(f"Warning: Failed to convert static to shared library: {e}")
+                # Fall back to copying the static library
+                output_path = self.output_dir / library_path.name
+                shutil.copy2(library_path, output_path)
+                print(f"Copied static library as fallback: {output_path}")
+                
+        else:
+            # Normal case: copy the library directly
+            output_path = self.output_dir / library_path.name
+            shutil.copy2(library_path, output_path)
+            print(f"Copied library to: {output_path}")
 
         # Also copy any additional required files
         if self.platform_name == 'Windows':