API Reference¶

def get_config_for_frequency(self) -> dict:
    """Gets the antenna configuration for the current frequency.

    Raises:
        ValueError: If no configuration is defined for the frequency.

    Returns:
        The antenna configuration dictionary.
    """
    freq_str = str(self.frequency_mhz)
    if freq_str not in self.antenna_config:
        raise ValueError(f"Antenna configuration not defined for frequency: {self.frequency_mhz} MHz")
    return self.antenna_config[freq_str]

def get_model_type(self) -> str:
    """Returns the antenna model type string."""
    return str(self.get_config_for_frequency().get("model_type"))

def get_source_entity_name(self) -> str:
    """Returns the source entity name from the antenna config."""
    return str(self.get_config_for_frequency().get("source_name"))

def get_centered_antenna_path(self, centered_antennas_dir: str) -> str:
    """Constructs the path to the centered .sab antenna file.

    If the exact frequency file doesn't exist, finds the nearest available frequency
    and shows a warning.

    Args:
        centered_antennas_dir: The directory for centered antenna files.

    Returns:
        The absolute path to the centered antenna model file.

    Raises:
        FileNotFoundError: If no antenna files are found in the directory.
    """
    antenna_filename = f"{self.frequency_mhz}MHz_centered.sab"
    antenna_path = os.path.join(centered_antennas_dir, antenna_filename)

    # Check if exact file exists
    if os.path.exists(antenna_path) and os.path.isfile(antenna_path):
        return antenna_path

    # File doesn't exist, try to find nearest frequency
    logger.warning(f"Antenna file for {self.frequency_mhz} MHz not found: {antenna_path}. Searching for nearest available frequency...")

    # Scan directory for available antenna files
    if not os.path.exists(centered_antennas_dir):
        raise FileNotFoundError(f"Antenna directory does not exist: {centered_antennas_dir}")

    available_files = []
    pattern = re.compile(r"(\d+)MHz_centered\.sab$")

    try:
        for filename in os.listdir(centered_antennas_dir):
            match = pattern.match(filename)
            if match:
                freq = int(match.group(1))
                filepath = os.path.join(centered_antennas_dir, filename)
                if os.path.isfile(filepath):
                    available_files.append((freq, filepath))
    except (OSError, PermissionError) as e:
        raise FileNotFoundError(f"Could not read antenna directory {centered_antennas_dir}: {e}") from e

    if not available_files:
        raise FileNotFoundError(f"No antenna files found in directory: {centered_antennas_dir}")

    # Find nearest frequency
    available_files.sort(key=lambda x: x[0])  # Sort by frequency
    nearest_freq, nearest_path = min(available_files, key=lambda x: abs(x[0] - self.frequency_mhz))

    logger.warning(f"Using antenna file for {nearest_freq} MHz instead of {self.frequency_mhz} MHz. File: {nearest_path}")

    return nearest_path

def set_total_simulations(self, total: int):
    """Sets total simulation count for progress tracking."""
    self.total_simulations = total

def set_project_scope(self, total_projects: int):
    """Sets total project count for progress tracking."""
    self.total_projects = total_projects

def set_current_project(self, project_index: int):
    """Sets the current project index."""
    self.current_project = project_index

def simulation_completed(self):
    """Marks one simulation as completed."""
    self.completed_simulations += 1

def start_stage(self, phase_name: str, total_stages: int = 1):
    """Starts tracking a new phase (setup/run/extract).

    Args:
        phase_name: Phase name like 'setup', 'run', or 'extract'.
        total_stages: Number of stages within this phase.
    """
    self.current_phase = phase_name
    self.phase_start_time = time.monotonic()
    self.phase_skipped = False
    self.completed_stages_in_phase = 0
    self.total_stages_in_phase = total_stages

def end_stage(self):
    """Ends current phase and records its duration for future estimates."""
    if self.phase_start_time:
        elapsed = time.monotonic() - self.phase_start_time

        # For setup phase: if it was cached/skipped, don't add to statistics
        # (cached phases pollute real execution time statistics)
        if self.current_phase == "setup" and self.phase_skipped:
            # Cached setup: don't pollute statistics
            # avg_{phase}_time remains unchanged (uses previous real measurements)
            pass
        else:
            # Real phase: add to statistics and compute simple average for display
            self.subtask_times[self.current_phase].append(elapsed)
            times = self.subtask_times[self.current_phase]
            # Store simple average for pie charts, timings table, etc.
            self.profiling_config[f"avg_{self.current_phase}_time"] = sum(times) / len(times)

    self.current_phase = None
    self.phase_skipped = False  # Reset for next phase

def complete_run_phase(self):
    """Stores the total duration of the 'run' phase from its subtasks."""
    self.run_phase_total_duration = sum(self.subtask_times.get("run_simulation_total", [0]))

