Instructions to use Premchan369/Q-TensorFormer with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use Premchan369/Q-TensorFormer with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("text-generation", model="Premchan369/Q-TensorFormer", trust_remote_code=True)

# pip install -U transformers accelerate
# Load model directly
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("Premchan369/Q-TensorFormer", trust_remote_code=True, device_map="auto")

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use Premchan369/Q-TensorFormer with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "Premchan369/Q-TensorFormer"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "Premchan369/Q-TensorFormer",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Use Docker

docker model run hf.co/Premchan369/Q-TensorFormer

SGLang

How to use Premchan369/Q-TensorFormer with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "Premchan369/Q-TensorFormer" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "Premchan369/Q-TensorFormer",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "Premchan369/Q-TensorFormer" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "Premchan369/Q-TensorFormer",
		"prompt": "Once upon a time,",
		"max_tokens": 512,
		"temperature": 0.5
	}'

Docker Model Runner
How to use Premchan369/Q-TensorFormer with Docker Model Runner:
```
docker model run hf.co/Premchan369/Q-TensorFormer
```

Q-TensorFormer / docs /CLAIM_TO_CODE_MAP.md

Premchandyadav369

feat(research): Turn Q-TensorFormer into a verified research system with LFS figure assets

0e4850b about 2 months ago

preview code

Raw History Blame Contribute Delete

7.83 kB

# Claim-to-Code Mapping: Architectural Consistency & Empirical Traceability

This document establishes 1-to-1 traceability between every architectural, mathematical, systems, and performance claim in **Q-TensorFormer** and the underlying codebase implementation and empirical benchmark runners.

---

## 1. Traceability Matrix

