1# Copyright (c) Meta Platforms, Inc. and affiliates. 2# All rights reserved. 3# 4# This source code is licensed under the BSD-style license found in the 5# LICENSE file in the root directory of this source tree. 6 7# pyre-strict 8from __future__ import annotations 9 10from typing import Any, Dict, Enum, List, Optional, Sequence, Tuple 11 12from executorch.exir._warnings import experimental 13 14@experimental("This API is experimental and subject to change without notice.") 15class Verification(Enum): 16 """Verification maps C++ Program::Verification to Python. 17 18 .. warning:: 19 20 This API is experimental and subject to change without notice. 21 """ 22 23 Minimal: ... 24 InternalConsistency: ... 25 26@experimental("This API is experimental and subject to change without notice.") 27class ExecuTorchModule: 28 """ExecuTorchModule is a Python wrapper around a C++ ExecuTorch program. 29 30 .. warning:: 31 32 This API is experimental and subject to change without notice. 33 """ 34 35 # pyre-ignore[2, 3]: "Any" in parameter and return type annotations. 36 def __call__(self, inputs: Any, clone_outputs: bool = True) -> List[Any]: ... 37 # pyre-ignore[2, 3]: "Any" in parameter and return type annotations. 38 def run_method( 39 self, 40 method_name: str, 41 inputs: Sequence[Any], # pyre-ignore[2]: "Any" in parameter type annotations. 42 clone_outputs: bool = True, 43 ) -> List[Any]: ... 44 # pyre-ignore[2, 3]: "Any" in parameter and return type annotations. 45 def forward( 46 self, 47 inputs: Sequence[Any], # pyre-ignore[2]: "Any" in parameter type annotations. 48 clone_outputs: bool = True, 49 ) -> List[Any]: ... 50 # pyre-ignore[3]: "Any" in return type annotations. 51 def plan_execute(self) -> List[Any]: ... 52 # Bundled program methods. 53 def load_bundled_input( 54 self, bundle: BundledModule, method_name: str, testset_idx: int 55 ) -> None: ... 56 # pyre-ignore[3]: "Any" in return type annotations. 57 def verify_result_with_bundled_expected_output( 58 self, 59 bundle: BundledModule, 60 method_name: str, 61 testset_idx: int, 62 rtol: float = 1e-5, 63 atol: float = 1e-8, 64 ) -> List[Any]: ... 65 def has_etdump(self) -> bool: ... 66 def write_etdump_result_to_file( 67 self, path: str, debug_buffer_path: Optional[str] = None 68 ) -> None: ... 69 def method_meta(self, method_name: str) -> MethodMeta: ... 70 def method_names(self) -> List[str]: ... 71 72@experimental("This API is experimental and subject to change without notice.") 73class BundledModule: 74 """ 75 .. warning:: 76 77 This API is experimental and subject to change without notice. 78 """ 79 80 ... 81 82@experimental("This API is experimental and subject to change without notice.") 83class TensorInfo: 84 """Metadata about a tensor such as the shape and dtype. 85 86 .. warning:: 87 88 This API is experimental and subject to change without notice. 89 """ 90 91 def sizes(self) -> Tuple[int, ...]: 92 """Shape of the tensor as a tuple""" 93 ... 94 95 def dtype(self) -> int: 96 """The data type of the elements inside the tensor. 97 See documentation for ScalarType in executorch/runtime/core/portable_type/scalar_type.h 98 for the values these integers can take.""" 99 ... 100 101 def is_memory_planned(self) -> bool: 102 """True if the tensor is already memory planned, meaning no allocation 103 needs to be provided. False otherwise""" 104 ... 105 106 def nbytes(self) -> int: 107 """Number of bytes in the tensor. Not the same as numel if the dtype is 108 larger than 1 byte wide""" 109 ... 110 111 def __repr__(self) -> str: ... 112 113@experimental("This API is experimental and subject to change without notice.") 114class MethodMeta: 115 """Metadata about a method such as the number of inputs and outputs. 116 117 .. warning:: 118 119 This API is experimental and subject to change without notice. 120 """ 121 122 def name(self) -> str: 123 """The name of the method, such as 'forward'""" 124 ... 125 126 def num_inputs(self) -> int: 127 """The number of user inputs to the method. This does not include any 128 internal buffers or weights, which don't need to be provided by the user""" 129 ... 130 131 def num_outputs(self) -> int: 132 """The number of outputs from the method. This does not include any mutated 133 internal buffers""" 134 ... 135 136 def input_tensor_meta(self, index: int) -> TensorInfo: 137 """The tensor info for the 'index'th input. Index must be in the interval 138 [0, num_inputs()). Raises an IndexError if the index is out of bounds""" 139 ... 140 141 def output_tensor_meta(self, index: int) -> TensorInfo: 142 """The tensor info for the 'index'th output. Index must be in the interval 143 [0, num_outputs()). Raises an IndexError if the index is out of bounds""" 144 ... 145 146 def __repr__(self) -> str: ... 147 148@experimental("This API is experimental and subject to change without notice.") 149def _load_for_executorch( 150 path: str, 151 enable_etdump: bool = False, 152 debug_buffer_size: int = 0, 153 program_verification: Verification = Verification.InternalConsistency, 154) -> ExecuTorchModule: 155 """Load an ExecuTorch Program from a file. 156 157 .. warning:: 158 159 This API is experimental and subject to change without notice. 160 161 Args: 162 path: File path to the ExecuTorch program as a string. 163 enable_etdump: If true, enables an ETDump which can store profiling information. 164 See documentation at https://pytorch.org/executorch/stable/etdump.html 165 for how to use it. 166 debug_buffer_size: If non-zero, enables a debug buffer which can store 167 intermediate results of each instruction in the ExecuTorch program. 168 This is the fixed size of the buffer, if you have more intermediate 169 result bytes than this allows, the execution will abort with a failed 170 runtime check. 171 """ 172 ... 173 174@experimental("This API is experimental and subject to change without notice.") 175def _load_for_executorch_from_buffer( 176 buffer: bytes, 177 enable_etdump: bool = False, 178 debug_buffer_size: int = 0, 179 program_verification: Verification = Verification.InternalConsistency, 180) -> ExecuTorchModule: 181 """Same as _load_for_executorch, but takes a byte buffer instead of a file path. 182 183 .. warning:: 184 185 This API is experimental and subject to change without notice. 186 """ 187 ... 188 189@experimental("This API is experimental and subject to change without notice.") 190def _load_for_executorch_from_bundled_program( 191 module: BundledModule, enable_etdump: bool = False, debug_buffer_size: int = 0 192) -> ExecuTorchModule: 193 """Same as _load_for_executorch, but takes a bundled program instead of a file path. 194 195 See https://pytorch.org/executorch/stable/bundled-io.html for documentation. 196 197 .. warning:: 198 199 This API is experimental and subject to change without notice. 200 """ 201 ... 202 203@experimental("This API is experimental and subject to change without notice.") 204def _load_bundled_program_from_buffer( 205 buffer: bytes, non_const_pool_size: int = ... 206) -> BundledModule: 207 """ 208 .. warning:: 209 210 This API is experimental and subject to change without notice. 211 """ 212 ... 213 214@experimental("This API is experimental and subject to change without notice.") 215def _get_operator_names() -> List[str]: 216 """ 217 .. warning:: 218 219 This API is experimental and subject to change without notice. 220 """ 221 ... 222 223@experimental("This API is experimental and subject to change without notice.") 224def _create_profile_block(name: str) -> None: 225 """ 226 .. warning:: 227 228 This API is experimental and subject to change without notice. 229 """ 230 ... 231 232@experimental("This API is experimental and subject to change without notice.") 233def _dump_profile_results() -> bytes: 234 """ 235 .. warning:: 236 237 This API is experimental and subject to change without notice. 238 """ 239 ... 240 241@experimental("This API is experimental and subject to change without notice.") 242def _reset_profile_results() -> None: 243 """ 244 .. warning:: 245 246 This API is experimental and subject to change without notice. 247 """ 248 ... 249