Update documentation with info about floats + fractional literals

CHANGES.md

@@ -54,6 +54,21 @@
   typechecker will use that information to infer superclass instances
   from subclasses.
 
+* Added a family of base types, `Float e p`, for working with
+  floating point numbers.  The parameters control the precision of
+  the numbers, with `e` being the number of bits to use in the exponent
+  and `p-1` being the number of bits to use in the mantissa.
+  The `Float` family of types may be used through the usual overloaded
+  functionality in Cryptol, and there is a new buit-in module called
+  `Float`, which contains functionality specific to floating point numbers.
+
+* Add a way to write fractional literals in base 2,8,10, and 16.
+  Fractional literals are overloaded, and may be used for different types
+  (currently `Rational` and the `Float` family).  Fractional literal in base
+  2,8,and 16 must be precise, and will be rejected statically if they cannot be
+  represented exactly.  Fractional literals in base 10 are rounded to the
+  nearest even representable number.
+
 ## New features
 
 * Document the behavior of lifted selectors.

docs/CryptolPrims.md

@@ -38,6 +38,21 @@ Literals
                    , lengthFromThenTo first next last == len) =>
 		   [len]a
 
+Fractional Literals
+-------------------
+
+The predicate `FLiteral m n r a` asserts that the type `a` contains the
+fraction `m/n`.  The flag `r` indicates if we should round (`r >= 1`)
+or report an error if the number can't be represented exactly.
+
+    type FLiteral : # -> # -> # -> * -> Prop
+
+
+Fractional literals are desugared into calles to the primitive `fraction`:
+
+    fraction : { m, n, r, a } FLiteral m n r a => a
+
+
 
 Zero
 ----

docs/ProgrammingCryptol/appendices/Syntax.tex

@@ -188,6 +188,51 @@ \section{Numeric Literals}\label{numeric-literals}}
                     // a = Integer or [n] where n >= width 10
 \end{verbatim}
 
+Numeric literals may also be written as polynomials by writing a
+polynomial expression in terms of \texttt{x} between an opening
+\texttt{\textless{}\textbar{}} and a closing
+\texttt{\textbar{}\textgreater{}}. Numeric literals in polynomial
+notation result in bit sequences of length one more than the degree of
+the polynomial. Examples:
+
+\begin{verbatim}
+<| x^^6 + x^^4 + x^^2 + x^^1 + 1 |>  // : [7], equal to 0b1010111
+<| x^^4 + x^^3 + x |>                // : [5], equal to 0b11010
+\end{verbatim}
+
+Cryptol also supports fractional literals using binary (prefix
+\texttt{0b}), octal (prefix \texttt{0o}), decimal (no prefix), and
+hexadecimal (prefix \texttt{ox}) digits. A fractional literal must
+contain a \texttt{.} and may optionally have an exponent. The base of
+the exponent for binary, octal, and hexadecimal literals is 2 and the
+exponent is marked using the symbol \texttt{p}. Decimal fractional
+literals use exponent base 10, and the symbol \texttt{e}. Examples:
+
+\begin{verbatim}
+10.2
+10.2e3            // 10.2 * 10^3
+0x30.1            // 3 * 64 + 1/16
+0x30.1p4          // (3 * 64 + 1/16) * 2^4
+\end{verbatim}
+
+All fractional literals are overloaded and may be used with types that
+support fractional numbers (e.g., \texttt{Rational}, and the
+\texttt{Float} family of types).
+
+Some types (e.g.~the \texttt{Float} family) cannot represent all
+fractional literals precisely. Such literals are rejected statically
+when using binary, octal, or hexadecimal notation. When using decimal
+notation, the literal is rounded to the closes represental even number.
+
+All numeric literals may also include \texttt{\_}, which has no effect
+on the literal value but may be used to improve readability. Here are
+some examples:
+
+\begin{verbatim}
+0b_0000_0010
+0x_FFFF_FFEA
+\end{verbatim}
+
 \hypertarget{expressions}{%
 \section{Expressions}\label{expressions}}
 
@@ -233,6 +278,7 @@ \section{Expressions}\label{expressions}}
 if x
   then y
   else z : Bit  // the type annotation is on `z`, not the whole `if`
+[1..9 : [8]]    // specify that elements in `[1..9]` have type `[8]`
 \end{verbatim}
 
 \textbf{Local Declarations}
@@ -579,8 +625,8 @@ \section{Type Synonym Declarations}\label{type-synonym-declarations}}
 \hypertarget{modules}{%
 \section{Modules}\label{modules}}
 
-A \textbf{\emph{module}} is used to group some related definitions.
-Each file may contain at most one module.
+A \textbf{\emph{module}} is used to group some related definitions. Each
+file may contain at most one module.
 
 \begin{verbatim}
 module M where

