Measuring features from predicates (time cost or memory used)

Usage:performance(P,M,Times)

performance accepts a goal, P, as a first argument. The aim of this predicate is to call P several times and meassure some feature (in this version, only time, that is reason because no extra parameter has been added). M defines how many times P should be called. Usually, calling the predicate in some succesion (10,100,1000) and dividing by the number of times it is executed we can obtain the "execution time" of the predicate (if we are measuring time).

The result of executions are returned in the list Times

The diferent modes are:

• graph( Start , End , Increment ). It defines arithmetic succesion starting in Start and ending in End, by increment of Increment. So P is called Start times on the first time, Start+Increment on the second, etc.

• graph The same as graph/3 but with default options

• graph_exp( Start , End , Exp ). It defines geometric succesion. Start is multiplied by Exp till it gets End. So P is called Start times on the first time, Start*Exp on the second, etc.

• graph_exp The same as graph_exp/3 but with default options

• The following properties should hold at call time:
  (basic_props:callable/1)P is a term which represents a goal, i.e., an atom or a structure.
  (basic_props:term/1)M is any term.
  (term_typing:var/1)Times is a free variable.
• The following properties should hold upon exit:
  (basic_props:callable/1)P is a term which represents a goal, i.e., an atom or a structure.
  (basic_props:term/1)M is any term.
  (basic_props:list/2)Times is a list of nums.

Usage:benchmark(P,BenchList,NumTimes,Method,Reserved,OutList)

The predicate P, which accepts ONE argument, is called with the first member of each pair of the BenchList list NumTimes. The entry list have pairs because the second member of the pair express the meaning of the first one in the X-Axis. For example, if we are doing a benchmark of qsort function, the first member will be a list for being ordered and the second one will be the length of the unordered list. The output is a list of (X,Y) points where Y means the time needed for its entry of "cost" X. OutList can be used as TimeList in predicate generate_plot. Reserved is reserved for future implementations (it will take the value of runtime, memory_used...)

• The following properties should hold at call time:
  (basic_props:callable/1)P is a term which represents a goal, i.e., an atom or a structure.
  (basic_props:list/2)BenchList is a list of pairs.
  (basic_props:int/1)NumTimes is an integer.
  (time_analyzer:average_mode/1)time_analyzer:average_mode(Method)
  (basic_props:term/1)Reserved is any term.
  (term_typing:var/1)OutList is a free variable.
• The following properties should hold upon exit:
  (basic_props:callable/1)P is a term which represents a goal, i.e., an atom or a structure.
  (basic_props:list/2)BenchList is a list of pairs.
  (basic_props:int/1)NumTimes is an integer.
  (time_analyzer:average_mode/1)time_analyzer:average_mode(Method)
  (basic_props:term/1)Reserved is any term.
  (basic_props:list/2)OutList is a list of pairs.

Usage:compare_benchmark(ListPred,BenchList,Method,NumTimes,BaseName,Reserved,GeneralOptions)

It is the generalization of execute predicate benchmark/6 with several predicates. benchmark/6 predicate is called with each predicate in ListPred, and BaseName is used for the temporaries basename file. GeneralOptions are aplied to the plot

• The following properties should hold at call time:
  (basic_props:list/2)ListPred is a list of callables.
  (basic_props:list/1)BenchList is a list.
  (time_analyzer:average_mode/1)time_analyzer:average_mode(Method)
  (basic_props:int/1)NumTimes is an integer.
  (term_typing:atom/1)BaseName is currently instantiated to an atom.
  (basic_props:term/1)Reserved is any term.
  (basic_props:list/1)GeneralOptions is a list.

Usage:benchmark2(P,BenchList,Method,NumTimes,What,OutList)

The predicate P, which accepts TWO arguments, is called NumTimes with the first member of each pair of the BenchList list and a free variable as the second. The time of execution (in the future, the desired featured for be measured) is expected to be the second argument, that is because it is a variable. The entry list, BenchList have pairs because the second member of the pair express the cost of the first (in X-Axis). For example, if we are doing a benchmark of qsort function, the first member will be a list for being ordered and the second one will represent the lenght of the unordered list. The output is a list of (X,Y) points where Y express the time needed for they entry of "cost" X. OutList can be used as TimeList in predicate generate_plot. What is reserved for future use

• The following properties should hold at call time:
  (basic_props:callable/1)P is a term which represents a goal, i.e., an atom or a structure.
  (basic_props:list/2)BenchList is a list of pairs.
  (time_analyzer:average_mode/1)time_analyzer:average_mode(Method)
  (basic_props:int/1)NumTimes is an integer.
  (term_typing:atom/1)What is currently instantiated to an atom.
  (term_typing:var/1)OutList is a free variable.
• The following properties should hold upon exit:
  (basic_props:callable/1)P is a term which represents a goal, i.e., an atom or a structure.
  (basic_props:list/2)BenchList is a list of pairs.
  (time_analyzer:average_mode/1)time_analyzer:average_mode(Method)
  (basic_props:int/1)NumTimes is an integer.
  (term_typing:atom/1)What is currently instantiated to an atom.
  (basic_props:list/2)OutList is a list of pairs.

Usage:compare_benchmark2(ListPred,BenchList,Method,NumTimes,BaseName,Reserved,GeneralOptions)

It is the generalization of execute predicate benchmark2/6 with several predicates. benchmark2/6 is called with each predicate in ListPred and BaseName is used for the temporaries basename file. GeneralOptions are applied to the plot ('default' can be used for default General options)

• The following properties should hold at call time:
  (basic_props:list/2)ListPred is a list of callables.
  (basic_props:list/1)BenchList is a list.
  (time_analyzer:average_mode/1)time_analyzer:average_mode(Method)
  (basic_props:int/1)NumTimes is an integer.
  (term_typing:atom/1)BaseName is currently instantiated to an atom.
  (term_typing:atom/1)Reserved is currently instantiated to an atom.
  (basic_props:list/1)GeneralOptions is a list.
• The following properties should hold upon exit:
  (basic_props:list/2)ListPred is a list of callables.
  (basic_props:list/1)BenchList is a list.
  (time_analyzer:average_mode/1)time_analyzer:average_mode(Method)
  (basic_props:int/1)NumTimes is an integer.
  (term_typing:atom/1)BaseName is currently instantiated to an atom.
  (term_typing:atom/1)Reserved is currently instantiated to an atom.
  (basic_props:list/1)GeneralOptions is a list.

Usage:sub_times(A,B,C)

C is the result of doing A - B, where A, B, C are a list of pairs as (Time,_)

• Call and exit should be compatible with:
  (basic_props:list/2)A is a list of pairs.
  (basic_props:list/2)B is a list of pairs.
  (basic_props:list/2)C is a list of pairs.

Usage:div_times(A,B)

A is a list of pairs (P1,P2). B is a list of pairs with the form (P1,P2/P1) for each (P1,P2) that belongs to A

• Call and exit should be compatible with:
  (basic_props:list/2)A is a list of pairs.
  (basic_props:list/2)B is a list of pairs.

Usage:cost(A,T,What)

This pred is thought for measuring constant complexity predicates. T is the expected measured feature. What is reserved for future implementations, just put 'runtime'

• Call and exit should be compatible with:
  (basic_props:callable/1)A is a term which represents a goal, i.e., an atom or a structure.
  (basic_props:int/1)T is an integer.
  (basic_props:term/1)What is any term.