Yet Another High Level AI Simulator
polaris is a high level simulator for performance analysis of AI architectures. It takes as input an AI Workload and an Architecture Configuration. It represents the input workload into an in-memory directed acyclic graph (DAG) data structure, where each node represents a computation or a communication operator, and each edge represents a dataflow. The graph data structure represents an intermediate representation (IR) for the Simulator virtual machine (VM). We can execute various graph transformations, and eventually schedule the DAG on a backend for performance analysis.
- Python 3.13 or higher
- Miniforge package manager
Execute git clone https://github.com/tenstorrent/polaris.git
The recommended setup uses Python with the Miniforge installation manager. It is expected that the reader is familiar with conda environments, creating and switching between environments. One can familiarize oneself with these concepts at Conda Getting Started.
-
Download and install Miniforge as described in the Miniforge Installation Instructions:
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" bash Miniforge3-$(uname)-$(uname -m).sh
-
Update conda:
conda update -n base -c conda-forge conda
-
Conda environment initialization: The install script prompts the user to initialize conda with your shell. After this step, the user needs to log out and login again (or, exit the terminal and start a new terminal session).
-
To enable conda command on the path, run
source <your-conda-install-path>/etc/profile.d/conda.sh
- Create and activate the Polaris environment. The conda environment will
be created with the name 'polaris'. If you wish to provide a different name to the environment, run the command
conda env create --file environment.yaml --name <name-of-your-choice>instead.conda env create --file environment.yaml conda activate polaris
- Create and activate the development environment. The conda environment will
be created with the name 'polarisdev'. If you wish to provide a different name to the environment, run the command
conda env create --file envdev.yaml --name <name-of-your-choice>instead.conda env create --file envdev.yaml conda activate polarisdev
- Install pre-commit hooks:
pre-commit install
python polaris.py [options] --archspec <arch_config> --wlspec <workload_spec> --wlmapspec <mapping_spec>--archspec, -a: Path to architecture specification YAML file--wlspec, -w: Path to workload specification YAML file--wlmapspec, -m: Path to workload mapping specification YAML file--study, -s: Name for the simulation study (default: "study")--odir, -o: Output directory for results (default: ".")--outputformat: Output format for results (none/yaml/json/pickle, default: json)--dump_stats_csv: Enable CSV stats output--dryrun, -n: Perform a dry run without actual simulation
--datatype, -d: Activation data type (fp64/fp32/tf32/fp16/bf16/fp8/int32/int8)--dump_ttsim_onnx: Dump ONNX graph for TTSIM workloads
--frequency: Frequency (MHz) range specification (start end step)--batchsize: Batch size range specification (start end step)
--enable_memalloc: Enable memory allocation simulation--instr_profile: Enable instruction profiling--enable_cprofile: Enable Python cProfile for performance analysis
--log_level, -l: Set logging level (debug/info/warning/error/critical, default: info)
--filterarch: Filter architecture configurations--filterwlg: Filter workload groups--filterwl: Filter specific workloads--filterwli: Filter workload instances
The architecture specification file (archspec) defines the hardware configuration including:
- Device specifications
- Memory hierarchy
- Compute resources
- Clock frequencies
The workload specification file (wlspec) defines:
- AI model configurations
- Batch sizes
- Input/output specifications
- Operator configurations
The workload mapping specification file (wlmapspec) defines:
- Operator to datatype mappings
- Resource requirements
- Operator fusion rules
- Null operations
Polaris supports multiple output formats:
- YAML: Human-readable structured format
- JSON: Web-friendly format
- Pickle: Binary format for Python objects
- CSV: Tabular format for statistics
The simulation provides various performance metrics including:
- Execution cycles and time
- Memory usage and requirements
- Resource bottlenecks
- Input/output parameter counts
- Resource utilization
output_dir/
├── study_name/
│ ├── SUMMARY/
│ │ └── study-summary.csv
│ └── stats/
│ ├── device-workload-stats.csv
│ └── device-workload-opstats.[yaml|json|pickle]
- Start with a dry run using
--dryrunto validate configurations - Use filtering options to focus on specific architectures or workloads
- Enable CSV output for easy data analysis
- Use appropriate output formats based on your needs:
- YAML for human readability
- JSON for web integration
- Pickle for Python processing
- Monitor memory requirements using
--enable_memalloc
-
Memory Constraints
- Use
--enable_memallocto check memory requirements - Verify device memory specifications
- Use
-
Performance Issues
- Enable profiling with
--enable_cprofile - Check resource bottlenecks in output statistics
- Enable profiling with
-
Configuration Errors
- Validate YAML syntax in specification files
- Use
--dryrunto check configurations - Verify file paths and permissions
Polaris includes tools for correlating simulated performance with measured hardware performance.
The correlation tool compares Polaris simulation results with actual hardware measurements from TT-Metal.
Quick Start:
# Step 1: Parse hardware metrics (creates metadata)
python tools/parse_ttsi_perf_results.py --tag <TAG>
# Step 2: Run correlation (reads data source from metadata)
python tools/run_ttsi_corr.py \
--tag <TAG> \
--workloads-config config/ttsi_correlation_workloads.yaml \
--arch-config config/tt_wh.yaml \
--output-dir __CORRELATION_OUTPUTNote: <TAG> identifies the reference data version (e.g., 03nov25, 15oct25). See Reference Data Tags below for details.
Polaris maintains versioned snapshots of TT-Metal reference performance data using tags:
- What are tags? Tags identify specific versions of TT-Metal hardware measurements (e.g.,
03nov25= November 3, 2025 measurements) - Current default: The default tag is automatically updated to use the latest reference data
- Available tags: See
TTSI_REF_VALID_TAGSintools/ttsi_corr/ttsi_corr_utils.pyfor all valid tags - Using older data: You can explicitly specify any valid tag with
--tag <TAG>to reproduce results with older reference data - Creating custom tags: To create a new tag:
- Parse metrics with a new tag name:
python tools/parse_ttsi_perf_results.py --tag <YOUR_TAG> - This creates
data/metal/inf/<YOUR_TAG>/with metric files - Run correlation with the same tag:
python tools/run_ttsi_corr.py --tag <YOUR_TAG>
- Parse metrics with a new tag name:
Features:
- Automated correlation analysis between Polaris and TT-Metal
- XLSX and CSV export with formulas and formatting
- Geometric mean calculation for aggregate metrics
- Support for multiple input formats (markdown, directories, URLs)
Documentation: See tools/parsers/ for detailed documentation.
Extract performance metrics from TT-Metal markdown documentation:
python tools/parse_ttsi_perf_results.py \
--input https://raw.githubusercontent.com/tenstorrent/tt-metal/main/models/README.md \
--output-dir data/metal/infFeatures:
- Standards-compliant markdown parsing (CommonMark via markdown-it-py)
- Automatic categorization by model type (LLM, vision, detection, NLP, diffusion)
- YAML output format compatible with correlation tools
- Robust error handling and validation
Documentation:
- Parser README - Architecture and API reference
- Usage Examples - Examples and troubleshooting
For issues and questions:
- Check the project repository: https://github.com/tenstorrent/polaris
- Review existing issues or create new ones
- Consult the development team for advanced support