update documentation

Author: kn0sys

src/circuits/mod.rs

@@ -17,8 +17,35 @@ use std::fmt;
 /// This structure embodies (Sequential Ordering) by defining a precise
 /// list of interactions to be simulated. It captures a specific process or algorithm within the framework.
 ///
-/// Analogy: Similar to `cirq.Circuit` or `qiskit.QuantumCircuit`, representing the
-/// sequence of gates and measurements applied to qubits.
+/// Analogy: Similar to `cirq.Circuit` or `qiskit.QuantumCircuit`.
+///
+/// # Examples
+///
+/// ```
+/// # use onq::{Circuit, CircuitBuilder, Operation, QduId, LockType};
+/// # fn qid(id: u64) -> QduId { QduId(id) }
+/// let q0 = qid(0);
+/// let q1 = qid(1);
+///
+/// // Create using methods
+/// let mut circuit1 = Circuit::new();
+/// circuit1.add_operation(Operation::InteractionPattern { target: q0, pattern_id: "Superposition".to_string()});
+/// circuit1.add_operation(Operation::ControlledInteraction { control: q0, target: q1, pattern_id: "QualityFlip".to_string()});
+///
+/// // Create using builder
+/// let circuit2 = CircuitBuilder::new()
+///     .add_op(Operation::InteractionPattern { target: q0, pattern_id: "Superposition".to_string()})
+///     .add_op(Operation::ControlledInteraction { control: q0, target: q1, pattern_id: "QualityFlip".to_string()})
+///     .build();
+///
+/// assert_eq!(circuit1.len(), 2);
+/// assert!(circuit1.qdus().contains(&q0));
+/// assert!(circuit1.qdus().contains(&q1));
+/// assert_eq!(circuit1, circuit2);
+///
+/// // Print the circuit diagram
+/// println!("{}", circuit1);
+/// ```
 #[derive(Clone, PartialEq)] // PartialEq useful for testing circuits
 pub struct Circuit {
     /// The unique set of QDUs involved across all operations in this circuit.
@@ -115,7 +142,22 @@ impl Default for Circuit {
 // Circuit Builder
 //-------------------------------------------------------------------------
 
-/// A helper struct for programmatically constructing `Circuit` instances using method chaining.
+/// A helper struct for programmatically constructing [`Circuit`] instances using method chaining.
+///
+/// # Examples
+/// ```
+/// # use onq::{Circuit, CircuitBuilder, Operation, QduId, LockType};
+/// # fn qid(id: u64) -> QduId { QduId(id) }
+/// let q0 = qid(0);
+/// let q1 = qid(1);
+///
+/// let circuit = CircuitBuilder::new()
+///     .add_op(Operation::InteractionPattern { target: q0, pattern_id: "Superposition".to_string()})
+///     .add_op(Operation::ControlledInteraction { control: q0, target: q1, pattern_id: "QualityFlip".to_string()})
+///     .build();
+///
+/// assert_eq!(circuit.len(), 2);
+/// ```
 pub struct CircuitBuilder {
     circuit: Circuit,
     // Potential future fields:

src/core/constants.rs

@@ -1,7 +1,10 @@
-// Example: src/core/constants.rs
+//! Mathematical constants potentially relevant to simulation.
+
+/// Mathematical constants derived from or relevant to the framework
 pub mod onq_constants {
+    /// The golden ratio constant φ (Phi).
     pub const PHI: f64 = 1.618_033_988_749_895;
-    // Add PI here too for consistency, though std::f64::consts::PI exists
+    /// Used for phase angles (`e^(iθ)`)
     pub const PI: f64 = std::f64::consts::PI;
 }
 

src/core/error.rs

@@ -1,4 +1,4 @@
-// src/core/error.rs
+//! Error handling logic
 
 use std::fmt;
 
@@ -21,23 +21,43 @@ impl fmt::Display for QduId {
 pub enum OnqError {
     /// Failure to maintain coherent state or unified reference.
     /// Analogous to failing (Phase Coherence).
-    Incoherence { message: String },
+    Incoherence {
+        /// Incoherence failure message
+        message: String
+    },
 
     /// Failure to stabilize or maintain stable patterns.
     /// Analogous to failing (Frame Stability) or (Pattern Convergence).
-    Instability { message: String },
+    Instability {
+        /// Instability failure message
+        message: String
+    },
 
     /// Compromised distinction boundary, losing qualitative distinction
-    BoundaryFailure { qdu_id: QduId, message: String },
+    BoundaryFailure {
+        /// Compromised QDU
+        qdu_id: QduId,
+        /// BoundaryFailure failure message
+        message: String
+    },
 
     /// Invalid reference, relationship, or connection between elements
-    ReferenceViolation { message: String },
+    ReferenceViolation {
+        /// ReferenceViolation failure message
+        message: String
+    },
 
     /// An applied operation is inconsistent with the current state or framework rules
-    InvalidOperation { message: String },
+    InvalidOperation {
+        /// InvalidOperation failure message
+        message: String
+    },
 
     /// General error encountered during the simulation process itself.
-    SimulationError { message: String },
+    SimulationError {
+        /// SimulationError failure message
+        message: String
+    },
     // Future: Could add variants like `FrameNotFound`, `QduNotFound` if needed by simulation logic.
 }
 

src/core/frame.rs

@@ -1,4 +1,4 @@
-// src/core/frame.rs
+//! QDU interaction logic
 
 use std::fmt;
 // Potentially use Arc later if frames need to be shared reference-counted objects

src/core/qdu.rs

@@ -1,4 +1,4 @@
-// src/core/qdu.rs
+//! ONQ qubit representation data structure
 
 use super::error::QduId;
 use std::fmt;

src/core/state.rs

@@ -1,4 +1,4 @@
-// src/core/state.rs
+//! ONQ state vector representation
 
 // Make sure `num-complex` is in Cargo.toml: `num-complex = "0.4"`
 use num_complex::Complex;

src/lib.rs

@@ -1,9 +1,50 @@
 // src/lib.rs
 
-//! `onq` - A library for simulating quantum information processing
+#![warn(missing_docs)] // Enforce documentation warnings during build
+
+//! `onq`: Operations for Next Generation Quantum Computating Simulation Library
+//!
+//! This library provides Rust structures and functions for simulating computation
+//! based *only* on abstract principles.
+//!
+//! ## Core Idea
+//!
+//! Unlike standard quantum simulators modeling quantum mechanics, `onq` explores
+//! computation emerging necessarily from a self-containing distinction. It models
+//! phenomena analogous to quantum computation (superposition,
+//! entanglement analogs, interference, stabilization) without assuming physics,
+//! relying solely on the structural and logical consequences defined by the framework
+//!
+//! ## Key Components
 //!
-//! This library provides structures and tools derived strictly from nature
-//! to model phenomena analogous to quantum computation.
+//! * **Core Types (`onq::core`):** Defines fundamental concepts like `QduId`,
+//!   `PotentialityState` (complex state vectors), and `StableState`.
+//! * **Operations (`onq::operations`):** Defines quantum operations (`Operation`, `LockType`)
+//!   (analogs of H, X, Z, S, T, CNOT, CZ, CPhase, etc.).
+//! * **Circuits (`onq::circuits`):** Provides `Circuit` to represent ordered sequences
+//!   of quantum operations and `CircuitBuilder` for easy construction.
+//! * **Validation (`onq::validation`):** Offers functions to check state validity
+//!   (normalization, phase coherence interpretation).
+//! * **ONQ Virtual Machine (`onq::vm`):** An interpreter (`OnqVm`) that executes
+//!   `Program`s containing mixed sequences of `Instruction`s (quantum ops, classical ops,
+//!   control flow based on stabilization results).
+//! * **Simulation Engine (`onq::simulation::engine` - internal):** Handles the underlying
+//!   state vector evolution and stabilization logic.
+//!
+//! ## Interpretation & Differences from QM
+//!
+//! Users should be aware that `onq` simulation relies heavily on **interpretations**
+//! of the abstract and sometimes mathematically ambiguous framework.
+//! Key differences from standard Quantum Mechanics include:
+//!
+//! * **Stabilization vs Measurement:** `Stabilize` is deterministic (seeded by state hash),
+//!   uses scoring (interpreting Phase Coherence and Pattern Resonance),
+//!   and resolves potentiality based on framework rules, not probabilistic collapse.
+//! * **Locking:** `RelationalLock` uses non-unitary projection to model state integration.
+//! * **Operations:** Gate availability and behavior are strictly based on derivations.
+//!
+//! **See the project README for detailed explanations of concepts, interpretations, and limitations.**
+
 
 pub mod core;
 pub mod operations;

src/operations/mod.rs

@@ -88,13 +88,15 @@ pub enum Operation {
     ///
     /// Analogy: Could be analogous to operations creating/breaking entanglement or
     /// enforcing phase coherence, but details depend on derivation.
-    /// **Placeholder Name:** Needs better grounding.
     RelationalLock {
+        /// The first QDU involved in the lock.
         qdu1: QduId,
+        /// The second QDU involved in the lock.
         qdu2: QduId,
         /// The target integrated/entangled state type for the lock.
         lock_type: LockType,
-        establish: bool, // If true, project onto lock state; if false, currently no-op.
+        /// If true, project onto lock state; if false, currently no-op.
+        establish: bool,
     },
 
     /// Represents the Stabilization Protocol (SP).
@@ -123,8 +125,29 @@ pub enum Operation {
 
 impl Operation {
     /// Returns a list of all QDU IDs directly mentioned in the operation's parameters.
-    /// This helps the simulator identify potentially affected states, although interactions
-    /// might implicitly affect other connected QDUs within the same frame.
+    ///
+    /// This helps identify which parts of the state vector might be affected by an operation,
+    /// although the actual effect (especially for multi-QDU gates) modifies the global state.
+    ///
+    /// # Examples
+    /// ```
+    /// # use onq::{Operation, QduId, LockType};
+    /// let q0 = QduId(0);
+    /// let q1 = QduId(1);
+    /// let op_h = Operation::InteractionPattern { target: q0, pattern_id: "H".to_string() };
+    /// let op_cx = Operation::ControlledInteraction { control: q0, target: q1, pattern_id: "X".to_string() };
+    /// let op_lock = Operation::RelationalLock { qdu1: q0, qdu2: q1, lock_type: LockType::BellPhiPlus, establish: true };
+    /// let op_stab = Operation::Stabilize { targets: vec![q0, q1] };
+    ///
+    /// assert_eq!(op_h.involved_qdus(), vec![q0]);
+    /// // Note: Order might not be guaranteed depending on internal representation if changed from vec!
+    /// let mut cx_qdus = op_cx.involved_qdus(); cx_qdus.sort();
+    /// assert_eq!(cx_qdus, vec![q0, q1]);
+    /// let mut lock_qdus = op_lock.involved_qdus(); lock_qdus.sort();
+    /// assert_eq!(lock_qdus, vec![q0, q1]);
+    /// let mut stab_qdus = op_stab.involved_qdus(); stab_qdus.sort();
+    /// assert_eq!(stab_qdus, vec![q0, q1]);
+    /// ```
     pub fn involved_qdus(&self) -> Vec<QduId> {
         match self {
             Operation::PhaseShift { target, .. } => vec![*target],