Homological Observability

This package provides tools for analyzing the recoverability of accumulated cycle histories in finite-state Markov jump processes.

A state snapshot records where a system is; its cycle history records the net circulation accumulated around the network. At finite temporal resolution, the same sequence of snapshots can hide different net windings, even when all transition rates are known. Longer observation adds both snapshots and history to recover. How rapidly must sampling improve to keep pace, and how can additional counters reduce that requirement?

The theoretical foundation is Stochastic Histories at Finite Temporal Resolution: Homological Observability and Information Phase Diagrams in Markov Jump Processes (paper DOI). The package also reproduces the paper's finite-model calculations.

Read the paper · Reproduce the calculations · Cite

Analyze your own network. Provide its transition graph and optional integer counter rules. Each counter accumulates signed integer increments on edge crossings. The software computes hidden cycle differences and their exposure layers, the corresponding asymptotic sampling requirements, and the information retained by different counter configurations. Use the command line or Python to obtain explanatory reports and exact integer evidence.

The graph must be finite, connected, and simple, with positive transition-rate support in both directions. The recording protocol uses regular noiseless state snapshots and optional exact counters. Network and counter analyses need no rate values. The critical experiment uses exact positive rates to compute path weights and limiting mark distributions.

Install

Use Python 3.11–3.13. In your working directory, create a virtual environment and install the package from PyPI:

python3 -m venv .venv
.venv/bin/python -m pip install homological-observability==1.2.0

The installation guide includes Windows commands. On Windows, use .venv\Scripts\homological-observability.exe in place of .venv/bin/homological-observability below, and .venv\Scripts\python.exe in place of .venv/bin/python. Activation is optional. Installation needs internet access; examples and reference data are included in the package.

Try a counter comparison

A four-state ring and a seven-state ring are connected by a bridge. You can count signed crossings on either ring: which choice postpones the earliest remaining cycle-history ambiguity?

.venv/bin/homological-observability study-example bridge --output bridge-study.json
.venv/bin/homological-observability compare bridge-study.json --output-dir bridge-results

Open bridge-results/comparison.md. The study completes all six candidates; three of its results are:

Counting the short ring postpones the first unresolved cycle direction to layer four. Counting the long ring leaves the earlier ambiguity in place. The two counters retain different information, even though each leaves one hidden direction. The study also shows that a weighted counter can tie a scalar objective without retaining the same information, and that a proportional extra channel is redundant.

The worked comparison explains the hidden layers and the example's sampling law. COMPLETE records the scope of the calculation; the report describes the remaining ambiguity. The bundle contains structured results, exact witnesses, the input, and replay instructions. Each run uses a new output directory.

Reproduce the paper evidence

.venv/bin/homological-observability reproduce --check --output-dir generated_results

This command regenerates the paper's finite-model calculations, compares them with the packaged reference data, and writes generated_results/REPORT.md and generated_results/companion_summary.png. For pinned dependencies and the reader-side test suite, follow the reproduction guide.

Analyze your own network

For one observation scheme, prepare my-model.json with your graph, optional counter rules, and any sampling parameters. The model input guide explains the fields and includes a complete example. Run:

.venv/bin/homological-observability analyze my-model.json

To compare several counter configurations, adapt the bridge study. Save a copy of bridge-study.json as my-study.json. Update the study and model names, research question, graph, and candidate counters. Replace the example's alpha: 0.375 with your own sampling exponent, or remove it for a comparison of graph and counter information alone. Keep an explicit cycle enumeration budget, then run:

.venv/bin/homological-observability compare my-study.json --output-dir my-results

The study editing guide walks through these choices. The input guide describes signed edge increments, sampling units, validation, and resource limits. Every exported study also includes a model file for each candidate, ready to inspect separately with analyze.

Python API

Run this with the virtual environment's Python interpreter:

import homological_observability as ho

study = ho.load_study_example("bridge")
comparison = ho.compare_configurations(study)
print(ho.render_comparison_text(comparison))

Use ho.load_study("my-study.json") for your own study. The output guide describes structured results and renderers, including single-configuration analysis and rate-dependent critical experiments.

Interpretation and further reading

Integer lattice calculations and finite catalogues are exact when complete. Sampling thresholds, phase labels, and entropy coefficients describe long-time asymptotic limits under the stated model assumptions. Choosing a sampling interval for a specified finite-run error tolerance requires additional risk analysis. Cycle enumeration can grow exponentially; use computation budgets and check the reported completeness of each result.

• Overview and first study
• Scientific assumptions and research uses
• Integer layers and sampling: a worked two-loop example
• Rate-dependent critical experiments
• Changes by version
• Report an issue

Theory and citation

The paper map connects the software's calculations to the theoretical results and paper evidence.

Cite the paper for theoretical results and the software for computations. When your work uses both, cite them separately. The citation guide provides the full paper and software references and a copyable paper BibTeX entry. Record the software version used and the Git commit for a source checkout.

Authors: HongZheng Liu, YiNuo Tian, Zhiyue Wu, and Jianqun Cheng.

The software is distributed under the MIT License. The archived paper is licensed under CC BY 4.0.