homological-observability 1.1.0__tar.gz

homological_observability-1.1.0/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All user-visible software changes are recorded here. The project follows
+semantic versioning for packaged interfaces; schema versions are tracked
+separately inside their JSON documents.
+
+## 1.1.0 — 2026-10-13
+
+### Added
+
+- Exact exposure, visible-image, and hidden integer filtrations for user-defined
+  connected finite simple graphs.
+- Smith/Hermite graded quotient invariants, including finite torsion factors.
+- Versioned JSON Schemas for topology models and analyses, critical models and
+  experiments, example catalogs, reproduction results, and controlled errors.
+- Stable top-level Python API and deterministic JSON, text, and Markdown
+  renderers.
+- `examples`, `example`, `analyze`, `critical`, and `reproduce` CLI tasks with
+  documented statuses and exit codes.
+- Exact critical-layer path catalogues and theorem-derived marked-Poisson
+  experiment specifications for known strictly positive directed edge rates.
+- Exact decimal and rational parsing for critical rates and intensity, with
+  atomic path, integer-digit, cycle, and output resource limits.
+- Built-in wedge-of-C3-and-C5 demonstration with a staged exposure, index-two
+  visible quotient, and hidden free direction.
+- Rate-biased C4 end-to-end example with an exact nonreversible stationary law,
+  conditional critical marks, and a generated machine-readable result.
+- Wheel and sdist distributions with installed reference data.
+- Python 3.11–3.13 support.
+
+### Changed
+
+- Analysis Schema version 2 separates completion of the requested horizon from
+  certification that the natural filtration is complete.
+- Analyses that complete a restricted horizon without exposing the full
+  integral homology lattice now return `PARTIAL_HORIZON` rather than
+  `COMPLETE`.
+- `quickstart.py` now creates and manages its validation environment before
+  running the reader-side tests and frozen-paper reproduction.
+- Generated reports use `Visible` and `Hidden` consistently for the two
+  readout sectors.
+- Terminal tables align quotient values with their column headings.
+- Critical resource controls distinguish an integer-digit preflight admission
+  budget from exact digit and output-record ceilings.
+
+### Compatibility
+
+- The source-checkout commands `quickstart.py`, `reproduce_all.py`,
+  `critical_kernel_checks.py`, `selected_appendix_checks.py`, and
+  `explore_cycles.py` remain supported.
+
+### Fixed
+
+- Reproduction reports distinguish calculation checks from frozen-reference
+  comparison, and failed or interrupted runs invalidate earlier success reports.
+- Equivalent finite-ring endpoint and winding coordinates use the same bounded
+  calculation. Oversized floating-point requests raise explicit range or budget
+  errors before summation.
+- Source builds require setuptools 77.0.3 or later, matching the SPDX license
+  metadata used by the package.
+- Software and companion paper metadata include the complete four-author list.
+- The shared pinned verification dependencies include JSON Schema validation
+  and its dependencies, so fresh quickstart environments and CI can run the
+  reader-side tests. Existing quickstart environments refresh automatically.
+- Path preflight stops at a certified resource refusal without constructing
+  an oversized count. Uncomputed totals remain explicitly unavailable.
+- Generated topology integers share one representation boundary across the
+  Python API, JSON, text, and Markdown output.
+- Maximum-value parentheses display correctly in the GitHub-rendered guides.
+- Poisson-averaged MAP evaluation remains finite at large representable means.
+- Small-window endpoint probabilities retain representable subnormal mass;
+  unresolved positive probabilities raise explicit range errors. Rare bridges
+  use stable series through a unit sampling window.
+- Exact digit checks no longer format oversized integers before counting.
+  Explicit decimal input/output bounds keep rejected requests and limited
+  results reportable, including model hashes and command-line diagnostics.
+- Direct public graph and readout construction validates integer coefficients,
+  graph structure, and analysis settings before scientific computation.
+- Phase regimes now follow the exact binary sampling input, including values
+  adjacent to non-dyadic thresholds. Exposure and entropy calculations round
+  after exact arithmetic and report unrepresentable results consistently.
+- C3 and C4 count-TV diagnostics use outward-rounded probability recurrences,
+  including arithmetic error and omitted tails in the returned intervals.
+- Small-window cycle bridges cancel the rare-endpoint scale before division.
+- Reproduction protects both committed and installed references, including
+  symbolic and hard-link aliases with different output names.
+- Critical digit limits include scientific integers, readout maps, marks and
+  derived total intensities, with atomic rejection of oversized results.
+- The diametric-chord C6 from Appendix F.4 has its own path-pair regression;
+  the existing distance-two chord example remains separately identified.
+
+### Scientific evidence
+
+- The C3/C4 TV columns in the critical-kernel table are recalibrated against
+  independent high-precision probabilities. The other reference values and
+  existing comparison tolerances are retained. See [numerical methods](docs/NUMERICS.md).
+- The exact integer kernel has been checked across all 996 connected graphs in
+  the NetworkX graph atlas, including independent path-pair and integer-readout
+  comparisons.
+
+## 1.0.0
+
+- Initial computational companion for the paper's exactly solvable finite-cycle
+  examples, critical kernels, MAP identity, and reciprocal-lattice peak
+  mechanism.

