Contributing Guide

Thank you for your interest in contributing to the Low-Rank Toolbox!

How to Contribute

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/low-rank-toolbox.git
cd low-rank-toolbox

Create a development environment:

conda env create -f environment.yml
conda activate low-rank-dev
pip install -e .

Create a new branch for your feature or bugfix:

git checkout -b feature/your-feature-name

Make your changes and ensure:
- Code follows existing style conventions
- All tests pass: pytest
- New features include tests
- Documentation is updated if needed
Run tests locally:
```
pytest -v
```

Build documentation to verify your changes:

cd docs
make html
# Open build/html/index.html in your browser

Commit your changes with clear, descriptive messages:

git add .
git commit -m "Add feature: brief description"

Push to your fork:

git push origin feature/your-feature-name

Submit a Pull Request on GitHub

Code Style Guidelines

Python Code:

Follow PEP 8 style guide
Use type hints for function parameters and return values
Maximum line length: 127 characters
Use meaningful variable names

Docstrings:

Use NumPy-style docstrings
Include mathematical notation where appropriate
Provide examples for complex functions
Reference academic papers when implementing published algorithms

Example:

def my_function(A: ndarray, k: int) -> ndarray:
    """
    Brief one-line description.

    More detailed explanation of what the function does,
    including mathematical notation if needed.

    Parameters
    ----------
    A : ndarray
        Description of parameter A
    k : int
        Description of parameter k

    Returns
    -------
    ndarray
        Description of return value

    Examples
    --------
    >>> import numpy as np
    >>> A = np.random.randn(10, 5)
    >>> result = my_function(A, 3)
    >>> result.shape
    (10, 3)

    References
    ----------
    .. [1] Author et al. (2023). Paper title. Journal.
    """
    # Implementation here
    pass

Testing Guidelines

Writing Tests:

Place tests in the tests/ directory
Mirror the source code structure
Name test files test_<module>.py
Name test functions test_<functionality>

Test Coverage:

Aim for >90% code coverage
Test edge cases (empty arrays, single elements, etc.)
Test error handling
Test both real and complex data types

Example Test:

def test_my_function_basic():
    """Test basic functionality of my_function."""
    A = np.random.randn(10, 5)
    result = my_function(A, 3)

    assert result.shape == (10, 3)
    assert np.linalg.norm(result) > 0

def test_my_function_edge_case():
    """Test edge case with empty array."""
    A = np.random.randn(10, 0)
    with pytest.raises(ValueError):
        my_function(A, 3)

Documentation Guidelines

Updating Documentation:

When adding new features:

Update relevant docstrings
Add examples to docs/source/quickstart.rst if appropriate
Update API reference if adding new classes/functions
Build docs locally to verify formatting

Building Documentation:

cd docs
make clean
make html
# View: open build/html/index.html

Pull Request Process

Before Submitting:

✅ All tests pass locally
✅ Code follows style guidelines
✅ Documentation is updated
✅ Commit messages are clear
✅ No merge conflicts with main branch

PR Description Should Include:

What changes were made
Why the changes were made
How to test the changes
Any breaking changes
References to related issues

Review Process:

Automated checks will run (tests, linting, docs build)
Maintainers will review your code
Address any requested changes
Once approved, your PR will be merged!

Reporting Issues

Bug Reports:

Include:

Python version
Operating system
Minimal reproducible example
Expected vs. actual behavior
Full error traceback

Feature Requests:

Include:

Use case description
Proposed API (if applicable)
References to papers/algorithms (if applicable)
Why this would be valuable to the community

Communication

GitHub Issues: Bug reports, feature requests
Pull Requests: Code contributions
Discussions: General questions, ideas

Code of Conduct

Be respectful and constructive in all interactions. We welcome contributors from all backgrounds and experience levels.

Questions?

If you’re unsure about anything, feel free to ask! Open an issue or start a discussion on GitHub.

Thank you for contributing! 🎉