pyrites/twelf-experiments/peano/README.md

# Peano Arithmetic in Twelf

This directory contains a formalization of Peano arithmetic and basic number theory in Twelf, including definitions, proofs of fundamental properties, and statements of advanced theorems.

## Quick Start

### Loading All Files

Using the Twelf server interactively:

```bash
twelf-server
```

Then at the Twelf prompt:

```
loadFile nat.elf
loadFile add.elf
loadFile mult.elf
loadFile exp.elf
loadFile order.elf
loadFile div.elf
loadFile prime.elf
loadFile theorems.elf
```

Or load all files at once with a script:

```bash
twelf-server <<'EOF'
loadFile nat.elf
loadFile add.elf
loadFile mult.elf
loadFile exp.elf
loadFile order.elf
loadFile div.elf
loadFile prime.elf
loadFile theorems.elf
EOF
```

### Running Computations

Once files are loaded, you can compute with `%solve`:

```
%solve _ : add (s (s z)) (s (s (s z))) N.   -- 2 + 3 = ?
%solve _ : mult (s (s z)) (s (s (s z))) N.  -- 2 * 3 = ?
%solve _ : exp (s (s z)) (s (s (s z))) N.   -- 2^3 = ?
%solve _ : factorial (s (s (s (s z)))) N.   -- 4! = ?
```

## File Structure

Files must be loaded in order due to dependencies:

| File | Description | Dependencies |
|------|-------------|--------------|
| `nat.elf` | Natural numbers (Peano axioms), equality | none |
| `add.elf` | Addition, commutativity, associativity | nat.elf |
| `mult.elf` | Multiplication, basic properties | nat.elf, add.elf |
| `exp.elf` | Exponentiation | nat.elf, add.elf, mult.elf |
| `order.elf` | Less-than, less-equal, trichotomy | nat.elf |
| `div.elf` | Divisibility, GCD, division with remainder | nat.elf, add.elf, mult.elf, order.elf |
| `prime.elf` | Primes, factorial, prime factorization | all above |
| `theorems.elf` | Computational tests, theorem summary | all above |
| `sources.cfg` | Configuration file for batch loading | - |

## Definitions

### Natural Numbers (`nat.elf`)

```
nat : type.
z : nat.              -- zero
s : nat -> nat.       -- successor
```

Numbers: `z` = 0, `s z` = 1, `s (s z)` = 2, etc.

Abbreviations: `one`, `two`, `three`, `four`, `five`

### Addition (`add.elf`)

```
add : nat -> nat -> nat -> type.
add/z : add z N N.                        -- 0 + N = N
add/s : add (s M) N (s P) <- add M N P.   -- (1+M) + N = 1 + (M + N)
```

### Multiplication (`mult.elf`)

```
mult : nat -> nat -> nat -> type.
mult/z : mult z N z.                              -- 0 * N = 0
mult/s : mult (s M) N R <- mult M N P <- add N P R.  -- (1+M) * N = N + M*N
```

### Exponentiation (`exp.elf`)

```
exp : nat -> nat -> nat -> type.
exp/z : exp N z (s z).                            -- N^0 = 1
exp/s : exp N (s M) R <- exp N M P <- mult N P R. -- N^(1+M) = N * N^M
```

### Ordering (`order.elf`)

```
lt : nat -> nat -> type.   -- less than
lt/z : lt z (s N).                      -- 0 < 1+N
lt/s : lt (s M) (s N) <- lt M N.        -- M < N implies 1+M < 1+N

le : nat -> nat -> type.   -- less than or equal
le/z : le z N.                          -- 0 <= N
le/s : le (s M) (s N) <- le M N.        -- M <= N implies 1+M <= 1+N
```

### Divisibility (`div.elf`)

```
divides : nat -> nat -> type.
divides/intro : divides D N <- mult D K N.  -- D | N iff N = D * K for some K
```

### Primes (`prime.elf`)

```
prime : nat -> type.
prime/two   : prime (s (s z)).         -- 2 is prime
prime/three : prime (s (s (s z))).     -- 3 is prime
prime/five  : prime (s (s (s (s (s z))))).  -- 5 is prime
prime/seven : prime (s (s (s (s (s (s (s z))))))).  -- 7 is prime
```

## Verified Theorems

These theorems have complete proofs checked by Twelf's totality checker (`%total`):

