Tools : PyTeal optimization utility

docs/compiler_optimization.rst

@@ -0,0 +1,30 @@
+.. _compiler_optimization:
+
+Compiler Optimization
+========================
+**The optimizer is at an early stage and is disabled by default. Backwards compatability cannot be
+guaranteed at this point.**
+
+The optimizer is a tool for improving performance and reducing resource consumption. In this context,
+the terms *performance* and *resource* can apply across multiple dimensions, including but not limited
+to: compiled code size, scratch slot usage, opcode cost, etc. 
+
+Optimizer Usage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The compiler determines which optimizations to apply based on the provided :any:`OptimizeOptions` object as
+shown in the code block below. The :any:`OptimizeOptions` constructor receives a set of keyword arguments 
+representing flags corresponding to particular optimizations. If arguments are provided to the
+constructor or no :any:`OptimizeOptions` object is passed to :any:`compileTeal` then the default behavior is
+that no optimizations are applied.
+
+============================== ================================================================================ ===========================
+Optimization Flag              Description                                                                      Default
+============================== ================================================================================ ===========================
+:code:`scratch_slots`          A boolean describing whether or not scratch slot optimization should be applied. :code:`False`
+============================== ================================================================================ ===========================
+
+.. code-block:: python
+
+    optimize_options = OptimizeOptions(scratch_slots=True)
+    compileTeal(approval_program(), mode=Mode.Application, version=4, optimizer=optimize_options)

docs/index.rst

@@ -43,6 +43,7 @@ PyTeal **hasn't been security audited**. Use it at your own risk.
    state
    assets
    versions
+   compiler_optimization
 
 .. toctree::
    :maxdepth: 3

pyteal/__init__.py

@@ -8,6 +8,7 @@
     DEFAULT_TEAL_VERSION,
     CompileOptions,
     compileTeal,
+    OptimizeOptions,
 )
 from .types import TealType
 from .errors import TealInternalError, TealTypeError, TealInputError, TealCompileError
@@ -23,6 +24,7 @@
         "DEFAULT_TEAL_VERSION",
         "CompileOptions",
         "compileTeal",
+        "OptimizeOptions",
         "TealType",
         "TealInternalError",
         "TealTypeError",

pyteal/__init__.pyi

@@ -11,6 +11,7 @@ from .compiler import (
     DEFAULT_TEAL_VERSION,
     CompileOptions,
     compileTeal,
+    OptimizeOptions,
 )
 from .types import TealType
 from .errors import TealInternalError, TealTypeError, TealInputError, TealCompileError
@@ -122,6 +123,7 @@ __all__ = [
     "Not",
     "OnComplete",
     "Op",
+    "OptimizeOptions",
     "Or",
     "Pop",
     "Reject",

pyteal/compiler/__init__.py

@@ -6,10 +6,13 @@
     compileTeal,
 )
 
+from .optimizer import OptimizeOptions
+
 __all__ = [
     "MAX_TEAL_VERSION",
     "MIN_TEAL_VERSION",
     "DEFAULT_TEAL_VERSION",
     "CompileOptions",
     "compileTeal",
+    "OptimizeOptions",
 ]

pyteal/compiler/compiler.py

@@ -203,7 +203,7 @@ def compileTeal(
             constants will be assembled in the most space-efficient way, so enabling this may reduce
             the compiled program's size. Enabling this option requires a minimum TEAL version of 3.
             Defaults to false.
-        optimize (optional): OptimizeOptions that determine which optimization will be applied.
+        optimize (optional): OptimizeOptions that determine which optimizations will be applied.
 
     Returns:
         A TEAL assembly program compiled from the input expression.

pyteal/compiler/optimizer/optimizer.py

@@ -7,17 +7,16 @@
 class OptimizeOptions:
     """An object which specifies the optimizations to be performed and relevant context.
 
-    _skip_slots: the slots that should be skipped during optimization. At the
-        moment this includes:
-                1. reserved slots because they may have dependencies outside
-                the current application. For example, the 'gloads' opcode can
-                access the slots of other applications in the tx group.
-                2. global slots because they're outside the scope of global
-                optimizations, which only apply to the control flow graph of
-                a single subroutine.
-                3. slots used with dynamic scratch vars. These slots use
-                indirection by means of the 'stores' opcode and dependencies
-                can only be determined at runtime.
+    _skip_slots: the slots that should be skipped during optimization. At the moment this includes:
+            1. reserved slots because they may have dependencies outside
+            the current application. For example, the 'gloads' opcode can
+            access the slots of other applications in the tx group.
+            2. global slots because they're outside the scope of global
+            optimizations, which only apply to the control flow graph of
+            a single subroutine.
+            3. slots used with dynamic scratch vars. These slots use
+            indirection by means of the 'stores' opcode and dependencies
+            can only be determined at runtime.
 
     Args: