nesformer کے ساتھ مرتب شدہ Qwen3.5 ماڈل کے اندر NES گیمز چلائیں

nesformer کیا ہے؟

nesformer ایک تجرباتی NES رن ٹائم ہے جس میں کنسول کا 6502 CPU، 2 KB ورک RAM، اور کارٹریج پروگرام ROM ایک معیاری Qwen3_5ForCausalLM چیک پوائنٹ کے weights اور state کے اندر کام کرتے ہیں۔ weights کو train نہیں کیا گیا۔ اس کے بجائے، ایک compiler نے انہیں CPU سرکٹ نافذ کرنے کے لیے حساب کر کے تیار کیا ہے۔

گیم کے دوران، ماڈل CPU execution log کی ایک وقت میں ایک token پیش گوئی کرتا ہے۔ Python host program کنسول کے باقی اجزا فراہم کرتا ہے: یہ گرافکس رینڈر کرتا ہے، کنٹرولر input پڑھتا ہے، timing سنبھالتا ہے، I/O reads کا جواب دیتا ہے، اور vertical-blanking NMI interrupt داخل کرتا ہے۔

یہ پروجیکٹ Qwenputer پر مبنی ہے اور اس کا compiler اور مرکزی memory technique دوبارہ استعمال کرتا ہے۔ ہر Gated DeltaNet head ایک state matrix برقرار رکھتا ہے۔ One-hot keys اور queries اس matrix کی قطاروں کو memory cells کی طرح کام کرنے دیتی ہیں، جو registers، RAM، اور cartridge data محفوظ کرتی ہیں۔

اہم خصوصیات

• Train کرنے کے بجائے compiled: ہر nonzero weight ایک circuit specification سے تیار کیا جاتا ہے۔
• معیاری checkpoint format: checkpoint ایک عام Hugging Face folder ہے اور اسے custom model code کے بغیر Qwen3_5ForCausalLM.from_pretrained سے load کیا جا سکتا ہے۔
• مکمل سرکاری 6502 instruction set: سرکٹ تمام 151 سرکاری opcodes، addressing modes، flags، stack operations، BRK، اور NMI entry نافذ کرتا ہے۔
• قابلِ دوبارہ استعمال NROM support: ایک ہی weights مختلف iNES mapper 0 ROMs چلا سکتے ہیں، کیونکہ منتخب cartridge کو startup پر model state میں لکھا جاتا ہے۔
• Scripted controls: command line سے frame کے حساب سے button presses شیڈول کی جا سکتی ہیں۔
• Visual exports: runs کو compatible terminal میں دکھایا اور GIF یا PNG frames کے طور پر محفوظ کیا جا سکتا ہے۔
• Execution verification: check command model output کا bundled reference CPU سے موازنہ کرتا ہے اور پہلے فرق پر رک جاتا ہے۔
• متعدد execution engines: nesformer ایک تیز numba engine، ایک سادہ NumPy engine، اور ایک stock Transformers engine فراہم کرتا ہے۔

سمجھیں کہ ماڈل کے اندر کیا چلتا ہے

checkpoint میں 6502 core، CPU registers اور flags، 2 KB ورک RAM، اور 32 KB program-ROM table شامل ہے۔ یہ program fetches، data reads، stack operations، اور OAM DMA reads بھی سنبھالتا ہے۔

host، PPU renderer، palette، controllers، vblank NMI timing، cycle counting، اور APU register handling کی ذمہ داری برقرار رکھتا ہے۔ Sound نافذ نہیں کیا گیا۔ host I/O reads اور NMI events کی values token stream میں داخل کرتا ہے، لیکن emitted trace کے علاوہ model کے registers یا RAM کا براہِ راست معائنہ نہیں کرتا۔

nesformer model inference کے ذریعے CPU کی نقالی کرتا ہے، لیکن یہ مکمل NES نہیں ہے جو entirely weights کے اندر نافذ ہو۔

