README.md

Binary Math Education System

An interactive CLI tool for teaching binary mathematics, logic gates, and truth tables to computer science freshmen. This system provides hands-on learning with progressive difficulty levels, step-by-step explanations, and adaptive feedback.

Overview

The Binary Math Education System is designed to help students master fundamental digital logic concepts through interactive lessons and practice. Whether you're a freshman learning binary for the first time or an educator looking for teaching materials, this system provides comprehensive coverage of:

• Binary number system fundamentals: Conversion between decimal and binary, arithmetic operations, and two's complement representation
• Logic gates: Complete coverage of AND, OR, NOT, XOR, NAND, NOR, and XNOR gates with truth tables and circuit diagrams
• Truth table generation: Parse boolean expressions and generate/validate truth tables
• Interactive practice: Adaptive problem generation with immediate feedback and progressive hints

Built entirely with Python's standard library (no external dependencies), this system runs anywhere Python 3.8+ is installed.

Features

• Interactive Lessons with 4 modes:

  • Binary Basics: Number conversion, arithmetic, two's complement
  • Logic Gates: Digital electronics fundamentals with visual circuit diagrams
  • Truth Tables: Boolean algebra and logic evaluation
  • Practice Mode: Mixed problems with adaptive difficulty

• Progressive Difficulty Levels:

  • Beginner: Unlimited hints, step-by-step guidance
  • Intermediate: Moderate assistance, 3 hints per problem
  • Advanced: Minimal guidance, 1 hint per problem

• Adaptive Learning: System adjusts difficulty based on performance metrics (accuracy, streaks, hints used)

• Session Management:

  • Automatic save/resume functionality
  • Progress tracking and analytics
  • Session history stored in ~/.binary_tutor/sessions/

• Educational Features:

  • Step-by-step explanations with visual aids
  • 3-level progressive hint system
  • Real-time answer validation
  • ASCII circuit diagrams and truth tables
  • Boolean algebra expressions
  • Real-world analogies

• Progress Tracking:

  • Problems completed and accuracy percentage
  • Current streak and total hints used
  • Session duration and historical data

Quick Start

Installation

# Clone or download the repository
cd /path/to/binary

# No external dependencies required - uses Python standard library only!
# Python 3.8+ required
python3 --version

Run Interactive Tutor

# Start the interactive tutor CLI
python3 src/interactive_tutor.py

# Or use the demo script
python3 demo_tutor.py

Quick Demo (5 minutes)

# Try the Python API directly
from src.binary_basics import BinaryTutor
from src.logic_gates import AND, OR, NOT

# Binary conversion
tutor = BinaryTutor(difficulty_level='beginner')
result = tutor.decimal_to_binary(42)
print(result['result'])  # '00101010'

# Logic gates
gate_result = AND(True, False)
print(gate_result.result)  # False
print(gate_result.explanation)  # Full educational output

Project Structure

binary/
├── src/                          # Core modules
│   ├── binary_basics.py          # Binary conversion and arithmetic
│   ├── logic_gates.py            # Logic gate operations
│   ├── truth_tables.py           # Truth table generation
│   ├── practice_generator.py    # Problem generation engine
│   └── interactive_tutor.py      # CLI interface
├── examples/                     # Usage examples
│   └── logic_gates_demo.py       # Logic gates demonstrations
├── demo_tutor.py                 # Non-interactive demo script
└── docs/                         # Architecture and guides
    ├── QUICKSTART.md
    ├── ARCHITECTURE.md
    └── MODULE_DOCUMENTATION.md

Module Overview

binary_basics.py

Binary number system tutor with difficulty-based progression

Core functionality:

• decimal_to_binary(): Convert decimal to binary with division-by-2 visualization
• binary_to_decimal(): Convert binary to decimal using place value method
• add_binary(), subtract_binary(), multiply_binary(): Binary arithmetic with carry/borrow tracking
• to_twos_complement(), from_twos_complement(): Signed integer representation
• bitwise_and(), bitwise_or(), bitwise_xor(), bitwise_not(): Bitwise operations
• left_shift(), right_shift(): Bit shifting with multiplication/division effects

logic_gates.py

Educational logic gate operations with truth tables and circuit diagrams

Available gates:

• NOT(a): Single-input inverter
• AND(a, b, ...): All inputs must be True
• OR(a, b, ...): At least one input must be True
• NAND(a, b, ...): NOT-AND (universal gate)
• NOR(a, b, ...): NOT-OR (universal gate)
• XOR(a, b, ...): Exclusive OR (different inputs)
• XNOR(a, b, ...): Exclusive NOR (same inputs)

Features:

• Returns GateResult objects with .result, .truth_table, .circuit, .explanation
• Supports gate composition: OR(AND(True, True), NOT(False))
• Flexible input types: booleans, integers (0/1), strings ('0'/'1')

truth_tables.py

Parse boolean expressions and generate/validate truth tables

Core functionality:

• Parse complex boolean expressions (e.g., "(A AND B) OR (NOT C)")
• Generate complete truth tables for any number of variables
• Validate user-provided truth tables
• Educational output with step-by-step evaluation

practice_generator.py

Adaptive problem generation with validation and hints

Features:

• Generate problems for all lesson types
• Difficulty-appropriate problem complexity
• Validate answers with flexible matching
• 3-level progressive hint system
• Performance-based difficulty adjustment

interactive_tutor.py

Command-line interface for interactive lessons

Architecture:

• TutorOrchestrator: Main application controller
• SessionManager: Save/load/resume sessions
• DisplayRenderer: Colorized CLI output
• InputHandler: User input validation
• LessonInterface: Lesson content management

Usage Examples

Using Binary Basics

from src.binary_basics import BinaryTutor

tutor = BinaryTutor(difficulty_level='beginner')

# Convert decimal 42 to binary
result = tutor.decimal_to_binary(42)
print(result['result'])           # '00101010'
print(result['explanation'])      # Detailed explanation
print(result['visual'])           # ASCII visual aid

# Binary addition
result = tutor.add_binary('1011', '0110')
print(result['result'])           # '10001'
print(result['visual'])           # Shows carry propagation

Using Logic Gates

from src.logic_gates import AND, OR, NOT, XOR, compare_gates

# Basic gate operations
result = AND(True, False)
print(result.result)              # False
print(result)                     # Full educational output

# Gate composition
result = OR(AND(True, True), NOT(False))
print(result.result)              # True

# Compare multiple gates
print(compare_gates('AND', 'OR', 'XOR'))

Using Truth Tables

from src.truth_tables import TruthTableGenerator

generator = TruthTableGenerator()

# Generate truth table for expression
result = generator.generate_table("A AND B")
print(result['table'])            # Complete truth table
print(result['visual'])           # ASCII formatted table

# Validate user input
is_valid = generator.validate_table("A OR B", user_table)

Using Practice Generator

from src.practice_generator import PracticeGenerator

generator = PracticeGenerator(difficulty='intermediate')

# Get a practice problem
problem = generator.generate_problem('binary_basics')
print(problem['question'])
print(problem['type'])            # 'binary', 'decimal', or 'text'

# Check answer
is_correct = generator.check_answer(problem['id'], user_answer)

# Get progressive hints
hint1 = generator.get_hint(problem['id'], level=1)
hint2 = generator.get_hint(problem['id'], level=2)

Running the Interactive Tutor

# Launch interactive mode
python3 src/interactive_tutor.py

# Navigate menus with number keys
# Use commands during lessons:
#   h - Get a hint
#   n - Next question
#   b - Previous question
#   s - Save session
#   q - Quit to menu
#   ? - Show help

Installation & Setup

System Requirements

• Python 3.8+ (uses standard library only)
• Terminal with UTF-8 support (for visual elements)
• ~50MB disk space (for code and session data)

Installation Steps

# 1. Navigate to project directory
cd /Users/bhunt/development/claude/binary

# 2. Verify Python version
python3 --version  # Should be 3.8 or higher

# 3. Test the modules
python3 src/test_modules.py

# 4. Run interactive tutor
python3 src/interactive_tutor.py

No Dependencies Required

This project uses only Python standard library:

• json - Session data persistence
• dataclasses - Structured data
• enum - Type-safe enumerations
• pathlib - Cross-platform file paths
• itertools - Truth table generation
• functools - Memoization/caching

Running Tests

# Run module tests
python3 src/test_modules.py

# Run demo (non-interactive test)
python3 demo_tutor.py

# Test individual modules
python3 -c "from src.binary_basics import BinaryTutor; \
            t = BinaryTutor(); \
            print(t.decimal_to_binary(42)['result'])"

Lessons Available

1. Binary Basics

Topics: Binary number system, base conversion, arithmetic operations

• Decimal ↔ Binary conversion (division-by-2 and place value methods)
• Binary arithmetic: addition, subtraction, multiplication
• Two's complement signed representation
• Bitwise operations: AND, OR, XOR, NOT
• Bit shifting: left (multiply) and right (divide)

Sample Problems:

• "Convert decimal 42 to binary"
• "What is 1010 + 0101 in binary?"
• "Convert -5 to 8-bit two's complement"

2. Logic Gates

Topics: Digital electronics, logic gate operations, circuit design

• Basic gates: AND, OR, NOT
• Compound gates: NAND, NOR, XOR, XNOR
• Truth table generation for all gates
• Gate composition and circuit diagrams
• Boolean algebra expressions

