freepaths 2.5.0__tar.gz → 2.6__tar.gz

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

@@ -1,23 +1,22 @@
 Metadata-Version: 2.4
 Name: freepaths
-Version: 2.5.0
+Version: 2.6
 Summary: Phonon Monte Carlo simulator
 Home-page: https://github.com/anufrievroman/freepaths
 Author: Roman Anufriev
 Author-email: anufriev.roman@protonmail.com
-License: GPL
+License-Expression: GPL-3.0-only
 Classifier: Development Status :: 4 - Beta
-Classifier: License :: OSI Approved :: GNU General Public License (GPL)
 Classifier: Environment :: Console
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Utilities
 Requires-Python: ~=3.11
 Description-Content-Type: text/markdown
+License-File: license
 Requires-Dist: numpy
 Requires-Dist: matplotlib
 Requires-Dist: scipy
@@ -28,7 +27,8 @@ Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
-Dynamic: license
+Dynamic: license-file
+Dynamic: license-expression
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -94,6 +94,16 @@ Alternatively, you can run FreePATHS in the mean free path sampling mode, which
 The calculated thermal conductivity will be output in the terminal. However, other statistical quantities and plots will still be calculated and output in the `Results` folder.
 
 
+## Testing
+
+The `tests` folder holds the validation tests that must pass before a new version is published. They run against the source tree, not an installed copy. From the repository root:
+
+```
+pip install pytest
+pytest tests
+```
+
+
 ## Troubleshooting
 
 - [Troubles with installation](https://anufrievroman.gitbook.io/freepaths/installation)

{freepaths-2.5.0 → freepaths-2.6}/README.md

@@ -59,6 +59,16 @@ Alternatively, you can run FreePATHS in the mean free path sampling mode, which
 The calculated thermal conductivity will be output in the terminal. However, other statistical quantities and plots will still be calculated and output in the `Results` folder.
 
 
+## Testing
+
+The `tests` folder holds the validation tests that must pass before a new version is published. They run against the source tree, not an installed copy. From the repository root:
+
+```
+pip install pytest
+pytest tests
+```
+
+
 ## Troubleshooting
 
 - [Troubles with installation](https://anufrievroman.gitbook.io/freepaths/installation)

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

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

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

@@ -149,7 +149,6 @@ class Config:
         self.holes = HOLES
         self.pillars = PILLARS
         self.interfaces = INTERFACES
-        self.bulks = BULKS
 
         # Multiprocessing:
         self.num_workers = NUMBER_OF_PROCESSES

{freepaths-2.5.0 → freepaths-2.6}/freepaths/data.py

@@ -67,6 +67,10 @@ class GeneralData(Data):
         self.final_frequencies = []
         self.initial_energies = []
         self.group_velocities = []
+        # Wavevector of each particle, row-aligned with final_frequencies/group_velocities.
+        # Recorded separately because k cannot be recovered from f and v_g on a curved
+        # dispersion, and the physical wavelength is 2*pi/k (see Phonon.wavelength):
+        self.wavevectors = []
         self.travel_times = []
         self.mean_free_paths = []
         self.thermal_conductivity = []
@@ -86,6 +90,7 @@ class GeneralData(Data):
         else:
             self.final_frequencies.append(pt.f)
             self.group_velocities.append(pt.speed)
+            self.wavevectors.append(pt.k)
             self.branches.append(pt.branch_number)
 
     def save_flight_data(self, flight, mode=None):
@@ -120,6 +125,7 @@ class GeneralData(Data):
         else:
             np.savetxt("Data/All final frequencies.csv", self.final_frequencies, fmt='%2.4e', header="f [Hz]", encoding='utf-8')
             np.savetxt("Data/All group velocities.csv", self.group_velocities, fmt='%.4f', header="Vg [m//s]", encoding='utf-8')
+            np.savetxt("Data/All wavevectors.csv", self.wavevectors, fmt='%2.4e', header="k [1//m]", encoding='utf-8')
         if mode is SimulationMode.PHONON_TRACING:
             np.savetxt("Data/All exit angles.csv", self.exit_angles, fmt='%.4f', header="Angle [rad]", encoding='utf-8')
             np.savetxt("Data/All initial angles.csv", self.initial_angles, fmt='%.4f', header="Angle [rad]", encoding='utf-8')
@@ -147,6 +153,7 @@ class GeneralData(Data):
             'free_paths': self.free_paths,
             'final_frequencies': self.final_frequencies,
             'group_velocities': self.group_velocities,
+            'wavevectors': self.wavevectors,
             'travel_times': self.travel_times,
             'mean_free_paths': self.mean_free_paths,
             'thermal_conductivity': self.thermal_conductivity,
@@ -157,6 +164,63 @@ class GeneralData(Data):
         }
 
 
+class SpecularityData(Data):
+    """
+    Running sums behind the specular scattering probability report (MFP-sampling mode).
+
+    The reported kappa-weighted specularity is a weighted mean over modes,
+    sum(kappa_i * f_i) / sum(kappa_i) with f_i = specular_i / (specular_i + diffuse_i),
+    so it accumulates in four fixed-size arrays and never needs the per-mode tallies
+    kept around. That matters: storing them was one 10-integer row per phonon in memory
+    and on disk, which scales with NUMBER_OF_PARTICLES for a result that is 10 numbers.
+    Arrays are indexed by flight.BOUNDARY_CATEGORIES and merged across the branch
+    workers by Data.read_data, whose "+" is elementwise on numpy arrays.
+    """
+
+    def __init__(self):
+        """Initialize the accumulators, one entry per boundary category"""
+        from freepaths.flight import BOUNDARY_CATEGORIES
+        self.specular_events = np.zeros(len(BOUNDARY_CATEGORIES))
+        self.diffuse_events = np.zeros(len(BOUNDARY_CATEGORIES))
+        self.kappa_weighted_specular = np.zeros(len(BOUNDARY_CATEGORIES))
+        self.kappa_of_scattered = np.zeros(len(BOUNDARY_CATEGORIES))
+
+    def add_particle(self, flight):
+        """Fold one finished flight into the running sums"""
+        events = np.array(flight.boundary_events, dtype=float).reshape(-1, 2)
+        specular, diffuse = events[:, 0], events[:, 1]
+        total = specular + diffuse
+        self.specular_events += specular
+        self.diffuse_events += diffuse
+        # Only modes that actually hit a given boundary enter that boundary's mean:
+        scattered = total > 0
+        kappa = flight.thermal_conductivity
+        self.kappa_weighted_specular[scattered] += kappa * specular[scattered] / total[scattered]
+        self.kappa_of_scattered[scattered] += kappa
+
+    def write_into_files(self):
+        """Write the specular scattering probabilities into a file"""
+        from freepaths.flight import BOUNDARY_CATEGORIES
+        total = self.specular_events + self.diffuse_events
+        with np.errstate(invalid='ignore', divide='ignore'):
+            per_event = 100 * self.specular_events / total
+            per_kappa = 100 * self.kappa_weighted_specular / self.kappa_of_scattered
+        rows = [[per_event[i], per_kappa[i], total[i]] for i in range(len(BOUNDARY_CATEGORIES))]
+        np.savetxt("Data/Specular scattering probability.csv", np.array(rows), fmt='%2.4e', delimiter=',',
+                   header="Boundary: " + ", ".join(BOUNDARY_CATEGORIES)
+                          + "\nSpecular per event [%], Specular kappa-weighted [%], Total events",
+                   encoding='utf-8')
+
+    def dump_data(self):
+        """Return data of a process in the form of a dictionary to be attached to the global data"""
+        return {
+            'specular_events': self.specular_events,
+            'diffuse_events': self.diffuse_events,
+            'kappa_weighted_specular': self.kappa_weighted_specular,
+            'kappa_of_scattered': self.kappa_of_scattered,
+        }
+
+
 class ScatteringData(Data):
     """Statistics of particle scattering events"""
 

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

@@ -129,7 +129,6 @@ INTERFACE_ROUGHNESS              = 0.2e-9
 HOLES                            = []
 PILLARS                          = []
 INTERFACES                       = []
-BULKS                            = []
 
 # Multiprocessing:
 NUMBER_OF_PROCESSES              = 10

{freepaths-2.5.0 → freepaths-2.6}/freepaths/electron.py

@@ -127,15 +127,16 @@ class Electron(Particle):
         """
         self.f = self.energy / h
 
-    def assign_speed(self, material):
+    def speed_in(self, material):
         """
-        Assign speed to an electron using group velocity and considering parabolic energy-k relation and conduction minimum at 0
+        Speed of an electron in the given material from the parabolic energy-k relation,
+        with the conduction minimum at 0
         """
         if self.is_electron_carrier:
             effective_mass = material.effective_electron_dos_mass
         else:
             effective_mass = material.effective_hole_dos_mass
-        self.speed = (2*self.energy/(effective_mass))**(0.5)
+        return (2*self.energy/(effective_mass))**(0.5)
 
     def assign_internal_scattering_time(self, material):
         """

{freepaths-2.5.0 → freepaths-2.6}/freepaths/flight.py

@@ -4,6 +4,13 @@ from math import cos
 import numpy as np
 
 from freepaths.config import cf
+from freepaths.scattering_types import Scattering
+
+
+# Boundary categories tallied per particle by Flight.record_boundary_events. The order
+# fixes the index order of Flight.boundary_events, of the data.SpecularityData
+# accumulators, and of the rows of "Data/Specular scattering probability.csv".
+BOUNDARY_CATEGORIES = ('Side walls', 'Top and bottom walls', 'Hole walls', 'Pillar walls', 'Interfaces')
 
 
 class Path:
@@ -50,6 +57,16 @@ class Flight:
         # impurity) and boundary (diffuse surface) spectra in the MFP-sampling mode:
         self._internal_count = 0
         self._boundary_count = 0
+        # Specular and diffuse boundary event counts of THIS particle, as flat
+        # [specular, diffuse] pairs per entry of BOUNDARY_CATEGORIES. The aggregate
+        # ScatteringData counters cannot answer "how specular is a given mode", because
+        # they sum events over all particles: a mode that scatters diffusely lingers in
+        # the structure and accumulates far more events than one that reflects
+        # specularly and streams straight out. Folded into data.SpecularityData as soon
+        # as the flight ends and then discarded with the Flight, so nothing per-mode
+        # accumulates; only filled in the MFP-sampling mode, which is where it is
+        # reported (see output_info.weighted_specularity_information).
+        self.boundary_events = [0] * (2 * len(BOUNDARY_CATEGORIES))
         self.hole_diff_scattering_angles = []
         self.hole_spec_scattering_angles = []
         self.thermal_conductivity = 0.0
@@ -97,6 +114,19 @@ class Flight:
         if not cf.low_memory_usage:
             self.free_paths.append(self.free_path)
 
+    def record_boundary_events(self, scattering_types):
+        """Tally this timestep's boundary events by category and by specularity."""
+        categories = (scattering_types.walls, scattering_types.top_bottom,
+                      scattering_types.holes, scattering_types.pillars,
+                      # interfaces covers reflection AND transmission, so counting
+                      # interfaces_transmission as well would double-count them:
+                      scattering_types.interfaces)
+        for index, scattering in enumerate(categories):
+            if scattering is Scattering.SPECULAR:
+                self.boundary_events[2 * index] += 1
+            elif scattering is Scattering.DIFFUSE:
+                self.boundary_events[2 * index + 1] += 1
+
     def record_scattering_channel(self, is_internal, is_boundary):
         """Tally the channel of a diffuse event that ends a free-path segment, so the
         total scattering rate can later be split into internal and boundary spectra."""

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

@@ -127,30 +127,3 @@ def alpha_total_2T(theta_i, vg_i, vg_j, rho_i, rho_j, omega_i, omega_j, material
     T2 = P_j * a_s2 + (1 - P_j) * a_d2
 
     return T1 * T2
-
-
-def alpha_total_1T(theta_i, vg_i, vg_j, rho_i, rho_j, omega_i, omega_j, material_i, material_j, branch_number, roughness):
-    """Transmission model for 1 transmission : ex: Si → Ge for small rectangle inside single crystal Si"""
-
-    k_i = get_k_from_omega(omega_i, material_i, branch_number)
-    k_j = get_k_from_omega(omega_j, material_j, branch_number)
-
-    wavelength_i = lambda_from_k(k_i)
-    wavelength_j = lambda_from_k(k_j)
-
-    P_i = math.exp(-16 * math.pi**2 * roughness**2 / wavelength_i**2)
-    P_j = math.exp(-16 * math.pi**2 * roughness**2 / wavelength_j**2)
-
-    try:
-        sin_theta_t = (vg_i / vg_j) * math.sin(theta_i)
-        if abs(sin_theta_t) > 1:
-            return 0.0  # Totle reflection at the entry
-    except:
-        return 0.0
-
-    a_s = alpha_spec(theta_i, vg_i, vg_j, rho_i, rho_j)
-    a_d = alpha_diff(k_i, k_j, P_i, P_j)
-    T_1T = P_i * a_s + (1 - P_i) * a_d
-
-    return T_1T
-

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

@@ -20,7 +20,7 @@ from freepaths.run_particle import run_particle
 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.data import ScatteringData, GeneralData, SegmentData, PathData, TriangleScatteringData, SpecularityData
 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
@@ -87,6 +87,7 @@ def _run_branch(branch_number, shared_list, shared_progress):
     places_stats = TriangleScatteringData()
     path_stats = PathData()
     scatter_maps = ScatteringMap()
+    specularity_stats = SpecularityData()
 
     total_thermal_conductivity = 0.0
     total_kappa_variance = 0.0
@@ -148,6 +149,7 @@ def _run_branch(branch_number, shared_list, shared_progress):
 
         general_stats.save_particle_data(phonon, SimulationMode.PHONON_MFP_SAMPLING)
         general_stats.save_flight_data(flight, SimulationMode.PHONON_MFP_SAMPLING)
+        specularity_stats.add_particle(flight)
 
         if index < cf.output_trajectories_of_first:
             path_stats.save_particle_path(flight)
@@ -165,6 +167,7 @@ def _run_branch(branch_number, shared_list, shared_progress):
         'places_stats': places_stats.dump_data(),
         'path_stats': path_stats.dump_data(),
         'scatter_maps': scatter_maps.dump_data(),
+        'specularity_stats': specularity_stats.dump_data(),
     })
 
 
