> For the complete documentation index, see [llms.txt](https://docs.varphi-lang.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.varphi-lang.com/ampliphi.md).

# Ampliphi

Ampliphi is a high-level, imperative programming language designed to compile down to the Varphi architecture.

Ampliphi was originally developed by [Hassan El-Sheikha](https://www.linkedin.com/in/hassan-el-sheikha/), [Kevin Thevara](https://www.linkedin.com/in/kevin-thevara/), and [Youssef Abouzied](https://www.linkedin.com/in/youssef-abouzied/) as part of a compilers course at the University of Toronto. It provides a familiar C-like syntax with strong static typing, arrays, and procedures. It attempts to abstract away the complexities of writing raw Varphi assembly while utilizing an advanced compiler optimization pipeline to produce more efficient Varphi code.

***

### Quick Look

Ampliphi programs consist of global variable declarations followed by procedures. The entry point of every program is the `main` procedure.

Because Ampliphi compiles directly to Varphi, each declared variable maps directly to a tape in the generated Varphi code. When running your program via the Ampliphi CLI, you will be automatically prompted to initialize the values of these variables/tapes before the program executes.

Here is a simple program that calculates the sum of an array:

```c
// Global declarations
int[5] arr;
int sum;
int i;
bool cond;

// Entry point
procedure main {
    sum = 0;
    i = 0;
    
    // Note: Control flow conditions must be evaluated into a boolean variable first!
    cond = i < 5;
    
    while (cond) {
        sum = sum + arr[i];
        i = i + 1;
        
        // Re-evaluate condition for the next iteration
        cond = i < 5;
    }
}
```

***

### Getting Started

#### Installation

You can install the Ampliphi toolchain directly via PyPI using `uv` or `pip`:

```bash
uv pip install ampliphi
```

Alternatively, you can download the standalone executable for your operating system (Windows, macOS, or Linux) from our [GitHub Releases](https://github.com/varphi-lang/ampliphi/releases/latest).

#### Usage

To compile and run an Ampliphi source file, simply use the CLI:

```bash
ampliphi my_program.aphi --run
```

If you use the `--run` flag, the CLI will interactively ask you to provide initial values for your global variables (tapes) before executing the compiled Varphi.

You can also inspect the compilation pipeline by emitting the AST, IR, or Tokens:

```
Usage: ampliphi [OPTIONS] INPUT_FILE

Options:
  -t, --tokens          Print the token stream from the lexer.
  -a, --ast             Print the abstract syntax tree.
  -c, --check           Check syntax and types only (do not compile).
  -x, --xml             Print the AST in XML format.
  -i, --ir              Print the intermediate representation.
  -r, --run             Run the compiled program immediately.
  --no-opt              Disable optimizations.
  --help                Show this message and exit.
```

***

### Language Guide

#### Variables and Types

All variables in Ampliphi are **global** and must be declared at the top of the file before any procedures. Ampliphi supports two primitive types: `int` and `bool`, as well as fixed-size arrays.

```c
int x;
bool flag;
int[10] arr;
```

{% hint style="info" %}
In the compiled Varphi output for the snippet above, `x` and `flag` will each become a standard tape, while `arr` will consist of 10 array tapes.
{% endhint %}

#### Procedures

Code is organized into procedures. A program must contain at least one procedure named `main`. Procedures can invoke other procedures using the `invoke` keyword.

```c
procedure do_work {
    x = x + 1;
}

procedure main {
    x = 0;
    invoke do_work;
}
```

#### Control Flow

Ampliphi supports `if/else` and `while` statements.

{% hint style="info" %}
The condition for an `if` or `while` statement *cannot* be an inline expression (like `x < 5`). It **must** be a boolean identifier. You must evaluate your condition into a boolean variable first.
{% endhint %}

```c
bool greater;
int x;

procedure main {
    greater = x > 10;
    
    if (greater) {
        x = 10;
    } else {
        x = 0;
    }
}
```

***

### Formal Grammar

Ampliphi follows a strict, easy-to-parse grammar. Below is the formal EBNF specification:

```ebnf
program = {declaration} {procedure}

declaration = type identifier ";"
            | type "[" int_literal "]" identifier ";"

type = "int" | "bool"

procedure = "procedure" identifier "{" {statement} "}"

statement = assignment
          | if_statement
          | while_statement
          | invoke_statement

assignment = identifier "=" rhs ";"
           | array_access "=" rhs ";"

rhs = operand
    | unary_op operand
    | operand binary_op operand

if_statement = "if" "(" identifier ")" "{" {statement} "}" "else" "{" {statement} "}"

while_statement = "while" "(" identifier ")" "{" {statement} "}"

invoke_statement = "invoke" identifier ";"

operand = identifier | literal | array_access

array_access = identifier "[" operand "]"

binary_op = "+" | "-" | ">" | "<" | "==" | "&&" | "||"

unary_op = "!"

literal = int_literal | bool_literal

bool_literal = "true" | "false"

int_literal = digit {digit}  

identifier = letter { letter | digit } 

letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"

digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.varphi-lang.com/ampliphi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.