[v0.0.4] 2025-08-25

🚨++ New Plug-in Integrated ++ 🚨
- Energy Balance plug-in integrated with PyHelios

## Visualizer
- Added `Visualizer.colorContextPrimitivesByData()`
- Fixed a number of issues where visualizer methods were using lists instead of Helios data types (e.g., vec2, vec3, etc.)

Author: bnbailey-psl

.github/workflows/docs.yml

@@ -54,6 +54,13 @@ jobs:
         doxygen --version
         doxypypy --help
         
+    - name: Sync version to Doxygen config
+      run: |
+        # Get version from setuptools-scm and update Doxyfile
+        VERSION=$(python -c "from pyhelios._version import __version__; print(__version__)")
+        echo "Updating Doxygen PROJECT_NUMBER to: $VERSION"
+        sed -i "s/^PROJECT_NUMBER.*$/PROJECT_NUMBER         = $VERSION/" docs/Doxyfile.python
+        
     - name: Build documentation
       run: |
         # Create output directory
@@ -118,6 +125,13 @@ jobs:
         pip install -r requirements.txt
         pip install -e .
         
+    - name: Sync version to Doxygen config (preview)
+      run: |
+        # Get version from setuptools-scm and update Doxyfile
+        VERSION=$(python -c "from pyhelios._version import __version__; print(__version__)")
+        echo "Updating Doxygen PROJECT_NUMBER to: $VERSION"
+        sed -i "s/^PROJECT_NUMBER.*$/PROJECT_NUMBER         = $VERSION/" docs/Doxyfile.python
+        
     - name: Build documentation (preview)
       run: |
         mkdir -p docs/generated

.github/workflows/pytest-linux-gpu.yaml

@@ -21,8 +21,8 @@ jobs:
           role-to-assume: ${{ secrets.OIDC_ROLE_ARN }}
           aws-region: us-west-2
       - run: |
-          aws ec2 start-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
-          aws ec2 wait instance-running --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
+          aws ec2 start-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }}
+          aws ec2 wait instance-running --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }}
 
   run_pyhelios_gpu_tests:
     runs-on: [self-hosted]
@@ -90,5 +90,5 @@ jobs:
           role-to-assume: ${{ secrets.OIDC_ROLE_ARN }}
           aws-region: us-west-2
       - run: |
-          aws ec2 stop-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
-          aws ec2 wait instance-stopped --instance-ids ${{ secrets.EC2_INSTANCE_ID }}
+          aws ec2 stop-instances --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }}
+          aws ec2 wait instance-stopped --instance-ids ${{ secrets.EC2_INSTANCE_ID_LINUX }}

CLAUDE.md

@@ -96,8 +96,6 @@ python -m pyhelios.plugins info radiation
 # Validate plugin configuration
 python -m pyhelios.plugins validate --plugins radiation,visualizer
 
-# List all available profiles
-python -m pyhelios.plugins profiles
 ```
 
 #### Configuration File Support
@@ -106,7 +104,9 @@ Create `pyhelios_config.yaml` to specify default plugin selection:
 
 ```yaml
 plugins:
-  profile: "standard"
+  explicit_plugins:
+    - weberpenntree
+    - visualizer
   excluded_plugins:
     - radiation  # Exclude if no GPU available
 
@@ -180,20 +180,6 @@ PyHelios uses a sophisticated plugin-based architecture supporting **21 availabl
 - **visualizer**: OpenGL-based 3D visualization and rendering
 - **projectbuilder**: GUI project builder with ImGui interface
 
-#### Plugin Selection Profiles
-
-The system includes predefined profiles for common use cases:
-
-- **minimal**: Core functionality only (weberpenntree, canopygenerator, solarposition)
-- **standard**: Standard features with visualization (adds visualizer, energybalance, photosynthesis)
-- **gpu-accelerated**: High-performance GPU features (adds radiation for ray tracing)
-- **research**: Comprehensive research suite (includes most plugins for academic use)
-- **production**: Production-ready features (reliable, well-tested plugins)
-- **visualization**: Focus on rendering and visualization capabilities
-- **sensing**: Remote sensing and LiDAR simulation capabilities  
-- **physics**: Comprehensive physics modeling and simulation
-- **development**: Minimal set for PyHelios development and testing
-
 ### Cross-Platform Library Loading
 
 PyHelios includes a sophisticated cross-platform library loader (`pyhelios/plugins/loader.py`):
@@ -448,6 +434,16 @@ pytest tests/test_context.py -v
 - Tests provide clear output showing passed/skipped/failed counts  
 - Zero warnings and errors in final test execution
 
