Quelle  Time_Manual.thy

(* Author: Tobias Nipkow *)

theory Time_Manual
imports "HOL-Library.Time_Commands"
begin

section ‹Introduction›

text ‹This manual describes the framework for the automatic definition of step-counting
 running-time' functions from HOL functions. The principles of the translation are described
  Section 1.5, Running Time, of the book
 Functional Data Structures and Algorithms. A Proof Assistant Approach.
 🪙‹https://fdsa-book.net›
  load the framework import 🍋‹HOL-Library.Time_Commands›
  framework was implemented by Jonas Stahl.

  a first simple example consider ‹len›, which we define here returning an ‹int›
 to distinguish it from the time functions returning ‹nat›):›

fun len :: "'a list ==> int" where
"len [] = 0" |
"len (x#xs) = 1 + len xs"

time_fun len

text‹
  ‹time_fun› defines a new function ‹T_len› of type ‹'a list ==> nat›, the time function
  ‹len› that counts the number of computation steps. The definition is printed by ‹time_fun›:
 ‹fun T_len :: "'a list ==> nat" where
 T_len [] = 1 |
 T_len (x # xs) = T_len xs + 1›
  details of this translation are described in the book referenced above.
  manual is about the use of the time framework.

  ‹time_fun f› retrieves the definition of ‹f› and defines a corresponding step-counting
 -time function ‹T_f›. For all auxiliary functions used by ‹f›
 excluding constructors and predefined functions (see below)),
  time functions must already have been defined. Example:›

fun aux :: "'a ==> 'a" where
"aux x = x"

time_fun aux

fun main :: "bool ==> bool" where
"main x = aux x"

time_fun main

text ‹For functions defined by ‹definition›, there is a corresponding ‹time_definition› command.
 :›

definition gdef :: "'a ==> 'a" where "gdef x = x"

time_definition gdef

thm T_gdef.simps

text ‹Note that ‹T_gdef› is defined via ‹fun›, which means that the defining equation is not named
 ‹T_gdef_def› but ‹T_gdef.simps› and is a simp-rule.

  time functions for many standard functions (in particular on lists) are already
  in theory ‹HOL-Library.Time_Functions› and basic upper bounds are proved.›


section ‹Termination›

text ‹If the definition of a recursive function requires a manual termination proof,
  ‹time_function› accompanied by a ‹termination› command.›

function sum_to :: "int ==> int ==> int" where
  "sum_to i j = (if j ≤ i then 0 else i + sum_to (i+1) j)"
by pat_completeness auto
termination
  by (relation "measure (λ(i,j). nat(j - i))") auto

time_function sum_to
termination
  by (relation "measure (λ(i,j). nat(j - i))") auto


section ‹Partial Functions›

text ‹Partial functions can also be `timed'.›

(* Partial functions defined with \<open>function\<close> can currently not be timed:
function pos1 :: "int \<Rightarrow> bool" where
"pos1 i = (if i = 1 then True else pos1 (i-1))"
by auto

time_function pos1

function T_pos1 :: "int \<Rightarrow> nat" where
"T_pos1 i = (if i = 1 then 1 else T_pos1 (i-1) + 1)"
by auto
*)

partial_function (tailrec) positive :: "int ==> bool" where
"positive i = (if i = 1 then True else positive (i-1))"

time_partial_function positive

text ‹The difference is that ‹T_positive› has return type ‹nat option› because ‹positive›
  not terminate.

  a function defined with ‹partial_function (option)› is trickier and we do not go into it here.›


section ‹Higher-Order Functions›

text ‹A large subclass of higher-order functions are supported, covering ‹map›, ‹filter› and other
  functions. For example,›

time_fun map

text ‹defines a time function ‹T_map :: ('a ==> nat) ==> 'a list ==> nat›.
  first argument (called ‹T_f› below) is the time function for the first argument ‹f› of ‹map›.
  ignore the definition of ‹T_map› because the output of ‹time_fun map›
  that you should add these lemmas›

lemma T_map_simps [simp,code]:
  "T_map T_f [] = 1"
  "T_map T_f (x # xs) = T_f x + T_map T_f xs + 1"
by (simp_all add: T_map_def)

text‹which are what you would expect as defining equations.
  can click on the suggestion to have it copied into your theory.
 , you can work with ‹T_map› as if it were defined via those equations.

  general, things are a bit more complicated, which is why ‹T_map› is defined the way it is.
 ›

fun foldl :: "('b ==> 'a ==> 'b) ==> 'b ==> 'a list ==> 'b" where
"foldl f a [] = a" |
"foldl f a (x # xs) = foldl f (f a x) xs"

time_fun foldl

text‹This definition is generated:

 ‹fun T_foldl :: ('b ==> 'a ==> 'b) × ('b ==> 'a ==> nat) ==> 'b ==> 'a list ==> nat where
 T_foldl (f,T_f) a [] = 1 |
 T_foldl (f,T_f) a (x # xs) = T_f a x + T_foldl f (f a x) xs + 1›

  meaning of the pair ‹(f, T_f)› is obvious. The difference to ‹T_map› is
  ‹T_foldl› needs not just ‹T_f› (like ‹T_map›) but also ‹f›. Function ‹T_map› does not need ‹f›:
  the recursion equation ‹map f (x # xs) = f x # map f xs› the result of subterm ‹f x›
  irrelevant for the computation of ‹T_map› because the running time of ‹(#)› is constant.
  is in contrast to ‹foldl›, whose running time may depend on its second argument.

  higher-order functions are translated like ‹foldl›, but if the first element in ‹(f,T_f)›
  unused, a simplified definition is derived. This is the case for ‹T_map›.

  case you wonder how it is ensured that ‹T_foldl› is always passed a corresponding pair
  a function and its timing function: this is the responsibility of the time framework
  translating functions that use ‹foldl›. Example:›

definition inc :: "int ==> 'a ==> int" where "inc i x = i+1"
definition "len2 xs = foldl inc 0 xs"
time_definition inc
time_definition len2

text ‹In the defining equation ‹T_len2 xs = T_foldl (inc, T_inc) 0 xs›
  find the correct pair ‹(inc, T_inc)›.›


subsection ‹Limitations›

text‹Partial application and lambda-abstraction are currently not supported.
  need to be replaced by additional function definitions, if possible. For example,›

definition fHO :: "bool list ==> bool list" where ‹fHO = map (λx. x ∧ x)›

text ‹is not acceptable (i.e. ‹time_definition fHO› fails), but can be replaced with›

definition double :: "int ==> int" where ‹double i = 2 * i›
definition fHO' :: "int list ==> int list" where ‹fHO' xs = map double xs›

time_definition double
time_definition fHO'

text ‹That is why in the definition of ‹len2› above we could not just write
 ‹foldl (λi x. i+1) 0 xs›.›


section ‹Predefined Functions›

text‹The time framework requires executable functions. However,
  basic types and functions are not defined via ‹datatype› and ‹fun›
  in an abstract mathematical fashion and are not executable,
 .e. the time framework does not apply (or gives the `wrong' result).

  order to model actual hardware that executes these predefined functions in constant time,
  is a command for axiomatically declaring that some function takes 0 time.
 This is how we model constant time, to simplify the resulting time expressions.
  does not change the asymptotic running time of user-defined functions using the
  functions because 1 is added for every user-defined function call.)
  🍋‹HOL-Library.Time_Commands› declares a number of predefined functions
  0-time functions. This includes
