API Reference
Optimizer
Bases: Generic[T]
Schema-based xNES optimizer over dataclass or mapping schemas.
batch_size
property
batch_size
Configured sample count for the next freshly drawn batch.
mean
property
mean
Current mean parameters in the schema's runtime shape.
For transformed parameters this is the transformed latent mean, used as a convenient center rather than the exact expected value.
scale_marginal
property
scale_marginal
Current scale-vector parameters in the schema's runtime shape.
seed
property
seed
Configured root seed used for future batch sampling.
ask
ask(context=None)
Reserve one sampled parameter set for one evaluation.
load
load(state)
Restore optimizer state from a previous snapshot.
save
save()
Serialize the current optimizer state into a JSON-compatible mapping.
tell
tell(result)
Submit the objective result for the pending sample.
OptimizerSession
Bases: Generic[T]
Persisted optimizer workflow around an in-memory Optimizer.
batch_size
property
batch_size
Configured sample count for the next freshly drawn batch.
dirty
property
dirty
Whether committed optimizer state exists that has not been durably flushed.
mean
property
mean
Current optimizer mean parameters.
restored
property
restored
Whether this session loaded an existing checkpoint.
scale_marginal
property
scale_marginal
Current optimizer scale-vector parameters.
schema_diff
property
schema_diff
Difference against the restored schema, or an empty baseline on fresh sessions.
seed
property
seed
Configured root seed used for future batch sampling.
ask
ask(context=None)
Reserve one sampled parameter set for evaluation.
flush
flush()
Persist the current committed optimizer state.
tell
tell(result)
Record one result and atomically persist the updated optimizer state.
OptimizerReport
dataclass
Outcome of one Optimizer.tell call.
parameter
Parameter
dataclass
User-facing metadata for one optimized scalar schema field.
mean is the user-space center value. scale is the latent-space standard
deviation. min and max, when provided, are asymptotic user-space
bounds applied through monotone coordinate transforms.
mean_to_latent
mean_to_latent(value)
Map a user-space mean value into latent coordinates.
reconciliation_key
reconciliation_key()
Return the persisted transform data that must match to reuse latent state.
to_user_space
to_user_space(value)
Map latent coordinates into user-space values.
validate
validate(name)
Validate the parameter specification for one schema field.
parameter
parameter(*, mean=None, scale=1.0, min=None, max=None)
Return the canonical dataclass field declaration for one optimized scalar.
Parameter
dataclass
User-facing metadata for one optimized scalar schema field.
mean is the user-space center value. scale is the latent-space standard
deviation. min and max, when provided, are asymptotic user-space
bounds applied through monotone coordinate transforms.
mean_to_latent
mean_to_latent(value)
Map a user-space mean value into latent coordinates.
reconciliation_key
reconciliation_key()
Return the persisted transform data that must match to reuse latent state.
to_user_space
to_user_space(value)
Map latent coordinates into user-space values.
validate
validate(name)
Validate the parameter specification for one schema field.
SchemaDiff
dataclass
Difference between persisted and current schema definitions.
Attributes:
| Name | Type | Description |
|---|---|---|
added |
list[str]
|
Current schema leaf names absent from the loaded state. |
removed |
list[str]
|
Loaded schema leaf names absent from the current schema. |
changed |
list[str]
|
Shared leaf names whose persisted transform compatibility differs. |
unchanged |
list[str]
|
Shared leaf names whose persisted transform compatibility matches. |
XNESStatus
Bases: Enum
Outcome of one XNES.update step.
is_completion
property
is_completion
Whether the update reached a non-error stopping condition.
is_error
property
is_error
Whether the update hit an error stopping condition.
is_ok
property
is_ok
Whether the update succeeded and sampling can continue.
is_terminal
property
is_terminal
Whether the update requested a restart.
XNES
Exponential Natural Evolution Strategies distribution state.
The distribution is stored in factored form as
scale_global * scale_shape and updated
from ranked standardized samples.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mean0
|
ndarray
|
Initial mean vector. |
required |
scale0
|
ndarray | float
|
Initial scale, either scalar, diagonal vector, or full matrix. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the supplied shapes are inconsistent, the scale matrix is not positive with finite determinant. |
axis_ratio
property
axis_ratio
Current principal-axis ratio of the scale transform.
dim
property
dim
Dimension of the search space.
scale
property
scale
Current full scale matrix scale_global * scale_shape.
scale_marginal
property
scale_marginal
Current marginal per-dimension standard deviations in latent space.
sample
sample(num_samples=None, rng=None)
Sample a mirrored standardized batch.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
num_samples
|
int | None
|
Optional batch size. Values below two are clamped, and odd values are rounded up to keep mirrored pairs. |
None
|
rng
|
Generator | None
|
Optional NumPy random generator. |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Standardized samples |
transform
transform(samples)
Map standardized samples z into current distribution coordinates.
update
update(samples, ranking, eta_mean=1.0, eta_scale_global=1.0, eta_scale_shape=1.0, eps=1e-10)
Apply one xNES update from ranked standardized samples.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
samples
|
ndarray
|
Standardized sample matrix with shape |
required |
ranking
|
list[int]
|
Permutation of sample indices ordered from best to worst. |
required |
eta_mean
|
float
|
Mean learning-rate override. |
1.0
|
eta_scale_global
|
float
|
Global-scale learning-rate override. |
1.0
|
eta_scale_shape
|
float
|
Shape learning-rate multiplier override. |
1.0
|
eps
|
float
|
Numerical stopping threshold. |
1e-10
|
Returns:
| Type | Description |
|---|---|
XNESStatus
|
An |
Raises:
| Type | Description |
|---|---|
ValueError
|
If sample shapes are inconsistent, samples are not finite, or the ranking is not a valid permutation. |