| # | Major Claim | Source File(s) | Class / Function | Exact Implementation Mechanism | Experiment Verifying Claim | Empirical Result File | Confidence & Classification |
|---|---|---|---|---|---|---|---|
| **1** | **Dynamic Per-Token Tensor Rank Adaptation** | `src/tensor_layers.py`<br>`src/blocks.py` | `TTLinear.set_rank`<br>`TTLinear.forward_token_grouped` | Zero-SVD nested tensor core slicing $\mathcal{G}[1:r, :, :, 1:r]$ for $r \in \{1, 2, 4, 8\}$ with token-grouped batching. | `experiments/run_adaptive_rank_validation.py` | `outputs/adaptive_rank_results.json` | **MEASURED** (High) |
| **2** | **Continuous 8D Information State Vector** | `src/information_state.py` | `TokenInformationState.forward` | Real-time computation of $[S_t, H_t, U_t, A_t, R_t, L_t, M_t, B_t]$ with EMA running variance normalization. | `experiments/run_information_state_ablation.py` | `outputs/information_state_ablation.json` | **MEASURED** (High) |
| **3** | **Marginal Value Resource Allocation** | `src/resource_allocator.py` | `InformationValueAllocator`<br>`MarginalValueModel` | Evaluates $\text{Value}(a \mid \mathbf{z}_t) = \Delta \hat{Q} / (\Delta C_{\text{eff}} + \epsilon)$ across combinatorial action space. | `experiments/run_marginal_value_model.py` | `outputs/marginal_value_results.json` | **MEASURED** (High) |
| **4** | **Closed-Loop PID Dual Multiplier Control** | `src/resource_allocator.py` | `PIDDualSubgradientController.update` | Proportional-integral-derivative tuning of $\boldsymbol{\lambda} = [\lambda_l, \lambda_m, \lambda_e, \lambda_b]^T$ on constraint error $e(t) = \mathcal{C}(t) - \mathcal{B}$. | `experiments/run_controller_convergence.py` | `outputs/controller_convergence.json` | **MEASURED** (High) |
| **5** | **Anti-Chattering Hysteresis Stabilization** | `src/resource_allocator.py` | `InformationValueAllocator.forward` | Dual-threshold switching logic: suppresses route changes unless $\Delta U \ge \tau_{\text{hyst}}$ and cooldown elapsed. | `experiments/run_hysteresis_validation.py` | `outputs/hysteresis_results.json` | **MEASURED** (High) |
| **6** | **Nested TT Slicing Correctness** | `src/tensor_layers.py` | `TTLinear.get_active_cores` | Slices pre-allocated cores along bond dimensions without re-decomposition or runtime SVD. | `experiments/run_nested_tt_analysis.py` | `outputs/nested_tt_analysis.json` | **MEASURED** (High) |
| **7** | **Grouped-Query Attention (GQA) Memory Savings** | `src/attention.py` | `MultiHeadAttention.forward` | Decoupled $N_q / N_{kv}$ with zero-copy view broadcasting, reducing KV cache entries by up to 75%. | `experiments/run_gqa_audit.py` | `outputs/gqa_audit.json` | **MEASURED** (High) |
| **8** | **Multi-Precision Adaptive KV Cache** | `src/kv_cache.py` | `AdaptiveKVCache`<br>`QuantizedKVTensor` | Dynamic switching between FP16, symmetric INT8, and asymmetric packed INT4 with attention-sink eviction. | `experiments/run_kv_rate_distortion.py` | `outputs/kv_rate_distortion.json` | **MEASURED** (High) |
| **9** | **Quantum Kernel Self-Attention (QKSAM)** | `src/quantum_backend.py`<br>`src/attention.py` | `QuantumBackend.compute_kernel_matrix` | Evaluates $K(\mathbf{q}, \mathbf{k}) = \text{Tr}[\rho(\mathbf{q})\rho(\mathbf{k})]$ via parameterized quantum circuits with PennyLane. | `experiments/run_quantum_utility.py` | `outputs/quantum_utility.json` | **SIMULATED** (Disclosed Classical Overhead) |
| **10** | **Meyer-Wallach Entanglement Metric** | `src/quantum_backend.py` | `compute_meyer_wallach_entanglement` | Exact state entanglement capacity $Q(|\psi\rangle) = \frac{8}{n}\sum \det(\rho_k) \in [0, 1]$. | `tests/test_advanced_features.py` | PyTest Suite Report | **MEASURED** (Mathematical Definition) |
| **11** | **Calibrated Early-Exit Depth Routing** | `src/blocks.py` | `HybridBlock.forward` | Evaluates epistemic uncertainty $U_t < \gamma_{\text{exit}}$ to bypass downstream blocks via identity residual addition. | `experiments/run_comprehensive_comparison.py` | `outputs/comprehensive_comparison.json` | **MEASURED** (High) |
| **12** | **Hardware Roofline Model Analysis** | `src/hardware_cost_model.py` | `HardwareRooflineAnalyzer` | Computes arithmetic intensity $I = \text{FLOPs} / \text{Byte}$, ridge points, and memory/compute bound boundaries across devices. | `src/hardware_cost_model.py` | `outputs/comprehensive_comparison.json` | **ESTIMATED** (Level 2 Calibrated Model) |
| **13** | **Memory Traffic per Token (Bytes/tok)** | `src/tensor_layers.py`<br>`src/attention.py` | `get_memory_traffic` | Tracks physical bytes read (weights + activations) and written per forward pass. | `experiments/run_detailed_latency_profiling.py` | `outputs/detailed_latency_results.json` | **MEASURED** (High) |
| **14** | **Multi-Level Energy Profiling** | `src/hardware_cost_model.py` | `HardwareCostModel.estimate_energy_uj` | Multi-level hierarchy (Level 1: Analytical, Level 2: Calibrated Device Power $\times$ Wall-Clock Time, Level 3: Sensors). | `experiments/run_comprehensive_comparison.py` | `outputs/comprehensive_comparison.json` | **ESTIMATED** (Level 2 Clearly Disclosed) |
| **15** | **Multi-Baseline Comparison (11 Models)** | `src/baselines.py`<br>`experiments/` | `DenseBaseline`, `StaticTT`, `INT8/INT4 PTQ`, `H2O`, `GQA` | Standardized evaluation of 11 models under identical sequence lengths, batch sizes, and token budgets. | `experiments/run_comprehensive_comparison.py` | `outputs/comprehensive_comparison.json` | **MEASURED** (High) |
| **16** | **Multi-Dimensional Pareto Dominance** | `experiments/run_pareto_frontiers.py` | `compute_pareto_hypervolume` | Multi-point trade-offs across Quality vs Latency, Memory, Energy, Bandwidth, and KV size. | `experiments/run_pareto_frontiers.py` | `outputs/pareto_frontiers.json` | **MEASURED** (High) |

