Contributing to PyCauset

Thank you for your interest in contributing to PyCauset! We welcome contributions from the community, whether it's fixing bugs, adding new features, or improving documentation.

Before you start, read the project protocols:

• project/protocols/
• Documentation Protocol

Getting Started

Prerequisites

To build PyCauset from source, you will need:

• Python 3.8+
• C++ Compiler:
  • Windows: Visual Studio 2022 (Desktop development with C++)
  • Linux: GCC or Clang
  • macOS: Xcode Command Line Tools
• CMake 3.15+
• CUDA Toolkit (Optional, for GPU support)

Setting Up the Development Environment

1. Clone the Repository:

   git clone https://github.com/BrorH/pycauset.git
   cd pycauset
   

2. Create a Virtual Environment:

   python -m venv .venv
   # Windows
   .venv\Scripts\Activate.ps1
   # Linux/macOS
   source .venv/bin/activate
   

3. Install from source (this builds the native extension via scikit-build-core):

   pip install -e .
   

Building the Project

We provide helper scripts to simplify the build process.

Windows

# Build Python extension and run tests
./build.ps1 -All

# Only build Python extension
./build.ps1 -Python

Linux/macOS

Recommended workflow:

pip install -e .

Running Tests

PyCauset has a comprehensive test suite covering both the C++ core and the Python interface.

Python Tests

pytest tests/python

C++ Unit Tests

If you built with CMake, you can run C++ tests via CTest from your build directory.

Coding Standards

C++

• Use C++17 features.
• Follow standard RAII principles.
• Use pybind11 for Python bindings.
• Keep headers in include/ and implementation in src/.

Python

• Follow PEP 8.
• Use type hints.
• Document all public functions and classes using Google-style docstrings.

Documentation

Documentation is written in Markdown and built with MkDocs.

Install documentation dependencies:

pip install -r requirements-docs.txt

If you are changing behavior, remember the docs checklist in Documentation Protocol.

# Serve documentation locally
mkdocs serve

Submitting a Pull Request

1. Fork the repository.
2. Create a new branch (git checkout -b feature/my-feature).
3. Commit your changes.
4. Push to the branch (git push origin feature/my-feature).
5. Open a Pull Request.

Please ensure all tests pass before submitting!