Homological Observability

This package provides tools for analyzing the recoverability of accumulated cycle histories in finite-state Markov jump processes. Use it to study your own network, compare observation schemes, and reproduce the paper's finite-model calculations.

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?

What the theory establishes. The paper organizes unresolved cycle differences into an integer hierarchy and derives the asymptotic sampling conditions for recovering accumulated windings. Its information phase diagram describes how residual uncertainty grows as observation time and sampling resolution change. These transitions persist at equilibrium under detailed balance. The scientific scope explains the assumptions and physical interpretation.

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. Find which cycle differences remain hidden, how sampling must scale to resolve them, and which counter choices reveal different or redundant information. The command line and Python API return explanatory reports backed by exact integer calculations.

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. On macOS or Linux:

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

On Windows PowerShell:

py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install homological-observability==1.2.1

Python 3.11 or 3.13 can be selected in place of 3.12. 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

After installing the package above, run:

.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. Successful verification prints PASS: all calculation checks completed and PASS: generated tables agree with frozen reference results. The output directory also contains the numerical CSV tables. 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.