🚀 Quick Start Guide

Get up and running with Setwise in under 5 minutes! This guide will walk you through creating your first professional quiz with the new v2.0 features.

Step 1: Installation

Choose your preferred installation method:

# Core Setwise package
pip install git+https://github.com/nipunbatra/setwise.git
# Includes Streamlit web interface
pip install git+https://github.com/nipunbatra/setwise.git[web]
# Everything including development tools
pip install git+https://github.com/nipunbatra/setwise.git[dev,web,security]
NotePrerequisites
  • Python 3.8+
  • LaTeX distribution (TeX Live, MiKTeX, or MacTeX)
  • Git (for installation from GitHub)

Quick LaTeX install:

# Ubuntu/Debian
sudo apt-get install texlive-full

# macOS
brew install --cask mactex

# Windows - Download from https://miktex.org/

Step 2: Create Your First Quiz

Create a Question File

Create my_first_quiz.py with the new v2.0 features:

#!/usr/bin/env python3
"""My First Setwise v2.0 Quiz"""

# NEW v2.0: Professional quiz metadata
quiz_metadata = {
    "title": "Introduction to Science Quiz",
    "subject": "General Science",
    "duration": "30 minutes", 
    "total_marks": 15,
    "instructions": ["Answer all questions", "Show your work where applicable"]
}

# Multiple choice questions (including NEW templated MCQ!)
mcq = [
    # Regular MCQ question (v1.x compatible)
    {
        "question": r"What is the chemical symbol for water?",
        "options": [r"H$_2$O", r"CO$_2$", r"NaCl", r"O$_2$"],
        "answer": r"H$_2$O",
        "marks": 2
    },
    
    # NEW v2.0: Templated MCQ with dynamic values!
    {
        "template": r"A circle has radius {{ r }} cm. What is its area? (π ≈ 3.14)",
        "options": [
            r"{{ 3.14 * r**2 }} cm²",      # Correct: πr²
            r"{{ 2 * 3.14 * r }} cm²",     # Wrong: circumference
            r"{{ 3.14 * r }} cm²",         # Wrong: π×r
            r"{{ r**2 }} cm²"              # Wrong: just r²
        ],
        "answer": r"{{ 3.14 * r**2 }} cm²",
        "variables": [
            {"r": 3},   # Area = 28.26 cm²
            {"r": 5},   # Area = 78.5 cm²
            {"r": 2}    # Area = 12.56 cm²
        ],
        "marks": 3
    }
]

# Subjective questions (including multi-part!)
subjective = [
    # Regular subjective question
    {
        "question": r"Explain the difference between speed and velocity.",
        "answer": r"Speed is scalar (magnitude only), velocity is vector (magnitude + direction). Speed = distance/time, Velocity = displacement/time.",
        "marks": 4
    },
    
    # NEW v2.0: Enhanced multi-part question
    {
        "question": r"Motion Analysis:",
        "parts": [
            {
                "question": r"A car travels 60 km in 1 hour. Calculate its speed.",
                "answer": r"Speed = Distance/Time = 60 km / 1 hour = 60 km/h",
                "marks": 2
            },
            {
                "question": r"If the car maintains this speed, how far will it travel in 2.5 hours?",
                "answer": r"Distance = Speed × Time = 60 km/h × 2.5 h = 150 km",
                "marks": 2
            }
        ],
        "marks": 4
    }
]

Generate Your Quiz

# Generate 3 randomized quiz sets
setwise generate --questions-file my_first_quiz.py --sets 3

# Use a specific random seed for reproducibility
setwise generate --questions-file my_first_quiz.py --sets 3 --seed 42

# Try different templates
setwise generate --questions-file my_first_quiz.py --template compact --sets 2

Output: You’ll get professional PDF quiz sets + answer keys!

output/
├── quiz_set_1.pdf      # Beautiful LaTeX quiz
├── quiz_set_2.pdf      # Same questions, different order
├── quiz_set_3.pdf      # Randomized MCQ options
├── answer_key_1.txt    # Complete solutions
├── answer_key_2.txt
└── answer_key_3.txt

Step 3: Explore Advanced Features

Try the Web Interface

Launch the user-friendly web interface:

streamlit run setwise_web.py

Features: - 📝 Visual question editor with syntax highlighting - 🔍 Live validation and error checking
- 📊 PDF preview with download buttons - 📚 Built-in examples (Physics, Machine Learning, etc.) - ✨ NEW v2.0 features prominently showcased

Use Built-in Examples

# List available examples
setwise questions list

