API Reference - Bloch Sphere

Detailed API reference for Bloch sphere visualization.

quantumpytho.modules.bloch_ascii

Functions

run_bloch_ascii

from quantumpytho.modules.bloch_ascii import run_bloch_ascii

run_bloch_ascii(
    theta: float,
    phi: float,
    shots: int = 1024
) -> None

Visualizes a quantum state on the Bloch sphere using ASCII art.

Parameters:

theta (float) - Polar angle in radians [0, π]
phi (float) - Azimuthal angle in radians [0, 2π]
shots (int, optional) - Number of measurement shots. Default: 1024

Returns:

None (prints to stdout)

Example:

from quantumpytho.modules.bloch_ascii import run_bloch_ascii

# Visualize |+⟩ state
run_bloch_ascii(theta=1.571, phi=0)

# Visualize |i+⟩ state
run_bloch_ascii(theta=1.571, phi=1.571)

Output:

State Vector Projection (θ=1.571000, φ=0.000000):
Statevector([ 0.707+0.j,  0.707+0.j], dims=(2,))
|0> state: [###########--------]   50.00% (512 shots)
|1> state: [###########--------]   50.00% (512 shots)

Theory

Any single-qubit pure state can be represented as:

$$|\psi\rangle = \cos(\theta/2)|0\rangle + e^{i\phi}\sin(\theta/2)|1\rangle$$

where: - $\theta \in [0, \pi]$ is the polar angle - $\phi \in [0, 2\pi]$ is the azimuthal angle

Common States

State	θ	φ	Description
\|0⟩	0	0	Ground state
\|1⟩	π	0	Excited state
\|+⟩	π/2	0	Equal superposition
\|−⟩	π/2	π	Equal superposition with phase
\|i+⟩	π/2	π/2	Equal superposition with imaginary phase
\|i−⟩	π/2	3π/2	Equal superposition with negative imaginary phase