brushline.optimization.pareto
The non-dominated archive builder, crowding-distance eviction, pareto.json writer, and promotion
records.
Multi-objective archive, scalarization portfolio, diversity, and promotion.
The archive keeps only feasible, non-dominated search results. It deduplicates identical objective
vectors, records crowding distance, evicts the most crowded members deterministically when the size
cap is exceeded, and writes a validated brushline.pareto.v1 document.
- class brushline.optimization.pareto.ArchiveConfig(*, max_size: Annotated[int, Ge(ge=1)] = 50, eviction: Annotated[str, MinLen(min_length=1)] = 'crowding-distance-v1', created_by: Annotated[str, MinLen(min_length=1)] = 'brushline.optimization.pareto')[source]
Bases:
BaseModelArchive build settings.
- Parameters:
max_size (int) – Maximum archive members.
eviction (str) – Eviction policy name.
created_by (str) – Archive creator.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.optimization.pareto.ArchiveError[source]
Bases:
ValueErrorRaised when archive inputs or promotion requests are inconsistent.
- class brushline.optimization.pareto.ArchiveResult(*, archive: ParetoArchive, duplicates: list[str] = <factory>, evicted: list[str] = <factory>, rejected_infeasible: list[str] = <factory>, crowding: dict[str, float]=<factory>)[source]
Bases:
BaseModelThe archive and the decisions that produced it.
- Parameters:
archive (ParetoArchive) – Validated archive.
duplicates (list of str) – Plan ids removed as duplicate objective vectors.
evicted (list of str) – Plan ids removed by the diversity cap.
rejected_infeasible (list of str) – Plan ids excluded because they were infeasible.
crowding (dict of str to float) – Crowding distance by plan id.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.optimization.pareto.PromotionRecord(*, schema_version: str = 'brushline.promotion.v1', promotion_id: Annotated[str, MinLen(min_length=1)], plan_id: Annotated[str, MinLen(min_length=1)], parent_plan_id: str | None = None, reason: Annotated[str, MinLen(min_length=1)], objective: dict[str, float], created_utc: datetime, created_by: Annotated[str, MinLen(min_length=1)])[source]
Bases:
BaseModelOne archive member promoted to a plan version.
- Parameters:
schema_version ({"brushline.promotion.v1"}) – Schema version.
promotion_id (str) – Promotion id.
plan_id (str) – Promoted archive plan.
parent_plan_id (str or None) – Prior plan version.
reason (str) – Promotion reason.
objective (dict of str to float) – Objective vector.
created_utc (datetime) – Timezone-aware creation time.
created_by (str) – Promoter.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.optimization.pareto.build_archive(runs: list[SearchRun], *, instance_id: str | None = None, run_id: str | None = None, config: ArchiveConfig | None = None, created_utc: datetime | None = None, scalarizations: list[Scalarization] | None = None) ArchiveResult[source]
Build a non-dominated archive from exact search runs.
- Parameters:
runs (list of SearchRun) – Replayable search results.
instance_id (str or None, optional) – Instance id. Defaults to the first run’s instance.
run_id (str or None, optional) – Run id. Defaults to the instance id.
config (ArchiveConfig, optional) – Archive settings.
created_utc (datetime, optional) – Creation time. Defaults to now.
scalarizations (list of Scalarization, optional) – Archive scalarizations. Defaults to the five adapter scalarizations.
- Returns:
ArchiveResult – Validated archive and build decisions.
- Raises:
ArchiveError – When runs are empty or span multiple instances.
- brushline.optimization.pareto.load_pareto_archive(path: str | Path) ParetoArchive[source]
Load and validate a Pareto archive.
- Parameters:
path (str or Path) – Source.
- Returns:
ParetoArchive – Archive.
- Raises:
ArchiveError – When the archive is invalid.
- brushline.optimization.pareto.load_promotion(path: str | Path) PromotionRecord[source]
Load a promotion record.
- Parameters:
path (str or Path) – Source.
- Returns:
PromotionRecord – Promotion record.
- brushline.optimization.pareto.promote_member(archive: ParetoArchive, plan_id: str, reason: str, *, parent_plan_id: str | None = None, created_by: str = 'brushline.optimization.pareto', created_utc: datetime | None = None) PromotionRecord[source]
Promote one archive member to a plan version.
- Parameters:
archive (ParetoArchive) – Source archive.
plan_id (str) – Member plan id.
reason (str) – Promotion reason.
parent_plan_id (str or None, optional) – Prior plan version.
created_by (str, optional) – Promoter.
created_utc (datetime, optional) – Creation time.
- Returns:
PromotionRecord – Promotion record.
- Raises:
ArchiveError – When the plan is not in the archive.
- brushline.optimization.pareto.write_pareto_archive(archive: ParetoArchive, path: str | Path) Path[source]
Write and validate a Pareto archive as
pareto.json.- Parameters:
archive (ParetoArchive) – Archive.
path (str or Path) – Destination.
- Returns:
Path – Written path.
- Raises:
ArchiveError – When the archive is invalid.
- brushline.optimization.pareto.write_promotion(record: PromotionRecord, path: str | Path) Path[source]
Write a promotion record.
- Parameters:
record (PromotionRecord) – Promotion record.
path (str or Path) – Destination.
- Returns:
Path – Written path.