# Using Gappa from other tools¶

## Why and Gappa¶

The Why software verification platform can be used to translate code annotated with pre- and postconditions into proof obligations suitable for Gappa.

By installing Frama-C first and then Why (in order to build the Jessie plugin), one gets a tool for directly certifying C programs with Gappa.

### Example: floating-point square root¶

The example below demonstrates the usage of these tools. The C file
defines a `sqrt`

function that computes the square root with a relative
accuracy of \(2^{-43}\) for an input `x`

between 0.5 and 2.

```
/*@
requires 0.5 <= x <= 2;
ensures \abs(\result - 1/\sqrt(x)) <= 0x1p-6 * \abs(1/\sqrt(x));
*/
double sqrt_init(double x);
/*@
lemma quadratic_newton: \forall real x, t; x > 0 ==>
\let err = (t - 1 / \sqrt(x)) / (1 / \sqrt(x));
(0.5 * t * (3 - t * t * x) - 1 / \sqrt(x)) / (1 / \sqrt(x)) ==
- (1.5 + 0.5 * err) * (err * err);
*/
/*@
requires 0.5 <= x <= 2;
ensures \abs(\result - \sqrt(x)) <= 0x1p-43 * \abs(\sqrt(x));
*/
double sqrt(double x)
{
int i;
double t, u;
t = sqrt_init(x);
/*@ loop pragma UNROLL 4;
@ loop invariant 0 <= i <= 3; */
for (i = 0; i <= 2; ++i) {
u = 0.5 * t * (3 - t * t * x);
//@ assert \abs(u - 0.5 * t * (3 - t * t * x)) <= 1;
/*@ assert \let err = (t - 1 / \sqrt(x)) / (1 / \sqrt(x));
(0.5 * t * (3 - t * t * x) - 1 / \sqrt(x)) / (1 / \sqrt(x)) ==
- (1.5 + 0.5 * err) * (err * err); */
//@ assert \abs(u - 1 / \sqrt(x)) <= 0x1p-10 * \abs(1 / \sqrt(x));
t = u;
}
//@ assert x * (1 / \sqrt(x)) == \sqrt(x);
return x * t;
}
```

The code starts by calling the `sqrt_init`

function. It returns an
approximation of \(x^{-1/2}\) with a relative accuracy
of \(2^{-6}\). Only the specification of this auxiliary function is
given. (Preconditions are introduced by the `requires`

keyword, while
postconditions are introduced by `ensures`

.) Its implementation could
use small tables for instance. Note that bounds on relative errors are
expressed as \(|\mathit{approx} - \mathit{exact}| \le \mathit{error}
\times |\mathit{exact}|\) in this setting.

The `sqrt`

function then performs three Newton iterations in order to
obtain an improved approximation of the reciprocal square root of `x`

.
Since Gappa only handles straight-line programs, a pragma annotation
instructs Frama-C to completely unroll the loop before passing it to
Jessie. Finally, once the reciprocal square root has been computed, it
is multiplied by `x`

to obtain the square root.

### Passing hints through annotations¶

The `assert`

annotations cause Frama-C/Jessie to generate additional
proof obligations. These facts are then available to the following proof
obligations as hypotheses. In this example, the actual content of the
assertions does not matter from a certification point of view, they are
only used as a way to pass information to Gappa. Indeed, as explained in
ref:example-fixed, Gappa needs to know about Newton’s relation and
which expressions are approximations of what. So, if the program were to
be directly expressed in Gappa syntax, the three loop assertions would
instead have been written as follows.

```
rsqrt = 1 / sqrt(x);
err = (t - rsqrt) / rsqrt;
{ ... }
u ~ 0.5 * t * (3 - t * t * x);
(0.5 * t * (3 - t * t * x) - rsqrt) / rsqrt -> - (1.5 + 0.5 * err) * (err * err);
u ~ rsqrt;
```

When writing these assertions for guiding Gappa, one just as to make sure
that they are easily provable; their actual accuracy is not relevant. For
instance, if the relative distance between `u`

and \(1 / \sqrt{x}\)
had been \(2^{-1}\) instead of \(2^{-10}\), Gappa would still
have succeeded.

