Quick Start Guide

Installation

1. Ensure Ascend environment is set up:

   # Check msprof availability
   which msprof
   
   # Set environment variables
   export ASCEND_HOME_PATH=/usr/local/Ascend
   export PATH=$ASCEND_HOME_PATH/bin:$PATH
   

2. Install Python dependencies:

   pip install torch torch_npu
   pip install pyyaml pandas  # optional, for advanced features
   

3. Install MindSpeed-Ops in development mode:

   cd /path/to/MindSpeed-Ops
   pip install -e .
   

Basic Usage

1. Test a Single API (Random Mode)

# Test Triton add API
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input [10,10] x float32 \
     --input [10,10] y float16

2. Load Tensors from Files

# Load tensors from .pth files
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input-mode file \
     --input path/to/x.pth x \
     --input path/to/y.pth y

3. With Optional Parameters

# JSON format optional parameters
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input [10,10] x float32 \
     --input [10,10] y float32 \
     --other-optional-params '{"alpha": 0.5}'

4. Fixed Random Seed

# Use custom seed for reproducibility
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input [10,10] x float32 \
     --input [10,10] y float32 \
     --seed 123

Common Examples

Example 1: Quick Performance Check

# Check add API performance with default settings
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input [1024,1024] x float32 \
     --input [1024,1024] y float16

Example 2: Matmul with Parameters

# Matmul with transpose options
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.aclnn.matmul import matmul" \
     --input [256,256] a float32 \
     --input [256,256] b float32 \
     --other-optional-params '{"transpose_a": false, "transpose_b": false}'

Example 3: Tensor Parameters

# Generate tensor parameters
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.custom_op import custom_op" \
     --input [10,10] x float32 \
     --other-optional-params '{
       "alpha": 0.5,
       "bias": {"is_tensor": true, "shape": [10, 10], "dtype": "float32"}
     }'

Example 4: Different Implementations

# Test ACLNN implementation
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.aclnn.matmul import matmul" \
     --input [256,256] a float32 \
     --input [256,256] b float32

# Test TileLang implementation
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.tilelang.custom_op import custom_op" \
     --input [10,10] x float32

Example 5: Batch Testing

# Test multiple APIs
for api in "triton.add" "aclnn.matmul" "tilelang.custom_op"; do
    echo "Testing $api..."
    python operator_performance_profile.py \
         --api "from mindspeed_ops.api.$api import $(echo $api | cut -d. -f2)" \
         --input [256,256] x float32 \
         --input [256,256] y float32 \
         --output-format json \
         --output-file ${api}_results.json
done

API Path Format

The --api parameter requires a full import path:

"from <module_path> import <function_name>"

Valid Formats

# �?Correct: Full import path
--api "from mindspeed_ops.api.triton.add import add"

# �?Correct: ACLNN implementation
--api "from mindspeed_ops.api.aclnn.matmul import matmul"

# �?Correct: TileLang implementation
--api "from mindspeed_ops.api.tilelang.custom_op import custom_op"

# �?Incorrect: Missing import statement
--api "mindspeed_ops.api.triton.add"

# �?Incorrect: Missing module path
--api "add"

Input Modes

Random Mode (Default)

Generate random tensors with specified shape and dtype:

python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input-mode random \
     --input [10,10] x float32 \
     --input [10,10] y float16

File Mode

Load tensors from .pth files:

python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input-mode file \
     --input data/x.pth x \
     --input data/y.pth y

Optional Parameters

Simple Values

# Single parameter
--other-optional-params '{"alpha": 0.5}'

# Multiple parameters
--other-optional-params '{"alpha": 0.5, "block_size": 512, "inplace": true}'

Tensor Parameters

# Generate tensor with specified shape and dtype
--other-optional-params '{"bias": {"is_tensor": true, "shape": [10, 10], "dtype": "float32"}}'

Mixed Parameters

# Mix of simple values and tensor parameters
--other-optional-params '{
  "alpha": 0.5,
  "bias": {"is_tensor": true, "shape": [10, 10], "dtype": "float32"},
  "gamma": 1.5
}'

Random Seed

The tool uses a fixed random seed to ensure reproducible results:

• Default seed: 42
• Custom seed: Use --seed parameter
• Effect: Same random tensors generated each run

# Use default seed (42)
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input [10,10] x float32

# Use custom seed
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input [10,10] x float32 \
     --seed 123

Python API Usage

Basic Testing

from operator_performance_profile import OperatorPerformanceComparator

# Create comparator
comparator = OperatorPerformanceComparator()

