latin-rectangles 0.1.0__tar.gz

latin_rectangles-0.1.0/.gitignore

@@ -0,0 +1,197 @@
+# macOS specific files
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the enitre vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

latin_rectangles-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

latin_rectangles-0.1.0/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+    "python.defaultInterpreterPath": ".venv/bin/python",
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit",
+            "source.fixAll": "explicit"
+        },
+        "editor.formatOnSave": true
+    },
+    "ruff.enable": true,
+    "ruff.importStrategy": "fromEnvironment"
+}

latin_rectangles-0.1.0/COMPLEXITY_ANALYSIS_REPORT.md

@@ -0,0 +1,144 @@
+# Complexity Analysis
+
+## Overview
+
+This document presents a comprehensive complexity analysis of the Latin rectangles extension counting algorithm. The analysis is based on empirical benchmarking data collected across problem sizes from n=4 to n=800.
+
+**Dataset:** 797 benchmark measurements  
+**Algorithm:** Latin rectangle extension counting via rook polynomials and cycle decomposition  
+**Analysis Date:** June 6, 2025
+
+## Summary
+
+The algorithm exhibits quadratic time complexity O(n^2.009) and sub-linear memory complexity O(n^1.360), demonstrating excellent scalability characteristics for combinatorial enumeration problems across an extensive range of problem sizes.
+
+## Time Complexity
+
+### Empirical Analysis
+
+The time complexity analysis was performed on 797 data points spanning n=4 to n=800.
+
+- **Time Range:** 25.6μs to 276ms
+- **Growth Factor:** 10,770× across the tested range
+- **Performance:** Maintains sub-second execution for all tested values
+
+### Model Fitting Results
+
+| Model | R² Score | Formula |
+|-------|----------|---------|
+| **Power** | **0.9812** | **T(n) ≈ 2.95×10⁻⁷ × n^2.009** |
+| Linear | 0.8625 | T(n) ≈ 2.94×10⁻⁴n - 4.48×10⁻² |
+| Logarithmic | 0.5244 | T(n) ≈ 5.65×10⁻²log(n) - 2.49×10⁻¹ |
+
+### Analysis
+
+The power law model provides the best fit (R² = 0.9812) with an exponent of 2.009, indicating near-quadratic scaling. This represents a significant improvement over naive factorial-time approaches and demonstrates the effectiveness of the rook polynomial methodology, with the algorithm approaching quadratic complexity at very large scales while maintaining excellent performance.
+
+## Memory Complexity
+
+### Empirical Analysis
+
+Memory consumption analysis across the same 797 data points shows efficient space utilization.
+
+- **Memory Range:** 0.5KB to 308KB
+- **Growth Factor:** 612× across the tested range
+- **Efficiency:** Maintains minimal memory footprint throughout
+
+### Model Fitting Results
+
+| Model | R² Score | Formula |
+|-------|----------|---------|
+| **Power** | **0.9790** | **M(n) ≈ 2.47×10⁻⁵ × n^1.360** |
+| Linear | 0.9183 | M(n) ≈ 3.21×10⁻⁴n - 3.10×10⁻² |
+| Logarithmic | 0.6273 | M(n) ≈ 6.55×10⁻²log(n) - 2.76×10⁻¹ |
+
+### Analysis
+
+The power law model achieves excellent fit (R² = 0.9790) with an exponent of 1.360, indicating sub-linear memory scaling. The algorithm maintains efficient memory usage patterns essential for practical applications, with memory growth significantly slower than quadratic.
+
+## Result Magnitude Analysis
+
+### Growth Characteristics
+
+The algorithm computes extension counts that grow exponentially with problem size.
+
+- **Result Range:** 2.00 to extremely large values (up to hundreds of digits)
+- **Growth Factor:** Astronomical growth across the tested range
+
+### Model Fitting Results
+
+| Model | R² Score | Formula |
+|-------|----------|---------|
+| **Exponential** | **0.2510** | **Extensions ≈ 7.57×10⁹² × 0.705^n** |
+| Factorial | 1.0000* | Extensions ≈ 1.03×10⁻¹ × (n!)^1.007 |
+
+*Perfect fit for n ≤ 20
+
+### Analysis
+
+While result magnitudes grow exponentially, the algorithm maintains near-quadratic computation time, demonstrating exceptional efficiency in computing large combinatorial values. The factorial model provides perfect fit for smaller values, while larger values show complex growth patterns that challenge simple exponential models.
+
+## Performance Characteristics
+
+### Scalability Profile
+
+The algorithm exhibits excellent scalability across the tested range:
+
+- **n ≤ 50:** Sub-millisecond execution (< 1ms)
+- **n ≤ 200:** Fast execution (< 10ms)
+- **n ≤ 500:** Efficient execution (< 100ms)
+- **n ≤ 800:** Manageable execution (< 300ms)
+
+### Comparative Analysis
+
+The algorithm significantly outperforms theoretical worst-case approaches:
+
+- **vs O(n!):** Exponentially faster for all practical values
+- **vs O(n³):** ~30× faster than cubic scaling at large n
+- **vs O(n²):** Approaches but does not exceed quadratic performance
+
+## Implementation Efficiency
+
+### Algorithmic Strengths
+
+1. **Mathematical Foundation:** Leverages rook polynomial theory for efficient computation
+2. **Cycle Decomposition:** Exploits derangement structure to reduce complexity
+3. **Memory Management:** Maintains minimal memory footprint with efficient data structures
+4. **Numerical Stability:** Handles large integer arithmetic without precision loss
+
+### Technical Characteristics
+
+- **Average Time per Operation:** 132μs across all test cases
+- **Memory Efficiency:** < 308KB for largest tested cases
+- **Numerical Range:** Handles results with hundreds of digits
+- **Consistency:** Stable performance across all problem sizes
+
+## Methodology
+
+### Data Collection
+
+Benchmarks were collected using a systematic approach:
+
+- **Environment:** Controlled testing environment with consistent system resources
+- **Measurement:** High-precision timing using system performance counters
+- **Validation:** Multiple runs per data point with statistical averaging
+- **Range:** Comprehensive coverage from small (n=4) to very large (n=800) problem sizes
+
+### Statistical Analysis
+
+Model fitting employed least-squares regression with coefficient of determination (R²) for goodness-of-fit evaluation. The power law model consistently provided the best fit for both time and memory complexity patterns.
+
+## Conclusions
+
+The Latin rectangles extension counting algorithm demonstrates:
+
+- **Time Complexity:** O(n^2.009) near-quadratic scaling
+- **Memory Complexity:** O(n^1.360) sub-linear scaling
+- **Practical Performance:** Sub-second execution for problem sizes up to n=800
+- **Scalability:** Maintains efficiency across an extensive range of problem sizes
+
+The algorithm's performance characteristics make it suitable for production use in combinatorial enumeration applications requiring both accuracy and efficiency, with excellent scalability demonstrated up to n=800.
+
+---
+
+*Analysis based on 797 empirical measurements across problem sizes n=4 to n=800*

