Skip to content

Getting Started with TorchEBM Development

Welcome to the TorchEBM development community! This guide provides everything you need to set up your environment, understand our workflow, and make your first contribution.

Ways to Contribute

We welcome contributions of all kinds:

  • Report Bugs

    Find a bug? Report it on our issue tracker with a clear description and steps to reproduce.

  • Suggest Features

    Have an idea for a new feature or an improvement? Share it in the discussions.

  • Improve Documentation

    Help us make our documentation better by fixing typos, clarifying explanations, or adding new examples.

  • Write Code

    Contribute directly to the codebase by fixing bugs, implementing new features, or improving performance.

Development Setup

Follow these steps to set up your local development environment.

1. Prerequisites

Make sure you have the following installed:

  • Python 3.9+
  • Git
  • A GitHub Account

2. Fork and Clone

First, fork the TorchEBM repository on GitHub. Then, clone your fork locally:

1
2
git clone https://github.com/YOUR-USERNAME/torchebm.git
cd torchebm

3. Set Up Virtual Environment

It's highly recommended to use a virtual environment:

1
2
3
4
5
6
7
8
# Create a virtual environment
python -m venv venv

# Activate it (macOS/Linux)
source venv/bin/activate

# Or on Windows
venv\Scripts\activate

4. Install Dependencies

Install TorchEBM in editable mode along with all development dependencies:

1
pip install -e ".[dev]"

Contribution Workflow

1. Create a Branch

Create a new branch for your changes. Use a descriptive name, like feature/new-sampler or fix/gradient-bug.

1
git checkout -b feature/your-feature-name

2. Make Changes

Make your changes to the codebase. Be sure to follow our Code Guidelines.

3. Run Tests

Before committing, run the tests to ensure your changes haven't broken anything:

1
pytest

4. Commit Your Changes

We follow the Conventional Commits specification. Your commit messages should be structured as follows:

1
2
3
4
5
<type>: <description>

[optional body]

[optional footer]

Common types:

Type Description
feat A new feature
fix A bug fix
docs Documentation only changes
style Changes that do not affect the meaning of the code
refactor A code change that neither fixes a bug nor adds a feature
perf A code change that improves performance
test Adding missing tests or correcting existing tests
chore Changes to the build process or auxiliary tools

Example:

1
git commit -m "feat: add support for adaptive step sizes in LangevinDynamics"

5. Create a Pull Request

Push your branch to your fork and open a pull request to the main branch of the TorchEBM repository.

1
git push origin feature/your-feature-name

In your pull request description, clearly explain the changes you've made and reference any relevant issues.

Documentation Development

To work on the documentation locally, install the docs dependencies and serve the site:

1
2
pip install -e ".[docs]"
mkdocs serve

This will start a live-reloading server at http://127.0.0.1:8000.