# Generate with professional examples
wget https://raw.githubusercontent.com/nipunbatra/setwise/main/examples/physics_questions.py
setwise generate --questions-file physics_questions.py --sets 2

# Try machine learning examples  
wget https://raw.githubusercontent.com/nipunbatra/setwise/main/examples/computer_science_questions.py
setwise generate --questions-file computer_science_questions.py --sets 2

Validate and Fix Questions

# Validate your question file
setwise questions validate my_first_quiz.py

# Fix common LaTeX errors automatically
setwise questions fix-latex my_first_quiz.py

# Get comprehensive LaTeX help
setwise questions latex-help

Step 4: Master Templates (NEW v2.0!)

The most powerful new feature! Create dynamic questions with variables:

Basic Template Example

mcq = [{
    "template": r"What is {{ a }} + {{ b }}?",
    "options": [
        r"{{ a + b }}",         # Correct
        r"{{ a - b }}",         # Common mistake
        r"{{ a * b }}",         # Different operation
        r"{{ (a + b) * 2 }}"    # Double the answer
    ],
    "answer": r"{{ a + b }}",
    "variables": [
        {"a": 3, "b": 7},   # Creates: What is 3 + 7? Answer: 10
        {"a": 12, "b": 8},  # Creates: What is 12 + 8? Answer: 20
        {"a": 5, "b": 9}    # Creates: What is 5 + 9? Answer: 14
    ],
    "marks": 2
}]

Advanced Physics Template

mcq = [{
    "template": r"A projectile launched at {{ angle }}° with velocity {{ v0 }} m/s. Maximum height?",
    "options": [
        r"$h = \frac{({{ v0 }} \sin {{ angle }}°)^2}{2g}$ = {{ height:.1f }} m",  # Correct
        r"$h = \frac{{{ v0 }}^2}{2g}$ = {{ v0**2 / (2*9.8):.1f }} m",
        r"$h = {{ v0 }} \sin {{ angle }}°$ = {{ v0 * 0.5 if angle == 30 else v0 * 0.707:.1f }} m",  
        r"$h = \frac{{{ v0 }}}{g}$ = {{ v0 / 9.8:.1f }} m"
    ],
    "answer": r"$h = \frac{({{ v0 }} \sin {{ angle }}°)^2}{2g}$ = {{ height:.1f }} m",
    "variables": [
        {"angle": 30, "v0": 20, "height": 5.1},   # sin(30°) = 0.5
        {"angle": 45, "v0": 25, "height": 15.9},  # sin(45°) = 0.707
        {"angle": 60, "v0": 30, "height": 34.4}   # sin(60°) = 0.866
    ],
    "marks": 4
}]

Step 5: Try Different Templates

Setwise includes 3 professional templates:

# List available templates
setwise list-templates

# Default: Professional single-column (formal exams)
setwise generate --template default --questions-file my_first_quiz.py --sets 2

# Compact: Space-efficient two-column (printing)
setwise generate --template compact --questions-file my_first_quiz.py --sets 2

# Minimal: Clean black & white (simple assessments)
setwise generate --template minimal --questions-file my_first_quiz.py --sets 2

Common Commands Reference

Generation

# Basic generation
setwise generate

# Custom questions
setwise generate --questions-file quiz.py

# Multiple sets with seed
setwise generate --seed 42 --sets 5

# Specific question counts
setwise generate --mcq 5 --subjective 3

Question Management

# Validate questions
setwise questions validate file.py

# Create sample file
setwise questions create-sample new.py

# Fix LaTeX errors
setwise questions fix-latex file.py

# Get statistics
setwise questions stats file.py

Next Steps

🎉 Congratulations! You’ve created your first Setwise quiz with v2.0 features.

Explore more:

📚 Examples

Ready-to-use subject-specific question libraries

🎯 v2.0 Features

Deep dive into all new capabilities

📝 Question Format

Complete reference for writing questions

Troubleshooting

WarningCommon Issues

LaTeX not found:

# Install LaTeX first
sudo apt-get install texlive-full  # Ubuntu
brew install --cask mactex        # macOS

Question validation errors:

# Check your Python syntax
setwise questions validate my_quiz.py

# Auto-fix common LaTeX issues
setwise questions fix-latex my_quiz.py

Import errors:

# Reinstall with all dependencies
pip install --upgrade git+https://github.com/nipunbatra/setwise.git[web]

Get Help

  • 📖 Full Documentation: Browse this site’s navigation menu
  • 🐛 Report Issues: GitHub Issues
  • 💬 Community: GitHub Discussions
  • 🆘 Command Help: setwise --help or setwise questions --help

Ready for more advanced features?

Explore v2.0 Features View Examples