Definition Formats

Markov Solver supports multiple input formats for defining Markov chains. This page documents each supported format with examples and schema references.

See the examples directory for complete configuration examples.

Supported Formats

Format	Extensions	Description
Chain Format	`.yaml`, `.yml`, `.json`	List of transitions with from/to/value fields
Transition Matrix	`.yaml`, `.yml`, `.json`	States list with nested transition probabilities
DOT/Graphviz	`.dot`, `.gv`	Standard Graphviz directed graph format
CSV Adjacency Matrix	`.csv`	Spreadsheet-compatible adjacency matrix

Chain Format (YAML/JSON)

The chain format defines a Markov chain as a list of transitions. This is the default format for .yaml, .yml, and .json files.

Schema

pydantic model markov_solver.parser.schema.MarkovChainDefinition

Schema for the chain-based Markov chain definition format.

Example:

chain:
  - from: "S0"
    to: "S1"
    value: "0.5"

Fields:

chain (list[markov_solver.parser.schema.MarkovLinkSchema])
symbols (dict[str, str | int | float])

field chain: list[MarkovLinkSchema] [Required]: List of links defining the Markov chain

field symbols: dict[str, str | int | float] [Optional]: Optional symbolic variables

pydantic model markov_solver.parser.schema.MarkovLinkSchema

Schema for a single link/edge in the Markov chain.

Config:

populate_by_name: bool = True
validate_by_alias: bool = True
validate_by_name: bool = True

Fields:

from_state (str)
to_state (str)
value (str)

field from_state: str [Required] (alias 'from'): Source state name

field to_state: str [Required] (alias 'to'): Target state name

field value: str [Required]: Transition probability or rate

Example (YAML)

chain:
  - from: "Sunny"
    to: "Sunny"
    value: "0.9"
  - from: "Sunny"
    to: "Rainy"
    value: "0.1"
  - from: "Rainy"
    to: "Rainy"
    value: "0.5"
  - from: "Rainy"
    to: "Sunny"
    value: "0.5"

Example with Symbols (YAML)

symbols:
  lambda: 1.5
  mu: 2.0
chain:
  - from: "S0"
    to: "S1"
    value: "lambda"
  - from: "S1"
    to: "S0"
    value: "mu"

Transition Matrix Format

The transition matrix format defines states explicitly and uses nested dictionaries for transition probabilities.

Schema

pydantic model markov_solver.parser.schema.TransitionMatrixDefinition

Schema for the transition matrix Markov chain definition format.

Example:

{
    "states": ["S0", "S1", "S2"],
    "initial": "S0",
    "transitions": {
        "S0": {"S0": 0.5, "S1": 0.5},
        "S1": {"S2": 1.0}
    }
}

Fields:

initial (str | None)
states (list[str])
symbols (dict[str, str | int | float])
transitions (dict[str, dict[str, float | str]])

field initial: str | None = None: Optional initial state

field states: list[str] [Required]: List of state names

field symbols: dict[str, str | int | float] [Optional]: Optional symbolic variables

field transitions: dict[str, dict[str, float | str]] [Required]: Transition matrix as nested dict

Example (YAML)

states:
  - Sunny
  - Rainy
transitions:
  Sunny:
    Sunny: 0.9
    Rainy: 0.1
  Rainy:
    Rainy: 0.5
    Sunny: 0.5

Example (JSON)

{
  "states": ["Sunny", "Rainy"],
  "transitions": {
    "Sunny": {"Sunny": 0.9, "Rainy": 0.1},
    "Rainy": {"Rainy": 0.5, "Sunny": 0.5}
  }
}

DOT/Graphviz Format

The DOT format uses standard Graphviz syntax for directed graphs. Edge labels represent transition probabilities.

Parser

class markov_solver.parser.dot_parser.DotParser

Bases: FormatParser

Parser for DOT/Graphviz format.

Example:

digraph {
    S0 -> S0 [label=0.5]
    S0 -> S1 [label=0.5]
    S1 -> S2 [label=1.0]
}

EDGE_PATTERN = re.compile('^\\s*"?([^"\\s\\->]+)"?\\s*->\\s*"?([^"\\s\\[]+)"?\\s*(?:\\[\\s*label\\s*=\\s*"?([^"\\]]+)"?\\s*])?', re.MULTILINE)

parse(content: str) → MarkovChain: Parse file content into a MarkovChain.

supports_extension(extension: str) → bool: Check if this parser supports the given file extension.

Example

digraph {
    Sunny -> Sunny [label=0.9]
    Sunny -> Rainy [label=0.1]
    Rainy -> Rainy [label=0.5]
    Rainy -> Sunny [label=0.5]
}

Notes

Node names can be quoted or unquoted
Labels can be quoted or unquoted
Edges without labels default to probability 1.0
Symbolic values are supported in labels

CSV Adjacency Matrix Format

The CSV format represents the transition matrix as a spreadsheet-compatible adjacency matrix.

Parser

class markov_solver.parser.csv_parser.CsvAdjacencyMatrixParser

Bases: FormatParser

Parser for CSV adjacency matrix format.

The first row and first column contain state names. Cell values are transition probabilities.

Example:: ,S0,S1,S2 S0,0.5,0.5,0 S1,0,0,1.0 S2,0,0,1.0

parse(content: str) → MarkovChain: Parse file content into a MarkovChain.

supports_extension(extension: str) → bool: Check if this parser supports the given file extension.

Example

,Sunny,Rainy
Sunny,0.9,0.1
Rainy,0.5,0.5

Notes

First row contains state names (header)
First column contains source state names
Cell values are transition probabilities
Zero values (0 or 0.0) are ignored
Empty cells are ignored

Extensibility

The parser system is extensible. You can create custom parsers by subclassing the FormatParser base class.

Base Class

class markov_solver.parser.base.FormatParser

Bases: ABC

Abstract base class for format-specific parsers.

abstractmethod parse(content: str) → MarkovChain: Parse file content into a MarkovChain.

abstractmethod supports_extension(extension: str) → bool: Check if this parser supports the given file extension.

exception markov_solver.parser.base.ParserError

Bases: Exception

Raised when parsing fails.

Registering Custom Parsers

from markov_solver.parser import get_parser, FormatParser
from markov_solver.model.markov_chain import MarkovChain

class MyCustomParser(FormatParser):
    def parse(self, content: str) -> MarkovChain:
        # Custom parsing logic
        ...

    def supports_extension(self, extension: str) -> bool:
        return extension.lower() == ".custom"

# Register the parser
parser = get_parser()
parser.register_parser(MyCustomParser())