API Reference

Core abstractions for discrete-time stochastic processes.

class stochlab.core.Path(times: ~numpy.ndarray, states: ~numpy.ndarray, extras: dict[str, ~typing.Any] = <factory>)[source]

Bases: object

A single discrete-time sample path (X_0, X_1, …, X_T).

Represents one realization of a stochastic process over discrete time steps.

times

Time points, typically [0, 1, 2, …, T].

Type:: np.ndarray

states

State values at each time point (labels or indices).

Type:: np.ndarray

extras

Optional metadata (waiting times, payoffs, etc.).

Type:: dict[str, Any]

Examples

>>> times = np.array([0, 1, 2])
>>> states = np.array(["A", "B", "A"])
>>> path = Path(times=times, states=states)
>>> len(path)
3
>>> path[1]
'B'

extras: dict[str, Any]

states: ndarray

times: ndarray

class stochlab.core.SimulationResult(paths: list[~stochlab.core.simulation.Path], metadata: dict[str, ~typing.Any] = <factory>)[source]

Bases: object

Collection of sample paths with basic analysis methods.

Represents the output of a Monte Carlo simulation, containing multiple realizations of a stochastic process.

paths

Collection of sample paths from the simulation.

Type:: list[Path]

metadata

Optional information about the simulation (process name, seed, etc.).

Type:: dict[str, Any]

Examples

>>> path1 = Path(times=np.array([0, 1]), states=np.array(["A", "B"]))
>>> path2 = Path(times=np.array([0, 1]), states=np.array(["A", "A"]))
>>> result = SimulationResult(paths=[path1, path2])
>>> len(result)
2
>>> df = result.to_dataframe()
>>> result.state_distribution(t=1)
{'A': 0.5, 'B': 0.5}

metadata: dict[str, Any]

paths: list[Path]

state_distribution(t: int) → dict[Hashable, float][source]

Empirical distribution of states at time index t across all paths.

Parameters:: t (int) – Time index to analyze (0-based index into each Path).
Returns:: Mapping from state to empirical probability.
Return type:: dict[State, float]

to_dataframe() → DataFrame[source]

Convert simulation results to a pandas DataFrame.

Returns:: DataFrame with columns: - ‘path_id’ : int (which simulated path) - ‘t’ : int (time index, 0-based) - ‘time’ : Any (actual time value from Path.times) - ‘state’ : State (state label or index)
Return type:: pd.DataFrame

class stochlab.core.StateSpace(states: Sequence[Hashable], _index_map: Mapping[Hashable, int] | None = None)[source]

Bases: object

Finite state space S = {s₀, s₁, …, sₙ₋₁} with bijective label ↔ index mapping.

Provides the foundation for all discrete-time stochastic processes by managing the finite set of possible states and their integer representations.

Parameters:: states (Sequence[State]) – Ordered sequence of unique state labels (any hashable type).

states

The ordered state labels.

Type:: Sequence[State]

index_map

Read-only mapping from state label to integer index.

Type:: Mapping[State, int]

n_states

Number of states (alias for len(states)).

Type:: int

Examples

Basic usage:

>>> ss = StateSpace(["Bull", "Bear", "Sideways"])
>>> len(ss)
3
>>> ss.index("Bear")
1
>>> ss.state(0)
'Bull'
>>> "Bull" in ss
True

Complex state types:

>>> market_states = StateSpace([("Bull", "High"), ("Bull", "Low"), ("Bear", "High")])
>>> market_states.index(("Bear", "High"))
2

Mathematical Context

For a stochastic process (Xₜ)ₜ₌₀ᵀ, this class defines: - State space: S = {s₀, s₁, …, sₙ₋₁} - Bijection: φ: S → {0, 1, …, n-1} - Used for transition matrix indexing: P[i,j] = P(Xₜ₊₁ = sⱼ | Xₜ = sᵢ)

index(state: Hashable) → int[source]

Return the integer index corresponding to a state label.

Parameters:: state (State) – The state label to look up.
Returns:: The index in [0, n_states-1].
Return type:: int
Raises:: KeyError – If the state is not part of this StateSpace.

property index_map: Mapping[Hashable, int]

Mapping from state label -> integer index.

This is intended to be read-only. Do not mutate it.

property n_states: int: Explicit property for the number of states (alias of len(ss)).

state(idx: int) → Hashable[source]

Return the state label corresponding to an integer index.

Parameters:: idx (int) – Index in [0, n_states-1].
Returns:: The corresponding state label.
Return type:: State
Raises:: IndexError – If idx is out of range.

