Metadata-Version: 2.5
Name: mocaco
Version: 0.3.0
Summary: Convergence analysis for Monte Carlo series — works with Polars DataFrames
Author-email: Álvaro Esteban Muñoz <em.alvaro.l@gmail.com>
License: LGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: numpy>=2.5.3
Requires-Dist: polars>=1.44.2
Requires-Dist: pydantic>=2.13.5
Requires-Dist: rich>=15.0.0
Requires-Dist: scipy>=1.18.1
Provides-Extra: pandas
Requires-Dist: pandas>=3.0.6; extra == 'pandas'
Requires-Dist: pyarrow>=26.0.0; extra == 'pandas'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.11.2; extra == 'plot'
Description-Content-Type: text/markdown

# mocaco

[![CI/CD & Tests](https://github.com/emalvarol/mocaco/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/emalvarol/mocaco/actions/workflows/ci-cd.yml)
![PyPi Version](https://img.shields.io/github/v/tag/emalvarol/mocaco?sort=semver&filter=v*.*.*&label=version)
![Python Versions](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)
[![codecov](https://codecov.io/gh/emalvarol/mocaco/graph/badge.svg)](https://codecov.io/gh/emalvarol/mocaco)
![License: LGPL](https://img.shields.io/badge/license-LGPL-blue)


<p align="center">
  <img src="https://raw.githubusercontent.com/emalvarol/mocaco/main/docs/assets/mocaco_logo_v2.svg" alt="mocaco logo" width="200"/>
</p>

Convergence analysis for Monte Carlo series using Polars DataFrames for fastest Python performance.
The library provides a simple API for applying different convergence and stopping criteria to Monte Carlo simulation results as well as a simple contribution approach (only one .py needed to add a new convergence criterion).

## Quickstart

```python
import polars as pl
import mocaco as mcc

# Prepare your Monte Carlo samples
df = pl.DataFrame({"it": range(1000), "value": your_samples})

# Create a normalized sample frame
samples = mcc.samples(df, it_col="it", target_col="value")

# Run a convergence criterion
result = mcc.convergence.clt_uni_abs(samples, threshold=0.01)

# Inspect results
print(result.is_converged)  # True/False
print(result.estimate)  # Final cumulative mean
print(result.error)  # Final CLT-based absolute error
print(result.n)  # Number of samples
# and more...
```

## API Overview

| Function | Description |
|----------|-------------|
| `mcc.samples(df, it_col, target_col)` | Create a normalized sample frame from a Polars DataFrame |
| `mcc.convergence(samples, method="...")` | Generic invocation of any registered criterion |
| `mcc.convergence.clt_uni_abs(samples, ...)` | Typed invocation of a specific criterion |
| `mcc.methods()` | List all registered convergence criteria |
| `mcc.describe("clt_uni_abs")` | Get metadata and parameter info for a criterion |

## Available Methods

- [`clt_uni_abs`] — CLT-based absolute error threshold

## Documentation and Changes

Full documentation is available at (https://emalvarol.github.io/mocaco/), in the `docs/` directory, or can be built locally with:

```bash
mkdocs serve
```

Changes and new features are available at (https://github.com/emalvarol/mocaco/blob/main/CHANGELOG.md)

## Installation (Developers)

### Environment

Create the virtual environment and install the project in editable mode with `uv`:

```bash
uv venv
uv sync
uv pip install -e .
```

If it is needed to remove an old environment:

```bash
Remove-Item -Recurse -Force .venv
```

### ruff
```bash
uv run ruff check --fix . && uv run ruff format .
```

### mypy
```bash
uv run mypy src/
```

### pytest
```bash
uv run pytest
```
