API Documentation#

compileiq.ciq#

exception compileiq.ciq.CheckpointCompatibilityWarning#

Bases: UserWarning

A build-provenance check was bypassed via the unsafe debug override.

exception compileiq.ciq.SearchSpaceExhaustedWarning#

Bases: UserWarning

A managed search ended early because the engine ran out of untried candidates.

class compileiq.ciq.CheckpointSearchConfig#

Bases: BaseModel

Bounded public search shape needed before the sealed state is restored.

field problem_type: Literal['min', 'max'] [Required]#

field normalize: bool [Required]#

field num_objectives: int [Required]#

Constraints:

ge = 1
le = 64

field generations: int [Required]#

Constraints:

ge = 1
le = 4294967295

field pool_size: int [Required]#

Constraints:

ge = 6
le = 4096

class compileiq.ciq.CheckpointResultRow#

Bases: BaseModel

One bounded user-visible SearchResult row stored outside optimizer state.

field metadata: str [Required]#

Constraints:

max_length = 1048576

field generation: int [Required]#

Constraints:

ge = 0
le = 4294967295

field scores: list[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True)] | Literal['*']] [Required]#

Constraints:

min_length = 1
max_length = 64

field params: dict | str | list[dict | str] [Required]#

field normalized_scores: list[Annotated[int, Strict(strict=True)] | Annotated[float, Strict(strict=True)] | Literal['*']] | None = None#

Constraints:

min_length = 1
max_length = 64

class compileiq.ciq.CheckpointResultLedger#

Bases: BaseModel

Validated user-visible history carried in the single checkpoint artifact.

field rows: list[CheckpointResultRow] [Optional]#

Constraints:

max_length = 262144

class compileiq.ciq.CheckpointEnvelope#

Bases: BaseModel

Safe outer metadata required to reconstruct a Search before unsealing.

field format: Literal['compileiq-checkpoint-v1'] [Required]#

field engine: str [Required]#

Constraints:

min_length = 1
max_length = 128

field provider: str [Required]#

Constraints:

min_length = 1
max_length = 128

field provider_version: str [Required]#

Constraints:

min_length = 1
max_length = 128

field abi_version: int [Required]#

Constraints:

ge = 0
le = 4294967295

field artifact_sha256: str [Required]#

Constraints:

pattern = ^[0-9a-f]{64}$

field search_space_identity: str [Required]#

Constraints:

pattern = ^[0-9a-f]{64}$

field search_config: CheckpointSearchConfig [Required]#

field exit_on_failure: bool [Required]#

field worker_type_name: str | None = None#

Constraints:

min_length = 1
max_length = 128

field tracker_type_name: str | None = None#

Constraints:

min_length = 1
max_length = 128

field result_ledger: CheckpointResultLedger [Required]#

field sealed_blob_sha256: str [Required]#

Constraints:

pattern = ^[0-9a-f]{64}$

field sealed_blob: str [Required]#

Constraints:

min_length = 1
max_length = 25165824

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), ISOLATED (fresh local process per task), RAY (distributed via Ray), ASYNC (asyncio concurrency), or MANUAL (external ask/tell execution only). 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#: Passed to the selected engine, which may emit additional diagnostics when enabled.

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 engine: str | EngineConfig = 'amber'#: Execution engine. The default ‘amber’ selects the native runtime included in complete platform wheels. Use EngineConfig(name=…, options={…}) when passing engine-owned settings.

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

property provider: str#: Resolved backend provider for diagnostics and checkpoint provenance.

property run_id: None#

always None since CompileIQ 1.1.

It identified a run in the original core’s results database, which CompileIQ 1.1 removed; use checkpoints to continue a search.

Type:: Deprecated

property engine_options: dict[str, Any]#: Validated provider-owned settings active for this search.

property pending_candidates: tuple[BackendCandidate, ...]#: Outstanding candidates, including work restored for resubmission.

property result: SearchResult#: Accumulated accepted results, including history restored from a checkpoint.

property best_result: Dict | List[Dict]#: Return the best completed result or multi-objective Pareto front so far.

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.

ask( num_samples: int | None = None, ) → list[BackendCandidate]#

Ask a registered backend for candidates without running the objective function.

Batch sizing and repeated-ask behavior are provider-owned capabilities. num_samples requests that exact batch size from providers supporting arbitrary batches. When omitted, the provider selects its next natural batch from its current state. Providers separately declare whether a new batch may be issued while earlier candidates remain pending.

evaluate(

candidates: list[BackendCandidate],

num_workers: int | None = None,

task_timeout: int | float | None = None,

**worker_kwargs: Any,

) → list[Score]#

Evaluate pending candidates without submitting them to the optimizer.

candidates may be any non-empty subset returned by ask(), in any order. Candidate IDs and parameters are validated before the worker runs. The returned scores remain caller-owned until passed to tell(); this method does not apply optimizer failure policy, advance backend state, remove pending candidates, or append results.

tell(scores: list[Score]) → None#

Submit scores for pending candidates using their stable param_id values.

List order is irrelevant, and every provider accepts any non-empty subset of outstanding IDs. Score.params is an optional compatibility echo: when supplied it is validated, but the provider’s detached pending snapshot is authoritative for backend submissions and stored result rows.

save_checkpoint( path: str | PathLike[str], *, require_no_pending: bool = False, ) → Path#

Atomically save visible results and backend-sealed execution state.

Set require_no_pending to fail before sealing or artifact creation when any candidate remains outstanding.

restore_checkpoint( path: str | PathLike[str], *, pending_policy: PendingCandidatePolicy | str = PendingCandidatePolicy.RESUBMIT, allow_unsafe_provenance_mismatch: bool = False, ) → None#: Restore compatible state, optionally accepting unsafe build-provenance drift.

classmethod from_checkpoint(

path: str | PathLike[str],

*,

objective_function: Callable,

search_space: Dict[str, Any] | Path | List[Dict | Path | SearchSpaceProvider] | SearchSpaceProvider,

worker_type: WorkerTypes | type[Worker] | None = None,

tracker_config: TrackerConfig | None = None,

pending_policy: PendingCandidatePolicy | str = PendingCandidatePolicy.RESUBMIT,

exit_on_failure: bool | None = None,

allow_unsafe_provenance_mismatch: bool = False,

**search_kwargs: Any,

) → Search#: Restore a search, reconstructing safe built-in execution types when possible.

Run the selected engine through its managed ask, evaluate, and tell lifecycle.

Restored pending candidates are evaluated first through the newly configured worker. Otherwise the engine produces each candidate batch, the worker evaluates it, and the accepted scores are submitted until the configured generation limit is reached. The returned result contains both restored history and newly accepted evaluations.

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.
checkpoint_path – When set, atomically replace this checkpoint after each successfully accepted managed batch. The selected engine must support checkpointing. No automatic checkpoint is created when this parameter is None.
**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 initialize 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.

property supports_managed_execution: bool#: Whether this worker can execute objectives through evaluate() or start().

abstractmethod run(

*,

function: Callable,

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

params_ids: Sequence[int | str],

num_function_returns: int = 1,

num_workers: int = 1,

**kwargs,

) → list[Score]#

Execute a parameter pool while preserving backend-owned candidate IDs.

params_ids may contain integers or strings. Every returned non-baseline Score must carry the ID associated with the corresponding input parameter.

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.

MANUAL#: Disables CompileIQ-managed objective execution. Use ask() to obtain candidates, evaluate them externally, and submit their scores through tell().

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#

Deprecated: has no effect since CompileIQ 1.1. Search ignores a non-default value with a FutureWarning; amber’s closest option is survivor_count. It was the number of parents in a generation that become the progenitors of the next. If set to None, we calculate it based on pool size.

Constraints:

gt = 1
multiple_of = 2

field mutate_rate: float = 0.25#

Deprecated: has no effect since CompileIQ 1.1. Search ignores a non-default value with a FutureWarning; amber’s closest option is mutation_probability. It was the chance a sampled candidate is perturbed between iterations.

Constraints:

gt = 0.0
lt = 1.0

field objective_weights: list[float] | None = None#: Deprecated: has no effect since CompileIQ 1.1. Search ignores a non-default value with a FutureWarning; amber’s closest option is reference_direction_weights. It weighted objectives when generating 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#: Deprecated: has no effect since CompileIQ 1.1. Search ignores a non-default value with a FutureWarning; amber always replaces each failed candidate one-for-one. It chose whether the original core resubmitted a whole pool after a generation with too few passing candidates.

to_legacy() → str#

Convert configuration into expected legacy format

Deprecated: will be removed in a future release.

classmethod from_legacy(legacy: str)#

Converts legacy lisp-like format into the SearchConfiguration Object.

Deprecated: will be removed in a future release.

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

The validated search configuration that Search hands to the selected engine. Engines and internal extensions may subclass it with fields that users do not set.

compileiq.types.Score#

compileiq.utils.validation.validate_inf_nan(val: float) → float | Literal['*']#: Scores are stored in results, CSV files, and JSON checkpoints, which do not handle ‘inf’ and ‘nan’ consistently, so non-finite scores are recorded as invalid.

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] | None = None#: Deprecated for Search.tell(): optional compatibility echo of the parameters that generated this score. Candidate IDs are authoritative, and Search stores the parameters from the issued BackendCandidate.

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,8,2) will produce the inclusive search space [0,2,4,6,8].

Parameters:

start – Similar to a loop, start of the range.
end – Inclusive upper bound. Values advance from start by step without exceeding this bound; the bound itself does not need to fall on that stepped grid.
step – Similar to a loop, how to slide the range window.
knockout_prob – Probability from 0.0 to 1.0 that the parameter is omitted from an initially sampled candidate. Search engines may then evolve the parameter’s on/off state, so this is an initialization prior rather than a guaranteed ratio in every candidate batch.
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 – Probability from 0.0 to 1.0 that the parameter is omitted from an initially sampled candidate. Search engines may then evolve the parameter’s on/off state, so this is an initialization prior rather than a guaranteed ratio in every candidate batch.

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 – Probability from 0.0 to 1.0 that the parameter is omitted from an initially sampled candidate. Search engines may then evolve the parameter’s on/off state, so this is an initialization prior rather than a guaranteed ratio in every candidate batch.

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 – Probability from 0.0 to 1.0 that the parameter is omitted from an initially sampled candidate. Search engines may then evolve the parameter’s on/off state, so this is an initialization prior rather than a guaranteed ratio in every candidate batch.

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 norm_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#: Drops rows that repeat an earlier row’s parameters and scores exactly, for example in results loaded from a CSV written by an engine that re-issued the same parameters.

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.