\<open>(+)\<close>, \<open>-\<close>, \<open>(*)›, ‹/›, ‹div›, ‹min›, ‹max›, ‹<\<close>, ‹≤›, \¬›, ‹∧›, ‹∨› and ‹=›
and can be extended with the command \<open>time_fun_0\<close>.
This feature has to be used with care:

\<^item> Many of these functions are polymorphic and reside in type classes.
The constant-time assumption is justified only for those types where the hardware offers
suitable support, e.g. numeric types. The argument size is implicitly bounded, too.

\<^item> The constant-time assumption for \<open>(=)\<close> is justified for recursive data types such as lists and trees
as long as the comparison is of the form \<open>t = c\<close> where \<open>c\<close> is a constant term, for example \<open>xs = []\<close>.

Users of the time framework need to ensure that 0-time functions are used only within these bounds.\<close>


section \<open>Locales\<close>

text \<open>If we want to apply the time framework to a function \<open>g\<close> defined within a locale,
we need to add additional locale parameters \<open>T_f :: \<tau> \<Rightarrow> nat\<close> for every locale
parameter \<open>f :: \<tau> \<Rightarrow> \<tau>'\<close> used in the definition of \<open>g\<close>.

In the following example we do not only parameterize the locale with \<open>T_f\<close>
but also assume a property of \<open>T_f\<close>. As a result we can prove a property of \<open>T_g\<close>
inside the locale:\<close>

lemma T_map_sum: "T_map T_f xs = sum_list (map T_f xs) + length xs + 1"
by(induction xs) (auto)

locale LT =
fixes f :: "'a \<Rightarrow> 'a"
and T_f :: "'a \<Rightarrow> nat"
assumes T_f: "T_f x \<le> 1"
begin

definition g where "g xs = map f xs"

time_definition g

lemma sum_list_map_T_f_ub: "sum_list (map T_f xs) \<le> length xs"
proof(induction xs)
  case (Cons a xs) thus ?case using T_f[of a] by auto
qed simp

lemma T_g_ub: "T_g xs \<le> 2 * length xs + 1"
unfolding T_g.simps T_map_sum using sum_list_map_T_f_ub[of xs]
by linarith

end

text \<open>Of course now you need to prove \<open>T_f x \<le> 1\<close> for every interpretation of the locale.
A more flexible approach is not to constrain \<open>T_f\<close> inside the locale. It may then be difficult
to derive a generic time bound for \<open>T_g\<close> inside the locale (in the above example it would not be
difficult). If that is the case, one may also derive a bound for \<open>T_g\<close> conditional
on some specific bound for \<open>T_f\<close>. Or one can derive the bound for \<open>T_g\<close>
after a specific interpretation with a specific \<open>T_f\<close>.
For a larger realistic example of the latter approach see theory
\<open>HOL-Data_Structures.Time_Locale_Example\<close>.\<close>


section \<open>Fine Points\<close>

text \<open>Time functions for mutually recursive functions \<open>f, g, \<dots>\<close>: \<open>time_fun f g \<dots>\<close>.\<close>

text \<open>If you want to generate time functions not from the defining equations of a function
but from lemmas proved as equations, you can provide those lemmas explicitly. Example:\<close>

fun f0 :: "nat \<Rightarrow> nat" where
"f0 0 = 0" |
"f0 (Suc n) = f0 n"

lemma f0_eq: "f0 n = 0"
by (induction n) auto

time_fun f0 equations f0_eq

text \<open>The \<open>T_\<close> prefix can be changed by modifying the \<open>time_prefix\<close> attribute. Example:\<close>

declare [[time_prefix = "t_"]]

text \<open>The time framework is not verified
(which is why the framework always prints out what it defines).
There is no underlying formal model. This remains future work.\<close>

end