Sansqrit DSL — Complete Syntax

Language Mindmap

This infographic shows the complete structure of the Sansqrit DSL. Every node is a capability documented on this page. The language is organized into three layers: classical computing (variables, control flow, functions), quantum computing (gates, algorithms, circuits), and domain packages (chemistry, biology, ML).

Quick Start — Your First Program

Sansqrit programs are saved as .sq files and executed with cargo run --bin sansqrit -- run program.sq. The language is Python-like in appearance but quantum-native: gate functions and measurement are first-class operations, not library calls. Here is a complete program that creates a Bell state, measures it 1000 times, and prints the results:

-- bell.sq — A complete Sansqrit program
print("Creating a Bell state...")

simulate {
    let q = quantum_register(2)     -- allocate 2 qubits
    H(q[0])                          -- Hadamard on qubit 0
    CNOT(q[0], q[1])                -- entangle qubits 0 and 1
    let result = measure_all(q, shots=1000)
    print(f"Results: {result}")       -- {"00": ~500, "11": ~500}
    print(f"⟨Z₀⟩ = {expectation_z(q[0]):.4f}")
}

print("Done!")

How the lexer processes this: The lexer reads each character and produces tokens: KW_PRINT, LPAREN, STRING("Creating..."), RPAREN, NEWLINE, KW_SIMULATE, LBRACE, etc. The parser then builds an AST with a Simulate statement containing a body of LetDecl, ExprStmt (gate calls), and LetDecl (measurement). The interpreter executes these sequentially, dispatching gate calls to the QuantumEngine.

Keywords (33)

Reserved words that cannot be used as variable names. These are recognized by the lexer and have special meaning in the parser. The complete list:

Data Types (8)

Sansqrit is dynamically typed — variables can hold any type and types are checked at runtime. The eight fundamental data types are:

-- Type examples
let age = 42                      -- Int
let energy = -1.137               -- Float
let name = "Sansqrit"             -- String
let active = true                 -- Bool
let primes = [2, 3, 5, 7]        -- List
let config = {"shots": 1000}     -- Dict
let unique = {1, 2, 3}           -- Set
let result = None                 -- None

-- Type checking
print(type(age))      -- "Int"
print(type(energy))   -- "Float"
print(type(primes))   -- "List"

Operators (22)

Listed from lowest to highest precedence. Operators higher in the table bind more loosely.

Assignment Operators

let x = 10     -- assign
x += 5          -- add-assign: x = 15
x -= 3          -- subtract-assign: x = 12
x *= 2          -- multiply-assign: x = 24
x /= 4          -- divide-assign: x = 6.0

Variables & Constants

Variables are declared with let (mutable) or const (immutable). Sansqrit uses lexical scoping — variables are visible in the block where they are declared and all nested blocks.

let x = 42              -- mutable: can be reassigned
x = 99                  -- OK: x is mutable
const PI_APPROX = 3.14  -- immutable: cannot be reassigned
-- PI_APPROX = 3.0     -- ERROR: cannot reassign const

-- Type annotation (optional)
let name: String = "Alice"
let count: Int = 0

-- Multiple assignments
let a = 1
let b = 2
let c = a + b  -- c = 3

Control Flow

if / else / else if

if energy < -1.0 {
    print("Ground state found!")
} else if energy < 0.0 {
    print("Bound state")
} else {
    print("Unbound")
}

for loop

-- Range iteration
for i in range(10) { print(i) }          -- 0,1,2,...,9
for i in range(2, 8) { print(i) }       -- 2,3,...,7
for x in range_step(0.0,1.0,0.1) { }   -- float stepping

-- Collection iteration
for item in ["H", "He", "Li"] { print(item) }

-- Enumerated iteration
for (i, val) in enumerate(["a","b","c"]) {
    print(f"{i}: {val}")  -- 0: a, 1: b, 2: c
}

-- Zip iteration
for (a, b) in zip([1,2], ["x","y"]) { print(a, b) }

while / loop

let n = 1
while n < 1000 { n *= 2 }
print(n)  -- 1024

loop {
    let r = measure(q[0])
    if r == 1 { break }
}

match (Pattern Matching)

match gate_name {
    "H" => print("Hadamard"),
    "X" | "Y" | "Z" => print("Pauli gate"),
    "CNOT" => print("Entangling gate"),
    _ => print(f"Unknown: {gate_name}")
}

Functions & Lambdas

-- Named function with default parameter
fn greet(name, greeting="Hello") {
    return f"{greeting}, {name}!"
}
print(greet("Alice"))             -- "Hello, Alice!"
print(greet("Bob", "Hi"))        -- "Hi, Bob!"

-- Lambda (anonymous function)
let square = fn(x) { x ** 2 }
print(square(5))                  -- 25

-- Higher-order functions
let doubled = map([1,2,3], fn(x) { x * 2 })  -- [2, 4, 6]
let evens = filter([1,2,3,4], fn(x) { x % 2 == 0 })  -- [2, 4]
let total = reduce([1,2,3,4], fn(a,b) { a + b }, 0)  -- 10

Classes & Structs

-- Struct: data-only container
struct Point { x, y }
let p = Point(3.0, 4.0)
print(p.x)  -- 3.0

-- Class: data + methods
class Particle {
    fn init(self, mass, charge) {
        self.mass = mass
        self.charge = charge
    }
    fn energy(self, velocity) {
        return 0.5 * self.mass * velocity ** 2
    }
}
let electron = Particle(9.1e-31, -1.6e-19)
print(electron.energy(1e6))

