API Documentation#

compileiq.ciq#

class compileiq.ciq.Search#

Bases: BaseModel

Your main class to start a CompileIQ search. Instantiate this class with your objective function, search space, and search configuration, then call start() to run the search and retrieve the results.

field objective_function: Callable [Required]#: A Python function that runs the task and returns score(s). The function must have all imports and objects declared inside.

field search_space: Dict[str, Any] | Path | List[Dict | Path | SearchSpaceProvider] | SearchSpaceProvider [Required]#: The user search space for CompileIQ to explore. The objective function will receive a single set following this declaration. Accepted values: a dict mapping string keys to compileiq search_spaces functions, a path to an existing search-space file, or a SearchSpaceProvider instance.

field search_config: Dict[str, Any] | SearchConfiguration | Path [Required]#: Search configuration parameters such as generation number and mutation rate. Accepted values: a SearchConfiguration object, a dict with SearchConfiguration keys, or a path to an existing .config file.

field worker_type: WorkerTypes | type[Worker] = WorkerTypes.NATIVE#: Selects which worker implementation runs your objective function. Built-in options via WorkerTypes: NATIVE (default, local multiprocessing), RAY (distributed via Ray), or ASYNC (asyncio concurrency). A Worker subclass can also be passed directly for custom implementations.

field tracker_config: TrackerConfig [Optional]#: A TrackerConfig that defines how experiment tracking will be handled. Refer to TrackerTypes for available options.

field debug: bool = False#: When enabled, the cached log from the core subprocess is not deleted, allowing inspection of its output.

field cache_folder: Path | None = None#: Base directory for cache files created during the run. Cleaned up at the end unless CIQ_KEEP_CACHE=1 is set. Defaults to ~/.cache/compileiq if not provided.

field dump_results: Path | None = None#: If set, the results CSV is written to this path after every evaluation batch (typically one batch per pool_size evaluations). No file is written if None.

field disable_progress_bar: bool = False#: Disables the TQDM progress bar.

field exit_on_failure: bool = True#: When True, execution terminates with a RuntimeError if all objectives fail in the first generation. Set to False if your search has an inherently high failure rate.

field run_id: int | None = None#

field current_generation: int = 0#: Current generation of the search, starting at 0.

sample( num_samples: int = 1, ) → List[dict | str | list[dict | str]]#

Instead of performing a full search, this function will just sample num_samples from the search space provided by the user.

Parameters:: num_samples (int) – Number of samples to retrieve from the search space.
Returns:: A list of parameter sets sampled from the search space, in the same format as the parameters sent to the objective function during a normal search.

start(

num_workers: int | None = None,

task_timeout: int | float | None = None,

**additional_worker_kwargs,

) → SearchResult#

The CompileIQ core is started as a subprocess through here.

The communication between python process and the subprocess is done through sockets:

During __init__ we prepare the python socket server for communication with the core subprocess.
The search_space.json and main_config.json files are created inside the cache folder. (Core needs these.)
We start the core process with the correct environment variables and wait for communication.
The core process will start sending parameter candidates which we will execute using multiprocess.
The Python process returns the scores through the socket.
At some point the core process sends a completion flag indicating the end of the tune process.

Parameters:

num_workers – The maximum number of processes spawned to run parallel searches. This parameter is ignored by workers where respects_num_workers is False.
task_timeout – The maximum time (in seconds) allowed for a single execution of the objective. If the timeout is reached, the worker will treat it as a failed execution and return a failed Score. This is useful to prevent workers from hanging indefinitely on certain parameter sets.
**additional_worker_kwargs –
Additional keyword arguments forwarded to the worker’s run() method. Each worker accepts the kwargs it cares about. For example:
- RayWorker: accepts Ray task resource options
- Custom workers: accept any kwargs they define

Returns (SearchResult):: An object with the search results.

property search_space_resolution_metadata: list[dict[str, str | int | None]] | None#: One metadata record per resolved provider, or None if no provider was used.

model_post_init(context: Any, /) → None#

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self – The BaseModel instance.
context – The context.

compileiq.types#

class compileiq.types.ProblemType(*values)#

Bases: StrEnum

Supported problem types, min or max

class compileiq.types.MultiScoreComparison(*values)#

Bases: StrEnum