latin_rectangles-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,34 @@
+# Development commands
+
+## Setup
+
+```bash
+# Install the project in development mode
+uv sync --dev
+
+# Activate the virtual environment
+source .venv/bin/activate  # or use `uv run` prefix for commands
+```
+
+## Linting and Formatting
+
+```bash
+# Check code style and lint
+uv run ruff check
+
+# Fix auto-fixable issues
+uv run ruff check --fix
+
+# Format code
+uv run ruff format
+
+# Check formatting without making changes
+uv run ruff format --check
+```
+
+## Running the application
+
+```bash
+# Run the main script
+uv run latin-rectangles --n 42
+```

latin_rectangles-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ioannis Michaloliakos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

latin_rectangles-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: latin-rectangles
+Version: 0.1.0
+Summary: Count the number of one-row extensions of Latin rectangles.
+Author-email: Ioannis Michaloliakos <ioannis.michalol@ufl.edu>
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Latin Rectangles Extension Counter
+
+A high-performance Python library for counting the number of ways to extend a 2×n [Latin rectangle](https://en.wikipedia.org/wiki/Latin_rectangle) to a 3×n Latin rectangle using rook polynomial methods and cycle decomposition theory.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Overview
+
+A **Latin rectangle** is an r×n array filled with n different symbols such that each symbol occurs exactly once in each row and at most once in each column.
+
+### Extension Problem
+
+Given a 2×n Latin rectangle:
+
+```text
+1  2  3  4  5  6  7  8
+p[1]  p[2]  p[3]  p[4]  p[5]  p[6]  p[7]  p[8]
+```
+
+where `p` is a [derangement](https://en.wikipedia.org/wiki/Derangement), the problem is to count how many valid third rows can be added such that the resulting 3×n rectangle remains a Latin rectangle. This library provides an efficient algorithm for computing Latin rectangle extensions.
+
+### Key Features
+
+- **High Performance**: Approximate O(n^2) time complexity, tested **up to n=800**.
+- **Memory Efficient**: Approximate O(n^1.36) memory complexity
+- **Mathematically Rigorous**: Based on rook polynomial theory and cycle decomposition
+- **Easy to Use**: Simple command-line interface and Python API
+- **Well Tested**: Comprehensive test suite with complexity analysis
+
+## Installation
+
+```console
+git clone https://github.com/ionmich/latin-rectangles.git
+cd latin-rectangles
+```
+
+## Quick Start
+
+### Command Line (CLI) Usage
+
+Generate random derangement:
+
+```console
+> uv run python -m latin_rectangles --n 42
+🎲 Generated Random Derangement for n=42
+📊 Cycle structure: [2, 2, 4, 8, 26]
+🔢 Number of extensions: 185,566,788,772,996,286,199,647,931,971,186,844,003,087,641,029,824
+```
+
+Use specific cycle structure:
+
+```console
+> uv run python -m latin_rectangles --c "2,2,4"
+⚙️  Specific Cycle Structure for n=8
+📊 Cycle structure: [2, 2, 4]
+🔢 Number of extensions: 4,744
+```
+
+Enumerate all possible cycle structures:
+
+```console
+> uv run python -m latin_rectangles --n 8 --all
+🔍 All Cycle Structures for n=8
+📊 Found 7 possible structures with non-zero extensions:
+
+ 1. [2, 2, 2, 2] → 4,752 extensions
+ 2. [2, 2, 4] → 4,744 extensions
+ 3. [2, 3, 3] → 4,740 extensions
+ 4. [2, 6] → 4,740 extensions
+ 5. [4, 4] → 4,740 extensions
+ 6. [3, 5] → 4,738 extensions
+ 7. [8] → 4,738 extensions
+```
+
+## Get help
+
+```console
+uv run latin-rectangles --help
+```
+
+## Python Library Usage
+
+```python
+from latin_rectangles import count_extensions, count_random_extensions
+from latin_rectangles import generate_random_derangement
+
+# Method 1: One-liner for random derangement
+extensions = count_random_extensions(n=12)
+print(f"Extensions: {extensions:,}")
+
+# Method 2: Step-by-step with custom derangement
+derangement = generate_random_derangement(n=10)
+extensions = count_extensions(derangement)
+print(f"Derangement {derangement[1:]} has {extensions:,} extensions")
+
+# Method 3: With predefined derangement (1-indexed with dummy 0)
+p = [0, 2, 3, 4, 5, 6, 7, 8, 1]  # 8-cycle for n=8
+extensions = count_extensions(p)
+print(f"8-cycle has {extensions:,} extensions")  # Output: 4,738
+```
+
+## Algorithm Details
+
+### Mathematical Foundation
+
+The algorithm leverages **rook polynomial theory** to solve the Latin rectangle extension problem:
+
+1. **Input**: A derangement (permutation with no fixed points) representing the second row
+2. **Cycle Decomposition**: Decompose the derangement into disjoint cycles
+3. **Rook Polynomials**: Compute rook polynomial for each cycle structure
+4. **Polynomial Multiplication**: Combine rook polynomials to get the final count
+
+## API Reference
+
+### Core Functions
+
+#### `count_extensions(permutation: list[int]) -> int`
+
+Counts the number of extensions for a given derangement.
+
+**Parameters:**
+
+- `permutation`: 1-indexed list representing a derangement (p[0] is dummy value)
+
+**Returns:** Integer number of possible third rows
+
+**Raises:** `ValueError` if input is not a derangement
+
+#### `count_random_extensions(n: int) -> int`
+
+Convenience function that generates a random derangement and counts its extensions.
+
+**Parameters:**
+
+- `n`: Size of the derangement (must be > 1)
+
+**Returns:** Number of extensions for the randomly generated derangement
+
+#### `generate_random_derangement(n: int) -> list[int]`
+
+Generates a random derangement of size n.
+
+**Parameters:**
+
+- `n`: Size of the derangement
+
+**Returns:** 1-indexed list representing the derangement
+
+#### `find_cycle_decomposition(permutation: list[int]) -> list[list[int]]`
+
+Finds the cycle decomposition of a permutation.
+
+**Parameters:**
+
+- `permutation`: 1-indexed permutation
+
+**Returns:** List of cycles (each cycle is a list of indices)
+
+## Examples
+
+### Basic Usage Examples
+
+```python
+from latin_rectangles import count_extensions
+
+# Example 1: Single 8-cycle
+p_8_cycle = [0, 2, 3, 4, 5, 6, 7, 8, 1]
+print(f"8-cycle: {count_extensions(p_8_cycle):,} extensions")
+# Output: 8-cycle: 4,738 extensions
+
+# Example 2: Two 4-cycles  
+p_4_4 = [0, 2, 3, 4, 1, 6, 7, 8, 5]
+print(f"4,4-cycles: {count_extensions(p_4_4):,} extensions")
+# Output: 4,4-cycles: 4,740 extensions
+
+# Example 3: Four 2-cycles
+p_2_2_2_2 = [0, 2, 1, 4, 3, 6, 5, 8, 7]
+print(f"2,2,2,2-cycles: {count_extensions(p_2_2_2_2):,} extensions")
+# Output: 2,2,2,2-cycles: 4,752 extensions
+```
+
+### Advanced Usage
+
+```python
+from latin_rectangles import generate_random_derangement, find_cycle_decomposition, count_extensions
+
+# Generate and analyze a random derangement
+n = 15
+derangement = generate_random_derangement(n)
+cycles = find_cycle_decomposition(derangement)
+cycle_lengths = sorted([len(c) for c in cycles])
+extensions = count_extensions(derangement)
+
+print(f"n={n}")
+print(f"Derangement: {derangement[1:]}")
+print(f"Cycle structure: {cycle_lengths}")
+print(f"Extensions: {extensions:,}")
+```
+
+### Batch Processing
+
+```python
+from latin_rectangles import count_random_extensions
+
+# Process multiple sizes
+results = []
+for n in range(5, 21):
+    extensions = count_random_extensions(n)
+    results.append((n, extensions))
+    print(f"n={n:2d}: {extensions:,} extensions")
+
+# Find the size with the most extensions in this batch
+max_n, max_extensions = max(results, key=lambda x: x[1])
+print(f"Maximum: n={max_n} with {max_extensions:,} extensions")
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run the test suite
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=latin_rectangles
+
+# Run specific test
+uv run pytest tests/test_main.py -v
+```
+
+### Code Quality
+
+```bash
+# Type checking
+uv run mypy src/
+
+# Linting
+uv run ruff check src/
+
+# Formatting
+uv run ruff format src/
+```
+
+### Benchmarking
+
+```bash
+# Run performance benchmarks
+uv run python benchmark.py
+
+# Analyze complexity
+uv run python complexity_analysis.py
+```
+
+## Contributing
+
+Contributions are welcome! Please see [DEVELOPMENT.md](DEVELOPMENT.md) for development guidelines.
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Citation
+
+If you use this library in your research, please cite:
+
+```bibtex
+@software{latin_rectangles,
+  title={Latin Rectangles Extension Counter},
+  author={Ioannis Michaloliakos},
+  year={2025},
+  url={https://github.com/ionmich/latin-rectangles}
+}
+```