+**CRITICAL: Mandatory Full Verification Protocol**
+For ANY changes to C++ interface files (native/src/*, native/include/*, pyhelios_build/*), ctypes wrappers, or core functionality, you MUST complete this verification sequence:
+
+1. **Full Native Rebuild**: Run `build_scripts/build_helios --clean` to rebuild from scratch
+2. **Complete Test Suite**: Run `pytest` (not individual tests) to verify ALL tests pass
+3. **Zero Tolerance**: Any failing tests must be fixed before declaring success
+4. **No Shortcuts**: Never skip the full test suite even if "individual tests pass"
+
+This protocol is NON-NEGOTIABLE and must be completed regardless of time constraints or apparent simplicity of changes.
+
 **GitHub CI/CD Integration:**
 - Comprehensive CI/CD workflows test PyHelios across all platforms
 - Quick tests (`test-quick.yml`) for fast development feedback
@@ -469,6 +465,16 @@ pytest tests/test_context.py -v
 - **Mock mode development**: Develop and test PyHelios functionality without requiring native library compilation
 - **Test categories**: Use `pytest -m cross_platform` for platform-independent tests, `pytest -m native_only` for native library tests
 
+**MANDATORY: Final Verification Checklist**
+Before declaring ANY task complete involving C++/Python interface changes:
+□ Built native libraries from scratch using `build_scripts/build_helios --clean`
+□ Ran complete `pytest` suite (not selective tests)
+□ All tests pass with zero failures
+□ No regressions introduced in any module
+□ Changes committed to git if task involves file modifications
+
+Failure to complete this checklist constitutes incomplete task execution.
+
 **Architecture and Integration:**
 - **UUID-based tracking**: All geometric operations return UUIDs for object tracking
 - **Context state management**: The Context manages geometry state with dirty/clean marking
@@ -512,7 +518,7 @@ PyHelios has successfully integrated 3 major Helios C++ plugins (radiation, visu
 
 **ALWAYS follow the 8-phase integration process:**
 
-1. **Plugin Metadata Registration** - Add to `pyhelios/config/plugin_metadata.py` and relevant profiles
+1. **Plugin Metadata Registration** - Add to `pyhelios/config/plugin_metadata.py`
 2. **Build System Integration** - CMake and flexible plugin selection system
 3. **C++ Interface Implementation** - Add wrapper functions to `pyhelios_build/pyhelios_interface.cpp`
 4. **ctypes Wrapper Creation** - Python-to-C++ interface in `pyhelios/wrappers/`
@@ -541,6 +547,9 @@ Many plugins require runtime assets that must be copied to specific locations wh
 - Map parameters semantically, not just positionally
 - Test different parameter combinations
 
+**Git Control**:
+- Be sure to add any files to git control that will be needed in the repository.
+
 #### Documentation Requirements
 
 For plugin integration tasks, ALWAYS:
@@ -554,7 +563,7 @@ For plugin integration tasks, ALWAYS:
 All plugin integrations MUST include:
 - **Cross-platform tests** (`@pytest.mark.cross_platform`) that work with mock mode
 - **Native-only tests** (`@pytest.mark.native_only`) that require actual plugin functionality
-- **Plugin metadata tests** to verify registration and profiles
+- **Plugin metadata tests** to verify registration
 - **Error handling tests** to verify proper exception translation
 - **Asset management tests** to verify runtime dependencies are available
 

README.md

@@ -14,6 +14,10 @@ PyHelios provides a Python interface to the powerful Helios C++ library for 3D p
 
 📖 **[Complete Documentation](https://plantsimulationlab.github.io/PyHelios/)**
 
+⚠️Note that this is a work in progress. Not all Helios functionality has been implemented in PyHelios ⚠️
+
+See the Helios C++ documentation for a more in-depth description of Helios: https://baileylab.ucdavis.edu/software/helios
+
 ## Quick Start
 
 ### Installation
@@ -66,10 +70,6 @@ pip install -e .
 - Python 3.7+
 
 ```bash
-# Install prerequisites
-sudo apt-get update
-sudo apt-get install build-essential cmake python3-dev
-
 # Clone repository
 git clone --recursive https://github.com/PlantSimulationLab/PyHelios.git
 cd PyHelios/
@@ -100,18 +100,6 @@ patch_uuid = context.addPatch(center=center, size=size, color=color)
 print(f"Created patch: {patch_uuid}")
 ```
 
-### Tree Modeling
-
-```python
-from pyhelios import Context, WeberPennTree
-
-context = Context()
-wpt = WeberPennTree(context)
-
-# Generate procedural tree
-tree_id = wpt.buildTree(WeberPennTree.WPTType.LEMON)
-```
-
 ## Documentation
 
 | Section | Description |
@@ -127,7 +115,7 @@ tree_id = wpt.buildTree(WeberPennTree.WPTType.LEMON)
 - **Plant modeling**: WeberPennTree procedural generation 
 - **GPU acceleration**: OptiX-powered radiation simulation
 - **3D visualization**: OpenGL-based real-time rendering
-- **Flexible plugins**: 21 available plugins for specialized tasks
+- **Flexible plugins**: Currently 4 plug-ins implemented
 - **Development mode**: Mock mode for development without native libraries
 
 ## Quick Commands

build_scripts/build_helios.py

@@ -219,7 +219,7 @@ def clean_build_artifacts(self) -> None:
         With the current architecture, all build artifacts are contained within
         the build directory, so cleaning is simply removing that directory.
         """
-        print("🧹 Cleaning build artifacts...")
+        print("[CLEAN] Cleaning build artifacts...")
 
         # Remove the build directory - this contains all build artifacts
         if self.build_dir.exists():
@@ -265,13 +265,13 @@ def resolve_plugin_selection(self) -> List[str]:
 
         if result.warnings:
             for warning in result.warnings:
-                print(f"⚠️  Warning: {warning}")
+                print(f"[WARN] {warning}")
 
         if result.added_plugins:
             print(f"[OK] Added dependencies: {result.added_plugins}")
 
         if result.removed_plugins:
-            print(f"🚫 Removed incompatible plugins: {result.removed_plugins}")
+            print(f"[EXCLUDED] Removed incompatible plugins: {result.removed_plugins}")
 
         print(f"[OK] Final plugin selection: {result.final_plugins}")
         return result.final_plugins
@@ -1027,7 +1027,7 @@ def _copy_visualizer_assets(self) -> None:
         target_base_dir = self.output_dir.parent / 'plugins' / 'visualizer'
 
         if not build_visualizer_dir.exists():
-            print(f"ℹ️  Visualizer assets directory not found: {build_visualizer_dir} (visualizer plugin may not be enabled)")
+            print(f"[INFO] Visualizer assets directory not found: {build_visualizer_dir} (visualizer plugin may not be enabled)")
             return
 
         total_files_copied = 0
@@ -1093,9 +1093,9 @@ def _copy_visualizer_assets(self) -> None:
                 print(f"[OK] Copied {font_count} font files")
 
         if total_files_copied > 0:
-            print(f"🎨 Successfully copied {total_files_copied} visualizer assets to {target_base_dir}")
+            print(f"[OK] Successfully copied {total_files_copied} visualizer assets to {target_base_dir}")
         else:
-            print(f"⚠️  No visualizer assets found to copy")
+            print(f"[WARN] No visualizer assets found to copy")
 
     def _clean_duplicate_symbols(self, main_lib_path: Path, build_lib_dir: Path) -> Dict[str, Any]:
         """
@@ -1399,18 +1399,19 @@ def _patch_zlib_cmake_for_windows(self) -> None:
 
 def get_default_plugins() -> List[str]:
     """
-    Get the default set of plugins (only the 3 currently integrated plugins).
+    Get the default set of plugins (only the currently integrated plugins).
     
-    Currently only 3 plugins are integrated into PyHelios:
+    Currently integrated plugins in PyHelios:
     - visualizer: OpenGL-based 3D visualization
     - weberpenntree: Procedural tree generation
     - radiation: OptiX-accelerated ray tracing (GPU optional)
+    - energybalance: GPU-accelerated thermal modeling and energy balance
     
     Returns:
         List of default plugins
     """
-    # Only return the 3 plugins that are actually integrated into PyHelios
-    integrated_plugins = ["visualizer", "weberpenntree", "radiation"]
+    # Return the plugins that are actually integrated into PyHelios
+    integrated_plugins = ["visualizer", "weberpenntree", "radiation", "energybalance"]
 
     # Filter by platform compatibility
     default_plugins = []
@@ -1449,24 +1450,40 @@ def parse_plugin_selection(args) -> List[str]:
     # 2. Apply exclusion flags
     if args.nogpu:
         # Remove GPU-dependent plugins
+        gpu_plugins = [p for p in selected_plugins 
+                      if PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).gpu_required]
         selected_plugins = [p for p in selected_plugins 
                           if not PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).gpu_required]
+        if gpu_plugins:
+            print(f"[EXCLUDED] GPU-dependent plugins excluded (--nogpu): {gpu_plugins}")
 
     if args.novis:
         # Remove visualization plugins
+        vis_plugins = [p for p in selected_plugins 
+                      if any(dep in ["opengl", "glfw", "imgui"] 
+                           for dep in PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).system_dependencies)]
         selected_plugins = [p for p in selected_plugins 
                           if not any(dep in ["opengl", "glfw", "imgui"] 
                                    for dep in PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).system_dependencies)]
+        if vis_plugins:
+            print(f"[EXCLUDED] Visualization plugins excluded (--novis): {vis_plugins}")
 
     # 3. Apply additional exclusions
     if args.exclude:
+        excluded_plugins = [p for p in selected_plugins if p in args.exclude]
         selected_plugins = [p for p in selected_plugins if p not in args.exclude]
+        if excluded_plugins:
+            print(f"[EXCLUDED] Explicitly excluded plugins (--exclude): {excluded_plugins}")
 
 
     # 4. Check environment variables for additional exclusions
     if os.environ.get('PYHELIOS_EXCLUDE_GPU', '').lower() in ['1', 'true', 'yes']:
+        env_gpu_plugins = [p for p in selected_plugins 
+                          if PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).gpu_required]
         selected_plugins = [p for p in selected_plugins 
                           if not PLUGIN_METADATA.get(p, PluginMetadata("", "", [], [], [], False, True, [], [])).gpu_required]
+        if env_gpu_plugins:
+            print(f"[EXCLUDED] GPU-dependent plugins excluded (PYHELIOS_EXCLUDE_GPU): {env_gpu_plugins}")
 
     # 5. Return final plugin list
     return selected_plugins
@@ -1657,7 +1674,7 @@ def main():
             print(f"[ERROR] Invalid plugins: {validation['invalid_plugins']}")
         print(f"Platform compatible: {validation['platform_compatible']}")
         if validation['platform_incompatible']:
-            print(f"⚠️  Platform incompatible: {validation['platform_incompatible']}")
+            print(f"[WARN] Platform incompatible: {validation['platform_incompatible']}")
 
         if validation['system_dependencies']:
             print("\nSystem Dependencies:")
@@ -1733,7 +1750,7 @@ def main():
             # PyHelios automatically discovers libraries in the build directory
 
         except Exception as e:
-            print(f"⚠️  Warning: Could not load built library: {e}")
+            print(f"[WARN] Could not load built library: {e}")
             if platform.system() != 'Windows':
                 print("   Try setting LD_LIBRARY_PATH and running again:")
                 print(f"   export LD_LIBRARY_PATH=\"{args.output_dir}:$LD_LIBRARY_PATH\"")

docs/CHANGELOG.md

@@ -1,16 +1,27 @@
 # Changelog
 
+# [v0.0.4] 2025-08-25
+
+🚨++ New Plug-in Integrated ++ 🚨
+- Energy Balance plug-in integrated with PyHelios
+
+- Updated Helios native C++ library to v1.3.46
+
+## Visualizer
+- Added `Visualizer.colorContextPrimitivesByData()`
+- Fixed a number of issues where visualizer methods were using lists instead of Helios data types (e.g., vec2, vec3, etc.)
+
 # [v0.0.3] 2025-08-23
 
 ## Context
-- Added comprehensive file loading support with `loadPLY()`, `loadOBJ()`, and `loadXML()` methods
-- Enhanced `loadPLY()` with 5 overloads supporting origin, height, rotation, color, and upaxis transformations
-- Enhanced `loadOBJ()` with 4 overloads including scale transformations and upaxis specification
-- Added complete `loadXML()` implementation for Helios XML geometry files
+- Added comprehensive file loading support with `Context.loadPLY()`, `Context.loadOBJ()`, and `Context.loadXML()` methods
+- Enhanced `Context.loadPLY()` with 5 overloads supporting origin, height, rotation, color, and upaxis transformations
+- Enhanced `Context.loadOBJ()` with 4 overloads including scale transformations and upaxis specification
+- Added complete `Context.loadXML()` implementation for Helios XML geometry files
 - Extended native C++ wrapper with 9 new file loading functions and proper error handling
 - Added comprehensive parameter validation and security path checking
-- Implemented `addTriangleTextured()`
-- Implemented `addTrianglesFromArraysTextured()`
+- Implemented `Context.addTriangleTextured()`
+- Implemented `Context.addTrianglesFromArraysTextured()`
 
 ## Examples
 - Added example geometry files: `suzanne.ply`, `suzanne.obj`, `suzanne.mtl`, and `leaf_cube.xml`