Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
256 lines (187 loc) · 6.32 KB

CONTRIBUTING.md

File metadata and controls

256 lines (187 loc) · 6.32 KB

Contributing to ActiveLearning4RA

Thank you for considering contributing to ActiveLearning4RA! We welcome contributions from the community.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue with:

  • A clear, descriptive title
  • Steps to reproduce the issue
  • Expected vs. actual behavior
  • Your environment (Python version, OS, etc.)
  • Minimal code example that demonstrates the problem

Suggesting Enhancements

We welcome feature requests! Please open an issue with:

  • Clear description of the proposed feature
  • Use case / motivation
  • Possible implementation approach (if you have ideas)

Pull Requests

  1. Fork the repository and create a new branch from main

  2. Set up development environment:

    git clone https://github.com/yourusername/ActiveLearning4RA.git
cd ActiveLearning4RA
pip install -e ".[dev]"

  3. Make your changes:

    • Follow the existing code style
    • Add docstrings for all public functions
    • Include type hints
    • Add comments for complex logic

  4. Test your changes:

    # Run existing examples
cd examples/component
python main.py

# If adding new features, add tests
pytest tests/

  5. Commit your changes:

    git add .
git commit -m "Add feature: description of your changes"

  6. Push to your fork:

    git push origin your-branch-name

  7. Open a Pull Request:

    • Provide a clear description of your changes
    • Reference any related issues
    • Ensure all CI checks pass

Code Style

Python Style

  • Follow PEP 8
  • Use 4 spaces for indentation
  • Maximum line length: 100 characters (flexible for readability)
  • Use meaningful variable names

Docstring Format

def my_function(arg1: torch.Tensor, arg2: float) -> torch.Tensor:
    """
    Brief description of what the function does.

    Longer description if needed, explaining the algorithm,
    mathematical formulas, or important implementation details.

    Parameters:
        arg1: Description of arg1, including shape if tensor (e.g., [N, D])
        arg2: Description of arg2

    Returns:
        Description of return value, including shape if tensor

    Example:
        >>> x = torch.randn(10, 2)
        >>> result = my_function(x, 1.0)
    """
    # Implementation
    pass

Type Hints

Always use type hints for function signatures:

from typing import List, Tuple, Optional
import torch

def process_data(
    samples: torch.Tensor,
    threshold: float = 0.0
) -> Tuple[torch.Tensor, int]:
    """Process data and return results."""
    # ...
    return processed_samples, count

Areas for Contribution

We especially welcome contributions in these areas:

🔬 Algorithm Enhancements

  • New learning functions (e.g., REIF, EGRA)
  • Adaptive batch sizing
  • Multi-fidelity methods
  • Time-dependent reliability

🚀 Performance Improvements

  • GPU parallelization for large MCS pools
  • Sparse GP methods for scalability
  • Faster DPP sampling algorithms

📊 Visualization

  • Interactive 3D plots for 3D problems
  • Animation of sampling process
  • Dashboard for real-time monitoring

🧪 Testing

  • Unit tests for core functions
  • Integration tests for full workflows
  • Benchmark suite for performance tracking

📚 Documentation

  • Tutorial notebooks
  • Video tutorials
  • API documentation improvements
  • Additional examples

🔧 Utilities

  • More DOE methods (Sobol, Halton, etc.)
  • Sensitivity analysis tools
  • Result export/import utilities
  • Configuration file support (YAML/JSON)

Development Workflow

Branch Naming

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation updates
  • refactor/description - Code refactoring

Commit Messages

Use clear, descriptive commit messages:

Add batch DPP sampling for AK-MCS

- Implement greedy DPP-MAP algorithm
- Add ARD-based distance weighting
- Include tests for 2D and 10D cases
- Update documentation

Closes #42

Testing Guidelines

If you're adding new features:

  1. Add unit tests in tests/ directory
  2. Add integration tests if the feature affects multiple modules
  3. Test edge cases: empty inputs, extreme values, etc.
  4. Verify numerical stability with different random seeds

Example test structure:

import pytest
import torch
from ActiveLearning4RA.core.component import AK_MCS

def test_ak_mcs_basic():
    """Test basic AK-MCS functionality"""
    # Setup
    def simple_func(x):
        return x[:, 0] + x[:, 1] - 2

    # Run test
    # ...

    # Assertions
    assert model is not None
    assert len(pf_path) > 0

def test_ak_mcs_convergence():
    """Test convergence behavior"""
    # ...

Code Review Process

All pull requests will be reviewed by maintainers. We look for:

  1. Correctness: Does the code work as intended?
  2. Quality: Is the code readable and maintainable?
  3. Testing: Are there adequate tests?
  4. Documentation: Are docstrings and comments clear?
  5. Style: Does it follow the project conventions?

Please be patient - we'll do our best to review PRs in a timely manner.

Questions?

If you have questions about contributing, feel free to:

  • Open an issue with the "question" label
  • Start a discussion in GitHub Discussions
  • Email the maintainers

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors.

Expected Behavior

  • Be respectful and considerate
  • Accept constructive criticism gracefully
  • Focus on what's best for the community
  • Show empathy towards others

Unacceptable Behavior

  • Harassment or discriminatory language
  • Personal attacks or trolling
  • Publishing others' private information
  • Other conduct inappropriate in a professional setting

License

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

Thank you for contributing to ActiveLearning4RA! 🎉