### Addition Properties
- **add-total**: Addition always produces a result
- **add-comm**: M + N = N + M (commutativity)
- **add-assoc**: (A + B) + C = A + (B + C) (associativity)
- **add-right-z**: N + 0 = N (right identity)
- **add-right-s**: M + (S N) = S(M + N)
- **add-cancel-left**: A + B = A + C implies B = C (left cancellation)
- **add-func**: Addition is deterministic

### Multiplication Properties
- **mult-total**: Multiplication always produces a result
- **mult-right-z**: N * 0 = 0
- **mult-left-one**: 1 * N = N
- **mult-right-one**: N * 1 = N

### Exponentiation Properties
- **exp-total**: Exponentiation always produces a result
- **exp-one**: N^1 = N
- **exp-base-one**: 1^N = 1
- **exp-base-zero**: 0^(S N) = 0

### Order Properties
- **le-refl**: N <= N (reflexivity)
- **le-trans**: A <= B and B <= C implies A <= C (transitivity)
- **le-antisym**: A <= B and B <= A implies A = B (antisymmetry)
- **lt-trans**: A < B and B < C implies A < C
- **trichotomy-total**: For all M, N: exactly one of M < N, M = N, M > N

### Divisibility Properties
- **one-divides**: 1 | N for all N
- **divides-zero**: N | 0 for all N
- **divides-refl**: N | N for all N

### Factorial
- **factorial-total**: Factorial always produces a result

## Theorems Stated But Not Fully Proven

The following theorems are stated with proof sketches but require additional infrastructure:

### Multiplication Commutativity
- **mult-comm**: M * N = N * M
- Requires the `mult-right-s` lemma (M * (S N) = M + M * N)

### Distributivity
- **mult-distrib-left**: A * (B + C) = A*B + A*C
- Provable by induction on A

### Multiplication Associativity
- **mult-assoc**: (A * B) * C = A * (B * C)
- Requires distributivity

### Number Theory
- **has-prime-divisor-total**: Every N > 1 has a prime divisor
- **infinitude-of-primes**: For any prime P, there exists a prime Q > P
- **euclid-lemma**: If P is prime and P | AB, then P | A or P | B
- **fundamental-theorem-existence**: Every N > 1 has a prime factorization
- **fundamental-theorem-uniqueness**: Prime factorization is unique up to ordering

## How Twelf Proofs Work

Twelf uses the "judgments as types" methodology. A theorem is represented as a type family, and its proof is a term of that type.

### Example: Addition Commutativity

```
add-comm : add M N P -> add N M P -> type.
%mode add-comm +D1 -D2.
```

This declares that `add-comm` takes a derivation `D1` showing `add M N P` and produces a derivation `D2` showing `add N M P`.

The `%mode` declaration specifies that `D1` is an input (+) and `D2` is an output (-).

### Totality Checking

```
%worlds () (add-comm _ _).
%total D (add-comm D _).
```

- `%worlds ()` declares the proof works in the empty world (no hypothetical assumptions)
- `%total D (add-comm D _)` verifies the proof terminates and covers all cases, with recursion on `D`

## Understanding the Output

When you run `%solve`, Twelf shows the derivation tree:

```
%solve _ : add two three N.
```

Output:
```
add (s (s z)) (s (s (s z))) (s (s (s (s (s z)))))
   = add/s (add/s add/z).
```

This shows:
- The result: 2 + 3 = 5
- The proof: apply `add/s` twice, then `add/z`

## Extending This Formalization

### Adding New Theorems

1. Identify what lemmas are needed
2. Define the theorem type with appropriate mode
3. Write cases for each constructor
4. Add `%worlds` and `%total` declarations

### Common Patterns

**Induction on a natural number:**
```
my-theorem : {N:nat} ... -> type.
%mode my-theorem +N ...
my-theorem/z : my-theorem z ...
my-theorem/s : my-theorem (s N) ... <- my-theorem N ...
%worlds () (my-theorem _ _).
%total N (my-theorem N _).
```

**Induction on a derivation:**
```
my-theorem : some-relation A B -> another-relation A B -> type.
%mode my-theorem +D1 -D2.
my-theorem/case1 : my-theorem some-relation/c1 another-relation/c1.
my-theorem/case2 : my-theorem (some-relation/c2 D) (another-relation/c2 D')
                    <- my-theorem D D'.
%worlds () (my-theorem _ _).
%total D (my-theorem D _).
```

## References

- [Twelf Wiki](http://twelf.org/wiki/Main_Page)
- [Twelf User's Guide](http://twelf.org/wiki/User%27s_Guide)
- Harper & Licata, "Mechanizing Metatheory in a Logical Framework"