docs: Add comprehensive documentation to base_algorithm.py

[Copilot]

Overview

Addresses the documentation request for base_algorithm.py by adding comprehensive docstrings and inline comments to explain the purpose, functionality, and usage of the FlightAlgorithm abstract base class.

Problem

The FlightAlgorithm base class lacked documentation, making it difficult for developers to:

• Understand its role in the optimization algorithm architecture
• Know what parameters to pass when creating subclasses
• Understand the seeding strategies and their implications
• Implement the abstract methods correctly

Changes Made

1. Class-Level Documentation

Added a comprehensive docstring (2,843 characters) that explains:

• The purpose of FlightAlgorithm as the abstract base class for all optimization algorithms
• How it handles random seed management, domain boundaries, and fitness function evaluation
• The two seeding strategies (seed_init=True vs False) and their behavioral differences:
  • seed_init=True: Separate random generator for initialization only (allows exploration variation)
  • seed_init=False: Same seed for all operations (fully deterministic and reproducible)
• All class attributes with detailed descriptions and examples
• Complete usage example showing how to instantiate and run a concrete algorithm
• "See Also" section referencing related algorithm implementations

2. Method Documentation

Added detailed docstrings for all methods:

__init__() - Documents all 6 parameters:

domain, fitness_function, seed, seed_init, init, max_time

Each parameter includes type information, purpose, default values, and behavioral notes.

get_base() - Explains its use for algorithm family identification (e.g., "BaseGA" for all genetic algorithm variants), useful for plotting and result categorization.

get_name() - Explains its use for identifying specific algorithm implementations (e.g., "HillClimb", "RandomSearch"), used for labeling results.

run() - Documents:

• All input parameters (domain, fitness_function, seed)
• The 5-element return tuple structure: (best_solution, best_cost, scores, nfe, seed)
• Usage example with code
• Important notes about respecting the max_time limit

3. Enhanced Inline Comments

Improved existing comments to be more descriptive:

• Detailed explanation of each seeding strategy's purpose and behavior
• Clarified initialization logic for the init parameter
• Noted potential bug where max_time parameter is always overridden to 1000

4. Code Quality Improvements

• Fixed spacing around operators for PEP 8 compliance
• Improved code readability without changing functionality

Example Usage

After these changes, developers can now easily understand how to use the base class:

from fliscopt.hc import HillClimb
from fliscopt.fitness import domain, fitness_function

# Create an algorithm instance with clear understanding of parameters
hc = HillClimb(
    domain=domain['domain'],           # Search space boundaries
    fitness_function=fitness_function,  # Objective function to minimize
    seed=42,                            # For reproducibility
    seed_init=False                     # Fully deterministic run
)

# Run the optimization
solution, cost, scores, nfe, seed = hc.run(
    domain=domain['domain'],
    fitness_function=fitness_function,
    seed=42
)

Verification

• ✅ All Python syntax validated
• ✅ Documentation accessible via help() function
• ✅ Class structure and functionality unchanged
• ✅ PEP 8 formatting applied
• ✅ CodeQL security scan: 0 vulnerabilities found

Impact

This documentation enhancement makes the codebase more maintainable and accessible to contributors by providing clear guidance on:

• The architecture and design patterns used
• How to properly implement new optimization algorithms
• The expected interfaces and return formats
• Best practices for reproducible experiments

Total documentation added: ~6,000 characters across class and method docstrings, transforming an undocumented 36-line file into a well-documented 172-line file.

Original prompt

On base_algorithm.py, Explain this shit

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.