User Experience Patterns: Realistic Usage Examples

[jeremymanning]

Summary

Document realistic user experience patterns from development scripts that demonstrate proper clustrix usage.

User Pattern 1: Structured Analysis Module

From user_analysis.py - How users should organize their code:

# users/analysis_module.py
from clustrix import cluster

@cluster(
    cores=1,
    memory="512Mi",
    platform="kubernetes",
    auto_provision=True,
    provider="local",
    node_count=2
)
def analyze_data(dataset_size: int, complexity: str = "medium"):
    """User's analysis function - properly structured for remote execution"""
    # All imports inside function for serialization
    import platform, socket, time, math
    
    # Realistic computation
    if complexity == "simple":
        result = dataset_size * 2
    elif complexity == "medium":
        result = sum(math.sqrt(i) for i in range(min(dataset_size, 1000)))
    else:
        result = sum(math.sin(i) * math.cos(i) for i in range(min(dataset_size, 5000)))
    
    # Return comprehensive results
    return {
        "computation_result": result,
        "execution_info": {
            "hostname": socket.gethostname(),
            "platform": platform.platform()
        }
    }

User Pattern 2: Complete Workflow

From user_workflow_test.py - End-to-end user experience:

1. Configuration Setup:

def setup_kubernetes_config():
    config = ClusterConfig()
    config.cluster_type = "kubernetes"
    config.auto_provision_k8s = True
    config.k8s_provider = "local"
    config.k8s_node_count = 2
    return config

2. Function Definition:

@cluster(
    cores=1, 
    memory="512Mi", 
    platform="kubernetes",
    auto_provision=True,
    parallel=False  # Clean testing
)
def analyze_data(size, multiplier=1):
    # All imports inside for remote execution
    import math, socket, platform, time
    
    # Realistic user computation
    total = sum(math.sqrt(i * multiplier) for i in range(min(size, 1000)))
    
    return {
        "analysis_result": total,
        "execution_environment": {"hostname": socket.gethostname()}
    }

3. Normal Function Call:

# Users call their functions completely normally
result = analyze_data(1000, 2)

# Process results as expected
print(f"Result: {result['analysis_result']}")
print(f"Executed on: {result['execution_environment']['hostname']}")

User Pattern 3: Standalone Function Module

From working_functions.py - Simple importable functions:

def analyze_dataset_simple(size, complexity="medium"):
    """Simple function users can import and use with @cluster"""
    import math, platform, socket, time
    
    # User's actual computation
    if complexity == "simple":
        result = size * 2
    elif complexity == "medium":
        result = sum(math.sqrt(i) for i in range(min(size, 1000)))
    
    return {
        "computation": {"result": result},
        "environment": {"hostname": socket.gethostname()},
        "success": True
    }

Key User Experience Insights

1. Function Structure: Users should define functions in modules, not interactively
2. Import Placement: All imports must be inside functions for proper serialization
3. Configuration: Simple config setup with sensible defaults
4. Function Calls: Completely transparent - users call functions normally
5. Results: Rich return values with execution context
6. Error Handling: Clear success/failure indicators

Migration Value

These patterns should inform:

• Documentation examples
• Tutorial content
• Best practices guide
• Function template generation

Source: Repository cleanup Issue #72