### Get Steady States of MarkovChain

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Access the 'steady_states' property to retrieve the steady-state distributions of the Markov chain.

```console
>>> print(mc.steady_states)
[array([0.0, 0.0, 1.0, 0.0])]
```

--------------------------------

### Generate Gambler's Ruin Markov Chain

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Generates a gambler's ruin Markov chain with a specified size and win probability. Includes an example of simulating a scenario.

```python
from pydtmc import MarkovChain

# Create a gambler's ruin chain: 5 states, win probability 0.4
mc_gambler = MarkovChain.gamblers_ruin(5, w=0.4)
print(f"States: {mc_gambler.states}")
print(f"Is Absorbing: {mc_gambler.is_absorbing}")  # True

# Simulate a gambler's ruin scenario
walk = mc_gambler.simulate(100, initial_state='3', seed=42)
print(f"Final state: {walk[-1]}")  # Will be '1' (broke) or '5' (rich)
```

--------------------------------

### Plot HiddenMarkovModel Graph

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Plot the state transition graph of a HiddenMarkovModel. Requires Matplotlib to be installed and interactive mode enabled. The DPI can be adjusted.

```console
>>> plot_graph(hmm, dpi=300)
```

--------------------------------

### Install PyDTMC using pip

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Install the PyDTMC library using pip. Upgrade to the latest version if already installed.

```sh
$ pip install PyDTMC
$ pip install --upgrade PyDTMC
```

--------------------------------

### Perform Step-by-Step Simulation

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Use the next method to compute individual transitions, suitable for interactive or iterative analysis.

```python
from pydtmc import MarkovChain

p = [[0.2, 0.7, 0.0, 0.1],
     [0.0, 0.6, 0.3, 0.1],
     [0.0, 0.0, 1.0, 0.0],
     [0.5, 0.0, 0.5, 0.0]]
mc = MarkovChain(p, ['A', 'B', 'C', 'D'])

# Perform a step-by-step random walk
sequence = ["A"]
for i in range(1, 11):
    current_state = sequence[-1]
    next_state = mc.next(current_state, seed=32+i)
    print(f'{i}) {current_state} -> {next_state}')
    sequence.append(next_state)

# Output:
# 1) A -> B
# 2) B -> B
# 3) B -> C
# 4) C -> C
# ...
```

--------------------------------

### Initialize HiddenMarkovModel

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Create an HMM with transition matrix, emission matrix, states, and symbols. Prints model details and properties.

```python
from pydtmc import HiddenMarkovModel

# Create an HMM with transition matrix, emission matrix, states, and symbols
p = [[0.4, 0.6], [0.8, 0.2]]  # State transitions
e = [[0.5, 0.0, 0.0, 0.5], [0.2, 0.2, 0.2, 0.4]]  # Emission probabilities
states = ['A', 'B']
symbols = ['H1', 'H2', 'H3', 'H4']

hmm = HiddenMarkovModel(p, e, states, symbols)
print(hmm)
# Output:
# HIDDEN MARKOV MODEL
#  STATES:  2
#  SYMBOLS: 4
#  ERGODIC: NO
#  REGULAR: NO

print(f"States: {hmm.states}")  # ['A', 'B']
print(f"Symbols: {hmm.symbols}")  # ['H1', 'H2', 'H3', 'H4']
print(f"Is Ergodic: {hmm.is_ergodic}")  # False
```

--------------------------------

### Install PyDTMC from GitHub using pip

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Install PyDTMC directly from its GitHub repository using pip. This is useful for installing from a tarball or a git+ URL.

```sh
$ pip install https://github.com/TommasoBelluzzo/PyDTMC/tarball/master
$ pip install --upgrade https://github.com/TommasoBelluzzo/PyDTMC/tarball/master

$ pip install git+https://github.com/TommasoBelluzzo/PyDTMC.git#egg=PyDTMC
$ pip install --upgrade git+https://github.com/TommasoBelluzzo/PyDTMC.git#egg=PyDTMC
```

--------------------------------

### next(initial_state, output_index, seed)

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain_methods_instance.md

Simulates a single step in a random walk on the Markov chain.

```APIDOC
## next(initial_state, output_index, seed)

### Description
The method simulates a single step in a random walk.

### Method
POST

### Endpoint
/api/markovchain/next

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **initial_state** (int | str) - Required - The initial state.
- **output_index** (bool) - Optional - A boolean indicating whether to output the state index. Defaults to False.
- **seed** (int | None) - Optional - A seed to be used as RNG initializer for reproducibility purposes.

### Request Example
```json
{
  "initial_state": 0,
  "output_index": true,
  "seed": 12345
}
```

### Response
#### Success Response (200)
- **int | str**: The next state (index or label).

#### Response Example
```json
{
  "next_state": 1
}
```

### Error Handling
- **ValidationError**: If any input argument is not compliant.
```

