Fix #104: Improve initial population diversity in IsoFuel algorithm

INSTALLATION.md

@@ -0,0 +1,179 @@
+# Installation Guide
+
+## Dependency Management
+
+WeatherRoutingTool uses optional dependency groups to provide a flexible installation experience. This allows users to install only the dependencies they need, reducing installation time and potential conflicts.
+
+## Installation Options
+
+### 1. Minimal Installation (Recommended for beginners)
+```bash
+pip install WeatherRoutingTool
+```
+
+**What you get:**
+- Core weather routing functionality
+- Basic data processing capabilities
+- Configuration management
+- Essential scientific computing tools
+
+**Use case:** Learning weather routing, basic route optimization, or when you don't need visualization.
+
+### 2. With Visualization
+```bash
+pip install WeatherRoutingTool[viz]
+```
+
+**What you get:**
+- Everything from minimal installation
+- Route visualization and plotting
+- Map generation
+- Statistical plots
+
+**Use case:** When you need to visualize routes, weather conditions, or optimization results.
+
+### 3. With Geospatial Features
+```bash
+pip install WeatherRoutingTool[geospatial]
+```
+
+**What you get:**
+- Everything from minimal installation
+- Advanced geographic calculations
+- Land mask support
+- Geospatial data analysis
+
+**Use case:** When working with complex geographic constraints or advanced route planning.
+
+### 4. With Genetic Algorithm
+```bash
+pip install WeatherRoutingTool[genetic]
+```
+
+**What you get:**
+- Everything from minimal installation
+- Genetic algorithm optimization
+- Multi-objective optimization capabilities
+
+**Use case:** When you need advanced optimization algorithms beyond basic routing.
+
+### 5. With Data Processing
+```bash
+pip install WeatherRoutingTool[data]
+```
+
+**What you get:**
+- Everything from minimal installation
+- Large dataset processing
+- Parallel computing capabilities
+- Advanced data access
+
+**Use case:** When working with large weather datasets or need performance optimization.
+
+### 6. With External Data Download
+```bash
+pip install WeatherRoutingTool[download]
+```
+
+**What you get:**
+- Everything from minimal installation
+- Automatic weather data downloading
+- Access to external data sources
+
+**Use case:** When you need to fetch weather data from external sources automatically.
+
+### 7. Full Installation
+```bash
+pip install WeatherRoutingTool[all]
+```
+
+**What you get:** All features and dependencies.
+
+**Use case:** When you need all features or are unsure which groups you need.
+
+### 8. Development Installation
+```bash
+pip install WeatherRoutingTool[dev]
+```
+
+**What you get:**
+- All features
+- Development tools (flake8, pytest)
+- Testing framework
+
+**Use case:** For contributors and developers working on the codebase.
+
+## Combining Groups
+
+You can combine multiple groups:
+```bash
+pip install WeatherRoutingTool[viz,genetic]
+```
+
+## Upgrading Installations
+
+To add features to an existing installation:
+```bash
+pip install WeatherRoutingTool[viz]  # Adds visualization to existing installation
+```
+
+## Troubleshooting
+
+### Installation Issues
+
+1. **Cartopy installation fails on Windows:**
+   ```bash
+   pip install WeatherRoutingTool[viz] --no-binary cartopy
+   ```
+
+2. **Memory errors during installation:**
+   Use minimal installation and add groups as needed:
+   ```bash
+   pip install WeatherRoutingTool
+   pip install WeatherRoutingTool[viz]
+   ```
+
+3. **Conflicts with existing packages:**
+   Use a virtual environment:
+   ```bash
+   python -m venv wrt_env
+   source wrt_env/bin/activate  # On Windows: wrt_env\Scripts\activate
+   pip install WeatherRoutingTool[all]
+   ```
+
+### Dependency Conflicts
+
+If you encounter dependency conflicts, try:
+1. Using a fresh virtual environment
+2. Installing groups individually to identify the conflicting package
+3. Using `pip install --upgrade` to update conflicting packages
+
+## Performance Considerations
+
+- **Minimal installation** has the fastest installation time and smallest footprint
+- **Full installation** provides all features but takes longer to install
+- **Selective installation** reduces the chance of dependency conflicts
+- **Virtual environments** are recommended for all installations
+
+## Feature Requirements
+
+| Feature | Required Dependency Group |
+|---------|---------------------------|
+| Basic routing | core (included in all installations) |
+| Route plotting | viz |
+| Map generation | viz |
+| Genetic algorithm | genetic |
+| Land constraints | geospatial |
+| Large datasets | data |
+| Auto-download weather | download |
+| Image processing | image |
+
+## Migration from Previous Versions
+
+If you're upgrading from a version before dependency groups:
+1. Your existing installation will continue to work
+2. To use the new modular approach, create a fresh installation:
+   ```bash
+   pip uninstall WeatherRoutingTool
+   pip install WeatherRoutingTool[all]  # Or your preferred groups
+   ```

