Metadata-Version: 2.4
Name: zeq-galaxy-tools
Version: 1.287.126
Summary: 12 molecular and scientific Galaxy tools (PubChem 3D, RCSB PDB, AlphaFold, ChEMBL, MD Simulator, NIST Spectral + 6 TM siblings) — powered by the Zeq API at zeq.dev with 1.287 Hz HulyaPulse synchronisation and HMAC ZeqProof verification.
Author: Zeq. H
License-Expression: LicenseRef-1.287HZ
Project-URL: Homepage, https://www.zeq.dev
Project-URL: Documentation, https://www.zeq.dev/sdk/
Project-URL: Galaxy ToolShed, https://toolshed.g2.bx.psu.edu/view/Zeq
Project-URL: Zeq Paper, https://doi.org/10.5281/zenodo.18158152
Project-URL: Framework Paper, https://doi.org/10.5281/zenodo.15825138
Keywords: zeq,hulyapulse,galaxy,bioinformatics,molecular-biology,structural-biology,cheminformatics,pubchem,pdb,alphafold,chembl,molecular-dynamics,spectroscopy,nist,zeqond,zeqproof,ko42,hulyas,protein-structure,drug-discovery,generative-mathematics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Zeq Galaxy Tools

> **Beta** — These plugins are currently in beta. Features, APIs, and tool behaviour may change between releases. Feedback and bug reports are welcome.