@@ -227,6 +230,7 @@ def main(input_file, mode: SimulationMode):
     places_stats = TriangleScatteringData()
     path_stats = PathData()
     scatter_maps = ScatteringMap()
+    specularity_stats = SpecularityData()
     total_thermal_conductivity = 0.0
     total_kappa_variance = 0.0
     total_kappa1 = 0.0
@@ -245,6 +249,7 @@ def main(input_file, mode: SimulationMode):
         places_stats.read_data(result['places_stats'])
         path_stats.read_data(result['path_stats'])
         scatter_maps.read_data(result['scatter_maps'])
+        specularity_stats.read_data(result['specularity_stats'])
 
     # Create the output folder and copy input file:
     if not os.path.exists("Results/" + cf.output_folder_name):
@@ -257,6 +262,7 @@ def main(input_file, mode: SimulationMode):
     # Save data and generate plots:
     general_stats.write_into_files(mode)
     scatter_stats.write_into_files()
+    specularity_stats.write_into_files()
     segment_stats.write_into_files()
     if cf.output_scattering_map:
         scatter_maps.write_into_files()
@@ -306,7 +312,7 @@ def main(input_file, mode: SimulationMode):
     plot_data(mode, cf)
 
     output_general_information(start_time, general_stats, mode)
-    output_scattering_information(scatter_stats)
+    output_scattering_information(scatter_stats, specularity_stats, mode)
     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')
     if cf.phonon_hydrodynamic:

{freepaths-2.5.0 → freepaths-2.6}/freepaths/maps.py

@@ -5,6 +5,7 @@ from scipy.constants import k as k_B
 import numpy as np
 from freepaths.config import cf
 from freepaths.options import SimulationMode
+import freepaths.move
 
 class Maps:
     """Parent maps class with functions common to all classes below"""
@@ -182,9 +183,18 @@ class ThermalMaps(Maps):
         This first time step is unique for each phonon. This is done to simulate more relistic continious heat flow.
         """
 
+        # The phonon is recorded at the middle of the step it is about to make, not at its start.
+        # A sample stands for the whole step, and the start of the step is a first-order (left
+        # rectangle) rule: in a temperature gradient it undercounts the heat flux by a fraction
+        # step / (2 * MFP), which made the Fourier kappa low by -10% at MFP/step = 5. The midpoint
+        # is second-order accurate, so the bias disappears (tests/test_end_to_end.py, gray medium):
+        d_x, d_y, _ = freepaths.move.step(pt.theta, pt.phi, pt.speed, cf.timestep)
+        x = pt.x + d_x / 2
+        y = pt.y + d_y / 2
+
         # Calculate the index of the pixel in which we record this phonon:
-        index_x = int(((pt.x + cf.width / 2) * cf.number_of_pixels_x) // cf.width)
-        index_y = int(pt.y // (cf.length / cf.number_of_pixels_y))
+        index_x = int(((x + cf.width / 2) * cf.number_of_pixels_x) // cf.width)
+        index_y = int(y // (cf.length / cf.number_of_pixels_y))
 
         # Prevent error if the phonon is outside the structure:
         if (0 <= index_x < cf.number_of_pixels_x) and (0 <= index_y < cf.number_of_pixels_y):
@@ -215,7 +225,7 @@ class ThermalMaps(Maps):
             # is formed as the ratio to the thermal map (calculate_drift_velocity).
             if self.record_momentum:
                 cos_phi = abs(cos(pt.phi))
-                k_over_omega = material.wavevector(pt.branch_number, pt.f) / (2 * np.pi * pt.f)
+                k_over_omega = pt.k / (2 * np.pi * pt.f)
                 p = energy * k_over_omega
                 self.crystal_momentum_map_x[index_y, index_x] += p * sin(pt.theta) * cos_phi
                 self.crystal_momentum_map_y[index_y, index_x] += p * cos(pt.theta) * cos_phi

{freepaths-2.5.0 → freepaths-2.6}/freepaths/materials.py

@@ -123,10 +123,17 @@ class Material(ABC):
         return d_omega / d_k
 
     def wavevector(self, branch_number, f):
-        """Wavevector magnitude k [1/m] at ordinary frequency f [Hz] on the given branch"""
-        f_branch = self.dispersion[:, branch_number + 1]
+        """
+        Wavevector magnitude k [1/m] at ordinary frequency f [Hz] on the given branch,
+        taken from the tabulated point closest to f. Nearest-point search rather than
+        interpolation for the same reason as in group_velocity(): the SiC/Graphite TA
+        branches are non-monotonic in f. The k = 0 point is excluded from the search so
+        that a finite frequency can never map onto k = 0, which would make the phonon
+        wavelength 2*pi/k infinite.
+        """
+        f_branch = self.dispersion[1:, branch_number + 1]
         nearest = np.abs(f_branch - f).argmin()
-        return self.dispersion[nearest, 0]
+        return self.dispersion[nearest + 1, 0]
 
     def mean_inverse_phase_velocity_sq(self):
         """
@@ -198,6 +205,7 @@ class Material(ABC):
         Assigned attributes (each a list of 3 per-branch arrays, except the
         branch probabilities, which are single arrays of 3 cumulative values):
         - frequencies_table: bin-midpoint frequency [Hz] of each dispersion bin;
+        - wavevector_table: bin-midpoint wavevector k [1/m] of each bin;
         - group_velocity_table: group velocity dw/dk [m/s] of each bin;
         - emission_frequency_probabilities, scattering_frequency_probabilities:
           cumulative probabilities of the frequency bins within each branch;
@@ -206,6 +214,7 @@ class Material(ABC):
           a branch before picking a frequency.
         """
         self.frequencies_table = []
+        self.wavevector_table = []
         self.group_velocity_table = []
         self.emission_frequency_probabilities = []
         self.scattering_frequency_probabilities = []
@@ -234,6 +243,7 @@ class Material(ABC):
             dos = k_mid[valid]**2 * d_k[valid]
 
             self.frequencies_table.append(freqs[valid])
+            self.wavevector_table.append(k_mid[valid])
             self.group_velocity_table.append(group_velocity[valid])
 
             # Cumulative bin weights; the last element is the total weight of
@@ -534,7 +544,7 @@ class SiGe(Material):
     Relaxation time - Umklapp coefficient carried over from the pre-refit Si values
       (Maire et al., Sci. Rep. 7, 41794 (2017) era), impurity/alloy coefficient an
       ad-hoc adaptation of the same; NOT refit against bulk SiGe kappa data, unlike
-      Si (see Data/Fitting_BulkSi/). Treat absolute SiGe kappa values with caution.
+      Si (see FreePATHS_Paper/Data/Fitting_BulkSi/). Treat absolute SiGe kappa values with caution.
     Heat capacity - Fit based on Desai P.D., J. Phys. Chem. Ref. Data 13, 1069 (1984) and Wunderlich, Thermophysical Properties of Materials, Springer (2005)
     Effective masses - linearly interpolated between Si and Ge at x=0.2 (Schaffler, 2001)
     """
