refactor: Add error handling and API encapsulation

[zazabap]

Major refactoring to make the library more modular and professional:

• Add comprehensive error handling module (src/error.rs) using thiserror
• Encapsulate struct fields (State, Circuit, Operation) with public getters
• Replace Rc with Arc for thread-safe shared ownership
• Update all methods to return Result<T, LogosQError> for proper error handling
• Fix all tests to use new API (getters, Result handling)
• Fix all examples to use new API and handle Results
• Fix doctest in MatrixGate documentation
• Remove all compilation warnings

Changes:

• State: vector and num_qubits fields now private with getters
• Circuit: operations, num_qubits, name fields now private with getters
• Operation: gate, qubits, name fields now private with getters
• All circuit operations now return Result types
• All state operations now return Result types
• Updated 44 files with 1957 insertions and 649 deletions

All tests pass (131 tests) and all doctests pass (17 tests). All examples compile without warnings.

---

Note

Refactors core APIs to return Result with structured errors, encapsulates internals with getters, switches to Arc, and updates all modules/examples/tests for the new error- and feature-gated parallel API.

• API & Errors (breaking):
  • Introduce src/error.rs with LogosQError and crate-wide Result<T>.
  • Change core methods (e.g., Circuit::add_operation, execute, execute_and_measure, expectation, State::measure_qubit) to return Result.
  • Encapsulate fields in State, Circuit, and Operation; add getters (num_qubits(), operations(), name(), vector(), etc.).
  • Replace Rc with Arc for gates/noise models; adjust trait bounds for thread safety.
• Concurrency & Features:
  • Make parallelism opt-in via parallel feature; conditionally use Rayon for state ops and measurements.
  • Update QFT/algorithms/noise to use new accessors and in-place mutations.
• Modules Updated:
  • Circuits/gates/states/noise/algorithms/vis/optimization adapted to new API (getters, Result, Arc).
  • Prelude re-exports now include LogosQError and Result.
• Examples & Tests:
  • Update all examples and tests to use getters and handle Result (unwrap()), plus a new examples/gradient_bugs.rs.
• Packaging:
  • Bump version to 0.2.1; add thiserror, rand, rayon (optional), approx, plotters, rustfft; update README install snippet.

^{Written by Cursor Bugbot for commit 6746d87. This will update automatically on new commits. Configure here.}