README.md

@@ -2,6 +2,69 @@
 
 A tool to perform optimization of ship routes based on fuel consumption in different weather conditions.
 
+## Installation
+
+### Minimal Installation (Core Features)
+For basic weather routing functionality without visualization or advanced features:
+
+```bash
+pip install WeatherRoutingTool
+```
+
+### Installation with Optional Features
+
+#### With Visualization Support
+For plotting and visualization capabilities:
+```bash
+pip install WeatherRoutingTool[viz]
+```
+
+#### With Geospatial Features
+For advanced geospatial analysis:
+```bash
+pip install WeatherRoutingTool[geospatial]
+```
+
+#### With Genetic Algorithm
+For optimization using genetic algorithms:
+```bash
+pip install WeatherRoutingTool[genetic]
+```
+
+#### With Data Processing
+For large dataset processing:
+```bash
+pip install WeatherRoutingTool[data]
+```
+
+#### With External Data Download
+For downloading weather data:
+```bash
+pip install WeatherRoutingTool[download]
+```
+
+#### Full Installation
+For all features (equivalent to current installation):
+```bash
+pip install WeatherRoutingTool[all]
+```
+
+#### Development Installation
+For contributors and developers:
+```bash
+pip install WeatherRoutingTool[dev]
+```
+
+### Dependency Groups
+
+- **Core**: `numpy`, `pandas`, `xarray`, `scipy`, `pydantic`, `astropy` - Essential for basic functionality
+- **Visualization**: `matplotlib`, `seaborn`, `cartopy` - Plotting and mapping
+- **Geospatial**: `geopandas`, `shapely`, `geographiclib`, `geovectorslib`, `global_land_mask` - Advanced geographic features
+- **Data Processing**: `dask`, `datacube`, `netcdf4` - Large dataset handling
+- **Download**: `maridatadownloader` - External weather data downloading
+- **Genetic**: `pymoo` - Genetic algorithm optimization
+- **Image**: `scikit-image`, `Pillow` - Image processing
+
 Documentation: https://52north.github.io/WeatherRoutingTool/
 
 Introduction: [WRT-sandbox](https://github.com/52North/WRT-sandbox) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/52North/WRT-sandbox.git/HEAD?urlpath=%2Fdoc%2Ftree%2FNotebooks/execute-WRT.ipynb)

WeatherRoutingTool/algorithms/genetic/population.py

@@ -270,11 +270,55 @@ def generate(self, problem, n_samples, **kw):
 
             X[i, 0] = rt
 
-        # fallback: fill all other individuals with the same population as the last one
+        # fallback: fill remaining individuals with perturbed copies to maintain diversity
         for j in range(i + 1, n_samples):
-            X[j, 0] = np.copy(X[j - 1, 0])
+            X[j, 0] = self._perturb_route(np.copy(X[j - 1, 0]), j - i)
         return X
 
+    def _perturb_route(self, route: np.ndarray, perturbation_factor: int) -> np.ndarray:
+        """Apply controlled perturbation to a route to maintain population diversity.
+
+        Creates small random variations in intermediate waypoints while preserving
+        start and destination points. Perturbation magnitude increases with perturbation_factor
+        to ensure diversity across multiple copied routes.
+
+        :param route: Original route to perturb as array of [lat, lon, speed] waypoints
+        :type route: np.ndarray
+        :param perturbation_factor: Factor to control perturbation magnitude (higher = more variation)
+        :type perturbation_factor: int
+        :return: Perturbed route with same structure as input
+        :rtype: np.ndarray
+        """
+        if len(route) <= 2:
+            # Route has only start and end points, cannot perturb
+            return route
+
+        # Create perturbed copy
+        perturbed_route = np.copy(route)
+
+        # Calculate perturbation magnitude (0.1 to 1.0 degrees based on factor)
+        # Cap at reasonable maximum to maintain route coherence
+        max_perturbation = min(0.1 + (perturbation_factor * 0.1), 1.0)
+
+        # Perturb intermediate waypoints (exclude start [0] and end [-1])
+        for i in range(1, len(route) - 1):
+            # Apply random perturbation to latitude and longitude
+            lat_perturbation = np.random.uniform(-max_perturbation, max_perturbation)
+            lon_perturbation = np.random.uniform(-max_perturbation, max_perturbation)
+
+            # Apply perturbations
+            perturbed_route[i, 0] += lat_perturbation  # latitude
+            perturbed_route[i, 1] += lon_perturbation  # longitude
+
+            # Ensure coordinates remain within valid ranges
+            perturbed_route[i, 0] = np.clip(perturbed_route[i, 0], -90, 90)    # latitude bounds
+            perturbed_route[i, 1] = np.clip(perturbed_route[i, 1], -180, 180)  # longitude bounds
+
+        # Log perturbation for debugging
+        logger.debug(f"Applied perturbation factor {perturbation_factor} with max magnitude {max_perturbation:.3f} degrees")
+
+        return perturbed_route
+
 
 class GcrSliderPopulation(Population):
 
@@ -345,11 +389,55 @@ def generate(self, problem, n_samples, **kw):
                 rt = self.recalculate_speed_for_route(rt)
             X[i, 0] = rt
 
-        # fallback: fill all other individuals with the same population as the last one
+        # fallback: fill remaining individuals with perturbed copies to maintain diversity
         for j in range(i + 1, n_samples):
-            X[j, 0] = np.copy(X[j - 1, 0])
+            X[j, 0] = self._perturb_route(np.copy(X[j - 1, 0]), j - i)
         return X
 
+    def _perturb_route(self, route: np.ndarray, perturbation_factor: int) -> np.ndarray:
+        """Apply controlled perturbation to a route to maintain population diversity.
+
+        Creates small random variations in intermediate waypoints while preserving
+        start and destination points. Perturbation magnitude increases with perturbation_factor
+        to ensure diversity across multiple copied routes.
+
+        :param route: Original route to perturb as array of [lat, lon, speed] waypoints
+        :type route: np.ndarray
+        :param perturbation_factor: Factor to control perturbation magnitude (higher = more variation)
+        :type perturbation_factor: int
+        :return: Perturbed route with same structure as input
+        :rtype: np.ndarray
+        """
+        if len(route) <= 2:
+            # Route has only start and end points, cannot perturb
+            return route
+
+        # Create perturbed copy
+        perturbed_route = np.copy(route)
+
+        # Calculate perturbation magnitude (0.1 to 1.0 degrees based on factor)
+        # Cap at reasonable maximum to maintain route coherence
+        max_perturbation = min(0.1 + (perturbation_factor * 0.1), 1.0)
+
+        # Perturb intermediate waypoints (exclude start [0] and end [-1])
+        for i in range(1, len(route) - 1):
+            # Apply random perturbation to latitude and longitude
+            lat_perturbation = np.random.uniform(-max_perturbation, max_perturbation)
+            lon_perturbation = np.random.uniform(-max_perturbation, max_perturbation)
+
+            # Apply perturbations
+            perturbed_route[i, 0] += lat_perturbation  # latitude
+            perturbed_route[i, 1] += lon_perturbation  # longitude
+
+            # Ensure coordinates remain within valid ranges
+            perturbed_route[i, 0] = np.clip(perturbed_route[i, 0], -90, 90)    # latitude bounds
+            perturbed_route[i, 1] = np.clip(perturbed_route[i, 1], -180, 180)  # longitude bounds
+
+        # Log perturbation for debugging
+        logger.debug(f"Applied perturbation factor {perturbation_factor} with max magnitude {max_perturbation:.3f} degrees")
+
+        return perturbed_route
+
     def create_route(self, lat: float = None, lon: float = None, speed: float = None):
         """
         :param lat: latitude of the waypoint