Metadata-Version: 2.5
Name: stochx
Version: 0.2.0
Summary: A Python library for stochastic-process analysis, simulation, and finite-probability objects.
Project-URL: Homepage, https://github.com/Faycal214/stochx
Project-URL: Documentation, https://faycal214.github.io/stochx/
Project-URL: Repository, https://github.com/Faycal214/stochx
Project-URL: Issues, https://github.com/Faycal214/stochx/issues
Project-URL: Changelog, https://github.com/Faycal214/stochx/blob/main/CHANGELOG.md
Author-email: Alikacem Faycal <faycal213.dz@gmail.com>
License: MIT
License-File: LICENSE
Keywords: Poisson process,birth-death process,conditional expectation,continuous-time Markov chains,discrete-time Markov chains,martingales,probability,stochastic processes,stochastic simulation,stopping times,uniformization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Description-Content-Type: text/markdown

# StochX

[![CI](https://github.com/Faycal214/stochx/actions/workflows/test.yml/badge.svg)](https://github.com/Faycal214/stochx/actions/workflows/test.yml)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-1081C2?style=flat)](https://faycal214.github.io/stochx/)
[![Python](https://img.shields.io/badge/python-3.10%2B-1081C2?style=flat)](https://www.python.org/)
[![License](https://img.shields.io/github/license/Faycal214/stochx?style=flat)](LICENSE)

StochX is a lightweight Python library for turning stochastic-process mathematics into executable, validated, and testable objects.

It is designed around a simple idea: each mathematical object should have a clear Python representation, a predictable API, numerical validation, and runnable examples.

## What makes StochX different

StochX is not limited to discrete-time Markov chains. Its public stochastic API is organized around several connected mathematical objects:

| Area | Main objects |
|---|---|
| Discrete-time Markov chains | `MarkovChain` |
| Poisson processes | `PoissonProcess`, `NonHomogeneousPoissonProcess` |
| Continuous-time Markov chains | `ContinuousTimeMarkovChain`, `CTMCPath` |
| Birth-death processes | `BirthDeathProcess` |
| Finite probability spaces | `FiniteProbabilitySpace`, `RandomVariable`, `Partition` |
| Conditional expectation | `FiniteProbabilitySpace`, `RandomVariable` |
| Filtrations and martingales | `Filtration`, `Martingale`, `StoppingTime`, `StoppedProcess` |

Two features are particularly central to the library:

- **CTMC numerical flexibility:** transition probabilities can be evaluated using the matrix-exponential route or a uniformization implementation.
- **Mathematical continuity:** finite conditional expectation, filtrations, martingales, and stopping times are first-class public objects rather than separate utilities.

## Installation

```bash
python -m pip install stochx
```

For development:

```bash
python -m pip install -e ".[dev]"
```

For documentation development:

```bash
python -m pip install -e ".[docs]"
mkdocs serve
```

## Quick start

### Discrete-time Markov chain

```python
import numpy as np
from stochx.stochastic import MarkovChain, empirical_state_frequencies

P = [
    [0.7, 0.3],
    [0.4, 0.6],
]

chain = MarkovChain(P, states=["A", "B"])

print(chain.n_step_transition(5))
print(chain.stationary_distribution())

path = chain.simulate(
    10_000,
    initial_state="A",
    rng=np.random.default_rng(0),
)
print(empirical_state_frequencies(path, chain.states))
```

### Continuous-time Markov chain

```python
from stochx.stochastic import ContinuousTimeMarkovChain

Q = [
    [-2.0, 2.0],
    [1.0, -1.0],
]

chain = ContinuousTimeMarkovChain(Q, states=["A", "B"])

print(chain.transition_matrix(2.0))
print(chain.transition_matrix_at(2.0, method="uniformization"))
```

## Public API

The public stochastic namespace is available from `stochx.stochastic`:

```python
from stochx.stochastic import (
    BirthDeathProcess,
    CTMCPath,
    ContinuousTimeMarkovChain,
    FiniteProbabilitySpace,
    Filtration,
    MarkovChain,
    Martingale,
    NonHomogeneousPoissonProcess,
    Partition,
    PoissonProcess,
    RandomVariable,
    StoppedProcess,
    StoppingTime,
    empirical_state_frequencies,
)
```

The complete reference is maintained in the [API documentation](https://faycal214.github.io/stochx/).

## Examples

Every major mathematical area has a runnable example, and `examples/07_api_operations.py` provides a broader public-API gallery.

```text
examples/
├── 01_discrete_markov_chain.py
├── 02_poisson_process.py
├── 03_continuous_markov_chain.py
├── 04_birth_death_process.py
├── 05_conditional_expectation.py
├── 06_martingale.py
└── 07_api_operations.py
```

The CI suite executes every `examples/*.py` file.

## Documentation

The documentation site separates three concerns:

- **Course material** for the mathematical development.
- **API Reference** for Python classes, properties, methods, validation rules, and examples.
- **Worked Examples** for end-to-end executable usage.

Start at the [documentation site](https://faycal214.github.io/stochx/).

## Development and quality gates

The repository uses GitHub Actions to run the stochastic test suite on Python 3.10, 3.11, and 3.12. The CI pipeline also checks:

- public API docstring coverage;
- API-reference page coverage;
- documentation structure;
- runnable example coverage;
- strict MkDocs builds.

Run the main stochastic suite locally with:

```bash
pytest -q tests/test_stochastic_*.py --disable-warnings
```

Run the release-surface checks with:

```bash
pytest -q \
  tests/test_docstring_coverage.py \
  tests/test_stochastic_example_coverage.py \
  tests/test_api_documentation_coverage.py \
  tests/test_documentation_coverage.py
```

Build the package locally before a release:

```bash
python -m build
python -m twine check dist/*
```

## Versioning

StochX follows semantic versioning for public API changes:

- `MAJOR` for incompatible public API changes;
- `MINOR` for backwards-compatible features;
- `PATCH` for backwards-compatible fixes.

The package version is defined once in `stochx/__init__.py` and is used by the build configuration, avoiding separate version values that can drift.

## Release status

StochX is currently in the early development stage. PyPI publishing is prepared through a tag-based release workflow, but releases are not automatically published until the repository's PyPI trusted publisher is configured.

## License

MIT
