Metadata-Version: 2.4
Name: rustylab
Version: 0.3.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
Requires-Dist: polars>=1.43.2,<1.44.0
License-File: LICENSE
Summary: RustyLab is a high-performance scientific computing and machine learning library for Python, powered by a Rust core exposed through PyO3 and a native Polars expression API.
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
Project-URL: Wiki, https://codeberg.org/esuriddick/rustylab/wiki

<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, with its numerical core 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**, with a thin Python layer that offers the same routines as native **Polars expressions** - 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:

- **Rust numerical core** - memory safe, fast, and modern (i.e., the Python layer only builds expressions);
- **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)

>>> import polars as pl                 # Use the same routines as Polars expressions
>>> from rustylab import expr
>>> pl.DataFrame({"x": [0.0, 1.0, 2.0]}).with_columns(
...     pdf = expr.stats.norm.pdf("x")
... )
```

## 📏 Numerical Accuracy

RustyLab is designed to deliver **highly accurate and reproducible numerical results**. In practice, this means that values produced by RustyLab 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.

**RustyLab functions are systematically benchmarked against a trusted Python alternative**, such as mpmath, 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.

To validate this level of accuracy:

- Outputs are tested via **tolerance‑based comparisons** using `pytest.approx`.
- The tolerance‑based checks make use of the following strict thresholds:
  - Relative tolerance: 1e-12
  - Absolute tolerance: 1e-15

The tolerance‑based checks make use of both **relative** and **absolute** tolerances 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.

By combining high‑precision testing, 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.

