StochX

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:

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

python -m pip install stochx

For development:

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

For documentation development:

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

Quick start

Discrete-time Markov chain

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

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:

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.

Examples

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

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.

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:

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

Run the release-surface checks with:

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:

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