Premchan369/Q-TensorFormer

1# SOURCE API FINAL: Standard Model & Configuration Interfaces2 3**Date**: September 17, 2026  4**Repository**: `Premchan369/Q-TensorFormer`5 6---7 8## 1. Canonical Model Configuration Interface9 10```python11from src.config import ModelConfig, validate_model_config12 13# Canonical ModelConfig hyperparameter signature14config = ModelConfig(15    vocab_size=10000,      # Vocabulary size16    d_model=128,           # Model embedding dimension17    n_heads=4,             # Number of attention heads18    n_layers=2,            # Number of transformer blocks19    ff_multiplier=4,       # Feed-forward expansion factor (D_ff = d_model * ff_multiplier)20    max_seq_len=128,       # Maximum sequence context length21    dropout=0.1,           # Dropout rate22    tt_rank=8,             # Maximum Tensor-Train rank23    tt_min_rank=2,         # Minimum Tensor-Train rank24    use_tensor_ffn=True,   # Enable TT-FFN25    n_qubits=4,            # Number of quantum simulation wires26    n_quantum_layers=2,    # Number of variational circuit layers27    quantum_sparsity=0.3,  # Target quantum routing sparsity28    use_quantum=True,      # Enable quantum pathway29    rank_alpha=2.0,        # Rank allocation slope30    rank_smoothing=0.9,    # EMA rank smoothing factor31)32 33# Validate config against model requirements34validate_model_config(config, QTensorFormer)35```36 37---38 39## 2. Canonical Model Instantiation & Forward Pass40 41```python42from src.models import QTensorFormer, DenseBaseline43 44# Instantiate Q-TensorFormer45qtf = QTensorFormer(config, preset="QTF_BALANCED")46 47# Instantiate Apples-to-Apples Dense Baseline48dense = DenseBaseline(config)49 50# Forward pass51import torch52input_ids = torch.randint(0, config.vocab_size, (1, 32), dtype=torch.long)53 54logits_qtf = qtf(input_ids)       # Shape: [1, 32, 10000]55logits_dense = dense(input_ids)   # Shape: [1, 32, 10000]56```57 58---59 60## 3. Legacy Module Interoperability61 62Both `q_tensor_former.py` and `q_tensor_former_v2.py` accept the canonical `ModelConfig` directly:63 64```python65import q_tensor_former as qtf166import q_tensor_former_v2 as qtf267 68m1 = qtf1.QTensorFormer(config)69m2 = qtf2.QTensorFormer(config)70```71