Status: Complete and working ✅
An educational platform for balanced ternary computing with a CPU simulator, assembly language, and debugging tools.
This project explores a balanced ternary CPU design and provides a software stack to experiment with it: a cycle-accurate simulator, an assembler, and tracing utilities. The goal is to make ternary concepts concrete and approachable for learners and practitioners.
- Signed enables (
mulT): A single trit controls pass/off/invert operations. - Bus cancellation (
splus): P⊕N=Z simplifies datapath selection. - Three-way branching (
branchBySign): Branch on negative/zero/positive without binary comparators. - Delta counters (
stepCounter): ±1 operations without a dedicated ALU path. - Natural negation: ABS/NEG via trit inversion.
- Base‑3 shifts: Multiply/divide by powers of 3 by wiring.
- CPU model: 9‑trit words, 6‑trit addressing, cycle‑accurate execution.
- Assembly language: 15 instructions with labels.
- Debugging: Colorized tracing with cost breakdowns and branch visualization.
- Learning path: Examples and tutorials from basics to more advanced topics.
- Performance readouts: CPI and execution metrics.
- Word size: 9 trits (range ±9,841)
- Memory: 6‑trit addresses (729 locations)
- Instruction format:
[ARG(6) | OPC(3)](9 trits total) - ISA (15 opcodes):
LIT, ADD, SUB, ADI, LDA, STA, SHL, SHR, JMP, JZ, JN, JSP, CMV, HALT, NOP - Arithmetic: Hardware‑faithful full adders (exhaustively tested)
- Cost model: Configurable latencies approximating pipeline costs
Example trace output:
PC=000000 IR=LIT 7 ACC=000000000/0 CycLeft=1 cost=1 [fetch=1] [rdPorts=1]
PC=00000+ IR=ADI 5 ACC=000000+-+/7 CycLeft=6 cost=6 [fetch=1]+[~half(ALU=2+perTrit*1x9)] [rdPorts=1]
PC=0000+- IR=STA 300 ACC=000000++0/12 CycLeft=1 cost=3 [fetch=1]+[st] [rdPorts=1]
[STORE] M[300] = 000000++0 / 12
PC=0000+0 IR=HALT ACC=000000++0/12 CycLeft=1 cost=1 halt [fetch=1] [rdPorts=1]
------------------------------------------------------------
HALT
ACC = 000000++0 / 12 INST = 4 CYCL = 11 CPI = 2.75
What the tracer shows:
- Color‑coded instructions, registers, and operations
- Cost analysis per instruction
- Branch direction (N/Z/P) preview for
CMV/JSP - Memory stores at retirement
- CPI and instruction counts
Example program:
; Add two numbers and store result
LIT 7 ; Load immediate 7 into ACC
ADI 5 ; Add immediate 5: ACC = 12
STA 300 ; Store result at memory address 300
HALT ; Stop execution
; 3-way conditional with ternary lookup
LIT 0 ; ACC = 0 (zero)
CMV 200 ; Load M[201] when ACC is zero (N/Z/P → 200/201/202)
HALT ; Result: ACC = value from M[201]- Stack (Haskell build tool)
# Clone and enter directory
cd balanced-ternary-cpu
# Build the project
stack build
# Run the default demo
stack exec balanced-ternary-cpu-exe
# Run tests
stack test
# Interactive development
stack ghciimport T3
main = do
print $ toBT 5 -- [P,N,P]
print $ fromBT [P,N,P] -- 5
demoAddStore -- Add and store demo
demoShiftAdd -- Shift multiplication demoMain CPU demos:
# Basic demos
stack exec balanced-ternary-cpu-exe # Default add/store demo
stack exec balanced-ternary-cpu-exe -- --shift # Shift multiplication
stack exec balanced-ternary-cpu-exe -- --original # CMV demo
# Rich tracing
stack exec balanced-ternary-cpu-exe -- --rich-addstore
stack exec balanced-ternary-cpu-exe -- --rich-shift
stack exec balanced-ternary-cpu-exe -- --rich-originalAssembly execution:
# Run assembly programs
stack exec t3asm -- examples/assembly/addstore.asm # Add and store
stack exec t3asm -- examples/assembly/cmov3.asm # Conditional 3-way move
stack exec t3asm -- examples/assembly/shift.asm # Shift operations
stack exec t3asm -- examples/assembly/flow.asm # Control flow and loops
# Enhanced tracing
stack exec t3asm -- examples/assembly/addstore.asm --rich
stack exec t3asm -- examples/assembly/cmov3.asm --rich
# Execution control
stack exec t3asm -- examples/assembly/flow.asm --steps 50cpu/
├── src/ # Core library implementation
│ └── T3.hs # Main ternary CPU module
├── app/ # Executable programs
│ └── Main.hs # Demo application
├── examples/ # Example programs and tutorials
├── docs/ # Technical documentation
└── test/ # Test suite
- Getting Started — Installation, setup, and first steps
- Architecture Overview — CPU design, ternary logic fundamentals
- Programming Guide — Assembly language reference and debugging
- Technical Design — Implementation details and mathematical foundations
- Development History — Project evolution and milestones
- Examples Overview — Complete demo guide and learning path
- Assembly Programs — Sample ternary assembly code
- Library Usage — Haskell API demonstrations
- Interactive Demo — Quick library exploration
- Core Library — T3 module overview and API reference
| Topic | Documentation | Examples | Implementation |
|---|---|---|---|
| Getting Started | Setup Guide | First Demo | Build Instructions |
| Ternary Logic | Architecture | Basic Examples | Core Types |
| Assembly Programming | Programming Guide | Assembly Examples | ISA Definition |
| CPU Architecture | Technical Design | Rich Tracing Demo | CPU Implementation |
| Performance Analysis | Cost Model | Tracing Examples | Cost Functions |
Run these commands to explore the system:
# Basic CPU demonstrations
stack exec balanced-ternary-cpu-exe -- --addstore # Simple arithmetic
stack exec balanced-ternary-cpu-exe -- --shift # Ternary multiplication
stack exec balanced-ternary-cpu-exe -- --original # Conditional operations
# Enhanced tracing (recommended for learning)
stack exec balanced-ternary-cpu-exe -- --rich-addstore
stack exec balanced-ternary-cpu-exe -- --rich-shift
# Assembly language programs
stack exec t3asm -- examples/assembly/addstore.asm --rich
stack exec t3asm -- examples/assembly/cmov3.asm --rich- Assembly Programs — Complete runnable programs with documentation
- Haskell Examples — Library API demonstrations
- Performance Analysis — Optimization techniques
See Examples Overview for the complete learning path and all available demonstrations.
Contributions are welcome:
- Documentation improvements
- Example programs and tutorials
- Performance optimizations
- Hardware synthesis experiments
MIT License — see LICENSE for details.