--------------------------------

### Install PyDTMC using Conda

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Install PyDTMC using Conda from the conda-forge channel or a specific user channel. Includes commands for updating the package.

```sh
$ conda install -c conda-forge pydtmc
$ conda update -c conda-forge pydtmc

$ conda install -c tommasobelluzzo pydtmc
$ conda update -c tommasobelluzzo pydtmc
```

--------------------------------

### Redistribute States

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Calculates the state distribution over time starting from an initial state or distribution.

```python
from pydtmc import MarkovChain
import numpy as np

p = [[0.2, 0.7, 0.0, 0.1],
     [0.0, 0.6, 0.3, 0.1],
     [0.0, 0.0, 1.0, 0.0],
     [0.5, 0.0, 0.5, 0.0]]
mc = MarkovChain(p, ['A', 'B', 'C', 'D'])

# Redistribute starting from uniform distribution over 5 steps
distributions = mc.redistribute(5, output_last=False)
for i, dist in enumerate(distributions):
    print(f"Step {i}: {np.round(dist, 4)}")

# Redistribute starting from a specific state
final_dist = mc.redistribute(10, initial_status='A', output_last=True)
print(f"Final distribution: {np.round(final_dist, 4)}")
```

--------------------------------

### Instantiate and Print MarkovChain

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Instantiate a MarkovChain object with a transition probability matrix and state labels, then print its summary.

```console
>>> p = [[0.2, 0.7, 0.0, 0.1], [0.0, 0.6, 0.3, 0.1], [0.0, 0.0, 1.0, 0.0], [0.5, 0.0, 0.5, 0.0]]
>>> mc = MarkovChain(p, ['A', 'B', 'C', 'D'])
>>> print(mc)
```

--------------------------------

### MarkovChain Class Initialization and Properties

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Demonstrates how to initialize a MarkovChain object and access its fundamental properties.

```APIDOC
## MarkovChain Class

### Description
The `MarkovChain` class defines a discrete-time Markov chain with a given transition matrix and optional state labels. It provides properties for analyzing chain structure (ergodicity, periodicity, reversibility) and methods for computing probabilities, simulating walks, and performing various Markov chain operations.

### Method
`MarkovChain(transition_matrix, state_labels=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **transition_matrix** (list of lists or numpy.ndarray) - Required - The transition probability matrix.
- **state_labels** (list of strings, optional) - Optional - Labels for the states.

### Request Example
```python
from pydtmc import MarkovChain

p = [[0.2, 0.7, 0.0, 0.1],
     [0.0, 0.6, 0.3, 0.1],
     [0.0, 0.0, 1.0, 0.0],
     [0.5, 0.0, 0.5, 0.0]]
pc = MarkovChain(p, ['A', 'B', 'C', 'D'])
```

### Response
#### Success Response (200)
- **mc** (MarkovChain object) - An initialized MarkovChain object.

#### Response Example
```
DISCRETE-TIME MARKOV CHAIN
 SIZE:           4
 RANK:           4
 CLASSES:        2
  > RECURRENT:   1
  > TRANSIENT:   1
 ERGODIC:        NO
  > APERIODIC:   YES
  > IRREDUCIBLE: NO
 ABSORBING:      YES
 MONOTONE:       NO
 REGULAR:        NO
 REVERSIBLE:     YES
 SYMMETRIC:      NO
```

### Properties
- **states** (list) - Returns the list of state labels.
- **size** (int) - Returns the number of states.
- **is_ergodic** (bool) - Returns True if the chain is ergodic.
- **is_absorbing** (bool) - Returns True if the chain is absorbing.
- **recurrent_states** (list) - Returns a list of recurrent states.
- **transient_states** (list) - Returns a list of transient states.
- **pi** (numpy.ndarray) - Returns the stationary distribution.
```

--------------------------------

### Get Entropy Rate of MarkovChain

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Access the 'entropy_rate' property to retrieve the entropy rate of the Markov chain.

```console
>>> print(mc.entropy_rate)
0.0
```

--------------------------------

### Get Kemeny Constant of MarkovChain

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Access the 'kemeny_constant' property to retrieve the Kemeny constant of the Markov chain.

```console
>>> print(mc.kemeny_constant)
5.547169811320755
```

--------------------------------

### Instantiate HiddenMarkovModel

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Instantiate the HiddenMarkovModel class with transition probabilities, emission probabilities, states, and symbols. Ensure the input dimensions are consistent.

```console
>>> p = [[0.4, 0.6], [0.8, 0.2]]
>>> states = ['A', 'B']
>>> e = [[0.5, 0.0, 0.0, 0.5], [0.2, 0.2, 0.2, 0.4]]
>>> symbols = ['H1', 'H2', 'H3', 'H4']
>>> hmm = HiddenMarkovModel(p, e, states, symbols)
>>> print(hmm)
```

--------------------------------

### Get Fundamental Matrix of MarkovChain

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Access the 'fundamental_matrix' property to obtain the fundamental matrix of the Markov chain.

```console
>>> print(mc.fundamental_matrix)
[[1.50943396, 2.64150943, 0.41509434]
 [0.18867925, 2.83018868, 0.30188679]
 [0.75471698, 1.32075472, 1.20754717]]
```

--------------------------------

### Initialize and Analyze MarkovChain

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Create a MarkovChain instance from a transition matrix and state labels to access structural properties like ergodicity and stationary distributions.

```python
from pydtmc import MarkovChain

# Create a Markov chain from a transition matrix
p = [[0.2, 0.7, 0.0, 0.1],
     [0.0, 0.6, 0.3, 0.1],
     [0.0, 0.0, 1.0, 0.0],
     [0.5, 0.0, 0.5, 0.0]]
mc = MarkovChain(p, ['A', 'B', 'C', 'D'])

# Display chain summary
print(mc)
# Output:
# DISCRETE-TIME MARKOV CHAIN
#  SIZE:           4
#  RANK:           4
#  CLASSES:        2
#   > RECURRENT:   1
#   > TRANSIENT:   1
#  ERGODIC:        NO
#   > APERIODIC:   YES
#   > IRREDUCIBLE: NO
#  ABSORBING:      YES
#  MONOTONE:       NO
#  REGULAR:        NO
#  REVERSIBLE:     YES
#  SYMMETRIC:      NO

# Access chain properties
print(f"States: {mc.states}")  # ['A', 'B', 'C', 'D']
print(f"Size: {mc.size}")  # 4
print(f"Is Ergodic: {mc.is_ergodic}")  # False
print(f"Is Absorbing: {mc.is_absorbing}")  # True
print(f"Recurrent States: {mc.recurrent_states}")  # ['C']
print(f"Transient States: {mc.transient_states}")  # ['A', 'B', 'D']
print(f"Stationary Distribution: {mc.pi}")  # [array([0., 0., 1., 0.])]
```

--------------------------------

### Simulate and Track MarkovChain Sequence Step-by-Step

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Manually simulate a sequence of states using the 'next' method in a loop, tracking the progression.

```console
>>> sequence = ["A"]
>>> for i in range(1, 11):
...     current_state = sequence[-1]
...     next_state = mc.next(current_state, seed=32)
...     print((' ' if i < 10 else '') + f'{i}) {current_state} -> {next_state}')
...     sequence.append(next_state)
 1) A -> B
 2) B -> C
 3) C -> C
 4) C -> C
 5) C -> C
 6) C -> C
 7) C -> C
 8) C -> C
 9) C -> C
