From 548dc42d9f454cb8c29fddb88ca41f8b1b595882 Mon Sep 17 00:00:00 2001
From: hachem <im@hachem.wtf>
Date: Wed, 10 Dec 2025 23:14:16 +0100
Subject: [add]: prelimenary noise layers

---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 4605e24..c5707c8 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,34 @@ Automatic detection and use of platform-specific SIMD instructions:
 - Multi-pass fusion until convergence
 - Execution layer grouping for parallelism
 
+### Noise Channels (Density Matrix)
+
+Realistic quantum noise simulation using Kraus operators:
+
+| Channel | Description |
+|---------|-------------|
+| `depolarising(p)` | Random Pauli error with probability $p$ |
+| `amplitude_damping(γ)` | Energy decay ($T_1$ relaxation) |
+| `phase_damping(γ)` | Phase decoherence ($T_2$ dephasing) |
+| `bit_flip(p)` | $X$ error with probability $p$ |
+| `phase_flip(p)` | $Z$ error with probability $p$ |
+| `bit_phase_flip(p)` | $Y$ error with probability $p$ |
+
+```rust
+use libpsi_core::{DensityMatrix, NoiseChannel};
+
+// Create density matrix from circuit state
+let dm = DensityMatrix::from_state_vector(&state_vec);
+
+// Apply noise
+let noise = NoiseChannel::depolarising(0.05);
+dm.apply_noise_channel(&noise, 0);  // Apply to qubit 0
+
+// Check properties
+println!("Purity: {}", dm.purity());       // 1.0 = pure, <1.0 = mixed
+println!("Fidelity: {}", dm.fidelity_with_pure_state(&ideal_state));
+```
+
 ## Project Structure
 
 - **`libpsi-core`**: Core quantum simulation library
-- 
cgit v1.3