freepaths 2.3.4__tar.gz → 2.4.1__tar.gz

{freepaths-2.3.4 → freepaths-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freepaths
-Version: 2.3.4
+Version: 2.4.1
 Summary: Phonon Monte Carlo simulator
 Home-page: https://github.com/anufrievroman/freepaths
 Author: Roman Anufriev

{freepaths-2.3.4 → freepaths-2.4.1}/freepaths/__main__.py

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

{freepaths-2.3.4 → freepaths-2.4.1}/freepaths/config.py

@@ -71,6 +71,11 @@ class Config:
         self.energy_lower_bound = ENERGY_LOWER_BOUND
         self.energy_step = ENERGY_STEP
         self.electron_mfp = ELECTRON_MFP
+        self.doping_concentration = DOPING_CONCENTRATION
+        self.surface_potential = SURFACE_POTENTIAL
+        self.depletion_doping = DEPLETION_DOPING   # doping for the dead-layer width only (falls back to DOPING_CONCENTRATION)
+        self.depletion_width = 0.0   # [m] carrier dead-layer width; set from the material at simulation start
+        self.electron_mfp_energy_exponent = ELECTRON_MFP_ENERGY_EXPONENT
         self.mean_mapping_constant = MEAN_MAPPING_CONSTANT
         self.is_carrier_electron = IS_CARRIER_ELECTRON
         self.fermi_level_lower_bound = FERMI_LEVEL_LOWER_BOUND
@@ -85,6 +90,7 @@ class Config:
         self.number_of_pixels_y = NUMBER_OF_PIXELS_Y
         self.number_of_virtual_timesteps = NUMBER_OF_VIRTUAL_TIMESTEPS
         self.ignore_faulty_particles = IGNORE_FAULTY_PARTICLES
+        self.gradient_fit_range = GRADIENT_FIT_RANGE
 
         # Material parameters:
         self.media = MEDIA
@@ -92,8 +98,11 @@ class Config:
 
         # Internal scattering:
         self.include_internal_scattering = INCLUDE_INTERNAL_SCATTERING
-        self.use_gray_approximation_mfp = USE_GRAY_APPROXIMATION_MFP
-        self.gray_approximation_mfp = GRAY_APPROXIMATION_MFP
+        self.use_dispersion_heat_capacity = USE_DISPERSION_HEAT_CAPACITY
+        self.max_number_of_scattering_events = MAX_NUMBER_OF_SCATTERING_EVENTS
+        self.grain_size = GRAIN_SIZE
+        self.grain_size_std = GRAIN_SIZE_STD
+        self.grain_roughness = GRAIN_ROUGHNESS
 
         # System dimensions:
         self.thickness = THICKNESS
@@ -157,6 +166,11 @@ class Config:
         if self.number_of_particles < self.output_trajectories_of_first:
             self.output_trajectories_of_first = self.number_of_particles
 
+        if not (0.0 <= self.gradient_fit_range[0] < self.gradient_fit_range[1] <= 1.0):
+            logging.error("Parameter GRADIENT_FIT_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.3.4 → freepaths-2.4.1}/freepaths/data.py

@@ -57,10 +57,14 @@ class GeneralData(Data):
         """Initialize arrays for writing various properties"""
         self.initial_angles = []
         self.exit_angles = []
+        self.launch_frequencies = []
+        self.exit_frequencies = []
         self.hole_diff_scattering_angles = []
         self.hole_spec_scattering_angles = []
         self.free_paths = []
-        self.frequencies = []
+        # Last-known frequency of each particle, paired with group_velocities below
+        # (used for the frequency-velocity/MFP correlation plots, not a true launch value):
+        self.final_frequencies = []
         self.initial_energies = []
         self.group_velocities = []
         self.travel_times = []
@@ -72,7 +76,7 @@ class GeneralData(Data):
         if mode is SimulationMode.ELECTRON:
             self.initial_energies.append(pt.energy)
         else:
-            self.frequencies.append(pt.f)
+            self.final_frequencies.append(pt.f)
             self.group_velocities.append(pt.speed)
 
     def save_flight_data(self, flight, mode=None):
@@ -83,6 +87,8 @@ class GeneralData(Data):
         if mode is SimulationMode.PHONON_TRACING:
             self.initial_angles.append(flight.initial_theta)
             self.exit_angles.append(flight.exit_theta)
+            self.launch_frequencies.append(flight.initial_frequency)
+            self.exit_frequencies.append(flight.exit_frequency)
             self.hole_diff_scattering_angles.extend(flight.hole_diff_scattering_angles)
             self.hole_spec_scattering_angles.extend(flight.hole_spec_scattering_angles)
         self.travel_times.append(flight.travel_time)
@@ -101,11 +107,13 @@ class GeneralData(Data):
         if mode is SimulationMode.ELECTRON:
             np.savetxt("Data/All initial energies.csv", self.initial_energies, fmt='%2.4e', header="Energy [J]", encoding='utf-8')
         else:
-            np.savetxt("Data/All initial frequencies.csv", self.frequencies, fmt='%2.4e', header="f [Hz]", encoding='utf-8')
+            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')
         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')
+            np.savetxt("Data/All launch frequencies.csv", self.launch_frequencies, fmt='%2.4e', header="f [Hz]", encoding='utf-8')
+            np.savetxt("Data/All exit frequencies.csv", self.exit_frequencies, fmt='%2.4e', header="f [Hz]", encoding='utf-8')
             if cf.holes:
                 np.savetxt("Data/All hole diffuse scattering angles.csv", self.hole_diff_scattering_angles, fmt='%.4f', header="Angle [rad]", encoding='utf-8')
                 np.savetxt("Data/All hole specular scattering angles.csv", self.hole_spec_scattering_angles, fmt='%.4f', header="Angle [rad]", encoding='utf-8')
@@ -118,10 +126,12 @@ class GeneralData(Data):
         return {
             'initial_angles': self.initial_angles,
             'exit_angles': self.exit_angles,
+            'launch_frequencies': self.launch_frequencies,
+            'exit_frequencies': self.exit_frequencies,
             'hole_diff_scattering_angles': self.hole_diff_scattering_angles,
             'hole_spec_scattering_angles': self.hole_spec_scattering_angles,
             'free_paths': self.free_paths,
-            'frequencies': self.frequencies,
+            'final_frequencies': self.final_frequencies,
             'group_velocities': self.group_velocities,
             'travel_times': self.travel_times,
             'mean_free_paths': self.mean_free_paths,

freepaths-2.4.1/freepaths/default_config.py

@@ -0,0 +1,164 @@
+"""Default config file"""
+
+import numpy as np
+from scipy.constants import k, electron_volt
+from freepaths.sources import Source
+
+
+# General parameters:
+OUTPUT_FOLDER_NAME               = "Si nanowire at 300 K"
+NUMBER_OF_PARTICLES              = 10000
+NUMBER_OF_NODES                  = 400
+T                                = 300
+OUTPUT_SCATTERING_MAP            = False
+OUTPUT_TRAJECTORIES_OF_FIRST     = 20
+OUTPUT_STRUCTURE_COLOR           = "#F0F0F0"
+NUMBER_OF_LENGTH_SEGMENTS        = 10
+LOW_MEMORY_USAGE                 = False
+
+# Time parameters:
+TIMESTEP                         = 2e-12
+NUMBER_OF_TIMESTEPS              = 200000
+NUMBER_OF_VIRTUAL_TIMESTEPS      = NUMBER_OF_TIMESTEPS * 3
+NUMBER_OF_TIMEFRAMES             = 8
+NUMBER_OF_STABILIZATION_TIMEFRAMES = 5
+
+# Electron parameters [eV]
+IS_CARRIER_ELECTRON              = True
+ENERGY_UPPER_BOUND               = 350e-3
+ENERGY_LOWER_BOUND               = 0
+ENERGY_STEP                      = 5e-3
+
+ELECTRON_MFP                     = 10e-9 # [m] crystal (acoustic-phonon-limited) MFP, energy-independent
+# Ionized-impurity scattering: if DOPING_CONCENTRATION > 0, the MFP becomes energy-
+# and doping-dependent via Matthiessen's rule, 1/Lambda_tot(E) = 1/ELECTRON_MFP +
+# 1/Lambda_ii(E), where Lambda_ii is the Brooks-Herring contribution from N_I ionized
+# dopants (screened Coulomb scattering). This shortens the MFP with doping and raises
+# the Seebeck coefficient. 0 -> pure crystal MFP.
+DOPING_CONCENTRATION             = 0.0   # [m^-3] ionized-impurity (dopant) concentration N_I
+# Surface depletion of carriers: with SURFACE_POTENTIAL > 0, a dead layer of width
+# W = sqrt(2*eps_s*phi_s/(e*N_D)) (abrupt-junction depletion) is excluded around every
+# free surface (walls, top/bottom, hole edges) for CARRIERS ONLY. phi_s is the surface
+# band bending set by Fermi-level pinning at the native oxide / surface states. Needs
+# a doping (DEPLETION_DOPING or DOPING_CONCENTRATION) and the material dielectric
+# constant. 0 -> no depletion.
+SURFACE_POTENTIAL                = 0.0   # [eV] surface band bending phi_s (0 = off)
+# Doping used ONLY for the depletion-width formula. If 0/None it falls back to
+# DOPING_CONCENTRATION. Set this (and leave DOPING_CONCENTRATION = 0) to add a surface
+# dead layer from the real doping WITHOUT engaging Brooks-Herring, i.e. to isolate the
+# depletion effect on top of a constant-MFP transport calibration.
+DEPLETION_DOPING                 = 0.0   # [m^-3] dopant concentration for the dead-layer width only
+# Legacy phenomenological energy dependence (only used when DOPING_CONCENTRATION = 0):
+# Lambda(E) = ELECTRON_MFP * (E/kT)^p.  p=0 -> constant; p=2 -> ionized-impurity-like.
+ELECTRON_MFP_ENERGY_EXPONENT     = 0.0
+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
+OUTPUT_ANIMATION_FPS             = 24
+
+# Map & profiles parameters:
+NUMBER_OF_PIXELS_X               = 7
+NUMBER_OF_PIXELS_Y               = 67
+IGNORE_FAULTY_PARTICLES          = False
+GRADIENT_FIT_RANGE               = (0.1, 0.9)
+
+# Material parameters:
+MEDIA                            = "Si"
+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):
+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
+
+# System dimensions [m]:
+THICKNESS                        = 150e-9
+WIDTH                            = 200e-9
+LENGTH                           = 2000e-9
+IS_TWO_DIMENSIONAL_MATERIAL      = False
+INCLUDE_RIGHT_SIDEWALL           = True
+INCLUDE_LEFT_SIDEWALL            = True
+INCLUDE_TOP_SIDEWALL             = False
+INCLUDE_BOTTOM_SIDEWALL          = False
+
+# Hot and cold sides [m]:
+COLD_SIDE_POSITION_TOP           = True
+COLD_SIDE_POSITION_BOTTOM        = False
+COLD_SIDE_POSITION_RIGHT         = False
+COLD_SIDE_POSITION_LEFT          = False
+HOT_SIDE_POSITION_TOP            = False
+HOT_SIDE_POSITION_BOTTOM         = True
+HOT_SIDE_POSITION_RIGHT          = False
+HOT_SIDE_POSITION_LEFT           = False
+RETHERMALIZATION_ON_HOT_SIDES    = True
+
+# Particle source:
+PARTICLE_SOURCES = [Source(x=0, y=0, z=0, size_x=0,  size_y=0, size_z=0, angle_distribution="random", angle=0)]
+
+# Roughness [m]:
+SIDE_WALL_ROUGHNESS              = 2e-9
+HOLE_ROUGHNESS                   = 2e-9
+PILLAR_ROUGHNESS                 = 2e-9
+TOP_ROUGHNESS                    = 0.2e-9
+BOTTOM_ROUGHNESS                 = 0.2e-9
+PILLAR_TOP_ROUGHNESS             = 0.2e-9
+INTERFACE_ROUGHNESS              = 0.2e-9
+
+# Holes and pillars:
+HOLES                            = []
+PILLARS                          = []
+INTERFACES                       = []
+BULKS                            = []
+
+# Multiprocessing:
+NUMBER_OF_PROCESSES              = 10

freepaths-2.4.1/freepaths/electron.py

@@ -0,0 +1,149 @@
+"""This module provides electron class which generates and moves an electron"""
+
+from random import choice, random
+from scipy.constants import h, k, hbar, electron_volt, elementary_charge, epsilon_0
+from freepaths.config import cf
+from freepaths.particle import Particle
+from freepaths.options import ParticleType
+
+import numpy as np
+
+
+def _carrier_dos_mass(material):
+    """DOS effective mass of the active carrier (electron or hole)."""
+    return material.effective_electron_dos_mass if cf.is_carrier_electron else material.effective_hole_dos_mass
+
+
+def depletion_width(material):
+    """Surface-depletion (dead-layer) width for carriers, from the abrupt-junction
+    depletion approximation W = sqrt(2*eps_s*phi_s/(e*N_D)), with phi_s = SURFACE_POTENTIAL
+    the surface band bending (eV, used as volts), N_D the doping, and eps_s the static
+    permittivity of the material. Carriers are excluded within W of every free surface
+    (Fermi-level pinning by surface states / native oxide). Returns 0 if there is no
+    doping or no surface potential. Reference: any semiconductor-device text (e.g. Sze),
+    surface-depletion / dead-layer model for nanostructure conductivity.
+
+    N_D is DEPLETION_DOPING if set, otherwise DOPING_CONCENTRATION. The separate
+    DEPLETION_DOPING lets the dead layer be driven by the real doping WITHOUT also
+    engaging the Brooks-Herring ionized-impurity MFP (which keys off DOPING_CONCENTRATION),
+    i.e. to isolate the depletion effect on top of a constant-MFP transport calibration."""
+    N_I = cf.depletion_doping if cf.depletion_doping else cf.doping_concentration
+    phi = cf.surface_potential
+    eps_r = getattr(material, 'dielectric_constant', None)
+    if not N_I or phi <= 0 or not eps_r:
+        return 0.0
+    eps = eps_r * epsilon_0
+    return np.sqrt(2.0 * eps * phi / (elementary_charge * N_I))
+
+
+def electron_mfp(energy, material):
+    """Energy- and doping-dependent carrier mean free path via Matthiessen's rule:
+        1/Lambda_tot(E) = 1/Lambda_ac + 1/Lambda_ii(E, N_I).
+
+    Lambda_ac = ELECTRON_MFP is the crystal (acoustic-phonon-limited) MFP, taken
+    energy-independent (for acoustic deformation-potential scattering tau ~ E^-1/2
+    cancels v ~ E^1/2, so Lambda = v*tau ~ E^0). Lambda_ii is the ionized-impurity
+    contribution from the Brooks-Herring model: screened Coulomb scattering off the
+    DOPING_CONCENTRATION ionized dopants, with tau_ii ~ E^{3/2} in the weak-screening
+    limit. Ionized impurities thus scatter LOW-energy carriers most, shortening the
+    MFP with doping and making scattering energy-selective, which raises the Seebeck
+    coefficient. DOPING_CONCENTRATION = 0 recovers the crystal MFP (optionally with
+    the legacy phenomenological exponent ELECTRON_MFP_ENERGY_EXPONENT).
+
+    Applies identically to electrons and holes: the carrier's own DOS effective mass
+    is used (chosen by IS_CARRIER_ELECTRON) and N_I is the density of ionized donors
+    (n-type) or acceptors (p-type). Reference: Brooks-Herring; Chattopadhyay &
+    Queisser, Rev. Mod. Phys. 53, 745 (1981). `energy` in J, scalar or array."""
+    lambda_ac = cf.electron_mfp
+    N_I = cf.doping_concentration
+
+    if not N_I:
+        # No ionized impurities: crystal MFP, with optional legacy power law.
+        p = cf.electron_mfp_energy_exponent
+        if p == 0:
+            return lambda_ac
+        return lambda_ac * (energy / (k * cf.temp)) ** p
+
+    # Brooks-Herring ionized-impurity MFP (Matthiessen-combined with the acoustic MFP):
+    energy = np.maximum(energy, 1e-4 * elementary_charge)   # guard against E -> 0
+    m_star = _carrier_dos_mass(material)
+    eps = material.dielectric_constant * epsilon_0
+    T = cf.temp
+    # Debye screening from the free carriers (n = N_I, full activation): 1/L_D^2 = e^2 n / (eps kB T)
+    inv_screen_length_sq = elementary_charge**2 * N_I / (eps * k * T)
+    b = 8.0 * m_star * energy / (hbar**2 * inv_screen_length_sq)     # b = (2k/beta)^2
+    screening = np.maximum(np.log1p(b) - b / (1.0 + b), 1e-12)
+    inv_tau_ii = (N_I * elementary_charge**4) / (16.0 * np.pi * np.sqrt(2.0 * m_star) * eps**2 * energy**1.5) * screening
+    v = np.sqrt(2.0 * energy / m_star)
+    lambda_ii = v / inv_tau_ii                                        # = v * tau_ii
+    return 1.0 / (1.0 / lambda_ac + 1.0 / lambda_ii)
+
+
+class Electron(Particle):
+    """An electron particle"""
+
+    def __init__(self, material):
+        super().__init__()
+
+        # Assign particle type
+        self.type = ParticleType.ELECTRON
+        self.is_electron_carrier = cf.is_carrier_electron # assign electron or hole behavior
+
+        source = choice(cf.particles_sources)
+        while True:
+            self.x, self.y, self.z = source.generate_coordinates()
+            is_in_hole = any(hole.is_inside(self.x, self.y, None, cf) for hole in cf.holes)
+            if not is_in_hole:
+                break
+
+        # Assign initial angles
+        self.theta, self.phi = source.generate_angles()
+        self.correct_angle()
+        if cf.is_two_dimensional_material:
+            self.phi, self.z = 0.0, 0.0
+
+        self.assign_energy()
+        self.assign_frequency(material)
+        self.assign_speed(material)
+        self.assign_internal_scattering_time(material)
+
+    def assign_energy(self):
+        """
+        Assign energy uniformly to an electron based on temperature.
+        Conduction minimum is considered at 0 energy by convention.
+        """
+        num_energy_points = int((cf.energy_upper_bound-cf.energy_lower_bound)/cf.energy_step)
+        # Keep energy in J for other computations
+        self.energy = np.random.choice(np.linspace(cf.energy_lower_bound, cf.energy_upper_bound - cf.energy_step, num_energy_points)) * electron_volt + cf.energy_step * electron_volt
+
+
+    @property
+    def wavelength(self):
+        raise Exception("Electron wavelength undefined")
+
+    def assign_frequency(self, material):
+        """
+        Conduction minimum is 0 by convention
+        """
+        self.f = self.energy / h
+
+    def assign_speed(self, material):
+        """
+        Assign speed to an electron using group velocity and considering parabolic energy-k relation and 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)
+
+    def assign_internal_scattering_time(self, material):
+        """
+        Determine relaxation time after which this particle will undergo internal scattering.
+        Considering only elasctic scattering between electrons and phonons and thus a constant MFP.
+        With ELECTRON_MFP_ENERGY_EXPONENT != 0 the MFP becomes energy-dependent
+        (see electron_mfp_at_energy); scattering stays elastic so the electron's energy,
+        and hence its MFP, is fixed for the whole flight.
+        """
+        mfp = electron_mfp(self.energy, material)
+        self.time_of_internal_scattering = -np.log(random()) * (mfp / self.speed)

{freepaths-2.3.4 → freepaths-2.4.1}/freepaths/flight.py

@@ -3,21 +3,23 @@
 from math import cos
 import numpy as np
 
+from freepaths.config import cf
+
 
 class Path:
     """Particle path coordinates"""
 
     def __init__(self, x_init, y_init, z_init):
         """Initialize a path"""
-        self.x = np.array([x_init])
-        self.y = np.array([y_init])
-        self.z = np.array([z_init])
+        self.x = [x_init]
+        self.y = [y_init]
+        self.z = [z_init]
 
     def add_point(self, x_new, y_new, z_new):
         """Add a point to the particle path"""
-        self.x = np.append(self.x, x_new)
-        self.y = np.append(self.y, y_new)
-        self.z = np.append(self.z, z_new)
+        self.x.append(x_new)
+        self.y.append(y_new)
+        self.z.append(z_new)
 
     @property
     def number_of_path_points(self):
@@ -36,21 +38,30 @@ class Flight:
         self.initial_theta = self.particle.theta
         self.path = Path(self.particle.x, self.particle.y, self.particle.z)
         self.exit_theta = 0.0
+        self.exit_frequency = 0.0
         self.free_path = 0.0
         self.travel_time = 0.0
         self.time_since_previous_scattering = 0.0
         self.free_paths = []
+        self._mfp_sum = 0.0
+        self._mfp_count = 0
         self.hole_diff_scattering_angles = []
         self.hole_spec_scattering_angles = []
         self.thermal_conductivity = 0.0
     @property
     def mean_free_path(self):
         """Mean value of all free flights"""
-        try:
-            mfp = sum(self.free_paths)/len(self.free_paths)
-        except ZeroDivisionError:
-            mfp = 0
-        return mfp
+        return self._mfp_sum / self._mfp_count if self._mfp_count else 0
+
+    @property
+    def mean_free_path_sem(self):
+        """Standard error of the mean free path (MFP sampling mode only). Assumes
+        individual free-path segments are exponentially distributed (the natural
+        assumption for Poisson-process intrinsic scattering: coefficient of
+        variation = 1, i.e. std = mean), so SEM = mean_free_path / sqrt(n)."""
+        if self._mfp_count < 1:
+            return 0.0
+        return self.mean_free_path / (self._mfp_count ** 0.5)
 
     def add_point_to_path(self):
         """Add a scattering point to the path"""
@@ -58,7 +69,10 @@ class Flight:
 
     def save_free_paths(self):
         """Save current free path to the list of free paths"""
-        self.free_paths.append(self.free_path)
+        self._mfp_sum += self.free_path
+        self._mfp_count += 1
+        if not cf.low_memory_usage:
+            self.free_paths.append(self.free_path)
 
     def save_hole_diff_scattering_angle(self, angle):
         """Save angle of diffuse scattering from the hole"""
@@ -73,10 +87,15 @@ class Flight:
         self.time_since_previous_scattering = 0.0
         self.free_path = 0.0
 
-    def finish(self, step, timestep):
-        """Finish the flight and record final state"""
+    def finish(self, step, timestep, reached_cold_side=False):
+        """Finish the flight and record final state. travel_time is only set when
+        the particle genuinely reached the cold side - it means "time to cold side",
+        so leaving it at 0 for other exits (e.g. the MFP-sampling scattering-event
+        cap) keeps that meaning intact instead of recording a meaningless duration."""
         self.exit_theta = self.particle.theta
-        self.travel_time = step * timestep
+        self.exit_frequency = self.particle.f
+        if reached_cold_side:
+            self.travel_time = step * timestep
 
     def add_step(self, timestep):
         """Increase parameters of the flight by length of one step"""

{freepaths-2.3.4 → freepaths-2.4.1}/freepaths/main_mfp_sampling.py

@@ -99,6 +99,7 @@ def _run_branch(branch_number, shared_list, shared_progress):
     scatter_maps = ScatteringMap()
 
     total_thermal_conductivity = 0.0
+    total_kappa_variance = 0.0
     last_pct = -1
 
     for index in range(cf.number_of_particles):
@@ -112,9 +113,9 @@ def _run_branch(branch_number, shared_list, shared_progress):
         d_k_vector = material.dispersion[index + 1, 0] - material.dispersion[index, 0]
 
         # Initialise phonon at this k-point and run it through the geometry:
-        phonon = Phonon(material, branch_number, index)
+        phonon = Phonon(material, SimulationMode.PHONON_MFP_SAMPLING, branch_number, index)
         flight = Flight(phonon)
-        run_particle(phonon, flight, scatter_stats, places_stats, segment_stats, None, scatter_maps, material)
+        run_particle(phonon, flight, scatter_stats, places_stats, segment_stats, None, scatter_maps, material, SimulationMode.PHONON_MFP_SAMPLING)
 
         # Mode heat capacity (Ref. PRB 88 155318, 2013):
         omega = 2 * math.pi * phonon.f
@@ -126,6 +127,12 @@ def _run_branch(branch_number, shared_list, shared_progress):
         flight.thermal_conductivity = (1 / (6 * math.pi**2)) * c_p * phonon.speed**2 * mean_relax_time * k_vector**2 * d_k_vector
         total_thermal_conductivity += flight.thermal_conductivity
 
+        # 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:
+            kappa_relative_sem = flight.mean_free_path_sem / flight.mean_free_path
+            total_kappa_variance += (flight.thermal_conductivity * kappa_relative_sem) ** 2
+
         general_stats.save_particle_data(phonon, SimulationMode.PHONON_MFP_SAMPLING)
         general_stats.save_flight_data(flight, SimulationMode.PHONON_MFP_SAMPLING)
 
@@ -135,6 +142,7 @@ def _run_branch(branch_number, shared_list, shared_progress):
     # Push this branch's results to the shared list for the main process to collect:
     shared_list.append({
         'total_thermal_conductivity': total_thermal_conductivity,
+        'total_kappa_variance': total_kappa_variance,
         'scatter_stats': scatter_stats.dump_data(),
         'general_stats': general_stats.dump_data(),
         'segment_stats': segment_stats.dump_data(),
@@ -144,6 +152,21 @@ def _run_branch(branch_number, shared_list, shared_progress):
     })
 
 
+def calculate_porosity(grid_points=300):
+    """Calculate the porosity (hole area fraction) of the structure by sampling
+    the hole shapes on a regular grid. Holes partially outside the simulation
+    domain are accounted for with their inside part only."""
+    if not cf.holes:
+        return 0.0
+    xs = np.linspace(-cf.width / 2, cf.width / 2, grid_points)
+    ys = np.linspace(0, cf.length, grid_points)
+    inside = 0
+    for x in xs:
+        for y in ys:
+            inside += any(hole.is_inside(x, y, None, cf) for hole in cf.holes)
+    return inside / (grid_points * grid_points)
+
+
 def main(input_file, mode: SimulationMode):
     """Integrate the phonon dispersion over all three branches in parallel to get
     the bulk thermal conductivity via the MFP-sampling method."""
@@ -151,7 +174,7 @@ def main(input_file, mode: SimulationMode):
     print(f'Mean free path sampling of {Fore.GREEN}{cf.output_folder_name}{Style.RESET_ALL}')
     start_time = time.time()
 
-    branch_names = get_media_class(cf.media).branch_names
+    branch_names = get_media_class(cf.media).dispersion_branch_names
     n_branches = len(branch_names)
 
     # Spawn one worker process per polarization branch, all running concurrently:
@@ -189,9 +212,11 @@ def main(input_file, mode: SimulationMode):
     path_stats = PathData()
     scatter_maps = ScatteringMap()
     total_thermal_conductivity = 0.0
+    total_kappa_variance = 0.0
 
     for result in shared_list:
         total_thermal_conductivity += result['total_thermal_conductivity']
+        total_kappa_variance += result['total_kappa_variance']
         scatter_stats.read_data(result['scatter_stats'])
         general_stats.read_data(result['general_stats'])
         segment_stats.read_data(result['segment_stats'])
@@ -218,14 +243,39 @@ def main(input_file, mode: SimulationMode):
     if cf.output_path_animation:
         create_animation()
 
-    np.savetxt("Data/Thermal conductivity from MFP.csv", np.array([total_thermal_conductivity]), fmt='%2.4e', header="K [W/mK]", encoding='utf-8')
+    # The MFP-sampling integral uses the bulk DoS with boundary-limited free paths,
+    # so total_thermal_conductivity is the conductivity of the solid material
+    # (MFP suppression only, no volume removed by the holes). To obtain the
+    # effective conductivity of the porous structure, it is scaled by the Eucken
+    # factor F = (1 - phi) / (1 + phi/2), where phi is the porosity:
+    porosity = calculate_porosity()
+    eucken_factor = (1 - porosity) / (1 + porosity / 2)
+    effective_thermal_conductivity = total_thermal_conductivity * eucken_factor
+
+    header = "K_material [W/mK], Porosity, Eucken factor, K_effective [W/mK]"
+    np.savetxt("Data/Thermal conductivity from MFP.csv",
+               np.array([[total_thermal_conductivity, porosity, eucken_factor, effective_thermal_conductivity]]),
+               fmt='%2.4e', delimiter=',', header=header, encoding='utf-8')
+
+    # Kept in its own file rather than appended to "Thermal conductivity from MFP.csv",
+    # since several plotting scripts index into that file positionally (incl. by
+    # [-1] for the last column), which a trailing column would silently break:
+    kappa_sem = total_kappa_variance ** 0.5
+    effective_kappa_sem = kappa_sem * eucken_factor
+    np.savetxt("Data/Thermal conductivity from MFP uncertainty.csv",
+               np.array([[kappa_sem, effective_kappa_sem]]),
+               fmt='%2.4e', delimiter=',',
+               header="K_material SEM [W/mK], K_effective SEM [W/mK]", encoding='utf-8')
 
     sys.stdout.write("\rAnalyzing the data...")
     plot_data(mode, cf)
 
-    output_general_information(start_time)
+    output_general_information(start_time, general_stats, mode)
     output_scattering_information(scatter_stats)
-    output_parameter_warnings(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')
-    sys.stdout.write(f"\rThermal conductivity = {Fore.GREEN}{total_thermal_conductivity:.5f}{Style.RESET_ALL} W/m·K\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.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")
     sys.stdout.write(f"\r{Fore.BLUE}Thank you for using FreePATHS{Style.RESET_ALL}\n\n")