# Define inputs
inputs = [
    {'name': 'x', 'shape': [10, 10], 'dtype': 'float32', 'mode': 'random'},
    {'name': 'y', 'shape': [10, 10], 'dtype': 'float16', 'mode': 'random'}
]

# Run test
results = comparator.compare_single_api(
    api_path="from mindspeed_ops.api.triton.add import add",
    inputs=inputs,
    iterations=100
)

# Print results
print(results)

Advanced Usage

from operator_performance_profile import OperatorPerformanceComparator

comparator = OperatorPerformanceComparator()

# Test with file inputs
inputs = [
    {'name': 'x', 'file_path': 'data/x.pth', 'mode': 'file'},
    {'name': 'y', 'file_path': 'data/y.pth', 'mode': 'file'}
]

# With optional parameters
optional_params = {
    'alpha': 0.5,
    'bias': {
        'is_tensor': True,
        'shape': [10, 10],
        'dtype': 'float32'
    }
}

# Run test with seed
results = comparator.compare_single_api(
    api_path="from mindspeed_ops.api.triton.custom_op import custom_op",
    inputs=inputs,
    iterations=100,
    optional_params=optional_params,
    seed=42
)

Output Examples

Text Report

============================================================
OP_STATISTIC CSV DATA (Filtered Columns)
============================================================
Note: Showing only OP_Type, Core_Type, MinTime, Avg_Time, Max_Time, Count columns
============================================================

API: from mindspeed_ops.api.triton.add import add
Input specifications:
  x: shape=[10, 10], dtype=float32
  y: shape=[10, 10], dtype=float16

Random seed: 42

Data Type: float32_float16
Source file: op_statistic_0.csv
Shape: 5 rows × 6 columns
------------------------------------------------------------
OP Type         Core Type  Min Time(us)  Avg Time(us)  Max Time(us)  Count
----------------------------------------------------------------------
Add             AI Core    12.45         15.23         18.91         100

JSON Output

{
  "api_path": "from mindspeed_ops.api.triton.add import add",
  "module": "mindspeed_ops.api.triton.add",
  "function": "add",
  "seed": 42,
  "implementations": {
    "float32_float16": {
      "source_file": "op_statistic_0.csv",
      "is_op_statistic": true,
      "columns": ["OP Type", "Core Type", "Min Time(us)", "Avg Time(us)", "Max Time(us)", "Count"],
      "data": [...]
    }
  }
}

Troubleshooting

Common Issues

1. API import failed

   Error: Failed to import module 'mindspeed_ops.api.triton.add'
   

   Solution: Check module path and ensure module exists.

2. Function not found

   Error: Function 'add' not found in module
   

   Solution: Check function name and ensure it's exported.

3. Invalid API path format

   Error: Invalid API path format
   

   Solution: Use format: "from module.path import function"

   # �?Correct
   --api "from mindspeed_ops.api.triton.add import add"
   
   # �?Wrong format (missing quotes)
   --api from mindspeed_ops.api.triton.add import add
   

4. File not found

   Error: Input file not found: path/to/x.pth
   

   Solution: Check file path and ensure file exists.

5. NPU not available

   torch.npu.is_available() returns False
   

   Solution: Check NPU drivers and torch_npu installation.

Debug Mode

# Enable verbose output
export DEBUG=1
python operator_performance_profile.py \
     --api "from mindspeed_ops.api.triton.add import add" \
     --input [10,10] x float32 \
     --input [10,10] y float16

# Check generated script
cat benchmark_api/benchmark_add_*.py

Key Features

1. Single API Testing

• Test any API by specifying its import path
• No need to discover operators
• Direct and precise testing

2. Flexible Input Modes

• Random mode: Generate tensors with specified shape and dtype
• File mode: Load tensors from .pth files

3. JSON Parameter Format

• Easy-to-use JSON format for optional parameters
• Support for simple values and tensor parameters
• Type-safe parameter specification

4. Fixed Random Seed

• Reproducible results with configurable seed
• Default seed: 42
• Ensures consistency across runs

5. No Warmup Runs

• Direct benchmarking without warmup iterations
• Faster execution time
• More accurate performance measurement

Next Steps

1. Explore Examples: Run the example scripts in the examples/ directory
2. Customize Configuration: Modify config.yaml for your needs
3. Test with Real Data: Use file mode with your actual data
4. Integrate with CI/CD: Add performance testing to your pipeline

Getting Help

• Check the README.md for detailed documentation
• Run python operator_performance_profile.py --help for command-line options
• Look at example scripts in the examples/ directory
• Check the API configurations in the code