pyhqiv 0.4.2

Horizon-Quantized Informational Vacuum (HQIV) framework — discrete null lattice, phase-horizon Maxwell, octonion algebra, and protein-scale field simulation

pyhqiv — Horizon-Quantized Informational Vacuum (HQIV)

⚠️ Experimental status. All features in this package are experimental. APIs and numerical results may change. Public contribution and feedback are greatly appreciated — please open issues or pull requests on GitHub.

Known issues: The CMB pipeline in particular has known limitations (analytic transfer vs full Boltzmann hierarchy, phenomenological map from C_ℓ template, peak positions/shape vs CLASS-HQIV). See docs/HQIV_CMB_Pipeline.md for details.

---

Why HQIV? HQIV unifies causal-horizon monogamy with discrete null-lattice combinatorics to predict curvature (Ω_k), CMB-consistent ages, and phase-horizon corrections to Maxwell/fluids/molecules. See the paper for the full framework.

Pip-installable Python package implementing the Horizon-Quantized Informational Vacuum (HQIV) framework exactly as defined in the paper:

Ettinger, Steven Jr, Horizon-Quantized Informational Vacuum (HQIV): A Unified Framework from Causal Horizon Monogamy and Discrete Null-Lattice Combinatorics. Zenodo, 2026. https://doi.org/10.5281/zenodo.18794889

Citation

If you use this package in research, please cite the paper. On GitHub you can use the Cite this repository button (from CITATION.cff in the repo root):

@misc{ettinger2026hqiv,
  author       = {Ettinger, Steven Jr},
  title        = {Horizon-Quantized Informational Vacuum (HQIV): A Unified Framework from Causal Horizon Monogamy and Discrete Null-Lattice Combinatorics},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.18794889},
  url          = {https://doi.org/10.5281/zenodo.18794889}
}

Installation

pip install pyhqiv

From source:

git clone https://github.com/disregardfiat/pyhqiv.git && cd pyhqiv
pip install -e .

Also on TestPyPI for pre-release testing:
pip install --index-url https://test.pypi.org/simple/ pyhqiv

Extra	Purpose
ase	ASE for structure/relaxation (protein/crystal)
mda	MDAnalysis for trajectories (protein demo)
qutip	QuTiP for quantum optics
jax	JAX for JIT-accelerated lattice integrals / evolve_to_cmb
pyvista	PyVista for 3D visualization
cosmology	Healpy for full CMB pipeline (maps, C_ℓ, σ₈, LOS/ISW) — optional heavy module
all	All of the above

pip install pyhqiv[ase,mda,qutip,jax,pyvista]
# or
pip install pyhqiv[all]

Quick start

Cosmology (one call): Evolve to the CMB and get Ω_k^true, wall-clock/apparent ages, and lapse:
result = HQIVCosmology().evolve_to_cmb(T0_K=2.725) → Ω_k ≈ 0.0098, age 51.2 / 13.8 Gyr, lapse ≈ 3.96.

Full CMB (T_Pl → now): With pip install pyhqiv[cosmology], run the evolver and get a full-sky map in µK plus σ₈:

from pyhqiv import HQIVUniverseEvolver
import healpy as hp

evolver = HQIVUniverseEvolver(nside=1024)
result = evolver.run_from_T_Pl_to_now()
hp.mollview(result["T_map_muK"], title="HQIV CMB from Planck epoch to now")
print(f"σ₈ = {result['sigma8']:.4f}")

See examples/cmb_mollview_planck.py and examples/cmb_mollview_planck.ipynb for mollview + C_ℓ vs Planck.

from pyhqiv import DiscreteNullLattice, HQIVSystem, HQIVCosmology
import numpy as np

# Cosmology
result = HQIVCosmology().evolve_to_cmb(T0_K=2.725)  # Omega_true_k ≈ 0.0098

# Fields
lattice = DiscreteNullLattice(m_trans=500, gamma=0.40)
sys = HQIVSystem.from_atoms([(0, 0, 0), (1.5, 0, 0)], charges=[1, -1], gamma=0.40)
grid = np.mgrid[-2:2:11j, -2:2:11j, -2:2:11j].reshape(3, -1).T
E, B = sys.compute_fields(grid, t=0.0)