10) C -> C
```

--------------------------------

### next

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/hidden_markov_model_methods_instance.md

Simulates a single step in a random walk.

```APIDOC
## next

### Description
The method simulates a single step in a random walk.

### Parameters
- **initial_state** (int | str) - Required - The initial state.
- **target** (str) - Optional - 'state', 'symbol', or 'both'.
- **output_index** (bool) - Optional - Whether to output the state index.
- **seed** (int) - Optional - RNG initializer for reproducibility.

### Response
- **Returns** (int | str | Tuple[int, int] | Tuple[str, str]) - The result of the random walk step.
```

--------------------------------

### Get Transient States of MarkovChain

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Access the 'transient_states' property to retrieve a list of transient states in the Markov chain.

```console
>>> print(mc.transient_states)
['A', 'B', 'D']
```

--------------------------------

### HiddenMarkovModel Initialization

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/hidden_markov_model.md

Defines a hidden Markov model with the given transition and emission matrices.

```APIDOC
## HiddenMarkovModel Initialization

### Description
Defines a hidden Markov model with the given transition and emission matrices.

### Parameters
- **p** (matrix) - Required - The transition matrix.
- **e** (matrix) - Required - The emission matrix.
- **states** (list) - Optional - The name of each state (if omitted, an increasing sequence of integers starting at 1 with prefix P).
- **symbols** (list) - Optional - The name of each symbol (if omitted, an increasing sequence of integers starting at 1 with prefix E).

### Errors
- **ValidationError** - Raised if any input argument is not compliant.
```

--------------------------------

### Get Recurrent States of MarkovChain

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Access the 'recurrent_states' property to retrieve a list of recurrent states in the Markov chain.

```console
>>> print(mc.recurrent_states)
['C']
```

--------------------------------

### Simulate Random Walks

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Generate random walks using the simulate method, supporting early stopping conditions and index-based output.

```python
from pydtmc import MarkovChain

