### Glob and Install Python Examples

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/examples/CMakeLists.txt

Finds all Python example files and conditionally installs them. Sets the path for examples based on the installation flag.

```cmake
file(GLOB EXAMPLES "${CMAKE_CURRENT_SOURCE_DIR}/*.py")
if(COPY_TESTS)
  install(FILES ${EXAMPLES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}")
  set(EXAMPLES_PATH "${CMAKE_CURRENT_BINARY_DIR}")
else()
  set(EXAMPLES_PATH "${CMAKE_CURRENT_SOURCE_DIR}")
endif()

foreach(EXAMPLE ${EXAMPLES})
  get_filename_component(NAME ${EXAMPLE} NAME_WE)
  add_poptorch_py_example(${NAME} ${EXAMPLES_PATH})
endforeach()
```

--------------------------------

### Glob and Install Python Examples

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/CMakeLists.txt

Finds all Python files in the current source directory and conditionally installs them to the build directory if `COPY_TESTS` is enabled. It then iterates through the found examples to add them as user guide tests.

```cmake
file(GLOB EXAMPLES "${CMAKE_CURRENT_SOURCE_DIR}/*.py")
if(COPY_TESTS)
  install(FILES ${EXAMPLES} DESTINATION "${CMAKE_CURRENT_BINARY_DIR}")
  set(DOC_EXAMPLES_PATH "${CMAKE_CURRENT_BINARY_DIR}")
else()
  set(DOC_EXAMPLES_PATH "${CMAKE_CURRENT_SOURCE_DIR}")
endif()

foreach(EXAMPLE ${EXAMPLES})
  get_filename_component(NAME ${EXAMPLE} NAME_WE)
  add_poptorch_py_user_guide_example(${NAME} ${DOC_EXAMPLES_PATH})
endforeach()
```

--------------------------------

### Define Function to Add Python User Guide Examples

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/CMakeLists.txt

This function, `add_poptorch_py_user_guide_example`, is used to add Python scripts as user guide examples. It sets up test names, commands, and labels based on whether the example is considered 'long' or 'short'.

```cmake
function(add_poptorch_py_user_guide_example name path)
  message(STATUS "Adding python example '${name}'")
  set(extra_labels "")
  if("${name}" STREQUAL "pipeline_simple")
    set(extra_labels ";external_data")
  else()
    if("${name}" IN_LIST LONG_TESTS)
      set(extra_labels "")
    else()
      set(extra_labels ";short")
    endif()
  endif()

  add_test(NAME "${name}_user_guide_example"
           COMMAND python3 ${path}/${name}.py
           WORKING_DIRECTORY ${PROJECT_BINARY_DIR})
  set_tests_properties("${name}_user_guide_example" PROPERTIES LABELS "user_guide_examples${extra_labels}")
endfunction()
```

--------------------------------

### Python Simple Adder Example

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/installation.rst

A basic Python script to verify the Poplar SDK setup. This example is typically found in the SDK's examples directory.

```python
import poptorch
import torch

class Adder(torch.nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, x, y):
        return x + y

model = Adder()
optimizer = poptorch.optim.Adam(model.parameters(), lr=0.001)

# Create a Popfile for the model
popfile = poptorch.Popfile()
popfile.add_model(model)
popfile.save("simple_adder.pop")

# Load the Popfile
loaded_model = poptorch.PopfileLoader("simple_adder.pop")

# Create dummy data
input1 = torch.randn(10)
input2 = torch.randn(10)

# Compile the model
compiled_model = poptorch.inferenceModel(loaded_model)

# Run inference
output = compiled_model(input1, input2)

print("Output:", output)

```

--------------------------------

### Install README

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/CMakeLists.txt

Installs the README.md file to the root of the installation directory.

```cmake
install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/README.md
        DESTINATION .)
```

--------------------------------

### Configure and Install Enable Script

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/CMakeLists.txt

Configures the enable.sh script using template variables and then installs it to the root of the installation directory.

```cmake
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/scripts/enable.sh.in
  ${PROJECT_BINARY_DIR}/enable.sh
  @ONLY)

install(FILES ${CMAKE_CURRENT_BINARY_DIR}/enable.sh
        DESTINATION .)
```

--------------------------------

### Install LaTeX for Documentation Build

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Installs the full LaTeX distribution, necessary for building documentation.

```sh
sudo apt install -y texlive-full
```

--------------------------------

### Install Library and Headers

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/poptorch_compiler/pytorch_bridge/CMakeLists.txt

Installs the 'poptorch_compiler' target, including its library files and public headers. Headers are installed into a 'pytorch_bridge' subdirectory.

```cmake
install(TARGETS poptorch_compiler
  LIBRARY
    DESTINATION ${CMAKE_INSTALL_LIBDIR}
  PUBLIC_HEADER
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/pytorch_bridge
)
```

--------------------------------

### Install PopTorch Python Files

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/poptorch_geometric/python/CMakeLists.txt

Installs the generated __init__.py file, other Python files, type stubs, and the 'ops' directory to the specified Python installation directory.

```cmake
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/__init__.py DESTINATION "${INSTALL_POPPYG_PYDIR}")
install(FILES ${poppyg_python_files} py.typed DESTINATION "${INSTALL_POPPYG_PYDIR}")
install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/ops DESTINATION "${INSTALL_POPPYG_PYDIR}")
```

--------------------------------

### Install torchvision

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/example.rst

