saealib.Population

class saealib.Population(attrs, init_capacity=100, *, genomes=None, space=None, dense_numeric_view=None, dense_view=None)

ベースクラス: Generic[T_Individual]

Container for schema-defined population attributes and genome data.

パラメータ:

• attrs (list[PopulationAttribute])

• init_capacity (int)

• genomes (GenomeBatch | None)

• space (Any | None)

• dense_numeric_view (DenseNumericView | None)

• dense_view (DenseNumericView | None)

Methods

__init__	Initialize a Population.
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

Population.__init__(attrs, init_capacity=100, *, genomes=None, space=None, dense_numeric_view=None, dense_view=None)

Initialize a Population.

パラメータ:

• attrs (list[PopulationAttribute]) -- Column definitions for per-candidate data.

• init_capacity (int) -- Initial storage capacity.

• genomes (GenomeBatch | None) -- Optional initial genome batch.

• space (Any | None) -- 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.

戻り値の型:

None

Population.append(element=None, **kwargs)

Append one candidate.

パラメータ:

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

例外:

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.

戻り値の型:

None

メモ

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

Population.argsort(name, reverse=False)

Return row indices that order a named column.

パラメータ:

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

戻り値:

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

戻り値の型:

ndarray of int

例外:

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

Population.clear()

Clear the population.

戻り値の型:

None

Population.delete(index)

Delete candidates selected by index in place.

パラメータ:

index (int, slice, list of int, or ndarray) -- Row index or indices to remove from the active population.

戻り値の型:

None

メモ

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

Population.empty_like(capacity=None)

Create an empty population with the same schema and representation.

パラメータ:

capacity (int or None, optional) -- Storage capacity for the new population. If omitted, the current capacity is reused.

戻り値:

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.

戻り値の型:

Population

Population.extend(other)

Extend the population with another candidate collection.

パラメータ:

other (Population or dict) -- Source population or column-data mapping. A mapping may provide genome or genomes for an opaque genome representation.

例外:

ValidationError -- If the source supplies assigned candidate IDs through this public method, or omits genomes required by a custom representation.

戻り値の型:

None

メモ

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

Population.extract(indices)

Return a new population containing rows selected by indices.

パラメータ:

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.

戻り値:

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.

戻り値の型:

Population

Population.get(key: str) → ndarray | None

Population.get(key: str, default: _T_Default) → ndarray | _T_Default

Get the array of a specific attribute.

パラメータ:

• key (str) -- The attribute name to get the array for.

• default (any, optional) -- Returned when the key is absent. Defaults to None.

戻り値:

The attribute array if key exists, otherwise default.

戻り値の型:

np.ndarray or default

Population.get_array(key)

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

パラメータ:

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

戻り値:

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.

戻り値の型:

np.ndarray

例外:

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

メモ

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.

Population.get_cache(key)

Return a cached value without changing population state.

パラメータ:

key (Hashable) -- Cache key to look up.

戻り値:

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.

戻り値の型:

Any or None

例外:

TypeError -- If key is not hashable.

メモ

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

Population.mod_structure()

Mark population structure as changed and invalidate cached results.

戻り値の型:

None

Population.mod_value()

Mark population values as changed and invalidate cached results.

戻り値の型:

None

Population.reorder(order)

Reorder candidates according to a complete row permutation.

パラメータ:

order (ndarray of int) -- Permutation containing one row index for every active candidate.

例外:

ValueError -- If order does not contain one entry per active row.

戻り値の型:

None

メモ

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

Population.set_cache(key, value)

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

パラメータ:

• key (Hashable) -- Cache key. An existing value for the key is replaced.

• value (Any) -- Value to retain until the population is modified.

例外:

TypeError -- If key is not hashable.

戻り値の型:

None

メモ

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.

Population.truncate(new_size)

Keep the first new_size candidates in place.

パラメータ:

new_size (int) -- Number of leading active rows to retain. Values greater than or equal to the current size leave the population unchanged.

例外:

ValueError -- If new_size is negative.

戻り値の型:

None

メモ

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.

Population.update_array(key, value)

Update array in place and bump the value version.

パラメータ:

• key (str)

• value (Any)

戻り値の型:

None

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

パラメータ:

• 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)

例外:

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.

戻り値の型:

None