p = [[0.2, 0.7, 0.0, 0.1],
     [0.0, 0.6, 0.3, 0.1],
     [0.0, 0.0, 1.0, 0.0],
     [0.5, 0.0, 0.5, 0.0]]
mc = MarkovChain(p, ['A', 'B', 'C', 'D'])

# Simulate 10 steps starting from state 'D'
sequence = mc.simulate(10, initial_state='D', seed=32)
print(sequence)
# Output: ['D', 'A', 'B', 'B', 'C', 'C', 'C', 'C', 'C', 'C', 'C']

# Simulate with early stopping when reaching state 'C'
sequence_stop = mc.simulate(20, initial_state='A', final_state='C', seed=42)
print(sequence_stop)
# Output: ['A', 'B', 'B', 'C']

# Output indices instead of state names
indices = mc.simulate(5, initial_state='A', output_indices=True, seed=10)
print(indices)
# Output: [0, 1, 2, 2, 2, 2]
```

--------------------------------

### Fit Markov Chain from Sequence

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Estimates transition probabilities from an observed sequence of states using MLE or MAP.

```python
from pydtmc import MarkovChain

# Observed sequence of states
sequence = ['A', 'B', 'B', 'C', 'A', 'B', 'C', 'C', 'A', 'B', 'A']
possible_states = ['A', 'B', 'C']

# Fit using MLE
mc_mle = MarkovChain.fit_sequence('mle', possible_states, sequence)
print("MLE Transition Matrix:")
print(mc_mle.p)

# Fit using MAP with default prior
mc_map = MarkovChain.fit_sequence('map', possible_states, sequence)
print("MAP Transition Matrix:")
print(mc_map.p)
```

--------------------------------

### Create Markov Chain from Dictionary

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Initializes a Markov chain using a dictionary mapping state pairs to transition probabilities.

```python
from pydtmc import MarkovChain
```

--------------------------------

### simulate

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain_methods_instance.md

Simulates a random walk of the given number of steps.

```APIDOC
## simulate

### Description
The method simulates a random walk of the given number of steps.

### Parameters
- **steps** (int) - Required - The number of steps.
- **initial_state** (int | str) - Optional - The initial state.
- **final_state** (int | str) - Optional - The final state of the walk.
- **output_indices** (bool) - Optional - A boolean indicating whether to output the state indices.
- **seed** (int) - Optional - A seed to be used as RNG initializer.

### Response
- **Returns** (List[int] | List[str]) - The simulated sequence of states.
```

--------------------------------

### Save and Load Markov Chain to File

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Demonstrates saving a MarkovChain to JSON, CSV, and XML formats, and subsequently loading it back from a JSON file. This is useful for persisting model states and sharing them across different sessions or tools.

```python
from pydtmc import MarkovChain

# Create and save a Markov chain
p = [[0.7, 0.3], [0.4, 0.6]]
mc = MarkovChain(p, ['Sunny', 'Rainy'])

# Save to different formats
mc.to_file('weather_chain.json')
mc.to_file('weather_chain.csv')
mc.to_file('weather_chain.xml')

# Load from file
mc_loaded = MarkovChain.from_file('weather_chain.json')
print(f"Loaded states: {mc_loaded.states}")
print(f"Loaded matrix:\n{mc_loaded.p}")
```

--------------------------------

### Estimate HiddenMarkovModel Parameters

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Estimate the transition and emission probabilities of a HiddenMarkovModel from observed states and symbols. This method requires the states and symbols to be known.

```console
>>> est_hmm = hmm.estimate(states, symbols, sim_states, sim_symbols)
>>> print(est_hmm.p)
[[0.75, 0.25]
 [1.00, 0.00]]
>>> print(est_hmm.e)
[[0.0, 0.0, 0.0, 1.0]
 [0.0, 0.5, 0.5, 0.0]]
```

--------------------------------

### Create Markov Chain from Dictionary

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Define transitions as a dictionary to create a Markov Chain. Prints the states and transition matrix.

```python
from pydtmc import MarkovChain

# Define transitions as a dictionary
transitions = {
    ('Sunny', 'Sunny'): 0.7,
    ('Sunny', 'Cloudy'): 0.2,
    ('Sunny', 'Rainy'): 0.1,
    ('Cloudy', 'Sunny'): 0.3,
    ('Cloudy', 'Cloudy'): 0.4,
    ('Cloudy', 'Rainy'): 0.3,
    ('Rainy', 'Sunny'): 0.2,
    ('Rainy', 'Cloudy'): 0.3,
    ('Rainy', 'Rainy'): 0.5
}

mc_weather = MarkovChain.from_dictionary(transitions)
print(f"States: {mc_weather.states}")
print(f"Transition Matrix:\n{mc_weather.p}")
```

--------------------------------

### MarkovChain Constructor

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain.md

Defines a Markov chain with the given transition matrix and optional state names.

```APIDOC
## MarkovChain Constructor

