cqlib_core/visualization/state/mod.rs
1// This code is part of Cqlib.
2//
3// (C) Copyright China Telecom Quantum Group 2026
4//
5// This code is licensed under the Apache License, Version 2.0. You may
6// obtain a copy of this license in the LICENSE.txt file in the root directory
7// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
8//
9// Any modifications or derivative works of this code must retain this
10// copyright notice, and modified files need to carry a notice indicating
11// that they have been altered from the originals.
12
13//! SVG-first quantum-state visualization.
14//!
15//! This module provides plotting routines for pure and mixed quantum states:
16//!
17//! - [`plot_bloch_vector`]: render one Bloch vector
18//! - [`plot_bloch_multivector`]: render one reduced Bloch vector per qubit
19//! - [`plot_state_city`]: render real/imaginary density-matrix components
20//! - [`plot_state_paulivec`]: render Pauli-basis expectation values
21//!
22//! # Module Structure
23//!
24//! - [`StateVisualizationSource`]: adapter trait for core QIS state types
25//! - [`StatePlotOptions`]: styling and layout options
26//! - [`state_to_density_matrix`]: normalize QIS states into density matrices
27//! - [`local_bloch_vectors`]: compute reduced single-qubit Bloch vectors
28//!
29//! # Examples
30//!
31//! ```rust
32//! use cqlib_core::qis::Statevector;
33//! use cqlib_core::visualization::{StatePlotOptions, plot_bloch_multivector};
34//! use num_complex::Complex64;
35//!
36//! let state = Statevector::from_state(
37//! 1,
38//! vec![
39//! Complex64::new(1.0 / 2.0_f64.sqrt(), 0.0),
40//! Complex64::new(1.0 / 2.0_f64.sqrt(), 0.0),
41//! ],
42//! ).unwrap();
43//! let svg = plot_bloch_multivector(&state, &StatePlotOptions::default()).unwrap();
44//! assert!(svg.contains("<svg"));
45//! ```
46
47mod data;
48mod math;
49mod options;
50mod plot;
51
52pub use data::{StateVisualizationSource, state_to_density_matrix};
53pub use math::local_bloch_vectors;
54pub use options::StatePlotOptions;
55pub use plot::{
56 plot_bloch_multivector, plot_bloch_vector, plot_state_city, plot_state_paulivec,
57 render_state_plot_to_file,
58};
59
60#[cfg(test)]
61#[path = "data_test.rs"]
62mod data_test;
63
64#[cfg(test)]
65#[path = "math_test.rs"]
66mod math_test;
67
68#[cfg(test)]
69#[path = "options_test.rs"]
70mod options_test;
71
72#[cfg(test)]
73#[path = "plot_test.rs"]
74mod plot_test;