Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
342 lines (240 loc) · 7.15 KB

CONTRIBUTING.md

File metadata and controls

342 lines (240 loc) · 7.15 KB

Contributing to Schr

Thank you for your interest in contributing to Schr! This guide will help you get started with development, testing, and submitting contributions.

Table of Contents

Getting Started

Prerequisites

  • Python >= 3.11
  • uv package manager
  • Git
  • (Optional) CUDA-compatible GPU for testing GPU features

Development Setup

  1. Fork and clone the repository:

    git clone https://github.com/sql-hkr/schr.git
cd schr

  2. Install uv if you haven't already:

    curl -LsSf https://astral.sh/uv/install.sh | sh

  3. Sync all dependencies (including development tools):

    uv sync --all-extras

    This installs:

    • Core dependencies (JAX, matplotlib, tqdm)
    • Development tools (pytest, ruff, sphinx)
    • The package in editable mode
    • Creates/updates the virtual environment automatically

  4. Verify installation:

    uv run pytest
python -c "import schr; print(schr.__version__)"

Code Style

Python Style Guidelines

We follow PEP 8 with these specifications:

  • Line length: 100 characters
  • Indentation: 4 spaces (no tabs)
  • Quotes: Double quotes for strings
  • Imports: Sorted and grouped (stdlib, third-party, local)

Using Ruff

We use ruff for linting and formatting:

# Check code
uv run ruff check src/

# Fix issues automatically
uv run ruff check --fix src/

# Format code
uv run ruff format src/

Configuration is in pyproject.toml.

Testing

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=schr

# Run specific test file
uv run pytest tests/test_qm.py

# Verbose output
uv run pytest -v

Test Coverage

Aim for >80% code coverage. Generate coverage reports:

# HTML coverage report
uv run pytest --cov=schr --cov-report=html

# View report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

Contribution Workflow

Creating a Feature Branch

# Update main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/your-feature-name

Making Changes

  1. Write code following style guidelines

  2. Add tests for new functionality

  3. Update documentation if needed

  4. Run tests to ensure nothing breaks:

    uv run pytest
uv run ruff check src/

  5. Commit changes with clear messages:

    git add src/schr/new_file.py tests/test_new_file.py
git commit -m "feat: add new feature with description"

Commit Message Guidelines

Follow conventional commits format:

type: short description

Longer explanation if needed. Describe:
- What changed
- Why it changed
- Any breaking changes

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • test: Adding tests
  • refactor: Code restructuring
  • perf: Performance improvement
  • chore: Maintenance tasks

Examples:

git commit -m "feat: add Crank-Nicolson solver"
git commit -m "fix: correct boundary handling in 3D"
git commit -m "docs: add section on tunneling"
git commit -m "test: increase coverage for edge cases"

Pull Request Process

Submitting a Pull Request

  1. Push your branch:

    git push origin feature/your-feature-name

  2. Create Pull Request on GitHub:

    • Go to https://github.com/sql-hkr/schr/pulls

    • Click "New Pull Request"

    • Select your branch

    • Fill in the PR template:

      ## Description
Brief description of changes

## Motivation
Why are these changes needed?

## Changes Made
- Added X
- Modified Y
- Fixed Z

## Testing
- [ ] All tests pass
- [ ] Added new tests
- [ ] Documentation updated

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated

  3. Address review comments:

    • Respond to reviewer feedback
    • Make requested changes
    • Push updates to the same branch

PR Checklist

Before submitting, ensure:

  • Code follows PEP 8 and passes ruff check
  • All tests pass (uv run pytest)
  • New features have tests
  • Documentation is updated
  • Commit messages follow conventions
  • No merge conflicts with main

Code Review

What We Look For

  • Correctness: Does it work as intended?
  • Tests: Are there adequate tests?
  • Documentation: Is it well-documented?
  • Style: Does it follow guidelines?
  • Performance: Is it efficient?
  • Maintainability: Is it readable?

Areas for Contribution

High Priority

  • New solvers: Magnus expansion, etc.
  • 3D examples: More complex 3D systems
  • Performance: GPU optimization, better memory management
  • Documentation: More tutorials and examples
  • Testing: Increase coverage, add benchmarks

Medium Priority

  • Visualization: Enhanced plotting utilities
  • Analysis tools: Expectation values, correlation functions
  • QED features: More interaction Hamiltonians
  • Examples: Real-world applications

Good First Issues

Look for issues labeled good first issue on GitHub:

  • Documentation improvements
  • Adding docstring examples
  • Writing unit tests
  • Fixing typos
  • Adding type hints

Bug Reports

When reporting bugs, include:

  1. Clear title describing the issue

  2. Environment information:

    import sys
import jax
print(f"Python: {sys.version}")
print(f"JAX: {jax.__version__}")
print(f"Backend: {jax.default_backend()}")

  3. Minimal reproducible example

  4. Expected behavior

  5. Actual behavior

  6. Full error traceback

Feature Requests

When requesting features, include:

  1. Clear title: "Feature: [description]"
  2. Motivation: Why is this needed?
  3. Proposed solution: How should it work?
  4. Alternatives: Other approaches?
  5. Use cases: Examples of usage

Community Guidelines

Code of Conduct

  • Be respectful: Treat everyone with respect
  • Be inclusive: Welcome diverse perspectives
  • Be constructive: Provide helpful feedback
  • Be patient: Everyone is learning

Communication Channels

  • GitHub Issues: Bug reports, feature requests
  • Pull Requests: Code contributions
  • Discussions: Questions, ideas, general discussion

Getting Help

If you need help:

  1. Check the documentation
  2. Search existing issues
  3. Ask in GitHub Discussions
  4. Contact maintainers: sql.hkr@gmail.com

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to Schr!

Your contributions make this package better for the entire research community.

For questions, open an issue or discussion on GitHub.