**Twelve molecular and scientific connector tools for the [Galaxy](https://galaxyproject.org/) bioinformatics platform** — 6 original tools plus 6 time-modulation (TM) siblings, each powered by the [Zeq API](https://www.zeq.dev) with 1.287 Hz HulyaPulse synchronisation and cryptographically signed ZeqProof verification.

[![PyPI version](https://badge.fury.io/py/zeq-galaxy-tools.svg)](https://pypi.org/project/zeq-galaxy-tools/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![Galaxy ToolShed](https://img.shields.io/badge/Galaxy-ToolShed-blue)](https://toolshed.g2.bx.psu.edu/view/Zeq)
[![License: 1.287HZ](https://img.shields.io/badge/License-1.287HZ-lightgrey.svg)](https://hulyas.org)

---

## What is the Zeq API?

The [Zeq API](https://www.zeq.dev) is a generative-mathematics computation kernel built on the HULYAS Master Equation and the KO42 metric tensioner. It provides deterministic, reproducible physics computations across **236 protocols**, **1,536 kinematic operators**, and **64 scientific domains** in 5 domain groups (Core Physics, Extended Physics, Applied Sciences, Industry, and Frontier research).

Every computation is signed with an **HMAC ZeqProof receipt** that can be independently verified, and results are reproducible against NIST CODATA 2018 constants. The API is not a simulation or approximation layer — it is a real computation engine with cryptographic proof of correctness.

**Key concepts:**

- **HulyaPulse** — a 1.287 Hz temporal synchronisation clock that phase-locks all computations to a universal timebase
- **Zeqond** — the fundamental time unit of 0.777 seconds (1 / 1.287 Hz), used as the computational heartbeat
- **KO42 Metric Tensioner** — the mandatory prime-directive operator that modulates spacetime metrics on every calculation: `ds^2 = g_(mu,nu) dx^mu dx^nu + alpha * sin(2pi * 1.287 * t) dt^2`
- **HULYAS Master Equation** — the unifying field equation that compiles all selected operators into a single expression
- **ZeqProof** — an HMAC-signed receipt attached to every API response, allowing independent cryptographic verification of results
- **7-Step Zeqond Protocol** — the mandatory computation pipeline: KO42 prime directive, operator selection (up to 3 + KO42), scale matching, precision tuning (error less than or equal to 0.1%), compilation via HULYAS Master Equation, execution via Functional Equation, and verification

Full SDK documentation (Learn, Build, Reference, Operate): **[zeq.dev/sdk](https://www.zeq.dev/sdk/)**

---

## What Are Zeq Galaxy Tools?

This package wraps the Zeq API into Galaxy-compatible tool definitions, so researchers can run molecular and scientific computations directly inside Galaxy workflows — with the same ZeqProof verification and HulyaPulse synchronisation available from the raw API.

Each tool connects to a major public scientific data source (PubChem, RCSB PDB, AlphaFold, ChEMBL, NIST) or runs a molecular dynamics simulation engine, and optionally applies 1.287 Hz temporal modulation to the results.

### Original Tools (6)

| Tool | What it does | Data Source |
|------|-------------|-------------|
| `zeq-pubchem-3d` | Fetches 3D molecular structures, bond lengths, and chemical properties | [PubChem](https://pubchem.ncbi.nlm.nih.gov/) |
| `zeq-rcsb-pdb` | Retrieves experimental protein structures from X-ray crystallography and cryo-EM | [RCSB PDB](https://www.rcsb.org/) |
| `zeq-alphafold` | Downloads AI-predicted protein structures with per-residue confidence scores | [AlphaFold DB](https://alphafold.ebi.ac.uk/) |
| `zeq-chembl` | Queries bioactivity data — IC50, EC50, Ki values, and pharmacological assays | [ChEMBL](https://www.ebi.ac.uk/chembl/) |
| `zeq-md-simulator` | Runs molecular dynamics simulations using Lennard-Jones, Morse, and Coulomb potentials | Built-in simulation engine |
| `zeq-nist-spectral` | Looks up atomic spectral emission lines for 16 elements | [NIST ASD](https://www.nist.gov/pml/atomic-spectra-database) |

### Time-Modulation (TM) Siblings (6)

Each original tool has a TM sibling that applies **1.287 Hz HulyaPulse temporal filtering** to the output data. This modulates results using the Zeq equation `R(t) = S(t) [1 + alpha * sin(2pi * 1.287 * t + phi_0)]`, adding a phase-coherent temporal envelope to every data point.

| Tool | Base tool |
|------|-----------|
| `zeq-pubchem-3d-tm` | zeq-pubchem-3d |
| `zeq-rcsb-pdb-tm` | zeq-rcsb-pdb |
| `zeq-alphafold-tm` | zeq-alphafold |
| `zeq-chembl-tm` | zeq-chembl |
| `zeq-md-simulator-tm` | zeq-md-simulator |
| `zeq-nist-spectral-tm` | zeq-nist-spectral |

---

## Installation

### From PyPI

```bash
pip install zeq-galaxy-tools
```

### From Galaxy ToolShed

All 12 tools are available on the [Galaxy ToolShed](https://toolshed.g2.bx.psu.edu/view/Zeq) and can be installed directly into any Galaxy instance by an administrator.

---

## Getting a Zeq API Key

**Free demo key (100 calls/day, no signup):**

```bash
curl -s https://www.zeq.dev/api/demo-key
```

Returns:
```json
{"key": "zeq_ak_demo_...", "plan": "demo", "dailyLimit": 100}
```

**Keyless proof endpoint (10 calls/min/IP, no auth at all):**

```bash
curl -s https://www.zeq.dev/api/zeq/prove \
  -H "Content-Type: application/json" \
  -d '{"operators": ["KO42"], "inputs": {"t": 1.287}}'
```

Returns a signed 7-step protocol output with HMAC ZeqProof that you can verify against textbook physics.

For production keys, visit **[zeq.dev](https://www.zeq.dev)**.

---

## Usage

### Command Line

Every tool installs as a standalone CLI command:

```bash
# Fetch aspirin 3D structure from PubChem
zeq-pubchem-3d --zeq_api_key YOUR_KEY --molecule aspirin --mode all \
  --output_atoms atoms.tsv --output_bonds bonds.tsv \
  --output_properties props.tsv --output_json summary.json

# Fetch haemoglobin structure from RCSB PDB
zeq-rcsb-pdb --zeq_api_key YOUR_KEY --pdb_id 4HHB --mode all \
  --output_atoms atoms.tsv --output_summary summary.tsv --output_json data.json

# Get AlphaFold predicted structure for human haemoglobin subunit alpha
zeq-alphafold --zeq_api_key YOUR_KEY --uniprot_id P69905 --mode all \
  --output_atoms atoms.tsv --output_confidence conf.tsv --output_json summary.json

# Query ChEMBL for ibuprofen bioactivity data
zeq-chembl --zeq_api_key YOUR_KEY --molecule ibuprofen --mode all \
  --output_activities activities.tsv --output_molecule mol.tsv --output_json data.json

# Run a Lennard-Jones molecular dynamics simulation
zeq-md-simulator --zeq_api_key YOUR_KEY --potential lennard_jones \
  --num_particles 50 --num_steps 1000 \
  --output_trajectory traj.tsv --output_energy energy.tsv --output_json summary.json

# Look up iron emission spectrum from NIST
zeq-nist-spectral --zeq_api_key YOUR_KEY --element Fe --mode all \
  --output_lines lines.tsv --output_spectrum spectrum.tsv --output_json summary.json
```

Add `--hulyapulse` to any original tool to enable 1.287 Hz temporal modulation. The TM siblings (`zeq-pubchem-3d-tm`, etc.) apply it by default.

### Galaxy Workflows

Once installed from the ToolShed, the tools appear under the **Zeq** section in Galaxy's tool panel. Each tool accepts input parameters through Galaxy's standard form interface and produces tabular (.tsv) and JSON outputs that can be piped into downstream Galaxy workflow steps.

---

## How It Works — Architecture

```
User / Galaxy Workflow
        |
        v
+------------------+
| Zeq Galaxy Tool  |    (this package — CLI wrapper + Galaxy XML)
| e.g. zeq-rcsb-pdb|
+------------------+
        |
        v
+------------------+
|   Zeq API        |    (https://www.zeq.dev)
|   /api/zeq/compute
+------------------+
    |           |
    v           v
+--------+  +----------+
| KO42   |  | Operators|    1,536 operators across 64 domains
| Metric |  | (QM, NM, |    (Quantum Mechanics, Newtonian, General
| Tensor |  |  GR, CS) |     Relativity, Computer Science, and more)
+--------+  +----------+
    |           |
    v           v
+------------------+
| HULYAS Master    |    Compile all operators into one expression
| Equation         |
+------------------+
        |
        v
+------------------+
| ZeqProof (HMAC)  |    Cryptographic receipt — verify with
|                  |    POST /api/zeq/verify
+------------------+
        |
        v
  .tsv + .json outputs
  (Galaxy-compatible)
```

1. The Galaxy tool collects user parameters (molecule name, PDB ID, element, etc.)
2. It calls the Zeq API at `zeq.dev/api/zeq/compute` with the appropriate operators
3. The API runs the 7-Step Zeqond Protocol: applies KO42, selects domain operators, compiles via the HULYAS Master Equation, executes, and verifies precision is within 0.1% error
4. Results come back with a signed ZeqProof HMAC receipt
5. The tool writes Galaxy-compatible .tsv and .json output files

---

## The Zeq API — Endpoints Reference

| Endpoint | Auth | Description |
|----------|------|-------------|
| `GET /api/health` | None | Liveness check |
| `GET /api/zeq/pulse` | None | Live HulyaPulse — current Zeqond, phase, R(t) |
| `POST /api/zeq/prove` | None (10/min/IP) | Keyless KO42 proof for verification |
| `GET /api/demo-key` | None | Get a free demo key (100 calls/day) |
| `GET /api/operators` | None | Full operator registry (1,536 operators) |
| `GET /api/operators/categories` | None | 64 domain categories across 5 groups |
| `POST /api/zeq/compute` | Bearer key | Full 7-step computation with ZeqProof |
| `POST /api/zeq/verify` | Bearer key | Verify a ZeqProof HMAC receipt |
| `GET /api/zeq/pulse/stream` | Bearer key | Server-Sent Events live tick (every 777 ms) |

Full OpenAPI spec: [zeq.dev/openapi.json](https://www.zeq.dev/openapi.json)

---

## Operator Coverage

The Zeq API provides **1,536 kinematic operators** organised into **64 scientific domains** across **5 domain groups**:

| Domain Group | Domains | Example Areas |
|-------------|---------|---------------|
| **Core Physics** | 16 | Classical Mechanics, Electromagnetism, Quantum Mechanics, Thermodynamics, Optics, Fluid Dynamics, Gravitational Physics |
| **Extended Physics** | 11 | Astrophysics, Cosmology, Condensed Matter, Particle Physics, Plasma Physics, Nuclear Physics |
| **Applied Sciences** | 12 | Biophysics, Chemical Physics, Materials Science, Geophysics, Oceanography, Climate Modelling |
| **Industry** | 12 | Aerospace Engineering, Biomedical Engineering, Renewable Energy, Semiconductor Physics, Telecommunications |
| **Frontier** | 13 | Consciousness Studies, Dark Energy Models, Emergent Complexity, Quantum Gravity, Analogue Gravity |

Each domain contains 24 operators. Every operator has a formal equation, unit definitions, and is compiled through the HULYAS Master Equation during computation.

---

## Requirements

- Python 3.8 or later
- A Zeq API key — get a free demo key instantly with `curl https://www.zeq.dev/api/demo-key`
- No external Python dependencies (standard library only)

---

## Citations

If you use Zeq Galaxy Tools in published research, please cite:

- Zeq, Hammoudeh. *ZEQ OS: Universal Proper-Time Modulation — Synchronized Physics Across Quantum, Classical, and Relativistic Domains.* [doi.org/10.5281/zenodo.18158152](https://doi.org/10.5281/zenodo.18158152)
- Zeq, Hammoudeh; Zeq, Aydan. *ZEQ OS — EVOLUTION OF MATHEMATICS: A Synchronized Computational Formalism Featuring HULYAS Math, Kinematic Operators, 1.287 Hz HulyaPulse & the 0.777s Zeqond for Analysis Across Quantum to Relativity.* [doi.org/10.5281/zenodo.15825138](https://doi.org/10.5281/zenodo.15825138)

If you use AlphaFold data, also cite:
- Jumper et al. (2021). *Highly accurate protein structure prediction with AlphaFold.* Nature. [doi.org/10.1038/s41586-021-03819-2](https://doi.org/10.1038/s41586-021-03819-2)

---

## Links

- **Zeq API:** [zeq.dev](https://www.zeq.dev)
- **SDK Documentation:** [zeq.dev/sdk](https://www.zeq.dev/sdk/)
- **Galaxy ToolShed:** [toolshed.g2.bx.psu.edu/view/Zeq](https://toolshed.g2.bx.psu.edu/view/Zeq)
- **OpenAPI Spec:** [zeq.dev/openapi.json](https://www.zeq.dev/openapi.json)
- **Homepage:** [hulyas.org](https://hulyas.org)

---

## License

1.287 HULYAS ZEQ Public License (1.2
