|
| 1 | +# Running an ExecuTorch Model in C++ Tutorial |
| 2 | + |
| 3 | +**Author:** [Jacob Szwejbka](https://github.com/JacobSzwejbka) |
| 4 | + |
| 5 | +In this tutorial, we will cover the APIs to load an ExecuTorch model, |
| 6 | +prepare the MemoryManager, set inputs, execute the model, and retrieve outputs. |
| 7 | + |
| 8 | +For a high level overview of the ExecuTorch Runtime please see [Runtime Overview](runtime-overview.md), and for more in-depth documentation on |
| 9 | +each API please see the [Runtime API Reference](executorch-runtime-api-reference.rst). |
| 10 | +[Here](https://github.com/pytorch/executorch/blob/main/examples/portable/executor_runner/executor_runner.cpp) is a fully functional version C++ model runner, and the [Setting up ExecuTorch](getting-started-setup.md) doc shows how to build and run it. |
| 11 | + |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +You will need an ExecuTorch model to follow along. We will be using |
| 16 | +the model `SimpleConv` generated from the [Exporting to ExecuTorch tutorial](./tutorials/export-to-executorch-tutorial). |
| 17 | + |
| 18 | +## Model Loading |
| 19 | + |
| 20 | +The first step towards running your model is to load it. ExecuTorch uses an abstraction called a `DataLoader` to handle the specifics of retrieving the `.pte` file data, and then `Program` represents the loaded state. |
| 21 | + |
| 22 | +Users can define their own `DataLoader`s to fit the needs of their particular system. In this tutorial we will be using the `FileDataLoader`, but you can look under [Example Data Loader Implementations](https://github.com/pytorch/executorch/tree/main/extension/data_loader) to see other options provided by the ExecuTorch project. |
| 23 | + |
| 24 | +For the `FileDataLoader` all we need to do is provide a file path to the constructor. |
| 25 | + |
| 26 | +``` cpp |
| 27 | +using namespace torch::executor; |
| 28 | + |
| 29 | +Result<util::FileDataLoader> loader = |
| 30 | + util::FileDataLoader::from("/tmp/model.pte"); |
| 31 | +assert(loader.ok()); |
| 32 | + |
| 33 | +Result<Program> program = |
| 34 | + torch::executor::Program::load(loader.get()); |
| 35 | +assert(program.ok()); |
| 36 | +``` |
| 37 | +
|
| 38 | +## Setting Up the MemoryManager |
| 39 | +
|
| 40 | +Next we will set up the `MemoryManager`. |
| 41 | +
|
| 42 | +One of the principles of ExecuTorch is giving users control over where the memory used by the runtime comes from. Today (late 2023) users need to provide 2 different allocators: |
| 43 | +
|
| 44 | +* Method Allocator: A `MemoryAllocator` used to allocate runtime structures at `Method` load time. Things like Tensor metadata, the internal chain of instructions, and other runtime state come from this. |
| 45 | +
|
| 46 | +* Planned Memory: A `HierarchicalAllocator` containing 1 or more memory arenas where internal mutable tensor data buffers are placed. At `Method` load time internal tensors have their data pointers assigned to various offsets within. The positions of those offsets and the sizes of the arenas are determined by memory planning ahead of time. |
| 47 | +
|
| 48 | +For this example we will retrieve the size of the planned memory arenas dynamically from the `Program`, but for heapless environments users could retrieve this information from the `Program` ahead of time and allocate the arena statically. We will also be using a malloc based allocator for the method allocator. |
| 49 | +
|
| 50 | +``` cpp |
| 51 | +
|
| 52 | +// Method names map back to Python nn.Module method names. Most users will only have the singular method "forward". |
| 53 | +const char* method_name = "forward"; |
| 54 | +
|
| 55 | +// MethodMeta is a lightweight structure that lets us gather metadata |
| 56 | +// information about a specific method. In this case we are looking to |
| 57 | +// get the required size of the memory planned buffers for the method |
| 58 | +// "forward". |
| 59 | +Result<MethodMeta> method_meta = program->method_meta(method_name); |
| 60 | +assert(method_meta.ok()); |
| 61 | +
|
| 62 | +std::vector<std::unique_ptr<uint8_t[]>> planned_buffers; // Owns the Memory |
| 63 | +std::vector<Span<uint8_t>> planned_arenas; // Passed to the allocator |
| 64 | +
|
| 65 | +size_t num_memory_planned_buffers = method_meta->num_memory_planned_buffers(); |
| 66 | +
|
| 67 | +// It is possible to have multiple layers in our memory hierarchy; for example, SRAM and DRAM. |
| 68 | +for (size_t id = 0; id < num_memory_planned_buffers; ++id) { |
| 69 | + // .get() will always succeed because id < num_memory_planned_buffers. |
| 70 | + size_t buffer_size = |
| 71 | + static_cast<size_t>(method_meta->memory_planned_buffer_size(id).get()); |
| 72 | + planned_buffers.push_back(std::make_unique<uint8_t[]>(buffer_size)); |
| 73 | + planned_arenas.push_back({planned_buffers.back().get(), buffer_size}); |
| 74 | +} |
| 75 | +HierarchicalAllocator planned_memory( |
| 76 | + {planned_arenas.data(), planned_arenas.size()}); |
| 77 | +
|
| 78 | +// Version of MemoryAllocator that uses malloc to handle allocations |
| 79 | +// rather then a fixed buffer. |
| 80 | +util::MallocMemoryAllocator method_allocator; |
| 81 | +
|
| 82 | +// Assemble all of the allocators into the MemoryManager that the Executor |
| 83 | +// will use. |
| 84 | +MemoryManager memory_manager(&method_allocator, &planned_memory); |
| 85 | +``` |
| 86 | + |
| 87 | +## Loading a Method |
| 88 | + |
| 89 | +In ExecuTorch we load and initialize from the `Program` at a method granularity. Many programs will only have one method 'forward'. `load_method` is where initialization is done, from setting up tensor metadata, to intializing delegates, etc. |
| 90 | + |
| 91 | +``` cpp |
| 92 | +Result<Method> method = program->load_method(method_name); |
| 93 | +assert(method.ok()); |
| 94 | +``` |
| 95 | +
|
| 96 | +## Setting Inputs |
| 97 | +
|
| 98 | +Now that we have our method we need to set up its inputs before we can |
| 99 | +perform an inference. In this case we know our model takes a single (1, 3, 256, 256) |
| 100 | +sized float tensor. |
| 101 | +
|
| 102 | +Depending on how your model was memory planned, the planned memory may or may |
| 103 | +not contain buffer space for your inputs and outputs. |
| 104 | +
|
| 105 | +If the outputs were not memory planned then users will need to set up the output data pointer with 'set_output_data_ptr'. In this case we will just assume our model was exported with inputs and outputs handled by the memory plan. |
| 106 | +
|
| 107 | +``` cpp |
| 108 | +// Create our input tensor. |
| 109 | +float data[1 * 3 * 256 * 256]; |
| 110 | +Tensor::SizesType sizes[] = {1, 3, 256, 256}; |
| 111 | +Tensor::DimOrderType dim_order = {0, 1, 2, 3}; |
| 112 | +TensorImpl impl( |
| 113 | + ScalarType::Float, // dtype |
| 114 | + 4, // number of dimensions |
| 115 | + sizes, |
| 116 | + data, |
| 117 | + dim_order); |
| 118 | +Tensor t(&impl); |
| 119 | +
|
| 120 | +// Implicitly casts t to EValue |
| 121 | +Error set_input_error = method->set_input(t, 0); |
| 122 | +assert(set_input_error == Error::Ok); |
| 123 | +``` |
| 124 | + |
| 125 | +## Perform an Inference |
| 126 | + |
| 127 | +Now that our method is loaded and our inputs are set we can perform an inference. We do this by calling `execute`. |
| 128 | + |
| 129 | +``` cpp |
| 130 | +Error execute_error = method->execute(); |
| 131 | +assert(execute_error == Error::Ok); |
| 132 | +``` |
| 133 | +
|
| 134 | +## Retrieve Outputs |
| 135 | +
|
| 136 | +Once our inference completes we can retrieve our output. We know that our model only returns a single output tensor. One potential pitfall here is that the output we get back is owned by the `Method`. Users should take care to clone their output before performing any mutations on it, or if they need it to have a lifespan seperate from the `Method`. |
| 137 | +
|
| 138 | +``` cpp |
| 139 | +EValue output = method->get_output(0); |
| 140 | +assert(output.isTensor()); |
| 141 | +``` |
| 142 | + |
| 143 | +## Conclusion |
| 144 | + |
| 145 | +In this tutorial, we went over the APIs and steps required to load and perform an inference with an ExecuTorch model in C++. |
0 commit comments