Sample Problems:

• "What is the output of AND(1, 0)?"
• "Evaluate: OR(AND(1, 1), NOT(0))"
• "Which gate is the universal gate?"

3. Truth Tables

Topics: Boolean algebra, logic evaluation, truth table construction

• Parse complex boolean expressions
• Generate complete truth tables (1-4 variables)
• Validate truth table correctness
• Understand operator precedence
• Evaluate compound expressions

Sample Problems:

• "How many rows in a truth table with 3 variables?"
• "Generate truth table for (A AND B) OR C"
• "Validate this truth table for A XOR B"

4. Practice Mode

Topics: Mixed problems from all lesson types

• Adaptive difficulty based on performance
• Mixed problem types (conversion, gates, truth tables)
• Real-time performance tracking
• Streak bonuses for consecutive correct answers

Session Management

Automatic Session Saving

Sessions are automatically saved to ~/.binary_tutor/sessions/ as JSON files:

~/.binary_tutor/sessions/
├── uuid-1234-5678-90ab.json
├── uuid-2345-6789-01bc.json
└── uuid-3456-7890-12cd.json

Resume Sessions

From the main menu, select "Resume Lesson" to see active sessions:

Active Sessions:
  1. Binary Basics (beginner) - 5 problems
  2. Logic Gates (intermediate) - 12 problems
  3. Practice Mode (intermediate) - 8 problems

Progress Statistics

View detailed statistics for any session:

• Problems completed and accuracy percentage
• Current streak (consecutive correct answers)
• Total hints used
• Session duration
• Attempt history with timestamps

Data Structure

Each session stores:

{
  "session_id": "uuid",
  "created": "ISO-8601 timestamp",
  "lesson_state": {
    "lesson_id": "binary_basics",
    "difficulty": "beginner",
    "problems_completed": 5,
    "correct_answers": 4,
    "accuracy": 80.0,
    "current_streak": 2,
    "hints_used": 3,
    "attempts_history": [...]
  }
}

Contributing

Adding New Lessons

1. Create lesson content in appropriate module (binary_basics.py, logic_gates.py, etc.)
2. Add problem generation logic to practice_generator.py
3. Update LessonInterface in interactive_tutor.py
4. Add lesson to menu in TutorOrchestrator

Extending Problem Types

1. Add new problem type to PracticeGenerator.generate_problem()
2. Implement answer validation in PracticeGenerator.check_answer()
3. Create progressive hints in PracticeGenerator.get_hint()
4. Update input validation in InputHandler.get_answer()

Coding Standards

• Use type hints for all function parameters and returns
• Write docstrings with examples for public methods
• Keep functions focused and single-purpose
• Use dataclasses for structured data
• Follow PEP 8 style guidelines
• Add educational value - explain the "why" not just the "what"

Architecture

For detailed architecture documentation, see:

• /Users/bhunt/development/claude/binary/ARCHITECTURE.md - Complete system architecture
• /Users/bhunt/development/claude/binary/QUICKSTART.md - Getting started guide
• /Users/bhunt/development/claude/binary/src/MODULE_DOCUMENTATION.md - API reference

Design Principles

1. Educational First: Every operation includes explanations, not just answers
2. Progressive Complexity: Start simple, add complexity as students improve
3. Visual Learning: ASCII diagrams and formatted output for visual learners
4. Immediate Feedback: Real-time validation and hints
5. Persistent Progress: Sessions save automatically for continuous learning

License & Author

Author: bhunt Role: Network Engineer & Developer Purpose: Educational tool for computer science freshmen

License: This is an educational project. Feel free to use, modify, and distribute for learning purposes.

Additional Resources

Quick Reference Files

• QUICKSTART.md - 5-minute getting started guide
• QUICK_REFERENCE.md - Cheat sheet for common operations
• EXAMPLE_SCENARIOS.md - Real-world usage examples
• IMPLEMENTATION_GUIDE.md - Developer guide for contributors

System Documentation

• ARCHITECTURE_SUMMARY.md - High-level system overview
• INTERACTIVE_TUTOR_ARCHITECTURE.md - CLI design patterns
• LOGIC_GATES_ARCHITECTURE.md - Logic gates implementation
• SYSTEM_DIAGRAMS.md - Visual architecture diagrams

Support

For questions, issues, or contributions:

1. Check existing documentation in /docs/
2. Review example usage in /examples/
3. Run the demo script: python3 demo_tutor.py
4. Contact: bhunt (Network Engineer & Developer)

---

Happy Learning! Master binary mathematics, logic gates, and digital electronics with interactive, adaptive lessons designed for freshman computer science students.