Perfect Numbers Network Documentation

Complete guide to setting up and running the Perfect Numbers Network distributed computing system.

Getting Started

The Perfect Numbers Network is a distributed computing system that searches for perfect numbers by testing Mersenne primes using the Lucas-Lehmer algorithm.

Prerequisites

Python 3.7 or higher installed
Basic command-line knowledge
Network connectivity (for distributed operation)

Quick Setup

# 1. Download and extract the project
# 2. Navigate to the project directory
cd perfect-numbers-network

# 3. Run the server (Terminal 1)
python server.py

# 4. Run a client (Terminal 2)
python client.py

# 5. Open the dashboard (Terminal 3)
python dashboard.py
# Visit http://localhost:8080

Running the Server

The server coordinates work distribution and tracks results.

Starting the Server

# Default port (5555)
python server.py

# Custom port
python server.py 8000

💡 Note: The server automatically creates a SQLite database (perfectnet.db) to track progress, users, and results.

Server Features

Work Distribution: Assigns untested exponents to clients
Progress Tracking: Monitors client progress in real-time
Automatic Reassignment: Reclaims expired work assignments
Result Storage: Stores all test results and discoveries
User Credits: Tracks contributions by username

Server Output

╔════════════════════════════════════════════════════════════╗
║  Perfect Number Network Server (GIMPS-style)             ║
╚════════════════════════════════════════════════════════════╝
Server: 0.0.0.0:5555
Database: perfectnet.db
Status: Waiting for clients...

Client registered: alice from 127.0.0.1:54321
Assigned p=127 to alice

Running Clients

Clients perform the computational work to find perfect numbers.

Starting a Client

# Connect to localhost
python client.py

# Connect to remote server
python client.py 192.168.1.100

# Specify custom port
python client.py localhost 8000

You'll be prompted to enter a username. Choose something memorable!

Client Workflow

Connects to the server
Registers with your username
Requests work assignment
Receives an exponent to test
Performs Lucas-Lehmer test
Reports progress every 5 minutes
Saves checkpoints every 10,000 iterations
Submits result when complete
Requests next assignment

Client Features

Progress Reporting: Updates server with current progress
Checkpointing: Saves state to resume interrupted work
ETA Display: Shows estimated time to completion
Automatic Recovery: Resumes from checkpoint after crash

🎉 Finding a Perfect Number: When a client discovers a Mersenne prime (and therefore a perfect number), both the server and client will display a celebration message!

Web Dashboard

The dashboard provides real-time monitoring of the entire network.

Starting the Dashboard

# Default port (8080)
python dashboard.py

# Custom port
python dashboard.py 9000

# Custom database
python dashboard.py 8080 perfectnet.db

Then open http://localhost:8080 in your web browser.

Dashboard Features

📊 Live Statistics: Queue size, active assignments, primes found
✨ Discoveries: All discovered perfect numbers
⚙️ Active Assignments: Real-time progress tracking
🏆 Top Contributors: Leaderboard of users
📈 Recent Results: Latest completed tests
🔄 Auto-Refresh: Updates every 10 seconds

Monitoring

Use the monitor tool for command-line status queries.

# Monitor localhost server
python monitor.py

# Monitor remote server
python monitor.py 192.168.1.100 5555

Monitor Output

The monitor displays:

Server connection status
Work queue statistics
Active assignments with progress
Top contributors leaderboard
Recent activity feed
Discovered perfect numbers
Next exponents in queue

Administration

The admin tool provides database management capabilities.

Adding Work

# Add specific exponents
python admin.py add-work 127 521 607 1279

# Add a range of prime exponents
python admin.py add-range 10000 20000

Managing Assignments

# Reset expired assignments
python admin.py reset

# Clear a user's assignments
python admin.py clear-user alice

Exporting Data

# Export all results to CSV
python admin.py export results.csv

Statistics and Maintenance

# Show detailed statistics
python admin.py stats

# Optimize database
python admin.py vacuum

Admin Commands Reference

Command	Description
`add-work`	Add specific exponents to queue
`add-range`	Add range of prime exponents
`reset`	Reset expired assignments
`clear-user`	Clear user's assignments
`export`	Export results to CSV
`stats`	Show detailed statistics
`vacuum`	Optimize database

Benchmarking

Test your system's performance before committing to long computations.

Running Benchmarks

# Quick benchmark (recommended first)
python benchmark.py quick

# Medium benchmark (~1 minute)
python benchmark.py medium

# Large benchmark (several minutes)
python benchmark.py large

# Test specific exponent
python benchmark.py 2281

Understanding Results

The benchmark will show:

Time per exponent
Iterations per second
Estimated completion times for various exponent sizes
Recommended exponent range for your system

💡 Tip: Run the quick benchmark first to understand what exponent sizes your system can handle efficiently.

Troubleshooting

Client Can't Connect to Server

Problem: "Could not connect to server"

Solutions:

Verify the server is running
Check the IP address and port are correct
Check firewall settings
Try: python monitor.py to test connectivity

Work Assignments Expiring

Problem: Assignments timing out before completion

Solutions:

Run python benchmark.py to test your system
Request smaller exponents from the admin
Ensure stable network connection

Database Locked

Problem: "Database is locked" error

Solutions:

Close all clients and dashboard
Restart the server
Run: python admin.py vacuum

Dashboard Not Loading

Problem: Can't access dashboard at localhost:8080

Solutions:

Verify dashboard.py is running
Try a different port: python dashboard.py 8081
Check if another application is using port 8080

Frequently Asked Questions

How long does it take to find a perfect number?

It depends on the exponent size and your hardware. Known perfect numbers up to 127 take seconds, while larger ones can take hours to months. Run python benchmark.py to get estimates for your system.

Can I run multiple clients on the same machine?

Yes! Just open multiple terminals and run python client.py in each. Use different usernames for each client.

What happens if my computer crashes during computation?

The client saves checkpoints every 10,000 iterations. When you restart, it will resume from the last checkpoint. The server will also reassign expired work if needed.

How is credit allocated?

Each user is credited for every completed test. If you discover a perfect number, you receive special recognition!

Can I pause and resume later?

Yes! Press Ctrl+C to stop the client. When you restart, it will load the checkpoint and continue where it left off.

What exponent range should I test?

Start with smaller exponents (under 10,000) to get familiar with the system. Run python benchmark.py for personalized recommendations based on your hardware.

Is this project connected to GIMPS?

This is an independent educational project inspired by GIMPS. For actual Mersenne prime hunting contributing to mathematical research, visit mersenne.org.

How do I contribute to the project development?

Visit our GitHub repository to report issues, suggest features, or submit pull requests!

Need More Help?

Check the Technical Documentation
Visit the GitHub Issues page
Join community discussions