qft-rs - Native Rust SDK for Quantum File Type

Production-grade Rust library for working with quantum states in the .qft format.

Installation

Add to your Cargo.toml:

[dependencies]

qft = "1.0"



# With async support

qft = { version = "1.0", features = ["async"] }

Quick Start

use qft::prelude::*;

fn main() -> Result<()> {
    // Create a 4-qubit state
    let mut state = QftFile::new(4)?;
    
    // Set to GHZ-like state |0000⟩ + |1111⟩
    state[0] = Complex64::new(1.0 / 2.0_f64.sqrt(), 0.0);
    state[15] = Complex64::new(1.0 / 2.0_f64.sqrt(), 0.0);
    
    // Save to disk
    state.save("state.qft")?;
    
    // Load and verify
    let loaded = QftFile::load("state.qft")?;
    assert!((state.fidelity(&loaded)? - 1.0).abs() < 1e-10);
    
    Ok(())
}

Features

Builder API

use qft::QftBuilder;

let state = QftBuilder::new(4)
    .bond_dimension(128)
    .golay(true)
    .metadata("author", "Alice")
    .metadata("experiment", "VQE ground state")
    .build()?;

Common States

use qft::{bell_state, ghz_state, uniform_state, basis_state};

let bell = bell_state()?;                    // |00⟩ + |11⟩
let ghz = ghz_state(4)?;                     // |0000⟩ + |1111⟩
let uniform = uniform_state(3)?;             // Equal superposition
let basis = basis_state(4, 5)?;              // |0101⟩

State Operations

let mut state = QftFile::new(4)?;

// Normalization
state.normalize()?;
assert!(state.is_normalized(1e-10));

// Fidelity
let other = QftFile::new(4)?;
let fid = state.fidelity(&other)?;

// Inner product
let overlap = state.inner_product(&other)?;

// Trace distance
let dist = state.trace_distance(&other)?;

I/O Operations

// Binary format
state.save("state.qft")?;
let loaded = QftFile::load("state.qft")?;

// Bytes
let bytes = state.to_bytes()?;
let from_bytes = QftFile::from_bytes(&bytes)?;

// JSON
let json = state.to_json()?;
let from_json = QftFile::from_json(&json)?;

Async I/O (feature-gated)

use qft::QftFile;

#[tokio::main]
async fn main() -> qft::Result<()> {
    let state = QftFile::new(4)?;
    state.save_async("state.qft").await?;
    
    let loaded = QftFile::load_async("state.qft").await?;
    Ok(())
}

Configuration

use qft::{QftFile, QftConfig};

let config = QftConfig {
    bond_dimension: 128,
    golay_enabled: true,
    truncation_threshold: 1e-12,
};

let state = QftFile::with_config(4, config)?;

Metadata

let mut state = QftFile::new(4)?;

state.set_metadata("author", "Alice");
state.set_metadata("date", "2026-01-25");

if let Some(author) = state.get_metadata("author") {
    println!("Author: {}", author);
}

for (key, value) in state.metadata() {
    println!("{}: {}", key, value);
}

API Reference

QftFile

QftBuilder

Error Types

Performance

Feature Flags

License

MIT OR Apache-2.0