Installs a specific version of torchvision required for the MNIST example. Ensure the Poplar SDK is installed prior to running this command.

```console
$ python3 -m pip install torchvision==0.11.1
```

--------------------------------

### Install PopTorch Wheel

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/poptorch_geometric/user_guide/installation.rst

Install the PopTorch wheel file from the Poplar SDK. Replace <sdk_path> with the actual path to your SDK.

```bash
$ pip install <sdk_path>/poptorch-x.x.x.whl
```

--------------------------------

### Example PopTorch Configuration File

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Example contents of a config file used to set options. Each line corresponds to a Python command to set an option, omitting the 'options.' prefix.

```python
use_ipu_model
num_ipus 1

# Example of a nested option
replication_factor 2

# Example of a boolean option
compile_only true
```

--------------------------------

### Compile and Install PopTorch Libraries

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Compiles and installs the PopTorch and PopTorch Geometric libraries using Ninja.

```sh
ninja install
```

--------------------------------

### Install PopTorch Geometric Wheel

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/poptorch_geometric/user_guide/installation.rst

Install the PopTorch Geometric wheel file after PopTorch is installed. Ensure the virtual environment is activated and replace <sdk_path>.

```bash
# Enable the Python environment containing PopTorch (if not already enabled)
$ source poptorch_test/bin/activate
$ pip install <sdk_path>/poptorch_geometric-x.x.x.whl
```

--------------------------------

### Create Build Environment

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Uses the provided script to create a build environment and install necessary dependencies.

```sh
../poptorch/scripts/create_buildenv.py
```

--------------------------------

### Create and activate virtual environment, install PopTorch

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/installation.rst

Sets up a Python virtual environment and installs PopTorch from a wheel file. This isolates PopTorch from the system Python environment.

```bash
virtualenv -p python3 poptorch_test
source poptorch_test/bin/activate
pip install -U pip
pip install <sdk_path>/poptorch_x.x.x.whl
```

--------------------------------

### MNIST Example Code

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/example.rst

This Python code demonstrates how to run an MNIST model on the IPU. Highlighted lines indicate PopTorch-specific code for multi-IPU execution. Ensure the Poplar SDK and torchvision are installed.

```python
import poptorch
import torch
import torch.nn as nn
import torch.optim as optim
from torchvision import datasets, transforms

# Model definition
class MNISTModel(nn.Module):
    def __init__(self):
        super(MNISTModel, self).__init__()
        self.conv1 = nn.Conv2d(1, 32, kernel_size=3, stride=1, padding=1)
        self.relu1 = nn.ReLU()
        self.pool1 = nn.MaxPool2d(kernel_size=2, stride=2)
        self.conv2 = nn.Conv2d(32, 64, kernel_size=3, stride=1, padding=1)
        self.relu2 = nn.ReLU()
        self.pool2 = nn.MaxPool2d(kernel_size=2, stride=2)
        self.fc1 = nn.Linear(64 * 7 * 7, 128)
        self.relu3 = nn.ReLU()
        self.fc2 = nn.Linear(128, 10)

    def forward(self, x):
        x = self.pool1(self.relu1(self.conv1(x)))
        x = self.pool2(self.relu2(self.conv2(x)))
        x = x.view(-1, 64 * 7 * 7)
        x = self.relu3(self.fc1(x))
        x = self.fc2(x)
        return x

# Data loading and preprocessing
transform = transforms.Compose([
    transforms.ToTensor(),
    transforms.Normalize((0.1307,), (0.3081,))
])
train_dataset = datasets.MNIST('./data', train=True, download=True, transform=transform)
val_dataset = datasets.MNIST('./data', train=False, download=True, transform=transform)

train_loader = torch.utils.data.DataLoader(train_dataset, batch_size=64, shuffle=True)
val_loader = torch.utils.data.DataLoader(val_dataset, batch_size=1000, shuffle=False)

# PopTorch configuration
model = MNISTModel()
optimizer = optim.Adam(model.parameters(), lr=0.001)
loss_fn = nn.CrossEntropyLoss()

# Create PopTorch options
opts = poptorch.Options()
opts.deviceIteration(poptorch.ipu_models.ipu_model_creation.DeviceIteration.II)

# Compile the model with PopTorch
poptorch_model = poptorch.trainingModel(model, opts, optimizer=optimizer, loss_fn=loss_fn)

# Training loop
num_epochs = 1
for epoch in range(num_epochs):
    for batch_idx, (data, target) in enumerate(train_loader):
        # Training step
        poptorch_model.train_step(data, target)
        if batch_idx % 100 == 0:
            print(f'Epoch {epoch}, Batch {batch_idx}, Loss: {poptorch_model.get_current_loss():.4f}')

# Evaluation loop
correct = 0
total = 0
with torch.no_grad():
    for data, target in val_loader:
        outputs = poptorch_model.eval_step(data)
        _, predicted = torch.max(outputs.data, 1)
        total += target.size(0)
        correct += (predicted == target).sum().item()

accuracy = 100 * correct / total
print(f'Accuracy on the validation set: {accuracy:.2f}%')

```

--------------------------------

### Install PopTorch Geometric Wheel

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Installs the PopTorch Geometric wheel after PopTorch is installed. PyTorch Geometric is installed automatically.

