From 746a7ad552846ee235c0752ce689c211042232c3 Mon Sep 17 00:00:00 2001 From: Carlos Gutierrez Date: Wed, 22 Oct 2025 22:08:13 -0400 Subject: [PATCH] creating documentation --- README.md | 294 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) diff --git a/README.md b/README.md index e69de29..cb4ba20 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,294 @@ +# Insertion Sort Algorithm - Decreasing Order Implementation + +## Overview + +This project implements the **Insertion Sort Algorithm** to sort arrays in **monotonically decreasing order** (largest to smallest). The implementation provides both in-place and non-destructive sorting variants, along with comprehensive test cases and detailed documentation. + +### Key Features + +- ✅ **Decreasing Order Sorting**: Sorts arrays from largest to smallest +- ✅ **Two Implementation Variants**: In-place and non-destructive sorting +- ✅ **Comprehensive Test Suite**: Handles edge cases and various input scenarios +- ✅ **Well-Documented Code**: Clear comments and docstrings +- ✅ **Educational Focus**: Demonstrates algorithm concepts with examples + +## Architecture + +### Algorithm Flow Diagram + +``` +Input Array: [5, 2, 8, 1, 9, 3] + ↓ + ┌─────────────────────────────────────┐ + │ Insertion Sort Process │ + └─────────────────────────────────────┘ + ↓ + ┌─────────────────────────────────────┐ + │ Step 1: Start with element at i=1 │ + │ Current: 2, Sorted: [5] │ + │ Insert 2 → [5, 2] │ + └─────────────────────────────────────┘ + ↓ + ┌─────────────────────────────────────┐ + │ Step 2: Process element at i=2 │ + │ Current: 8, Sorted: [5, 2] │ + │ Insert 8 → [8, 5, 2] │ + └─────────────────────────────────────┘ + ↓ + ┌─────────────────────────────────────┐ + │ Step 3: Process element at i=3 │ + │ Current: 1, Sorted: [8, 5, 2] │ + │ Insert 1 → [8, 5, 2, 1] │ + └─────────────────────────────────────┘ + ↓ + ┌─────────────────────────────────────┐ + │ Step 4: Process element at i=4 │ + │ Current: 9, Sorted: [8, 5, 2, 1] │ + │ Insert 9 → [9, 8, 5, 2, 1] │ + └─────────────────────────────────────┘ + ↓ + ┌─────────────────────────────────────┐ + │ Step 5: Process element at i=5 │ + │ Current: 3, Sorted: [9, 8, 5, 2, 1]│ + │ Insert 3 → [9, 8, 5, 3, 2, 1] │ + └─────────────────────────────────────┘ + ↓ +Output Array: [9, 8, 5, 3, 2, 1] +``` + +### Core Algorithm Structure + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Insertion Sort │ +├─────────────────────────────────────────────────────────────┤ +│ Function: insertion_sort_decreasing(arr) │ +│ Input: Array of comparable elements │ +│ Output: Array sorted in decreasing order │ +├─────────────────────────────────────────────────────────────┤ +│ Algorithm Steps: │ +│ 1. Iterate through array starting from index 1 │ +│ 2. For each element, find its correct position │ +│ 3. Shift larger elements to the right │ +│ 4. Insert current element in correct position │ +│ 5. Repeat until all elements are processed │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Implementation Details + +### Core Functions + +#### 1. `insertion_sort_decreasing(arr)` +- **Purpose**: Non-destructive sorting that returns a new sorted array +- **Parameters**: `arr` (list) - Input array to be sorted +- **Returns**: `list` - New array sorted in decreasing order +- **Space Complexity**: O(n) - Creates a copy of the input array + +#### 2. `insertion_sort_decreasing_inplace(arr)` +- **Purpose**: In-place sorting that modifies the original array +- **Parameters**: `arr` (list) - Input array to be sorted (modified) +- **Returns**: `list` - Same array sorted in decreasing order +- **Space Complexity**: O(1) - Sorts in-place + +### Algorithm Logic + +The key difference from standard insertion sort is the comparison condition: + +```python +# Standard insertion sort (ascending): +while j >= 0 and arr[j] > current_element: + +# Our implementation (descending): +while j >= 0 and arr[j] < current_element: +``` + +This ensures that elements are arranged in decreasing order (largest to smallest). + +## Complexity Analysis + +| Aspect | Complexity | Description | +|--------|------------|-------------| +| **Time Complexity** | O(n²) | Worst case when array is sorted in ascending order | +| **Space Complexity** | O(1) | In-place version uses constant extra space | +| **Best Case** | O(n) | When array is already sorted in descending order | +| **Average Case** | O(n²) | Random order arrays | + +## Usage Examples + +### Basic Usage + +```python +from insertion_sort_decreasing import insertion_sort_decreasing + +# Example 1: Basic sorting +arr = [5, 2, 8, 1, 9, 3] +sorted_arr = insertion_sort_decreasing(arr) +print(sorted_arr) # Output: [9, 8, 5, 3, 2, 1] + +# Example 2: In-place sorting +arr = [64, 34, 25, 12, 22, 11, 90] +insertion_sort_decreasing_inplace(arr) +print(arr) # Output: [90, 64, 34, 25, 22, 12, 11] +``` + +### Edge Cases Handled + +```python +# Empty array +empty_arr = [] +result = insertion_sort_decreasing(empty_arr) +print(result) # Output: [] + +# Single element +single = [42] +result = insertion_sort_decreasing(single) +print(result) # Output: [42] + +# Duplicate elements +duplicates = [3, 3, 3, 3] +result = insertion_sort_decreasing(duplicates) +print(result) # Output: [3, 3, 3, 3] +``` + +## Running the Program + +### Prerequisites +- Python 3.6 or higher + +### Execution +```bash +python3 insertion_sort_decreasing.py +``` + +### Expected Output +The program will run through 7 comprehensive test cases demonstrating: +- Random unsorted arrays +- Already sorted arrays (ascending and descending) +- Edge cases (empty, single element, duplicates) +- Larger arrays for performance demonstration + +## Test Cases + +The implementation includes comprehensive test cases: + +1. **Random Array**: `[5, 2, 8, 1, 9, 3]` → `[9, 8, 5, 3, 2, 1]` +2. **Ascending Order**: `[1, 2, 3, 4, 5]` → `[5, 4, 3, 2, 1]` +3. **Descending Order**: `[5, 4, 3, 2, 1]` → `[5, 4, 3, 2, 1]` +4. **Single Element**: `[1]` → `[1]` +5. **Empty Array**: `[]` → `[]` +6. **Duplicates**: `[3, 3, 3, 3]` → `[3, 3, 3, 3]` +7. **Large Array**: `[64, 34, 25, 12, 22, 11, 90]` → `[90, 64, 34, 25, 22, 12, 11]` + +## Educational Value + +This implementation serves as an excellent learning resource for: + +- **Algorithm Understanding**: Clear demonstration of insertion sort mechanics +- **Sorting Concepts**: Shows how to modify algorithms for different sort orders +- **Code Quality**: Demonstrates good practices in Python programming +- **Testing**: Comprehensive test suite showing edge case handling +- **Documentation**: Well-commented code with clear explanations + +## File Structure + +``` +MSCS532_Assignment1/ +├── insertion_sort_decreasing.py # Main implementation +├── test_insertion_sort.py # Comprehensive test suite +├── run_tests.py # Test runner with various options +├── README.md # This documentation +└── LICENSE # Project license +``` + +## Testing + +### Running Tests + +The project includes a comprehensive test suite with multiple ways to run tests: + +#### Quick Tests (Essential functionality) +```bash +python3 run_tests.py --quick +``` + +#### Full Test Suite +```bash +python3 run_tests.py +``` + +#### Unit Tests Only +```bash +python3 run_tests.py --unit-only +``` + +#### Performance Benchmarks +```bash +python3 run_tests.py --benchmark +``` + +#### Stress Tests +```bash +python3 run_tests.py --stress +``` + +#### Negative Test Cases +```bash +python3 run_tests.py --negative +``` + +#### Using unittest directly +```bash +python3 -m unittest test_insertion_sort -v +``` + +### Test Coverage + +The test suite includes **38 comprehensive test cases** covering: + +#### ✅ **Functional Tests** +- Basic sorting functionality +- Already sorted arrays (ascending/descending) +- Empty arrays and single elements +- Duplicate elements +- Negative numbers and zero values +- Large numbers and edge cases + +#### ✅ **Behavioral Tests** +- Non-destructive sorting (original array unchanged) +- In-place sorting (original array modified) +- Sorting stability (equal elements maintain order) + +#### ✅ **Performance Tests** +- Small arrays (10-100 elements) +- Worst-case performance (ascending order) +- Best-case performance (descending order) +- Random arrays with timing measurements + +#### ✅ **Stress Tests** +- Edge cases and boundary conditions +- Very large/small numbers +- Mixed data types +- Random large arrays + +#### ✅ **Negative Test Cases** +- Invalid input types (None, strings, numbers, dicts, tuples, sets) +- Non-comparable elements (mixed types) +- Nested lists and complex data structures +- Custom objects with/without comparison methods +- Infinity and NaN values +- Unicode strings and special characters +- Boolean values and mixed numeric types +- Very large arrays and deep recursion scenarios + +## Contributing + +This is an educational project demonstrating insertion sort implementation. Feel free to: +- Add more test cases +- Implement additional sorting algorithms +- Improve documentation +- Optimize the implementation + +## License + +See LICENSE file for details.