Expose ring-generator utilities and surface non-ergodic Markov generators

[Copilot]

This change exposes ring-analysis helpers at the package boundary and makes markov_generator explicitly report when stationary-quantity assumptions are violated. It addresses silent misuse by detecting multi-component generators and returning the component count with the generator output.

• Public API surface

  • Exported ergodic_components, ring_generator, and reduce_ring from jump_diffusion_engine.__init__.
  • These utilities are now importable directly from jump_diffusion_engine.

• Ergodicity diagnostics

  • Added ergodic_components(L, rtol=1e-9) to estimate dim ker(L) via singular-value thresholding.
  • markov_generator(...) now computes component count and emits a RuntimeWarning when the generator is not single-component.

• Ring reduction utilities

  • Added ring_generator(N, channels) to build conservative column-generators on Z_N.
  • Added reduce_ring(N, channels) to compute the coprime core (g, N_core, channels_core, L_core) with channel-rate aggregation under reduction.

• Markov generator return contract

  • markov_generator(...) now returns an additional key: n_components.

from jump_diffusion_engine import JumpDiffusionEngine, ergodic_components, ring_generator, reduce_ring

L_ring = ring_generator(12, {2: 1.0, -4: 0.5})
n_comp = ergodic_components(L_ring)

eng = JumpDiffusionEngine(lambda t: 0.5)
out = eng.markov_generator(lambda_val=0.5, n_points=200)
print(out["n_components"])  # warns if != 1

[beanapologist]

Further expose a stochastic systems invariant structure

[beanapologist]

Update pr

reduce_ringis not consistent with the acceptance rule used byring_generator`. In particular, it includes zero- and negative-rate channel keys in the GCD used for reduction, while the generator itself silently ignores those channels. That produces a mathematically incorrect sector count and core size for inputs that the API currently accepts without error. Because the function’s documentation promises an exact reduction and a zero-error spectral replication, this should be corrected before merge.

[beanapologist]

@copilot test

entropy production = current × affinity

[Copilot]

@copilot test

entropy production = current × affinity

Implemented in e828b88: added TestEntropyProduction::test_entropy_production_equals_current_times_affinity, which constructs a biased ring generator, solves the stationary distribution from L, and verifies entropy production equals current × affinity.