Metadata-Version: 2.4
Name: debrispy
Version: 0.1.0
Summary: Debris disc surface density modeling and Monte Carlo sampling.
Author-email: Deniz Akansoy <da619@cam.ac.uk>
License: MIT License
        
        Copyright (c) 2025 Deniz Akansoy
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: astronomy,astrophysics,debris discs,debris disks,surface density,monte carlo,orbital dynamics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.4
Requires-Dist: scipy>=1.12.0
Requires-Dist: matplotlib>=3.7.5
Requires-Dist: tqdm>=4.67.1
Requires-Dist: fast_histogram>=0.14
Requires-Dist: joblib>=1.5.1
Requires-Dist: adaptive>=1.3.2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: notebook; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Dynamic: license-file

# **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 ([see full documentation](#4-documentation) for usage and API reference).

![Demo](assets/demo.gif)

---

## **Table of Contents**

1. [Repository Structure](#1-repository-structure)  
2. [Installation](#2-installation)  
3. [Dependencies](#3-dependencies)  
4. [Documentation](#4-documentation)  
5. [Example Notebooks](#5-example-notebooks)  
6. [Testing](#6-testing)

---

## **1. Repository Structure**

Breakdown of the repository's folder structure and its purpose:

- **`debrispy/`**  
  Core package code, including all class implementations.

- **`tests/`**  
  Contains a test suite using `pytest`. See [Section 6](#6-testing) for further information.

- **`examples/`**  
  Example files (both `.py` and `.ipynb`) showcasing how to use the package.

- **`docs/`**  
  Contains the full Sphinx-generated documentation (both the source files and built html files). The documentation can easily be accessed online without requiring manual building or download. See [Section 4](#4-documentation) for viewing instructions.


---

## **2. Installation**

> **Important:** DebrisPy requires **Python 3.8 or higher**.

To install the `DebrisPy` package locally:

1. Clone the repository from the GitLab directory:


```bash
git clone <repository-url>
cd DebrisPy  # Navigate to the parent directory
```

2. Install the python package:


```bash
pip install . 
```

---

## **3. Dependencies**

All required dependencies are automatically installed when installing the package via `pip`.

**Numerical and Scientific Computing**

- `numpy`: fast array manipulation and vectorised math
- `scipy`: numerical integration, special functions, and interpolation
- `fast_histogram`: high-performance 1D/2D histogramming
- `adaptive`: optional grid refinement and adaptive sampling
- `matplotlib`: 1D and 2D surface density plotting
- `tqdm`: progress bars for long-running sampling routines
- `joblib`: parallel execution for kernel computations


---

## **4. Documentation**

The documentation contains information on each class within the package, and provides examples on various use cases. This can be accessed online via debrispy.readthedocs.io

The source files for the documentation are also provided in the main repository.



---

## **5. Example Notebooks**

This repository includes a collection of Jupyter notebooks (found in the `notebooks` directory) that demonstrate how to use the DebrisPy package in practice. These are organised into two subdirectories:

- `docs_notebooks/`
These notebooks form the main section of the documentation. They are well-annotated, with clear, step-by-step examples showing how to initialise and use each of the core classes (e.g., SigmaA, Kernel, ASD, MonteCarlo).*We recommend looking through these notebooks before the others, as they provide the most accessible introduction to the package.*


- `report_notebooks/`
These notebooks were used to generate all figures and results shown in the MPhil report.
While not structured as tutorials, they are still lightly commented and provide insight into how the package can be applied in research scenarios, including benchmarking, model comparison, and analysis of specific case studies.

---

## **6. Tests**

This package includes a set of automated tests using the `pytest` framework, located in the `tests/` directory.

> `pytest` is a lightweight Python framework for writing and running test functions to automatically verify that code behaves as expected.

After installing the package, we recommend running the test suite to ensure that the package has been installed correctly. This can be run from the root directory, by executing:

```bash
pytest tests/
```

---

For any further questions regarding usage, please see the documentation. Feel free to contact Deniz Akansoy via da619@cam.ac.uk, any feedback would be greately appreciated.