### Execution results¶

Passing the program above to the Frama-C/Jessie tool produces the following console output…

```
$ frama-c -jessie a.c
[kernel] preprocessing with "gcc -C -E -I. -dD a.c"
[jessie] Starting Jessie translation
[kernel] No code for function sqrt_init, default assigns generated
[jessie] Producing Jessie files in subdir a.jessie
[jessie] File a.jessie/a.jc written.
[jessie] File a.jessie/a.cloc written.
[jessie] Calling Jessie tool in subdir a.jessie
Generating Why function sqrt
[jessie] Calling VCs generator.
gwhy-bin [...] why/a.why
Computation of VCs...
Computation of VCs done.
Reading GWhy configuration...
Loading .gwhyrc config file
GWhy configuration loaded...
Creating GWhy Tree view...
```

…and displays the following user interface.

On the left of the window are the proof obligations. Once all of them
are proved, the code is guaranteed to match its specification. Green
marks flag proof obligations that were automatically proved. Selected
proof obligations are displayed on the right; here it is the
postcondition of the `sqrt`

function.

Gappa is not able to prove Newton’s relation nor does it know that \(x \times \sqrt{x}^{-1} = \sqrt{x}\) holds. These assertions are therefore left unproved. Due to loop unrolling, Newton’s relation appears three times. To factor these occurrences, a lemma describing the relation has been added to the C code. The Alt-Ergo prover is used to check that the three occurrences indeed match this lemma.

In the end, we have 72 proof obligations and only two of them are left unproved by the combination of Gappa and Alt-Ergo. They are mathematical identities on real-valued expressions, so they could easily be checked with an interactive proof assistant or a computer algebra system. (And they should be, at least for Newton’s relation, because of its error-prone expression.)

## Coq and Gappa¶

The Gappa Coq Library adds a
`gappa`

tactic to the Coq Proof Assistant.
This tactic invokes Gappa to solve properties about floating-point or
fixed-point arithmetic. It can also solve simple inequalities over real
numbers.

The tactic is provided by the `Gappa_tactic`

module. It expects to
find a Gappa executable (called `gappa`

) in the user program path.

```
From Coq Require Import Reals.
From Flocq Require Import Core.
From Gappa Require Import Gappa_tactic.
Open Scope R_scope.
Goal
forall x y : R,
3/4 <= x <= 3 ->
0 <= sqrt x <= 1775 * powerRZ 2 (-10).
Proof.
gappa.
Qed.
```

The tactic recognizes fully-applied `rounding_fixed`

and
`rounding_float`

functions as rounding operators.

The script below proves that the difference between two double precision floating-point numbers in \([\frac{52}{16}, \frac{53}{16}]\) and \([\frac{22}{16}, \frac{30}{16}]\) is exactly representable as a double-precision floating-point number. (Rounding direction does not matter for this example; it has been arbitrarily chosen as rounding toward zero.)

```
Definition rnd := rounding_float rndZR 53 (-1074).
Goal
forall a_ b_ a b : R,
a = rnd a_ ->
b = rnd b_ ->
52 / 16 <= a <= 53 / 16 ->
22 / 16 <= b <= 30 / 16 ->
rnd (a - b) = (a - b).
Proof.
unfold rnd; gappa.
Qed.
```

The tactic handles goals and hypotheses that are either equalities of
real numbers, \(e_1 = e_2\), or pairs of inequalities on real
numbers, \(b_1 \le e \le b_2\), or inequalities expressing relative
errors, \(|e_1 - e_2| \le b \cdot |e_2|\). For inequalities, the *b*
bounds have to be explicit dyadic numbers. The tactic also recognizes
properties written as \(|e| \le b\) as syntactic sugar for \(0
\le |e| \le b\).

The tactic is built on Flocq’s formalism and uses the same rounding operators and formats. The previous goal could therefore have been written in a slightly more natural way.

```
Definition format :=
generic_format radix2 (FLT_exp (-1074) 53).
Goal
forall a b : R,
format a -> format b ->
52 / 16 <= a <= 53 / 16 ->
22 / 16 <= b <= 30 / 16 ->
format (a - b).
Proof.
unfold format; gappa.
Qed.
```