def get_weighted_progress(self, phase_name: str, phase_progress_ratio: float) -> float:
    """Calculates overall study progress using phase weights and simulation count.

    This method handles the complexity that different phases (setup, run, extract)
    take different amounts of time. For example, if setup takes 10 minutes, run takes
    2 hours, and extract takes 5 minutes, then the run phase should account for
    roughly 85% of the progress bar, not 33%.

    The calculation works in two parts:
    1. Progress within current simulation: Sums weights of completed phases,
       plus partial weight for the current phase based on its progress ratio.
    2. Overall progress: Divides (completed_simulations + current_sim_progress)
       by total_simulations to get the overall percentage.

    Args:
        phase_name: The name of the current phase ('setup', 'run', or 'extract').
        phase_progress_ratio: Progress within current phase (0.0 = not started,
                             1.0 = fully complete).

    Returns:
        Overall progress percentage (0.0 to 100.0).
    """
    if self.total_simulations == 0:
        return 0.0

    # Progress within the current simulation
    progress_current_sim = 0
    for p, w in self.phase_weights.items():
        if p == phase_name:
            progress_current_sim += w * phase_progress_ratio
            break
        progress_current_sim += w

    # Overall progress
    overall_progress = (self.completed_simulations + progress_current_sim) / self.total_simulations
    # print(f"DEBUG: get_weighted_progress: phase={phase_name}, ratio={phase_progress_ratio:.2f}, completed={self.completed_simulations}, total={self.total_simulations}, progress={overall_progress * 100:.1f}%")
    return overall_progress * 100

def get_subtask_estimate(self, task_name: str) -> float:
    """Retrieves the estimated time for a specific subtask.
    Args:
        task_name: The name of the subtask.
    Returns:
        The estimated duration in seconds.
    """
    return self.profiling_config.get(f"avg_{task_name}", 1.0)

def get_phase_subtasks(self, phase_name: str) -> list:
    """Gets a list of subtasks for a given phase.
    Args:
        phase_name: The name of the phase.
    Returns:
        A list of subtask names.
    """
    subtasks = []
    for key in self.profiling_config.keys():
        if key.startswith(f"avg_{phase_name}_"):
            subtasks.append(key.replace("avg_", ""))
    return subtasks

def get_time_remaining(self, current_stage_progress: float = 0.0) -> float:
    """Estimates total time remaining for the entire study.

    Uses historical timing data to predict how long each phase will take,
    then calculates remaining time by subtracting elapsed time from total
    estimated time. This gives a realistic ETA that accounts for the fact
    that different phases take different amounts of time.

    The calculation considers:
    - Time already spent on fully completed simulations
    - Time spent on phases within the current simulation that are done
    - Estimated time remaining in the current phase (based on progress ratio)
    - Estimated time for all future simulations

    Args:
        current_stage_progress: Progress within current stage (0.0 to 1.0).

    Returns:
        Estimated time remaining in seconds.
    """
    if not self.current_phase or self.total_simulations == 0:
        return 0.0

    # Calculate the total estimated time for one simulation using smart estimates
    total_time_per_sim = 0
    for phase in ["setup", "run", "extract"]:
        if self.execution_control.get(f"do_{phase}", False):
            total_time_per_sim += self._get_smart_phase_estimate(phase)

    # Calculate estimated time remaining in the current simulation
    ordered_phases = [p for p in ["setup", "run", "extract"] if self.execution_control.get(f"do_{p}", False)]
    try:
        current_phase_index = ordered_phases.index(self.current_phase)
    except ValueError:
        current_phase_index = 0

    # Estimated time remaining in current phase (based on progress)
    # Clamp progress to [0.0, 1.0] to handle edge cases
    progress = max(0.0, min(1.0, current_stage_progress))
    current_phase_time = self._get_smart_phase_estimate(self.current_phase)
    time_remaining_in_current_sim = current_phase_time * (1.0 - progress)

    # Add time for phases not yet started in current simulation
    for i in range(current_phase_index + 1, len(ordered_phases)):
        phase = ordered_phases[i]
        time_remaining_in_current_sim += self._get_smart_phase_estimate(phase)

    # Calculate remaining simulations (excluding current one)
    remaining_simulations = self.total_simulations - self.completed_simulations - 1

    # Estimated time remaining = time left in current sim + time for all remaining sims
    eta = time_remaining_in_current_sim + (remaining_simulations * total_time_per_sim)
    return max(0, eta)

@contextlib.contextmanager
def subtask(self, task_name: str):
    """A context manager to time a subtask."""
    self.subtask_stack.append({"name": task_name, "start_time": time.monotonic()})
    try:
        yield
    finally:
        subtask = self.subtask_stack.pop()
        elapsed = time.monotonic() - subtask["start_time"]
        self.subtask_times[subtask["name"]].append(elapsed)
        self.update_and_save_estimates()

def update_and_save_estimates(self):
    """Updates the profiling configuration with the latest average times and saves it.

    This makes the profiler's estimates self-improving over time.
    """
    try:
        with open(self.config_path, "r") as f:
            full_config = json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        full_config = {}

    if self.study_type not in full_config:
        full_config[self.study_type] = {}

    for key, value in self.profiling_config.items():
        if key.startswith("avg_"):
            full_config[self.study_type][key] = round(value, 2)

    for task_name, times in self.subtask_times.items():
        if times:
            avg_task_time = sum(times) / len(times)
            avg_key = f"avg_{task_name}"
            full_config[self.study_type][avg_key] = round(avg_task_time, 2)
            # Also update the in-memory profiling_config so it's available when sent to GUI
            self.profiling_config[avg_key] = round(avg_task_time, 2)

    with open(self.config_path, "w") as f:
        json.dump(full_config, f, indent=4)

def save_estimates(self):
    """Saves the final profiling estimates at the end of the study."""
    self.update_and_save_estimates()