ضروریات اور folder setup

آپ کو Python 3.11 یا اس کے بعد کا ورژن، nesformer source archive، اور الگ weights archive درکار ہیں۔ دونوں archives کو ایک ہی top-level folder میں extract کریں۔ weights directory کو Python package کے اندر نہیں بلکہ اس کے برابر ہونا چاہیے۔

nesformer/
├── nesformer/
├── chipformer/
├── roms/
├── examples/
├── tests/
├── pyproject.toml
└── weights/
    ├── config.json
    ├── generation_config.json
    ├── model.safetensors
    ├── nesformer.json
    └── SHA256SUMS

تمام commands اوپر دکھائی گئی top-level directory سے چلائیں۔ بطورِ ڈیفالٹ، CLI، nesformer/ package کے برابر موجود weights/ تلاش کرتا ہے۔

ڈاؤن لوڈ کیے گئے weights کی تصدیق کریں

یہ تصدیق کرنے کے لیے شامل checksum file استعمال کریں کہ weights درست طور پر extract ہوئے ہیں:

shasum -a 256 -c weights/SHA256SUMS

اگر checkpoint کسی اور جگہ رکھا ہے تو run، check، یا trace استعمال کرتے وقت اس کا مقام --weights /path/to/weights کے ذریعے دیں۔ info command checkpoint path براہِ راست قبول کرتی ہے۔

nesformer انسٹال کریں

virtual environment بنائیں اور فعال کریں، پھر مطلوبہ numerical اور image-processing packages انسٹال کریں:

python3 -m venv .venv
source .venv/bin/activate
pip install numpy scipy numba pillow

Windows پر environment کو اس command سے فعال کریں:

.venv\Scripts\activate

ڈیفالٹ fast engine numba استعمال کرتا ہے۔ اس کا پہلا run engine compile کرنے میں تقریباً 20 سیکنڈ لیتا ہے۔ بعد کے runs اس compilation work کو دوبارہ استعمال کرتے ہیں۔

اپنی پہلی game چلائیں

repository میں آزاد لائسنس کے تحت فراہم کردہ test ROMs شامل ہیں۔ درج ذیل command Thwaite کو 600 frames تک چلاتی ہے، frames کو terminal میں دکھاتی ہے، اور Start اور A button presses کی scripted sequence فراہم کرتی ہے:

python -m nesformer run roms/thwaite.nes --frames 600 --show \
  --buttons "start@90-95+200-205,a@230-233+250-253+270-273+290-293+310-313+330-333+350-353+370-373+390-393+410-413+430-433+450-453+470-473+490-493+510-513+530-533+550-553+570-573+590-593"

--show option ہر generated frame کو 24-bit color support والے terminal، مثلاً iTerm2 یا Windows Terminal، میں دکھاتی ہے۔ execution مکمل ہونے پر CLI ROM کے نام پر animated GIF محفوظ کرتی ہے، مثلاً thwaite.gif۔

کارکردگی حقیقی NES کے مقابلے میں بہت کم ہے۔ ابتدائی compilation کے بعد، ایک frame میں عموماً ایک سے چھ سیکنڈ لگتے ہیں۔ 600-frame run NES time کے 10 سیکنڈ کی نمائندگی کرتا ہے اور اسے مکمل ہونے میں تقریباً 25 منٹ لگ سکتے ہیں۔

اپنی compatible ROM چلائیں

اپنی قانونی طور پر حاصل کردہ ROM کو roms/ directory میں رکھیں یا کوئی دوسرا path فراہم کریں۔ ROM کو NROM board استعمال کرنا چاہیے، جس کی شناخت iNES mapper 0 کے طور پر ہوتی ہے۔ compatible مثالوں میں Super Mario Bros.، Donkey Kong، اور Excitebike شامل ہیں، تاہم یہ تجارتی ROMs شامل نہیں کی گئیں۔