---

## 2. Key Code-Architecture Consistency Resolutions

### A. Per-Token Rank Execution in Sequences
- **Previous state**: In multi-token prefill sequences, `TTLinear.set_rank()` set a single global rank for the layer based on sequence-averaged utility.
- **Resolution**: Implemented `forward_token_grouped()` in `TTLinear` allowing each token in a sequence to be routed to its selected rank $r_t \in \{1, 2, 4, 8\}$, contracted through the sliced core, and scattered back in order.
### B. Removal of Theoretical Convergence Guarantees
- **Previous state**: README claimed "guarantees asymptotic convergence to KKT boundary".
- **Resolution**: Reformulated to "empirically stable closed-loop tracking". Created `experiments/run_controller_convergence.py` measuring actual settling time ($t_{\text{settle}}$), maximum overshoot ($M_p$), and steady-state error ($e_{\text{ss}}$) under workload step changes.

### C. Removal of "Zero Overhead" Claims
- **Previous state**: Slicing previously cited as zero-latency extraction (0.00 ms).
- **Corrected status**: Empirically measured tensor slicing pointer arithmetic overhead (~20-50 µs per layer on CPU/GPU) is explicitly disclosed and included in all latency breakdowns in `experiments/run_adaptive_rank_validation.py` and reported accurately.

