DebrisPy

A Python Package for Computing the Radial Profiles of Surface Density in Debris Discs

Welcome to DebrisPy — a lightweight package designed to compute the azimuthally averaged surface density (ASD) profiles in debris discs using both semi-analytical and Monte Carlo approaches.

---

Installation

1. The package can be installed via PyPI directly:

pip install debrispy

Important: DebrisPy requires Python 3.8 or higher.

2. For development, clone the repository and install in editable mode:

git clone https://github.com/DenizAkansoy/DebrisPy.git
cd DebrisPy
pip install -e .

---

Features

DebrisPy provides tools for:

• defining semi-major-axis surface-density profiles;
• specifying unique eccentricity profiles or eccentricity distributions;
• constructing eccentricity kernels for ASD calculations;
• computing azimuthally averaged surface-density profiles;
• validating and visualising results with Monte Carlo sampling;
• using built-in profiles or arbitrary user-defined functions;
• optional adaptive gridding, interpolation, and parallelisation for more demanding calculations.

Important: custom functions must be vectorised

User-supplied functions should be vectorised. DebrisPy evaluates many profiles and distributions on NumPy arrays, so scalar Python conditionals such as if/else will usually fail or behave incorrectly.

For example, avoid:

def bad_profile(a):
    if a < 50:
        return 0.0
    return a**-1

Use NumPy-aware operations instead:

import numpy as np

def good_profile(a):
    return np.where(a < 50, 0.0, a**-1)

Boolean masks and array arithmetic are also suitable.

---

Documentation

The full documentation is available online:

https://debrispy.readthedocs.io

The documentation includes worked examples, API references, implementation notes, and notebook-based tutorials.

The documentation source files are located in:

docs/source/

To build the documentation locally:

cd docs
make html
open build/html/index.html

---

Repository structure

debrispy/              Core package code
docs/source/           Sphinx documentation source
examples/              Example notebooks and scripts
tests/                 Test suite
assets/                README/demo assets

---

Examples

Example notebooks are provided in the examples/ directory. These demonstrate how to define input profiles, construct eccentricity kernels, compute ASD profiles, and compare semi-analytic calculations with Monte Carlo realisations.

---

Dependencies

Core dependencies are installed automatically when installing DebrisPy with:

pip install debrispy

These include:

• numpy
• scipy
• matplotlib
• fast_histogram
• adaptive
• tqdm
• joblib

Additional optional dependencies are needed for development, testing, and building the documentation.

For development and testing:

pip install -e ".[dev]"

This installs additional packages such as:

• pytest
• ipykernel
• notebook

For building the documentation locally:

pip install -e ".[docs]"

This installs additional packages such as:

• sphinx
• sphinx-rtd-theme
• myst-parser
• nbsphinx

Testing

After cloning the repository, the test suite can be run with:

pytest tests/

For development, install the package with the optional development dependencies:

pip install -e ".[dev]"
pytest tests/

---

Testing

To run the test suite, clone the repository and install the optional development dependencies:

git clone https://github.com/DenizAkansoy/DebrisPy.git
cd DebrisPy
pip install -e ".[dev]"
pytest tests/

---

Contact

For questions, bug reports, or feedback, please open an issue on GitHub or contact Deniz Akansoy at da619@cam.ac.uk.