یہ مثال Super Mario Bros. شروع کرتی ہے، Right دبائے رکھتی ہے، اور کئی چھلانگیں مقرر کرتی ہے:

python -m nesformer run roms/smb.nes --frames 600 --show \
  --buttons "start@60-65,right@200-600,a@250-265+300-315+360-375+420-435+480-495+540-555"

شروع ہوتے وقت ROM کو ماڈل کی DeltaNet حالت میں لوڈ کیا جاتا ہے۔ ہر مطابقت رکھنے والی گیم کے لیے checkpoint دوبارہ بنانے کی ضرورت نہیں ہوتی۔

اسکرپٹ سے کنٹرول ان پٹ

--buttons آپشن کوما سے جدا اندراجات قبول کرتا ہے۔ ہر اندراج میں ایک یا زیادہ بٹن نام، ایک @ علامت، اور ایک یا زیادہ فریم رینجز شامل ہوتی ہیں۔

start@60-65
right@200-600
a@250-265+300-315
right+b@200-600

• start@60-65 فریم 60 سے فریم 65 تک Start دباتا ہے۔
• right@200-600 مخصوص وقفے کے دوران Right دبائے رکھتا ہے۔
• a@250-265+300-315 A بٹن کو دو بار دبانے کے لیے مقرر کرتا ہے۔
• right+b@200-600 بیک وقت Right اور B دبائے رکھتا ہے۔

دستیاب نام a، b، select، start، up، down، left، اور right ہیں۔ فریم پاور آن ہوتے وقت شروع ہوتے ہیں اور 60 فریم فی سیکنڈ کی رفتار سے آگے بڑھتے ہیں۔ اس لیے فریم 600، NES وقت کے 10 سیکنڈ کے برابر ہے۔

عام طور پر بٹن کو تھوڑا پہلے دبانا محفوظ ہوتا ہے، کیونکہ جن اسکرینوں پر حرکت دستیاب نہ ہو وہاں گیمز کنٹرولز کو نظر انداز کر دیتی ہیں۔ بٹن دبانے کا دورانیہ اہم ہو سکتا ہے؛ مثال کے طور پر Super Mario Bros. میں A کو زیادہ دیر دبانے سے زیادہ اونچی چھلانگ لگتی ہے۔

فریم آؤٹ پٹ کو کنٹرول کریں

پہلے سے، run 120 فریم چلاتا ہے اور ROM کے نام پر مبنی GIF لکھتا ہے۔ نتیجے کو حسب ضرورت بنانے کے لیے آؤٹ پٹ آپشنز استعمال کریں:

python -m nesformer run roms/thwaite.nes \
  --frames 300 \
  --every 2 \
  --scale 3 \
  --gif output/thwaite.gif

• --frames N، N فریم کے بعد رک جاتا ہے۔
• --gif PATH متحرک GIF کی منزل منتخب کرتا ہے۔
• --png DIR محفوظ کیے گئے فریموں کو الگ الگ PNG فائلوں کے طور پر محفوظ کرتا ہے۔
• --every N ہر Nواں فریم محفوظ کرتا ہے۔
• --scale N محفوظ کیے گئے فریموں کو صحیح عددی عامل سے بڑا کرتا ہے۔
• --show تیار کردہ فریم ٹرمینل میں دکھاتا ہے۔

صرف --png استعمال کرنے سے GIF آؤٹ پٹ غیر فعال ہو جاتا ہے۔ جب PNG فریموں اور اینیمیشن دونوں کی ضرورت ہو تو واضح --gif آپشن شامل کریں۔

python -m nesformer run roms/thwaite.nes \
  --frames 120 \
  --png frames \
  --gif thwaite.gif

عمل درآمد کا معائنہ اور تصدیق

حوالہ CPU کے ساتھ موازنہ کریں

check کمانڈ checkpoint اور پروجیکٹ کے روایتی reference 6502 کو ساتھ ساتھ چلاتی ہے۔ یہ پہلے token کے فرق پر رک جاتی ہے:

python -m nesformer check roms/thwaite.nes --tokens 50000

پہلے سے موازنے کی لمبائی 50,000 tokens ہے۔ آپ وہی --buttons، --weights، --engine، اور --no-skip آپشنز دے سکتے ہیں جو دیگر execution کمانڈز قبول کرتی ہیں۔

ماڈل کی token stream پرنٹ کریں

ماڈل کے تیار کردہ CPU ریکارڈز کا معائنہ کرنے کے لیے trace استعمال کریں:

python -m nesformer trace roms/thwaite.nes --tokens 100

پہلے سے trace کی لمبائی 40 tokens ہے۔ زیادہ تر CPU instructions کے لیے ایک token درکار ہوتا ہے، جبکہ I/O، pointer reads، stack operations، یا DMA سے متعلق instructions کئی tokens پر مشتمل records تیار کر سکتی ہیں۔

رن کے دوران token IDs محفوظ کریں

run کمانڈ تیار کردہ token IDs کو بعد کے تجزیے کے لیے فائل میں لکھ سکتی ہے:

python -m nesformer run roms/thwaite.nes \
  --frames 60 \
  --trace trace.txt

آپ --max-tokens N بھی استعمال کر سکتے ہیں تاکہ صرف فریم کی حد پر انحصار کرنے کے بجائے تیار کردہ tokens کی مقررہ تعداد کے بعد عمل درآمد روک دیا جائے۔

execution engine منتخب کریں

nesformer تین engines فراہم کرتا ہے، جن کی کارکردگی اور dependencies مختلف ہیں:

• fast: پہلے سے منتخب numba implementation۔ README کے مطابق development machine کے ایک CPU core پر تقریباً 1,650 tokens فی سیکنڈ۔
• numpy: آسان NumPy implementation، جس کی رفتار تقریباً 210 tokens فی سیکنڈ بتائی گئی ہے۔
• hf: معیاری Hugging Face Transformers، جس کی رفتار تقریباً 10 tokens فی سیکنڈ بتائی گئی ہے۔

--engine کے ذریعے engine منتخب کریں:

python -m nesformer run roms/thwaite.nes --frames 3 --engine numpy

معیاری Transformers استعمال کریں

Hugging Face engine منتخب کرنے سے پہلے اضافی dependencies انسٹال کریں:

pip install "torch>=2.6" "transformers>=5.22"
python -m nesformer run roms/thwaite.nes --frames 3 --engine hf

checkpoint کو کسی custom model implementation کی ضرورت نہیں۔ اندرونی طور پر، nesformer اسے لوڈ کرتا ہے، ایک padding token کو decode کرتا ہے، ابتدائی machine state کو cache کی DeltaNet states میں لکھتا ہے، اور پھر تیار کردہ tokens کو ایک ایک کر کے دوبارہ input کے طور پر دیتا ہے۔

اعلیٰ درجے کی تجاویز

weights کو repository سے باہر رکھیں

جب checkpoint کسی دوسری جگہ محفوظ ہو تو --weights استعمال کریں:

python -m nesformer run roms/thwaite.nes \
  --weights /path/to/weights \
  --frames 120

checkpoint metadata کا معائنہ کریں

checkpoint کی تفصیل دیکھنے کے لیے information کمانڈ استعمال کریں:

python -m nesformer info

اگر weights پہلے سے مقررہ directory میں نہ ہوں تو info کو ان کا path فراہم کریں۔

checkpoint دوبارہ بنائیں

repository میں circuit checkpoint دوبارہ تیار کرنے کے لیے درکار compiler شامل ہے۔ عام build weights/ میں لکھتی ہے اور README کے مطابق تقریباً 10 سیکنڈ لیتی ہے:

python -m nesformer build

آؤٹ پٹ کی دوسری directory منتخب کریں:

python -m nesformer build --out compiled-weights

idle-loop skipping سمجھیں

