docs: improve README with detailed architecture and usage

Author: MichalRedm

README.md

@@ -1,18 +1,123 @@
-# Portfolio Optimization
+# Portfolio Optimization with Spectral Mixture Gaussian Processes
 
 [![Python CI](https://github.com/MichalRedm/portfolio-optimization/actions/workflows/ci.yml/badge.svg)](https://github.com/MichalRedm/portfolio-optimization/actions/workflows/ci.yml)
 
-Modular Python implementation for Markowitz Portfolio Optimization using Spectral Mixture Gaussian Processes.
+A professional-grade Python implementation of Multi-Objective Portfolio Optimization. This project combines advanced time-series forecasting (Spectral Mixture Gaussian Processes) with state-of-the-art evolutionary algorithms (MOEA/D) to find optimal asset allocations.
 
-## Features
-- Modular architecture (SOLID principles)
-- Exact Gaussian Process regression (Spectral Mixture Kernel)
-- Pareto Front optimization (Weighted Sum & Epsilon-Constrained)
-- Matplotlib visualizations
+---
 
-## Setup
-1. Create virtual environment: `python -m venv .venv`
-2. Activate environment
-3. Install dependencies: `pip install -r requirements.txt`
-4. Run standard experiment: `python -m scripts.experiment_standard`
-5. Run MOEA/D experiment: `python -m scripts.experiment_moead`
+## 🚀 Overview
+
+This repository provides a modular framework for:
+1.  **Price Prediction**: Using Gaussian Processes with Spectral Mixture (SM) kernels to capture complex periodicity and trends in financial data.
+2.  **Portfolio Modeling**: Defining multi-objective problems including Expected Return, Risk (Variance), and Diversification (HHI Index).
+3.  **Pareto Front Discovery**: Solving the optimization problem using classical (Weighted Sum, Epsilon-Constrained) and evolutionary (MOEA/D) approaches.
+
+---
+
+## 🛠️ Key Algorithms
+
+### 1. Classical Optimizers
+*   **Weighted Sum**: Aggregates objectives into a single scalar value.
+*   **Epsilon-Constrained (ECM)**: Maximizes return while keeping other objectives within strict bounds. Used as the ground-truth reference for quality metrics.
+
+### 2. MOEA/D (Decomposition-based Optimization)
+*   **Standard MOEA/D**: Decomposes the problem into subproblems with fixed weight vectors.
+*   **MOEA/D-DRA (Dynamic Resource Allocation)**: Optimizes computational efficiency by focusing on subproblems that show the most improvement.
+*   **MOEA/D-AWA (Adaptive Weight Adjustment)**: Dynamically repositions weight vectors during search to ensure a uniform distribution of solutions across the Pareto front.
+
+---
+
+## 📦 Project Structure
+
+```text
+├── .github/workflows/  # CI/CD Pipeline (Linting & Formatting)
+├── data/               # Historical asset price data (CSV)
+├── scripts/            # Experiment entry points
+│   ├── experiment_standard.py  # Classical optimization comparison
+│   ├── experiment_moead.py     # Basic MOEA/D vs ECM
+│   ├── experiment_dra.py       # Performance & efficiency testing
+│   └── experiment_awa.py       # Diversity & distribution testing
+├── src/
+│   ├── portfolio/      # Core optimization logic
+│   │   ├── metrics.py  # Quality metrics (IGD, Spacing, Spread)
+│   │   ├── moead_base.py # Common evolutionary logic
+│   │   └── ...
+│   ├── predictors.py   # GP-SM Regression models
+│   └── visualization.py # Advanced plotting and 3D animations
+└── requirements.txt    # Dependency list
+```
+
+---
+
+## ⚙️ Setup & Installation
+
+1.  **Clone the repository**:
+    ```bash
+    git clone https://github.com/MichalRedm/portfolio-optimization.git
+    cd portfolio-optimization
+    ```
+
+2.  **Create and activate a virtual environment**:
+    ```bash
+    python -m venv .venv
+    # Windows
+    .venv\Scripts\activate
+    # Linux/macOS
+    source .venv/bin/activate
+    ```
+
+3.  **Install dependencies**:
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+---
+
+## 📈 Running Experiments
+
+The project includes several built-in experiments to evaluate algorithm performance.
+
+### Standard Optimization (ECM vs Weighted Sum)
+```bash
+python scripts/experiment_standard.py
+```
+
+### MOEA/D vs Standard Comparison
+```bash
+python scripts/experiment_moead.py
+```
+
+### Efficiency & Resource Allocation (DRA)
+```bash
+python scripts/experiment_dra.py
+```
+
+### Distribution & Adaptive Weights (AWA)
+```bash
+python scripts/experiment_awa.py
+```
+
+---
+
+## 📊 Quality Metrics
+
+We evaluate the quality of the found Pareto fronts using:
+*   **IGD (Inverted Generational Distance)**: Measures how close the found solutions are to the true Pareto front.
+*   **Spacing**: Measures how evenly the solutions are distributed.
+*   **Spread**: Measures how well the solutions cover the entire objective space.
+
+---
+
+## 🎨 Visualizations
+
+The framework generates high-quality visualizations, including:
+*   **2D Comparisons**: Scatter plots showing the Pareto front against reference models.
+*   **3D Animations**: Interactive rotation of 3D fronts (Return vs Risk vs Diversification) saved as smooth GIFs (25 FPS).
+*   **Efficiency Plots**: Performance over time (IGD vs. Function Evaluations).
+
+---
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.