Implementation:Interpretml Interpret Powerlift RunTrials

Knowledge Sources	Interpretml Interpret
Domains	Benchmarking, Execution, Worker
Last Updated	2026-02-07 12:00 GMT

Overview

Trial worker entry point that fetches, compiles, and executes benchmark trial functions from the database in a loop, with timeout enforcement, error handling, and support for both local and containerized execution.

Description

This module serves as the core trial execution engine for Powerlift. The run_trials() function implements the worker loop:

1. Trial function retrieval -- Fetches the trial function source code from the database (or from a local cached file for containerized runners). The code is parsed via ast.parse(), validated to be a module containing a function definition, and dynamically compiled and executed.
2. Trial picking -- Calls store.pick_trial() in a loop to claim the next available trial for the given experiment and runner. Returns False when no more work is available.
3. Timed execution -- Wraps each trial function call in timed_run() to enforce the configured timeout. If a timeout occurs, raises a RuntimeError with the duration.
4. Error recording -- On exception, records a detailed error message including task origin, name, method, metadata, and the full traceback. Calls store.end_trial() to finalize the trial record.
5. Garbage collection -- Explicitly calls gc.collect() between trials to clean up cyclic garbage from previous trial functions.

The module also implements __main__ behavior for containerized execution, reading configuration from environment variables (EXPERIMENT_ID, RUNNER_ID, DB_URL, TIMEOUT) and using exit codes to signal completion status (0 = done, 1 = more work, other = error).

Usage

This module is invoked in two ways: directly by the LocalMachine executor via runner.run_trials(), or as a command-line entry point via python -m powerlift.run in Docker/ACI containers. It is the central execution point for all Powerlift benchmark trials.

Code Reference

Source Location

• Repository: Interpretml_Interpret
• File: python/powerlift/powerlift/run/__main__.py

Signature

def run_trials(
    experiment_id,
    runner_id,
    db_url,
    timeout,
    raise_exception,
    print_exceptions=False,
    max_attempts=5,
    return_after_one=False,
):
    """Runs trials. Includes wheel installation and timeouts."""
    ...

Import

from powerlift.run.__main__ import run_trials

I/O Contract

Inputs

Name	Type	Required	Description
experiment_id	int/str	Yes	Identifier of the experiment whose trials to run
runner_id	int/str	Yes	Unique identifier for this runner instance
db_url	str	Yes	Database connection URI
timeout	float	Yes	Maximum execution time in seconds per trial
raise_exception	bool	Yes	Whether to propagate exceptions to the caller
print_exceptions	bool	No	Whether to print exception details to stdout (default: False)
max_attempts	int	No	Maximum database retry attempts (default: 5)
return_after_one	bool	No	Return after completing one trial instead of looping (default: False)

Outputs

Name	Type	Description
return value	bool	False if no more work is available; True if return_after_one and a trial was completed
Exit code 0	int	No more work available (when run as __main__)
Exit code 1	int	More work available (when run as __main__)
Exit code 64	int	BaseException occurred (when run as __main__)
Exit code 65	int	Exception occurred (when run as __main__)

Usage Examples

# Direct invocation from Python (used by LocalMachine executor)
from powerlift.run.__main__ import run_trials

result = run_trials(
    experiment_id=1,
    runner_id=0,
    db_url="postgresql://user:pass@host/db",
    timeout=3600,
    raise_exception=False,
    print_exceptions=True,
)

# Container invocation via environment variables
export EXPERIMENT_ID=1
export RUNNER_ID=0
export DB_URL="postgresql://user:pass@host/db"
export TIMEOUT=3600
python -m powerlift.run

Related Pages

• Interpretml_Interpret_Powerlift_Executor -- Base class providing timed_run used by this module
• Interpretml_Interpret_Powerlift_LocalMachine -- Executor that calls run_trials directly
• Interpretml_Interpret_Powerlift_InsecureDocker -- Executor that invokes this as python -m powerlift.run in containers
• Interpretml_Interpret_Powerlift_Schema -- Trial and Experiment models queried by the Store
• Interpretml_Interpret_Powerlift_RunAzureCI -- Azure CI runner that provisions containers invoking this module