```sh
pip3 install ${SDK_PATH}/poptorch_geometric-*.whl
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/poptorch_geometric/user_guide/installation.rst

Recommended steps to create and activate a Python virtual environment for PopTorch Geometric installation.

```bash
$ virtualenv -p python3 poptorch_test
$ source poptorch_test/bin/activate
```

--------------------------------

### Set up Poplar and Popart environment variables

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/tests/custom_ops/CMakeLists.txt

Configures the build to find Poplar and Popart installations. Ensure POPLAR_DIR and POPART_DIR are set correctly.

```cmake
set(CMAKE_BUILD_TYPE Debug)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)

set(POPART_DIR CACHE PATH "Path to a Popart install")
set(POPLAR_DIR CACHE PATH "Path to a Poplar install")

if( NOT ${POPLAR_DIR} STREQUAL "")
  list(APPEND CMAKE_PREFIX_PATH ${POPLAR_DIR})
  if(NOT poplar_FOUND)
    find_package(poplar REQUIRED)
  endif()
else()
  # Check the package is not already in CMake's path
  find_package(poplar)
  if(NOT poplar_FOUND)
    message(FATAL_ERROR "You must provide a path to a Poplar install using -DPOPLAR_DIR=/path/to/popart/build/install")
  endif()
endif()
if( NOT EXISTS ${POPART_DIR} )
  # Check the package is not already in CMake's path
  find_package(popart COMPONENTS popart-only)
  if(NOT popart_FOUND)
    message(FATAL_ERROR "You must provide a path to a Popart build using -DPOPART_DIR=/path/to/popart/build")
  endif()
else()
  list(APPEND CMAKE_PREFIX_PATH ${POPART_DIR})
  if(NOT popart_FOUND)
    find_package(popart REQUIRED COMPONENTS popart-only)
  endif()
endif()

# All C++ code in this project will be compiled as C++14
set (CMAKE_CXX_STANDARD 14)

set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
```

--------------------------------

### Verify PopTorch Installation

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Checks if PopTorch is installed correctly by printing its version.

```python
python3 -c "import poptorch;print(poptorch.__version__)"
```

--------------------------------

### Install Poptorch Configuration File

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/CMakeLists.txt

Installs the `poptorch.conf` file to the specified destination directory within the build output. This is typically used for runtime configuration.

```cmake
install(FILES "poptorch.conf" DESTINATION "${PROJECT_BINARY_DIR}/tmp")
```

--------------------------------

### Parallel Execution Strategies Example

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/batching.rst

This example illustrates different parallel execution strategies such as SerialPhasedExecution, PipelinedExecution, and ShardedExecution. It highlights key lines for understanding the strategy definitions.

```python
    # annotations_strategy_start
    # This is a dummy model for demonstration purposes.
    # It is not intended to be run.
    class Model(torch.nn.Module):
        def __init__(self):
            super().__init__()
            self.layer1 = torch.nn.Linear(10, 20)
            self.layer2 = torch.nn.Linear(20, 30)
            self.layer3 = torch.nn.Linear(30, 10)

        def forward(self, x):
            x = self.layer1(x)
            x = self.layer2(x)
            x = self.layer3(x)
            return x

    # annotations_strategy_end
```

--------------------------------

### Precompile Training and Validation Models

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Example of precompiling both a training and a validation model.

```python
train_model = poptorch.trainingModel(model, opts)
val_model = poptorch.inferenceModel(model, opts)

train_model.compile_model(input_shape)
val_model.compile_model(input_shape)

train_model.export_model("train_model.bin")
val_model.export_model("val_model.bin")

```

--------------------------------

### Update pip and Install PopTorch Wheel

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Ensures pip is up-to-date and then installs the PopTorch wheel. Torch is installed automatically.

```sh
pip3 install -U pip --user
```

```sh
pip3 install ${SDK_PATH}/poptorch-*.whl
```

--------------------------------

### Install PopTorch and PopTorch Geometric

Source: https://context7.com/graphcore/poptorch/llms.txt

Installs PopTorch and optionally PopTorch Geometric using provided wheels from the Poplar SDK. Ensure the Poplar runtime environment is sourced before use.

```sh
# Install prerequisites
sudo apt install -y python3 python3-pip

# Set SDK path
export SDK_PATH=/path/to/poplar_sdk-ubuntu_20_04*

# Install PopTorch (automatically installs compatible PyTorch)
pip3 install ${SDK_PATH}/poptorch-*.whl

# Optionally install PopTorch Geometric
pip3 install ${SDK_PATH}/poptorch_geometric-*.whl

# Source runtime environment before using PopTorch
. ${SDK_PATH}/poplar-ubuntu_20_04*/enable.sh
. ${SDK_PATH}/popart-ubuntu_20_04*/enable.sh

# Verify installation
python3 -c "import poptorch; print(poptorch.__version__)"
python3 -c "import poptorch_geometric; print(poptorch_geometric.__version__)"
```

--------------------------------

### Install Ubuntu Packages for PopTorch

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Installs essential packages for running PopTorch on Ubuntu 20.04.

```sh
sudo apt install -y python3 python3-pip
```

--------------------------------

### Run Documentation Build Script

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/CMakeLists.txt

If `BUILD_DOCS` is enabled, this command executes a Python script to build the project's documentation. It specifies the installation directory and adds the installation prefix to the Python system path.

```cmake
run_poptorch_install_command(
  "python3 ${PROJECT_SOURCE_DIR}/scripts/docs_build.py --install-dir ${CMAKE_INSTALL_PREFIX} --add-to-sys-path ${CMAKE_INSTALL_PREFIX}"
  "${PROJECT_BINARY_DIR}"
  "docs_build.py")
