Platform and Configuration API

Hardware detection and system information utilities.

This module provides functions to gather system information and detect hardware capabilities, including Intel RAPL support for energy measurement.

pgsi_analyzer.platform.hardware.get_cpu_info() → Dict[str, Any][source]

Get CPU information using psutil (when available) and platform modules.

When psutil is not available (e.g. on PyPy), tries py-cpuinfo if installed, then falls back to platform and os.

Returns:

processor: CPU processor name
cores_physical: Number of physical CPU cores
cores_logical: Number of logical CPU cores
frequency_current: Current CPU frequency (MHz)
architecture: CPU architecture

Return type:

Dictionary containing CPU information

Examples

>>> info = get_cpu_info()
>>> info['processor']
'Intel64 Family 6 Model 142 Stepping 10, GenuineIntel'

pgsi_analyzer.platform.hardware.get_system_info(result_file_path: Path | None = None) → Dict[str, Any][source]

Get comprehensive system information.

Returns a dictionary with system information including CPU, RAM, OS, architecture, and test result file path.

Parameters:

result_file_path – Optional path to test result file. If provided as string, will be converted to Path.

Returns:

CPU: CPU processor name
RAM_GB: Total RAM in GB
OS: Operating system name and version
Architecture: System architecture
Test_Result_File: Path to test result file (if provided)
Platform: Detected platform (‘linux’, ‘windows’, ‘macos’, ‘unknown’)

Return type:

Dictionary containing system information

Examples

>>> info = get_system_info(Path('test.csv'))
>>> info['OS']
'Windows 10'
>>> info['RAM_GB']
16.0

pgsi_analyzer.platform.hardware.check_rapl_support() → bool[source]

Check if Intel RAPL (Running Average Power Limit) is available.

RAPL is only available on Linux systems with Intel x86_64 processors. This function checks both platform compatibility and whether pyRAPL can be imported and initialized.

Returns:: True if RAPL support is available, False otherwise

Examples

>>> check_rapl_support()
False  # On Windows or non-Intel systems
True   # On Linux with Intel x86_64 and pyRAPL installed

pgsi_analyzer.platform.hardware.warn_if_rapl_unavailable(exc: BaseException) → None[source]

Emit a UserWarning when RAPL is unavailable on Linux/Intel due to permissions.

Call this from the pyRAPL setup exception handler. On Linux x86_64, if the exception looks permission-related (PermissionError, errno 13, or message containing “permission”), warns with actionable advice (cap_sys_rawio or root). On other platforms, does nothing so that no permission-specific instructions appear for Windows/macOS.

Path resolution utilities for cross-platform compatibility.

This module provides functions to resolve paths in a platform-independent manner using pathlib.Path, with support for environment variable overrides.

pgsi_analyzer.platform.paths.get_user_data_dir() → Path[source]

Get platform-specific user data directory for pgsi_analyzer.

Returns:

Windows: %APPDATA%/pgsi_analyzer
Linux/macOS: ~/.local/share/pgsi_analyzer

Return type:

Path to user data directory

Examples

>>> get_user_data_dir()
WindowsPath('C:/Users/User/AppData/Roaming/pgsi_analyzer')
PosixPath('/home/user/.local/share/pgsi_analyzer')

pgsi_analyzer.platform.paths.resolve_data_path(base: Path | None = None) → Path[source]

Resolve data directory path with environment variable support.

Checks PGSI_ANALYZER_DATA_DIR environment variable first, then falls back to the user data directory.

Parameters:: base – Optional base path. If provided, returns this path directly.
Returns:: Path to data directory

Examples

>>> resolve_data_path()
WindowsPath('C:/Users/User/AppData/Roaming/pgsi_analyzer/data')

>>> import os
>>> os.environ['PGSI_ANALYZER_DATA_DIR'] = '/custom/path'
>>> resolve_data_path()
PosixPath('/custom/path')

pgsi_analyzer.platform.paths.resolve_benchmark_path(algorithm: str, method: str) → Path[source]

Resolve benchmark file path with environment variable support.

Checks PGSI_ANALYZER_BENCHMARKS_DIR environment variable first, then falls back to current directory.

Parameters:

algorithm – Algorithm name (e.g., ‘binary-trees’, ‘fasta’)
method – Execution method (e.g., ‘cpython’, ‘pypy’, ‘cython’)

Returns:

Path to benchmark directory

Examples

>>> resolve_benchmark_path('binary-trees', 'cpython')
PosixPath('./binary-trees/cpython')

>>> import os
>>> os.environ['PGSI_ANALYZER_BENCHMARKS_DIR'] = '/benchmarks'
>>> resolve_benchmark_path('fasta', 'pypy')
PosixPath('/benchmarks/fasta/pypy')

Configuration module for pgsi-analyzer.

Handles loading of tool paths (Python, PyPy, C compiler) from multiple sources: 1. CLI arguments (highest priority) 2. Environment variables 3. .env file 4. Defaults (system PATH detection)

Environment Variables:: PGSI_PYPY_PATH: Path to PyPy executable PGSI_CC_PATH: Path to C compiler (gcc/cl.exe) PGSI_PYTHON_PATH: Path to Python interpreter for benchmarks PGSI_RUNS: Number of measurement runs per benchmark (set by executor when invoking subprocesses)

class pgsi_analyzer.config.ToolPaths(python: Path, pypy: Path | None = None, c_compiler: Path | None = None)

Bases: object

Container for tool executable paths used during benchmark execution.

c_compiler: Path | None = None

pypy: Path | None = None

python: Path

pgsi_analyzer.config.get_measurement_runs(algorithm: str) → int: Return the number of measurement runs for benchmark decorators. When the executor runs benchmark subprocesses, it sets PGSI_RUNS in the environment; that value is the source of truth. Otherwise fall back to DEFAULT_PARAMS[algorithm][“test_n”] or 50.

pgsi_analyzer.config.load_tool_paths(env_file: Path | None = None, cli_python: str | None = None, cli_pypy: str | None = None, cli_cc: str | None = None, auto_load_env: bool = True) → ToolPaths

Load tool paths from multiple sources in priority order.

Priority (highest to lowest): 1. CLI arguments (cli_python, cli_pypy, cli_cc) 2. Environment variables (PGSI_PYTHON_PATH, PGSI_PYPY_PATH, PGSI_CC_PATH) 3. .env file (if env_file provided or auto_load_env=True) 4. Defaults (sys.executable, PATH detection for pypy/gcc)

Parameters:

env_file – Optional path to .env file. If None and auto_load_env=True, will try to load .env from current working directory.
cli_python – CLI-provided Python path (highest priority)
cli_pypy – CLI-provided PyPy path (highest priority)
cli_cc – CLI-provided C compiler path (highest priority)
auto_load_env – If True, automatically load .env from current directory if env_file is not provided

Returns:

Tuple of (ToolPaths object with resolved paths, path_sources dict for audit). path_sources: {“python”|”pypy”|”c_compiler”: {“path”: str, “source”: “cli”|”env”|”system_default”|”unavailable”}}

pgsi_analyzer.config.verify_tool_paths_against_env(tool_paths: ToolPaths) → list: Compare ToolPaths with os.environ after dotenv load. Returns a list of verification messages (match/mismatch) for testing and diagnostics.