NES گیمز اکثر مختصر لوپس میں vblank کا انتظار کرتی ہیں۔ جب میزبان کسی ایسے بالکل دہرائے جانے والے لوپ کا پتا لگاتا ہے جس میں RAM یا I/O پر کوئی تحریر نہ ہو، تو یہ کلاک کو اگلے PPU ایونٹ کے قریب تک آگے بڑھا دیتا ہے اور پھر باقی iterations چلاتا ہے۔ یہ optimization نظر آنے والے فریمز اور I/O timing کو برقرار رکھتے ہوئے token generation کو نمایاں طور پر کم کرتی ہے۔

ہر idle-loop iteration چلانے کے لیے --no-skip پاس کریں۔ یہ رفتار میں سست ہے، لیکن مکمل token sequence کا مطالعہ کرتے وقت مفید ہو سکتا ہے:

python -m nesformer trace roms/thwaite.nes --tokens 100 --no-skip

ٹیسٹ suite چلائیں

ٹیسٹنگ dependencies انسٹال کریں اور pytest چلائیں:

pip install pytest py65
python -m pytest -q tests

ٹیسٹس مکمل ہونے میں چند منٹ لگتے ہیں۔ یہ reference CPU کا nestest log کے ساتھ موازنہ کرتے ہیں، compiled circuit کو reference کے خلاف چیک کرتے ہیں، free-running weights کی تصدیق کرتے ہیں، اور idle-loop optimization کو ٹیسٹ کرتے ہیں۔

اہم حدود

• صرف NROM: گیمز کو iNES mapper 0 استعمال کرنا ہوگا۔ MMC1 اور MMC3 جیسے bank-switching mappers معاونت یافتہ نہیں ہیں۔
• صرف official opcodes: کسی غیر سرکاری 6502 opcode کا سامنا ہونے پر HALT جاری ہوتا ہے۔
• ROM سے execution: code کو cartridge ROM سے execute ہونا چاہیے؛ RAM میں jump کرنے پر HALT جاری ہوتا ہے۔
• IRQ کی معاونت نہیں: BRK اور NMI کام کرتے ہیں، لیکن APU frame اور DMC IRQs معاونت یافتہ نہیں ہیں۔
• محدود I/O behavior: I/O registers پر read-modify-write instructions، I/O write پیدا نہیں کرتیں، اور $4020 سے $7FFF تک کے addresses صفر پڑھتے ہیں۔
• گرافکس کی تفصیلات تقریباً درست: rendering ایک وقت میں ایک scanline پر ہوتی ہے، mid-scanline effects دوبارہ پیدا نہیں کیے جاتے، اور sprite-0 hit اور sprite overflow تقریباً درست ہیں۔
• آڈیو نہیں: APU register writes قبول کی جاتی ہیں، لیکن sound پیدا نہیں کی جاتی۔
• سست execution: idle-loop skipping کے باوجود، یہ project حقیقی console کے مقابلے میں تقریباً 150 سے 290 گنا سست چلتا ہے۔

نتیجہ

nesformer یہ ظاہر کرتا ہے کہ transformer checkpoint، trained language model کے بجائے ایک exact compiled computer کے طور پر کام کر سکتا ہے۔ جب source اور weights کو درست طریقے سے ترتیب دے دیا جائے، تو آپ compatible NROM گیمز چلا سکتے ہیں، controller input خودکار بنا سکتے ہیں، frames export کر سکتے ہیں، CPU tokens کا معائنہ کر سکتے ہیں، اور execution کا reference 6502 کے ساتھ موازنہ کر سکتے ہیں۔ اس کی mapper، graphics، audio، اور speed کی حدود اسے ایک تجرباتی system بناتی ہیں، لیکن اس کا standard Qwen3.5 checkpoint اور verification tools computation کو براہِ راست model weights اور DeltaNet state میں encoded شکل میں مطالعہ کرنے کا عملی طریقہ فراہم کرتے ہیں۔