Skip to content

feat: Migrate Nerlplanner from PySimpleGUI to PySide6 #422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat: Migrate Nerlplanner from PySimpleGUI to PySide6 #422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
283 changes: 283 additions & 0 deletions src_py/nerlPlanner/README_PySide6_Migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,283 @@
# Nerlplanner PySide6 Migration

## Overview

The Nerlplanner application has been successfully migrated from PySimpleGUI to PySide6, providing a modern, enhanced user experience while preserving all original functionality. This migration includes auto-generation capabilities for C++ and Erlang headers, which are critical components of the Nerlnet distributed neural network system.

## Features

### ✅ Enhanced User Experience
- **Modern PySide6 Interface**: Clean, professional GUI with improved visual design
- **Tabbed Interface**: Organized workflow with dedicated tabs for different configuration aspects
- **Enhanced Input Validation**: Real-time validation with visual feedback
- **Improved Error Handling**: Better error messages and user guidance
- **Keyboard Shortcuts**: Full keyboard navigation support
- **Status Bar**: Real-time feedback for user actions

### ✅ Preserved Functionality
- **Auto-Generation**: Complete preservation of C++ and Erlang header generation
- **JSON Configuration**: Full compatibility with existing configuration files
- **Device Management**: Network scanning and device configuration
- **Worker Configuration**: Advanced worker parameter management
- **Client/Router/Source Management**: Complete network topology configuration
- **Communication Mapping**: Visual network topology representation
- **Experiment Flow**: Experiment configuration and management

### ✅ Enhanced Capabilities
- **Flexible Worker Configuration**: Comprehensive dialog with multiple parameter categories
- **Advanced Network Settings**: Security, encryption, and authentication options
- **Custom Parameters**: Extensible parameter system for advanced configurations
- **JSON Editor**: Built-in JSON editor with validation and formatting
- **Import/Export**: Enhanced file management with multiple format support

## Architecture

### File Structure
```
src_py/nerlPlanner/
├── main.py # Smart launcher (auto-detects GUI framework)
├── main_original.py # Backup of original PySimpleGUI version
├── main_pyside6.py # Direct PySide6 launcher
├── launcher.py # Advanced launcher with dependency management
├── requirements.txt # Updated dependencies (PySide6 6.6.0)
├── ui/
│ ├── __init__.py # UI package initialization
│ ├── main_window.py # Main application window (PySide6)
│ ├── dialogs.py # Specialized dialog windows
│ └── migration_utils.py # Migration utilities and helpers
└── [original modules] # All original functionality preserved
```

### Key Components

#### 1. Main Window (`ui/main_window.py`)
- **NerlplannerMainWindow**: Main application class
- **Tabbed Interface**: Settings, Devices, Workers, Clients, Network
- **Menu System**: File, Tools, View, Help menus with shortcuts
- **Toolbar**: Quick access buttons and status display
- **Modern Styling**: Professional CSS-based theming

#### 2. Dialog Windows (`ui/dialogs.py`)
- **WorkerDialog**: Comprehensive worker configuration with multiple tabs
- **CommunicationMapDialog**: Network topology visualization
- **ExperimentFlowDialog**: Experiment flow configuration

#### 3. Migration Utilities (`ui/migration_utils.py`)
- **Compatibility Functions**: Bridge between old and new systems
- **Validation Tools**: Configuration validation and error checking
- **Helper Classes**: Common PySide6 operations and utilities

## Installation & Usage

### Quick Start

1. **Install Dependencies**:
```bash
pip install PySide6 graphviz pydot
```

2. **Run Application**:
```bash
# Automatic detection (recommended)
python main.py

# Direct PySide6 launch
python main_pyside6.py

# Advanced launcher with options
python launcher.py --gui auto
```

### Advanced Usage

The launcher provides several options:

```bash
# Check available GUI frameworks
python launcher.py --check

# Install dependencies automatically
python launcher.py --install-deps

# Force specific GUI framework
python launcher.py --gui pyside6 # Modern interface
python launcher.py --gui legacy # PySimpleGUI fallback

# Auto-select best available
python launcher.py --gui auto # Default behavior
```

## Migration Details

### What Was Migrated

1. **UI Components**:
- All input fields, buttons, and lists converted to PySide6 equivalents
- Layout system redesigned with modern Qt layouts
- Enhanced styling with CSS-based themes