API examples (every module)

import numpy as np
from pyhqiv import (
    # Constants (paper values)
    GAMMA, ALPHA, T_PL_GEV, T_LOCK_GEV, T_CMB_K, M_TRANS,
    COMBINATORIAL_INVARIANT, OMEGA_TRUE_K_PAPER, LAPSE_COMPRESSION_PAPER,
    HBAR_C_EV_ANG, A_LOC_ANG,
    # Lattice & cosmology
    DiscreteNullLattice,
    HQIVCosmology,
    # Phase lift
    HQIVPhaseLift,
    # Algebra (so(8), hypercharge)
    OctonionHQIVAlgebra,
    # Atom & system
    HQIVAtom, HQIVSystem,
    # Fluid (modified NS)
    f_inertia, g_vac_vector, eddy_viscosity, modified_momentum_rhs,
    # Molecular (PROtien)
    molecular,
    # Waveguide
    waveguide,
    # Fields
    PhaseHorizonFDTD,
    # Crystal & response
    HQIVCrystal, hqiv_potential_shift, compute_conductivity, response_tensor_diagonal,
    # Thermodynamics (phase diagrams, EOS, no reference data)
    HQIVThermoSystem, compute_free_energy, HQIVHydrogen, PhaseDiagramGenerator,
    hqiv_answer_thermo, plot_phase_diagram_standard_vs_hqiv, TESTABLE_PREDICTIONS,
)

# --- constants ---
print(GAMMA, COMBINATORIAL_INVARIANT, HBAR_C_EV_ANG)

# --- algebra: so(8) closure, hypercharge 4×4 block ---
alg = OctonionHQIVAlgebra(verbose=False)
dim, _ = alg.lie_closure_dimension()  # 28
data = alg.hypercharge_paper_data()

# --- lattice & cosmology: δE(m), evolve_to_cmb, Ω_k, ages, lapse ---
lattice = DiscreteNullLattice(m_trans=500, gamma=0.40)
result = lattice.evolve_to_cmb(T0_K=2.725)
delta_E = lattice.get_delta_E_grid()
cosmo = HQIVCosmology()
cosmo_result = cosmo.evolve_to_cmb(T0_K=2.725)  # Omega_true_k, 51.2/13.8 Gyr, lapse ≈ 3.96

# --- phase: δθ′(E′), ˙δθ′, lapse ---
phase = HQIVPhaseLift(gamma=0.40)
dtheta = phase.delta_theta_prime(0.5)
dot_dtheta = phase.delta_theta_prime_dot(H_homogeneous=1e-18)

# --- atom: local Θ, φ = 2c²/Θ ---
atom = HQIVAtom(position=(0, 0, 0), charge=1)
phi = atom.phi_local(np.array([[1.0, 0, 0]]))

# --- system: multi-atom, E/B on grid ---
sys = HQIVSystem.from_atoms([(0, 0, 0), (1, 0, 0)], charges=[1, -1])
E, B = sys.compute_fields(np.array([[0.5, 0, 0]]), t=0.0)

# --- fluid: f(a,φ), g_vac, ν_eddy ---
f = f_inertia(0.1, 1.0)
g_vac = g_vac_vector(1.0, 0.5, np.ones(3), np.zeros(3))
nu = eddy_viscosity(Theta_local=1.0, dot_delta_theta=1e-18, l_coh=1e-3, coherence_factor=0.5)

# --- molecular: Θ(Z,coord), bond length, damping, torsion energy ---
theta_C = molecular.theta_local(6, 2)  # ≈ 1.53 Å
r_eq = molecular.bond_length_from_theta(1.53, 1.33)
mag = molecular.damping_force_magnitude(1.0, 0.5, a_loc=1.0)