@@ -590,7 +600,7 @@ class Diamond(Material):
       momentum-conserving Normal rate.  The Umklapp and Normal constants come from a joint
       Callaway (kappa_1 + kappa_2) fit to the natural type-IIa kappa(T) curve of Onn et al.,
       PRL 68, 2806 (1992) over 10-400 K plus three anchors from Wei et al., PRL 70, 3764
-      (1993); see Data/Fitting_BulkDiamond/fit_bulk_diamond_callaway.py.
+      (1993); see FreePATHS_Paper/Data/Fitting_BulkDiamond/fit_bulk_diamond_callaway.py.
     """
 
     # Carbon isotope masses [amu] for the Tamura mass-variance parameter (12-C defines

{freepaths-2.5.0 → freepaths-2.6}/freepaths/output_info.py

@@ -35,12 +35,12 @@ def output_general_information(start_time, general_stats, mode):
             f'\nLength = {cf.length * 1e9:.1f} nm',
             f'\nWidth = {cf.width * 1e9:.1f} nm',
             f'\nThickness = {cf.thickness * 1e9:.1f} nm\n',
-            f'\nSide wall roughness = {cf.side_wall_roughness * 1e9:.1f} nm',
-            f'\nTop roughness = {cf.top_roughness * 1e9:.1f} nm',
-            f'\nBottom roughness = {cf.bottom_roughness * 1e9:.1f} nm',
-            *([ f'\nHole roughness = {cf.hole_roughness * 1e9:.1f} nm'] if cf.holes else []),
-            *([ f'\nInterface roughness = {cf.interface_roughness * 1e9:.1f} nm'] if cf.interfaces else []),
-            *([ f'\nGrain size = {cf.grain_size * 1e9:.1f} nm, std = {cf.grain_size_std * 1e9:.1f} nm, roughness = {cf.grain_roughness * 1e9:.1f} nm'] if cf.grain_size else []),
+            f'\nSide wall roughness = {cf.side_wall_roughness * 1e9:.3g} nm',
+            f'\nTop roughness = {cf.top_roughness * 1e9:.3g} nm',
+            f'\nBottom roughness = {cf.bottom_roughness * 1e9:.3g} nm',
+            *([ f'\nHole roughness = {cf.hole_roughness * 1e9:.3g} nm'] if cf.holes else []),
+            *([ f'\nInterface roughness = {cf.interface_roughness * 1e9:.3g} nm'] if cf.interfaces else []),
+            *([ f'\nGrain size = {cf.grain_size * 1e9:.1f} nm, std = {cf.grain_size_std * 1e9:.1f} nm, roughness = {cf.grain_roughness * 1e9:.3g} nm'] if cf.grain_size else []),
             '\n',
             f'\n{percentage:.0f}% of particles reached the cold side\n'
             ]
@@ -48,8 +48,51 @@ def output_general_information(start_time, general_stats, mode):
         file.writelines(info)
 
 
-def output_scattering_information(scatter_stats):
+def weighted_specularity_information(specularity_stats):
+    """
+    Specular scattering probability per boundary category (MFP-sampling mode), reported
+    two ways: averaged over events, and over each mode's own specular fraction weighted
+    by that mode's contribution to kappa.
+
+    Fed by the running sums in data.SpecularityData, so nothing per-mode is retained.
+
+    Read the kappa-weighted number. The per-event average answers a different question,
+    and in this mode a misleading one. The particles here are not a thermal population:
+    _run_branch sweeps the dispersion k-grid with one phonon per k-interval and equal
+    weight, and the temperature enters only afterwards, as the heat capacity in the
+    kappa integral. So an average over events is an unweighted average over the whole
+    Brillouin zone, with no temperature dependence whatsoever - half the modes sit
+    beyond k_max/2, where the wavelength is a few angstrom and the Soffer specularity is
+    ~0. It is skewed a second time by residence time: a mode that scatters diffusely
+    lingers in the structure and accumulates hundreds of events, while a specular one
+    streams straight out after a handful.
+
+    Taking each mode's own specular fraction removes the residence-time bias, and
+    weighting those by kappa gives the specularity actually seen by the heat carriers,
+    which does depend on temperature (low T shifts the population to long wavelengths,
+    where surfaces look smooth).
+    """
+    from freepaths.flight import BOUNDARY_CATEGORIES
+    total_events = specularity_stats.specular_events + specularity_stats.diffuse_events
+
+    rows = []
+    for index, name in enumerate(BOUNDARY_CATEGORIES):
+        if total_events[index] == 0:
+            continue
+        per_event = 100 * specularity_stats.specular_events[index] / total_events[index]
+        kappa_total = specularity_stats.kappa_of_scattered[index]
+        per_kappa = (100 * specularity_stats.kappa_weighted_specular[index] / kappa_total
+                     if kappa_total > 0 else float('nan'))
+        rows.append(f'\n  {name + ":":24s}{per_event:6.2f}% per event, {per_kappa:6.2f}% kappa-weighted')
+    if not rows:
+        return []
+
+    return ['\n\nSpecular scattering probability:', *rows, '\n']
+
+
+def output_scattering_information(scatter_stats, specularity_stats=None, mode=None):
     """Calculate and output general statistics on scattering events"""
+    from freepaths.options import SimulationMode
 
     # Calculate the percentage of different scattering events:
     total_wall = np.sum(scatter_stats.wall_diffuse) + np.sum(scatter_stats.wall_specular)
@@ -131,6 +174,11 @@ def output_scattering_information(scatter_stats):
                     f'{refl_on_interf:.2f}% - reflection',
                     ])
 
+    # Per-mode and kappa-weighted specularity, which the per-event percentages above
+    # cannot express (MFP-sampling mode only - it needs the per-mode kappa contributions):
+    if mode is SimulationMode.PHONON_MFP_SAMPLING and specularity_stats is not None:
+        info.extend(weighted_specularity_information(specularity_stats))
+
     # Write the file:
     with open("Information.txt", "a", encoding="utf-8") as file:
         file.writelines(info)

{freepaths-2.5.0 → freepaths-2.6}/freepaths/output_plots.py

@@ -93,11 +93,16 @@ def launch_exit_frequency_distribution_calculation(number_of_nodes):
 
 
 def wavelength_distribution_calculation(number_of_nodes):
-    """Calculate particle wavelength distribution from their frequencies and velocities"""
-    frequencies = np.loadtxt("Data/All final frequencies.csv", encoding='utf-8')
-    speeds = np.loadtxt("Data/All group velocities.csv", encoding='utf-8')
-    wavelengths = np.zeros((len(speeds)))
-    wavelengths[:] = speeds[:] / frequencies[:]
+    """Calculate particle wavelength distribution, lam = 2*pi/k (see Phonon.wavelength)"""
+    try:
+        wavevectors = np.loadtxt("Data/All wavevectors.csv", encoding='utf-8')
+        wavelengths = 2 * np.pi / wavevectors
+    except OSError:
+        # Result folders written before the wavevector was recorded: fall back to the old
+        # v_g/f estimate, which underestimates the wavelength away from the Gamma point.
+        frequencies = np.loadtxt("Data/All final frequencies.csv", encoding='utf-8')
+        speeds = np.loadtxt("Data/All group velocities.csv", encoding='utf-8')
+        wavelengths = speeds / frequencies
     data_range = np.amax(wavelengths)
     distribution = np.zeros((number_of_nodes, 2))
     distribution[:, 0] = np.linspace(0, data_range, number_of_nodes)
@@ -490,7 +495,8 @@ def plot_thermal_map():
     """Plot thermal map as color map"""
     fig = plt.figure()
     thermal_map = np.genfromtxt("Data/Thermal map.csv", unpack=False, delimiter=',', skip_header=0, encoding='utf-8')
-    thermal_map = np.flipud(thermal_map)
+    # A map one pixel wide or long is read back as a 1D array, which imshow rejects:
+    thermal_map = np.flipud(np.reshape(thermal_map, (cf.number_of_pixels_y, cf.number_of_pixels_x)))
     minimum_of_colorbar = 1e-20  # Cannot be zero!
     boundaries = [(-cf.width / 2) * 1e6, (cf.width / 2) * 1e6, 0, cf.length * 1e6]
     plt.imshow(thermal_map, cmap='hot', interpolation='none', extent=boundaries,
@@ -508,6 +514,8 @@ def plot_heat_flux_map(file, label, units="a.u."):
     """Plot heat flux map as color map"""
     fig = plt.figure()
     heat_flux_map = np.genfromtxt(file, unpack=False, delimiter=',', skip_header=0, encoding='utf-8')
+    # A map one pixel wide or long is read back as a 1D array, which imshow rejects:
+    heat_flux_map = np.reshape(heat_flux_map, (cf.number_of_pixels_y, cf.number_of_pixels_x))
     heat_flux_map = np.abs(np.flipud(heat_flux_map))
     minimum_of_colorbar = 1e5
     boundaries = [(-cf.width / 2) * 1e6, (cf.width / 2) * 1e6, 0, cf.length * 1e6]

{freepaths-2.5.0 → freepaths-2.6}/freepaths/output_structure.py

@@ -2,7 +2,7 @@
 
 from matplotlib.patches import Rectangle
 from freepaths.config import cf
-from freepaths.scatterers import HorizontalPlane, VerticalPlane, Bulk
+from freepaths.scatterers import VerticalPlane
 
 def draw_structure_top_view(cf, color_holes="white", color_back="gray"):
     """Draw shape of the structure using patches from matplotlib"""
@@ -34,11 +34,6 @@ def draw_structure_top_view(cf, color_holes="white", color_back="gray"):
             patches.extend(patch if isinstance(patch, list) else [patch])
 
 
-    # Bulks as white patches:
-    for bulk in cf.bulks:
-        patch = bulk.get_patch(color_holes, cf)
-        patches.extend(patch if isinstance(patch, list) else [patch])
-
     # Particle source areas as red patches:
     for source in cf.particles_sources:
         width_x = 1e6 * cf.width / 49 if source.size_x == 0 else 1e6 * source.size_x
@@ -66,10 +61,10 @@ def draw_structure_side_view(cf, color_holes="white", color_back="gray"):
         )
     ]
 
-    # Interfaces as white patches:
-    for interface in cf.interfaces:
-        if isinstance(interface, HorizontalPlane):
-            patch = interface.get_patch(color_holes, cf)
-            patches.extend(patch if isinstance(patch, list) else [patch])
+    # Interfaces as white patches (only HorizontalPlane is visible in this view; it is disabled for now):
+    # for interface in cf.interfaces:
+    #     if isinstance(interface, HorizontalPlane):
+    #         patch = interface.get_patch(color_holes, cf)
+    #         patches.extend(patch if isinstance(patch, list) else [patch])
 
     return patches