```

--------------------------------

### Optimizer State Management in PyTorch

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/pytorch_to_poptorch.rst

This snippet shows a typical optimizer setup in PyTorch. Note that PopTorch manages optimizer state internally.

```python
optimizer = torch.optim.Adam(model.parameters(), lr=0.001)

# ... training loop ...

loss = poptorch_model(data, target)
loss.backward()
optimizer.step()

```

--------------------------------

### Define PopTorch Install Command

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/CMakeLists.txt

Defines a CMake function to execute installation commands that require PopTorch, PopArt, and Poplar environment variables to be set.

```cmake
function(run_poptorch_install_command cmd working_directory cmd_name)
  install(CODE
    "set(ENV{LD_LIBRARY_PATH} ${popart_LIB_DIR}:${POPLAR_DIR}:$ENV{LD_LIBRARY_PATH})
    set(ENV{POPTORCH_SMALL_IPU_MODEL} 1)
    execute_process( COMMAND ${cmd} WORKING_DIRECTORY ${working_directory} RESULT_VARIABLE RETVAL OUTPUT_VARIABLE OUTPUT ERROR_VARIABLE OUTPUT)
    if(RETVAL AND NOT RETVAL EQUAL 0)
      message(FATAL_ERROR \"${cmd_name} FAILED: \${OUTPUT}\")
    endif()")
endfunction()
```

--------------------------------

### Install Build Dependencies for PopTorch

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Installs additional packages required for building PopTorch and PopTorch Geometric from source on Ubuntu 20.04.

```sh
sudo apt install -y git curl g++
```

--------------------------------

### Enable PopTorch from Build Directory

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Sources the enable script from the PopTorch build folder to use the locally built libraries. This is an alternative to installing wheels.

```sh
. enable.sh
```

```python
python3 -c "import poptorch;print(poptorch.__version__)"
```

--------------------------------

### Efficient Training Accuracy Calculation

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/batching.rst

This example demonstrates how to efficiently calculate training accuracy across all batches using poptorch.OutputMode.Sum. This approach minimizes overhead when monitoring metrics.

```python
    # sum_accuracy_start
    class ModelWithAccuracy(torch.nn.Module):
        def __init__(self):
            super().__init__()
            self.layer1 = torch.nn.Linear(10, 20)
            self.layer2 = torch.nn.Linear(20, 10)

        def forward(self, x):
            x = self.layer1(x)
            x = self.layer2(x)
            return x

    # sum_accuracy_end
```

--------------------------------

### Stage Declaration Example

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Defines stages for phased execution. 'A' and 'B' run in parallel on different IPUs or sequentially on a single IPU depending on stage configuration.

```python
        # stage_start
        stage_a = poptorch.Stage(user_id='A')
        stage_b = poptorch.Stage(user_id='B')
        # stage_end
```

--------------------------------

### Execute set_version.py Script

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/poptorch_geometric/python/CMakeLists.txt

This code block executes the set_version.py script to dynamically set the version in the __init__.py file during the installation process. It checks for execution errors and reports them.

```cmake
execute_process(
        COMMAND python3 ${PROJECT_SOURCE_DIR}/../scripts/set_version.py --input-file ${CMAKE_CURRENT_SOURCE_DIR}/__init__.py ${CMAKE_CURRENT_BINARY_DIR}/__init__.py
        WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
        RESULT_VARIABLE RETVAL OUTPUT_VARIABLE OUTPUT ERROR_VARIABLE OUTPUT)
    if(RETVAL AND NOT RETVAL EQUAL 0)
      message(FATAL_ERROR "set_version.py FAILED: ${OUTPUT}")
    endif()
```

--------------------------------

### Set Poplar SDK Environment Variable

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Sets the SDK_PATH environment variable to point to the installed Poplar SDK. Replace '/path/to/poplar_sdk-ubuntu_20_04*' with your actual SDK path.

```sh
export SDK_PATH=/path/to/poplar_sdk-ubuntu_20_04*
```

--------------------------------

### Wrap Model for Training with PopTorch

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Example of using the trainingModel function to wrap a PyTorch model for IPU training. Ensure the model is in the correct mode (e.g., .train() or .eval()) before wrapping.

```python
import poptorch

# Assume 'model' is a PyTorch nn.Module
# model.train() or model.eval() should be called before wrapping

# Wrap the model for training
training_model = poptorch.trainingModel(model, options)

# ... rest of the training code
```

--------------------------------

### Show Test Help

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Run this command to display help information for the test script.

```sh
./test.sh --help
```

--------------------------------

### Display Help Information

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/tests/gnn/benchgnn_ops/README.md

Print detailed information about all supported options and arguments for the benchgnn tool.

```bash
python3 benchgnn_ops.py --help
```

--------------------------------

### Create Build Directory

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Creates a build directory and navigates into it, preparing for the build process.

```sh
mkdir build
cd build
```

--------------------------------

### Set Installation Directory for Python Packages

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/CMakeLists.txt

Defines the installation directory for Python packages. This is typically a subdirectory within the main installation prefix.

```cmake
set(INSTALL_PYDIR ${CMAKE_INSTALL_PREFIX}/poptorch)
```

--------------------------------

### Run Multiple Benchmark Test Cases with All Options

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/tests/gnn/benchgnn_ops/README.md

Combine directory-based and file-based configurations, along with operator-specific arguments, to run multiple benchmark test cases.

```bash
python3 benchgnn_ops.py --common_config=example_configs/common.yaml --config_dir=example_configs --config_files=[example_configs/scatter_testcase1.yaml,example_configs/scatter_testcase2.yaml] scatter --src_shape [1,12] --input_shape [1,12] --index_shape [1,12] --dim 0
```

--------------------------------

### Define PopTorch Python Example Function

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/examples/CMakeLists.txt

Defines a CMake function to add Python examples as tests. It conditionally sets labels based on the example name.

```cmake
function(add_poptorch_py_example name path)
  message(STATUS "Adding python example '${name}'")

  set(extra_labels "")
  if("${name}" STREQUAL "bert_ipu")
    set(extra_labels ";external_data")
  else()
    set(extra_labels ";short")
  endif()
  add_test(NAME "${name}_example"
           COMMAND python3 ${path}/${name}.py
           WORKING_DIRECTORY ${PROJECT_BINARY_DIR})
  set_tests_properties("${name}_example" PROPERTIES LABELS "examples${extra_labels}")
endfunction()
```

--------------------------------

### Define Installation Directory for Python Packages

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/poptorch_geometric/CMakeLists.txt

Sets a CMake variable to define the installation path for Python package files. This ensures Python modules are placed in the correct subdirectory within the installation prefix.

```cmake
set(INSTALL_POPPYG_PYDIR ${CMAKE_INSTALL_PREFIX}/poptorch_geometric)
```

--------------------------------

### Verify PopTorch Geometric Installation

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Checks if PopTorch Geometric is installed correctly by printing its version.

```python
python3 -c "import poptorch_geometric;print(poptorch_geometric.__version__)"
```

--------------------------------

### Create and Use FixedSizeDataLoader

Source: https://context7.com/graphcore/poptorch/llms.txt

Demonstrates creating a FixedSizeDataLoader and iterating through batches, showing how graph masks are handled.

```python
fixed_opts = FixedSizeOptions.from_dataset(dataset, batch_size=4)
print(fixed_opts)

poptorch_opts = poptorch.Options()
loader = FixedSizeDataLoader(
    dataset,
    batch_size=4,
    fixed_size_options=fixed_opts,
    add_pad_masks=True,
    shuffle=True,
    options=poptorch_opts)

for batch in loader:
    # batch.graphs_mask: [batch_size] bool — True for real graphs
    # batch.nodes_mask:  [num_nodes]  bool — True for real nodes
    # batch.edges_mask:  [num_edges]  bool — True for real edges
    print(batch.x.shape)         # [fixed_num_nodes, 16]
    print(batch.graphs_mask)     # e.g., [True, True, True, False] (last is padding)
    break
```

--------------------------------

### Load PopTorch Options from Config File

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Instantiate poptorch.Options and load settings from a configuration file. Ensure the config file format matches the expected command structure.

```python
options = poptorch.Options()
options.loadFromFile("poptorch.conf")
```

--------------------------------

### Run Multiple Benchmark Test Cases from Directory

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/tests/gnn/benchgnn_ops/README.md

Execute multiple benchmark test cases using YAML configuration files located in a specified directory, along with a common configuration file.

```bash
python3 benchgnn_ops.py --common_config=example_configs/common.yaml --config_dir=example_configs
```

--------------------------------

### Validate PopTorch and PopTorch Geometric Installation

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/poptorch_geometric/user_guide/installation.rst

Verify that PopTorch and PopTorch Geometric are installed correctly by checking their versions using Python commands.

```bash
$ python -c "import poptorch;print(poptorch.__version__)"
$ python -c "import poptorch_geometric;print(poptorch_geometric.__version__)"
```

--------------------------------

### Run Multiple Benchmark Test Cases from Specific Files

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/tests/gnn/benchgnn_ops/README.md

Execute multiple benchmark test cases by providing a list of specific YAML configuration files, in addition to a common configuration file.

```bash
python3 benchgnn_ops.py --common_config=example_configs/common.yaml --config_files=[example_configs/scatter_testcase1.yaml,example_configs/scatter_testcase2.yaml]
```

--------------------------------

### Install PopTorch Target

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/CMakeLists.txt

Defines an 'install_poptorch' target that installs PopTorch and its associated custom operations. This target is only available for CMake versions greater than 3.15.0.

```cmake
if(${CMAKE_VERSION} VERSION_GREATER "3.15.0")
  # Building poptorch without installing it doesn't make sense: the python
  # module cannot be used so always install after a build.
  add_custom_target(install_poptorch ALL
      COMMAND ${CMAKE_COMMAND} --install ${CMAKE_BINARY_DIR}
      DEPENDS poptorch custom_cube_op custom_leaky_relu_op custom_add_scalar_op custom_add_scalar_vec_op custom_add_vec_scalar_mul_op custom_reduce_op custom_three_input_reduce_op custom_many_attribute_op
  )
endif()
```

--------------------------------

### Precompile PopTorch Model for Offline Execution

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Demonstrates how to precompile a PopTorch model for export and execution on a machine without an IPU. Requires exact PopTorch version match on both machines.

```python
poplar_executor = poptorch.PoplarExecutor(model, pop_options)
poplar_executor.compileAndExport(export_path='my_model.cpk', export_model=True)
```

--------------------------------

### Run BenchGNN Benchmark

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/tests/gnn/benchgnn/README.md

Execute the benchgnn tool with specified dataset, model, batch size, and output file. Use --help for a full list of options.

```bash
benchgnn --dataset FakeDataset --model GAT --bs 1 100 --cpu --output outfile
```

```bash
benchgnn --help
```

--------------------------------

### Configure Device Iterations and Batch Size

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/batching.rst

Demonstrates setting the number of device iterations and batch size for training. Adjusting device iterations can improve processing efficiency by reducing host-IPU communication.

```python
options.device_iterations(iterations=10)
options.batch_size(batch_size=32)

```

--------------------------------

### PopTorch Training Model Instantiation

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/pytorch_to_poptorch.rst

Instantiate a PopTorch training model with the wrapped model, options, and optimizer.

```python
import poptorch

# Assuming model, options, and optimizer are defined
poptorch_model = poptorch.trainingModel(model_with_loss, options, optimizer)
```

--------------------------------

### Load Precompiled Model with Runtime Options

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Use `edit_opts_fn` to provide runtime information for selecting a device when loading a precompiled model.

```python
poptorch.load(model_path, "my_model.bin",
              options=poptorch.Options(),
              edit_opts_fn=lambda opts: opts.enable_ipu_inference_only())

```

--------------------------------

### Update Pip

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/poptorch_geometric/user_guide/installation.rst

Ensure pip is updated to at least version 18.1 for proper dependency installation.

```bash
$ pip install -U pip
```

--------------------------------

### Simple IPU Training Loop in PopTorch

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/pytorch_to_poptorch.rst

This snippet demonstrates a basic training loop for IPU execution using PopTorch. Note the use of `poptorch.trainingModel` and `poptorch_model.compile`.

```python
import poptorch
import torch

model = SimpleModel()
data = SimpleDataset()

optimizer = poptorch.optim.Adam(model.parameters(), lr=0.001)

poptorch_model = poptorch.trainingModel(model, optimizer, criterion)
poptorch_model.compile(sample_input=data[0][0])

for epoch in range(num_epochs):
    for data, target in dataloader:
        loss = poptorch_model(data, target)
        loss.backward()
        poptorch_model.step()

```

--------------------------------

### Build Standalone PopTorch Wheel

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/CMakeLists.txt

Creates a standalone wheel distribution for PopTorch. This target is useful for packaging PopTorch with its dependencies for easy installation.

```cmake
add_custom_target(poptorch_standalone_wheel
  WORKING_DIRECTORY ${CMAKE_INSTALL_PREFIX}
  COMMAND python3 ${PROJECT_SOURCE_DIR}/scripts/generate_python_package.py bdist_wheel --include-dir ${CMAKE_INSTALL_PREFIX}/include --lib-dir ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR} --output-dir ${CMAKE_INSTALL_PREFIX}/dist --python-dir ${INSTALL_PYDIR} --standalone "${popart_LIB_DIR}:${POPLAR_DIR}"
  DEPENDS poptorch
)
```

--------------------------------

### Configure I/O Tiles and Execution Strategy

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/hostio_optimisation.rst

Specify the number of I/O tiles and select an execution strategy to enable overlapping compute and I/O. This involves a trade-off between I/O and compute optimization.

```python
opts.TensorLocations.numIOTiles(64)
opts.setExecutionStrategy(poptorch.ShardedExecution())
```

--------------------------------

### poptorch.Options

Source: https://context7.com/graphcore/poptorch/llms.txt

Configures how PopTorch compiles and executes models. Options cover device iterations, replication, gradient accumulation, precision, tensor locations, and distributed execution. Options can also be loaded from a configuration file.

```APIDOC
## poptorch.Options

### Description
Configures how PopTorch compiles and executes models. Options cover device iterations, replication, gradient accumulation, precision, tensor locations, and distributed execution. Options can also be loaded from a configuration file.

### Usage Example
```python
import torch
import poptorch

# Create options with common settings
opts = poptorch.Options()
opts.deviceIterations(100)       # Run 100 batches per IPU step
opts.replicationFactor(4)        # Duplicate model across 4 IPUs
opts.Training.gradientAccumulation(8)  # Accumulate gradients 8x before update
opts.randomSeed(42)
opts.enableExecutableCaching("/tmp/poptorch_cache")  # Cache compiled executables

# Load additional options from a config file
# poptorch.conf contents: deviceIterations(10)\nreplicationFactor(2)
opts2 = poptorch.Options()
opts2.loadFromFile("poptorch.conf")
```
```

--------------------------------

### PopTorch Error Handling Example

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Demonstrates how to catch and handle PopTorch specific errors like RecoverableError and UnrecoverableError. The RecoverableError includes a recovery_action attribute.

```python
try:
    # Code that might raise a PopTorch error
    pass
except poptorch.RecoverableError as e:
    print(f"Recoverable error: {e.message} - Recovery action: {e.recovery_action}")
except poptorch.Error as e:
    print(f"Unrecoverable error: {e.message} (Type: {e.type}, Location: {e.location})")
except Exception as e:
    print(f"An unexpected Python error occurred: {e}")
```

--------------------------------

### Simple CPU Training Loop in PopTorch

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/pytorch_to_poptorch.rst

This snippet shows a basic training loop for CPU execution using PopTorch. Ensure the model and dataloader are correctly initialized.

```python
import poptorch
import torch

model = SimpleModel()
data = SimpleDataset()

optimizer = torch.optim.Adam(model.parameters(), lr=0.001)

poptorch_model = poptorch.trainingModel(model, optimizer, criterion)
poptorch_model.compile(sample_input=data[0][0])

for epoch in range(num_epochs):
    for data, target in dataloader:
        loss = poptorch_model(data, target)
        loss.backward()
        poptorch_model.step()

```

--------------------------------

### Use PopTorch IPU Model Simulator

Source: https://context7.com/graphcore/poptorch/llms.txt

Enables the software simulator for IPU hardware, useful for development and testing without physical IPUs.

```bash
export POPTORCH_IPU_MODEL=1
```

--------------------------------

### Generate PopTorch Package

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/poptorch_geometric/python/CMakeLists.txt

This code block executes the generate_poppyg_package.py script to create the final PopTorch Python package for installation. It checks for execution errors and reports them.

```cmake
execute_process(
        COMMAND python3 ${PROJECT_SOURCE_DIR}/../scripts/generate_poppyg_package.py install --output-dir ${CMAKE_INSTALL_PREFIX} --python-dir ${INSTALL_POPPYG_PYDIR}
        WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
        RESULT_VARIABLE RETVAL OUTPUT_VARIABLE OUTPUT ERROR_VARIABLE OUTPUT)
    if(RETVAL AND NOT RETVAL EQUAL 0)
      message(FATAL_ERROR "generate_poppyg_package.py FAILED: ${OUTPUT}")
    endif()
```

--------------------------------

### Enable PopVision System Analyser Tracing

Source: https://context7.com/graphcore/poptorch/llms.txt

Activates system-level tracing for PopVision, generating .pvti files for performance analysis.

```bash
export PVTI_OPTIONS='{"enable":"true"}'
```

--------------------------------

### Native PyTorch Training Loop (CPU)

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/intro.rst

Illustrates a standard PyTorch training loop on the CPU, including manual gradient backpropagation and optimizer stepping. The loss is incorporated into the forward pass.

```python
import torch
import torch.nn as nn
import torch.optim as optim

class SimpleModel(nn.Module):
    def __init__(self):
        super().__init__()
        self.linear = nn.Linear(10, 2)
        self.relu = nn.ReLU()
        self.loss_fn = nn.CrossEntropyLoss()

    def forward(self, input, target):
        out = self.linear(input)
        out = self.relu(out)
        loss = self.loss_fn(out, target)
        return out, loss

# simple_cpu_start
model = SimpleModel()
optimizer = optim.AdamW(model.parameters(), lr=0.001)

# Dummy data
input_data = torch.randn(32, 10)
target_data = torch.randint(0, 2, (32,))

# Training loop
for _ in range(10):
    prediction, loss = model(input_data, target_data)
    optimizer.zero_grad()
    loss.backward()
    optimizer.step()
# simple_cpu_end
```

--------------------------------

### Enable PopTorch Geometric from Build Directory

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/README.md

Sources the enable script from the PopTorch build folder to use the locally built PopTorch Geometric libraries.

```sh
. enable.sh
```

```python
python3 -c "import poptorch_geometric;print(poptorch_geometric.__version__)"
```

--------------------------------

### Set Minimum CMake Version and Project Name

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/poptorch_geometric/CMakeLists.txt

Specifies the minimum required CMake version and defines the project name. This is a standard starting point for any CMakeLists.txt file.

```cmake
cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
project(poptorch-geometric)
```

--------------------------------

### Configure PopTorch SGD Optimizer with Loss Scaling

Source: https://context7.com/graphcore/poptorch/llms.txt

Initialize the SGD optimizer with parameters for learning rate and loss scaling. Loss scaling is important for float16 stability during training.

```python
import torch
import poptorch

class ModelWithLoss(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = torch.nn.Linear(10, 10)
        self.loss = torch.nn.MSELoss()
    def forward(self, x, target):
        return self.fc(x), self.loss(self.fc(x), target)

model = ModelWithLoss()
input = torch.tensor([1.0] * 10)
target = torch.tensor([0.0] * 10)

# SGD with loss scaling (for float16 stability)
opt = poptorch.optim.SGD(model.parameters(), lr=0.01, loss_scaling=2.0,
                         use_combined_accum=False)
poptorch_model = poptorch.trainingModel(model, optimizer=opt)
poptorch_model(input, target)
```

--------------------------------

### Wrap Model for Inference with PopTorch

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

Example of using the inferenceModel function to wrap a PyTorch model for IPU inference. Ensure the model is in the correct mode (e.g., .train() or .eval()) before wrapping.

```python
import poptorch

# Assume 'model' is a PyTorch nn.Module
# model.train() or model.eval() should be called before wrapping

# Wrap the model for inference
inference_model = poptorch.inferenceModel(model, options)

# ... rest of the inference code
```

--------------------------------

### Handle PopTorch Errors with Custom Logic

Source: https://context7.com/graphcore/poptorch/llms.txt

Implement try-except blocks to catch specific PopTorch exceptions like `RecoverableError`, `UnrecoverableError`, and `poptorch.Error`. `RecoverableError` provides a `recovery_action` string for guided remediation.

```python
import torch
import poptorch

class SimpleModel(torch.nn.Module):
    def forward(self, x, y):
        return x + y

def run_with_error_handling():
    try:
        m = SimpleModel()
        inference_model = poptorch.inferenceModel(m)
        t1 = torch.tensor([1.])
        t2 = torch.tensor([2.])
        result = inference_model(t1, t2)
        assert result == 3.0
        print("Success:", result)

    except poptorch.RecoverableError as e:
        print(f"Recoverable error, action={e.recovery_action}: {e}")
        if e.recovery_action == "FULL_RESET":
            print("Rebooting server...")
        elif e.recovery_action == "IPU_RESET":
            print("Resetting IPU...")
        elif e.recovery_action == "PARTITION_RESET":
            print("Resetting partition...")

    except poptorch.UnrecoverableError as e:
        print(f"Unrecoverable: {e}. Taking machine offline.")

    except poptorch.Error as e:
        # Application or API error from the C++ backend
        print(f"PopTorch error: message={e.message}, type={e.type}, "
              f"location={e.location}")

    except Exception as e:
        print(f"Unexpected error: {e}")

run_with_error_handling()
```

--------------------------------

### poptorch Options - Scaling Knobs

Source: https://context7.com/graphcore/poptorch/llms.txt

Configure key scaling options like `deviceIterations`, `replicationFactor`, and `gradientAccumulation` to multiply the effective global batch size per host step.

```APIDOC
## poptorch Options — deviceIterations / replicationFactor / gradientAccumulation / Distributed

Three key scaling knobs that multiply the effective global batch size per host step. `deviceIterations` runs N consecutive batches on the IPU without returning to the host. `replicationFactor` duplicates the model across M IPUs. `gradientAccumulation` accumulates gradients K times before a weight update.

```python
import torch
import poptorch

class ModelWithLoss(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = torch.nn.Linear(6, 2)
        self.loss = torch.nn.CrossEntropyLoss()
    def forward(self, x, target=None):
        out = self.fc(x.view(x.shape[0], -1))
        if target is not None:
            return out, self.loss(out, target)
        return out

opts = poptorch.Options()
opts.deviceIterations(100)           # 100 IPU steps per host call
opts.replicationFactor(4)            # 4 replicas (global batch *= 4)
opts.Training.gradientAccumulation(8) # accumulate 8 microbatches (global batch *= 8)
opts.randomSeed(42)

# Distributed multi-process execution (e.g., 2 processes, 2 IPUs each = 4 IPUs total)
def process(process_id=0, num_processes=1):
    opts_dist = poptorch.Options()
    opts_dist.deviceIterations(400)
    opts_dist.replicationFactor(2)
    opts_dist.Distributed.configureProcessId(process_id, num_processes)
    opts_dist.Training.gradientAccumulation(8)
    opts_dist.randomSeed(42)

    dataset = torch.utils.data.TensorDataset(
        torch.randn(10000, 6), torch.randint(0, 2, (10000,)))
    loader = poptorch.DataLoader(opts_dist, dataset, batch_size=2,
                                 shuffle=True, drop_last=True)
    model = poptorch.trainingModel(ModelWithLoss(), options=opts_dist)
    for data, labels in loader:
        out, loss = model(data, labels)
    model.destroy()
```
```

--------------------------------

### Correct Persistent Tensor Usage with Buffers

Source: https://github.com/graphcore/poptorch/blob/sdk-release-3.4/docs/user_guide/overview.rst

This example demonstrates the correct method for maintaining a tensor's value between runs on the IPU by registering it as a buffer in PyTorch. This ensures the tensor can be modified and retain its state.

```python
class CounterModelCorrect(torch.nn.Module):
    def __init__(self):
        super().__init__()
        # Register 'i' as a buffer
        self.register_buffer('i', torch.tensor(0))

    def forward(self, x):
        # This will increment on each iteration when run on IPU
        self.i += 1
        return x + self.i

```

--------------------------------

### poptorch.optim (Optimizers)

Source: https://context7.com/graphcore/poptorch/llms.txt

PopTorch provides IPU-optimized versions of standard optimizers with added support for float16 training.

```APIDOC
## poptorch.optim (Optimizers)

PopTorch provides IPU-optimized versions of standard optimizers in the `poptorch.optim` namespace: `SGD`, `Adam`, `AdamW`, `RMSprop`, and `LAMB`. These add support for `loss_scaling`, `velocity_scaling`, and typed accumulators for `float16` training. Attributes explicitly passed to the constructor are treated as variable (updateable); all others default to constant (compiled in).

```python
import torch
import poptorch

class ModelWithLoss(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = torch.nn.Linear(10, 10)
        self.loss = torch.nn.MSELoss()
    def forward(self, x, target):
        return self.fc(x), self.loss(self.fc(x), target)

model = ModelWithLoss()
input = torch.tensor([1.0] * 10)
target = torch.tensor([0.0] * 10)

# SGD with loss scaling (for float16 stability)
opt = poptorch.optim.SGD(model.parameters(), lr=0.01, loss_scaling=2.0,
                         use_combined_accum=False)
poptorch_model = poptorch.trainingModel(model, optimizer=opt)
poptorch_model(input, target)

# Update optimizer hyperparameters at runtime
opt.loss_scaling = 1.0
poptorch_model.setOptimizer(opt)

# Adam with state dict save/restore (for checkpointing)
opt_adam = poptorch.optim.Adam(model.parameters())
train_model = poptorch.trainingModel(model, optimizer=opt_adam)
train_model(input, target)
torch.save({'optimizer_state_dict': opt_adam.state_dict()}, 'checkpoint.pt')
train_model.destroy()

new_opt = poptorch.optim.Adam(model.parameters())
checkpoint = torch.load('checkpoint.pt')
new_opt.load_state_dict(checkpoint['optimizer_state_dict'])
```
```