Installing

Prerequisites

TT-NN Visualizer requires data generated from TT-NN to analyze.

Follow instructions for setting up TT-Metalium and TT-NN.

Memory reports

Recommended PyTest config when generating your data:

export TTNN_CONFIG_OVERRIDES='{
    "enable_fast_runtime_mode": false,
    "enable_logging": true,
    "report_name": "YOUR REPORT NAME",
    "enable_detailed_buffer_report": true,
    "enable_detailed_tensor_report": false,
    "enable_graph_report": false,
    "enable_comparison_mode": false
}'

Configuration Option	Description
enable_fast_runtime_mode	Disable fast runtime mode to ensure all operations are properly traced. Must be disabled to enable logging.
enable_logging	Synchronizes main thread after every operation and logs the operation. Must be enabled.
report_name	Prefix of the folder name where the memory report is output. Must have a value for data8 to be output to disk.
enable_detailed_buffer_report	Enable to visualize the detailed buffer report after every operation. Needed for full buffer information.
enable_detailed_tensor_report	Enable to visualize the values of input and output tensors of every operation. Data not used by the visualizer.
enable_graph_report	Generates an SVG visualization of the computation graph. Data not used by the visualizer.
enable_comparison_mode	Enable to test the output of operations against their golden implementation. Optional, not always available on models.

To run a test with custom input data, you can use the following command with suitable values for input-path:

pytest --disable-warnings --input-path="path/to/input.json" path/to/test_file.py::test_function[param]

The final output should be a folder within ${TT_METAL_HOME}/generated/ttnn/reports/ which should include at least a db.sqlite file (config.json is optional for the visualizer).

For more information on generating data please refer to TT-Metalium and TT-NN documentation.

Performance reports

TT-NN Visualizer supports the reading of TT-Metalium performance reports. The expected output should be a folder within ${TT_METAL_HOME}/generated/profiler/reports/ containing a profile_log_device.csv file, another csv with the performance results, e.g. ops_perf_results_2024_12_11_11_09_16.csv, and a tracy_profile_log_host.tracy file.

Consult the TT-Metalium documentation on how to generate a performance report.

NPE

Network-on-chip performance estimator data can be loaded separately on the /npe route.

Refer to the tt-npe documentation for more details.

Installing from PyPI

TT-NN Visualizer can be installed from PyPI:

pip install ttnn-visualizer

After installation run ttnn-visualizer to start the application. It is recommended to do this within a virtual environment.

The minimum supported version of Python is 3.10. Pyenv can be used to ensure the application runs with a supported version of Python:

mkdir ttnn-visualizer
cd ttnn-visualizer
pyenv local 3.10 # Optional step if using pyenv to manage versions
python -m venv .env
source .env/bin/activate
pip install ttnn-visualizer
ttnn-visualizer

See pyenv for installation instructions.

pipx

If you have pipx installed on your system, it can be used to simplify the above steps.

pipx install --include-deps ttnn-visualizer
ttnn-visualizer

See pipx installation for further help with setting up pipx.

When installing ttnn-visualizer in a virtual environment, ensure that it is not also installed with the system Python. Having the package installed at the system level and in a virtual environment at the same time can lead to version mismatches.

If you run into any issue with an unexpected TT-NN Visualizer version appearing in the browser ensure you have uninstalled the system package by running pip uninstall ttnn-visualizer outside of the virtual env.