getting_started.md

Getting Started with SerDes Validation Framework

Overview

This tutorial will guide you through:

1. Setting up your environment
2. Basic framework usage
3. Mock testing for development
4. Running your first validation tests

Installation

Prerequisites

• Python 3.10 or higher
• pip package manager
• git (for source installation)

Setup Steps

1. Clone the repository:

git clone https://github.com/muditbhargava66/serdes-validation-framework.git
cd serdes-validation-framework

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Basic Usage

Controller Setup

The framework supports both real hardware and mock testing modes:

from typing import Dict, Optional, Union
import numpy as np
from serdes_validation_framework.instrument_control import get_instrument_controller

# Initialize controller (auto-detects mode)
controller = get_instrument_controller()

# Check current mode
print(f"Operating in {controller.get_mode()} mode")

Instrument Connection

def connect_to_instrument(resource_name: str) -> None:
    """
    Connect to test instrument
    
    Args:
        resource_name: VISA resource identifier
        
    Raises:
        ConnectionError: If connection fails
    """
    try:
        controller.connect_instrument(resource_name)
        
        # Verify connection
        response = controller.query_instrument(resource_name, '*IDN?')
        print(f"Connected to: {response}")
        
    except Exception as e:
        raise ConnectionError(f"Failed to connect to {resource_name}: {e}")

Mock Testing

Enabling Mock Mode

For development without hardware:

# Method 1: Environment variable
import os
os.environ['SVF_MOCK_MODE'] = '1'

# Method 2: Command line
# Run your script with:
# SVF_MOCK_MODE=1 python your_script.py

Basic Mock Example

def run_basic_test() -> None:
    """Demonstrate basic framework usage"""
    # Force mock mode for example
    os.environ['SVF_MOCK_MODE'] = '1'
    
    try:
        # Initialize
        controller = get_instrument_controller()
        
        # Connect
        resource = 'GPIB::1::INSTR'
        controller.connect_instrument(resource)
        
        # Send commands
        controller.send_command(resource, '*RST')
        response = controller.query_instrument(resource, '*IDN?')
        print(f"Instrument response: {response}")
        
    finally:
        # Cleanup
        controller.disconnect_instrument(resource)

Custom Mock Responses

def configure_mock_measurements() -> None:
    """Configure custom mock responses"""
    controller = get_instrument_controller()
    
    # Add voltage measurement response
    controller.add_mock_response(
        'MEASure:VOLTage:DC?',
        lambda: f"{np.random.normal(1.0, 0.1):.6f}",
        delay=0.1
    )
    
    # Add temperature measurement
    controller.add_mock_response(
        'MEASure:TEMPerature?',
        lambda: f"{np.random.normal(25.0, 0.5):.2f}",
        delay=0.2
    )

Data Collection

Basic Measurement

def measure_voltage(channel: int) -> float:
    """
    Measure DC voltage
    
    Args:
        channel: Channel number
        
    Returns:
        Measured voltage in volts
    """
    # Validate input
    assert isinstance(channel, int), "Channel must be integer"
    assert channel > 0, "Channel must be positive"
    
    # Get voltage reading
    response = controller.query_instrument(
        'GPIB::1::INSTR',
        f':MEASure:VOLTage:DC? (@{channel})'
    )
    
    try:
        return float(response)
    except ValueError:
        raise ValueError(f"Invalid voltage response: {response}")

Waveform Capture

def capture_waveform(
    duration: float,
    sample_rate: float
) -> Dict[str, np.ndarray]:
    """
    Capture waveform data
    
    Args:
        duration: Capture duration in seconds
        sample_rate: Sample rate in Hz
        
    Returns:
        Dictionary with time and voltage arrays
    """
    # Validate inputs
    assert isinstance(duration, float), "Duration must be float"
    assert isinstance(sample_rate, float), "Sample rate must be float"
    assert duration > 0, "Duration must be positive"
    assert sample_rate > 0, "Sample rate must be positive"
    
    try:
        # Configure acquisition
        num_points = int(duration * sample_rate)
        controller.send_command(
            'GPIB::1::INSTR',
            f':ACQuire:POINts {num_points}'
        )
        
        # Get data
        response = controller.query_instrument(
            'GPIB::1::INSTR',
            ':WAVeform:DATA?'
        )
        
        # Convert to arrays
        voltage = np.array(response.split(','), dtype=np.float64)
        time = np.arange(len(voltage)) / sample_rate
        
        return {
            'time': time,
            'voltage': voltage
        }
        
    except Exception as e:
        raise RuntimeError(f"Waveform capture failed: {e}")

Data Analysis

Basic Statistics

def analyze_measurements(
    values: np.ndarray,
    name: str = "data"
) -> Dict[str, float]:
    """
    Calculate basic statistics
    
    Args:
        values: Measurement values array
        name: Data name for error messages
        
    Returns:
        Dictionary of statistics
    """
    # Validate input
    assert isinstance(values, np.ndarray), \
        f"{name} must be numpy array"
    assert np.issubdtype(values.dtype, np.floating), \
        f"{name} must be floating-point"
    assert len(values) > 0, f"{name} cannot be empty"
    
    return {
        'mean': float(np.mean(values)),
        'std': float(np.std(values)),
        'min': float(np.min(values)),
        'max': float(np.max(values))
    }

Complete Example

PAM4 Signal Analysis

from serdes_validation_framework.data_analysis import PAM4Analyzer

def analyze_pam4_signal() -> None:
    """Demonstrate complete PAM4 analysis"""
    # Force mock mode for example
    os.environ['SVF_MOCK_MODE'] = '1'
    
    try:
        # Capture data
        data = capture_waveform(
            duration=1e-6,    # 1 µs
            sample_rate=256e9  # 256 GSa/s
        )
        
        # Create analyzer
        analyzer = PAM4Analyzer(data)
        
        # Analyze levels
        levels = analyzer.analyze_level_separation()
        print("\nPAM4 Levels:")
        print(f"Means: {levels.level_means}")
        print(f"Separations: {levels.level_separations}")
        print(f"Uniformity: {levels.uniformity:.3f}")
        
        # Calculate EVM
        evm = analyzer.calculate_evm()
        print("\nEVM Results:")
        print(f"RMS EVM: {evm.rms_evm_percent:.2f}%")
        print(f"Peak EVM: {evm.peak_evm_percent:.2f}%")
        
        # Analyze eye diagram
        eye = analyzer.analyze_eye_diagram()
        print("\nEye Measurements:")
        print(f"Heights: {eye.eye_heights}")
        print(f"Worst height: {eye.worst_eye_height:.3f}")
        
    except Exception as e:
        print(f"Analysis failed: {e}")

Next Steps

• Mock Testing Tutorial - Detailed mock testing guide
• 224G Ethernet Tutorial - Protocol-specific validation
• PAM4 Analysis Tutorial - Advanced signal analysis

Troubleshooting

Common Issues

1. Mode Selection:

   # Check current mode
   mode = controller.get_mode()
   if mode != 'mock':
       print("Warning: Using real hardware mode")

2. Connection Problems:

   try:
       controller.connect_instrument(resource_name)
   except ConnectionError as e:
       print(f"Connection failed: {e}")
       # Try alternative resource or mock mode

3. Data Validation:

   # Validate numeric data
   if not np.issubdtype(data.dtype, np.floating):
       raise TypeError(f"Expected float data, got {data.dtype}")

Getting Help

• Check the API Documentation
• Review the Troubleshooting Guide
• File issues on GitHub

See Also

• Mock Controller Documentation
• PAM4 Analysis Documentation
• Environment Configuration