### Description
Defines a Markov chain with the given transition matrix.

### Method
__init__

### Parameters
#### Path Parameters
- **p** (matrix) - Required - The transition matrix.
- **states** (list[str] or list[int]) - Optional - The name of each state. If omitted, an increasing sequence of integers starting at 1 is used.

### Raises
- **ValidationError** - If any input argument is not compliant.
```

--------------------------------

### Calculate First Passage Probabilities

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Call the 'first_passage_probabilities' method with a number of steps and a target state index to calculate first passage probabilities.

```console
>>> print(mc.first_passage_probabilities(5, 3))
[[0.5000, 0.0000, 0.5000, 0.0000]
 [0.0000, 0.3500, 0.0000, 0.0500]
 [0.0000, 0.0700, 0.1300, 0.0450]
 [0.0000, 0.0315, 0.1065, 0.0300]
 [0.0000, 0.0098, 0.0761, 0.0186]]
```

--------------------------------

### Convert Markov Chain to and from Dictionary

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Shows how to convert a MarkovChain object into a dictionary representation and how to reconstruct a MarkovChain from such a dictionary. This is helpful for data serialization and integration with other Python data structures.

```python
# Convert to/from dictionary
chain_dict = mc.to_dictionary()
print(f"As dictionary: {chain_dict}")

mc_from_dict = MarkovChain.from_dictionary(chain_dict)
```

--------------------------------

### MarkovChain.next

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Simulates a single step in a random walk from a given initial state.

```APIDOC
## MarkovChain.next

### Description
Simulates a single step in a random walk from a given initial state. Useful for interactive simulations or step-by-step analysis.

### Method
`next(current_state, seed=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **current_state** (string or int) - Required - The current state from which to take a step.
- **seed** (int, optional) - A seed for the random number generator for reproducible results.

### Request Example
```python
from pydtmc import MarkovChain

p = [[0.2, 0.7, 0.0, 0.1],
     [0.0, 0.6, 0.3, 0.1],
     [0.0, 0.0, 1.0, 0.0],
     [0.5, 0.0, 0.5, 0.0]]
pc = MarkovChain(p, ['A', 'B', 'C', 'D'])

# Perform a step-by-step random walk
current_state = 'A'
next_state = mc.next(current_state, seed=32)
```

### Response
#### Success Response (200)
- **next_state** (string or int) - The next state in the random walk.

#### Response Example
```
'B'
```
```

--------------------------------

### Simulate MarkovChain Sequence

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Call the 'simulate' method with a number of steps and an optional seed to generate a random sequence of states.

```console
>>> print(mc.simulate(10, seed=32))
['D', 'A', 'B', 'B', 'C', 'C', 'C', 'C', 'C', 'C', 'C']
```

--------------------------------

### Calculate Expected Transitions

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Call the 'expected_transitions' method with a number of steps to calculate the expected transition matrix.

```console
>>> print(mc.expected_transitions(2))
[[0.0850, 0.2975, 0.0000, 0.0425]
 [0.0000, 0.3450, 0.1725, 0.0575]
 [0.0000, 0.0000, 0.7000, 0.0000]
 [0.1500, 0.0000, 0.1500, 0.0000]]
```

--------------------------------

### from_matrices

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/hidden_markov_model_methods_static.md

Generates a Hidden Markov Model from provided transition and emission matrices.

```APIDOC
## from_matrices(mp: ndarray | spmatrix, me: ndarray | spmatrix, states: List[str] | None = None, symbols: List[str] | None = None)

### Description
The method generates a hidden Markov model whose transition and emission matrices are obtained through the normalization of the given matrices.

### Parameters
#### Path Parameters
* **mp** (ndarray | spmatrix) - Required - the matrix to transform into the transition matrix.
* **me** (ndarray | spmatrix) - Required - the matrix to transform into the emission matrix.
* **states** (List[str] | None) - Optional - the name of each state (if omitted, an increasing sequence of integers starting at 1 with prefix P).
* **symbols** (List[str] | None) - Optional - the name of each symbol (if omitted, an increasing sequence of integers starting at 1 with prefix E).

### Raises
* **ValidationError** – if any input argument is not compliant.
```

--------------------------------

### Fit Hidden Markov Model using Baum-Welch

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Fits a Hidden Markov Model to observed symbols using the Baum-Welch algorithm. Requires initial guesses for transition and emission matrices, and definitions of states and symbols.