homological_observability-1.1.0/CITATION.cff

@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite the software and companion paper."
+title: "Homological Observability: Research Kernel and Computational Companion"
+type: software
+authors:
+  - family-names: Liu
+    given-names: HongZheng
+  - family-names: Tian
+    given-names: YiNuo
+  - family-names: Wu
+    given-names: Zhiyue
+  - family-names: Cheng
+    given-names: Jianqun
+version: 1.1.0
+license: MIT
+repository-code: "https://github.com/yeruciwenrou-dotcom/homological-observability"
+preferred-citation:
+  type: article
+  authors:
+    - family-names: Liu
+      given-names: HongZheng
+    - family-names: Tian
+      given-names: YiNuo
+    - family-names: Wu
+      given-names: Zhiyue
+    - family-names: Cheng
+      given-names: Jianqun
+  title: "Stochastic Histories at Finite Temporal Resolution: Homological Observability and Information Phase Diagrams in Markov Jump Processes"
+  year: 2026
+  notes: "Unpublished manuscript; public release on arXiv is planned."

homological_observability-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Corrections, reproducible examples, and documentation improvements are welcome.
+Use the [issue forms](https://github.com/yeruciwenrou-dotcom/homological-observability/issues/new/choose)
+to report a problem, including the version or commit, a minimal input, and
+the expected and observed results. For a research question or proposed
+extension, open a regular issue describing the model and observation assumptions.
+
+## Development environment
+
+From a source checkout with Python 3.11–3.13, create a virtual environment
+and install the pinned dependencies and development tools. On macOS or Linux:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+python -m pip install -c requirements.txt -e '.[test]'
+```
+
+On Windows PowerShell:
+
+```powershell
+py -3.12 -m venv .venv
+.venv\Scripts\python.exe -m pip install -r requirements.txt
+.venv\Scripts\python.exe -m pip install -c requirements.txt -e '.[test]'
+```
+
+This editable installation uses your working source files. In the checks
+below, Windows users can replace `python` with `.venv\Scripts\python.exe`
+and `ruff` with `.venv\Scripts\ruff.exe`; activation is optional.
+
+Run the checks relevant to the change:
+
+```bash
+python -W error -m unittest discover -s tests -v
+python -W error reproduce_all.py
+python tests/validate_schema.py
+python tests/validate_graph_atlas.py
+python tests/validate_distribution.py
+ruff check .
+ruff format --check .
+```
+
+The distribution check builds a wheel and source archive, then installs and
+exercises each in a separate environment outside the checkout. It needs
+internet access for build tools and dependencies. CI runs these checks on
+each pull request.
+
+## Scientific changes
+
+For a calculation fix, explain the mathematical or numerical reason and add
+a regression that distinguishes the corrected result from the error. Closed forms,
+independent calculations, and structural invariants are useful comparisons.
+Update the input/output guides when a public contract changes.
+
+Keep new calculations in a separate output directory. The committed CSV files
+and their packaged copies are the paper's numerical references; changes to
+them need an independently justified correction and a matching changelog entry.
+Regenerate built-in example reports with `python tools/freeze_examples.py` and
+verify them with `python tools/freeze_examples.py --check`.
+
+Submit focused pull requests with the user-visible effect and verification
+results. Contributions use the repository's MIT License.

homological_observability-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HongZheng Liu, YiNuo Tian, Zhiyue Wu, and Jianqun Cheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

homological_observability-1.1.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md
+include CITATION.cff
+include CHANGELOG.md
+include CONTRIBUTING.md
+include PAPER_MAP.md
+include critical_kernel_checks.py
+include explore_cycles.py
+include quickstart.py
+include reproduce_all.py
+include requirements.txt
+include selected_appendix_checks.py
+recursive-include docs *.md *.svg
+recursive-include examples *.json *.md
+recursive-include results *.csv *.md *.png *.svg
+recursive-include tests *.py
+recursive-include tools *.py

homological_observability-1.1.0/PAPER_MAP.md

@@ -0,0 +1,118 @@
+# Paper map and evidence
+
+This repository is the companion codebase for the manuscript *Stochastic
+Histories at Finite Temporal Resolution: Homological Observability and
+Information Phase Diagrams in Markov Jump Processes*. The manuscript is not
+yet publicly available. See the
+[citation information](README.md#citation-and-license) for its release status
+and the software record.
+
+This guide connects the paper's mathematical objects to their implementation
+and reproducible evidence. Entries are organized by scientific object.
+
+The physical target is the accumulated integer cycle history of a particular
+run observed through vertex snapshots and optional counters. The filtration
+determines which history differences can appear at each short-time order;
+the critical experiment determines their limiting weights and what remains
+after the available observations. For a reader's introduction, start with
+[physical interpretation and scope](docs/SCIENTIFIC_SCOPE.md). This page
+provides the implementation and evidence trail behind those interpretations.
+
+## Integer homology and filtrations
+
+| Paper object | Computation | Implementation |
+| --- | --- | --- |
+| Integral homology $\Lambda=H_1(G;\mathbb Z)$ | Ordered spanning tree and fundamental cycles | [homology.py](src/homological_observability/homology.py) |
+| Exposure lattice $L_m$ | Simple cycles of length at most $2m$, followed by integer column HNF | [filtration.py](src/homological_observability/filtration.py) |
+| Integer side readout $\pi$ | Edge cochains restricted to cycle coordinates | [model.py](src/homological_observability/model.py), [homology.py](src/homological_observability/homology.py) |
+| Visible image $\pi(L_m)$ | Exact integer image | [integer_lattice.py](src/homological_observability/integer_lattice.py) |
+| Hidden lattice $K_m=L_m\cap\ker\pi$ | Saturated integer kernel and lattice image | [integer_lattice.py](src/homological_observability/integer_lattice.py) |
+| Successive graded quotients | Inclusion coordinates and Smith normal form | [integer_lattice.py](src/homological_observability/integer_lattice.py) |
+| Phase and entropy laws | Apply the paper's exponents and hidden-rank formulas | [phase.py](src/homological_observability/phase.py) |
+| Completeness | Distinguish a completed horizon, full lattice saturation, and exhausted resources | [analysis.py](src/homological_observability/analysis.py) |
+
+The [wedge C3–C5 example](docs/END_TO_END_EXAMPLE.md) exhibits staged exposure,
+a visible $\mathbb Z/2\mathbb Z$ quotient, and a hidden free direction. Its
+[JSON result](examples/wedge_c3_c5_result.json) records every lattice and graded
+quotient. These exact integer calculations retain finite-index effects that
+real-rank calculations would lose. Coordinate matrices depend on the chosen
+basis; ranks and quotient invariants do not.
+
+Independent checks include:
+
+- [Path-pair definitions and basis invariance](tests/test_filtration.py),
+  including both chorded C6 models and a pure-torsion graph.
+- [Integer-kernel and quotient tests](tests/test_integer_lattice.py), including
+  cases where a rational nullspace basis is insufficient.
+- [All 996 connected graph-atlas models](tests/validate_graph_atlas.py), with
+  independent path-pair and readout comparisons.
+- [Phase laws and sampling boundaries](tests/test_phase.py), together with
+  [horizon, resource, and CLI checks](tests/test_product_contract.py).
+
+The Appendix F.4 C6 uses the diametric chord {0,3}: both independent directions
+appear in $L_2$. The separate chord {0,2} example has ranks 1 and 2 at layers 2
+and 3. The tests identify these as `chorded_c6_diametric` and
+`chorded_c6_distance_two`, respectively.
+
+## Rate-dependent critical experiment
+
+| Paper object | Computation | Implementation |
+| --- | --- | --- |
+| Known generator and stationary law | Positive exact rates in both directions; solve $pQ=0$ over the rationals | [critical_experiment.py](src/homological_observability/critical_experiment.py) |
+| Critical marks | Enumerate walks of length $m$, subtract an endpoint reference geodesic, and project to $L_m/L_{m-1}$ | [_critical_catalogue.py](src/homological_observability/_critical_catalogue.py) |
+| Induced readout | Map critical marks to the visible quotient using constructive Smith coordinates | [_critical_catalogue.py](src/homological_observability/_critical_catalogue.py) |
+| Marked-Poisson limit | Combine stationary masses and path weights under $T\delta^{m-1}\to\theta$ | [_critical_catalogue.py](src/homological_observability/_critical_catalogue.py) |
+| Resource completeness | Check path, digit, cycle, and output limits before returning a complete experiment | [critical_experiment.py](src/homological_observability/critical_experiment.py) |
+
+The [biased C4 guide](docs/CRITICAL_EXPERIMENT.md) derives the conditional
+probabilities $4/5$ and $1/5$ and total critical intensity $5/2$ from exact
+rates. The complete [generated result](examples/biased_c4_critical_result.json)
+contains the stationary law, quotient groups, catalogue, and limit experiment.
+
+[Catalogue tests](tests/test_critical_catalogue.py) compare C3–C5 closed forms,
+nonreversible weights, repeated-vertex walks, zero marks, torsion, and changes
+of reference geodesic. [Public-interface tests](tests/test_critical_product_contract.py)
+check exact parsing, serialization, API/CLI agreement, and atomic resource
+limits. The output is a critical-limit generative specification; it is not an
+exact posterior at finite $(T,\delta)$ or an unconditional critical MAP solver.
+
+## Inputs, outputs, and reproducibility
+
+| Interface | Definition | Checks |
+| --- | --- | --- |
+| Models and results | [Model guide](docs/MODEL_GUIDE.md), [output contract](docs/OUTPUT_CONTRACT.md), and [bundled schemas](src/homological_observability/schemas) | [Schema validation](tests/validate_schema.py), [model tests](tests/test_model_io.py), and topology/critical interface tests |
+| Public Python API and CLI | [Package exports](src/homological_observability/__init__.py), [CLI](src/homological_observability/cli.py) | Equality of the structured API and CLI results |
+| Built-in examples | [Example registry](src/homological_observability/examples.py) | [Frozen example checks](tools/freeze_examples.py) and installed-package checks |
+| Probability and input boundaries | [Numerical methods](docs/NUMERICS.md) | [High-precision interval tests](tests/test_numerical_boundaries.py) and [extreme-input regressions](tests/test_extreme_inputs.py) |
+| Installation and reproduction | [Reproduction API](src/homological_observability/reproduction.py) | [Wheel and sdist checks outside the checkout](tests/validate_distribution.py) |
+| Documentation | [README](README.md) and the linked guides | [Executable examples and local-link checks](tests/test_documentation.py) |
+
+JSON Schema checks structure; runtime validation also checks connectivity,
+edge and readout semantics, and exact-value limits. Built-in examples are
+versioned demonstrations. The frozen tables below are the numerical reference
+for paper reproduction.
+
+## Frozen finite-cycle evidence
+
+| Calculation | Implementation and independent check | Reference |
+| --- | --- | --- |
+| Finite-cycle endpoint and bridge probabilities | [cycles.py](src/homological_observability/cycles.py); [finite-state matrix comparison](tests/test_cycles.py) | [Selected appendix checks](results/selected_appendix_checks.csv) |
+| Winding-sector posterior | [explore_cycles.py](explore_cycles.py); lifted-chain comparison | Reader-selected terminal table |
+| Small-window C3–C6 asymptotics | [reference_appendix.py](src/homological_observability/reference_appendix.py); refinement checks | [Selected appendix checks](results/selected_appendix_checks.csv) |
+| C3/C4 critical count kernels | [critical.py](src/homological_observability/critical.py); independent count laws | [Critical-kernel table](results/critical_kernel_results.csv) |
+| Poisson-averaged binomial MAP identity | [critical.py](src/homological_observability/critical.py); direct mixture and high-precision Bessel comparisons | MAP rows in the appendix table |
+| Reciprocal-lattice peak suppression | [lattice.py](src/homological_observability/lattice.py); positivity, ordering, and refinement checks | Lattice rows in the appendix table and [summary figure](results/companion_summary.png) |
+| Combined reproduction | [reporting.py](src/homological_observability/reporting.py) and [reproduction.py](src/homological_observability/reproduction.py) | [Report](results/REPORT.md) and PNG/SVG figures |
+
+`python quickstart.py` runs the reader-side tests and regenerates these
+calculations. Numerical comparison uses the documented tolerances and leaves
+the committed references unchanged.
+
+## Evidence boundary
+
+Enumeration and graph-atlas checks support the implementation; they do not
+replace proofs for arbitrary finite graphs. The critical task assumes a known
+exact generator. The frozen cycle examples establish neither a universal
+finite-sample error bound nor extensions to one-way support, multigraphs,
+noisy observations, or unknown models. General theorem statements,
+hypotheses, and proofs remain in the manuscript.

homological_observability-1.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: homological-observability
+Version: 1.1.0
+Summary: Homological observability and asymptotic sampling requirements for finite-state Markov jump processes
+Author: HongZheng Liu, YiNuo Tian, Zhiyue Wu, Jianqun Cheng
+License-Expression: MIT
+Project-URL: Repository, https://github.com/yeruciwenrou-dotcom/homological-observability
+Project-URL: Documentation, https://github.com/yeruciwenrou-dotcom/homological-observability#readme
+Project-URL: Issues, https://github.com/yeruciwenrou-dotcom/homological-observability/issues
+Project-URL: Changelog, https://github.com/yeruciwenrou-dotcom/homological-observability/blob/main/CHANGELOG.md
+Keywords: algebraic topology,integer lattices,Markov jump processes,homological observability,information theory,reproducible research,scientific software
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib<4,>=3.10
+Requires-Dist: networkx<4,>=3.6
+Requires-Dist: numpy<3,>=2.3
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: scipy<2,>=1.17
+Requires-Dist: sympy<2,>=1.14
+Provides-Extra: test
+Requires-Dist: build<2,>=1.3; extra == "test"
+Requires-Dist: jsonschema<5,>=4.25; extra == "test"
+Requires-Dist: mpmath<2,>=1.3; extra == "test"
+Requires-Dist: ruff<1,>=0.12; extra == "test"
+Dynamic: license-file
+
+# Homological Observability
+
+A Python toolkit for studying which accumulated cycle histories can be
+recovered from discrete observations of a known finite-state Markov jump
+network. Given a network and optional integer counters, it computes hidden
+cycle directions and their asymptotic sampling requirements. With transition
+rates, it also constructs the critical-limit experiment.
+
+The toolkit provides exact integer-lattice calculations, a command-line
+interface, a Python API, and reproducible finite-cycle examples.
+
+## Installation
+
+Use Python 3.11–3.13. In an activated virtual environment, run:
+
+```bash
+python -m pip install homological-observability
+homological-observability example wedge-c3-c5
+```
+
+The example joins a triangle and a five-cycle at one state and compares the
+cycle information retained by a weighted counter. Models and reference data
+are included in the installed package; no source checkout is needed.
+
+## Python API
+
+```python
+import homological_observability as ho
+
+model = ho.load_example("wedge-c3-c5")
+result = ho.analyze_model(model)
+print(ho.render_text(result))
+```
+
+Use `ho.load_model("triangle.json")` to read your own model and
+`ho.analysis_to_dict(result)` to obtain a structured result. The
+[model guide](https://github.com/yeruciwenrou-dotcom/homological-observability/blob/main/docs/MODEL_GUIDE.md)
+describes inputs and resource limits.
+
+## Reproduce the reference calculations
+
+```bash
+homological-observability reproduce --check --output-dir generated_results
+```
+
+This command compares fresh calculations with the packaged reference data
+and writes a report and figure to `generated_results`. For a source checkout
+with pinned dependencies and the reader-side test suite, follow the
+[reproduction guide](https://github.com/yeruciwenrou-dotcom/homological-observability#reproduce-the-paper-evidence).
+
+## Scope and documentation
+
+The graph must be finite, connected, undirected, and simple. Critical
+experiments require known positive transition rates in both directions on
+each edge. Lattice operations and finite catalogues are exact when the
+calculation completes; sampling requirements and phase labels describe
+long-time asymptotic limits. They do not supply a finite-run error guarantee.
+
+- [Overview and worked examples](https://github.com/yeruciwenrou-dotcom/homological-observability#readme)
+- [Scientific assumptions](https://github.com/yeruciwenrou-dotcom/homological-observability/blob/main/docs/SCIENTIFIC_SCOPE.md)
+- [Results and exit codes](https://github.com/yeruciwenrou-dotcom/homological-observability/blob/main/docs/OUTPUT_CONTRACT.md)
+- [Changes by version](https://github.com/yeruciwenrou-dotcom/homological-observability/blob/main/CHANGELOG.md)
+- [Report an issue](https://github.com/yeruciwenrou-dotcom/homological-observability/issues)
+
+## Companion paper and citation
+
+The software accompanies *Stochastic Histories at Finite Temporal Resolution:
+Homological Observability and Information Phase Diagrams in Markov Jump
+Processes*.
+
+> **Companion paper:** The manuscript is not yet publicly available. An arXiv
+> link will be added when the preprint is posted.
+
+Cite the paper for theoretical results and the software for computations,
+including the software version. Citation metadata is available in
+[CITATION.cff](https://github.com/yeruciwenrou-dotcom/homological-observability/blob/main/CITATION.cff).
+
+Authors: HongZheng Liu, YiNuo Tian, Zhiyue Wu, and Jianqun Cheng.
+
+The software is distributed under the MIT License. The manuscript has its
+own copyright and licensing status.