docs/ProgrammingCryptol/crashCourse/CrashCourse.tex

@@ -287,6 +287,61 @@ \section{Rationals}
 and integers.
 
 
+%===============================================================================
+\section{Floating Point Numbers}
+\label{sec:floats}
+
+The family of types \texttt{Float e p}\indTheFloatType represent IEEE 754
+floating point numbers with \texttt{e} bits in the exponent and
+\texttt{p-1} bits in the mantissa.  The family is defined in a built-in
+module called \texttt{Float} so to use it you'd need to either import
+it in you Cryptol specification or use \texttt{:m Float} on the
+Cryptol REPL.
+
+Floating point numbers may be written using either integral or fractioanl
+literals.  In general, literals that cannot be represented exactly are
+rejected with a type error, with the exception of decimal fractional litrals
+which are rounded to the nearest even representable numbers.
+
+Floating point numbers may be manipulated and compared using
+standard Cryptol operators, such as \texttt{+}, \texttt{==}, and \texttt{/.}
+(but {\em not} \texttt{/} which is only for integral types).
+When using the standard Cryptol operators the results that cannot be
+represented exactly are rounded to the nearest even representable number.
+
+The module \texttt{Float} provides additional functionality specific
+to floating point numbers.  In particular, it contains constants for
+writing special floating point values, and arithmetic operations
+that are parameterized on the rounding mode to use during computation
+(e.g., \texttt{fpAdd}).
+
+Of particular importance is the relation \texttt{=.=} for comparing
+floating point numbers semantically, rather that using the IEEE equality,
+which is done by \texttt{==}.  The behavior of the two differs
+mostly on special values, here are some examples:
+\begin{Verbatim}
+Float> fpNaN == (fpNaN : Float64)
+False
+Float> fpNaN =.= (fpNaN : Float64)
+True
+Float> 0 == (-0 : Float64)
+True
+Float> 0 =.= (-0 : Float64)
+False
+\end{Verbatim}
+
+Cryptol supports reasoning about floating point numbers using the
+{\texttt What4} interface to solvers that support IEEE floats.
+These back-ends have names starting with {\texttt w4}, for example,
+a good one to try is \texttt{w4-z3}.
+
+The Cryptol REPL has some settings to control how floating point numbers
+are printed on the REPL.  In particular \texttt{:fp-base} specifies
+in what numeric base to output floating point numbers, while
+\texttt{:fp-format} provides various settings for formatting the
+results.   For more information, see \texttt{:help :set fp-format}.
+
+
 %=====================================================================
 % \section{Tuples: Heterogeneous collections}
 % \label{sec:tuple}

docs/ProgrammingCryptol/utils/Indexes.tex

@@ -50,6 +50,7 @@
 \newcommand{\indTheWordType}{\index{word}\xspace}
 \newcommand{\indTheIntegerType}{\index{integer}\xspace}
 \newcommand{\indTheRationalType}{\index{rational}\xspace}
+\newcommand{\indTheFloatType}{\index{float}\xspace}
 \newcommand{\indTheSequenceType}{\index{sequence}\xspace}
 \newcommand{\indTheRecordType}{\index{record}\xspace}
 \newcommand{\indTheStringType}{\index{string}\xspace}

docs/Syntax.md

@@ -184,6 +184,32 @@ the degree of the polynomial.  Examples:
     <| x^^6 + x^^4 + x^^2 + x^^1 + 1 |>  // : [7], equal to 0b1010111
     <| x^^4 + x^^3 + x |>                // : [5], equal to 0b11010
 
+Cryptol also supports fractional literals using binary (prefix `0b`),
+octal (prefix `0o`), decimal (no prefix), and hexadecimal (prefix `ox`) digits.
+A fractional literal must contain a `.` and may optionally have an exponent.
+The base of the exponent for binary, octal, and hexadecimal literals is 2
+and the exponent is marked using the symbol `p`.  Decimal fractional literals
+use exponent base 10, and the symbol `e`.  Examples:
+
+    10.2
+    10.2e3            // 10.2 * 10^3
+    0x30.1            // 3 * 64 + 1/16
+    0x30.1p4          // (3 * 64 + 1/16) * 2^4
+
+All fractional literals are overloaded and may be used with types that support
+fractional numbers (e.g., `Rational`, and the `Float` family of types).
+
+Some types (e.g. the `Float` family) cannot represent all fractional literals
+precisely.  Such literals are rejected statically when using binary, octal,
+or hexadecimal notation.  When using decimal notation, the literal is rounded
+to the closes represental even number.
+
+
+All numeric literals may also include `_`, which has no effect on the
+literal value but may be used to improve readability.  Here are some examples:
+
+    0b_0000_0010
+    0x_FFFF_FFEA
 
 Expressions
 ===========