Python SDK — `zeq`

Python client for the Zeq platform — NumPy-native compute, Jupyter-friendly, mirrors the TypeScript surface.

Package zeq (PyPI) Runtime Python 3.10+ Source app/packages/sdk-python/ Precision ≤0.1%

Install

pip install zeq

Quickstart

from zeq import ZeqClient, pulse, NIST, PULSE_HZ, ZEQOND_SEC
import numpy as np

# HulyaPulse snapshot — local, no API key
p = pulse()
print(f"Zeqond {p.zeqond} · phase {p.phase:.3f} · R(t) {p.R_t}")

# Local compute
zeq = ZeqClient()
result = zeq.compute(
    domain="quantum_mechanics",
    inputs={"frequency": 5e14},
)
print(f"{result.value} {result.unit}")

# Production compute with API key
prod = ZeqClient(api_key=os.environ["ZEQ_KEY"])
gr = prod.compute(
    domain="general_relativity",
    inputs={"M": 2e30, "r": 3000},
)

NumPy integration

All compute results accept NumPy arrays as inputs; outputs are returned as typed arrays so they compose directly with pandas, SciPy, and matplotlib:

ts = np.linspace(0, 10, 1000)          # 10 s of Unix time
zeqonds = np.array([unix_to_zeqond(t) for t in ts])
rt = modulate(np.ones_like(ts), ts)    # R(t) envelope

import matplotlib.pyplot as plt
plt.plot(zeqonds, rt)

Jupyter

The package registers an IPython magic (%zeq) for interactive compute:

%zeq pulse
%zeq compute --domain quantum_mechanics --input '{"frequency": 5e14}'

Master-equation solve + register dump — `zeq.solve()` / `zeq.multibody()`

ZeqClient.compute_raw() runs the textbook-dispatch path. For the master-equation runtime (full trajectory + register dump + functional energy E = P_φ · Z), use the dedicated client methods.

from zeq import ZeqClient

zeq = ZeqClient(base_url="https://zeqapi.com", api_key=os.environ["ZEQ_KEY"])

# Single-body
r = zeq.solve(
    prompt="feather drop",
    mass=1e-4,
    location="earth",
    medium="air",
    ko_settings={"KO42": 1.0},
)
rd = r["registerDump"]
print(f"errorPct         = {r['errorPct']} %")
print(f"functionalEnergy = {r['functionalEnergy']}  (E = P_φ·Z)")
print(f"phi_range        = {rd['phi_range']}")
print(f"period_s         = {rd['period_s']}")
print(f"frequency_Hz     = {rd['frequency_Hz']}  (× {rd['freq_ratio_fH']} of 1.287 Hz)")
print(f"K_mean / U_mean  = {rd['energy_K_mean']} / {rd['energy_U_mean']}")
print(f"momentum_final   = {rd['momentum_final']}")
print(f"angular_proxy    = {rd['angular_proxy_mean']}")

# Strict autotune (≤ 0.1 % error against analytic reference)
tuned = zeq.solve_strict(
    prompt="free-fall calibration",
    mass=1.0,
    ko_settings={"NM19": 1.0, "NM24": 0.3},
    t_max=0.4, dt=0.001,
    max_iterations=40,
    reference_mode="free-fall",
)
print(tuned["tuneStatus"], tuned["tuneIterations"], tuned["betaFinal"])

# Multi-body — Sun-Earth-Moon
mb = zeq.multibody(
    prompt="sun-earth-moon",
    bodies=[
        {"mass": 1.989e30, "location": "sun",   "object": "sun"},
        {"mass": 5.972e24, "location": "earth", "object": "earth"},
        {"mass": 7.342e22, "location": "moon",  "object": "moon"},
    ],
    ko_settings={"KO42": 1.0, "NM21": 0.5, "GR35": 0.3},
)
for body in mb["bodies"]:
    print(body["object"], body["registerDump"])
for ix in mb["interactions"]:
    print(f"pair ({ix['bodyA']}, {ix['bodyB']}): F_avg = {ix['F_avg']}, sep_mean = {ix['separation_mean']}")

Optional keyword arguments (all numerical / categorical — math never reads the prompt string):

Argument	Purpose
`mass`, `location`, `medium`, `object`	Explicit physics inputs (kwargs, not parsed from `prompt`).
`alpha`, `beta`	KO42.1 / KO42.2 amplitudes.
`ko_settings`	Operator weights, keyed by operator ID.
`t_max`, `dt`	Integration horizon + step. Clamped server-side.
`use_operator_modules`	Use operator-specific physics values (SDK formula path).
`normalize_operators`	Default true; commensurate-scale operator contributions.
`core_only`	Restrict to 8 Core Operator Families.
`reference_mode`	`"free-fall" \| "shm" \| "model"` — analytic comparison target.
`pairwise_coupling`, `pairwise_softening`	(multibody only) γ and ε² in the pairwise term.
`max_iterations`	(solve_strict only) Tuner iteration cap, clamped to `[1, 40]`.

All three methods require an API key. See /api/framework/ for the full reference.

Surface parity

Same symbols as the TypeScript SDK:

ZeqClient — .compute(), .operators(), .pulse(), .verify()
pulse(), modulate(), unix_to_zeqond(), zeqond_to_unix()
compute_by_domain(domain, inputs)
NIST, PULSE_HZ, ZEQOND_SEC, ALPHA_K
get_operators(), get_operators_by_domain(), DOMAINS

Install​

Quickstart​

NumPy integration​

Jupyter​

Master-equation solve + register dump — zeq.solve() / zeq.multibody()​

Surface parity​

See also​