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
Development Setup
Code Style
Testing
Contribution Workflow
Pull Request Process
Code Review
Community Guidelines

Getting Started¶

Prerequisites¶

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

Development Setup¶

Fork and clone the repository:

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

Install uv if you haven’t already:

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

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

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¶

Write code following style guidelines
Add tests for new functionality
Update documentation if needed
Run tests to ensure nothing breaks:
```
uv run pytest
uv run ruff check src/
```

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¶

Push your branch:

git push origin feature/your-feature-name

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

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:

Clear title describing the issue

Environment information:

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

Minimal reproducible example
Expected behavior
Actual behavior
Full error traceback

Feature Requests¶

When requesting features, include:

Clear title: “Feature: [description]”
Motivation: Why is this needed?
Proposed solution: How should it work?
Alternatives: Other approaches?
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:

Check the documentation
Search existing issues
Ask in GitHub Discussions
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.