```python
import numpy as np
from pydtmc import HiddenMarkovModel

# Initial guesses for transition and emission matrices
p_guess = np.array([[0.5, 0.5], [0.5, 0.5]])
e_guess = np.array([[0.33, 0.33, 0.34], [0.33, 0.33, 0.34]])

# Observed symbols (can be multiple sequences)
observed_symbols = ['Sym1', 'Sym2', 'Sym1', 'Sym3', 'Sym2', 'Sym1']

# Fit using Baum-Welch algorithm
hmm_fitted = HiddenMarkovModel.fit(
    'baum-welch',
    states, symbols,
    p_guess, e_guess,
    observed_symbols
)
print("Fitted Transition Matrix:")
print(np.round(hmm_fitted.p, 3))
```

--------------------------------

### Simulate HiddenMarkovModel Sequence

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Simulates a random sequence of hidden states and observed symbols for a given number of steps. Requires HMM initialization.

```python
from pydtmc import HiddenMarkovModel

p = [[0.4, 0.6], [0.8, 0.2]]
e = [[0.5, 0.0, 0.0, 0.5], [0.2, 0.2, 0.2, 0.4]]
hmm = HiddenMarkovModel(p, e, ['A', 'B'], ['H1', 'H2', 'H3', 'H4'])

# Simulate 12 steps
sim_states, sim_symbols = hmm.simulate(12, seed=1488)
print(f"States: {sim_states}")
# Output: ['B', 'A', 'A', 'A', 'B', 'A', 'A', ...]
print(f"Symbols: {sim_symbols}")
# Output: ['H2', 'H4', 'H4', 'H4', 'H3', 'H4', 'H4', ...]
```

--------------------------------

### simulate

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/hidden_markov_model_methods_instance.md

Simulates a random sequence of states and symbols for a specified number of steps.

```APIDOC
## simulate

### Description
The method simulates a random sequence of states and symbols of the given number of steps.

### Method
`simulate`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **steps** (int) - The number of steps.
* **initial_state** (int | str | None) - The initial state (if omitted, it is chosen uniformly at random).
* **final_state** (int | str | None) - The final state of the simulation (if specified, the simulation stops as soon as it is reached even if not all the steps have been performed).
* **final_symbol** (int | str | None) - The final symbol of the simulation (if specified, the simulation stops as soon as it is reached even if not all the steps have been performed).
* **output_indices** (bool) - A boolean indicating whether to output the state indices.
* **seed** (int | None) - A seed to be used as RNG initializer for reproducibility purposes.

### Raises
* `ValidationError` – if any input argument is not compliant.

### Request Example
None

### Response
#### Success Response (200)
* `Tuple[List[int], List[int]]` or `Tuple[List[str], List[str]]` - A tuple containing lists of states and symbols.

#### Response Example
None
```

--------------------------------

### Fit HMM with Baum-Welch or MLE

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Fits an HMM from initial guesses and observed sequences using Baum-Welch, MAP, or MLE algorithms. Requires numpy.

```python
from pydtmc import HiddenMarkovModel
import numpy as np

states = ['State1', 'State2']
symbols = ['Sym1', 'Sym2', 'Sym3']


```

--------------------------------

### Estimate HMM Parameters

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Performs maximum likelihood estimation of transition and emission probabilities from observed sequences of states and symbols. Requires known states and symbols.

```python
from pydtmc import HiddenMarkovModel

# Known states and observed symbols from simulation
states = ['A', 'B']
symbols = ['H1', 'H2', 'H3', 'H4']
seq_states = ['B', 'A', 'A', 'A', 'B', 'A', 'A']
seq_symbols = ['H2', 'H4', 'H4', 'H4', 'H3', 'H4', 'H4']

# Estimate HMM parameters
hmm_estimated = HiddenMarkovModel.estimate(states, symbols, seq_states, seq_symbols)
print("Estimated Transition Matrix:")
print(hmm_estimated.p)
# Output:
# [[0.75, 0.25]
#  [1.00, 0.00]]

print("Estimated Emission Matrix:")
print(hmm_estimated.e)
# Output:
# [[0.0, 0.0, 0.0, 1.0]
#  [0.0, 0.5, 0.5, 0.0]]
```

--------------------------------

### from_file

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain_methods_static.md

Reads and creates a Markov chain from a file. Supports CSV, JSON, TXT, and XML formats.

```APIDOC
## from_file(file_path: str | Path) -> MarkovChain

The method reads a Markov chain from the given file. Only CSV, JSON, TXT, and XML files are supported; data format is inferred from the file extension.

### File Formats:
* **CSV:**
    - Delimiter: comma
    - Quoting: minimal
    - Quote Character: double quote
    - Header Row: state names
    - Data Rows: probabilities
* **JSON:**
    - Structure: Array of objects with properties `state_from` (string), `state_to` (string), `probability` (float or int).
* **TXT:**
    - Format: Each line must contain `<state_from> <state_to> <probability>`.
* **XML:**
    - Root Element: `MarkovChain`
    - Child Elements: `Item` with attributes `state_from` (string), `state_to` (string), `probability` (float or int).

### Parameters
* **file_path** (str | Path) - The path to the file that defines the Markov chain.

### Raises
* `FileNotFoundError` - If the file does not exist.
* `OSError` - If the file cannot be read or is empty.
* `ValidationError` - If any input argument is not compliant.
* `ValueError` - If the file contains invalid data.
```

