Metadata-Version: 2.4
Name: rustylab
Version: 0.2.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
License-File: LICENSE
Summary: RustyLab is a high‑performance scientific computing and machine learning library for Python, powered by a pure Rust core and exposed through PyO3.
Keywords: rustylab,rust,statistic,modeling,scientific,distribution,data,performance
Author-email: esuriddick <77727062+esuriddick@users.noreply.github.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Project-URL: Homepage, https://codeberg.org/esuriddick/rustylab
Project-URL: Issues, https://codeberg.org/esuriddick/rustylab/issues

<p align="center">
<img src="https://codeberg.org/esuriddick/rustylab/raw/branch/main/images/banner.jpg" alt="RustyLab" width="100%">
</p>

<p align="center">
  <img src="https://codeberg.org/esuriddick/rustylab/actions/workflows/num_acc_testing.yml/badge.svg" alt="Numerical Accuracy Testing">
  <a href="https://pypi.org/project/rustylab/">
    <img src="https://img.shields.io/pypi/v/rustylab" alt="PyPI version">
  </a>
  <a href="https://codeberg.org/esuriddick/rustylab/src/branch/main/LICENSE">
    <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
  </a>
</p>

> 🚧 RustyLab is under active development and its functionality is subject to change.

**RustyLab** is a high-performance scientific computing and machine learning library for Python, written entirely in **Rust**.

It aims to unify the core functionality of **SciPy**, **statsmodels**, and **scikit-learn** into a single, cohesive Python library with a strong focus on **speed**, **safety**, and **ergonomics**.

RustyLab is built in Rust and exposed to Python using **PyO3** and **maturin**, combining Rust’s performance with Python’s ease of use.

---

## 🚀 Why RustyLab?

The Python scientific ecosystem is powerful, but fragmented:

- Numerical routines live in **SciPy**;
- Statistical modelling in **statsmodels**;
- Machine learning in **scikit-learn**;
- Performance is built on a long-evolving foundation of native implementations and Python APIs.

RustyLab takes a different approach:

- **Pure Rust core** - memory safe, fast, and modern;
- **Polars-native data model** - designed for full compatibility with Polars;
- **Unified API** - statistics, optimization, and ML under one roof;
- **Python bindings** - no compromises in usability;
- **Performance by default** - zero-cost abstractions and parallelism;
- **Safe & predictable** - fewer runtime surprises.
- **Auditable source** - all function implementations are readily accessible, with [Wiki](https://codeberg.org/esuriddick/rustylab/wiki) references pointing to the exact code locations.

## 📦 Quickstart
Install the latest release of **RustyLab** Python client using `pip`:

```bash
pip install rustylab
```

Once installed, you can import the **RustyLab** library, any of its modules, or individual functions:

```bash
>>> import rustylab                     # Import the full library
>>> rustylab.special.beta(0.5, 0.5)

>>> from rustylab import special        # Import a specific module
>>> special.beta(0.5, 0.5)

>>> from rustylab.special import beta   # Import a function directly
>>> beta(0.5, 0.5)
```

## 📏 Numerical Accuracy

RustyLab is designed to deliver **highly accurate and reproducible numerical results**. In practice, this means that values produced by RustyLab typically agree with trusted reference implementations to approximately **13–15 significant decimal digits** (≈ 99.999999999999% accuracy, where relative error is meaningful, or with a difference smaller or equal to 1e-15). This level of precision is consistent with the practical limits of double‑precision (f64) floating‑point arithmetic.

To validate this level of accuracy:

- Outputs are tested using a **combination of exact equality checks** (where results are mathematically and numerically identical) **and tolerance‑based comparisons** using `pytest.approx`.
- When tolerance‑based checks are applied, the following strict thresholds are used:
  - Relative tolerance (rel): 1e-12
  - Absolute tolerance (abs): 1e-15

When tolerance‑based checks are used, both **relative** and **absolute** tolerances are applied simultaneously, following the semantics of `pytest.approx`: a comparison passes if **either** the relative error or the absolute error is within the specified bounds. In practice, this means that values with a meaningful scale are validated to many significant digits via the relative tolerance, while near‑zero or scale‑free quantities are validated via a strict absolute error bound. In all cases, the tolerances are chosen to reflect the limits of double‑precision floating‑point arithmetic and to ensure numerically correct results.

In addition, **every RustyLab function is systematically benchmarked against a trusted Python alternative** (such as NumPy, SciPy, or equivalent reference implementations). This ensures that:

- Numerical results closely match established Python scientific computing standards.
- Edge cases, including near‑zero values, very large magnitudes, and numerically sensitive operations, are handled consistently.
- Any deviations from reference implementations are intentional, well‑understood, and documented.

By combining high‑precision testing, exact checks where appropriate, strict absolute and relative error bounds, and direct comparison against well‑known Python libraries, **RustyLab provides transparent and verifiable numerical accuracy** suitable for both general‑purpose computation and demanding scientific workloads.

## 📚 Documentation & Module Reference

RustyLab’s full API documentation is maintained in the project's **Wiki**, which includes:

- A structured overview of all available modules.
- Documentation strings for every public function.
- Direct links to the corresponding Rust source files.
- Usage examples.

Explore the documentation here:  
👉 **RustyLab Wiki** — https://codeberg.org/esuriddick/rustylab/wiki

The Wiki is continuously updated as new features are added, making it the best place to understand the library’s capabilities.

