Skip to content

fused_chaos_index

The main API module for the Public Fused Chaos Index package.

Overview

This module provides the core functionality for computing the Fused Chaos Index (FCI) from cosmological data. The FCI is a graph-spectral metric derived from k-NN graph Hamiltonians, used to analyze spatial structure in galaxy catalogs and other point distributions.

Core Components

Operational Pipeline

The operational pipeline transforms galaxy positions into FCI metrics:

  1. k-NN Graph Construction - Build a weighted graph from spatial positions
  2. Hamiltonian Spectrum - Compute eigenvalues via sparse matrix methods
  3. IPR & SFF - Calculate Inverse Participation Ratio and Spectral Form Factor
  4. FCI Computation - Combine spectral features into final index

SYK-Collatz Constant

The SYK-Collatz module computes a theoretical constant based on the Sachdev-Ye-Kitaev model with Collatz-inspired perturbations.

Meta Tools

Evidence aggregation and robustness diagnostics:

  • combine_evidence_heuristic - Bayesian-inspired evidence combination
  • keyword_risk_audit - Keyword-based risk assessment
  • ablation_sensitivity - Sensitivity analysis for parameter variations

Quick Start

from fused_chaos_index import StreamlinedFCIPipeline, run_operational_demo
import numpy as np

# Generate synthetic data
positions = np.random.rand(1000, 2)

# Run pipeline
pipeline = StreamlinedFCIPipeline(positions, k=10, seed=42)
results = pipeline.run()

print(f"FCI: {results['fci']:.6f}")
print(f"IPR: {results['ipr']:.6f}")
print(f"SFF Peak: {results['sff_peak_height']:.6f}")

API Reference

fused_chaos_index

StreamlinedFCIPipeline

Minimal operational pipeline: points → graph → spectrum → IPR/SFF → FCI.

This is a cleaned, package-friendly extraction of the core logic from the research workspace.

Dependencies are intentionally minimal: numpy + scipy.

build_knn_graph(positions)

Construct a symmetric k-NN graph with exponential distance weights.

compute_fused_chaos_index(ipr, sff)

FCI = (⟨IPR⟩^{-1}) / (ramp_slope), then normalized by sqrt(n_states).

compute_ipr(eigenvectors)

Inverse Participation Ratio: IPR_α = Σ_i |ψ_α(i)|^4.

compute_sff(eigenvalues, *, max_time=50.0, n_times=30)

Spectral form factor (rank-based unfolding): SFF(t) = |Sigma_j exp(-i E_j t)|^2.

Note: This uses a rank-based unfolding (eigenvalues replaced by their rank indices). This is suitable for qualitative regime classification (localized vs delocalized) but does not preserve spectral density information. It should not be compared quantitatively to RMT predictions for the spectral rigidity parameter beta.

compute_spectrum(hamiltonian, *, n_eigenstates=50)

Compute the lowest-energy eigenpairs via sparse eigensolver.

construct_anderson_hamiltonian(adjacency)

Anderson tight-binding Hamiltonian: H = diag(disorder) - A.

coordinates_to_comoving_cartesian(catalog)

Convert (ra, dec, z) to comoving Cartesian coordinates (Mpc).

Uses the Hubble-law approximation $D_c \approx (c z) / H_0$, which is valid for $z \ll 1$. At $z = 0.3$ the error relative to the integrated Friedmann equation ($\Omega_m = 0.3$, $\Omega_\Lambda = 0.7$) is ~8%.

run(*, n_galaxies=2000, n_eigenstates=50)

Run the full pipeline end-to-end and return structured results.

simulate_euclid_like_catalog(*, n_galaxies=5000)

Generate a small synthetic catalog in (ra, dec, z).

Note: this is synthetic data for demonstration only.

ablation_sensitivity(x, y, *, n_trials=200, method='spearman', seed=42)

Measure robustness of a correlation to single-point ablations.

combine_evidence_heuristic(evidences, prior=0.5)

Heuristically combine multiple evidence strengths into a single score.

Implements a sequential Bayes-style update on odds, treating each ev as an evidence strength in [0,1]. Without calibration, this is not a probability.

compute_syk_collatz_fci_constant(*, N=32, kurt_collatz=3.72, kurt_syk=-1.23, method='analytic', seed=42, n_mc_samples=200000)

Compute the SYK–Collatz constant-approximation FCI value.

The research script effectively uses a constant approximation: $C = (kurt_{Collatz} * kurt_{SYK}) * \int_0^\infty (1/N) e^{-F/N} dF$.

With that integrand, the integral is 1, so the analytic result is simply: $C = kurt_{Collatz} * kurt_{SYK}$.

Parameters

method: "analytic" (default), "quad", or "mc".

keyword_risk_audit(text, hazard_keywords=None)

Flag simple dual-use keywords in free-form text.

Conservative preflight filter; not a substitute for policy/expert review.

run_public_suite(*, run_dir, profile='smoke', allow_network=False, frontier_clusters_json=None, tng_base_path=Path('./TNG300-1/output'), skip_tng=False, operational_n_galaxies=2000, operational_k=10, operational_seed=42, operational_n_eigenstates=40, syk_N=32, syk_kurt_collatz=3.72, syk_kurt_syk=-1.23, syk_method='analytic', frontier_manifest=Path('validation_results/frontier_evidence_suite_manifest.json'), universality_manifest=Path('validation_results/universality_ground_truth_suite_manifest.json'))

Run the public/offline-first suite and write a single suite manifest.

This is intentionally lightweight: - No downloads - No bundled large artifacts - Produces a manifest suitable for provenance and quick sanity checks