-- Inheritance
class Photon extends Particle { }

Strings & F-Strings

let s = "Hello, World"
let s2 = 'single quotes work too'

-- F-strings (formatted string literals) — embed expressions
let e = -1.137
print(f"Energy = {e:.6f} Hartree")   -- "Energy = -1.137000 Hartree"
print(f"2 + 3 = {2 + 3}")              -- "2 + 3 = 5"
print(f"Pi ≈ {PI:.4f}")                -- "Pi ≈ 3.1416"

-- String methods
print(s.upper())       -- "HELLO, WORLD"
print(s.lower())       -- "hello, world"
print(s.contains("World"))  -- true
print(s.replace("World", "Quantum"))  -- "Hello, Quantum"
print(s.split(", "))   -- ["Hello", "World"]
print(len(s))           -- 12

Collections

-- Lists
let nums = [1, 2, 3, 4, 5]
nums.append(6)           -- [1,2,3,4,5,6]
let last = nums.pop()    -- 6 (removes last element)
print(nums[0])            -- 1 (indexing)
print(nums[-1])           -- 5 (negative index)

-- List comprehensions
let squares = [x**2 for x in range(10)]  -- [0,1,4,9,...,81]

-- Dictionaries
let d = {"H": 1, "He": 2, "Li": 3}
print(d["H"])     -- 1
d["Be"] = 4       -- add entry

Pipeline Operator ( |> )

The pipeline operator passes the result of the left expression as the first argument to the right function. It enables a data-flow style of programming that is especially natural for quantum circuits.

-- Without pipeline (nested calls, hard to read):
print(sort(filter([5,2,8,1,9], fn(x) { x > 3 })))

-- With pipeline (left-to-right, readable):
[5,2,8,1,9] |> filter(fn(x) { x > 3 }) |> sort |> print
-- Output: [5, 8, 9]

Error Handling

try {
    let result = shor_factor(1)  -- might fail for N=1
} catch e {
    print(f"Error: {e}")
} finally {
    print("Cleanup complete")
}

-- Raise custom errors
fn validate_qubits(n) {
    if n < 1 { raise "Need at least 1 qubit" }
}

Import System

import chemistry           -- import entire package
import biology as bio      -- import with alias
import medical
import physics
import genetics
import ml
import math

-- Available packages:
-- chemistry : VQE, PES, Trotter, molecular Hamiltonians
-- biology   : DNA/RNA, protein folding, alignment
-- medical   : drug screening, vaccine design, binding energy
-- physics   : Ising model, Heisenberg chain, time evolution
-- genetics  : CRISPR guide design, GWAS, variant calling
-- ml        : QNN, QSVM, QPCA, variational classifiers
-- math      : Shor factoring, Grover search, HHL solver

Simulate Block

The simulate block is where quantum operations happen. It creates a QuantumEngine instance, executes the body, and captures measurement results. You can specify the engine tier explicitly or let Sansqrit auto-select based on qubit count.

-- Auto-select engine (default)
simulate {
    let q = quantum_register(4)
    H(q[0])
    print(measure_all(q, shots=1000))
}

-- Force chunked engine for large circuits
simulate(engine="Chunked") {
    let q = quantum_register(100)
    H(q[0])
    for i in range(99) { CNOT(q[i], q[i+1]) }
    print(measure_all(q, shots=100))
}

-- Force sparse engine
simulate(engine="Sparse") { /* ... */ }

-- Force dense engine
simulate(engine="Dense") { /* ... */ }

Quantum Operations — Complete Reference

quantum_register(n) → Qubit Array

Allocates n qubits, all initialized to |0⟩. Returns an array-like object that supports indexing with q[i].

let q = quantum_register(8)  -- 8 qubits, all |0⟩
print(n_qubits())             -- 8

All 46 Gate Functions

Every gate is called as a function inside a simulate block. Single-qubit gates take one qubit argument. Parametric gates take a qubit and angle(s). Two-qubit gates take two qubits. Three-qubit gates take three qubits. Multi-qubit gates take lists.

Measurement Functions

Circuit Constructor Functions (17)

Algorithm Functions (19)

Math Functions (15)

Collection Functions (12)

String Methods (7)

I/O Functions (5)

Type Conversion Functions (5)

Built-in Constants

Molecule Declaration

molecule H2 {
    atoms: [H, H],
    bond_length: 0.74,
    basis_set: "STO-3G"
}

molecule LiH {
    atoms: [Li, H],
    bond_length: 1.6,
    basis_set: "STO-3G"
}

-- Use in VQE:
simulate {
    let r = vqe(H2)
    print(f"H₂ energy: {r.energy:.6f} Ha")
}

Circuit Declaration

circuit BellPair(q0, q1) {
    H(q0)
    CNOT(q0, q1)
}

circuit QFTCircuit(qubits) {
    for i in range(len(qubits)) {
        H(qubits[i])
        for j in range(i+1, len(qubits)) {
            CP(qubits[j], qubits[i], PI / (1 << (j-i)))
        }
    }
}

simulate {
    let q = quantum_register(4)
    BellPair(q[0], q[1])
    QFTCircuit(q)
    print(measure_all(q, shots=1000))
}

Comments

-- Single-line comment (double-dash)
# Single-line comment (hash)
/* Multi-line
   comment */
/// Documentation comment