# Temperature-aware backbone torsion energy and discrete coupling angles for PROtien
# (angles in radians, Θ in Å, T in K):
E_residue = molecular.hqiv_energy_for_angles(
    phi=-1.0,
    psi=0.5,
    theta_local_ang=theta_C,
    temperature=300.0,
)
angles, energies, dE = molecular.coupling_angle_energy_profile(
    "phi",
    theta_local_ang=theta_C,
    temperature=300.0,
    n_states=32,
)

# --- waveguide: k_c², radius, taper, mode solver ---
from pyhqiv.waveguide import kc_squared_hqiv, waveguide_radius_constant_phi, hqiv_waveguide_mode_solver
kc2 = kc_squared_hqiv(omega=2*np.pi*1e9, beta=10.0, m_phase=1, dot_delta_theta=1e-18)
a = waveguide_radius_constant_phi(phi_target=1e10)
gx, gy = np.mgrid[0:1:5j, 0:1:5j]
evals, evecs, mask = hqiv_waveguide_mode_solver(gx, gy, 2*np.pi*1e9, 0.0, n_modes=2)

# --- fields: FDTD ---
fdtd = PhaseHorizonFDTD(shape=(10, 10, 10), dx=0.1, dt=0.05)
fdtd.step()

# --- crystal: PBC, Bloch sum ---
from pyhqiv.atom import HQIVAtom
atoms = [HQIVAtom([0, 0, 0], 0), HQIVAtom([0.5, 0, 0], 0)]
crystal = HQIVCrystal(atoms, lattice_vectors=np.eye(3), supercell_shape=(2, 1, 1))
bloch = crystal.bloch_sum(k_point=[0, 0, 0])
pos_sc = crystal.supercell_positions()

# --- response: conductivity ---
sigma = compute_conductivity(omega=1e10, sigma_0=1.0, phi_avg=1e5)
tensor = response_tensor_diagonal(omega=1e10, dim=3, sigma_0=1.0)

# --- band-gap: potential shift for PySCF ---
V_shift = hqiv_potential_shift(phi_avg=1e-10, dot_delta_theta_avg=1e-18)
# Use V_shift in pyscf.pbc as effective potential shift

Package layout

Path	Description
src/pyhqiv/algebra.py	Octonion HQIV algebra (so(8) closure, hypercharge 4×4 block)
src/pyhqiv/lattice.py	Discrete null lattice, δE(m), T(m), evolve_to_cmb
src/pyhqiv/phase.py	HQIVPhaseLift: δθ′(E′), ˙δθ′, ADM lapse compression
src/pyhqiv/atom.py	HQIVAtom (position, charge, species, local Θ, φ)
src/pyhqiv/system.py	HQIVSystem (multi-atom, monogamy γ, E/B on grid)
src/pyhqiv/fields.py	Phase-horizon FDTD / spectral Maxwell (γ(φ/c²)(˙δθ′/c) terms)
src/pyhqiv/fluid.py	Modified Navier–Stokes: f_inertia, g_vac, ν_eddy (laminar → standard NS)
src/pyhqiv/thermo.py	First-principles thermodynamics: phase diagrams, EOS, critical points (no DAC/reference data)
src/pyhqiv/perturbations.py	Unified linear perturbations with lapse/φ: stellar oscillations, fluid stability, phonons, cosmology (stays in main)
src/pyhqiv/cosmology/	Package: HQIVCosmology (background), HQIVUniverseEvolver (T_Pl→now map + σ₈), hqiv_cmb wrapper
src/pyhqiv/cosmology_full.py	Optional heavy module: σ₈, C_ℓ, universe_evolver, Healpy map, LOS/ISW (install pyhqiv[cosmology])
src/pyhqiv/waveguide.py	HQIV waveguide: k_c²(ω,β,m), constant-φ circle, taper, hyperbolic, mode solver
src/pyhqiv/molecular.py	PROtien: Θ(Z, coord), bond_length_from_theta, damping_force_magnitude, torsion energy + coupling-angle profiles
src/pyhqiv/crystal.py	HQIVCrystal: PBC, supercell, bloch_sum, reciprocal_vectors; high_symmetry_k_path; hqiv_potential_shift
src/pyhqiv/response.py	compute_conductivity, response_tensor_diagonal (phase-horizon corrected)
src/pyhqiv/ase_interface.py	HQIVCalculator (ASE: energy, forces, stress); hqiv_energy_at_positions, hqiv_forces_analytic, hqiv_stress_virial
src/pyhqiv/semiconductors.py	compute_band_gap, dos, effective_mass, compute_conductivity_tensor, dielectric_function_epsilon
src/pyhqiv/defects.py	formation_energy (HQIV vacuum correction), charged_defect_supercell
src/pyhqiv/export.py	export_charge_density_vesta, export_charge_density_ovito; pyscf_hqiv_shift
src/pyhqiv/constants.py	Paper constants (γ, α, T_Pl, 6^7√3, HBAR_C_EV_ANG, A_LOC_ANG, etc.)