### D. Quantum Simulation Overhead Disclosure
- **Previous state**: Emphasized theoretical quantum expressibility without stating classical CPU simulation penalty.
- **Resolution**: Full disclosure in documentation: running PennyLane statevector simulation on classical CPUs/GPUs incurs $+100\%\text{–}300\%$ latency overhead. Documented the exact epistemic uncertainty threshold required to justify quantum pathway activation.

	# Claim-to-Code Mapping: Architectural Consistency & Empirical Traceability

	This document establishes 1-to-1 traceability between every architectural, mathematical, systems, and performance claim in Q-TensorFormer and the underlying codebase implementation and empirical benchmark runners.

	---

	## 1. Traceability Matrix

	\| # \| Major Claim \| Source File(s) \| Class / Function \| Exact Implementation Mechanism \| Experiment Verifying Claim \| Empirical Result File \| Confidence & Classification \|
	\|---\|---\|---\|---\|---\|---\|---\|---\|
	\| 1 \| Dynamic Per-Token Tensor Rank Adaptation \| `src/tensor_layers.py`<br>`src/blocks.py` \| `TTLinear.set_rank`<br>`TTLinear.forward_token_grouped` \| Zero-SVD nested tensor core slicing $\mathcal{G}[1:r, :, :, 1:r]$ for $r \in \{1, 2, 4, 8\}$ with token-grouped batching. \| `experiments/run_adaptive_rank_validation.py` \| `outputs/adaptive_rank_results.json` \| MEASURED (High) \|
	\| 2 \| Continuous 8D Information State Vector \| `src/information_state.py` \| `TokenInformationState.forward` \| Real-time computation of $[S_t, H_t, U_t, A_t, R_t, L_t, M_t, B_t]$ with EMA running variance normalization. \| `experiments/run_information_state_ablation.py` \| `outputs/information_state_ablation.json` \| MEASURED (High) \|
	\| 3 \| Marginal Value Resource Allocation \| `src/resource_allocator.py` \| `InformationValueAllocator`<br>`MarginalValueModel` \| Evaluates $\text{Value}(a \mid \mathbf{z}_t) = \Delta \hat{Q} / (\Delta C_{\text{eff}} + \epsilon)$ across combinatorial action space. \| `experiments/run_marginal_value_model.py` \| `outputs/marginal_value_results.json` \| MEASURED (High) \|
	\| 4 \| Closed-Loop PID Dual Multiplier Control \| `src/resource_allocator.py` \| `PIDDualSubgradientController.update` \| Proportional-integral-derivative tuning of $\boldsymbol{\lambda} = [\lambda_l, \lambda_m, \lambda_e, \lambda_b]^T$ on constraint error $e(t) = \mathcal{C}(t) - \mathcal{B}$. \| `experiments/run_controller_convergence.py` \| `outputs/controller_convergence.json` \| MEASURED (High) \|
	\| 5 \| Anti-Chattering Hysteresis Stabilization \| `src/resource_allocator.py` \| `InformationValueAllocator.forward` \| Dual-threshold switching logic: suppresses route changes unless $\Delta U \ge \tau_{\text{hyst}}$ and cooldown elapsed. \| `experiments/run_hysteresis_validation.py` \| `outputs/hysteresis_results.json` \| MEASURED (High) \|
	\| 6 \| Nested TT Slicing Correctness \| `src/tensor_layers.py` \| `TTLinear.get_active_cores` \| Slices pre-allocated cores along bond dimensions without re-decomposition or runtime SVD. \| `experiments/run_nested_tt_analysis.py` \| `outputs/nested_tt_analysis.json` \| MEASURED (High) \|
	\| 7 \| Grouped-Query Attention (GQA) Memory Savings \| `src/attention.py` \| `MultiHeadAttention.forward` \| Decoupled $N_q / N_{kv}$ with zero-copy view broadcasting, reducing KV cache entries by up to 75%. \| `experiments/run_gqa_audit.py` \| `outputs/gqa_audit.json` \| MEASURED (High) \|
	\| 8 \| Multi-Precision Adaptive KV Cache \| `src/kv_cache.py` \| `AdaptiveKVCache`<br>`QuantizedKVTensor` \| Dynamic switching between FP16, symmetric INT8, and asymmetric packed INT4 with attention-sink eviction. \| `experiments/run_kv_rate_distortion.py` \| `outputs/kv_rate_distortion.json` \| MEASURED (High) \|
	\| 9 \| Quantum Kernel Self-Attention (QKSAM) \| `src/quantum_backend.py`<br>`src/attention.py` \| `QuantumBackend.compute_kernel_matrix` \| Evaluates $K(\mathbf{q}, \mathbf{k}) = \text{Tr}[\rho(\mathbf{q})\rho(\mathbf{k})]$ via parameterized quantum circuits with PennyLane. \| `experiments/run_quantum_utility.py` \| `outputs/quantum_utility.json` \| SIMULATED (Disclosed Classical Overhead) \|
	\| 10 \| Meyer-Wallach Entanglement Metric \| `src/quantum_backend.py` \| `compute_meyer_wallach_entanglement` \| Exact state entanglement capacity $Q(\|\psi\rangle) = \frac{8}{n}\sum \det(\rho_k) \in [0, 1]$. \| `tests/test_advanced_features.py` \| PyTest Suite Report \| MEASURED (Mathematical Definition) \|
	\| 11 \| Calibrated Early-Exit Depth Routing \| `src/blocks.py` \| `HybridBlock.forward` \| Evaluates epistemic uncertainty $U_t < \gamma_{\text{exit}}$ to bypass downstream blocks via identity residual addition. \| `experiments/run_comprehensive_comparison.py` \| `outputs/comprehensive_comparison.json` \| MEASURED (High) \|
	\| 12 \| Hardware Roofline Model Analysis \| `src/hardware_cost_model.py` \| `HardwareRooflineAnalyzer` \| Computes arithmetic intensity $I = \text{FLOPs} / \text{Byte}$, ridge points, and memory/compute bound boundaries across devices. \| `src/hardware_cost_model.py` \| `outputs/comprehensive_comparison.json` \| ESTIMATED (Level 2 Calibrated Model) \|
	\| 13 \| Memory Traffic per Token (Bytes/tok) \| `src/tensor_layers.py`<br>`src/attention.py` \| `get_memory_traffic` \| Tracks physical bytes read (weights + activations) and written per forward pass. \| `experiments/run_detailed_latency_profiling.py` \| `outputs/detailed_latency_results.json` \| MEASURED (High) \|
	\| 14 \| Multi-Level Energy Profiling \| `src/hardware_cost_model.py` \| `HardwareCostModel.estimate_energy_uj` \| Multi-level hierarchy (Level 1: Analytical, Level 2: Calibrated Device Power $\times$ Wall-Clock Time, Level 3: Sensors). \| `experiments/run_comprehensive_comparison.py` \| `outputs/comprehensive_comparison.json` \| ESTIMATED (Level 2 Clearly Disclosed) \|
	\| 15 \| Multi-Baseline Comparison (11 Models) \| `src/baselines.py`<br>`experiments/` \| `DenseBaseline`, `StaticTT`, `INT8/INT4 PTQ`, `H2O`, `GQA` \| Standardized evaluation of 11 models under identical sequence lengths, batch sizes, and token budgets. \| `experiments/run_comprehensive_comparison.py` \| `outputs/comprehensive_comparison.json` \| MEASURED (High) \|
	\| 16 \| Multi-Dimensional Pareto Dominance \| `experiments/run_pareto_frontiers.py` \| `compute_pareto_hypervolume` \| Multi-point trade-offs across Quality vs Latency, Memory, Energy, Bandwidth, and KV size. \| `experiments/run_pareto_frontiers.py` \| `outputs/pareto_frontiers.json` \| MEASURED (High) \|

	---

	## 2. Key Code-Architecture Consistency Resolutions

	### A. Per-Token Rank Execution in Sequences
	- Previous state: In multi-token prefill sequences, `TTLinear.set_rank()` set a single global rank for the layer based on sequence-averaged utility.
	- Resolution: Implemented `forward_token_grouped()` in `TTLinear` allowing each token in a sequence to be routed to its selected rank $r_t \in \{1, 2, 4, 8\}$, contracted through the sliced core, and scattered back in order.

	### B. Removal of Theoretical Convergence Guarantees
	- Previous state: README claimed "guarantees asymptotic convergence to KKT boundary".
	- Resolution: Reformulated to "empirically stable closed-loop tracking". Created `experiments/run_controller_convergence.py` measuring actual settling time ($t_{\text{settle}}$), maximum overshoot ($M_p$), and steady-state error ($e_{\text{ss}}$) under workload step changes.

	### C. Removal of "Zero Overhead" Claims
	- Previous state: Slicing previously cited as zero-latency extraction (0.00 ms).
	- Corrected status: Empirically measured tensor slicing pointer arithmetic overhead (~20-50 µs per layer on CPU/GPU) is explicitly disclosed and included in all latency breakdowns in `experiments/run_adaptive_rank_validation.py` and reported accurately.

	### D. Quantum Simulation Overhead Disclosure
	- Previous state: Emphasized theoretical quantum expressibility without stating classical CPU simulation penalty.
	- Resolution: Full disclosure in documentation: running PennyLane statevector simulation on classical CPUs/GPUs incurs $+100\%\text{–}300\%$ latency overhead. Documented the exact epistemic uncertainty threshold required to justify quantum pathway activation.