diff --git a/INSTALLATION.md b/INSTALLATION.md new file mode 100644 index 0000000..2931b4d --- /dev/null +++ b/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 + ``` diff --git a/README.md b/README.md index 72b7f47..006c4af 100644 --- a/README.md +++ b/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) diff --git a/pyproject.toml b/pyproject.toml index d676a3f..9a5cbe8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,8 +21,70 @@ classifiers = [ ] dynamic = ["dependencies"] +[project.optional-dependencies] +# Core dependencies for basic weather routing functionality +core = [ + "numpy", + "pandas", + "xarray", + "scipy>=1.10.0", + "pydantic", + "astropy" +] + +# Visualization and plotting capabilities +viz = [ + "matplotlib", + "seaborn", + "cartopy>0.20.0" +] + +# Advanced geospatial features +geospatial = [ + "geopandas", + "shapely", + "geographiclib", + "geovectorslib", + "global_land_mask" +] + +# Large dataset processing and data access +data = [ + "dask", + "datacube", + "netcdf4" +] + +# External data downloading capabilities +download = [ + "maridatadownloader@git+https://github.com/52North/maridatadownloader" +] + +# Genetic algorithm optimization +genetic = [ + "pymoo>=0.6.1" +] + +# Image processing features +image = [ + "scikit-image", + "Pillow" +] + +# All optional dependencies (full installation) +all = [ + "WeatherRoutingTool[core,viz,geospatial,data,download,genetic,image]" +] + +# Development dependencies +dev = [ + "WeatherRoutingTool[all]", + "flake8", + "pytest" +] + [tool.setuptools.dynamic] -dependencies = { file = ["requirements.txt"] } +dependencies = { file = ["requirements.core.txt"] } [tool.setuptools.packages.find] include = ["WeatherRoutingTool*"] diff --git a/requirements.core.txt b/requirements.core.txt new file mode 100644 index 0000000..0415220 --- /dev/null +++ b/requirements.core.txt @@ -0,0 +1,9 @@ +# Core dependencies for minimal WeatherRoutingTool installation +# These are essential for basic weather routing functionality + +numpy +pandas +xarray +scipy>=1.10.0 +pydantic +astropy diff --git a/test_minimal_install.py b/test_minimal_install.py new file mode 100644 index 0000000..09ec8bf --- /dev/null +++ b/test_minimal_install.py @@ -0,0 +1,119 @@ +#!/usr/bin/env python3 +""" +Test script to verify minimal installation works correctly. +This script tests core functionality without optional dependencies. +""" + +import sys +import traceback + +def test_core_imports(): + """Test that core modules can be imported with minimal installation.""" + print("Testing core imports...") + + try: + # Core dependencies + import numpy as np + import pandas as pd + import xarray as xr + from scipy import interpolate + import astropy.units as u + from pydantic import BaseModel + print("✓ Core dependencies imported successfully") + except ImportError as e: + print(f"✗ Core dependency import failed: {e}") + return False + + try: + # WRT core modules + import WeatherRoutingTool.config as config + import WeatherRoutingTool.routeparams as routeparams + import WeatherRoutingTool.weather as weather + print("✓ WRT core modules imported successfully") + except ImportError as e: + print(f"✗ WRT core module import failed: {e}") + traceback.print_exc() + return False + + return True + +def test_basic_functionality(): + """Test basic WRT functionality.""" + print("\nTesting basic functionality...") + + try: + from WeatherRoutingTool.config import Config + from WeatherRoutingTool.weather import WeatherCond + from datetime import datetime, timedelta + + # Test basic configuration + print("✓ Config class accessible") + + # Test weather condition creation + weather_cond = WeatherCond( + time=datetime.now(), + hours=24, + time_res=3 + ) + print("✓ WeatherCond creation successful") + + return True + except Exception as e: + print(f"✗ Basic functionality test failed: {e}") + traceback.print_exc() + return False + +def test_optional_imports_fail(): + """Test that optional dependencies are not available in minimal install.""" + print("\nTesting that optional dependencies are not available...") + + optional_deps = [ + ('matplotlib', 'matplotlib.pyplot'), + ('cartopy', 'cartopy.crs'), + ('geopandas', 'geopandas'), + ('pymoo', 'pymoo'), + ('dask', 'dask'), + ('netcdf4', 'netCDF4'), + ] + + for dep_name, import_path in optional_deps: + try: + __import__(import_path) + print(f"⚠ Optional dependency {dep_name} is available (unexpected)") + except ImportError: + print(f"✓ Optional dependency {dep_name} not available (expected)") + + return True + +def main(): + """Run all tests.""" + print("WeatherRoutingTool Minimal Installation Test") + print("=" * 50) + + tests = [ + test_core_imports, + test_basic_functionality, + test_optional_imports_fail, + ] + + results = [] + for test in tests: + try: + result = test() + results.append(result) + except Exception as e: + print(f"✗ Test {test.__name__} failed with exception: {e}") + results.append(False) + + print("\n" + "=" * 50) + print(f"Results: {sum(results)}/{len(results)} tests passed") + + if all(results): + print("🎉 All tests passed! Minimal installation works correctly.") + return 0 + else: + print("❌ Some tests failed. Check the output above.") + return 1 + +if __name__ == "__main__": + sys.exit(main())