Possible ways to aggregate multi-score at the end of the search.

AVERAGE#: Averages all multi-scores

STDDEV#: Finds the standard deviation from all scores

PARETO#: This is the preferred method. Calculate the pareto front for all scores.

class compileiq.types.TrackerTypes(*values)#

Bases: StrEnum

Chooses between the available tracker types for experiment tracking. Trackers are responsible for logging and tracking experiment data during the search.

LOGURU#: Uses the Loguru Python logging library for tracking experiment events. Provides simple and structured logging to an output file. This is the default tracker type.

MLFLOW#: Uses MLflow for ML experiment tracking and logging. Provides comprehensive experiment tracking including parameters, metrics, and artifacts.

DISABLED#: Disables experiment tracking. No data will be logged or tracked.

class compileiq.types.TrackerConfig#

Bases: BaseModel

field type: TrackerTypes | Literal['loguru', 'mlflow', 'disabled'] [Required]#

field enqueue: bool = True#

class compileiq.types.BaseTracker(tracker_config: TrackerConfig)#

Bases: ABC

Base class for experiment trackers.

Trackers receive lifecycle callbacks during a search, allowing implementations to log parameters, scores, and metadata to any backend (files, MLflow, etc.).

Lifecycle (in call order):: setup → search_starts → [generation_starts → [pre_objective → post_objective]* → generation_ends]* → search_ends → cleanup

kwargs: dict#

search_title: str | None = None#

__init__(tracker_config: TrackerConfig)#: Initialize the tracker from a config, storing a defensive copy. Calls setup() automatically after initialization.

tracker_type: TrackerTypes#

tracker_config: TrackerConfig#

setup(**kwargs)#

Initialize tracker resources (logging sinks, connections, etc.).

Called once during __init__ and again inside worker subprocesses that need to re-establish tracker state (e.g., RayWorker remote tasks).

cleanup(**kwargs)#: Release tracker resources. Called once after the search completes.

abstractmethod search_starts(**kwargs)#: Called when the search begins, before any generations run.

abstractmethod search_ends(**kwargs)#: Called when the search finishes, after all generations complete.

abstractmethod generation_starts(generation_number: int, **kwargs)#: Called at the start of each generation.

abstractmethod generation_ends(generation_number: int, **kwargs)#: Called at the end of each generation.

abstractmethod pre_objective(

config: dict | str | list[dict | str],

**kwargs,

)#

Called before each objective function evaluation.

Parameters:

config – The parameters being evaluated.
**kwargs – Worker-specific metadata (e.g., task_id, node_id).

abstractmethod post_objective(scores, **kwargs)#

Called after each objective function evaluation.

Parameters:

scores – JSON-serialized Score from the evaluation.
**kwargs – Worker-specific metadata (e.g., task_id).

class compileiq.types.Worker( cache_folder: str | PathLike, normalize: bool = False, tracker: BaseTracker | None = None, respects_num_workers: bool = False, supports_timeout: bool = False, )#

Bases: ABC

Minimal specification for a worker.

__init__( cache_folder: str | PathLike, normalize: bool = False, tracker: BaseTracker | None = None, respects_num_workers: bool = False, supports_timeout: bool = False, )#

property normalize: bool#: Whether normalization should be applied.

property baseline_score#: The baseline score used for normalization.

property cache_dir: str | PathLike#: The cache directory for this worker.

property current_generation: int#: The current generation number.

property tracker: BaseTracker#: The tracker instance.

property respects_num_workers: bool#: Whether this worker respects the num_workers parameter on its run method.

property supports_timeout: bool#: Whether this worker supports the task_timeout parameter on its run method.

abstractmethod run(

*,

function: Callable,

params_pool: Sequence[dict | str | list[dict | str]],

params_ids: Sequence[int],

num_function_returns: int = 1,

num_workers: int = 1,

**kwargs,

) → list[Score]#: Execute the objective function across a pool of parameters.

abstractmethod classmethod create( cache_folder: str | PathLike, normalize: bool, tracker: BaseTracker | None, ) → Worker#: Construct a worker instance with the given configuration.

static normalize_scores( current_score: Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], baseline_score: Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ) → Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']#

static normalize_scores( current_score: List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...], baseline_score: List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...], ) → List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...]

static normalize_scores( current_score: Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'] | List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...], baseline_score: Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'] | List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...], ) → Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'] | List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...]

We normalize the scores when normalize=True as there may be run-to-run variations.

Parameters:

current_score – The current score(s) to be normalized.
baseline_score – The baseline score(s) used for normalization.

Returns:

The normalized score(s).

static invalidate_score( num_objectives: int, ) → Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'] | List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...]#: Return an invalid score for the given number of objectives.

class compileiq.types.WorkerTypes(*values)#

Bases: StrEnum

Chooses between the available classes for workers. Workers are responsible for running the user objective function Different Worker types will use different libs and configurations for executing the function in parallel, locally or distributed

DEFAULT#: This is set to be the same as WorkerTypes.NATIVE

NATIVE#: Uses the native Python multiprocessing library to spawn new processes that will pick ‘work’ from a queue until all generations are complete. Supports: Only local parallelism

ISOLATED#: Same as NATIVE, but each evaluation spawns a new process. Useful if your objective function has memory leaks or other side effects that may affect other evaluations. If a timeout is set, it will kill the entire process. This is the most robust execution type, but also the slowest. Supports: Only local parallelism

RAY#: Uses RayTune Cluster and remote features to run your workload. Allows for seamless executing in clusters as long as you have the RayCluster properly configured. It is your responsibility to have a Ray Cluster configured to enable distributed execution. Supports: Local and Distributed Parallelism Ray Documentation:

[Get Started](https://docs.ray.io/en/latest/cluster/getting-started.html) [Deploy On-Premise](https://docs.ray.io/en/latest/cluster/vms/user-guides/launching-clusters/on-premises.html)

ASYNC#: Uses Python’s asyncio library to run your workload. The objective function must be of type async and be prepared to take advantage of concurrency.

worker_type() → type[Worker]#: Return the Worker subclass for this type.

class compileiq.types.DisabledTrackerConfig#

Bases: TrackerConfig

DisabledTrackerConfig is a configuration to disable tracking.

type#: The type of tracker it creates.

field type: Literal[TrackerTypes.DISABLED] = TrackerTypes.DISABLED#

class compileiq.types.DefaultTrackerConfig#

Bases: DisabledTrackerConfig

DefaultTrackerConfig is a configuration to use the default tracker.

field type: Literal[TrackerTypes.DISABLED] = TrackerTypes.DISABLED#

class compileiq.types.LoguruTrackerConfig#

Bases: TrackerConfig

LoguruTrackerConfig is a configuration for the LoguruTracker. By default, it will log to stderr.

type#: The type of tracker it creates.

field type: Literal[TrackerTypes.LOGURU] = TrackerTypes.LOGURU#

field sink: str | Annotated[TextIO, SkipValidation()] | Annotated[List, SkipValidation()] | None = None#

field enqueue: bool = True#

field level: str = 'INFO'#

field format: str = '{time:YYYY-MM-DD HH:mm:ss.SSS} | {level: <8} | {extra[task_id]} | {message}'#

class compileiq.types.MLflowTrackerConfig#

Bases: TrackerConfig

MLflowTrackerConfig is a configuration for the MLflowTracker.

type#: The type of tracker it creates.

experiment_name#: The name of the experiment to use.

run_name#: The name of the run to use.

tracking_uri#: The URI of the tracking server to use.

description#: The description of the run to use.

score_names#: The names of the scores to use.

log_config#: Whether to log the config for each objective function call.

field type: Literal[TrackerTypes.MLFLOW] = TrackerTypes.MLFLOW#

field experiment_name: str | None = None#

field run_name: str | None = None#

field tracking_uri: str | None = None#

field description: str | None = None#

field score_names: list = []#

field log_config: bool = True#

class compileiq.types.SearchConfiguration#

Bases: BaseModel

Supported values to configure your search behavior.

field problem_type: ProblemType | Literal['min', 'max'] = ProblemType.MIN#: If it is minimization or maximization problem

field normalize: bool = False#: Controls if the scores are normalized by CompileIQ. Mostly recommended if using multi-machine or multi-gpu setups.

field num_objectives: int = 1#

Should match the number of returns from your objective function

Constraints:

gt = 0

field generations: int [Required]#

The number of search iterations to run before halting. The larger this value, the more solutions will be evaluated, but it may also lead to better results.

Constraints:

gt = 0

field pool_size: int | None = None#

The batch size of evaluations for each search iteration. If set to None, we calculate it based on your number of objectives.

Constraints:

gt = 5

field cull_size: int | None = None#

The number of parents in a given generation that will become the progenitors of the next generation. The difference between pool size and cull size are the survivors of the next generation. If set to None, we calculate it based on pool size.

Constraints:

gt = 1
multiple_of = 2

field mutate_rate: float = 0.25#

The chance a sampled candidate will be perturbed between iterations.

Constraints:

gt = 0.0
lt = 1.0

field objective_weights: list[float] | None = None#: If you are doing multiobjective search you may want to weight-in more scores. This will affect how we generate the algorithm reference directions.

field init_with_true_random_threshold: float | None = 0.9#: Controls what sampling percentage is performed at seed-low and seed-high vs normal range. Defaults to 0.9, so 90% will be sampled from the seed-high and seed-low range, and 10% from start and end.

field enable_large_fail_pool: bool = True#: When a generation does not achieve at least 20pct of passing solutions it will not move into the next. The subsequent sample batch will only contain the minimal number of passing samples required for this generation to pass. If this is set to True, it will resubmit an entire pool size length batch.

to_legacy() → str#: Convert configuration into expected legacy format

to_json_dict() → dict#: Convert configuration into JSON dict for core consumption.

classmethod from_legacy(legacy: str)#: Converts legacy lisp-like format into the SearchConfiguration Object.

Warning

It will ignore all fields that are not available at SearchConfiguration

Warning

It will raise exceptions if using fields that are unsupported in CompileIQ

class compileiq.types.InternalSearchConfiguration#

Bases: SearchConfiguration

Used internally to construct the core search-space config. These are fields CompileIQ overwrites and the user should not set by themselves.

field dna_config: str | List[str] = ''#

field enable_result_file: bool = False#

compileiq.types.Score#

compileiq.utils.validation.validate_inf_nan(val: float) → float | Literal['*']#: Communication with Core is done through json which does not handle ‘inf’ and ‘nan’ when dumped.

class compileiq.utils.validation.Score#

Bases: BaseModel

This class represents returned values from the objective function.

field score: List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...] | Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'] [Required]#: The raw score returned by the objective function.

