saealib.Archive#

class saealib.Archive(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: ArchiveMixin, Population

Concrete archive combining ArchiveMixin with Population.

Its constructor is inherited from ArchiveMixin.

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)

Methods

`__init__`	Initialize archive storage and duplicate-resolution services.
`add`	Add a solution according to the configured duplicate policy.
`append`	Append one candidate.
`argsort`	Return row indices that order a named column.
`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.
`extract`	Return a new population containing rows selected by `indices`.
`get`	Get the array of a specific attribute.
`get_array`	Return a read-only view of the active rows in a named column.
`get_cache`	Return a cached value without changing population state.
`get_knn`	Get k-nearest neighbors of the given solution from the archive.
`mod_structure`	Mark population structure as changed and invalidate cached results.
`mod_value`	Invalidate the kNN cache on every value-only mutation, too.
`reorder`	Reorder rows according to a complete row permutation.
`set_cache`	Store a value in the population cache without changing its version.
`truncate`	Keep the first `new_size` rows in place.
`update_array`	Update array in place and bump the value version.
`update_rows`	Atomically update multiple columns for the given rows.

Method Details

Archive.__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)#

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.

Archive.add(element=None, **kwargs)#

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)

Archive.append(element=None, **kwargs)#

Append one candidate.

Parameters:

element (Individual-like object, dict, or None) – Candidate values read from an individual or mapping. Values passed through kwargs take precedence over values from element.
**kwargs (Any) – Column values to assign. genome or genomes supplies the single genome required by a non-dense genome representation.

Raises:

ValidationError – If an explicit candidate ID other than the unassigned -1 sentinel is supplied, or if a custom genome representation does not receive exactly one genome.

Return type:

None

Notes

The population grows its storage as needed. Appending invalidates cached values and structure-dependent views.

Archive.argsort(name, reverse=False)#

Return row indices that order a named column.

Parameters:

name (str) – Name of a column in the population schema.
reverse (bool, optional) – If true, return the indices in descending rather than ascending column order.

Returns:

Indices for the active rows in sorted order. The population is not mutated.

Return type:

ndarray of int

Raises:

KeyError – If name is not present in the population schema.

Archive.clear()#

Clear rows and invalidate identity/neighbor caches.

Return type:: None

Archive.delete(index)#

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.

Archive.empty_like(capacity=None)#

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: