ga-knapsack-toolkit 3.0.0

Educational genetic algorithm library for knapsack optimization problems.

Genetic Algorithms for Knapsack

Educational genetic algorithm toolkit with a FastAPI service for running knapsack optimization experiments.

This project provides a core GA library (ga_core) and a FastAPI service for running and tracking experiments on knapsack benchmarks.

Project Structure

This repository contains:

• src/ga_core/ – Core genetic algorithm library (publishable to PyPI)
• src/api/ – FastAPI web service for running GA experiments
• dane AG 2/ – Benchmark knapsack problem instances
• tests/ – Test suite

---

Installation

Library Only (for use in your code)

pip install ga-knapsack-toolkit

Full Development Setup

git clone https://github.com/maleckainez/GeneticAlgorithms.git
cd GeneticAlgorithms
python -m venv .venv
# Linux:
source .venv/bin/activate  
# Windows: 
.venv\Scripts\activate
# MacOS:
. .venv/bin/activate
pip install -e ".[dev,api]"

Install options:

• Base: pip install . – Core library only
• .[api] – Include FastAPI dependencies
• .[dev] – Include testing & linting tools
• .[dev,api] - Install all dependencies and tools

---

Library Usage (ga_core)

Quick Start

from pathlib import Path
from src.ga_core import ExperimentConfig, InputConfig, ExperimentStorage
from src.ga_core.engine import EvolutionEngine
from src.ga_core.io import load_yaml_config, load_experiment_data

# Load configuration
config_path = Path("config.yaml")
input_config = load_yaml_config(config_path)

# Load knapsack data
data_path = Path("dane AG 2/low-dimensional/f1_l-d_kp_10_269")
items_data = load_experiment_data(data_path)

# Create experiment config
config = ExperimentConfig(
    input=input_config,
    job_id="experiment-001",
    root_path=Path.cwd()
)

# Setup storage
from src.ga_core.storage import SimpleStorageLayout
layout = SimpleStorageLayout(root=config.root_path)
storage = ExperimentStorage(layout=layout, job_id=config.job_id)

# Run evolution
engine = EvolutionEngine(config=config, storage=storage, items_data=items_data)
engine.run()

Configuration (config.yaml)

data:
  data_filename: "f1_l-d_kp_10_269"
  max_weight: 269

population:
  size: 100
  generations: 500
  stream_batch_size: 50
  commit_mode: "swap"  # or "copy"

selection:
  type: "roulette"  # roulette, tournament, linear_rank
  selection_pressure: null  # for rank selection: 1.0-2.0
  tournament_size: null     # for tournament: int

genetic_operators:
  crossover_type: "two_point"  # one_point, two_point
  crossover_probability: 0.75
  mutation_probability: 0.01
  penalty_multiplier: 1.0
  strict_weight_constraints: false

experiment:
  seed: 42
  identifier: "exp-001"
  log_level: "INFO"

---

Web API

Running the API

# Development mode
fastapi dev src/api/main.py --reload --reload-dir src/

# Production mode
fastapi run src/api/main.py

API will be available at:

• http://localhost:8000

API Docs at:

• http://localhost:8000/docs

API Endpoints

Health Check

GET /health

Submit GA Job

POST /backend/run/ga
Content-Type: application/json

{
  "data": {"data_filename": "f1_l-d_kp_10_269", "max_weight": 269},
  "population": {"size": 100, "generations": 500, ...},
  ...
}

Response: {"job_id": "job-uuid", "status": "pending"}

Check Job Status

GET /backend/status/{job_id}

Response: {"job_id": "uuid", "status": "running"}

List Jobs by Status

GET /backend/jobs/finished

Response: {"status": "finished", "jobs": ["uuid1", "uuid2", ...]}

---

🧪 Development

Running Tests

pytest

Code Quality

# Format code
black .

# Lint
ruff check .

# Type check
mypy .

Test Coverage

coverage run -m pytest
coverage report

---

📊 Dataset: dane AG 2

The repository includes benchmark knapsack problem instances:

dane AG 2/
├── large_scale/               # Large instances (knapPI_*)
├── large_scale-optimum/       # Known optimal values
├── low-dimensional/           # Smaller instances (f*)
└── low-dimensional-optimum/   # Known optimal values

File format: Each line contains value weight

---

Author: Inez Małecka – [e-mail]