saealib.ArchiveMixin#

class saealib.ArchiveMixin(attrs, init_capacity=100, key_attr='x', atol=<object object>, rtol=<object object>, duplicate_policy='keep_first', genomes=None, dense_numeric_view=None, dense_view=None, services=None, space=None, fingerprint_service=None, equivalence_service=None, distance_service=None, **kwargs)[source]#

Bases: object

Provide archive operations for a Population subclass.

Duplicate identity is normally supplied by search-space services. The key_attr, atol, and rtol arguments remain supported for direct schema-backed construction without those services.

Parameters:

attrs (list[PopulationAttribute])
init_capacity (int)
key_attr (str)
atol (float | object)
rtol (float | object)
duplicate_policy (str)
genomes (GenomeBatch | None)
dense_numeric_view (DenseNumericView | None)
dense_view (DenseNumericView | None)
services (Any | None)
space (Any | None)
fingerprint_service (FingerprintService | None)
equivalence_service (EquivalenceService | None)
distance_service (DistanceService | None)

duplicate_policy#

Duplicate handling policy selected at construction.

Type:: str

key_attr#

Schema column used by compatibility identity handling.

Type:: str

atol#

Effective absolute tolerance, including any service-owned value.

Type:: float

rtol#

Effective relative tolerance, including any service-owned value.

Type:: float

Methods

`__init__`	Initialize archive storage and duplicate-resolution services.
`add`	Add a solution according to the configured duplicate policy.
`clear`	Clear rows and invalidate identity/neighbor caches.
`delete`	Delete candidates selected by `index` in place.
`empty_like`	Create an empty archive while retaining resolved identity services.
`extend`	Extend the archive with another candidate collection.
`get_knn`	Get k-nearest neighbors of the given solution from the archive.
`mod_value`	Invalidate the kNN cache on every value-only mutation, too.
`reorder`	Reorder rows according to a complete row permutation.
`truncate`	Keep the first `new_size` rows in place.

Method Details

ArchiveMixin.__init__(attrs, init_capacity=100, key_attr='x', atol=<object object>, rtol=<object object>, duplicate_policy='keep_first', genomes=None, dense_numeric_view=None, dense_view=None, services=None, space=None, fingerprint_service=None, equivalence_service=None, distance_service=None, **kwargs)[source]#

Initialize archive storage and duplicate-resolution services.

Parameters:

attrs (list of PopulationAttribute) – Column definitions for archive rows. With duplicate_policy="append", the schema must contain scalar int64 columns named id and request_id.
init_capacity (int, optional) – Initial row-storage capacity passed to Population.
key_attr (str, optional) – Schema column used by compatibility duplicate detection. In a service-backed archive, "x" may also provide the dense genome used to resolve an incoming candidate.
atol (float, optional) – Explicit absolute-tolerance override. When omitted, the archive uses the equivalence service’s tolerance when applicable, or zero for exact matching.
rtol (float, optional) – Explicit relative-tolerance override, with the same resolution rules as atol.
duplicate_policy ({"keep_first", "replace", "append"}, optional) – Action for a duplicate candidate. "keep_first" leaves the existing row unchanged, "replace" updates the existing row, and "append" retains every observation while requiring the observation schema described for attrs.
genomes (GenomeBatch or None, optional) – Initial opaque genome batch passed to Population.
dense_numeric_view (DenseNumericView or None, optional) – Service used when archive operations need dense coordinates for a non-dense genome representation.
dense_view (DenseNumericView or None, optional) – Compatibility alias for dense_numeric_view.
services (object or None, optional) – Service provider or registry used when space is not supplied. Explicit service arguments take precedence over services resolved from this provider.
space (object or None, optional) – Search-space or service provider. When supplied, it takes precedence over services and its services registry is queried for omitted service arguments.
fingerprint_service (FingerprintService or None, optional) – Explicit service for exact identity lookup of opaque genomes.
equivalence_service (EquivalenceService or None, optional) – Explicit service for tolerance-based identity lookup of opaque genomes.
distance_service (DistanceService or None, optional) – Explicit service for nearest-neighbor queries on opaque genomes.
**kwargs (Any) – Additional constructor keywords accepted for population compatibility.

Raises:

ValueError – If duplicate_policy is unknown or a compatibility key_attr is absent from the schema.
ValidationError – If an append archive has an invalid observation schema, or if service-backed duplicate detection lacks its required identity service.

ArchiveMixin.add(element=None, **kwargs)[source]#

Add a solution according to the configured duplicate policy.

Parameters:

element (Individual | dict | None) – Data for the additional individual
**kwargs – Set attribute values individually and add them. Alternatively, overwrite based on the element’s value and add it.
self (Any)

Returns:

idx – Index of the retained or newly added row.

Return type:

int

Notes

"keep_first" returns the existing row for a duplicate, "replace" updates or replaces that row, and "append" retains every observation subject to its ID and request-ID constraints.

Examples

>>> arcv.add(ind)
>>> arcv.add({"x": x_val})
>>> arcv.add(x=x_val, f=0.1)
>>> arcv.add(ind, f=0.1)

ArchiveMixin.clear()[source]#

Clear rows and invalidate identity/neighbor caches.

Return type:: None

ArchiveMixin.delete(index)[source]#

Delete candidates selected by index in place.

Parameters:: index (int, slice, list of int, or ndarray) – Row index or indices to remove from the active archive.

Notes

Surviving rows retain their relative order. The operation invalidates the archive’s identity and nearest-neighbor caches.

ArchiveMixin.empty_like(capacity=None)[source]#

Create an empty archive while retaining resolved identity services.

Parameters:

capacity (int or None, optional) – Storage capacity for the new archive. If omitted, the current capacity is reused.
self (Any)

Returns:

An empty archive of the same concrete type and schema with independent row storage and the same identity services.

Return type: