saealib.ParetoArchive#

class saealib.ParetoArchive(attrs, init_capacity=100, direction=None, dominator=None, eps_cv=0.0, key_attr='x', atol=0.0, rtol=0.0, duplicate_policy='keep_first', genomes=None, dense_numeric_view=None, dense_view=None, **kwargs)[source]#

Bases: ParetoMixin, Population

Concrete Pareto archive: ParetoMixin mixed into Population.

Parameters:

attrs (list[PopulationAttribute])
init_capacity (int)
direction (np.ndarray | None)
dominator (Dominator | None)
eps_cv (float)
key_attr (str)
atol (float)
rtol (float)
duplicate_policy (str)
genomes (GenomeBatch | None)
dense_numeric_view (DenseNumericView | None)
dense_view (DenseNumericView | None)

Methods

`__init__`	Initialize a Population.
`add`	Add a solution to the Pareto archive.
`append`	Append one candidate.
`argsort`	Return row indices that order a named column.
`clear`	Clear the population.
`delete`	Delete candidates selected by `index` in place.
`empty_like`	Create an empty population with the same schema and representation.
`extend`	Extend the population 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.
`mod_structure`	Mark population structure as changed and invalidate cached results.
`mod_value`	Mark population values as changed and invalidate cached results.
`reorder`	Reorder candidates 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` candidates 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

ParetoArchive.__init__(attrs, init_capacity=100, direction=None, dominator=None, eps_cv=0.0, key_attr='x', atol=0.0, rtol=0.0, duplicate_policy='keep_first', genomes=None, dense_numeric_view=None, dense_view=None, **kwargs)#

Initialize a Population.

Parameters:

attrs (list[PopulationAttribute]) – Column definitions for per-candidate data.
init_capacity (int) – Initial storage capacity.
genomes (GenomeBatch | None) – Optional initial genome batch.
space – Search space associated with the genomes.
dense_numeric_view (DenseNumericView | None) – Service used to obtain a dense numeric view of dense genomes.
dense_view (DenseNumericView | None) – Compatibility alias for dense_numeric_view.
direction (ndarray | None)
dominator (Dominator | None)
eps_cv (float)
key_attr (str)
atol (float)
rtol (float)
duplicate_policy (str)

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

Add a solution to the Pareto archive.

The solution is accepted only if it is not dominated by any existing member. After insertion all existing members that are dominated by the new solution are removed.

Parameters:

element (Individual | dict | None) – Data for the new solution.
**kwargs – Attribute values that override or supplement element.

Returns:

idx – Index assigned to the new solution, or -1 when it was rejected.

Return type:

int

Examples

>>> archive.add(ind)
>>> archive.add({"x": x_val, "f": f_val})
>>> archive.add(x=x_val, f=f_val)

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

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

ParetoArchive.clear()#

Clear the population.

Return type:: None

ParetoArchive.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 population.
Return type:: None

Notes

Surviving rows retain their relative order. The operation mutates the population and invalidates cached values and structure-dependent views.

ParetoArchive.empty_like(capacity=None)#

Create an empty population with the same schema and representation.

Parameters:: capacity (int or None, optional) – Storage capacity for the new population. If omitted, the current capacity is reused.
Returns:: An empty population of the same concrete type, schema, and genome representation. It reuses the associated space and dense-view service but has independent row storage.
Return type:: Population

ParetoArchive.extend(other)#

Extend the population with another candidate collection.

Parameters:: other (Population or dict) – Source population or column-data mapping. A mapping may provide genome or genomes for an opaque genome representation.
Raises:: ValidationError – If the source supplies assigned candidate IDs through this public method, or omits genomes required by a custom representation.
Return type:: None

Notes

An empty source is a no-op. Otherwise rows are copied, storage grows as needed, and cached values and structure-dependent views are invalidated.

ParetoArchive.extract(indices)#

Return a new population containing rows selected by indices.

Parameters:: indices (ndarray, list of int, or slice) – Indices into the active rows. Rows appear in the requested order; a slice follows normal Python slicing semantics.
Returns:: A new population of the same concrete type, schema, and genome representation. Row and genome data have independent storage, and the source population is unchanged.
Return type:: Population

ParetoArchive.get(key, default=None)#

Get the array of a specific attribute.

Parameters:

key (str) – The attribute name to get the array for.
default (any, optional) – Returned when the key is absent. Defaults to None.

Returns:

The attribute array if key exists, otherwise default.

Return type:

np.ndarray or default

ParetoArchive.get_array(key)#

Return a read-only view of the active rows in a named column.

Parameters:

key (str) – Column name. For "x", the value is obtained through the configured DenseNumericView unless this is a legacy scalar-x population.

Returns:

A non-writeable view covering the active rows of the column. The returned array for stored columns shares backing storage rather than being an owned copy; "x" uses the service-provided view.

Return type:

np.ndarray

Raises:

KeyError – If key is not a stored non-genome column.
AttributeError – If key is "x" and the required DenseNumericView is unavailable or reports that it cannot provide a view.

Notes

The population is not modified by this method. Mutating the returned view raises ValueError; use update_array() or update_rows() so value versions and caches remain synchronized.

ParetoArchive.get_cache(key)#

Return a cached value without changing population state.

Parameters:: key (Hashable) – Cache key to look up.
Returns:: The cached value, or None when no value is stored for key. A cached None is therefore indistinguishable from a missing key through this method.
Return type:: Any or None
Raises:: TypeError – If key is not hashable.

Notes

Cached values are removed when the population is modified through mod_value() or mod_structure().

ParetoArchive.mod_structure()#

Mark population structure as changed and invalidate cached results.

Return type:: None

ParetoArchive.mod_value()#

Mark population values as changed and invalidate cached results.

Return type:: None

ParetoArchive.reorder(order)#

Reorder candidates according to a complete row permutation.

Parameters:: order (ndarray of int) – Permutation containing one row index for every active candidate.
Raises:: ValueError – If order does not contain one entry per active row.
Return type:: None

Notes

Reordering is in place and invalidates cached values and structure-dependent views.

ParetoArchive.set_cache(key, value)#

Store a value in the population cache without changing its version.

Parameters:

key (Hashable) – Cache key. An existing value for the key is replaced.
value (Any) – Value to retain until the population is modified.

Raises:

TypeError – If key is not hashable.

Return type:

None

Notes

The cache is cleared by mod_value() and mod_structure(). Storing a value replaces only the entry for key; it does not clear other cached entries or bump the population’s value or structure version.

ParetoArchive.truncate(new_size)#

Keep the first new_size candidates in place.

Parameters:: new_size (int) – Number of leading active rows to retain. Values greater than or equal to the current size leave the population unchanged.
Raises:: ValueError – If new_size is negative.
Return type:: None

Notes

When the population is reduced, trailing rows become inactive and non-dense genome storage is reduced accordingly. Structure-dependent state and cached values are invalidated. No version or cache change occurs for a no-op truncation.

ParetoArchive.update_array(key, value)#

Update array in place and bump the value version.

Parameters:

key (str)
value (Any)

Return type:

None

ParetoArchive.update_rows(indices, values, genome=None)#

Atomically update multiple columns for the given rows.

Validates every index and value before mutating any backing storage, so a validation failure never leaves a partial update applied. Bumps the value version exactly once for a non-empty update; an update with empty indices or an empty values mapping is a no-op and does NOT bump the version.

Parameters:

indices (np.ndarray | list[int]) – Row indices to update. Must be 1-D, integer dtype, within [0, len(self)), and free of duplicates.
values (dict[str, np.ndarray]) – Mapping of column name to the new values for those rows. Each value array must match shape (len(indices), *schema[key].shape) and dtype schema[key].dtype exactly.
genome (GenomeBatch | ndarray | None)

Raises:

ValidationError – If indices is invalid (wrong dtype/ndim, out of range, or contains duplicates), if a key in values is unknown (or is "id"), or if a value array’s shape/dtype does not match the schema exactly.

Return type:

None