penguin.manager module

penguin.manager

Management utilities for running and scoring Penguin emulation experiments.

This module provides functions and classes for calculating experiment scores, handling subprocess execution and timeouts, and managing Panda emulation runs.

Functions

  • calculate_score

Classes

  • PandaRunner

class penguin.manager.PandaRunner[source]

Bases: object

Wrapper class for running penguin_run in a subprocess.

This class manages subprocess execution, timeouts, and signal handling to ensure robust experiment runs even in the presence of crashes or hangs.

catch_and_forward_sigint(p)[source]

Install a SIGINT handler that escalates to SIGKILL on repeated Ctrl+C.

Parameters:

p (subprocess.Popen) – Subprocess to forward signals to.

Return type:

None

run(conf_yaml, proj_dir, out_dir, init=None, timeout=None, show_output=False, verbose=False, resolved_kernel=None)[source]

Run the penguin emulation experiment in a subprocess.

Parameters:

  • conf_yaml (str) – Path to configuration YAML file.

  • proj_dir (str) – Project directory.

  • out_dir (str) – Output directory.

  • init (str or None) – Optional init script.

  • timeout (int or None) – Optional timeout in seconds.

  • show_output (bool) – Whether to show output.

  • verbose (bool) – Whether to enable verbose output.

  • resolved_kernel (str or None) – Optional resolved kernel path.

Raises:

RuntimeError – If the run was not successful.

Return type:

None

penguin.manager.calculate_score(result_dir, have_console=True)[source]

Return a dict of the distinct metrics we care about name: value.

This function loads experiment results and computes a score based on various health and coverage metrics. It handles missing or corrupt files gracefully by logging warnings and defaulting scores to 0.

Parameters:

  • result_dir (str) – Directory containing experiment results.

  • have_console (bool) – Whether console output is available.

Returns:

Dictionary of score metrics.

Raises:

RuntimeError – If the critical .ran file is missing, indicating a failed run.

Return type:

dict[str, int]