field norm_score: List[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*']] | Tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...] | Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'] | None = None#: The normalized score computed by the Worker based on the baseline scoreand the score returned by the objective function.Only needed if normalization=True

field params: str | dict | list[str | dict] [Required]#: The parameters sent to the objective function that generated this score

field metadata: str = ''#: Additional metadata that will be forward to the resulting dataframe

field param_id: int | str [Required]#: The unique identifier for the parameters used in the objective function

field num_objectives: int [Required]#: The number of objectives in the optimization problem

field is_baseline: bool = False#: Indicates if this score is a baseline score

property failed: bool#: Checks if the score indicates a failure based on the presence of INVALID_SCORE.

compileiq.utils.validation.validate_scores( func_return: Any, num_objectives: int, ) → Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'] | tuple[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True), AfterValidator(func=validate_inf_nan)] | Literal['*'], ...]#: Check if the objective function return matches the expected type and num_objectives reported by the user at SearchConfiguration.

compileiq.search_spaces#

Search space that follows a range-like format.

Example

range(0,9,2) will produce the search space of [1,3,5,7,9]

Parameters:

start – Similar to a loop, start of the range.
end – Similar to a loop, end of the range. Must respect the step size to not overflow or underflow
step – Similar to a loop, how to slide the range window.
knockout_prob – The knockout_prob is a percentage value representing the likelihood of the value being dropped and not forwarded to the user objective function.
seed_low – Range parameters can also specify a secondary subset through seed_low and seed_high. Instead of sampling from the full range, CompileIQ will initialize with values inside this smaller range. This can speed your search if your problem has too many failures in a specific range. The percentage of candidates initialized this way is determined by the SearchConfiguration parameter init_with_true_random_threshold.
seed_high – Range parameters can also specify a secondary subset through seed_low and seed_high. Instead of sampling from the full range, CompileIQ will initialize with values inside this smaller range. This can speed your search if your problem has too many failures in a specific range. The percentage of candidates initialized this way is determined by the SearchConfiguration parameter init_with_true_random_threshold.

Search space that will sample from a list. Legacy version called this Enum

Example

choice([1,2,3]) will pick only one out of 1, 2 or 3 at a time

Parameters:

choice_list – A list of values to sample from.
knockout_prob – The knockout_prob is a percentage value representing the likelihood of the value being dropped and not forwarded to the user objective function.

compileiq.search_spaces.base.literal( const_value: str | int | float, knockout_prob: float | None = None, ) → LiteralParamConfig#

Represents a constant value with an optional knockout threshold. Helpful if you have constant parameters that need to take advantage of knockout, like on and off flags from compilers.

Example

{‘x’: literal(5)} sets config[‘x’] to 5

Parameters:

const_value – A constant value that will be forwarded to your evaluation.
knockout_prob – The knockout_prob is a percentage value representing the likelihood of the value being dropped and not forwarded to the user objective function.

compileiq.search_spaces.base.log_sampling( start: Annotated[float, Gt(gt=0)], end: Annotated[float, Gt(gt=0)], total: int = 10, knockout_prob: float | None = None, ) → ChoiceParamConfig#

Search space similar to range() but will follow a logarithmic distribution

Parameters:

start – Similar to a loop, start of the range.
end – Similar to a loop, end of the range. Must respect the step size to not overflow or underflow
total – The larger the total number the bigger the sampler space CompileIQ will use.
knockout_prob – The knockout_prob is a percentage value representing the likelihood of the value being dropped and not forwarded to the user objective function.

Public compiler search space providers.

Each provider fetches a pre-built search space, by default from a GitHub release on NVIDIA/CompileIQ (override with CIQ_SEARCH_SPACES_REPO). For offline use, set CIQ_SEARCH_SPACES_DIR to a directory containing a manifest.json plus its referenced binaries; the providers below will read from that directory and skip the network. For a single binary you already have on disk, use LocalSearchSpaceBin instead.

class compileiq.search_spaces.compilers.SearchSpaceProvider(*args, **kwargs)#

Bases: Protocol

Structural interface for search space providers.

Each provider is a class whose constructor takes whatever it needs (auth_token, version, local options, etc.) and whose retrieve() method returns the search space.

retrieve() → dict | Path#

__init__(*args, **kwargs)#

class compileiq.search_spaces.compilers.CompilerSearchSpaceBase( version: str = '13.3', variant: str = 'default', tag: str = 'latest', )#

Bases: object

Base class for compiler-specific GitHub-release-backed providers.

Subclasses set the compiler class attribute. Network access can be bypassed by setting CIQ_SEARCH_SPACES_DIR to a directory holding a manifest.json plus its referenced binaries. version is the compiler version selector, defaulting to the launch catalog compiler version "13.3"; use tag to pin a specific search-space release.

compiler: str#

__init__( version: str = '13.3', variant: str = 'default', tag: str = 'latest', )#

retrieve() → Path#

class compileiq.search_spaces.compilers.PtxasSearchSpace( version: str = '13.3', variant: str = 'default', tag: str = 'latest', )#

Bases: CompilerSearchSpaceBase

Fetches a pre-built PTXAS search space from a GitHub release.

Honors CIQ_SEARCH_SPACES_DIR for offline use. See module docstring.

compiler: str = 'ptxas'#

class compileiq.search_spaces.compilers.NvccSearchSpace( version: str = '13.3', variant: str = 'default', tag: str = 'latest', )#

Bases: CompilerSearchSpaceBase

Fetches a pre-built NVCC search space from a GitHub release.

Honors CIQ_SEARCH_SPACES_DIR for offline use. See module docstring.

compiler: str = 'nvcc'#

class compileiq.search_spaces.compilers.LocalSearchSpaceBin(path: str | Path)#

Bases: object

Provider that returns an explicit on-disk binary path with no manifest.

Use this when you have a single search-space .bin file in hand (a development build, an asset shared out-of-band, etc.) and want to skip both the manifest lookup and any network access. For mirrors of a full release (multiple variants, manifest-based variant selection), set CIQ_SEARCH_SPACES_DIR instead and use the standard provider classes above.

__init__(path: str | Path)#

retrieve() → Path#

compileiq.results#

class compileiq.results.SearchResult( df: DataFrame, problem_type: ProblemType, num_scores: int, )#

