Vogel's Approximation Method - Web Application

A modern web-based implementation of Vogel's Approximation Method for solving Balanced Transportation Problems.

Features

• Modern Web UI: Clean, responsive interface using Tailwind CSS
• Dynamic Matrix Sizing: Support for 2x2 up to 5x5 transportation problems
• Real-time Validation: Input validation with helpful error messages
• Export Functionality: Export results as JSON
• Docker Support: Easy containerization and deployment
• Comprehensive Testing: Unit tests for algorithm validation
• RESTful API: Clean API endpoints for integration

Quick Start with Docker

Prerequisites

• Docker and Docker Compose installed

Running the Application

1. Clone and navigate to the project:

   git clone <repository-url>
   cd Logistic-Optimization-DSS

2. Build and run with Docker Compose:

   docker-compose up --build

3. Access the application:

   • Open your browser and go to http://localhost:5000
   • Or with nginx (if configured): http://localhost:80

4. Stop the application:

   docker-compose down

Docker Commands

Build only:

docker build -t vogel-app .

Run standalone container:

docker run -p 5000:5000 vogel-app

View logs:

docker-compose logs -f

Manual Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Installation Steps

1. Clone the repository:

   git clone <repository-url>
   cd Logistic-Optimization-DSS

2. Create virtual environment (recommended):

   # On Windows
   python -m venv venv
   venv\Scripts\activate
   
   # On macOS/Linux
   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Run the application:

   python app.py

5. Access the application:

   • Open your browser and go to http://localhost:5000

Development Mode

For development with auto-reload:

# Set environment variable
export FLASK_ENV=development  # On macOS/Linux
set FLASK_ENV=development     # On Windows

# Run with debug mode
python app.py

Running Tests

Run All Tests

# From project root
python tests/run_tests.py

# Or using unittest
python -m unittest tests.test_vogels_algorithm

Run Specific Test

python -m unittest tests.test_vogels_algorithm.TestVogelsApproximation.test_simple_balanced_problem

Test Coverage (optional)

pip install coverage
coverage run -m unittest tests.test_vogels_algorithm
coverage report
coverage html  # Opens detailed HTML report

API Documentation

Endpoints

GET /

Returns the main web interface.

GET /health

Health check endpoint.

{
  "status": "healthy"
}

POST /solve

Solve a transportation problem.

Request Body:

{
  "cost_matrix": [[3, 1, 2], [2, 4, 1], [5, 3, 2]],
  "supply": [10, 15, 20],
  "demand": [12, 18, 15]
}

Successful Response:

{
  "success": true,
  "allocation": [[0, 10, 0], [12, 0, 3], [0, 8, 12]],
  "total_cost": 89.0,
  "iterations": 5
}

Error Response:

{
  "success": false,
  "error": "Unbalanced problem: Supply sum (45) != Demand sum (45)"
}

Usage Guide

Using the Web Interface

1. Select Matrix Size: Choose the number of sources and destinations (2x2 to 5x5)
2. Enter Cost Matrix: Input transportation costs between each source and destination
3. Enter Supply and Demand: Input available supply at each source and required demand at each destination
4. Validate: The system automatically checks for balanced problems (total supply = total demand)
5. Solve: Click "Solve Problem" to compute the optimal allocation
6. View Results: See the allocation matrix and total transportation cost
7. Export: Download results as JSON for further analysis

Example Problem

Cost Matrix:

      Dest1  Dest2  Dest3
Src1   3      1      2
Src2   2      4      1
Src3   5      3      2

Supply: [10, 15, 20] Demand: [12, 18, 15]

Expected Output: Optimal allocation with minimum total cost

Project Structure

Logistic-Optimization-DSS/
├── app.py                    # Flask web application
├── vogels_algorithm.py       # Core algorithm implementation
├── requirements.txt          # Python dependencies
├── Dockerfile               # Docker container configuration
├── docker-compose.yml       # Docker Compose configuration
├── templates/
│   └── index.html          # Web interface template
├── tests/
│   ├── test_vogels_algorithm.py  # Unit tests
│   └── run_tests.py             # Test runner
└── README.md               # This file

Troubleshooting

Common Issues

1. Port already in use:

   # Find process using port 5000
   netstat -tulpn | grep :5000   # Linux
   netstat -ano | findstr :5000  # Windows
   
   # Kill the process or change port
   export PORT=5001  # Then run app.py

2. Docker build fails:

   # Clear Docker cache
   docker system prune -a
   
   # Rebuild without cache
   docker-compose build --no-cache

3. Module not found error:

   # Ensure you're in the correct directory
   cd Logistic-Optimization-DSS
   
   # Install dependencies
   pip install -r requirements.txt

4. Permission denied (Linux/macOS):

   # Fix file permissions
   chmod +x tests/run_tests.py

Performance Tips

• For large matrices (5x5), the algorithm completes in milliseconds
• Docker deployment provides consistent performance across environments
• Use Gunicorn for production deployments (included in Dockerfile)

Getting Help

1. Check the application logs for error messages
2. Run tests to verify algorithm correctness: python tests/run_tests.py
3. Verify Docker is running: docker --version
4. Check port availability: netstat -an | grep 5000

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run tests: python tests/run_tests.py
5. Submit a pull request

License

This project is licensed under the MIT License.

Contact

For questions or issues, please create an issue in the repository or contact the development team.