PySpeedIT.speed_it

Overview

This is the main module of PySpeedIT. It is a combination of Benchmark-IT, Profile-IT, Line-Memory-Profile-IT, Disassemble-IT.

Speed-It-Usage

1. Define one or more separate modules with test functions.

   Python-Example

   # file: usage_example.py
   
   from operator import itemgetter
   from random import shuffle
   
   
   def _outer_helper(y_):
      return y_[1]
   
   
   def example_pep265(data_):
      shuffle(data_)
      result = sorted(data_.items(), key=itemgetter(1))
      del result
   
   
   def example_formal_func_outer(data_):
      shuffle(data_)
      result = sorted(data_.items(), key=_outer_helper)
      del result
   
   
   # for Benchmark-IT subcode_blocks
   def example_multiple_subcode_blocks():
      # ::SPEEDIT:: data
      data = dict(zip(range(1000), range(1000)))
      # **SPEEDIT**
      shuffle(data)
      # ::SPEEDIT:: sorted
      result = sorted(data.items(), key=itemgetter(1))
      # **SPEEDIT**
      del result
   
   
   def memory_example():
      a = [1] * (10 ** 6)
      b = [2] * (2 * 10 ** 7)
      del b
      del a
   

2. Define an other module to run Speed-IT.

   Python-Example

   # file: run_speed_it __usage_example.py
   
   # Import abspath
   from os.path import abspath as path_abspath
   
   # Import speed_it
   from PySpeedIT.speed_it import speed_it
   
   
   # define any needed extra variables to use as arguments
   data = dict(zip(range(1000), range(1000)))
   
   
   # ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ #
   def main():
      # defining the: modules_func_tuple mapping
      modules__func_tuples = (
         # TUPLE format:
         # [module_path_str, (
         #   (name_str, function_name_str, list_of_positional_arguments, dictionary_of_keyword_arguments)
         # )]
   
         [path_abspath('usage_example.py'), (
            ('sorting: pep265', 'example_pep265', [data], {}),
            ('sorting: formal_func_outer', 'example_formal_func_outer', [data], {}),
            ('multiple_subcode_blocks', 'example_multiple_subcode_blocks', [], {}),
            ('memory_example', 'memory_example', [], {}),
         )],
         # any other module: a similar list
      )
   

   Note

   Do not import the module with the functions to speed-it: the module is internally loaded from file

For more examples see any files in the PySpeedIT source SOURCE/Examples

• especially the file: run_speed_it.py

Common Errors

Return statement in speed_it functions

Function which are used for speed_it may not have a return statement because they may run in a loop

Python-Example

WRONG return statement

# helper function is ok to have return statement
def recip_square(i_):
   return 1.0 / (i_ ** 2)


# function to be used by speed_it can not have a return statement
def approx_pi(n_=100000):
   val = 0.
   for k_ in range(1, n_ + 1):
      val += recip_square(k_)
   return (6 * val) ** 0.5

Missing speed_it modules__func_tuples arguments

If a function defines a default argument it still needs an argument passed on in the modules__func_tuples.

Python-Example

# function to be used by speed_it
def approx_pi(n_=100000):
   val = 0.
   for k_ in range(1, n_ + 1):
      val += recip_square(k_)
   return (6 * val) ** 0.5

WRONG: modules__func_tuples missing argument for : n_

modules__func_tuples = (
      [path_abspath('calculate_pi.py'), (
         ('calculate pi', 'approx_pi', [], {}),
      )],
   )

OK: modules__func_tuples with argument for : n_

modules__func_tuples = (
      [path_abspath('calculate_pi.py'), (
         ('calculate pi', 'approx_pi', [], {'n_': 100000}),
      )],
   )

Screenshots of OUTPUT HTML

Benchmark-IT OUTPUT HTML

Profile-IT OUTPUT HTML

Line-Memory-Profile-IT OUTPUT HTML

Disassemble-IT OUTPUT HTML

