Initial upload of source code

README.md

@@ -1,14 +1,13 @@
 ---
-title: AlphaQuantDemo V2
-emoji: 🐠
-colorFrom: pink
-colorTo: purple
+title: AlphaQuantDemo
+emoji: 👀
+colorFrom: red
+colorTo: gray
 sdk: gradio
-sdk_version: 5.34.0
-app_file: app.py
 pinned: false
-license: mit
-short_description: Duplicate of Original alphaQuantDemo
+license: apache-2.0
+short_description: testing platforms to build a quantum computing demo
+sdk_version: 5.32.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,603 @@
+import os
+import math
+import tempfile
+import gradio as gr
+
+import cudaq
+import numpy as np
+import cupy as cp
+
+from pathlib import Path
+
+# --- Plotly Imports ---
+import plotly.graph_objects as go
+import plotly.io as pio
+import imageio # For compiling GIF from frames
+
+# Set a default Plotly engine for image export
+try:
+    pio.kaleido.scope.mathjax = None # Can speed up Kaleido if MathJax not needed
+except AttributeError:
+    pass
+
+
+def simulate_qlbm_and_animate(num_reg_qubits: int, T: int, distribution_type: str, ux_input: float, uy_input: float):
+    """
+    Simulates a 2D advection-diffusion problem using a Quantum Lattice Boltzmann Method (QLBM)
+    and generates a GIF animation of the simulation's evolution using Plotly.
+    """
+
+    video_length = T
+    simulation_fps = 0.1
+    frames = int(simulation_fps * video_length)
+    if frames == 0:
+        frames = 1
+
+    num_anc = 3
+    num_qubits_total = 2 * num_reg_qubits + num_anc
+    current_N = 2**num_reg_qubits
+    N_tot_state_vector = 2**num_qubits_total
+    num_ranks = 1
+    rank = 0
+    N_sub_per_rank = int(N_tot_state_vector // num_ranks)
+
+    timesteps_per_frame = 1
+    if frames < T and frames > 0:
+        timesteps_per_frame = int(T / frames)
+    if timesteps_per_frame == 0:
+        timesteps_per_frame = 1
+
+    if distribution_type == "Sine Wave (Original)":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.sin(x * 2 * np.pi / N_val_func) * (1 - 0.5 * x / N_val_func) * \
+            np.sin(y * 4 * np.pi / N_val_func) * (1 - 0.5 * y / N_val_func) + 1
+    elif distribution_type == "Gaussian":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.exp(-((x - N_val_func / 2)**2 / (2 * (N_val_func / 5)**2) +
+                     (y - N_val_func / 2)**2 / (2 * (N_val_func / 5)**2))) * 1.8 + 0.2
+    elif distribution_type == "Random":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.random.rand(N_val_func, N_val_func) * 1.5 + 0.2 if isinstance(x, int) else \
+            np.random.rand(x.shape[0], x.shape[1]) * 1.5 + 0.2
+    else:
+        print(f"Warning: Unknown distribution type '{distribution_type}'. Defaulting to Sine Wave.")
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.sin(x * 2 * np.pi / N_val_func) * (1 - 0.5 * x / N_val_func) * \
+            np.sin(y * 4 * np.pi / N_val_func) * (1 - 0.5 * y / N_val_func) + 1
+
+    initial_state_func_eval = lambda x_coords, y_coords: \
+        selected_initial_state_function_raw(x_coords, y_coords, current_N) * \
+        (y_coords < current_N).astype(int)
+
+    with tempfile.TemporaryDirectory() as tmp_npy_dir:
+        intermediate_folder_path = Path(tmp_npy_dir)
+
+        cudaq.set_target('nvidia', option='fp64')
+
+        @cudaq.kernel
+        def alloc_kernel(num_qubits_alloc: int):
+            qubits = cudaq.qvector(num_qubits_alloc)
+
+        from cupy.cuda.memory import MemoryPointer, UnownedMemory
+
+        def to_cupy_array(state):
+            tensor = state.getTensor()
+            pDevice = tensor.data()
+            sizeByte = tensor.get_num_elements() * tensor.get_element_size()
+            mem = UnownedMemory(pDevice, sizeByte, owner=state)
+            memptr_obj = MemoryPointer(mem, 0)
+            cupy_array_val = cp.ndarray(tensor.get_num_elements(),
+                                    dtype=cp.complex128,
+                                    memptr=memptr_obj)
+            return cupy_array_val
+
+        class QLBMAdvecDiffD2Q5_new:
+            def __init__(self, ux=0.2, uy=0.15) -> None:
+                self.dim = 2
+                self.ndir = 5
+                self.nq_dir = math.ceil(np.log2(self.ndir))
+                self.dirs = []
+                for dir_int in range(self.ndir):
+                    dir_bin = f"{dir_int:b}".zfill(self.nq_dir)
+                    self.dirs.append(dir_bin)
+                self.e_unitvec = np.array([0, 1, -1, 1, -1])
+                self.wts = np.array([2/6, 1/6, 1/6, 1/6, 1/6])
+                self.cs = 1 / np.sqrt(3)
+                self.ux = ux
+                self.uy = uy
+                self.u = np.array([0, self.ux, self.ux, self.uy, self.uy])
+                self.wtcoeffs = np.multiply(self.wts, 1 + self.e_unitvec * self.u / self.cs**2)
+                self.create_circuit()
+
+            def create_circuit(self):
+                v = np.pad(self.wtcoeffs, (0, 2**num_anc - self.ndir))
+                v = v**0.5
+                v[0] += 1
+                v = v / np.linalg.norm(v)
+                U_prep = 2 * np.outer(v, v) - np.eye(len(v))
+                cudaq.register_operation("prep_op", U_prep)
+
+                def collisionOp(dirs_list):
+                    dirs_i_list_val = []
+                    for dir_str in dirs_list:
+                        dirs_i = [(int(c)) for c in dir_str]
+                        dirs_i_list_val += dirs_i[::-1]
+                    return dirs_i_list_val
+
+                self.dirs_i_list = collisionOp(self.dirs)
+
+                @cudaq.kernel
+                def rshift(q: cudaq.qview, n: int):
+                    for i in range(n):
+                        if i == n - 1:
+                            x(q[n - 1 - i])
+                        elif i == n - 2:
+                            x.ctrl(q[n - 1 - (i + 1)], q[n - 1 - i])
+                        else:
+                            x.ctrl(q[0:n - 1 - i], q[n - 1 - i])
+
+                @cudaq.kernel
+                def lshift(q: cudaq.qview, n: int):
+                    for i in range(n):
+                        if i == 0:
+                            x(q[0])
+                        elif i == 1:
+                            x.ctrl(q[0], q[1])
+                        else:
+                            x.ctrl(q[0:i], q[i])
+
+                @cudaq.kernel
+                def d2q5_tstep(q: cudaq.qview, nqx: int, nqy: int, nq_dir_val: int, dirs_i_val: list[int]):
+                    qx = q[0:nqx]
+                    qy = q[nqx:nqx + nqy]
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir_val]
+                    
+                    idx_lqx = 2
+                    b_list = dirs_i_val[idx_lqx * nq_dir_val:(idx_lqx + 1) * nq_dir_val]
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+                    cudaq.control(lshift, qdir, qx, nqx)
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+
+                    idx_rqx = 1
+                    b_list = dirs_i_val[idx_rqx * nq_dir_val:(idx_rqx + 1) * nq_dir_val]
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+                    cudaq.control(rshift, qdir, qx, nqx)
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+
+                    idx_lqy = 4
+                    b_list = dirs_i_val[idx_lqy * nq_dir_val:(idx_lqy + 1) * nq_dir_val]
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+                    cudaq.control(lshift, qdir, qy, nqy)
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+
+                    idx_rqy = 3
+                    b_list = dirs_i_val[idx_rqy * nq_dir_val:(idx_rqy + 1) * nq_dir_val]
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+                    cudaq.control(rshift, qdir, qy, nqy)
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+
+                @cudaq.kernel
+                def d2q5_tstep_wrapper(state_arg: cudaq.State, nqx: int, nqy: int, nq_dir_val: int, dirs_i_val: list[int]):
+                    q = cudaq.qvector(state_arg)
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir_val]
+                    prep_op(qdir[2], qdir[1], qdir[0]) # Assumes nq_dir_val is always 3
+                    d2q5_tstep(q, nqx, nqy, nq_dir_val, dirs_i_val)
+                    prep_op(qdir[2], qdir[1], qdir[0])
+
+                @cudaq.kernel
+                def d2q5_tstep_wrapper_hadamard(vec_arg: list[complex], nqx: int, nqy: int, nq_dir_val: int, dirs_i_val: list[int]):
+                    q = cudaq.qvector(vec_arg)
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir_val]
+                    qy = q[nqx:nqx + nqy]
+                    prep_op(qdir[2], qdir[1], qdir[0])
+                    d2q5_tstep(q, nqx, nqy, nq_dir_val, dirs_i_val)
+                    prep_op(qdir[2], qdir[1], qdir[0])
+                    for i in range(nqy):
+                        h(qy[i])
+
+                # MODIFIED run_timestep_func for memory optimization
+                def run_timestep_func(vec_arg, hadamard=False):
+                    if hadamard:
+                        result = cudaq.get_state(d2q5_tstep_wrapper_hadamard, vec_arg, num_reg_qubits, num_reg_qubits, self.nq_dir, self.dirs_i_list)
+                    else:
+                        result = cudaq.get_state(d2q5_tstep_wrapper, vec_arg, num_reg_qubits, num_reg_qubits, self.nq_dir, self.dirs_i_list)
+
+                    num_nonzero_ranks = num_ranks / (2**num_anc)
+                    rank_slice_cupy = to_cupy_array(result) # This is a cupy.ndarray view
+
+                    if rank >= num_nonzero_ranks and num_nonzero_ranks > 0:
+                        # This part of the original code implies multi-GPU/rank scenarios not fully active with num_ranks=1
+                        # For num_ranks=1, rank is 0, so this block isn't hit if num_nonzero_ranks > 0.
+                        # If num_nonzero_ranks is effectively 0 (e.g. 1/(2^3) < 1, which it is), this condition for rank=0 is also false.
+                        # The original logic: if rank >= num_nonzero_ranks: ...
+                        # If num_ranks=1, num_anc=3 -> num_nonzero_ranks = 1/8. rank=0 is not >= 1/8.
+                        # This block seems intended for ranks that should contain no data.
+                        # For now, keeping original logic path, but the optimization is for the other 'if' block.
+                        sub_sv_zeros = np.zeros(N_sub_per_rank, dtype=np.complex128)
+                        cp.cuda.runtime.memcpy(rank_slice_cupy.data.ptr, sub_sv_zeros.ctypes.data, sub_sv_zeros.nbytes, cp.cuda.runtime.memcpyHostToDevice)
+                    
+                    # OPTIMIZED BLOCK: Modify directly on GPU if conditions are met
+                    if rank == 0 and num_nonzero_ranks < 1 and N_sub_per_rank > 0:
+                        # num_nonzero_ranks = 1/8 < 1, so this condition is met for rank 0
+                        limit_idx = int(N_tot_state_vector / (2**num_anc))
+                        if limit_idx < rank_slice_cupy.size: 
+                            rank_slice_cupy[limit_idx:] = 0 # Modify directly on GPU using CuPy
+                        # No explicit memcpy back to GPU needed as rank_slice_cupy is the GPU array view.
+                    return result
+                self.run_timestep = run_timestep_func
+            # END OF MODIFIED run_timestep_func
+
+            def write_state(self, state_to_write, t_step_str_val):
+                rank_slice_cupy = to_cupy_array(state_to_write)
+                num_nonzero_ranks = num_ranks / (2**num_anc)
+
+                if rank < num_nonzero_ranks or (rank==0 and num_nonzero_ranks <=0):
+                    save_path = intermediate_folder_path / f"{t_step_str_val}_{rank}.npy"
+                    with open(save_path, 'wb') as f:
+                        arr_to_save = None
+                        data_limit = N_sub_per_rank
+                        if num_nonzero_ranks < 1 and rank == 0: # Only part of rank 0 has data
+                            data_limit = int(N_tot_state_vector / (2**num_anc))
+                        
+                        if data_limit > 0:
+                            relevant_part_cupy = cp.real(rank_slice_cupy[:data_limit])
+                        else:
+                            relevant_part_cupy = cp.array([], dtype=cp.float64)
+
+                        if relevant_part_cupy.size >= current_N * current_N: # Enough data for full grid
+                            arr_flat = relevant_part_cupy[:current_N * current_N]
+                            # CORRECTED CONDITION: Removed reference to downsampled_N
+                            if downsampling_factor > 1 and current_N > 0: 
+                                arr_reshaped = arr_flat.reshape((current_N, current_N))
+                                arr_downsampled = arr_reshaped[::downsampling_factor, ::downsampling_factor]
+                                arr_to_save = arr_downsampled.flatten()
+                            else: # No downsampling or conditions not met for it
+                                arr_to_save = arr_flat
+                        elif relevant_part_cupy.size > 0 : # Partial data
+                            if downsampling_factor > 1:
+                                arr_to_save = relevant_part_cupy[::downsampling_factor]
+                            else:
+                                arr_to_save = relevant_part_cupy
+                        
+                        if arr_to_save is not None and arr_to_save.size > 0:
+                            np.save(f, arr_to_save.get() if isinstance(arr_to_save, cp.ndarray) else arr_to_save)
+
+            def run_evolution(self, initial_state_arg, total_timesteps, observable=False):
+                current_state_val = initial_state_arg
+                for t_iter in range(total_timesteps):
+                    next_state_val = None
+                    if t_iter == total_timesteps - 1 and observable:
+                        next_state_val = self.run_timestep(current_state_val, True)
+                        self.write_state(next_state_val, str(t_iter + 1) + "_h")
+                    else:
+                        next_state_val = self.run_timestep(current_state_val)
+                        if (t_iter + 1) % timesteps_per_frame == 0:
+                            self.write_state(next_state_val, str(t_iter + 1))
+                            if rank == 0:
+                                print(f"Timestep: {t_iter + 1}/{total_timesteps}")
+
+                    cp.get_default_memory_pool().free_all_blocks()
+                    current_state_val = next_state_val
+
+                last_saved_timestep_name = str(total_timesteps) if not observable else str(total_timesteps) + "_h"
+                final_state_file_path = intermediate_folder_path / f"{last_saved_timestep_name}_{rank}.npy"
+                final_T_state_file_path = intermediate_folder_path / f"{total_timesteps}_{rank}.npy"
+
+                needs_final_save = True
+                if observable and final_state_file_path.exists():
+                    needs_final_save = False
+                elif not observable and final_T_state_file_path.exists() and total_timesteps > 0 and total_timesteps % timesteps_per_frame == 0 :
+                     needs_final_save = False
+                elif not observable and final_T_state_file_path.exists():
+                     needs_final_save = False
+                
+                if needs_final_save and total_timesteps > 0 :
+                    if not observable:
+                         self.write_state(current_state_val, str(total_timesteps))
+                elif total_timesteps == 0 and current_state_val is not None:
+                    self.write_state(current_state_val, "0")
+
+                if rank == 0:
+                    print(f"Timestep: {total_timesteps}/{total_timesteps} (Evolution complete)")
+                cp.get_default_memory_pool().free_all_blocks()
+                self.final_state = current_state_val
+        # --- END OF QLBM CLASS ---
+
+        downsampling_factor = 2**5
+        if current_N == 0:
+            print("Error: current_N is zero. num_reg_qubits likely too small.")
+            return None
+        if current_N < downsampling_factor:
+            downsampling_factor = current_N if current_N > 0 else 1
+
+        qlbm_obj = QLBMAdvecDiffD2Q5_new(ux=ux_input, uy=uy_input)
+        initial_state_val = cudaq.get_state(alloc_kernel, num_qubits_total)
+        
+        xv_init = np.arange(current_N)
+        yv_init = np.arange(current_N)
+        initial_grid_2d_X, initial_grid_2d_Y = np.meshgrid(xv_init, yv_init)
+
+        if distribution_type == "Random":
+            initial_grid_2d = selected_initial_state_function_raw(current_N, current_N, current_N) # Pass N for shape
+        else:
+            initial_grid_2d = initial_state_func_eval(initial_grid_2d_X, initial_grid_2d_Y)
+
+        sub_sv_init_flat = initial_grid_2d.flatten().astype(np.complex128)
+        full_initial_sv_host = np.zeros(N_sub_per_rank, dtype=np.complex128)
+        num_computational_states = current_N * current_N
+
+        if len(sub_sv_init_flat) == num_computational_states:
+            if num_computational_states <= N_sub_per_rank:
+                full_initial_sv_host[:num_computational_states] = sub_sv_init_flat
+            else:
+                print(f"Error: Grid data {num_computational_states} > N_sub_per_rank {N_sub_per_rank}")
+                return None
+        else:
+            print(f"Warning: Initial state size {len(sub_sv_init_flat)} != expected {num_computational_states}")
+            fill_len = min(len(sub_sv_init_flat), num_computational_states, N_sub_per_rank)
+            full_initial_sv_host[:fill_len] = sub_sv_init_flat[:fill_len]
+        
+        rank_slice_init = to_cupy_array(initial_state_val)
+        print(f'Rank {rank}: Initializing state with {distribution_type} (ux={ux_input}, uy={uy_input})...')
+        cp.cuda.runtime.memcpy(rank_slice_init.data.ptr, full_initial_sv_host.ctypes.data, full_initial_sv_host.nbytes, cp.cuda.runtime.memcpyHostToDevice)
+        print(f'Rank {rank}: Initial state copied. Size: {len(sub_sv_init_flat)}. N_sub_per_rank: {N_sub_per_rank}')
+
+        print("Starting QLBM evolution...")
+        qlbm_obj.run_evolution(initial_state_val, T)
+        print("QLBM evolution complete.")
+
+        print("Generating animation with Plotly...")
+        downsampled_N = current_N // downsampling_factor
+        if downsampled_N == 0 and current_N > 0:
+            downsampled_N = 1
+        elif current_N == 0:
+            print("Error: current_N is zero before Plotly stage.")
+            return None
+
+        plotted_timesteps_str = []
+        if T == 0:
+            if (intermediate_folder_path / f"0_{rank}.npy").exists():
+                plotted_timesteps_str.append("0")
+        else:
+            if timesteps_per_frame > 0:
+                for t_step_val in range(timesteps_per_frame, T + 1, timesteps_per_frame):
+                    if intermediate_folder_path.joinpath(f"{t_step_val}_{rank}.npy").exists():
+                        plotted_timesteps_str.append(str(t_step_val))
+            final_T_path = intermediate_folder_path.joinpath(f"{T}_{rank}.npy")
+            if final_T_path.exists() and str(T) not in plotted_timesteps_str:
+                plotted_timesteps_str.append(str(T))
+        
+        plotted_timesteps_str = sorted(list(set(plotted_timesteps_str)), key=lambda k_str: int(k_str))
+
+        if not plotted_timesteps_str :
+             print(f"Warning: No .npy files found for plotting T={T}. Animation may fail.")
+             return None
+
+        data_frames_list = []
+        actual_timesteps_for_title = []
+        for i_str_val in plotted_timesteps_str:
+            try:
+                file_path_load = intermediate_folder_path / f"{i_str_val}_{rank}.npy"
+                sol_loaded = np.load(file_path_load)
+                if sol_loaded.size == downsampled_N * downsampled_N:
+                    Z_data = np.reshape(sol_loaded, (downsampled_N, downsampled_N))
+                    data_frames_list.append(Z_data)
+                    actual_timesteps_for_title.append(i_str_val)
+                else:
+                    print(f"Warning: File {file_path_load} size {sol_loaded.size} != expected {downsampled_N*downsampled_N}. Skipping.")
+                    continue
+            except FileNotFoundError:
+                print(f"Warning: File {file_path_load} not found. Skipping.")
+                continue
+            except Exception as e_load:
+                print(f"Error loading/reshaping {file_path_load}: {e_load}. Skipping.")
+                continue
+
+        if not data_frames_list:
+            print("Error: No data frames loaded. Cannot create animation.")
+            return None
+
+        x_coords_plot = np.linspace(-10, 10, downsampled_N)
+        y_coords_plot = np.linspace(-10, 10, downsampled_N)
+
+        norm_factor_plotly = np.max(np.abs(data_frames_list[0])) if data_frames_list[0].size > 0 and np.max(np.abs(data_frames_list[0])) != 0 else 1.0
+        if norm_factor_plotly == 0: norm_factor_plotly = 1.0
+
+        all_data_max_val = norm_factor_plotly
+        if len(data_frames_list) > 0: # Should always be true if we reached here
+            max_vals_frames = [np.max(np.abs(d_frame)) for d_frame in data_frames_list if d_frame.size > 0]
+            if max_vals_frames:
+                global_max_val_frames = max(max_vals_frames)
+                if global_max_val_frames > 0 : all_data_max_val = global_max_val_frames
+        
+        clim_upper_plotly = (all_data_max_val / norm_factor_plotly) * 1.0
+        if clim_upper_plotly == 0 : clim_upper_plotly = 0.6
+
+        results_base_dir = "Results"
+        gif_frames_for_naming = int(simulation_fps * T)
+        if gif_frames_for_naming == 0: gif_frames_for_naming = 1
+        dist_name_part = distribution_type.replace(' ','').replace('(Original)','').replace('(','').replace(')','')
+        specific_folder_name = (f"d2q5_plotly_N{current_N}_T{T}_fr{gif_frames_for_naming}_"
+                                f"dist{dist_name_part}_ux{ux_input:.2f}_uy{uy_input:.2f}")
+        final_output_dir = Path(results_base_dir) / specific_folder_name
+        os.makedirs(final_output_dir, exist_ok=True)
+        gif_path_to_return = final_output_dir / "animation_plotly.gif"
+
+        Z_initial_placeholder = np.zeros((downsampled_N, downsampled_N))
+        fig = go.Figure(data=[go.Surface(
+                                z=Z_initial_placeholder, x=x_coords_plot, y=y_coords_plot,
+                                colorscale='Viridis', cmin=0, cmax=clim_upper_plotly,
+                                colorbar=dict(
+                                    title=dict(text='Density', side='right', font=dict(color='white')),
+                                    tickfont=dict(size=10, color='white'),
+                                    bgcolor='rgba(0,0,0,0.4)', bordercolor='gray', outlinewidth=1,
+                                    thickness=20, len=0.8, x=0.85, y=0.5
+                                ))])
+        
+        fig.update_layout(
+            paper_bgcolor='black', plot_bgcolor='black', font=dict(color='white'),
+            scene=dict(
+                bgcolor='black',
+                xaxis=dict(title=dict(text='X Axis', font=dict(color='white')), 
+                           tickfont=dict(color='white'),
+                           gridcolor='rgba(128,128,128,0.3)', zerolinecolor='rgba(128,128,128,0.5)',
+                           linecolor='rgba(128,128,128,0.5)'),
+                yaxis=dict(title=dict(text='Y Axis', font=dict(color='white')), 
+                           tickfont=dict(color='white'),
+                           gridcolor='rgba(128,128,128,0.3)', zerolinecolor='rgba(128,128,128,0.5)',
+                           linecolor='rgba(128,128,128,0.5)'),
+                zaxis=dict(title=dict(text='Density', font=dict(color='white')), 
+                           tickfont=dict(color='white'),
+                           range=[0, clim_upper_plotly], gridcolor='rgba(128,128,128,0.3)',
+                           zerolinecolor='rgba(128,128,128,0.5)', linecolor='rgba(128,128,128,0.5)'),
+                aspectratio=dict(x=1, y=1, z=0.7),
+                camera=dict(eye=dict(x=1.5, y=1.5, z=1.0), center=dict(x=0, y=0, z=-0.1), up=dict(x=0,y=0,z=1))
+            ),
+            margin=dict(l=10, r=10, b=10, t=60), width=800, height=700
+        )
+
+        temp_image_files = []
+        gif_fps_val = 10
+
+        try:
+            for k, Z_frame_data in enumerate(data_frames_list):
+                Z_plotly_frame = Z_frame_data / norm_factor_plotly
+                fig.data[0].z = Z_plotly_frame
+                current_ts_title = actual_timesteps_for_title[k] if k < len(actual_timesteps_for_title) else "Unknown"
+                fig.update_layout(
+                    title_text=f'QLBM Simulation (Plotly) - Timestep: {current_ts_title}',
+                    title_x=0.5, title_font_size=16
+                )
+                temp_image_path = intermediate_folder_path / f"plotly_frame_{k:04d}.png"
+                fig.write_image(str(temp_image_path), engine="kaleido")
+                temp_image_files.append(str(temp_image_path))
+
+            if not temp_image_files:
+                print("Error: No Plotly frames were successfully generated.")
+                # Cleanup potentially created empty directory
+                if not any(final_output_dir.iterdir()): # Check if directory is empty
+                    try:
+                        os.rmdir(final_output_dir)
+                    except OSError:
+                        pass # Ignore if it fails (e.g. not empty for other reasons)
+                return None
+            
+            with imageio.get_writer(str(gif_path_to_return), mode='I', fps=gif_fps_val, loop=0) as writer:
+                for filename in temp_image_files:
+                    image = imageio.imread(filename)
+                    writer.append_data(image)
+            
+            print(f"Plotly animation saved to {gif_path_to_return}")
+
+        except Exception as e_plotly_anim:
+            print(f"Error during Plotly animation/saving: {e_plotly_anim}")
+            print("Ensure 'kaleido' and 'imageio' are installed ('pip install kaleido imageio').")
+            return None
+        
+        return str(gif_path_to_return)
+
+# --- Gradio Interface Definition ---
+def qlbm_gradio_interface(num_reg_qubits_input: int, timescale_input: int, distribution_type_param: str, ux_param: float, uy_param: float):
+    num_reg_qubits_val = int(num_reg_qubits_input)
+    timescale_val = int(timescale_input)
+    ux_val = float(ux_param)
+    uy_val = float(uy_param)
+
+    print(f"Gradio Interface: num_reg_qubits={num_reg_qubits_val}, T={timescale_val}, Distribution={distribution_type_param}, ux={ux_val}, uy={uy_val}")
+
+    gif_path_output = simulate_qlbm_and_animate(
+        num_reg_qubits=num_reg_qubits_val,
+        T=timescale_val,
+        distribution_type=distribution_type_param,
+        ux_input=ux_val,
+        uy_input=uy_val
+    )
+
+    if gif_path_output is None:
+        gr.Warning("Animation generation failed. Please check console for errors.")
+        return None
+    return gif_path_output
+
+with gr.Blocks(theme=gr.themes.Soft(), title="QLBM Simulation with Plotly") as qlbm_demo:
+    gr.Markdown(
+    """
+    # ⚛️ Quantum Lattice Boltzmann Method (QLBM) Simulator (Plotly Animation)
+    Welcome to the Quantum Lattice Boltzmann Method (QLBM) simulator! This version uses Plotly for 3D animation.
+    
+    **How this Simulator Works:**
+    This simulator implements a D2Q5 model on a quantum computer simulator (CUDA-Q).
+    - Control grid size (via Number of Register Qubits: $N=2^{\text{num_reg_qubits}}$).
+    - Set total simulation time (Timescale T).
+    - Choose initial distribution.
+    - Set advection velocities `ux` and `uy`.
+    The simulation evolves this state, and a Plotly animation of the density is generated as a GIF.
+
+    **Note:** Higher qubit counts and longer timescales are computationally intensive. Advection velocities should be small (e.g., < 0.3).
+    The output GIF will loop indefinitely. Values for "Number of Register Qubits" above 9 may be unstable or very slow on shared/limited hardware.
+    """
+    )
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown("## Simulation Parameters")
+            num_reg_qubits_slider = gr.Slider(
+                minimum=2, maximum=10, value=8, step=1, # Max set to 10
+                label="Number of Register Qubits (num_reg_qubits)",
+                info="Grid N = 2^num_reg_qubits. Max 10 (Note: >8 slow; >9 may hit simulator/memory limits on free tiers)."
+            )
+            timescale_slider = gr.Slider(
+                minimum=0, maximum=2000, value=100, step=10,
+                label="Timescale (T)", info="Total number of timesteps. Max 2000."
+            )
+            distribution_options = ["Sine Wave (Original)", "Gaussian", "Random"]
+            distribution_type_input = gr.Radio(
+                choices=distribution_options, value="Sine Wave (Original)",
+                label="Initial Distribution Type", info="Select the initial pattern of the substance."
+            )
+            ux_slider = gr.Slider(
+                minimum=-0.4, maximum=0.4, value=0.2, step=0.01,
+                label="Advection Velocity ux", info="x-component of background advection."
+            )
+            uy_slider = gr.Slider(
+                minimum=-0.4, maximum=0.4, value=0.15, step=0.01,
+                label="Advection Velocity uy", info="y-component of background advection."
+            )
+            run_qlbm_btn = gr.Button("Run QLBM Simulation (Plotly)", variant="primary")
+
+        with gr.Column(scale=2):
+            qlbm_plot_output = gr.Image(label="QLBM Simulation Animation (Plotly GIF)", type="filepath", height=600)
+
+    qlbm_inputs_list = [num_reg_qubits_slider, timescale_slider, distribution_type_input, ux_slider, uy_slider]
+    run_qlbm_btn.click(
+        fn=qlbm_gradio_interface,
+        inputs=qlbm_inputs_list,
+        outputs=qlbm_plot_output
+    )
+    gr.Examples(
+        examples=[
+            [8, 100, "Sine Wave (Original)", 0.2, 0.15],
+            [6, 50, "Gaussian", 0.1, 0.05],
+            [4, 30, "Random", -0.05, 0.1],
+        ],
+        inputs=qlbm_inputs_list,
+        outputs=qlbm_plot_output,
+        fn=qlbm_gradio_interface,
+        cache_examples=False
+    )
+
+if __name__ == "__main__":
+    try:
+        cudaq.set_target('nvidia', option='fp64')
+        print(f"CUDA-Q Target successfully set to: {cudaq.get_target().name}")
+    except Exception as e_target:
+        print(f"Warning: Could not set CUDA-Q target to 'nvidia'. Error: {e_target}")
+        print(f"Current CUDA-Q Target: {cudaq.get_target().name}. Performance may be affected.")
+    
+    qlbm_demo.launch()

app_o.py

@@ -0,0 +1,568 @@
+import os
+import sys
+import time
+import math
+import threading
+import tempfile
+import gradio as gr
+
+import cudaq
+import numpy as np
+import cupy as cp
+# from scipy import interpolate # Not used
+
+from pathlib import Path
+
+from matplotlib import pyplot as plt
+from matplotlib.animation import FuncAnimation
+
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+
+def simulate_qlbm_and_animate(num_reg_qubits: int, T: int, distribution_type: str, ux_input: float, uy_input: float):
+    """
+    Simulates a 2D advection-diffusion problem using a Quantum Lattice Boltzmann Method (QLBM)
+    and generates a GIF animation of the simulation's evolution.
+
+    Args:
+        num_reg_qubits (int): The number of register qubits (determines grid size N=2^num_reg_qubits).
+        T (int): The total number of timesteps to run the simulation.
+        distribution_type (str): The type of initial distribution to use.
+        ux_input (float): Advection velocity in the x-direction.
+        uy_input (float): Advection velocity in the y-direction.
+
+    Returns:
+        str: The file path to the generated GIF animation, or None if an error occurs.
+    """
+
+    video_length = T
+    simulation_fps = 0.1
+    frames = int(simulation_fps * video_length)
+    if frames == 0:
+        frames = 1
+
+    num_anc = 3
+    num_qubits_total = 2 * num_reg_qubits + num_anc
+    current_N = 2**num_reg_qubits
+    N_tot_state_vector = 2**num_qubits_total
+    num_ranks = 1
+    rank = 0
+    N_sub_per_rank = int(N_tot_state_vector // num_ranks)
+
+    timesteps_per_frame = 1
+    if frames < T and frames > 0:
+        timesteps_per_frame = int(T / frames)
+    if timesteps_per_frame == 0:
+        timesteps_per_frame = 1
+
+    if distribution_type == "Sine Wave (Original)":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.sin(x * 2 * np.pi / N_val_func) * (1 - 0.5 * x / N_val_func) * \
+            np.sin(y * 4 * np.pi / N_val_func) * (1 - 0.5 * y / N_val_func) + 1
+    elif distribution_type == "Gaussian":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.exp(-((x - N_val_func / 2)**2 / (2 * (N_val_func / 5)**2) +
+                     (y - N_val_func / 2)**2 / (2 * (N_val_func / 5)**2))) * 1.8 + 0.2
+    elif distribution_type == "Random":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.random.rand(x.shape[0], x.shape[1]) * 1.5 + 0.2
+    else:
+        print(f"Warning: Unknown distribution type '{distribution_type}'. Defaulting to Sine Wave.")
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.sin(x * 2 * np.pi / N_val_func) * (1 - 0.5 * x / N_val_func) * \
+            np.sin(y * 4 * np.pi / N_val_func) * (1 - 0.5 * y / N_val_func) + 1
+
+    initial_state_func_eval = lambda x_coords, y_coords: \
+        selected_initial_state_function_raw(x_coords, y_coords, current_N) * \
+        (y_coords < current_N).astype(int)
+
+
+    with tempfile.TemporaryDirectory() as tmp_npy_dir:
+        intermediate_folder_path = Path(tmp_npy_dir)
+
+        cudaq.set_target('nvidia', option='fp64')
+
+        @cudaq.kernel
+        def alloc_kernel(num_qubits_alloc: int):
+            qubits = cudaq.qvector(num_qubits_alloc)
+
+        from cupy.cuda.memory import MemoryPointer, UnownedMemory
+
+        def to_cupy_array(state):
+            tensor = state.getTensor()
+            pDevice = tensor.data()
+            sizeByte = tensor.get_num_elements() * tensor.get_element_size()
+            mem = UnownedMemory(pDevice, sizeByte, owner=state)
+            memptr_obj = MemoryPointer(mem, 0)
+            cupy_array = cp.ndarray(tensor.get_num_elements(),
+                                    dtype=cp.complex128,
+                                    memptr=memptr_obj)
+            return cupy_array
+
+        class QLBMAdvecDiffD2Q5_new:
+            def __init__(self, ux=0.2, uy=0.15) -> None: # ux, uy are now passed here
+                self.dim = 2
+                self.ndir = 5
+                self.nq_dir = math.ceil(np.log2(self.ndir))
+                self.dirs = []
+                for dir_int in range(self.ndir):
+                    dir_bin = f"{dir_int:b}".zfill(self.nq_dir)
+                    self.dirs.append(dir_bin)
+                self.e_unitvec = np.array([0, 1, -1, 1, -1])
+                self.wts = np.array([2/6, 1/6, 1/6, 1/6, 1/6])
+                self.cs = 1 / np.sqrt(3)
+                self.ux = ux # Use passed ux
+                self.uy = uy # Use passed uy
+                self.u = np.array([0, self.ux, self.ux, self.uy, self.uy])
+                self.wtcoeffs = np.multiply(self.wts, 1 + self.e_unitvec * self.u / self.cs**2)
+                self.create_circuit()
+
+            def create_circuit(self):
+                v = np.pad(self.wtcoeffs, (0, 2**num_anc - self.ndir))
+                v = v**0.5
+                v[0] += 1
+                v = v / np.linalg.norm(v)
+                U_prep = 2 * np.outer(v, v) - np.eye(len(v))
+                cudaq.register_operation("prep_op", U_prep)
+
+                def collisionOp(dirs):
+                    dirs_i_list = []
+                    for dir_ in dirs:
+                        dirs_i = [(int(c)) for c in dir_]
+                        dirs_i_list += dirs_i[::-1]
+                    return dirs_i_list
+
+                self.dirs_i_list = collisionOp(self.dirs)
+
+                @cudaq.kernel
+                def rshift(q: cudaq.qview, n: int):
+                    for i in range(n):
+                        if i == n - 1:
+                            x(q[n - 1 - i])
+                        elif i == n - 2:
+                            x.ctrl(q[n - 1 - (i + 1)], q[n - 1 - i])
+                        else:
+                            x.ctrl(q[0:n - 1 - i], q[n - 1 - i])
+
+                @cudaq.kernel
+                def lshift(q: cudaq.qview, n: int):
+                    for i in range(n):
+                        if i == 0:
+                            x(q[0])
+                        elif i == 1:
+                            x.ctrl(q[0], q[1])
+                        else:
+                            x.ctrl(q[0:i], q[i])
+
+                @cudaq.kernel
+                def d2q5_tstep(q: cudaq.qview, nqx: int, nqy: int, nq_dir: int, dirs_i: list[int]):
+                    qx = q[0:nqx]
+                    qy = q[nqx:nqx + nqy]
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir]
+                    i = 2
+                    b_list = dirs_i[i * nq_dir:(i + 1) * nq_dir]
+                    for j in range(nq_dir):
+                        b = b_list[j]
+                        if b == 0:
+                            x(qdir[j])
+                    cudaq.control(lshift, qdir, qx, nqx)
+                    for j in range(nq_dir):
+                        b = b_list[j]
+                        if b == 0:
+                            x(qdir[j])
+                    i = 1
+                    b_list = dirs_i[i * nq_dir:(i + 1) * nq_dir]
+                    for j in range(nq_dir):
+                        b = b_list[j]
+                        if b == 0:
+                            x(qdir[j])
+                    cudaq.control(rshift, qdir, qx, nqx)
+                    for j in range(nq_dir):
+                        b = b_list[j]
+                        if b == 0:
+                            x(qdir[j])
+                    i = 4
+                    b_list = dirs_i[i * nq_dir:(i + 1) * nq_dir]
+                    for j in range(nq_dir):
+                        b = b_list[j]
+                        if b == 0:
+                            x(qdir[j])
+                    cudaq.control(lshift, qdir, qy, nqy)
+                    for j in range(nq_dir):
+                        b = b_list[j]
+                        if b == 0:
+                            x(qdir[j])
+                    i = 3
+                    b_list = dirs_i[i * nq_dir:(i + 1) * nq_dir]
+                    for j in range(nq_dir):
+                        b = b_list[j]
+                        if b == 0:
+                            x(qdir[j])
+                    cudaq.control(rshift, qdir, qy, nqy)
+                    for j in range(nq_dir):
+                        b = b_list[j]
+                        if b == 0:
+                            x(qdir[j])
+
+                @cudaq.kernel
+                def d2q5_tstep_wrapper(state_arg: cudaq.State, nqx: int, nqy: int, nq_dir: int, dirs_i: list[int]):
+                    q = cudaq.qvector(state_arg)
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir]
+                    prep_op(qdir[2], qdir[1], qdir[0])
+                    d2q5_tstep(q, nqx, nqy, nq_dir, dirs_i)
+                    prep_op(qdir[2], qdir[1], qdir[0])
+
+                @cudaq.kernel
+                def d2q5_tstep_wrapper_hadamard(vec: list[complex], nqx: int, nqy: int, nq_dir: int, dirs_i: list[int]):
+                    q = cudaq.qvector(vec)
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir]
+                    qy = q[nqx:nqx + nqy]
+                    prep_op(qdir[2], qdir[1], qdir[0])
+                    d2q5_tstep(q, nqx, nqy, nq_dir, dirs_i)
+                    prep_op(qdir[2], qdir[1], qdir[0])
+                    for i in range(nqy):
+                        h(qy[i])
+
+                def run_timestep_func(vec, hadamard=False):
+                    if hadamard:
+                        result = cudaq.get_state(d2q5_tstep_wrapper_hadamard, vec, num_reg_qubits, num_reg_qubits, self.nq_dir, self.dirs_i_list)
+                    else:
+                        result = cudaq.get_state(d2q5_tstep_wrapper, vec, num_reg_qubits, num_reg_qubits, self.nq_dir, self.dirs_i_list)
+                    
+                    num_nonzero_ranks = num_ranks / (2**num_anc)
+                    rank_slice_cupy = to_cupy_array(result)
+                    
+                    if rank >= num_nonzero_ranks:
+                        sub_sv_zeros = np.zeros(N_sub_per_rank, dtype=np.complex128)
+                        cp.cuda.runtime.memcpy(rank_slice_cupy.data.ptr, sub_sv_zeros.ctypes.data, sub_sv_zeros.nbytes, cp.cuda.runtime.memcpyHostToDevice)
+                    
+                    if rank == 0 and num_nonzero_ranks < 1:
+                        sub_sv_get = (rank_slice_cupy).get()
+                        sub_sv_get[int(N_tot_state_vector / (2**num_anc)):] = 0
+                        cp.cuda.runtime.memcpy(rank_slice_cupy.data.ptr, sub_sv_get.ctypes.data, sub_sv_get.nbytes, cp.cuda.runtime.memcpyHostToDevice)
+                    return result
+
+                self.run_timestep = run_timestep_func
+
+            def write_state(self, state_to_write, t_step):
+                rank_slice_cupy = to_cupy_array(state_to_write)
+                num_nonzero_ranks = num_ranks / (2**num_anc)
+                
+                if rank < num_nonzero_ranks:
+                    save_path = intermediate_folder_path / f"{t_step}_{rank}.npy"
+                    with open(save_path, 'wb') as f:
+                        arr_to_save = None
+                        if num_nonzero_ranks < 1:
+                            arr_to_save = cp.real(rank_slice_cupy)[:int(N_tot_state_vector / (2**num_anc))]
+                        else:
+                            arr_to_save = cp.real(rank_slice_cupy)
+                        
+                        if len(arr_to_save) > current_N :
+                            arr_to_save=arr_to_save.reshape((current_N, current_N))
+                            arr_to_save=arr_to_save[::downsampling_factor,::downsampling_factor]
+                            arr_to_save=arr_to_save.flatten()
+                        elif len(arr_to_save) > 0 :
+                            arr_to_save=arr_to_save[::downsampling_factor]
+
+                        np.save(f, arr_to_save.get() if isinstance(arr_to_save, cp.ndarray) else arr_to_save)
+
+
+            def run_evolution(self, initial_state_arg, total_timesteps, observable=False):
+                current_state = initial_state_arg
+                for t_iter in range(total_timesteps):
+                    next_state = None
+                    if t_iter == total_timesteps - 1 and observable:
+                        next_state = self.run_timestep(current_state, True)
+                        self.write_state(next_state, str(t_iter + 1) + "_h")
+                    else:
+                        next_state = self.run_timestep(current_state)
+                        if (t_iter + 1) % timesteps_per_frame == 0:
+                            self.write_state(next_state, t_iter + 1)
+                            if rank == 0:
+                                print(f"Timestep: {t_iter + 1}/{total_timesteps}")
+                    
+                    cp.get_default_memory_pool().free_all_blocks()
+                    current_state = next_state
+                
+                last_saved_timestep_name = str(total_timesteps) if not observable else str(total_timesteps) + "_h"
+                # Check if the very last state (T or T_h) was potentially saved by the loop or observable condition.
+                # If not, save it.
+                final_state_file_path = intermediate_folder_path.joinpath(f"{last_saved_timestep_name}_{rank}.npy")
+                # Also check if the non-observable final T state was saved if T aligns with timesteps_per_frame
+                final_T_state_file_path = intermediate_folder_path.joinpath(f"{total_timesteps}_{rank}.npy")
+
+                needs_final_save = True
+                if observable and final_state_file_path.exists(): # T_h was saved
+                    needs_final_save = False
+                elif not observable and final_T_state_file_path.exists() and total_timesteps % timesteps_per_frame == 0 : # T was saved by loop
+                     needs_final_save = False
+                elif not observable and final_T_state_file_path.exists(): # T was saved by a previous final write
+                     needs_final_save = False
+
+
+                if needs_final_save and total_timesteps > 0:
+                    if not observable: # Save as T_0.npy
+                         self.write_state(current_state, total_timesteps)
+                    # If observable, it should have been saved as T_h. If it wasn't (e.g. T=0), this won't run.
+
+                if rank == 0:
+                    print(f"Timestep: {total_timesteps}/{total_timesteps} (Evolution complete)")
+                cp.get_default_memory_pool().free_all_blocks()
+                self.final_state = current_state
+
+        downsampling_factor = 2**5
+        # Pass ux_input and uy_input to the constructor
+        qlbm_obj = QLBMAdvecDiffD2Q5_new(ux=ux_input, uy=uy_input)
+
+        initial_state = cudaq.get_state(alloc_kernel, num_qubits_total)
+        rank_slice_init = to_cupy_array(initial_state)
+
+        xv_init = np.arange(current_N)
+        yv_init = np.arange(current_N)
+        
+        print(f'Start initializing state with {distribution_type} distribution (ux={ux_input}, uy={uy_input})...')
+        initial_grid_2d = initial_state_func_eval(*np.meshgrid(xv_init, yv_init))
+        sub_sv_init_flat = initial_grid_2d.flatten().astype(np.complex128)
+        
+        full_initial_sv_host = np.zeros(N_sub_per_rank, dtype=np.complex128)
+        num_computational_states = current_N * current_N
+        
+        if len(sub_sv_init_flat) == num_computational_states:
+            full_initial_sv_host[:num_computational_states] = sub_sv_init_flat
+        else:
+            print(f"Warning: Mismatch in expected initial state size {num_computational_states} and calculated {len(sub_sv_init_flat)}")
+            full_initial_sv_host[:len(sub_sv_init_flat)] = sub_sv_init_flat
+
+        print(f'Rank {rank}: Initial state (N*N part) prepared. Size: {len(sub_sv_init_flat)}. Total N_sub_per_rank: {N_sub_per_rank}')
+        cp.cuda.runtime.memcpy(rank_slice_init.data.ptr, full_initial_sv_host.ctypes.data, full_initial_sv_host.nbytes, cp.cuda.runtime.memcpyHostToDevice)
+        print(f'Rank {rank}: Initial state copied to device.')
+
+        print("Starting QLBM evolution...")
+        qlbm_obj.run_evolution(initial_state, T)
+        print("QLBM evolution complete.")
+
+        print("Generating animation...")
+        downsampled_N = current_N // downsampling_factor
+        if downsampled_N == 0:
+            print("Error: Downsampled grid size is zero. Check num_reg_qubits and downsampling_factor.")
+            downsampled_N = 1
+
+        plotted_timesteps_str = [] # To store frame names (can include '_h')
+        if timesteps_per_frame > 0:
+            # Add regular frames saved by the loop
+            for t_step in range(timesteps_per_frame, T + 1, timesteps_per_frame):
+                if intermediate_folder_path.joinpath(f"{t_step}_0.npy").exists():
+                    plotted_timesteps_str.append(str(t_step))
+        
+        # Ensure the very last timestep (T or T_h) is considered for plotting
+        final_T_path = intermediate_folder_path.joinpath(f"{T}_0.npy")
+        final_Th_path = intermediate_folder_path.joinpath(f"{T}_h_0.npy")
+
+        if T > 0:
+            if final_Th_path.exists(): # Prefer T_h if it exists
+                if str(T)+"_h" not in plotted_timesteps_str:
+                    plotted_timesteps_str.append(str(T)+"_h")
+            elif final_T_path.exists(): # Else, use T if it exists
+                 if str(T) not in plotted_timesteps_str:
+                    plotted_timesteps_str.append(str(T))
+        
+        # Remove duplicates and sort (handle numeric and '_h' strings appropriately for sorting if needed, though string sort is often fine here)
+        plotted_timesteps_str = sorted(list(set(plotted_timesteps_str)), key=lambda k: (int(str(k).replace('_h','')), str(k)))
+
+
+        if not plotted_timesteps_str and T > 0 : # Fallback if T is small and not caught by loop
+            if final_Th_path.exists(): plotted_timesteps_str = [str(T)+"_h"]
+            elif final_T_path.exists(): plotted_timesteps_str = [str(T)]
+        elif not plotted_timesteps_str and T == 0:
+             print("Warning: T=0, no frames to plot for animation.")
+             return None
+
+        data = []
+        actual_timesteps_for_title = [] 
+
+        for i_str in plotted_timesteps_str:
+            try:
+                file_path = intermediate_folder_path / f"{i_str}_0.npy"
+                sol = np.load(file_path)
+                if sol.size == downsampled_N * downsampled_N:
+                    Z = np.reshape(sol, (downsampled_N, downsampled_N))
+                    data.append(Z)
+                    actual_timesteps_for_title.append(str(i_str).replace('_h',''))
+                else:
+                    print(f"Warning: File {file_path} has unexpected size {sol.size}. Expected {downsampled_N*downsampled_N}. Skipping this frame.")
+                    continue
+            except FileNotFoundError:
+                print(f"Warning: File not found for timestep {i_str} ({file_path}). Skipping this frame.")
+                continue
+            except Exception as e:
+                print(f"Error loading or reshaping file for timestep {i_str}: {e}. Skipping this frame.")
+                continue
+        
+        if not data:
+            print("Error: No data available to create animation. Check .npy file generation and paths.")
+            return None
+
+        fig = plt.figure(figsize=(10, 8))
+        ax = fig.add_subplot(111, projection='3d')
+
+        x_plot = np.linspace(-10, 10, downsampled_N)
+        y_plot = np.linspace(-10, 10, downsampled_N)
+        X_plot, Y_plot = np.meshgrid(x_plot, y_plot)
+
+        norm_factor = np.linalg.norm(data[0]) if data[0].size > 0 else 1.0
+        if norm_factor == 0:
+            norm_factor = 1.0
+
+        def update_frame(frame_idx):
+            ax.clear()
+            Z = data[frame_idx]
+            surf = ax.plot_surface(X_plot, Y_plot, Z / norm_factor, cmap='viridis', linewidth=0, antialiased=False)
+            current_timestep_for_title = actual_timesteps_for_title[frame_idx] if frame_idx < len(actual_timesteps_for_title) else "Unknown"
+            ax.set_title(f'Quantum Simulation Evolution (Timestep: {current_timestep_for_title})')
+            ax.set_xlabel('x')
+            ax.set_ylabel('y')
+            ax.set_zlim(0, 0.6)
+            return surf,
+
+        gif_animation_fps = 10
+        ani = FuncAnimation(fig, update_frame, frames=len(data), blit=False)
+
+        results_base_dir = "Results"
+        gif_frames_for_naming = int(simulation_fps * T)
+        if gif_frames_for_naming == 0: gif_frames_for_naming = 1
+        
+        # Sanitize distribution_type for filename
+        dist_name_part = distribution_type.replace(' ','').replace('(Original)','').replace('(','').replace(')','')
+        
+        specific_folder_name = (f"d2q5_nq{current_N}x{current_N}_T{T}_fr{gif_frames_for_naming}_"
+                                f"dist{dist_name_part}_ux{ux_input:.2f}_uy{uy_input:.2f}")
+        final_output_dir = Path(results_base_dir) / specific_folder_name
+        os.makedirs(final_output_dir, exist_ok=True)
+        gif_path_to_return = final_output_dir / "animation.gif"
+
+        try:
+            ani.save(str(gif_path_to_return), writer='pillow', fps=gif_animation_fps)
+            print(f"Animation saved to {gif_path_to_return}")
+        except Exception as e:
+            print(f"Error saving animation: {e}")
+            plt.close(fig)
+            return None
+        plt.close(fig)
+        return str(gif_path_to_return)
+
+# --- Gradio Interface Definition ---
+
+def qlbm_gradio_interface(num_reg_qubits_input: int, timescale_input: int, distribution_type_param: str, ux_param: float, uy_param: float):
+    num_reg_qubits_val = int(num_reg_qubits_input)
+    timescale_val = int(timescale_input)
+    ux_val = float(ux_param)
+    uy_val = float(uy_param)
+    
+    print(f"Gradio Interface: num_reg_qubits={num_reg_qubits_val}, T={timescale_val}, Distribution={distribution_type_param}, ux={ux_val}, uy={uy_val}")
+    
+    gif_path_output = simulate_qlbm_and_animate(
+        num_reg_qubits=num_reg_qubits_val, 
+        T=timescale_val, 
+        distribution_type=distribution_type_param,
+        ux_input=ux_val,
+        uy_input=uy_val
+    )
+    
+    if gif_path_output is None:
+        gr.Warning("Animation generation failed. Please check console for errors.")
+        return None 
+    return gif_path_output
+
+with gr.Blocks(theme=gr.themes.Soft(), title="QLBM Simulation") as qlbm_demo:
+    gr.Markdown(
+    """
+    # ⚛️ Quantum Lattice Boltzmann Method (QLBM) Simulator
+    Welcome to the Quantum Lattice Boltzmann Method (QLBM) simulator!
+
+    **What is QLBM?**
+    The Lattice Boltzmann Method (LBM) is a computational fluid dynamics technique for simulating fluid flow. QLBM is its quantum counterpart, leveraging quantum algorithms to potentially offer advantages for certain types of simulations. It's used here to model advection-diffusion phenomena, which describe how substances are transported due to bulk motion (advection) and spread out due to random motion (diffusion).
+
+    **How this Simulator Works:**
+    This simulator implements a D2Q5 model (2 dimensions, 5 velocity directions) on a quantum computer simulator (using CUDA-Q).
+    - You can control the grid size (via Number of Register Qubits, where grid size is $2^N \\times 2^N$).
+    - You can set the total simulation time (Timescale T).
+    - You can choose the initial distribution of the substance on the grid.
+    - You can set the advection velocities `ux` (x-direction) and `uy` (y-direction).
+    The simulation will then evolve this initial state over time, and an animation of the substance's density will be generated.
+
+    **Note:** Simulations with higher qubit counts and longer timescales can be computationally intensive and may take a significant amount of time to complete.
+    The $N$ in $2^N \\times 2^N$ grid refers to `num_reg_qubits`. Advection velocities `ux` and `uy` should generally be kept small (e.g., < 0.3) for model stability.
+    """
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown("## Simulation Parameters")
+            num_reg_qubits_slider = gr.Slider(
+                minimum=8, 
+                maximum=30,
+                value=8,   
+                step=1,
+                label="Number of Register Qubits (num_reg_qubits)",
+                info="Determines the N for grid size (2^N x 2^N). Max 30 (Note: >8 can be very slow)."
+            )
+            timescale_slider = gr.Slider(
+                minimum=10,  
+                maximum=10000,
+                value=100, 
+                step=100,
+                label="Timestep (T)",
+                info="Total number of timesteps. Max 2000 (Note: higher values increase run time significantly)."
+            )
+            distribution_options = ["Sine Wave (Original)", "Gaussian", "Random"]
+            distribution_type_input = gr.Radio(
+                choices=distribution_options,
+                value="Sine Wave (Original)",
+                label="Initial Distribution Type",
+                info="Select the initial pattern of the substance on the grid."
+            )
+            ux_slider = gr.Slider(
+                minimum=-0.4,
+                maximum=0.4,
+                value=0.2,
+                step=0.01,
+                label="Advection Velocity ux",
+                info="x-component of the background advection velocity."
+            )
+            uy_slider = gr.Slider(
+                minimum=-0.4,
+                maximum=0.4,
+                value=0.15,
+                step=0.01,
+                label="Advection Velocity uy",
+                info="y-component of the background advection velocity."
+            )
+            
+            run_qlbm_btn = gr.Button("Run QLBM Simulation", variant="primary")
+        
+        with gr.Column(scale=3):
+            qlbm_plot_output = gr.Image(label="QLBM Simulation Animation", type="filepath")
+
+    qlbm_inputs_list = [num_reg_qubits_slider, timescale_slider, distribution_type_input, ux_slider, uy_slider]
+    
+    run_qlbm_btn.click(
+        fn=qlbm_gradio_interface,
+        inputs=qlbm_inputs_list,
+        outputs=qlbm_plot_output
+    )
+
+    gr.Examples(
+        examples=[
+            [8, 100, "Sine Wave (Original)", 0.2, 0.15],  
+            [6, 50, "Gaussian", 0.1, 0.05],   
+            [4, 30, "Random", -0.05, 0.1],
+        ],
+        inputs=qlbm_inputs_list,
+        outputs=qlbm_plot_output,
+        fn=qlbm_gradio_interface,
+        cache_examples=False 
+    )
+
+if __name__ == "__main__":
+    qlbm_demo.launch()

app_pyvista.py

@@ -0,0 +1,666 @@
+import os
+import sys # Not explicitly used in the core logic, but often good for path manipulations
+# import time # Not explicitly used in the core logic after modifications
+import math
+# import threading # Not explicitly used in the core logic
+import tempfile
+import gradio as gr
+
+import cudaq
+import numpy as np
+import cupy as cp
+# from scipy import interpolate # Not used
+
+from pathlib import Path
+
+# --- PyVista Import ---
+import pyvista as pv
+# Set a global theme for PyVista if desired (optional, can be set per plotter too)
+pv.global_theme.anti_aliasing = 'fxaa' # Smooths plot edges
+pv.global_theme.lighting = True # Enable lighting for better 3D effect
+
+# --- Removed Matplotlib imports ---
+# from matplotlib import pyplot as plt
+# from matplotlib.animation import FuncAnimation
+# import matplotlib
+# matplotlib.use('Agg') # Not needed for PyVista off-screen plotting
+# import matplotlib.pyplot as plt # Duplicate, also removed
+
+def simulate_qlbm_and_animate(num_reg_qubits: int, T: int, distribution_type: str, ux_input: float, uy_input: float):
+    """
+    Simulates a 2D advection-diffusion problem using a Quantum Lattice Boltzmann Method (QLBM)
+    and generates a GIF animation of the simulation's evolution using PyVista.
+
+    Args:
+        num_reg_qubits (int): The number of register qubits (determines grid size N=2^num_reg_qubits).
+        T (int): The total number of timesteps to run the simulation.
+        distribution_type (str): The type of initial distribution to use.
+        ux_input (float): Advection velocity in the x-direction.
+        uy_input (float): Advection velocity in the y-direction.
+
+    Returns:
+        str: The file path to the generated GIF animation, or None if an error occurs.
+    """
+
+    video_length = T
+    simulation_fps = 0.1
+    frames = int(simulation_fps * video_length)
+    if frames == 0:
+        frames = 1
+
+    num_anc = 3
+    num_qubits_total = 2 * num_reg_qubits + num_anc
+    current_N = 2**num_reg_qubits
+    N_tot_state_vector = 2**num_qubits_total
+    num_ranks = 1
+    rank = 0
+    N_sub_per_rank = int(N_tot_state_vector // num_ranks)
+
+    timesteps_per_frame = 1
+    if frames < T and frames > 0:
+        timesteps_per_frame = int(T / frames)
+    if timesteps_per_frame == 0:
+        timesteps_per_frame = 1
+
+    # Initial state selection (as per the provided snippet)
+    if distribution_type == "Sine Wave (Original)":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.sin(x * 2 * np.pi / N_val_func) * (1 - 0.5 * x / N_val_func) * \
+            np.sin(y * 4 * np.pi / N_val_func) * (1 - 0.5 * y / N_val_func) + 1
+    elif distribution_type == "Gaussian":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.exp(-((x - N_val_func / 2)**2 / (2 * (N_val_func / 5)**2) +
+                     (y - N_val_func / 2)**2 / (2 * (N_val_func / 5)**2))) * 1.8 + 0.2
+    elif distribution_type == "Random":
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.random.rand(x.shape[0], x.shape[1]) * 1.5 + 0.2
+    else:
+        print(f"Warning: Unknown distribution type '{distribution_type}'. Defaulting to Sine Wave.")
+        selected_initial_state_function_raw = lambda x, y, N_val_func: \
+            np.sin(x * 2 * np.pi / N_val_func) * (1 - 0.5 * x / N_val_func) * \
+            np.sin(y * 4 * np.pi / N_val_func) * (1 - 0.5 * y / N_val_func) + 1
+
+    initial_state_func_eval = lambda x_coords, y_coords: \
+        selected_initial_state_function_raw(x_coords, y_coords, current_N) * \
+        (y_coords < current_N).astype(int)
+
+
+    with tempfile.TemporaryDirectory() as tmp_npy_dir:
+        intermediate_folder_path = Path(tmp_npy_dir)
+
+        cudaq.set_target('nvidia', option='fp64') # As per user's snippet
+
+        @cudaq.kernel
+        def alloc_kernel(num_qubits_alloc: int):
+            qubits = cudaq.qvector(num_qubits_alloc)
+
+        from cupy.cuda.memory import MemoryPointer, UnownedMemory
+
+        def to_cupy_array(state):
+            tensor = state.getTensor()
+            pDevice = tensor.data()
+            sizeByte = tensor.get_num_elements() * tensor.get_element_size()
+            mem = UnownedMemory(pDevice, sizeByte, owner=state)
+            memptr_obj = MemoryPointer(mem, 0)
+            cupy_array_val = cp.ndarray(tensor.get_num_elements(), # Renamed cupy_array
+                                    dtype=cp.complex128,
+                                    memptr=memptr_obj)
+            return cupy_array_val
+
+        class QLBMAdvecDiffD2Q5_new:
+            def __init__(self, ux=0.2, uy=0.15) -> None: # ux, uy are now passed here
+                self.dim = 2
+                self.ndir = 5
+                self.nq_dir = math.ceil(np.log2(self.ndir))
+                self.dirs = []
+                for dir_int in range(self.ndir):
+                    dir_bin = f"{dir_int:b}".zfill(self.nq_dir)
+                    self.dirs.append(dir_bin)
+                self.e_unitvec = np.array([0, 1, -1, 1, -1])
+                self.wts = np.array([2/6, 1/6, 1/6, 1/6, 1/6])
+                self.cs = 1 / np.sqrt(3)
+                self.ux = ux # Use passed ux
+                self.uy = uy # Use passed uy
+                self.u = np.array([0, self.ux, self.ux, self.uy, self.uy])
+                self.wtcoeffs = np.multiply(self.wts, 1 + self.e_unitvec * self.u / self.cs**2)
+                self.create_circuit()
+
+            def create_circuit(self):
+                v = np.pad(self.wtcoeffs, (0, 2**num_anc - self.ndir))
+                v = v**0.5
+                v[0] += 1 # This specific logic from original snippet
+                v = v / np.linalg.norm(v)
+                U_prep = 2 * np.outer(v, v) - np.eye(len(v))
+                cudaq.register_operation("prep_op", U_prep)
+
+                def collisionOp(dirs_list): # Renamed dirs
+                    dirs_i_list_val = [] # Renamed dirs_i_list
+                    for dir_str in dirs_list: # Renamed dir_
+                        dirs_i = [(int(c)) for c in dir_str]
+                        dirs_i_list_val += dirs_i[::-1]
+                    return dirs_i_list_val
+
+                self.dirs_i_list = collisionOp(self.dirs)
+
+                @cudaq.kernel
+                def rshift(q: cudaq.qview, n: int):
+                    for i in range(n):
+                        if i == n - 1:
+                            x(q[n - 1 - i])
+                        elif i == n - 2:
+                            x.ctrl(q[n - 1 - (i + 1)], q[n - 1 - i])
+                        else:
+                            x.ctrl(q[0:n - 1 - i], q[n - 1 - i])
+
+                @cudaq.kernel
+                def lshift(q: cudaq.qview, n: int):
+                    for i in range(n):
+                        if i == 0:
+                            x(q[0])
+                        elif i == 1:
+                            x.ctrl(q[0], q[1])
+                        else:
+                            x.ctrl(q[0:i], q[i])
+
+                @cudaq.kernel
+                def d2q5_tstep(q: cudaq.qview, nqx: int, nqy: int, nq_dir_val: int, dirs_i_val: list[int]): # Renamed args
+                    qx = q[0:nqx]
+                    qy = q[nqx:nqx + nqy]
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir_val] # Renamed nq_dir
+                    # Original logic for d2q5_tstep based on fixed indices i=1,2,3,4
+                    # This assumes a specific mapping of self.dirs indices to shift operations.
+                    # For +x (rshift qx), assume it corresponds to i=1's block in dirs_i_val
+                    # For -x (lshift qx), assume it corresponds to i=2's block in dirs_i_val
+                    # For +y (rshift qy), assume it corresponds to i=3's block in dirs_i_val
+                    # For -y (lshift qy), assume it corresponds to i=4's block in dirs_i_val
+                    # Important: The `dirs_i_val` is constructed based on `self.dirs`. The mapping between `self.dirs[i]`
+                    # and the actual shift operation (+x, -x, +y, -y) must be consistent with these hardcoded indices.
+                    # The snippet used i=1,2,3,4 which implies self.dirs[1] to self.dirs[4] are active.
+
+                    # Example interpretation (matching original snippet structure):
+                    # Original i=2 -> lshift qx (-x)
+                    idx_lqx = 2
+                    b_list = dirs_i_val[idx_lqx * nq_dir_val:(idx_lqx + 1) * nq_dir_val]
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+                    cudaq.control(lshift, qdir, qx, nqx)
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+
+                    # Original i=1 -> rshift qx (+x)
+                    idx_rqx = 1
+                    b_list = dirs_i_val[idx_rqx * nq_dir_val:(idx_rqx + 1) * nq_dir_val]
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+                    cudaq.control(rshift, qdir, qx, nqx)
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+
+                    # Original i=4 -> lshift qy (-y)
+                    idx_lqy = 4
+                    b_list = dirs_i_val[idx_lqy * nq_dir_val:(idx_lqy + 1) * nq_dir_val]
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+                    cudaq.control(lshift, qdir, qy, nqy)
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+
+                    # Original i=3 -> rshift qy (+y)
+                    idx_rqy = 3
+                    b_list = dirs_i_val[idx_rqy * nq_dir_val:(idx_rqy + 1) * nq_dir_val]
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+                    cudaq.control(rshift, qdir, qy, nqy)
+                    for j in range(nq_dir_val):
+                        if b_list[j] == 0: x(qdir[j])
+
+
+                @cudaq.kernel
+                def d2q5_tstep_wrapper(state_arg: cudaq.State, nqx: int, nqy: int, nq_dir_val: int, dirs_i_val: list[int]): # Renamed args
+                    q = cudaq.qvector(state_arg)
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir_val]
+                    prep_op(qdir[2], qdir[1], qdir[0]) # Assuming nq_dir_val is always 3 for prep_op
+                    d2q5_tstep(q, nqx, nqy, nq_dir_val, dirs_i_val)
+                    prep_op(qdir[2], qdir[1], qdir[0])
+
+                @cudaq.kernel
+                def d2q5_tstep_wrapper_hadamard(vec_arg: list[complex], nqx: int, nqy: int, nq_dir_val: int, dirs_i_val: list[int]): # Renamed args
+                    q = cudaq.qvector(vec_arg) # Renamed vec
+                    qdir = q[nqx + nqy:nqx + nqy + nq_dir_val]
+                    qy = q[nqx:nqx + nqy]
+                    prep_op(qdir[2], qdir[1], qdir[0])
+                    d2q5_tstep(q, nqx, nqy, nq_dir_val, dirs_i_val)
+                    prep_op(qdir[2], qdir[1], qdir[0])
+                    for i in range(nqy):
+                        h(qy[i])
+
+                def run_timestep_func(vec_arg, hadamard=False): # Renamed vec
+                    if hadamard:
+                        result = cudaq.get_state(d2q5_tstep_wrapper_hadamard, vec_arg, num_reg_qubits, num_reg_qubits, self.nq_dir, self.dirs_i_list)
+                    else:
+                        result = cudaq.get_state(d2q5_tstep_wrapper, vec_arg, num_reg_qubits, num_reg_qubits, self.nq_dir, self.dirs_i_list)
+
+                    num_nonzero_ranks = num_ranks / (2**num_anc)
+                    rank_slice_cupy = to_cupy_array(result)
+
+                    if rank >= num_nonzero_ranks and num_nonzero_ranks > 0: # Check num_nonzero_ranks > 0
+                        sub_sv_zeros = np.zeros(N_sub_per_rank, dtype=np.complex128)
+                        cp.cuda.runtime.memcpy(rank_slice_cupy.data.ptr, sub_sv_zeros.ctypes.data, sub_sv_zeros.nbytes, cp.cuda.runtime.memcpyHostToDevice)
+
+                    if rank == 0 and num_nonzero_ranks < 1 and N_sub_per_rank > 0 : # Check N_sub_per_rank > 0
+                        sub_sv_get = (rank_slice_cupy).get()
+                        limit_idx = int(N_tot_state_vector / (2**num_anc))
+                        if limit_idx < N_sub_per_rank : # Ensure index is within bounds
+                             sub_sv_get[limit_idx:] = 0
+                             cp.cuda.runtime.memcpy(rank_slice_cupy.data.ptr, sub_sv_get.ctypes.data, sub_sv_get.nbytes, cp.cuda.runtime.memcpyHostToDevice)
+                    return result
+                self.run_timestep = run_timestep_func
+
+            def write_state(self, state_to_write, t_step_str_val): # Renamed t_step, t_step_str
+                rank_slice_cupy = to_cupy_array(state_to_write)
+                num_nonzero_ranks = num_ranks / (2**num_anc)
+
+                if rank < num_nonzero_ranks or (rank==0 and num_nonzero_ranks <=0): # Logic for saving if this rank has data
+                    save_path = intermediate_folder_path / f"{t_step_str_val}_{rank}.npy" # Use t_step_str_val
+                    with open(save_path, 'wb') as f:
+                        arr_to_save = None
+                        data_limit = N_sub_per_rank
+                        if num_nonzero_ranks < 1 and rank == 0:
+                            data_limit = int(N_tot_state_vector / (2**num_anc))
+                        
+                        if data_limit > 0:
+                            relevant_part_cupy = cp.real(rank_slice_cupy[:data_limit])
+                        else:
+                            relevant_part_cupy = cp.array([], dtype=cp.float64) # Empty array if no data
+
+                        # Reshape and downsample based on current_N and downsampling_factor
+                        # This assumes the relevant_part_cupy[:current_N*current_N] is the 2D grid data
+                        if relevant_part_cupy.size >= current_N * current_N:
+                            arr_flat = relevant_part_cupy[:current_N * current_N]
+                            if downsampling_factor > 1:
+                                arr_reshaped = arr_flat.reshape((current_N, current_N))
+                                arr_downsampled = arr_reshaped[::downsampling_factor, ::downsampling_factor]
+                                arr_to_save = arr_downsampled.flatten()
+                            else:
+                                arr_to_save = arr_flat # No downsampling needed
+                        elif relevant_part_cupy.size > 0 : # Partial data less than full grid
+                            # This case is tricky for downsampling. For now, save what is available if it's 1D after downsampling.
+                            # The original code had a direct downsample on 1D array.
+                            # For consistency, if it's smaller than current_N*current_N, it's likely already "flat" for that part.
+                            if downsampling_factor > 1:
+                                arr_to_save = relevant_part_cupy[::downsampling_factor]
+                            else:
+                                arr_to_save = relevant_part_cupy
+                        
+                        if arr_to_save is not None and arr_to_save.size > 0:
+                            np.save(f, arr_to_save.get() if isinstance(arr_to_save, cp.ndarray) else arr_to_save)
+                        # else: print(f"Debug: No data to save for {save_path}")
+
+            def run_evolution(self, initial_state_arg, total_timesteps, observable=False):
+                current_state_val = initial_state_arg # Renamed current_state
+                for t_iter in range(total_timesteps):
+                    next_state_val = None # Renamed next_state
+                    if t_iter == total_timesteps - 1 and observable:
+                        next_state_val = self.run_timestep(current_state_val, True)
+                        self.write_state(next_state_val, str(t_iter + 1) + "_h")
+                    else:
+                        next_state_val = self.run_timestep(current_state_val)
+                        if (t_iter + 1) % timesteps_per_frame == 0:
+                            self.write_state(next_state_val, str(t_iter + 1)) # Pass as string
+                            if rank == 0:
+                                print(f"Timestep: {t_iter + 1}/{total_timesteps}")
+
+                    cp.get_default_memory_pool().free_all_blocks()
+                    current_state_val = next_state_val
+
+                last_saved_timestep_name = str(total_timesteps) if not observable else str(total_timesteps) + "_h"
+                final_state_file_path = intermediate_folder_path / f"{last_saved_timestep_name}_{rank}.npy"
+                final_T_state_file_path = intermediate_folder_path / f"{total_timesteps}_{rank}.npy"
+
+                needs_final_save = True
+                if observable and final_state_file_path.exists():
+                    needs_final_save = False
+                elif not observable and final_T_state_file_path.exists() and total_timesteps > 0 and total_timesteps % timesteps_per_frame == 0 :
+                     needs_final_save = False
+                elif not observable and final_T_state_file_path.exists(): # Saved by previous final write
+                     needs_final_save = False
+                
+                if needs_final_save and total_timesteps > 0 :
+                    if not observable:
+                         self.write_state(current_state_val, str(total_timesteps)) # Pass as string
+                elif total_timesteps == 0: # Save initial state if T=0
+                    self.write_state(current_state_val, "0")
+
+
+                if rank == 0:
+                    print(f"Timestep: {total_timesteps}/{total_timesteps} (Evolution complete)")
+                cp.get_default_memory_pool().free_all_blocks()
+                self.final_state = current_state_val
+        
+        # downsampling_factor from user's snippet
+        downsampling_factor = 2**5
+        if current_N < downsampling_factor and current_N > 0: # Adjust if N is too small
+            downsampling_factor = current_N 
+        elif current_N == 0: # Should be caught by num_reg_qubits check
+            print("Error: current_N is 0, cannot proceed.")
+            return None
+
+        qlbm_obj = QLBMAdvecDiffD2Q5_new(ux=ux_input, uy=uy_input)
+
+        initial_state_val = cudaq.get_state(alloc_kernel, num_qubits_total) # Renamed initial_state
+        rank_slice_init = to_cupy_array(initial_state_val)
+
+        xv_init = np.arange(current_N)
+        yv_init = np.arange(current_N)
+
+        print(f'Start initializing state with {distribution_type} distribution (ux={ux_input}, uy={uy_input})...')
+        initial_grid_2d = initial_state_func_eval(*np.meshgrid(xv_init, yv_init))
+        sub_sv_init_flat = initial_grid_2d.flatten().astype(np.complex128)
+
+        full_initial_sv_host = np.zeros(N_sub_per_rank, dtype=np.complex128)
+        num_computational_states = current_N * current_N
+
+        if len(sub_sv_init_flat) == num_computational_states:
+            if num_computational_states <= N_sub_per_rank:
+                full_initial_sv_host[:num_computational_states] = sub_sv_init_flat
+            else: # Should not happen if N_sub_per_rank is correctly N_tot_state_vector
+                print(f"Error: Grid data {num_computational_states} too large for N_sub_per_rank {N_sub_per_rank}")
+                return None
+        else:
+            print(f"Warning: Mismatch in expected initial state size {num_computational_states} and calculated {len(sub_sv_init_flat)}")
+            fill_len = min(len(sub_sv_init_flat), num_computational_states, N_sub_per_rank)
+            full_initial_sv_host[:fill_len] = sub_sv_init_flat[:fill_len]
+
+
+        print(f'Rank {rank}: Initial state (N*N part) prepared. Size: {len(sub_sv_init_flat)}. Total N_sub_per_rank: {N_sub_per_rank}')
+        cp.cuda.runtime.memcpy(rank_slice_init.data.ptr, full_initial_sv_host.ctypes.data, full_initial_sv_host.nbytes, cp.cuda.runtime.memcpyHostToDevice)
+        print(f'Rank {rank}: Initial state copied to device.')
+
+        print("Starting QLBM evolution...")
+        qlbm_obj.run_evolution(initial_state_val, T) # observable is False by default
+        print("QLBM evolution complete.")
+
+        print("Generating animation with PyVista...")
+        downsampled_N = current_N // downsampling_factor
+        if downsampled_N == 0 and current_N > 0: # Ensure at least 1x1 grid if not empty
+            downsampled_N = 1
+        elif current_N == 0:
+            print("Error: Downsampled grid size is zero because current_N is zero.")
+            return None
+
+        plotted_timesteps_str = []
+        if T == 0: # Handle T=0 case for plotting initial state
+            if (intermediate_folder_path / f"0_{rank}.npy").exists():
+                plotted_timesteps_str.append("0")
+        else:
+            if timesteps_per_frame > 0:
+                for t_step_val in range(timesteps_per_frame, T + 1, timesteps_per_frame): # Renamed t_step
+                    if intermediate_folder_path.joinpath(f"{t_step_val}_{rank}.npy").exists(): # rank is 0
+                        plotted_timesteps_str.append(str(t_step_val))
+
+            final_T_path = intermediate_folder_path.joinpath(f"{T}_{rank}.npy")
+            final_Th_path = intermediate_folder_path.joinpath(f"{T}_h_{rank}.npy") # Though observable=False
+
+            if T > 0: # Redundant due to outer T==0 check, but safe
+                if final_Th_path.exists():
+                    if str(T)+"_h" not in plotted_timesteps_str:
+                        plotted_timesteps_str.append(str(T)+"_h")
+                elif final_T_path.exists():
+                     if str(T) not in plotted_timesteps_str:
+                        plotted_timesteps_str.append(str(T))
+
+        plotted_timesteps_str = sorted(list(set(plotted_timesteps_str)), key=lambda k_str: (int(k_str.replace('_h','')), k_str))
+
+
+        if not plotted_timesteps_str : # Combined check for T=0 and T>0
+             print(f"Warning: No .npy files found for plotting for T={T}. Animation may be empty or fail.")
+             return None # No frames to plot
+
+        data_frames_list = [] # Renamed data
+        actual_timesteps_for_title = []
+
+        for i_str_val in plotted_timesteps_str: # Renamed i_str
+            try:
+                file_path_load = intermediate_folder_path / f"{i_str_val}_{rank}.npy" # Renamed file_path
+                sol_loaded = np.load(file_path_load) # Renamed sol
+                if sol_loaded.size == downsampled_N * downsampled_N:
+                    Z_data = np.reshape(sol_loaded, (downsampled_N, downsampled_N)) # Renamed Z
+                    data_frames_list.append(Z_data)
+                    actual_timesteps_for_title.append(str(i_str_val).replace('_h',''))
+                else:
+                    print(f"Warning: File {file_path_load} has unexpected size {sol_loaded.size}. Expected {downsampled_N*downsampled_N}. Skipping this frame.")
+                    continue
+            except FileNotFoundError:
+                print(f"Warning: File not found for timestep {i_str_val} ({file_path_load}). Skipping this frame.")
+                continue
+            except Exception as e_load: # Renamed e
+                print(f"Error loading or reshaping file for timestep {i_str_val}: {e_load}. Skipping this frame.")
+                continue
+
+        if not data_frames_list:
+            print("Error: No data available to create animation after loading. Check .npy file generation and paths.")
+            return None
+
+        # --- PyVista Animation Setup ---
+        # Define plot ranges (as in original matplotlib version)
+        x_coords_plot = np.linspace(-10, 10, downsampled_N) # Renamed x_plot
+        y_coords_plot = np.linspace(-10, 10, downsampled_N) # Renamed y_plot
+        X_mesh_plot, Y_mesh_plot = np.meshgrid(x_coords_plot, y_coords_plot) # Renamed X_plot, Y_plot
+
+        # Normalization factor for Z values (geometry and color)
+        # Use the max absolute value of the first frame for consistent scaling reference
+        norm_factor_pv = np.max(np.abs(data_frames_list[0])) if data_frames_list[0].size > 0 and np.max(np.abs(data_frames_list[0])) != 0 else 1.0
+        if norm_factor_pv == 0: norm_factor_pv = 1.0
+
+        # Determine a Z-axis limit for color mapping (clim)
+        # Based on max value across all frames (normalized by norm_factor_pv for consistency if geometry is also normalized by it)
+        all_data_max_val = norm_factor_pv # Initialize with first frame's norm
+        if len(data_frames_list) > 0:
+            max_vals_frames = [np.max(np.abs(d_frame)) for d_frame in data_frames_list if d_frame.size > 0] # Renamed d
+            if max_vals_frames:
+                global_max_val_frames = max(max_vals_frames) # Renamed global_max_val
+                if global_max_val_frames > 0 : all_data_max_val = global_max_val_frames
+        
+        # clim_upper is based on the range of actual scalar values being plotted
+        # If we plot Z_frame/norm_factor_pv as scalars, clim_upper is all_data_max_val/norm_factor_pv
+        # If we plot Z_frame as scalars, clim_upper is all_data_max_val
+        # Let's plot Z_frame/norm_factor_pv as scalars for consistency with previous z_lim=0.6 idea
+        
+        clim_upper_pv = (all_data_max_val / norm_factor_pv) * 1.0 # Target a bit above max normalized value, e.g. *1.0 for exact max
+        if clim_upper_pv == 0 : clim_upper_pv = 0.6 # Fallback like original
+
+        # GIF generation setup
+        results_base_dir = "Results"
+        gif_frames_for_naming = int(simulation_fps * T)
+        if gif_frames_for_naming == 0: gif_frames_for_naming = 1
+        dist_name_part = distribution_type.replace(' ','').replace('(Original)','').replace('(','').replace(')','')
+        specific_folder_name = (f"d2q5_pv_N{current_N}_T{T}_fr{gif_frames_for_naming}_"
+                                f"dist{dist_name_part}_ux{ux_input:.2f}_uy{uy_input:.2f}")
+        final_output_dir = Path(results_base_dir) / specific_folder_name
+        os.makedirs(final_output_dir, exist_ok=True)
+        gif_path_to_return = final_output_dir / "animation_pv.gif" # Changed name slightly
+
+        plotter = pv.Plotter(off_screen=True, window_size=[1000, 800], notebook=False)
+        # Set a fixed camera position for consistent view across frames
+        plotter.camera_position = 'xy' # Simple top-down-ish view
+        plotter.camera.azimuth = 30    # Rotate a bit
+        plotter.camera.elevation = 25  # Look down a bit
+        plotter.camera.zoom(1.2)       # Zoom in slightly
+
+        try:
+            plotter.open_gif(str(gif_path_to_return), fps=10)
+
+            # Corrected sargs dictionary
+            sargs = dict(
+                title='Density',
+                vertical=True,       # Ensure this is 'vertical'
+                position_x=0.05,     # X position of the scalar bar
+                position_y=0.1,      # Y position of the scalar bar
+                height=0.8,          # Height of the scalar bar
+                width=0.1,           # Width of the scalar bar
+                label_font_size=16,  # Font size for labels on the bar
+                title_font_size=18   # Font size for the title of the bar
+            )
+
+            for frame_idx, Z_frame_data in enumerate(data_frames_list):
+                plotter.clear_actors()
+
+                z_coords_geometry = (Z_frame_data / norm_factor_pv)
+                
+                if not X_mesh_plot.flags.c_contiguous: X_mesh_plot_flat = X_mesh_plot.ravel(order='C')
+                else: X_mesh_plot_flat = X_mesh_plot.ravel()
+                if not Y_mesh_plot.flags.c_contiguous: Y_mesh_plot_flat = Y_mesh_plot.ravel(order='C')
+                else: Y_mesh_plot_flat = Y_mesh_plot.ravel()
+                if not z_coords_geometry.flags.c_contiguous: z_coords_geometry_flat = z_coords_geometry.ravel(order='C')
+                else: z_coords_geometry_flat = z_coords_geometry.ravel()
+
+                surface_mesh = pv.StructuredGrid()
+                surface_mesh.points = np.column_stack((X_mesh_plot_flat, Y_mesh_plot_flat, z_coords_geometry_flat))
+                surface_mesh.dimensions = (downsampled_N, downsampled_N, 1)
+                surface_mesh["density"] = z_coords_geometry_flat
+
+                plotter.add_mesh(surface_mesh, scalars="density", cmap="viridis",
+                                 clim=[0, clim_upper_pv], scalar_bar_args=sargs, # sargs is passed here
+                                 show_edges=False)
+
+                current_ts_title = actual_timesteps_for_title[frame_idx] if frame_idx < len(actual_timesteps_for_title) else "Unknown"
+                plotter.add_text(f'QLBM Simulation (Timestep: {current_ts_title})',
+                                 position='upper_edge', font_size=18, color='black', font='arial')
+                
+                plotter.write_frame()
+            
+            plotter.close()
+            print(f"PyVista animation saved to {gif_path_to_return}")
+
+        except Exception as e_pv_anim:
+            print(f"Error during PyVista animation/saving: {e_pv_anim}")
+            if 'plotter' in locals() and hasattr(plotter, 'close'):
+                plotter.close()
+            return None
+        
+        return str(gif_path_to_return)
+
+
+
+# --- Gradio Interface Definition (remains largely the same) ---
+def qlbm_gradio_interface(num_reg_qubits_input: int, timescale_input: int, distribution_type_param: str, ux_param: float, uy_param: float):
+    num_reg_qubits_val = int(num_reg_qubits_input)
+    timescale_val = int(timescale_input)
+    ux_val = float(ux_param)
+    uy_val = float(uy_param)
+
+    print(f"Gradio Interface: num_reg_qubits={num_reg_qubits_val}, T={timescale_val}, Distribution={distribution_type_param}, ux={ux_val}, uy={uy_val}")
+
+    gif_path_output = simulate_qlbm_and_animate(
+        num_reg_qubits=num_reg_qubits_val,
+        T=timescale_val,
+        distribution_type=distribution_type_param,
+        ux_input=ux_val,
+        uy_input=uy_val
+    )
+
+    if gif_path_output is None:
+        gr.Warning("Animation generation failed. Please check console for errors.")
+        return None
+    return gif_path_output
+
+with gr.Blocks(theme=gr.themes.Soft(), title="QLBM Simulation with PyVista") as qlbm_demo:
+    gr.Markdown(
+    """
+    # ⚛️ Quantum Lattice Boltzmann Method (QLBM) Simulator (PyVista Animation)
+    Welcome to the Quantum Lattice Boltzmann Method (QLBM) simulator! This version uses PyVista for 3D animation.
+
+    **What is QLBM?**
+    The Lattice Boltzmann Method (LBM) is a computational fluid dynamics technique for simulating fluid flow. QLBM is its quantum counterpart, leveraging quantum algorithms to potentially offer advantages for certain types of simulations. It's used here to model advection-diffusion phenomena.
+
+    **How this Simulator Works:**
+    This simulator implements a D2Q5 model on a quantum computer simulator (CUDA-Q).
+    - Control grid size (via Number of Register Qubits: $N=2^{\text{num_reg_qubits}}$).
+    - Set total simulation time (Timescale T).
+    - Choose initial distribution.
+    - Set advection velocities `ux` and `uy`.
+    The simulation evolves this state, and a PyVista animation of the density is generated.
+
+    **Note:** Higher qubit counts and longer timescales are computationally intensive. Advection velocities should be small (e.g., < 0.3).
+    """
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown("## Simulation Parameters")
+            num_reg_qubits_slider = gr.Slider(
+                minimum=2,
+                maximum=11, # Max from original snippet
+                value=8,
+                step=1,
+                label="Number of Register Qubits (num_reg_qubits)",
+                info="Determines N for grid size (2^N x 2^N). Max 11 (Note: >8 can be very slow)."
+            )
+            timescale_slider = gr.Slider(
+                minimum=0, # Allow T=0
+                maximum=2000, # Max from original snippet
+                value=100,
+                step=10, # Step from original snippet
+                label="Timescale (T)",
+                info="Total number of timesteps. Max 2000."
+            )
+            distribution_options = ["Sine Wave (Original)", "Gaussian", "Random"]
+            distribution_type_input = gr.Radio(
+                choices=distribution_options,
+                value="Sine Wave (Original)",
+                label="Initial Distribution Type",
+                info="Select the initial pattern of the substance on the grid."
+            )
+            ux_slider = gr.Slider(
+                minimum=-0.4,
+                maximum=0.4,
+                value=0.2,
+                step=0.01,
+                label="Advection Velocity ux",
+                info="x-component of the background advection velocity."
+            )
+            uy_slider = gr.Slider(
+                minimum=-0.4,
+                maximum=0.4,
+                value=0.15,
+                step=0.01,
+                label="Advection Velocity uy",
+                info="y-component of the background advection velocity."
+            )
+
+            run_qlbm_btn = gr.Button("Run QLBM Simulation (PyVista)", variant="primary")
+
+        with gr.Column(scale=3):
+            qlbm_plot_output = gr.Image(label="QLBM Simulation Animation (PyVista GIF)", type="filepath", height=600) # Keep as Image for GIF
+
+    qlbm_inputs_list = [num_reg_qubits_slider, timescale_slider, distribution_type_input, ux_slider, uy_slider]
+
+    run_qlbm_btn.click(
+        fn=qlbm_gradio_interface,
+        inputs=qlbm_inputs_list,
+        outputs=qlbm_plot_output
+    )
+
+    gr.Examples(
+        examples=[
+            [8, 100, "Sine Wave (Original)", 0.2, 0.15],
+            [6, 50, "Gaussian", 0.1, 0.05],
+            [4, 30, "Random", -0.05, 0.1],
+            [7, 70, "Sine Wave (Original)", 0.0, 0.0] # Example with no advection
+        ],
+        inputs=qlbm_inputs_list,
+        outputs=qlbm_plot_output,
+        fn=qlbm_gradio_interface,
+        cache_examples=False
+    )
+
+if __name__ == "__main__":
+    # It's good practice to set the CUDA-Q target early if it's fixed.
+    try:
+        cudaq.set_target('nvidia', option='fp64')
+        print(f"CUDA-Q Target successfully set to: {cudaq.get_target().name}")
+    except Exception as e_target:
+        print(f"Warning: Could not set CUDA-Q target to 'nvidia'. Error: {e_target}")
+        print(f"Current CUDA-Q Target: {cudaq.get_target().name}. Performance may be affected if not using GPU.")
+
+    qlbm_demo.launch()

index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width" />
+		<title>My static Space</title>
+		<link rel="stylesheet" href="style.css" />
+	</head>
+	<body>
+		<div class="card">
+			<h1>Welcome to your static Space!</h1>
+			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
+			<p>
+				Also don't forget to check the
+				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
+			</p>
+		</div>
+	</body>
+</html>

packages.txt

@@ -0,0 +1,4 @@
+libgl1-mesa-glx
+libosmesa6-dev
+libegl1-mesa-dev
+xvfb

requirements.txt

@@ -0,0 +1,11 @@
+pyvista
+kaleido  # <-- Ensure this line is present
+imageio
+matplotlib
+plotly
+imageio-ffmpeg # Still recommended for broader codec support
+gradio
+cudaq # <--- This is the corrected line
+numpy
+cupy-cuda12x # Replace XXX with your target CUDA version (e.g., cupy-cuda118 or cupy-cuda12x)
+

style.css

@@ -0,0 +1,28 @@
+body {
+	padding: 2rem;
+	font-family: -apple-system, BlinkMacSystemFont, "Arial", sans-serif;
+}
+
+h1 {
+	font-size: 16px;
+	margin-top: 0;
+}
+
+p {
+	color: rgb(107, 114, 128);
+	font-size: 15px;
+	margin-bottom: 10px;
+	margin-top: 5px;
+}
+
+.card {
+	max-width: 620px;
+	margin: 0 auto;
+	padding: 16px;
+	border: 1px solid lightgray;
+	border-radius: 16px;
+}
+
+.card p:last-child {
+	margin-bottom: 0;
+}