Paper numbers (reproduced)

Quantity	Value	Source
Ω_k^true	+0.0098	Shell integral m = 0 … 500
m_trans	500	Discrete–continuous transition
γ	0.40	Entanglement monogamy
α	0.60	G_eff exponent
T_lock	1.8 GeV	QCD lock-in
6^7√3	≈ 4.849×10^5	Combinatorial invariant
Wall-clock age	51.2 Gyr	Lattice → CMB
Apparent age	13.8 Gyr	ADM lapse compression ≈ 3.96×

Tests

pip install -e ".[all]"
pytest tests/ -v

With coverage (optional):

pip install pytest-cov
pytest tests/ -v --cov=pyhqiv --cov-report=term-missing --cov-report=html
# open htmlcov/index.html

CI runs pytest with --cov=pyhqiv --cov-report=term-missing --cov-report=html and uploads the HTML report as an artifact (7-day retention). Config: .coveragerc. To add a coverage badge, integrate Codecov or Coveralls and add their badge to this README.

The test tests/test_paper_numbers.py checks Ω_true_k, γ, combinatorial invariant, lapse factor, and lattice δE(m) / mode counts to 6 decimal places. Additional tests cover ASE calculator (energy/forces/stress), crystal (PBC, k-path), fluid, semiconductors (band_gap, DOS, effective_mass, dielectric), defects, export, and thermo (EOS, phase diagram, hqiv_answer_thermo).

Reproducibility

From the repo root (or with pyhqiv on PYTHONPATH):

python examples/reproduce_paper.py           # all paper table values
python examples/reproduce_paper.py --plot   # tables + figures (requires matplotlib)
python examples/reproduce_paper.py --plot --pyvista  # add 3D figure (requires pyvista)

Figures are written to examples/reproduce_paper_figures/. For a thin HQIV→folding minimizer shim (ASE energy/forces from HQIVSystem), see examples/folding_shim_example.py. Thermodynamics examples (phase diagrams, no reference data): examples/thermo_metallic_hydrogen_phase_diagram.py, examples/thermo_silicon_melting.py, examples/thermo_argon_critical.py, examples/thermo_answer_any_question.py, examples/thermo_ase_phase_stability.py.

Thermodynamics (first principles, no DAC/reference data)

From the single axiom E_tot = m c² + ħ c/Δx with Δx ≤ Θ_local(ρ, T) the package derives phase diagrams, equations of state, and critical points without diamond-anvil or empirical databases:

• HQIVThermoSystem, compute_free_energy(P, T, composition, gamma) — Gibbs free energy with full φ and lapse correction.
• HQIVEquationOfState, HQIVIdealGas, HQIVRealGas, HQIVHydrogen — EOS with lapse; metallic H2 transition at ρ ≈ 0.6–1.0 g/cm³ from φ only.
• PhaseDiagramGenerator — P–T coexistence via Gibbs minimization (G1 = G2).
• hqiv_answer_thermo(question) — One-function pipeline: parse question → build system from axiom → return answer + plot code.
• thermo_fluid_lapse, thermo_crystal_phi, thermo_ase_phase_stability — Hooks with fluid.py, crystal.py, ase_interface.py.
• TESTABLE_PREDICTIONS, plot_phase_diagram_standard_vs_hqiv — Falsifiable predictions and side-by-side standard vs HQIV plots.

