# 🚀 ttperf - TT-Metal Performance Profiler
<div align="center">
[](https://github.com/Aswintechie/ttperf/issues)
[](https://github.com/Aswintechie/ttperf/stargazers)
**A streamlined CLI tool for profiling Tenstorrent's TT-Metal tests and extracting device kernel performance metrics**
</div>
## ✨ Features
- 🔍 **Automated Profiling**: Seamlessly runs Tenstorrent's TT-Metal profiler with pytest
- 📊 **CSV Analysis**: Automatically extracts and parses performance CSV files
- ⚡ **Real-time Output**: Shows profiling progress in real-time
- 📈 **Performance Metrics**: Calculates total DEVICE KERNEL DURATION
- 🎯 **Simple CLI**: Easy-to-use command-line interface
- 🛠️ **Flexible**: Supports named profiles and various test paths
- 🚀 **Operation-based Profiling**: Profile specific operations by name (e.g., `ttperf add`)
- ⚙️ **Dynamic Configuration**: Customize tensor shape, dtype, and layout for operations
## 🚀 Quick Start
### Installation
```bash
# Install from PyPI (recommended)
pip install ttperf
```
**Or install from source:**
```bash
# Clone the repository
git clone https://github.com/Aswintechie/ttperf.git
cd ttperf
# Install the package
pip install -e .
```
### Basic Usage
```bash
# Run profiling on a specific test
ttperf test_performance.py
# Run with a custom profile name
ttperf my_profile pytest test_performance.py
# Run on a specific test method
ttperf tests/test_ops.py::test_matmul
# Profile specific operations by name
ttperf add
ttperf relu
ttperf matmul
# Profile operations with custom profile names
ttperf my_add_profile add
ttperf my_relu_profile relu
# Profile operations with custom configuration
ttperf add --shape 1,1,32,32 --dtype bfloat16 --layout tile
ttperf relu --shape 1,1,64,64 --dtype float32 --layout row_major
# Profile operations with memory configuration
ttperf add --dram # Use DRAM memory (default)
ttperf relu --l1 # Use L1 memory
ttperf add --shape 1,1,64,64 --l1 # Combined options
```
## 📋 Usage Examples
### Test File Profiling
```bash
ttperf test_conv.py
```
### Named Profile
```bash
ttperf conv_benchmark pytest test_conv.py
```
### Specific Test Method
```bash
ttperf tests/ops/test_matmul.py::test_basic_matmul
```
### Operation-based Profiling
```bash
# Basic operations
ttperf add
ttperf subtract
ttperf multiply
ttperf divide
# Activation functions
ttperf relu
ttperf sigmoid
ttperf tanh
ttperf gelu
# Mathematical operations
ttperf sqrt
ttperf exp
ttperf log
ttperf sin
ttperf cos
# Comparison operations
ttperf gt
ttperf lt
ttperf eq
ttperf ne
# Reduction operations
ttperf max
ttperf min
ttperf mean
ttperf sum
# Backward operations
ttperf add_bw
ttperf relu_bw
ttperf sigmoid_bw
```
### Dynamic Configuration
```bash
# Custom tensor shape
ttperf add --shape 1,1,32,32
ttperf relu --shape 2,3,64,128
# Custom data type
ttperf add --dtype float32
ttperf multiply --dtype int32
# Custom memory layout
ttperf add --layout row_major
ttperf relu --layout tile
# Combined configuration
ttperf add --shape 1,1,64,64 --dtype float32 --layout row_major
ttperf gelu --shape 2,1,32,32 --dtype bfloat16 --layout tile
# Memory configuration options
ttperf add --memory-config dram # Explicit DRAM
ttperf relu --memory-config l1 # Explicit L1
ttperf add --dram --shape 1,1,128,128 # DRAM with custom shape
ttperf relu --l1 --dtype float32 # L1 with custom dtype
```
### List All Supported Operations
```bash
ttperf --list-ops
# or
ttperf -l
```
### Output Example
```
🔧 Using custom configuration:
Shape: (1, 1, 32, 32)
Dtype: bfloat16
Layout: tile
🏷️ Auto-generated profile name: temp_test_add
▶️ Running: ./tt_metal/tools/profiler/profile_this.py -n temp_test_add -c "pytest temp_test_add.py"
... (profiling output) ...
📁 Found CSV path: /path/to/profile_results.csv
⏱️ DEVICE KERNEL DURATION [ns] total: 1234567.89 ns
```
## 🛠️ How It Works
1. **Command Parsing**: Analyzes input arguments to determine profile name and test path/operation
2. **Operation Detection**: If an operation name is provided, maps it to the corresponding test method
3. **Dynamic Configuration**: If custom configuration is provided, generates a temporary test file with the specified parameters
4. **Profile Execution**: Runs the Tenstorrent's TT-Metal profiler with the specified test
5. **Output Monitoring**: Streams profiling output in real-time
6. **CSV Extraction**: Parses the output to find the generated CSV file path
7. **Performance Analysis**: Reads the CSV and calculates total device kernel duration
## 📊 Performance Metrics
The tool extracts the following key metrics:
- **DEVICE KERNEL DURATION [ns]**: Total time spent in device kernels
- **CSV Path**: Location of the detailed profiling results
- **Real-time Progress**: Live output during profiling
## ⚙️ Configuration Options
### Shape Configuration
- **Format**: Comma-separated integers (e.g., `1,1,32,32`)
- **Default**: `(1, 1, 1024, 1024)`
- **Example**: `--shape 2,3,64,128`
### Data Type Configuration
- **Valid Options**: `bfloat16`, `float32`, `int32`
- **Default**: `bfloat16`
- **Example**: `--dtype float32`
### Layout Configuration
- **Valid Options**: `tile`, `row_major`
- **Default**: `tile`
- **Example**: `--layout row_major`
## 🔧 Requirements
- Python 3.8+
- pandas
- Tenstorrent's TT-Metal development environment
- pytest
## 📁 Project Structure
```
ttperf/
├── ttperf.py # Main CLI implementation
├── pyproject.toml # Project configuration
├── README.md # This file
└── .gitignore # Git ignore rules
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ⚠️ Disclaimer
This tool is an independent utility that interfaces with Tenstorrent's TT-Metal profiling tools. It is not affiliated with or endorsed by Tenstorrent Inc. The tool serves as a convenience wrapper around existing TT-Metal profiling infrastructure.
## 🐛 Issues
If you encounter any issues, please [create an issue](https://github.com/Aswintechie/ttperf/issues) on GitHub.
## 👨💻 Author
**Aswin Z**
- GitHub: [@Aswintechie](https://github.com/Aswintechie)
- Portfolio: [aswinlocal.in](https://aswinlocal.in)
## 🌟 Acknowledgments
- Tenstorrent's TT-Metal development team for the profiling tools
- Python community for excellent libraries like pandas
---
<div align="center">
Made with ❤️ for the Tenstorrent TT-Metal community
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "ttperf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "tenstorrent, tt-metal, profiling, performance, cli",
"author": null,
"author_email": "Aswin <aswin@aswincloud.com>",
"download_url": "https://files.pythonhosted.org/packages/eb/36/f3c542ba38fa9bea1ab0a08fcf9bda40db142fd07e6788e86cb29013a58e/ttperf-0.1.5.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 ttperf - TT-Metal Performance Profiler\n\n<div align=\"center\">\n\n\n\n\n[](https://github.com/Aswintechie/ttperf/issues)\n[](https://github.com/Aswintechie/ttperf/stargazers)\n\n**A streamlined CLI tool for profiling Tenstorrent's TT-Metal tests and extracting device kernel performance metrics**\n\n</div>\n\n## \u2728 Features\n\n- \ud83d\udd0d **Automated Profiling**: Seamlessly runs Tenstorrent's TT-Metal profiler with pytest\n- \ud83d\udcca **CSV Analysis**: Automatically extracts and parses performance CSV files\n- \u26a1 **Real-time Output**: Shows profiling progress in real-time\n- \ud83d\udcc8 **Performance Metrics**: Calculates total DEVICE KERNEL DURATION\n- \ud83c\udfaf **Simple CLI**: Easy-to-use command-line interface\n- \ud83d\udee0\ufe0f **Flexible**: Supports named profiles and various test paths\n- \ud83d\ude80 **Operation-based Profiling**: Profile specific operations by name (e.g., `ttperf add`)\n- \u2699\ufe0f **Dynamic Configuration**: Customize tensor shape, dtype, and layout for operations\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI (recommended)\npip install ttperf\n```\n\n**Or install from source:**\n\n```bash\n# Clone the repository\ngit clone https://github.com/Aswintechie/ttperf.git\ncd ttperf\n\n# Install the package\npip install -e .\n```\n\n### Basic Usage\n\n```bash\n# Run profiling on a specific test\nttperf test_performance.py\n\n# Run with a custom profile name\nttperf my_profile pytest test_performance.py\n\n# Run on a specific test method\nttperf tests/test_ops.py::test_matmul\n\n# Profile specific operations by name\nttperf add\nttperf relu\nttperf matmul\n\n# Profile operations with custom profile names\nttperf my_add_profile add\nttperf my_relu_profile relu\n\n# Profile operations with custom configuration\nttperf add --shape 1,1,32,32 --dtype bfloat16 --layout tile\nttperf relu --shape 1,1,64,64 --dtype float32 --layout row_major\n\n# Profile operations with memory configuration\nttperf add --dram # Use DRAM memory (default)\nttperf relu --l1 # Use L1 memory\nttperf add --shape 1,1,64,64 --l1 # Combined options\n```\n\n## \ud83d\udccb Usage Examples\n\n### Test File Profiling\n```bash\nttperf test_conv.py\n```\n\n### Named Profile\n```bash\nttperf conv_benchmark pytest test_conv.py\n```\n\n### Specific Test Method\n```bash\nttperf tests/ops/test_matmul.py::test_basic_matmul\n```\n\n### Operation-based Profiling\n```bash\n# Basic operations\nttperf add\nttperf subtract\nttperf multiply\nttperf divide\n\n# Activation functions\nttperf relu\nttperf sigmoid\nttperf tanh\nttperf gelu\n\n# Mathematical operations\nttperf sqrt\nttperf exp\nttperf log\nttperf sin\nttperf cos\n\n# Comparison operations\nttperf gt\nttperf lt\nttperf eq\nttperf ne\n\n# Reduction operations\nttperf max\nttperf min\nttperf mean\nttperf sum\n\n# Backward operations\nttperf add_bw\nttperf relu_bw\nttperf sigmoid_bw\n```\n\n### Dynamic Configuration\n```bash\n# Custom tensor shape\nttperf add --shape 1,1,32,32\nttperf relu --shape 2,3,64,128\n\n# Custom data type\nttperf add --dtype float32\nttperf multiply --dtype int32\n\n# Custom memory layout\nttperf add --layout row_major\nttperf relu --layout tile\n\n# Combined configuration\nttperf add --shape 1,1,64,64 --dtype float32 --layout row_major\nttperf gelu --shape 2,1,32,32 --dtype bfloat16 --layout tile\n\n# Memory configuration options\nttperf add --memory-config dram # Explicit DRAM\nttperf relu --memory-config l1 # Explicit L1 \nttperf add --dram --shape 1,1,128,128 # DRAM with custom shape\nttperf relu --l1 --dtype float32 # L1 with custom dtype\n```\n\n### List All Supported Operations\n```bash\nttperf --list-ops\n# or\nttperf -l\n```\n\n### Output Example\n```\n\ud83d\udd27 Using custom configuration:\n Shape: (1, 1, 32, 32)\n Dtype: bfloat16\n Layout: tile\n\ud83c\udff7\ufe0f Auto-generated profile name: temp_test_add\n\u25b6\ufe0f Running: ./tt_metal/tools/profiler/profile_this.py -n temp_test_add -c \"pytest temp_test_add.py\"\n\n... (profiling output) ...\n\n\ud83d\udcc1 Found CSV path: /path/to/profile_results.csv\n\u23f1\ufe0f DEVICE KERNEL DURATION [ns] total: 1234567.89 ns\n```\n\n## \ud83d\udee0\ufe0f How It Works\n\n1. **Command Parsing**: Analyzes input arguments to determine profile name and test path/operation\n2. **Operation Detection**: If an operation name is provided, maps it to the corresponding test method\n3. **Dynamic Configuration**: If custom configuration is provided, generates a temporary test file with the specified parameters\n4. **Profile Execution**: Runs the Tenstorrent's TT-Metal profiler with the specified test\n5. **Output Monitoring**: Streams profiling output in real-time\n6. **CSV Extraction**: Parses the output to find the generated CSV file path\n7. **Performance Analysis**: Reads the CSV and calculates total device kernel duration\n\n## \ud83d\udcca Performance Metrics\n\nThe tool extracts the following key metrics:\n\n- **DEVICE KERNEL DURATION [ns]**: Total time spent in device kernels\n- **CSV Path**: Location of the detailed profiling results\n- **Real-time Progress**: Live output during profiling\n\n## \u2699\ufe0f Configuration Options\n\n### Shape Configuration\n- **Format**: Comma-separated integers (e.g., `1,1,32,32`)\n- **Default**: `(1, 1, 1024, 1024)`\n- **Example**: `--shape 2,3,64,128`\n\n### Data Type Configuration\n- **Valid Options**: `bfloat16`, `float32`, `int32`\n- **Default**: `bfloat16`\n- **Example**: `--dtype float32`\n\n### Layout Configuration\n- **Valid Options**: `tile`, `row_major`\n- **Default**: `tile`\n- **Example**: `--layout row_major`\n\n## \ud83d\udd27 Requirements\n\n- Python 3.8+\n- pandas\n- Tenstorrent's TT-Metal development environment\n- pytest\n\n## \ud83d\udcc1 Project Structure\n\n```\nttperf/\n\u251c\u2500\u2500 ttperf.py # Main CLI implementation\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 .gitignore # Git ignore rules\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \u26a0\ufe0f Disclaimer\n\nThis tool is an independent utility that interfaces with Tenstorrent's TT-Metal profiling tools. It is not affiliated with or endorsed by Tenstorrent Inc. The tool serves as a convenience wrapper around existing TT-Metal profiling infrastructure.\n\n## \ud83d\udc1b Issues\n\nIf you encounter any issues, please [create an issue](https://github.com/Aswintechie/ttperf/issues) on GitHub.\n\n## \ud83d\udc68\u200d\ud83d\udcbb Author\n\n**Aswin Z**\n- GitHub: [@Aswintechie](https://github.com/Aswintechie)\n- Portfolio: [aswinlocal.in](https://aswinlocal.in)\n\n## \ud83c\udf1f Acknowledgments\n\n- Tenstorrent's TT-Metal development team for the profiling tools\n- Python community for excellent libraries like pandas\n\n---\n\n<div align=\"center\">\nMade with \u2764\ufe0f for the Tenstorrent TT-Metal community\n</div> \n",
"bugtrack_url": null,
"license": null,
"summary": "A Python CLI wrapper for profiling Tenstorrent's TT-Metal tests",
"version": "0.1.5",
"project_urls": {
"Documentation": "https://github.com/Aswintechie/ttperf/blob/master/README.md",
"Homepage": "https://github.com/Aswintechie/ttperf",
"Issues": "https://github.com/Aswintechie/ttperf/issues",
"Repository": "https://github.com/Aswintechie/ttperf"
},
"split_keywords": [
"tenstorrent",
" tt-metal",
" profiling",
" performance",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "855fee5b38a52704c895273cb81102502b517c9929b8bd7c53a8f2166f6de079",
"md5": "3868c29acc48fc3fbdc8e0c5d8681cc6",
"sha256": "f678dc579115c2a1dfb9a8e5339846002471acd0bc7d0a799bbc1aab1e320cf9"
},
"downloads": -1,
"filename": "ttperf-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3868c29acc48fc3fbdc8e0c5d8681cc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25594,
"upload_time": "2025-08-19T12:21:15",
"upload_time_iso_8601": "2025-08-19T12:21:15.837543Z",
"url": "https://files.pythonhosted.org/packages/85/5f/ee5b38a52704c895273cb81102502b517c9929b8bd7c53a8f2166f6de079/ttperf-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eb36f3c542ba38fa9bea1ab0a08fcf9bda40db142fd07e6788e86cb29013a58e",
"md5": "d8fd4365113056c67b38e25af477c29e",
"sha256": "b7175276a70cbe5248f6f1e4bee9734928ee75a6b0df64138b586786a337409f"
},
"downloads": -1,
"filename": "ttperf-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "d8fd4365113056c67b38e25af477c29e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27470,
"upload_time": "2025-08-19T12:21:16",
"upload_time_iso_8601": "2025-08-19T12:21:16.754786Z",
"url": "https://files.pythonhosted.org/packages/eb/36/f3c542ba38fa9bea1ab0a08fcf9bda40db142fd07e6788e86cb29013a58e/ttperf-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 12:21:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Aswintechie",
"github_project": "ttperf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
}
],
"lcname": "ttperf"
}
JSON
