entropice/CONTRIBUTING.md

Contributing to Entropice

Thank you for your interest in contributing to Entropice! This document provides guidelines for contributing to the project.

Getting Started

Prerequisites

• CUDA 12 compatible GPU (for full functionality)
• Pixi package manager

Setup

pixi install

This will set up the complete environment including Python, RAPIDS, PyTorch, and all geospatial dependencies.

Development Workflow

Read in the Architecture Guide about the code organisatoin and key modules

Important: Always use pixi run to execute Python commands and scripts to ensure you're using the correct environment with all dependencies:

pixi run python script.py
pixi run python -c "import entropice"

Python Style and Formatting

• Follow PEP 8 conventions
• Use type hints for function signatures
• Prefer google-style docstrings for public functions
• Keep functions focused and modular

ty and ruff are used for typing, linting and formatting. Ensure to check for any warnings from both of these:

pixi run ty check # For type checks
pixi run ruff check # For linting
pixi run ruff format # For formatting

Single files can be specified by just adding them to the command, e.g. pixi run ty check src/entropice/dashboard/app.py

Testing

Run tests for specific modules:

pixi run pytest

When adding features, include tests that verify:

• Correct handling of geospatial coordinates and projections
• Proper aggregation to grid cells
• Data integrity through pipeline stages

Submitting Changes

Pull Request Process

1. Branch: Create a feature branch from main
2. Commit: Write clear, descriptive commit messages
3. Test: Verify your changes don't break existing functionality
4. Document: Update relevant docstrings and documentation
5. PR: Submit a pull request with a clear description of changes

Commit Messages

• Use present tense: "Add feature" not "Added feature"
• Keep first line under 72 characters

Notebooks

• Notebooks in notebooks/ are for exploration and validation, they are not commited to git
• Keep production code in src/entropice/

Dashboard Development

Run the dashboard locally:

pixi run dashboard

Dashboard code is in src/entropice/dashboard/ with modular pages and plotting utilities.

Questions?

For questions about the architecture, see ARCHITECTURE.md. For scientific background, see README.md.