2. **Event Handling**:
- PySimpleGUI event loops converted to Qt signal/slot system
- Improved event management with type safety

3. **Data Management**:
- All data structures preserved and enhanced
- Improved validation and error handling
- Better state management

4. **Dialog Windows**:
- Worker configuration dialog completely redesigned
- Enhanced parameter management with tabbed interface
- Custom parameter support with table editing

### What Was Preserved

1. **Core Functionality**:
- All auto-generation capabilities intact
- JSON configuration system unchanged
- Network scanning and device management
- Complete compatibility with existing configuration files

2. **Integration Points**:
- All imports from original modules preserved
- Definitions.py, Handlers.py, JsonElements.py fully compatible
- CppHeadersExporter and ErlHeadersExporter functionality maintained

3. **Data Formats**:
- Configuration file formats unchanged
- Network protocols and communication unchanged
- Auto-generated header formats preserved

## Technical Implementation

### Auto-Generation System

The critical auto-generation functionality is preserved through careful integration:

```python
# C++ Header Generation
from CppHeadersExporter import gen_header_worker_parameters_definitions
gen_header_worker_parameters_definitions(file_path)

# Erlang Header Generation
from ErlHeadersExporter import gen_worker_fields_hrl
gen_worker_fields_hrl(file_path)
```

### Enhanced Worker Configuration

The new WorkerDialog provides comprehensive parameter management:

- **Basic Tab**: Model architecture, activation functions
- **Network Tab**: Connection settings, security options
- **Learning Tab**: Training parameters, regularization
- **Advanced Tab**: Custom parameters, raw JSON editing

### Modern UI Patterns

- **Signal/Slot Architecture**: Type-safe event handling
- **Model-View Pattern**: Separation of data and presentation
- **CSS Styling**: Professional appearance with consistent theming
- **Input Validation**: Real-time feedback with visual indicators

## Compatibility

### Backward Compatibility
- All existing configuration files work without modification
- Original PySimpleGUI version remains available as fallback
- Auto-detection ensures smooth transition

### Forward Compatibility
- Modern Qt framework ensures long-term support
- Extensible architecture for future enhancements
- Standards-compliant code for easy maintenance

## Development

### Adding New Features

1. **New Dialog Windows**:
```python
from ui.dialogs import BaseDialog

class CustomDialog(BaseDialog):
def __init__(self, parent=None):
super().__init__(parent)
self.init_ui()
```

2. **New Configuration Tabs**:
```python
def create_custom_tab(self):
# Create tab widget and layout
# Add to main tab widget
```

3. **Enhanced Validation**:
```python
from ui.migration_utils import PySide6Helper

PySide6Helper.apply_validation_style(widget, is_valid)
```

### Testing

- **Framework Detection**: Test auto-detection with different installed packages
- **Configuration Compatibility**: Verify existing files load correctly
- **Auto-Generation**: Ensure C++ and Erlang header generation works
- **UI Functionality**: Test all tabs, dialogs, and user interactions

## Migration Benefits

1. **Enhanced User Experience**:
- Professional, modern interface
- Better organization and navigation
- Improved visual feedback and error handling

2. **Technical Improvements**:
- Type-safe signal/slot system
- Better memory management
- More robust error handling

3. **Long-term Sustainability**:
- Active framework with long-term support
- Better documentation and community
- Easier maintenance and extension

4. **Preserved Investment**:
- All existing functionality maintained
- Configuration files remain compatible
- Auto-generation system fully preserved

## Support

### Troubleshooting

1. **PySide6 Not Available**:
```bash
pip install PySide6
# or use launcher auto-install
python launcher.py --install-deps
```

2. **Legacy Fallback**:
```bash
pip install PySimpleGUI
python launcher.py --gui legacy
```

3. **Configuration Issues**:
- Use built-in JSON validator in Advanced tab
- Check error messages in status bar
- Verify file permissions and paths

### Getting Help

- Check status bar messages for real-time feedback
- Use Help → About for version information
- Review console output for detailed error messages
- Original functionality documented in existing Nerlnet documentation

## Conclusion

This migration successfully modernizes the Nerlplanner interface while preserving all critical functionality. The auto-generation system for C++ and Erlang headers remains fully functional, and the enhanced user experience makes the application more accessible and professional. The smart launcher ensures compatibility across different environments and provides a smooth transition path for existing users.
Loading