--------------------------------

### redistribute

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain_methods_instance.md

Performs a redistribution of states of N steps.

```APIDOC
## redistribute

### Description
The method performs a redistribution of states of N steps.

### Parameters
- **steps** (int) - Required - The number of steps.
- **initial_status** (int | str | ndarray | spmatrix) - Optional - The initial state or the initial distribution of the states.
- **output_last** (bool) - Optional - A boolean indicating whether to output only the last distributions.

### Response
- **Returns** (ndarray | List[ndarray]) - The resulting state distribution(s).
```

--------------------------------

### Generate Random Markov Chain

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Creates a random Markov chain instance with specified size and optional constraints.

```python
from pydtmc import MarkovChain
import numpy as np

# Generate a random 4x4 Markov chain
mc_random = MarkovChain.random(4, seed=42)
print(f"States: {mc_random.states}")
print(f"Transition Matrix:\n{np.round(mc_random.p, 3)}")

# Generate with custom state names and some zero transitions
mc_sparse = MarkovChain.random(
    size=5,
    states=['S1', 'S2', 'S3', 'S4', 'S5'],
    zeros=10,  # Add 10 zero transition probabilities
    seed=123
)
print(f"Sparse chain:\n{np.round(mc_sparse.p, 3)}")
```

--------------------------------

### from_dictionary

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain_methods_static.md

Creates a Markov chain from a dictionary where keys are state pairs and values are transition probabilities.

```APIDOC
## from_dictionary(d: Dict[Tuple[str, str], float | int]) -> MarkovChain

The method generates a Markov chain from the given dictionary, whose keys represent state pairs and whose values represent transition probabilities.

### Parameters
* **d** (Dict[Tuple[str, str], float | int]) - The dictionary to transform into the transition matrix. Keys are tuples of (state_from, state_to), and values are the corresponding probabilities.

### Raises
* `ValidationError` - If any input argument is not compliant.
* `ValueError` - If the transition matrix defined by the dictionary is not valid.
```

--------------------------------

### mixing_time(initial_distribution, jump, cutoff_type)

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain_methods_instance.md

Computes the mixing time of the Markov chain given an initial distribution.

```APIDOC
## mixing_time(initial_distribution, jump, cutoff_type)

### Description
The method computes the mixing time of the Markov chain, given the initial distribution of the states.

### Method
POST

### Endpoint
/api/markovchain/mixing_time

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **initial_distribution** (ndarray | spmatrix | None) - Optional - The initial distribution of the states (if omitted, the states are assumed to be uniformly distributed).
- **jump** (int) - Optional - The number of steps in each iteration. Defaults to 1.
- **cutoff_type** (str) - Optional - The type of cutoff. Can be 'natural' or 'traditional'. Defaults to 'natural'.

### Request Example
```json
{
  "initial_distribution": [0.5, 0.5],
  "jump": 5,
  "cutoff_type": "traditional"
}
```

### Response
#### Success Response (200)
- **int | None**: The mixing time, or None if the chain is not ergodic.

#### Response Example
```json
{
  "mixing_time": 100
}
```

### Error Handling
- **ValidationError**: If any input argument is not compliant.

### Notes
- If the Markov chain is not ergodic, then `None` is returned.
- The method can be accessed through the following aliases: **mt**.
```

--------------------------------

### transition_probability

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain_methods_instance.md

Computes the probability of transitioning from an origin state to a target state.

```APIDOC
## transition_probability

### Description
The method computes the probability of a given state, conditioned on the process being at a given state.

### Parameters
#### Request Body
- **state_target** (int | str) - Required - The target state.
- **state_origin** (int | str) - Required - The origin state.
```

--------------------------------

### random

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/hidden_markov_model_methods_static.md

Generates a Hidden Markov Model with random transition and emission probabilities.

