freepaths 2.4.3__tar.gz → 2.5.0__tar.gz

{freepaths-2.4.3 → freepaths-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freepaths
-Version: 2.4.3
+Version: 2.5.0
 Summary: Phonon Monte Carlo simulator
 Home-page: https://github.com/anufrievroman/freepaths
 Author: Roman Anufriev
@@ -21,7 +21,6 @@ Description-Content-Type: text/markdown
 Requires-Dist: numpy
 Requires-Dist: matplotlib
 Requires-Dist: scipy
-Requires-Dist: imageio
 Requires-Dist: colorama
 Dynamic: author
 Dynamic: author-email

{freepaths-2.4.3 → freepaths-2.5.0}/freepaths/__main__.py

@@ -7,7 +7,7 @@ from colorama import Fore, Style
 
 from freepaths.options import SimulationMode
 
-__version__ = "2.4.3"
+__version__ = "2.5.0"
 
 colorama.init()
 

{freepaths-2.4.3 → freepaths-2.5.0}/freepaths/animation.py

@@ -3,9 +3,9 @@
 import sys
 import os
 import shutil
-import imageio
 import numpy as np
 import matplotlib.pyplot as plt
+from PIL import Image
 
 from freepaths.config import cf
 from freepaths.output_structure import draw_structure_top_view
@@ -14,7 +14,7 @@ from freepaths.output_structure import draw_structure_top_view
 def generate_frames_xy():
     """Generate animation frames with phonon paths"""
 
-    data = np.genfromtxt("Data/Phonon paths.csv",
+    data = np.genfromtxt("Data/Particle paths.csv",
                          unpack=False,
                          delimiter=',',
                          skip_header=1,
@@ -77,21 +77,20 @@ def generate_frames_xy():
 def generate_animation_xy():
     """Generate animation of phonon path in XY plane"""
     sys.stdout.write(f"\rAnimation: creating animation file")
-    images = []
-    filenames = os.listdir("Frames/")
-    for filename in filenames:
-        images.append(imageio.imread(f"Frames/{filename}"))
 
-    # Create a GIF file:
-    imageio.mimsave("Animated paths XY.gif", images,
-                    duration=1000 * 1/cf.output_animation_fps, subrectangles=True)
-
-    # Create an MP4 file:
-    # writer = imageio.get_writer('Animated paths XY.mp4', fps=cf.output_animation_fps)
-
-    # for im in images:
-        # writer.append_data(imageio.imread(im))
-    # writer.close()
+    # Sort the frames so the GIF plays in the order they were rendered.
+    # os.listdir returns entries in arbitrary filesystem order (unsorted on
+    # macOS/APFS), which produced out-of-order animations. Filtering to the
+    # frame_*.png files also guards against stray files (e.g. .DS_Store).
+    filenames = sorted(f for f in os.listdir("Frames/") if f.endswith(".png"))
+
+    # Assemble the GIF with Pillow (already a matplotlib dependency), so no
+    # extra imaging library is required. Frames are converted to a palette
+    # image for GIF; duration is milliseconds per frame, loop=0 loops forever.
+    frames = [Image.open(f"Frames/{name}").convert("RGB").convert("P", palette=Image.ADAPTIVE)
+              for name in filenames]
+    frames[0].save("Animated paths XY.gif", save_all=True, append_images=frames[1:],
+                   duration=1000 / cf.output_animation_fps, loop=0, optimize=True)
 
 
 def delete_frames():

{freepaths-2.4.3 → freepaths-2.5.0}/freepaths/config.py

@@ -91,6 +91,7 @@ class Config:
         self.number_of_virtual_timesteps = NUMBER_OF_VIRTUAL_TIMESTEPS
         self.ignore_faulty_particles = IGNORE_FAULTY_PARTICLES
         self.gradient_fit_range = GRADIENT_FIT_RANGE
+        self.temperature_profile_x_range = TEMPERATURE_PROFILE_X_RANGE
 
         # Material parameters:
         self.media = MEDIA
@@ -98,7 +99,12 @@ class Config:
 
         # Internal scattering:
         self.include_internal_scattering = INCLUDE_INTERNAL_SCATTERING
-        self.use_dispersion_heat_capacity = USE_DISPERSION_HEAT_CAPACITY
+        self.phonon_hydrodynamic = PHONON_HYDRODYNAMIC
+        self.number_of_hydrodynamic_preruns = NUMBER_OF_HYDRODYNAMIC_PRERUNS
+        self.hydrodynamic_preruns_weight = HYDRODYNAMIC_PRERUNS_WEIGHT
+        self.number_of_hydrodynamic_prerun_particles = NUMBER_OF_HYDRODYNAMIC_PRERUN_PARTICLES
+        self.hydrodynamic_normal_resistive = HYDRODYNAMIC_NORMAL_RESISTIVE
+        self.isotope_c13_concentration = ISOTOPE_C13_CONCENTRATION
         self.max_number_of_scattering_events = MAX_NUMBER_OF_SCATTERING_EVENTS
         self.grain_size = GRAIN_SIZE
         self.grain_size_std = GRAIN_SIZE_STD
@@ -171,6 +177,11 @@ class Config:
                           f"See the documentation at {WEBSITE}")
             sys.exit()
 
+        if not (0.0 <= self.temperature_profile_x_range[0] < self.temperature_profile_x_range[1] <= 1.0):
+            logging.error("Parameter TEMPERATURE_PROFILE_X_RANGE must be a pair (start, end) with 0 <= start < end <= 1.\n" +
+                          f"See the documentation at {WEBSITE}")
+            sys.exit()
+
         if self.number_of_timeframes <= self.number_of_stabilization_timeframes:
             logging.error("Parameter NUMBER_OF_STABILIZATION_TIMEFRAMES exceeds or equal to NUMBER_OF_TIMEFRAMES.\n" +
                           "Leave at least one timeframe after NUMBER_OF_STABILIZATION_TIMEFRAMES.\n" +

{freepaths-2.4.3 → freepaths-2.5.0}/freepaths/default_config.py

@@ -55,9 +55,6 @@ MEAN_MAPPING_CONSTANT            = 5e-6 # [m²]
 
 FERMI_LEVEL_LOWER_BOUND          = -0.2  # [eV] lower end of post-processing Fermi level sweep
 FERMI_LEVEL_UPPER_BOUND          =  0.1  # [eV] upper end of post-processing Fermi level sweep;
-# far above the band edge the Fermi window leaves the sampled energy range and
-# the MC results become noisy, so there is little point in sweeping further
-
 
 # Animation:
 OUTPUT_PATH_ANIMATION            = False
@@ -68,6 +65,7 @@ NUMBER_OF_PIXELS_X               = 7
 NUMBER_OF_PIXELS_Y               = 67
 IGNORE_FAULTY_PARTICLES          = False
 GRADIENT_FIT_RANGE               = (0.1, 0.9)
+TEMPERATURE_PROFILE_X_RANGE      = (0.0, 1.0)
 
 # Material parameters:
 MEDIA                            = "Si"
@@ -76,47 +74,20 @@ MEDIA_FERMI_LEVEL                = None
 # Internal scattering:
 INCLUDE_INTERNAL_SCATTERING      = True
 
-# Phonon frequencies and branches are always sampled from the tabulated dispersion
-# (weight k^2 dk per bin, heat-capacity weighting, group-velocity weighting at the
-# source), so particles are equal-energy deviational bundles and the thermal maps
-# record a constant weight per phonon. At inelastic (anharmonic) internal scattering
-# events the branch and frequency are re-drawn from the collision-rate-weighted
-# distribution (Peraud & Hadjiconstantinou, PRB 84, 205331 (2011)), restoring local
-# thermal equilibrium of the phonon population. Elastic internal events (impurity/alloy
-# scattering) conserve the mode and only randomize the direction. This applies to the
-# phonon tracing mode; MFP sampling and electron modes keep the particle identity by
-# construction.
-
-# Convert deposited particle energy into the temperature profile using the
-# dispersion-only heat capacity (Material.dispersion_heat_capacity, summed only
-# over the branches in the tabulated dispersion) instead of the experimental
-# heat capacity fit (Material.assign_heat_capacity). On by default because it
-# makes the reported temperature and kappa self-consistent with the
-# dispersion-based sampling/rethermalization scheme and the model's own RTA
-# integral. Set to False to use the real material heat capacity instead (e.g.
-# including optical branches absent from the tabulated dispersion):
-USE_DISPERSION_HEAT_CAPACITY     = True
-
-# MFP sampling mode only (no effect in phonon tracing, where particles must keep
-# going for the full budget to build the flux map): end a phonon's flight early
-# once it has accumulated this many free-path segments, instead of always running
-# to NUMBER_OF_TIMESTEPS. A short-tau, low-velocity phonon takes tiny hops and
-# diffuses so slowly that it essentially never reaches a domain boundary, but its
-# mean free path already converges after a modest number of scattering events, so
-# running it to the full timestep budget is wasted compute. 1000 is on by default,
-# since it was validated (bulk Si MFP-sampling convergence study, Data/BulkSi_Phonon_MFP/)
-# to give the same result as 5000 while being far cheaper. Set to None to disable
-# (run to the timestep budget or a boundary, as before):
+# Phonon hydrodynamic transport.
+PHONON_HYDRODYNAMIC              = False
+NUMBER_OF_HYDRODYNAMIC_PRERUNS   = 5
+HYDRODYNAMIC_PRERUNS_WEIGHT      = 0.8
+NUMBER_OF_HYDRODYNAMIC_PRERUN_PARTICLES = None
+
+# Diagnostic control: when True, Normal events still fire but redraw the direction 
+# randomly instead of biased toward the local drift
+HYDRODYNAMIC_NORMAL_RESISTIVE    = False
+ISOTOPE_C13_CONCENTRATION        = 0.0
+
 MAX_NUMBER_OF_SCATTERING_EVENTS  = 1000
 
 # Grain boundary scattering (polycrystalline materials):
-# GRAIN_SIZE sets the mean grain diameter [m]. None disables grain boundary scattering entirely.
-# GRAIN_SIZE_STD sets the standard deviation [m]; the grain size is drawn per phonon from a
-# lognormal distribution with this mean and std. Set to 0 for monodisperse (single grain size).
-# GRAIN_ROUGHNESS is the RMS disorder width of the grain boundary [m], used in a Soffer-type
-# specularity factor: at low frequencies (long wavelengths) the boundary appears smooth and
-# phonons pass through; at high frequencies it acts as a classical diffuse scatterer.
-# Typical values: GRAIN_SIZE 100 nm – 10 µm, GRAIN_ROUGHNESS 0.5–2 nm.
 GRAIN_SIZE                       = None
 GRAIN_SIZE_STD                   = 0.0
 GRAIN_ROUGHNESS                  = 1e-9

{freepaths-2.4.3 → freepaths-2.5.0}/freepaths/interface_smmm.py

@@ -31,6 +31,19 @@ def alpha_spec(theta_i, vg_i, vg_j, rho_i, rho_j):
     """
     Specular transmission coefficient (AMM) between two materials.
 
+    Ran & Cao, PRB 110, 024302 (2024), Eq. (20):
+
+        alpha = 4*A*B / (A + B)**2,   A = Z_j/Z_i,  B = cos(theta_j)/cos(theta_i)
+
+    which is the standard oblique-incidence acoustic result 4*W_i*W_j/(W_i + W_j)**2
+    with the angle-corrected impedances W = Z/cos(theta), i.e. the COSINES IN THE
+    DENOMINATOR ARE CROSSED: (Z_i*cos(theta_j) + Z_j*cos(theta_i))**2. Writing them
+    uncrossed agrees at normal incidence but over-estimates transmission at oblique
+    incidence (Si/SiGe LA at 1 THz: 0.990 vs 0.928 at 60 deg).
+
+    Note this is Eq. (20), not Eq. (25): the MTM detailed-balance prefactor
+    min{1, P_j*C_j*vg_j**3 / (P_i*C_i*vg_i**3)} of Eq. (25) is deliberately not applied.
+
     Parameters:
     theta_i -- incidence angle
     vg_i, vg_j -- group velocities of media i and j
@@ -49,7 +62,7 @@ def alpha_spec(theta_i, vg_i, vg_j, rho_i, rho_j):
         Z_j = rho_j * vg_j
 
         num = 4 * Z_i * Z_j * abs(math.cos(theta_i)) * abs(math.cos(theta_j))
-        den = (Z_i * abs(math.cos(theta_i)) + Z_j * abs(math.cos(theta_j))) ** 2
+        den = (Z_i * abs(math.cos(theta_j)) + Z_j * abs(math.cos(theta_i))) ** 2
         return num / den
     except:
         return 0.0

{freepaths-2.4.3 → freepaths-2.5.0}/freepaths/main_mfp_sampling.py

@@ -21,10 +21,9 @@ from freepaths.phonon import Phonon
 from freepaths.flight import Flight
 from freepaths.options import SimulationMode
 from freepaths.data import ScatteringData, GeneralData, SegmentData, PathData, TriangleScatteringData
-from freepaths.materials import Si, SiC, Graphite, SiGe
+from freepaths.materials import create_material, get_media_class
 from freepaths.maps import ScatteringMap
 from freepaths.output_info import output_general_information, output_scattering_information, output_parameter_warnings
-from freepaths.materials import get_media_class
 from freepaths.output_plots import plot_data
 
 
@@ -78,17 +77,8 @@ def _run_branch(branch_number, shared_list, shared_progress):
     # Each worker builds its own material instance so the dispersion is
     # sampled with the correct number of points (number_of_particles + 1
     # intervals → number_of_particles midpoints):
-    if cf.media == "Si":
-        material = Si(cf.temp, num_points=cf.number_of_particles + 1)
-    elif cf.media == "SiGe":
-        material = SiGe(cf.temp, num_points=cf.number_of_particles + 1)
-    elif cf.media == "SiC":
-        material = SiC(cf.temp, num_points=cf.number_of_particles + 1)
-    elif cf.media == "Graphite":
-        material = Graphite(cf.temp, num_points=cf.number_of_particles + 1)
-    else:
-        logging.error(f"Material {cf.media} is not supported")
-        return
+    material = create_material(cf.media, cf.temp, num_points=cf.number_of_particles + 1,
+                               isotope_c13_concentration=cf.isotope_c13_concentration)
 
     # Local data structures — merged into the global ones after all workers finish:
     scatter_stats = ScatteringData()
@@ -100,6 +90,9 @@ def _run_branch(branch_number, shared_list, shared_progress):
 
     total_thermal_conductivity = 0.0
     total_kappa_variance = 0.0
+    total_kappa1 = 0.0        # Callaway kappa1 accumulator (uses combined tau_C)
+    total_k2_num = 0.0        # Callaway kappa2 numerator sum:   w * tau_C / tau_N
+    total_k2_den = 0.0        # Callaway kappa2 denominator sum:  w * tau_C / (tau_N * tau_R)
     last_pct = -1
 
     for index in range(cf.number_of_particles):
@@ -122,11 +115,31 @@ def _run_branch(branch_number, shared_list, shared_progress):
         part = scipy.constants.hbar * omega / (scipy.constants.k * cf.temp)
         c_p = scipy.constants.k * part**2 * math.exp(part) / (math.exp(part) - 1)**2
 
-        # Thermal conductivity contribution from this k-point (Ref. Phys. Rev. 132 2461, 1963):
+        # Thermal conductivity contribution from this k-point (Ref. Phys. Rev. 132 2461, 1963).
+        # The measured mean free path is limited by resistive (Umklapp + isotope) and boundary
+        # scattering, so mean_relax_time is the Callaway resistive time tau_R (Normal scattering
+        # does not fire in the MFP-sampling mode). weight is the common per-mode integrand factor.
         mean_relax_time = flight.mean_free_path / phonon.speed
-        flight.thermal_conductivity = (1 / (6 * math.pi**2)) * c_p * phonon.speed**2 * mean_relax_time * k_vector**2 * d_k_vector
+        weight = (1 / (6 * math.pi**2)) * c_p * phonon.speed**2 * k_vector**2 * d_k_vector
+        flight.thermal_conductivity = weight * mean_relax_time          # single-mode RTA (SMRT)
         total_thermal_conductivity += flight.thermal_conductivity
 
+        # Callaway dual-relaxation correction (Callaway, Phys. Rev. 113, 1046 (1959)):
+        # kappa = kappa1 + kappa2, with 1/tau_C = 1/tau_R + 1/tau_N. kappa1 uses the combined
+        # tau_C (Normal provisionally counted as resistive); kappa2 is the momentum-recovery term
+        # kappa2 = (sum w*tau_C/tau_N)^2 / (sum w*tau_C/(tau_N*tau_R)), accumulated linearly here
+        # and combined in main(). tau_C/tau_N = tau_C*normal_rate. Only computed when
+        # PHONON_HYDRODYNAMIC is on (the Normal / momentum-recovery treatment); otherwise
+        # normal_rate = 0 and kappa1 collapses to the standard SMRT conductivity.
+        normal_rate = material.phonon_normal_rate(omega) if cf.phonon_hydrodynamic else 0.0
+        if normal_rate > 0 and mean_relax_time > 0:
+            tau_C = 1.0 / (1.0 / mean_relax_time + normal_rate)
+            total_kappa1 += weight * tau_C
+            total_k2_num += weight * tau_C * normal_rate
+            total_k2_den += weight * tau_C * normal_rate / mean_relax_time
+        else:
+            total_kappa1 += weight * mean_relax_time
+
         # This mode's kappa is linear in its mean free path, so its variance
         # propagates directly through the same proportionality (kappa_i / mfp_i):
         if flight.mean_free_path > 0:
@@ -143,6 +156,9 @@ def _run_branch(branch_number, shared_list, shared_progress):
     shared_list.append({
         'total_thermal_conductivity': total_thermal_conductivity,
         'total_kappa_variance': total_kappa_variance,
+        'total_kappa1': total_kappa1,
+        'total_k2_num': total_k2_num,
+        'total_k2_den': total_k2_den,
         'scatter_stats': scatter_stats.dump_data(),
         'general_stats': general_stats.dump_data(),
         'segment_stats': segment_stats.dump_data(),
@@ -213,10 +229,16 @@ def main(input_file, mode: SimulationMode):
     scatter_maps = ScatteringMap()
     total_thermal_conductivity = 0.0
     total_kappa_variance = 0.0
+    total_kappa1 = 0.0
+    total_k2_num = 0.0
+    total_k2_den = 0.0
 
     for result in shared_list:
         total_thermal_conductivity += result['total_thermal_conductivity']
         total_kappa_variance += result['total_kappa_variance']
+        total_kappa1 += result['total_kappa1']
+        total_k2_num += result['total_k2_num']
+        total_k2_den += result['total_k2_den']
         scatter_stats.read_data(result['scatter_stats'])
         general_stats.read_data(result['general_stats'])
         segment_stats.read_data(result['segment_stats'])
@@ -267,6 +289,19 @@ def main(input_file, mode: SimulationMode):
                fmt='%2.4e', delimiter=',',
                header="K_material SEM [W/mK], K_effective SEM [W/mK]", encoding='utf-8')
 
+    # Callaway dual-relaxation conductivity kappa = kappa1 + kappa2 (momentum-recovery term).
+    # Only written in hydrodynamic mode (the Normal-process treatment); in the standard RTA the
+    # -s output is unchanged. Kept in a separate file so the positional indexers of
+    # "Thermal conductivity from MFP.csv" are not disturbed. See main_mfp_sampling._run_branch.
+    kappa2 = kappa_callaway = None
+    if cf.phonon_hydrodynamic:
+        kappa2 = (total_k2_num ** 2 / total_k2_den) if total_k2_den > 0 else 0.0
+        kappa_callaway = total_kappa1 + kappa2
+        np.savetxt("Data/Thermal conductivity Callaway.csv",
+                   np.array([[total_kappa1, kappa2, kappa_callaway]]),
+                   fmt='%2.4e', delimiter=',',
+                   header="kappa1 [W/mK], kappa2 [W/mK], kappa_Callaway [W/mK]", encoding='utf-8')
+
     sys.stdout.write("\rAnalyzing the data...")
     plot_data(mode, cf)
 
@@ -274,7 +309,12 @@ def main(input_file, mode: SimulationMode):
     output_scattering_information(scatter_stats)
     output_parameter_warnings(mode, general_stats)
     sys.stdout.write(f'\rSee the results in {Fore.GREEN}Results/{cf.output_folder_name}{Style.RESET_ALL}\n')
-    sys.stdout.write(f"\rMaterial thermal conductivity = {Fore.GREEN}{total_thermal_conductivity:.5f} ± {kappa_sem:.5f}{Style.RESET_ALL} W/m·K\n")
+    if cf.phonon_hydrodynamic:
+        sys.stdout.write(f"\rMaterial thermal conductivity (SMRT) = {Fore.GREEN}{total_thermal_conductivity:.5f} ± {kappa_sem:.5f}{Style.RESET_ALL} W/m·K\n")
+        sys.stdout.write(f"\rMaterial thermal conductivity (Callaway) = {Fore.GREEN}{kappa_callaway:.5f}{Style.RESET_ALL} W/m·K "
+                         f"(kappa1 {total_kappa1:.2f} + kappa2 {kappa2:.2f})\n")
+    else:
+        sys.stdout.write(f"\rMaterial thermal conductivity = {Fore.GREEN}{total_thermal_conductivity:.5f} ± {kappa_sem:.5f}{Style.RESET_ALL} W/m·K\n")
     if cf.holes:
         sys.stdout.write(f"\rEffective thermal conductivity = {Fore.GREEN}{effective_thermal_conductivity:.5f} ± {effective_kappa_sem:.5f}{Style.RESET_ALL} W/m·K "
                          f"(porosity {porosity:.1%}, Eucken factor {eucken_factor:.3f})\n")

{freepaths-2.4.3 → freepaths-2.5.0}/freepaths/main_tracing.py

@@ -21,8 +21,8 @@ from freepaths.options import SimulationMode
 from freepaths.data import ScatteringData, GeneralData, SegmentData, PathData, TriangleScatteringData
 from freepaths.post_computations import ElectronPostComputation
 from freepaths.progress import Progress
-from freepaths.materials import Si, SiC, Graphite, SiGe
-from freepaths.maps import ScatteringMap, ThermalMaps
+from freepaths.materials import create_material
+from freepaths.maps import ScatteringMap, ThermalMaps, DriftField
 from freepaths.output_info import output_general_information, output_scattering_information, output_parameter_warnings, output_electron_information
 from freepaths.animation import create_animation
 from freepaths.output_plots import plot_data
@@ -35,20 +35,15 @@ class ParticleSimulator:
     It is meant to be used as a worker for multiprocessing
     """
 
-    def __init__(self, worker_id, mode: SimulationMode, total_particles, shared_list, output_trajectories_of):
+    def __init__(self, worker_id, mode: SimulationMode, total_particles, shared_list, output_trajectories_of, drift_field=None):
 
         # Initialize the material:
-        if cf.media == "Si":
-            self.material = Si(cf.temp)
-        elif cf.media == "SiGe":
-            self.material = SiGe(cf.temp)
-        elif cf.media == "SiC":
-            self.material = SiC(cf.temp)
-        elif cf.media == "Graphite":
-            self.material = Graphite(cf.temp)
-        else:
-            logging.error(f"Material {cf.media} is not supported")
-            sys.exit()
+        self.material = create_material(cf.media, cf.temp,
+                                        isotope_c13_concentration=cf.isotope_c13_concentration)
+
+        # Frozen hydrodynamic drift field for this pass (None in the bootstrap pass and
+        # in non-hydrodynamic runs); read by momentum-conserving Normal scattering events:
+        self.material.drift_field = drift_field
 
         # Carrier surface-depletion dead-layer width (0 unless SURFACE_POTENTIAL and doping are set):
         cf.depletion_width = depletion_width(self.material)
@@ -130,11 +125,11 @@ class ParticleSimulator:
         self.result_queue.append(collected_data)
 
 
-def worker_process(worker_id, mode: SimulationMode, total_particles, shared_list, output_trajectories_of, finished_workers):
+def worker_process(worker_id, mode: SimulationMode, total_particles, shared_list, output_trajectories_of, finished_workers, drift_field=None):
     signal.signal(signal.SIGINT, signal.SIG_IGN)
     try:
         # Create a particle simulator and run the simulation:
-        simulator = ParticleSimulator(worker_id, mode, total_particles, shared_list, output_trajectories_of)
+        simulator = ParticleSimulator(worker_id, mode, total_particles, shared_list, output_trajectories_of, drift_field)
         simulator.simulate_particles(render_progress=1 if worker_id == 0 else 0)
 
         # Declare that the calculation is finished:
@@ -165,25 +160,24 @@ def display_workers_finished(finished_workers):
         pass
 
 
-def main(input_file, mode: SimulationMode):
+def run_pass(mode: SimulationMode, drift_field=None, total_particles=None):
     """
-    This is the main function.
-    It should be used to simulate electron paths or phonon paths at low temperatures.
+    Launch all worker processes for one full sweep of the ensemble (one "pass"), with
+    the given frozen drift field, and return the collected result_list. In a
+    non-hydrodynamic run this is called exactly once; in hydrodynamic mode it is called
+    once per self-consistency pass, each time with the drift field frozen at the value
+    converged from the previous pass. total_particles overrides cf.number_of_particles
+    for this pass (used to run cheaper preruns than the reported run).
     """
-
-    sys.stdout.write(f'Simulation of {Fore.GREEN}{cf.output_folder_name}{Style.RESET_ALL}\n')
-    start_time = time.time()
-
-    # Create manager for managing variable acces for multiple workers:
+    if total_particles is None:
+        total_particles = cf.number_of_particles
     manager = multiprocessing.Manager()
-
-    # These variables created with the manager can safely be accessed by multiple workers:
     shared_list = manager.list()
     finished_workers = manager.Value('i', 0)
 
     # Divide all the particles among the workers:
-    workload_per_worker = cf.number_of_particles // cf.num_workers
-    remaining_particles = cf.number_of_particles % cf.num_workers
+    workload_per_worker = total_particles // cf.num_workers
+    remaining_particles = total_particles % cf.num_workers
 
     # Divide number of output trajectories to save among workers:
     output_trajectories_per_worker = cf.output_trajectories_of_first // cf.num_workers
@@ -196,7 +190,7 @@ def main(input_file, mode: SimulationMode):
     for i in range(cf.num_workers):
         worker_particles = workload_per_worker + (1 if i < remaining_particles else 0)
         output_trajectory_of = output_trajectories_per_worker + (1 if i < remaining_output_trajectories else 0)
-        process = multiprocessing.Process(target=worker_process, args=(i, mode, worker_particles, shared_list, output_trajectory_of, finished_workers))
+        process = multiprocessing.Process(target=worker_process, args=(i, mode, worker_particles, shared_list, output_trajectory_of, finished_workers, drift_field))
         processes.append(process)
         process.start()
 
@@ -217,9 +211,11 @@ def main(input_file, mode: SimulationMode):
     # Wait for the worker count to finish but continue after 3 seconds:
     worker_count_process.join(timeout=3)
     worker_count_process.terminate() # should not be necessary but sometimes process does not terminate
+    return list(shared_list)
 
-    # Initiate data structures to collect the data from the workers:
-    # material = Material(cf.media, num_points=cf.number_of_phonons+1)
+
+def merge_results(result_list, mode: SimulationMode):
+    """Merge the per-worker data dictionaries from one pass into unified data structures."""
     scatter_stats = ScatteringData()
     places_stats = TriangleScatteringData()
     general_stats = GeneralData()
@@ -228,17 +224,9 @@ def main(input_file, mode: SimulationMode):
     scatter_maps = ScatteringMap()
     thermal_maps = ThermalMaps() if mode is SimulationMode.PHONON_TRACING else None
 
-    # Collect the results:
-    sys.stdout.write('\nCollecting data from workers...\r')
-
-    # Convert the shared list to a normal list so it's easier to use
-    result_list = list(shared_list)
-
-    # Check that all workers actually returned some data
     if len(result_list) != cf.num_workers:
         sys.stdout.write(f'WARNING: of {cf.num_workers} workers only the results of {len(result_list)} were collected\n')
 
-    # Put the data from every worker into it's respective place:
     execution_time_list = []
     for collected_data in result_list:
         scatter_stats.read_data(collected_data['scatter_stats'])
@@ -251,12 +239,103 @@ def main(input_file, mode: SimulationMode):
             thermal_maps.read_data(collected_data['thermal_maps'])
         execution_time_list.append(collected_data['execution_time'])
 
+    return scatter_stats, places_stats, general_stats, segment_stats, path_stats, scatter_maps, thermal_maps, execution_time_list
+
+
+def main(input_file, mode: SimulationMode):
+    """
+    This is the main function.
+    It should be used to simulate electron paths or phonon paths at low temperatures.
+    """
+
+    sys.stdout.write(f'Simulation of {Fore.GREEN}{cf.output_folder_name}{Style.RESET_ALL}\n')
+    start_time = time.time()
+
+    # Hydrodynamic mode first traces the ensemble in NUMBER_OF_HYDRODYNAMIC_PRERUNS
+    # preruns that only build the self-consistent drift field (frozen within each prerun,
+    # under-relaxed between them), then a final reported run that reads the converged field
+    # and supplies the reported statistics and maps. The reported run does NOT update the
+    # field (there is no pass after it), so unlike a plain "report the last of N passes"
+    # scheme the reported run reads the fully converged field. Everything non-hydrodynamic
+    # runs a single pass.
+    hydrodynamic = cf.phonon_hydrodynamic and mode is SimulationMode.PHONON_TRACING
+    number_of_preruns = cf.number_of_hydrodynamic_preruns if hydrodynamic else 0
+    number_of_passes = number_of_preruns + 1
+
+    # Material instance for the momentum-susceptibility constant (drift-field derivation):
+    hydro_material = create_material(cf.media, cf.temp,
+                                    isotope_c13_concentration=cf.isotope_c13_concentration) if hydrodynamic else None
+
+    drift_field = None
+    drift_convergence = []   # per-prerun (n, mean|u_fresh|, mean|u_field|, rel_change) for the convergence test
+    flux_profiles = []       # per-pass mid-length cross-width |J_y|(x), to watch it become parabolic
+    # Preruns only need to converge the field, so they can use fewer particles than the
+    # reported run (NUMBER_OF_HYDRODYNAMIC_PRERUN_PARTICLES; None = same as the reported run):
+    prerun_particles = cf.number_of_hydrodynamic_prerun_particles
+    for pass_index in range(number_of_passes):
+        is_reported_run = (pass_index == number_of_passes - 1)
+        pass_particles = None
+        if hydrodynamic and not is_reported_run and prerun_particles:
+            pass_particles = prerun_particles
+        if hydrodynamic:
+            n = pass_particles if pass_particles else cf.number_of_particles
+            label = "reported run" if is_reported_run else f"prerun {pass_index + 1}/{number_of_preruns}"
+            sys.stdout.write(f'\nHydrodynamic {label} ({n} particles)\n')
+
+        result_list = run_pass(mode, drift_field, pass_particles)
+
+        # Collect the results of this pass:
+        sys.stdout.write('\nCollecting data from workers...\r')
+        (scatter_stats, places_stats, general_stats, segment_stats, path_stats,
+         scatter_maps, thermal_maps, execution_time_list) = merge_results(result_list, mode)
+
+        # During preruns, update the self-consistent drift field for the next pass. The
+        # freshly measured field is under-relaxed against the previous one (Robbins-Monro)
+        # for stability. The reported run still measures its drift (for the saved profile)
+        # but does not feed it back:
+        if hydrodynamic and thermal_maps is not None:
+            thermal_maps.calculate_drift_velocity(hydro_material)
+
+            # Cross-width heat-flux profile at mid-length, one per pass, so the profile can
+            # be watched evolving from blunt (bootstrap, no drift) toward parabolic (Poiseuille):
+            ny = thermal_maps.heat_flux_map_y.shape[0]
+            band = thermal_maps.heat_flux_map_y[int(0.35 * ny):int(0.65 * ny), :]
+            flux_profiles.append(np.abs(band).mean(axis=0))
+
+            if not is_reported_run:
+                fresh = DriftField(thermal_maps.drift_velocity_x, thermal_maps.drift_velocity_y, thermal_maps.drift_velocity_z)
+                previous = drift_field
+                if drift_field is None:
+                    drift_field = fresh
+                else:
+                    g = cf.hydrodynamic_preruns_weight
+                    drift_field = DriftField(
+                        (1 - g) * drift_field.u_x + g * fresh.u_x,
+                        (1 - g) * drift_field.u_y + g * fresh.u_y,
+                        (1 - g) * drift_field.u_z + g * fresh.u_z,
+                    )
+
+                # Convergence diagnostics: mean drift magnitude of the freshly measured
+                # field and of the (under-relaxed) field carried to the next prerun, plus
+                # the relative L1 change of that field vs the previous prerun. When the
+                # relative change flattens toward its noise floor, the preruns are adequate.
+                def _mean_mag(f):
+                    mag = np.hypot(f.u_x, f.u_y)
+                    return float(mag[mag > 0].mean()) if np.any(mag > 0) else 0.0
+                if previous is None:
+                    rel_change = np.nan
+                else:
+                    delta = np.abs(drift_field.u_x - previous.u_x) + np.abs(drift_field.u_y - previous.u_y)
+                    scale = np.abs(drift_field.u_x) + np.abs(drift_field.u_y)
+                    rel_change = float(delta.sum() / (scale.sum() + 1e-30))
+                drift_convergence.append((pass_index + 1, _mean_mag(fresh), _mean_mag(drift_field), rel_change))
+
     # Give some info about the variability in the worker calculation time:
     if cf.num_workers > 1:
         sys.stdout.write(f'Shortest process execution time: {round(min(execution_time_list))}s\n')
         sys.stdout.write(f'Longest process execution time: {round(max(execution_time_list))}s\n')
 
-    # Run thermal calculations:
+    # Run thermal calculations on the final pass:
     if thermal_maps is not None:
         thermal_maps.calculate_thermal_conductivity()
         thermal_maps.calculate_heat_flux_modulus()
@@ -277,6 +356,18 @@ def main(input_file, mode: SimulationMode):
         shutil.copy(input_file, "Results/" + cf.output_folder_name)
     os.chdir("Results/" + cf.output_folder_name)
 
+    # Save the hydrodynamic-drift-field convergence trace (one row per prerun):
+    if drift_convergence:
+        np.savetxt("Data/Drift convergence.csv", np.array(drift_convergence), fmt="%1.4e", delimiter=",",
+                   header="prerun, mean|u_fresh| (m/s), mean|u_field| (m/s), rel_change_of_field", encoding="utf-8")
+    if flux_profiles:
+        prof = np.array(flux_profiles).T                       # rows = x pixels, cols = passes
+        nx = prof.shape[0]
+        x = (np.arange(nx) + 0.5) * cf.width / nx - cf.width / 2
+        header = "x (m), " + ", ".join([f"pass{i + 1}" for i in range(prof.shape[1])])
+        np.savetxt("Data/Drift convergence profiles.csv", np.column_stack([x, prof]), fmt="%1.4e",
+                   delimiter=",", header=header, encoding="utf-8")
+
     # Try to load pre-computed phonon thermal conductivity to enable ZT calculation:
     if mode is SimulationMode.ELECTRON:
         kappa_ph = None