Enables the full "space model": solar core, rocket propellants, high-z stellar evolution from one equation → entire phase diagram.

Advanced modeling (perturbations)

Unified linear perturbations with full HQIV lapse/φ corrections — stellar oscillations (Kepler/TESS), fluid instabilities, phonon spectra, cosmological density perturbations:

from pyhqiv import HQIVPerturbations, HQIVSolarCore

background = HQIVSolarCore()  # or HQIVSystem, future HQIVStar/HQIVNeutronStar
pert = HQIVPerturbations(background=background)
modes = pert.stellar_oscillations(l=1, n_max=5)
print([m.period for m in modes])  # periods with lapse-compressed frequencies
print(pert.summary())

CMB pipeline: Full universe evolution to a synthetic CMB map is in docs/HQIV_CMB_Pipeline.md. Use HQIVUniverseEvolver (pyhqiv.cosmology) with run_from_T_Pl_to_now() for a full-sky map (µK) and σ₈; it delegates to the optional module pyhqiv.cosmology_full. Seed from bulk (paper-authoritative): Until baryogenesis is complete, the pipeline should be seeded by HQIV horizon_modes/python/bulk.py. Call get_bulk_seed() (when the HQIV repo is available) and pass it as bulk_seed to the evolver or hqiv_cmb; then Ω_k, H₀, and η come from bulk. Caveat: the current map and σ₈ are phenomenological (C_ℓ template + synfast, growth-based σ₈); the first-principles chain (primordial seeding → forward evolution → LOS projection → anafast) is not yet implemented. See cmb_pipeline_status() and doc §0.1 for the gap.

Materials / semiconductors

For theorists in materials and semiconductors, the package provides:

• Full ASE Calculator — geometry relaxation with HQIV potential:

  from ase.optimize import BFGS
  from pyhqiv import HQIVCalculator
  calc = HQIVCalculator(gamma=0.40)
  atoms.calc = calc
  BFGS(atoms).run()   # get_potential_energy(), get_forces(), get_stress()
  

  See examples/relax_with_hqiv.py.

• HQIVCrystal — PBC, supercell, Bloch sum; high_symmetry_k_path() for k-path generation (e.g. "GXWG").

• Semiconductor API — compute_band_gap(), dos(), effective_mass(), compute_conductivity_tensor(), dielectric_function_epsilon() with HQIV corrections. See examples/silicon_bandgap_hqiv.py.

• Defect utilities — formation_energy() with HQIV vacuum correction; charged_defect_supercell() for charged-defect supercells.

• Hybrid interfaces — hqiv_potential_shift() (and pyscf_hqiv_shift()) for PySCF periodic band structure; export_charge_density_vesta() / export_charge_density_ovito() for charge-density export with HQIV modulation.

Extensibility

Custom lattices and phase lifts can implement the public protocols/base classes:

• NullLatticeProtocol / NullLatticeBase — implement shell_temperature, delta_E, mode_count_per_shell, omega_k_true, evolve_to_cmb, get_delta_E_grid, get_cumulative_mode_counts.
• PhaseLiftProtocol / PhaseLiftBase — implement delta_theta_prime, delta_theta_prime_dot, lapse_compression, maxwell_lift_coefficient.

Subclass the base classes for a new lattice or phase model; the built-in DiscreteNullLattice and HQIVPhaseLift satisfy the protocols by default.

Pre-commit

pip install pre-commit && pre-commit install

Runs ruff (lint + format), mypy, and generic hooks on commit. Config: .pre-commit-config.yaml.

For releases, the CI build runs scripts/update_citation_cff.py to set CITATION.cff version and date-released from the current tag/date. You can run it manually with --version X.Y.Z --date YYYY-MM-DD to sync before a release.

Contributing

Public contribution and feedback are greatly appreciated. Please open issues or pull requests on GitHub. All features are experimental; we welcome bug reports, documentation improvements, and suggestions.

License

MIT.