Bases: object

Stores results from a CompileIQ search in a pandas DataFrame.

df_results#

DataFrame containing the search results, including metadata, generation number, scores, and parameters.

Type:: pd.DataFrame

problem_type#

Indicates whether the optimization problem is a minimization or maximization task.

Type:: ProblemType

num_scores#

The number of scores recorded for each set of parameters.

Type:: int

score_columns#

List of column names in the DataFrame that contain the scores.

Type:: List[str]

__init__( df: DataFrame, problem_type: ProblemType, num_scores: int, )#

property score_columns: list#

property is_normalized: bool#

classmethod from_csv( csv_path: str, problem_type: str | ProblemType, clear_duplicates: bool = True, ) → SearchResult#

Loads dataframe into an SearchResult object.

Parameters:

csv_path – Path to usual CompileIQ dump_results csv file or previous SearchResult dataframe.
problem_type – Problem type, either “min” or “max”.
clear_duplicates – If True, will remove duplicate rows based on the params column.

Returns:

SearchResult object

classmethod from_dataframe( df: DataFrame, problem_type: str | ProblemType, clear_duplicates: bool = True, ) → SearchResult#

Loads dataframe into an SearchResult object.

Parameters:

df – Dataframe with the results.
problem_type – Problem type, either “min” or “max”.
clear_duplicates – If True, will remove duplicate rows based on the params column.

Returns:

SearchResult object

add_result( score: Score, generation_num: int, normalize: bool = False, ) → None#

Appends a single evaluated score to the results DataFrame.

Parameters:

score – a single Score object returned from the Worker.
generation_num – The generation this score was produced in.
normalize – Whether normalized scores should also be recorded.

get_best_result( multiscore_scope: MultiScoreComparison | Literal['avg', 'stddev', 'pareto_front'] = MultiScoreComparison.PARETO, ) → Dict | List[Dict]#

Returns the best result from your search.

Parameters:: multiscore_scope – For multi-score searches, how to aggregate scores before picking results. The default preserves existing behavior: single-score searches return the best row, while multi-score searches return the Pareto front.
Returns:: Dictionary with the best search scores, parameters and generation number, or a list of dictionaries when returning a Pareto front.

pareto_front() → List[Dict]#: Returns the Pareto-efficient rows from a multi-score search.

get_results() → DataFrame#

Returns:: Dataframe with all evaluated parameters

calculate_pareto_front( scores: ndarray, ) → ndarray[tuple[Any, ...], dtype[bool]]#

Find the pareto-efficient points given a list of scores.

Note

Using pareto_front() will yield the same Pareto front.

Parameters:: scores – An (n_params, n_scores) array with the scores. Position [i,j] is the jth score for the ith parameter set.
Returns:: A mask (boolean array) of size (n_params) indicating which rows from scores were selected

clear_duplicates() → DataFrame#: Core will often send the same params to be calculated. If the calculated scores are exactly the same as the previous time, we can just drop these rows.

save( filepath: str | PathLike = './search_results.csv', )#: Saves entire results dataframe to a CSV file. It will convert the params column into a JSON string for better parsing. :param filepath: Path to save the CSV file. Defaults to ./search_results.csv.

compileiq.tracker#

compileiq.tracker.logging_exception(func)#: A decorator that catches any exceptions raised by the decorated method.

class compileiq.tracker.DisabledTracker( tracker_config: DisabledTrackerConfig | None = None, )#

Bases: BaseTracker

DisabledTracker is a tracker that does nothing.

__init__( tracker_config: DisabledTrackerConfig | None = None, )#: Initialize the tracker from a config, storing a defensive copy. Calls setup() automatically after initialization.

setup(**kwargs)#

Initialize tracker resources (logging sinks, connections, etc.).

Called once during __init__ and again inside worker subprocesses that need to re-establish tracker state (e.g., RayWorker remote tasks).

cleanup(**kwargs)#: Release tracker resources. Called once after the search completes.

search_starts(**kwargs)#: Called when the search begins, before any generations run.

search_ends(**kwargs)#: Called when the search finishes, after all generations complete.

generation_starts(generation_number: int, **kwargs)#: Called at the start of each generation.

generation_ends(generation_number: int, **kwargs)#: Called at the end of each generation.

pre_objective(

config: dict | str | list[dict | str],

**kwargs,

)#

Called before each objective function evaluation.

Parameters:

config – The parameters being evaluated.
**kwargs – Worker-specific metadata (e.g., task_id, node_id).

post_objective(scores, **kwargs)#

Called after each objective function evaluation.

Parameters:

scores – JSON-serialized Score from the evaluation.
**kwargs – Worker-specific metadata (e.g., task_id).

class compileiq.tracker.LoguruTracker(tracker_config: LoguruTrackerConfig)#

Bases: BaseTracker

tracker_config: LoguruTrackerConfig#

__init__( tracker_config: LoguruTrackerConfig, )#: Initialize the tracker from a config, storing a defensive copy. Calls setup() automatically after initialization.

setup(**kwargs)#

Initialize tracker resources (logging sinks, connections, etc.).

Called once during __init__ and again inside worker subprocesses that need to re-establish tracker state (e.g., RayWorker remote tasks).

cleanup(**kwargs)#: Release tracker resources. Called once after the search completes.

search_starts(**kwargs)#: Called when the search begins, before any generations run.

search_ends(**kwargs)#: Called when the search finishes, after all generations complete.

generation_starts(generation_number: int, **kwargs)#: Called at the start of each generation.

generation_ends(generation_number: int, **kwargs)#: Called at the end of each generation.

pre_objective(

config: dict | str | list[dict | str],

**kwargs,

)#

Called before each objective function evaluation.

Parameters:

config – The parameters being evaluated.
**kwargs – Worker-specific metadata (e.g., task_id, node_id).

post_objective(scores, **kwargs)#

Called after each objective function evaluation.

Parameters:

scores – JSON-serialized Score from the evaluation.
**kwargs – Worker-specific metadata (e.g., task_id).

class compileiq.tracker.MLflowTracker(tracker_config: MLflowTrackerConfig)#

Bases: BaseTracker

tracker_config: MLflowTrackerConfig#

static get_date_string()#

__init__( tracker_config: MLflowTrackerConfig, )#: Initialize the tracker from a config, storing a defensive copy. Calls setup() automatically after initialization.

setup(**kwargs)#

Initialize tracker resources (logging sinks, connections, etc.).

Called once during __init__ and again inside worker subprocesses that need to re-establish tracker state (e.g., RayWorker remote tasks).

cleanup(**kwargs)#: Release tracker resources. Called once after the search completes.

search_starts(**kwargs)#: Called when the search begins, before any generations run.

search_ends(**kwargs)#: Called when the search finishes, after all generations complete.

generation_starts(generation_number: int, **kwargs)#: Called at the start of each generation.

generation_ends(generation_number: int, **kwargs)#: Called at the end of each generation.

pre_objective(

config: dict | str | list[dict | str],

**kwargs,

)#

Called before each objective function evaluation.

Parameters:

config – The parameters being evaluated.
**kwargs – Worker-specific metadata (e.g., task_id, node_id).

post_objective(scores, **kwargs)#

Called after each objective function evaluation.

Parameters:

scores – JSON-serialized Score from the evaluation.
**kwargs – Worker-specific metadata (e.g., task_id).

compileiq.utils.gpu#

compileiq.utils.gpu.has_nvidia_smi() → bool#

compileiq.utils.gpu.ctk_supports_compileiq() → bool#

Context manager to set GPU parameters for benchmarking. For time measurements it is recommended to set at least clock_mhz to a fixed value to prevent large variations during the search.

At the exit of the context manager, GPU settings will be reset to their default values. :param clock_mhz: Desired GPU clock speed in MHz. If None, no call is performed. :param mem_clock_mhz: Desired GPU memory clock speed in MHz. If None, no call is performed. :param power_watts: Desired GPU power limit in watts. If None, no call is performed. :param gpu_id: GPU ID(s) to apply settings to. If None, settings are applied to all visible GPUs. :param with_sudo: Whether to prefix nvidia-smi commands with sudo. Most commands require elevated

permissions, unless nvidia-smi is configured to no need it. Docker container environments may benefit from setting this to False.

Parameters:: raise_on_failure – Whether to raise an exception if nvidia-smi commands fail. If False, any failed commands will issue a warning instead, and the context manager will continue.