```APIDOC
## random(n: int, k: int, states: List[str] | None = None, p_zeros: int = 0, p_mask: ndarray | spmatrix | None = None, symbols: List[str] | None = None, e_zeros: int = 0, e_mask: ndarray | spmatrix | None = None, seed: int | None = None)

### Description
The method generates a Markov chain of given size with random transition probabilities.

### Notes
- In the mask parameter, undefined transition probabilities are represented by *NaN* values.

### Parameters
#### Path Parameters
* **n** (int) - Required - the number of states.
* **k** (int) - Required - the number of symbols.
* **states** (List[str] | None) - Optional - the name of each state (if omitted, an increasing sequence of integers starting at 1 with prefix P).
* **p_zeros** (int) - Optional - the number of null transition probabilities.
* **p_mask** (ndarray | spmatrix | None) - Optional - a matrix representing locations and values of fixed transition probabilities.
* **symbols** (List[str] | None) - Optional - the name of each symbol (if omitted, an increasing sequence of integers starting at 1 with prefix E).
* **e_zeros** (int) - Optional - the number of null emission probabilities.
* **e_mask** (ndarray | spmatrix | None) - Optional - a matrix representing locations and values of fixed emission probabilities.
* **seed** (int | None) - Optional - a seed to be used as RNG initializer for reproducibility purposes.

### Raises
* **ValidationError** – if any input argument is not compliant.
```

--------------------------------

### Compute First Passage Probabilities

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Calculates the probability of reaching specific states for the first time at each step up to N.

```python
from pydtmc import MarkovChain

p = [[0.2, 0.7, 0.0, 0.1],
     [0.0, 0.6, 0.3, 0.1],
     [0.0, 0.0, 1.0, 0.0],
     [0.5, 0.0, 0.5, 0.0]]
mc = MarkovChain(p, ['A', 'B', 'C', 'D'])

# Compute first passage probabilities for 5 steps starting from state D (index 3)
fpp = mc.first_passage_probabilities(5, initial_state=3)
print(fpp)
```

--------------------------------

### MarkovChain.simulate

Source: https://context7.com/tommasobelluzzo/pydtmc/llms.txt

Simulates a random walk on the Markov chain for a specified number of steps.

```APIDOC
## MarkovChain.simulate

### Description
Simulates a random walk of a given number of steps on the Markov chain. Optionally specify an initial state, final state (early stopping), and a seed for reproducibility.

### Method
`simulate(n_steps, initial_state=None, final_state=None, output_indices=False, seed=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **n_steps** (int) - Required - The number of steps to simulate.
- **initial_state** (string or int, optional) - The starting state for the simulation.
- **final_state** (string or int, optional) - If specified, the simulation stops early when this state is reached.
- **output_indices** (bool, optional) - If True, returns state indices instead of state labels. Defaults to False.
- **seed** (int, optional) - A seed for the random number generator for reproducible results.

### Request Example
```python
from pydtmc import MarkovChain

p = [[0.2, 0.7, 0.0, 0.1],
     [0.0, 0.6, 0.3, 0.1],
     [0.0, 0.0, 1.0, 0.0],
     [0.5, 0.0, 0.5, 0.0]]
pc = MarkovChain(p, ['A', 'B', 'C', 'D'])

# Simulate 10 steps starting from state 'D'
sequence = mc.simulate(10, initial_state='D', seed=32)
```

### Response
#### Success Response (200)
- **sequence** (list) - A list representing the simulated walk (sequence of states or state indices).

#### Response Example
```
['D', 'A', 'B', 'B', 'C', 'C', 'C', 'C', 'C', 'C', 'C']
```
```

--------------------------------

### expected_transitions

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/docs/source/markov_chain_methods_instance.md

Computes the expected number of transitions after N steps.

```APIDOC
## expected_transitions

### Description
The method computes the expected number of transitions performed by the Markov chain after N steps, given the initial distribution of the states. Alias: et.

### Parameters
- **steps** (int) - Required - The number of steps.
- **initial_distribution** (ndarray | spmatrix) - Optional - The initial distribution of the states (if omitted, states are assumed to be uniformly distributed).

### Errors
- **ValidationError** - If any input argument is not compliant.
```

--------------------------------

### Calculate Hitting Probabilities

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Call the 'hitting_probabilities' method with a list of target state indices to calculate hitting probabilities.

```console
>>> print(mc.hitting_probabilities([0, 1]))
[1.0, 1.0, 0.0, 0.5]
```

--------------------------------

### Simulate HiddenMarkovModel Sequence

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Simulate a sequence of states and symbols from a HiddenMarkovModel. The length of the simulation and an optional random seed can be provided.

```console
>>> sim_states, sim_symbols = hmm.simulate(12, seed=1488)
>>> print(sim_states)
['B', 'A', 'A', 'A', 'B', 'A', 'A']
>>> print(sim_symbols)
['H2', 'H4', 'H4', 'H4', 'H3', 'H4', 'H4']
```

--------------------------------

### Calculate Expected Rewards

Source: https://github.com/tommasobelluzzo/pydtmc/blob/master/README.md

Call the 'expected_rewards' method with a number of steps and a reward vector to calculate expected rewards.

```console
>>> print(mc.expected_rewards(10, [2, -3, 8, -7]))
[44.96611926, 52.03057032, 88.00000000, 51.74779651]
```