states: Sequence[Hashable]

class stochlab.core.StochasticProcess[source]

Bases: ABC

Abstract base class for discrete-time stochastic processes on a finite state space.

Any concrete model (Markov chain, queue, branching process, etc.) must:

expose its finite state_space,
implement sample_path to generate a single Path.

This gives a uniform interface that other components (Monte Carlo, analytics, reporting) can rely on.

abstractmethod sample_path(T: int, x0: Hashable | None = None, **kwargs: Any) → Path[source]

Generate a single discrete-time sample path (X_0, …, X_T).

Parameters:

T (int) – Horizon (number of time steps minus one). The returned path will have length T+1, with times typically [0, 1, …, T].
x0 (State, optional) – Optional initial state. If None, the process may use a default initial distribution or a default starting state.
**kwargs (Any) – Additional model-specific parameters for the simulation, if needed.

Returns:

The simulated path.

Return type:

Path

simulate_paths(n_paths: int, T: int, x0: Hashable | None = None, **kwargs: Any) → SimulationResult[source]

Generate multiple independent sample paths and wrap them in a SimulationResult.

This is a thin convenience wrapper around repeated calls to sample_path. More advanced Monte Carlo features (variance reduction, seeding strategies, parallelism, etc.) will live in a separate mc module.

Parameters:

n_paths (int) – Number of independent paths to simulate. Must be >= 1.
T (int) – Horizon for each path (see sample_path).
x0 (State, optional) – Optional common initial state for all paths.
**kwargs (Any) – Additional model-specific arguments forwarded to sample_path.

Returns:

Collection of simulated paths and basic metadata.

Return type:

SimulationResult

abstract property state_space: StateSpace

The finite state space on which this process evolves.

Returns:: The finite set of allowed states.
Return type:: StateSpace

Concrete stochastic process models.

class stochlab.models.MM1Queue(arrival_rate: float, service_rate: float, max_queue_length: int)[source]

Bases: StochasticProcess

Single-server queue with Poisson arrivals and exponential service times.

The state is the queue length (including any job in service) capped at max_queue_length, which provides the finite state space required by the core architecture. If the simulated queue would exceed this cap, a RuntimeError is raised, signalling that the user should increase the cap.

sample_path(T: int, x0: Hashable | None = None, **kwargs: Any) → Path[source]

Simulate T event transitions of the embedded discrete-time chain.

Times in the returned Path correspond to event epochs and are spaced by exponential inter-arrival times with rate λ + μ · 𝟙{queue>0}.

property state_space: StateSpace: Finite state space {0, 1, …, max_queue_length}.

class stochlab.models.MarkovChain(state_space: StateSpace, P: ndarray, initial_dist: ndarray | None = None)[source]

Bases: StochasticProcess

Finite-state, time-homogeneous Markov chain.

Parameters:

state_space (StateSpace) – Finite set of states.
P (np.ndarray) – Transition matrix of shape (n_states, n_states). P[i, j] = P(X_{t+1} = state_j | X_t = state_i).
initial_dist (np.ndarray | None) – Optional initial distribution over states (length n_states). If None, a default (e.g. unit mass on first state) is used.

classmethod from_transition_matrix(states: Sequence[Hashable], P: ndarray, initial_dist: ndarray | None = None) → MarkovChain[source]: Build a MarkovChain directly from states and a transition matrix.

sample_path(T: int, x0: Hashable | None = None, **kwargs: Any) → Path[source]: Generate a single sample path (X_0, …, X_T) from the Markov chain.

property state_space: StateSpace: The finite state space for this Markov chain.

class stochlab.models.RandomWalk(lower_bound: int, upper_bound: int, p: float = 0.5)[source]

Bases: StochasticProcess

Simple random walk on integers [lower_bound, upper_bound] with reflecting boundaries.

At each step: move up with probability p, down with probability 1-p. At boundaries: must move back into interior.

sample_path(T: int, x0: Hashable | None = None, **kwargs: Any) → Path[source]

Generate a single discrete-time sample path (X_0, …, X_T).

Parameters:

T (int) – Horizon (number of time steps minus one). The returned path will have length T+1, with times typically [0, 1, …, T].
x0 (State, optional) – Optional initial state. If None, the process may use a default initial distribution or a default starting state.
**kwargs (Any) – Additional model-specific parameters for the simulation, if needed.

Returns:

The simulated path.

Return type:

Path

property state_space: StateSpace

The finite state space on which this process evolves.

Returns:: The finite set of allowed states.
Return type:: StateSpace