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: BaseModel

Archive 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: ValueError

Raised 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: BaseModel

The 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: BaseModel

One 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.