Functions

PySpeedIT.speed_it.speed_it(html_output_dir_path=None, enable_benchmarkit=True, enable_profileit=True, enable_linememoryprofileit=True, enable_disassembleit=True, modules__func_tuples=None, output_max_slashes_fileinfo=2, use_func_name=True, output_in_sec=False, profileit__repeat=1, benchmarkit__output_source=False, benchmarkit__with_gc=False, benchmarkit__check_too_fast=True, benchmarkit__rank_by='best', benchmarkit__run_sec=1, benchmarkit__repeat=3)

Writes the results per defined module to html files overwriting them if they existed.

Parameters:

• html_output_dir_path – Base directory to output the results
• enable_benchmarkit – enable/disable Benchmark-IT
• enable_profileit – enable/disable Profile-IT
• enable_linememoryprofileit – enable/disable Line-Memory-Profile-IT
• enable_disassembleit – enable/disable Disassemble-IT
• modules__func_tuples –

  (tuple) TUPLE format:

  Python-Example

  [module_path_str, (
     (name1_str, function1_name_str, list_of_positional_arguments, dictionary_of_keyword_arguments),
     (name2_str, function2_name_str, list_of_positional_arguments, dictionary_of_keyword_arguments),
  ]
  

  # defining the: modules_func_tuple mapping
  modules__func_tuples = (
     [path_abspath('calculate_pi.py'), (
        ('calculate pi', 'approx_pi', [], {}),
     )],
     [path_abspath('dict_sorting.py'), (
        ('sorting: pep265', 'example_pep265', [data], {}),
        ('sorting: stupid', 'example_stupid', [data], {}),
        ('sorting: list_expansion', 'example_list_expansion', [data], {}),
        ('sorting: generator', 'example_generator', [data], {}),
        ('sorting: lambda', 'example_lambda', [data], {}),
        ('sorting: formal_func_inner', 'example_formal_func_inner', [data], {}),
        ('sorting: formal_func_outer', 'example_formal_func_outer', [data], {}),
     )],
  )
  

• output_max_slashes_fileinfo –

  (int) to adjust max path levels in the module file info

  (as well the Profile-IT func_txt)

• use_func_name –

  (bool)

  • if True the function name will be used in the output name
  • if False the func_dict key will be used in the the output name
• output_in_sec –

  (bool)

  • if true the output is kept in seconds (float)
  • if false it is transformed to:

    Orders of magnitude (time)

    Name	Symbol	Definition
    second	( s )	One second
    millisecond	( ms )	One thousandth of one second
    microsecond	( µs )	One millionth of one second
    nanosecond	( ns )	One billionth of one second

• profileit__repeat –

  (int) how often the function is repeated: the result will be the sum of all: similar to the code below

  for repeat in range(profileit__repeat):
     profiler.enable()
     profiler.runcall(func, *func_positional_arguments, **func_keyword_arguments)
     profiler.disable()
  

• benchmarkit__output_source – (bool) if True a text file is written with the actual Benchmark-IT code used
• benchmarkit__with_gc –

  (bool)

  • if True gc is kept on during timing
  • if False: turns off garbage collection during the timing
• benchmarkit__check_too_fast –

  (bool)

  • if True and a code block is executed faster than a Reference-Time an Exception is raised.

    • Reference-Time: the smallest difference of calling perf_counter() immediately after each other a couple of times

    SeeAlso

    Reference-Time

• benchmarkit__rank_by –

  (str) best, average or worst

  ..important:: worst uses also the best loop time but ranks the worst one as: base 100%

• benchmarkit__run_sec –

  (float or -1)

  • the number of loops per run is scaled to approximately fit the benchmarkit__run_sec
  • if benchmarkit__run_sec is -1: then the generated function source code is only run once
• benchmarkit__repeat –

  (int) how often everything is repeated

  • This is a convenient variable that calls the whole Benchmark-IT setup repeatedly