Contributing to DeepLens¶

We welcome contributions to DeepLens! This guide will help you get started.

Ways to Contribute¶

There are many ways to contribute to DeepLens:

Bug Reports: Report bugs and issues
Feature Requests: Suggest new features and enhancements
Code Contributions: Submit pull requests with bug fixes or new features
Documentation: Improve documentation and examples
Testing: Test the software and report issues
Community: Help others on Slack and GitHub Discussions

Getting Started¶

Fork the Repository

Fork the DeepLens repository on GitHub:

https://github.com/singer-yang/DeepLens

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/DeepLens.git
cd DeepLens

Set Up Development Environment

conda create -n deeplens_dev python=3.9
conda activate deeplens_dev
pip install -r requirements.txt

# Install development dependencies
pip install pytest black flake8 sphinx

Create a Branch

git checkout -b feature/my-new-feature
# or
git checkout -b fix/bug-description

Development Guidelines¶

Code Style¶

DeepLens follows PEP 8 style guidelines with some modifications:

Line Length: Maximum 100 characters
Indentation: 4 spaces (no tabs)
Quotes: Use single quotes for strings
Imports: Organized in groups (standard library, third-party, local)

Format code with Black:

black deeplens/ --line-length 100

Check with flake8:

flake8 deeplens/ --max-line-length 100

Code Structure¶

Follow these conventions:

File Organization:

# Copyright and license header
# Docstring explaining the module

# Imports (grouped)
import os
import sys

import torch
import numpy as np

from deeplens.optics import Ray

# Constants
DEFAULT_WAVELENGTH = 0.550

# Classes and functions
class MyClass:
    """Class docstring."""

    def __init__(self, param):
        """Initialize with param."""
        self.param = param

Docstrings:

Use Google-style docstrings:

def calculate_psf(depth, spp=2048, wavelength=0.550):
    """Calculate Point Spread Function.

    Args:
        depth (float): Object distance in mm.
        spp (int): Samples per pixel. Default: 2048.
        wavelength (float): Wavelength in micrometers. Default: 0.550.

    Returns:
        torch.Tensor: PSF tensor with shape [C, H, W].

    Raises:
        ValueError: If depth is negative.

    Example:
        >>> psf = calculate_psf(depth=1000, spp=4096)
        >>> print(psf.shape)
        torch.Size([1, 64, 64])
    """
    if depth < 0:
        raise ValueError("Depth must be positive")

    # Implementation
    return psf

Testing¶

Write tests for new features:

# tests/test_lens.py
import pytest
import torch
from deeplens import GeoLens

def test_lens_initialization():
    """Test GeoLens initialization."""
    lens = GeoLens(
        filename='./datasets/lenses/camera/ef50mm_f1.8.json',
        device='cpu'
    )
    assert lens.foclen > 0
    assert len(lens.surfaces) > 0

def test_psf_calculation():
    """Test PSF calculation."""
    lens = GeoLens(filename='./datasets/lenses/camera/ef50mm_f1.8.json')
    psf = lens.psf(points=[0.0, 0.0, -1000.0], spp=256)

    assert psf.shape[0] == 1  # Single channel
    assert psf.sum() > 0  # Non-zero PSF
    assert torch.isfinite(psf).all()  # No NaN or Inf

Run tests:

pytest tests/ -v

Contribution Workflow¶

Make Changes

Implement your feature or bug fix following the guidelines above.

Test Your Changes

# Run tests
pytest tests/

# Check code style
black deeplens/ --check
flake8 deeplens/

Commit Your Changes

Write clear, descriptive commit messages:
```
git add .
git commit -m "Add feature: brief description

Detailed explanation of what changed and why.
Closes #123"
```
Commit message format:
- First line: Brief summary (50 chars or less)
- Blank line
- Detailed description
- Reference issues: Closes #123 or Fixes #456
Push to Your Fork
```
git push origin feature/my-new-feature
```
Create Pull Request
- Go to the DeepLens repository on GitHub
- Click “New Pull Request”
- Select your fork and branch
- Fill in the PR template:
  - Description of changes
  - Related issues
  - Testing done
  - Screenshots (if applicable)
Code Review
- Respond to reviewer comments
- Make requested changes
- Push updates to your branch
Merge

Once approved, your PR will be merged by a maintainer.

Types of Contributions¶

Bug Fixes¶

When fixing a bug:

Create an issue describing the bug (if it doesn’t exist)
Write a test that reproduces the bug
Fix the bug
Verify the test now passes
Submit PR referencing the issue

New Features¶

For new features:

Discuss in an issue or Slack first
Design API and implementation
Write comprehensive tests
Add documentation and examples
Submit PR with:
- Implementation
- Tests
- Documentation
- Example usage

Documentation¶

Documentation improvements are always welcome:

Fix typos and clarify text
Add examples
Improve API documentation
Write tutorials

Documentation is in docs/ using reStructuredText:

cd docs/
make html
# Open _build/html/index.html in browser

Examples¶

Add examples to demonstrate features:

Create standalone script in root directory
Add thorough comments
Include sample data or instructions
Add to documentation examples section

Code Review Guidelines¶

When reviewing code:

What to Look For:

Correctness: Does the code work as intended?
Tests: Are there adequate tests?
Documentation: Is it well-documented?
Style: Does it follow guidelines?
Performance: Are there obvious inefficiencies?
Compatibility: Does it break existing code?

How to Review:

Be constructive and friendly
Explain reasoning for suggestions
Approve when ready or request changes
Test the code if possible

Community Guidelines¶

Be Respectful¶

Be welcoming to newcomers
Be patient with questions
Give constructive feedback
Respect different viewpoints

Communication¶

GitHub Issues: Bug reports, feature requests
Pull Requests: Code contributions
Slack: Quick questions, discussions
Email: Private matters

Report Issues¶

If you encounter:

Bugs or errors
Security vulnerabilities
Code of conduct violations

Report them through appropriate channels.

Development Setup¶

Advanced Setup¶

For development with GPU profiling and debugging:

# Install development dependencies
pip install pytest pytest-cov black flake8 ipdb

# Install documentation tools
pip install sphinx sphinx-rtd-theme

# Install pre-commit hooks (optional)
pip install pre-commit
pre-commit install

Running Tests¶

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_lens.py

# Run with coverage
pytest tests/ --cov=deeplens --cov-report=html

# Run only fast tests (skip slow integration tests)
pytest tests/ -m "not slow"

Building Documentation¶

cd docs/
make clean
make html

# View in browser
open _build/html/index.html  # macOS
xdg-open _build/html/index.html  # Linux

Release Process¶

For maintainers releasing new versions:

Update version in __init__.py
Update CHANGELOG.md
Create git tag: git tag v1.2.0
Push tag: git push origin v1.2.0
Create GitHub release
Update documentation

License¶

By contributing to DeepLens, you agree that your contributions will be licensed under the Creative Commons Attribution-NonCommercial 4.0 International License.

Questions?¶

If you have questions about contributing:

Check existing documentation
Search GitHub issues
Ask on Slack
Email: xinge.yang@kaust.edu.sa

Thank You!¶

Thank you for contributing to DeepLens! Your efforts help make optical simulation and design accessible to everyone.

DeepLens

Navigation

Related Topics