Getting Started

This guide will help you install and start using OpenTestability.

Prerequisites

Python 3.7 or higher
pip (Python package manager)
Graphviz (for visualization)

Platform-Specific Requirements

Linux/WSL (Recommended)

sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv graphviz

macOS

brew install python3 graphviz

Windows

Install Python from python.org
Install Graphviz from graphviz.org
Add Graphviz to PATH

Installation

Method 1: Clone from GitHub

# Clone the repository
git clone https://github.com/ranaumarnadeem/OpenTestability.git
cd OpenTestability

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/macOS/WSL
# OR
.\venv\Scripts\Activate.ps1  # Windows PowerShell

# Install dependencies
pip install -r requirements.txt

Method 2: Install as Package

# Install in development mode
pip install -e .

# Or install from PyPI (when available)
pip install opentestability

Verify Installation

# Check if opentest executable works
./opentest

# You should see:
# ============================================================
# OpenTestability Tool Environment v1.0
# Professional Circuit Testability Analysis
# ============================================================

Quick Start with Test Point Insertion

The primary feature of OpenTestability - automated test point insertion for DFT:

Complete TPI Workflow

# Step 1: Generate testability metrics
./opentest cop -i data/input/priority_encoder.v -j

# Step 2: Insert test points based on metrics  
./opentest tpi -i data/parsed/priority_encoder.json \
               -m data/results/priority_encoder_cop.json \
               -t 50 -n 10

# Result: Enhanced Verilog with test points
# File: data/TPI/priority_encoder_tp.v

Quick TPI Examples

# Conservative approach - only worst signals
./opentest tpi -i design.json -m metrics.json -t 20 -n 5

# Aggressive approach - improve many signals
./opentest tpi -i design.json -m metrics.json -t 80 -n 20

# With verbose output to see detailed analysis
./opentest tpi -i design.json -m metrics.json -t 50 -n 10 -v

Supporting Analysis Features

One-Command Testability Analysis

Generate metrics for TPI or standalone analysis:

COP Analysis (for TPI)

# Generate COP metrics with JSON output (ideal for TPI)
./opentest cop -i data/input/priority_encoder.v -j

# With custom output
./opentest cop -i data/input/priority_encoder.v -o my_results.txt

# Results saved to data/results/

SCOAP Analysis (alternative for TPI)

# Generate SCOAP metrics (alternative to COP for TPI)
./opentest scoap -i data/input/serial_ALU.v

# With custom output  
./opentest scoap -i data/input/serial_ALU.v -o my_results.json

# Results saved to data/results/

What Happens Automatically

When you run cop -i design.v or scoap -i design.v, the tool automatically:

Parses Verilog file (.v → .txt → .json)
Creates DAG (saved to data/dag_output/)
Detects Reconvergence (using simple algorithm by default)
Runs Analysis with reconvergence-aware metrics
Enables Parallel (automatic for circuits >100,000 gates)
Outputs Results to data/results/ directory

Interactive Mode

./opentest

# Direct Verilog analysis
opentest> cop -i priority_encoder.v
opentest> scoap -i serial_ALU.v

# Auto commands with reconvergence
opentest> auto-cop -i circuit.txt
opentest> auto-scoap -i circuit.txt

opentest> help cop
opentest> exit

Traditional Workflow (Step-by-Step)

For fine-grained control, you can still use individual commands:

1. Start the Tool Environment

./opentest

2. Parse a Verilog Netlist

opentest> parse -i priority_encoder.v
[✓] Parsed priority_encoder.v -> /path/to/priority_enc_parsed.json

3. Create DAG

opentest> dag -i priority_enc_parsed.json
[✓] DAG saved to /path/to/priority_enc_dag.json

4. Run COP or SCOAP Analysis

# COP analysis (now with auto-reconvergence)
opentest> cop -i priority_enc.txt
[INFO] Automatic reconvergence detection enabled
[INFO] Circuit size: 17 gates
[INFO] Reconvergent sites detected: 13
[✓] COP analysis completed: /path/to/priority_enc_cop.txt

# SCOAP analysis (now with auto-reconvergence)
opentest> scoap -i priority_enc.txt
[INFO] Automatic reconvergence detection enabled
[INFO] Fanout points extracted: 5
[✓] SCOAP analysis completed: /path/to/priority_enc_scoap.json

# Use auto-cop/auto-scoap for explicit reconvergence
opentest> auto-cop -i priority_enc.txt -w 4
opentest> auto-scoap -i priority_enc.txt -w 4

COP and SCOAP now automatically detect reconvergent fanout and apply correlation-aware adjustments for improved accuracy. Parallel computation is automatically enabled for circuits >100,000 gates.

5. Analyze Reconvergence

opentest> reconv -i priority_enc_dag.json
[✓] Reconvergence analysis completed: /path/to/priority_enc_reconv.json

6. Visualize Circuit

opentest> visualize -i priority_enc_dag.json
[✓] Graph visualization saved to /path/to/priority_enc_graph.png

Understanding the Workflow

Verilog Auto-Pipeline

Verilog Netlist (.v)
    ↓ [cop/scoap -i design.v]
Automatic Processing:
  - Parse Verilog
  - Create DAG
  - Detect Reconvergence
  - Run Analysis (with parallel if >100k gates)
    ↓
Results (.txt/.json in data/results/)

Traditional: Step-by-Step

Verilog Netlist (.v)
    ↓ [parse]
Parsed Netlist (.txt + .json)
    ↓ [dag]
DAG Representation (.json)
    ↓ [cop/scoap/reconv/visualize]
Analysis Results (.json/.png/.txt)

File Formats

Input: Gate-level Verilog netlists from synthesis tools (Genus, Design Compiler)
Parsed: Text format with gate definitions + JSON format for programmatic access
DAG: JSON with edges, labels, and primary I/O information
Results: JSON with analysis metrics and visualization images

Directory Structure

After running commands, your project will have:

OpenTestability/
├── src/opentestability/
│   ├── core/
│   │   ├── cop/                # COP analysis (with parallel support)
│   │   ├── scoap/              # Modular SCOAP implementation
│   │   ├── dag/                # DAG construction
│   │   └── reconvergence/      # Reconvergence algorithms + integration
│   ├── parsers/                # Netlist parsers
│   ├── visualization/          # Graph visualization
│   └── utils/                  # Utilities
├── data/
│   ├── input/                  # Put your .v files here
│   ├── parsed/                 # Parsed netlists (.txt, .json)
│   ├── dag_output/             # DAG files (.json)
│   ├── results/                # COP and SCOAP results
│   ├── reconvergence_output/   # Reconvergence analysis results
│   └── graphs/                 # Visualization outputs (.png)
├── tests/                      # Comprehensive test suite
├── docs/                       # Documentation
└── examples/                   # Example scripts

Common Issues

Issue: “ModuleNotFoundError: No module named ‘pyverilog’”

Solution: Install dependencies with pip install -r requirements.txt

Issue: “pygraphviz import error”

Solution: Install Graphviz system package first, then reinstall pygraphviz

Issue: “Permission denied: ./opentest”

Solution: Make executable with chmod +x opentest

Issue: Relative import errors when running scripts directly

Solution: Use the opentest tool environment or run as module:

python3 -m opentestability.core.dag_builder file.json

Next Steps

Quick Analysis

Test Point Insertion

Advanced Features

Additional Resources

Command Reference - Complete CLI documentation
Examples - Practical usage examples
Test Point Insertion Guide - DFT implementation
GitHub Repository
Report Issues
Discussions
Contributing Guide
Changelog