SearchSpace#
SearchSpace defines candidate representation and the services that operate on that representation.
Algorithms and surrogates use the GenomeBatch and services provided by the space instead of changing its internal representation directly.
SearchSpace’s role#
SearchSpace provides representation, services, sample(), and validate().
GenomeBatch stores candidates row-wise; it does not directly own candidate IDs or objective values.
validate() returns per-row validity and batch-wide errors in a ValidationResult.
ServiceRegistry registers the services provided by a space by name.
The space that needs them exposes sampling, validation, cloning, equivalence, distance, genome serialization, and other capabilities as SearchSpace services.
EvaluationAdapter is the Adapter boundary that converts a GenomeBatch into an evaluation Payload.
FeatureEncoder is an Adapter subtype responsible for the semantic conversion GenomeBatch → FeatureEncoder → FeatureBatch → Surrogate. Unlike a space capability such as SamplingService, it determines the features the surrogate can learn.
The public import is from saealib.space import FeatureEncoder.
What SearchSpace holds#
Built-in spaces are divided by the constraints on their representations:
VectorSpace: Handles fixed-width dense numeric vectors.ObjectSpace: The minimal space for holding arbitrary object representations.SequenceSpace: Handles sequences whose length can vary.PermutationSpace: Handles representations that satisfy permutation constraints.
Each space satisfies the common SearchSpace contract, but its service set and RepresentationSpec differ.
For example, ObjectSpace does not register default services, so the configuration must provide the services required by the algorithm separately.
Invariants#
RepresentationSpec describes parameter types, shapes, and representation kinds.
This description says how candidates are stored; it is not itself an implementation of sampling or feature encoding.
Services are the executable boundaries that fill this gap.
In the current implementation, the SurrogateManager contract declares ServiceRequirement("FeatureEncoder"), and VectorSpace registers a default encoder as a service, so numeric vector spaces resolve without extra configuration. ObjectSpace, PermutationSpace, and SequenceSpace raise an error unless the user provides a FeatureEncoder. The user decides what to pass to the surrogate.
Extending SearchSpace#
SearchSpace owns candidate representation, candidate-generation services, and representation validity.
It does not own candidate objective values, observation provenance, component state, or Graph execution order.
The space owns the representation rules and services for GenomeBatch values, while Population owns the live genome storage.
Population.genomes exposes that storage as a read-only view, not an immutable snapshot; subsequent Population updates may change its contents.
It does not implicitly add candidate IDs or Feedback results.
When adding a new candidate representation, define its RepresentationSpec, sampling, validation, and required services within one SearchSpace boundary.
Do not move RepresentationSpec into ComponentContract; declare connections to the port’s DataSpec and required services in the Compiler.
Common failures#
The RepresentationSpec and service set are fixed when the space is constructed, and the Compiler checks them against the component’s ServiceRequirement.
The GenomeBatch returned by sample() conforms to the space’s RepresentationSpec, and validate() reports mismatches in a ValidationResult instead of silently repairing them.
SearchSpace owns service implementation state, while components request and use registered services.
Mismatched kinds or shapes, missing required services, and invalid GenomeBatch values become Diagnostics from the Compiler or ValidationResult.
See Framework extensions for extending candidate representations, Declarative elements (Specs) for port and DataSpec boundaries, and Feedback for observations associated with candidates.
See the API reference for public type import paths.