Parameter Schema

Pool-owned parameter definitions with default values, Optuna search ranges, and metadata. Provides a single source of truth for parameter configuration that replaces scattered definitions across run_fingerprint defaults and ad-hoc initialisation code.

Parameter schema utilities for pool-owned parameter definitions.

This module provides the infrastructure for pools to declare their own parameters — including default values, Optuna search ranges, and metadata — in a single location (the pool class’s PARAM_SCHEMA dict). This eliminates the need for scattered parameter definitions across run_fingerprint_defaults, separate optuna_settings dicts, and ad-hoc initialization code.

The schema system supports a three-level priority for parameter resolution:

1. initial_values_dict (user-provided at runtime — highest priority)

2. run_fingerprint (experiment configuration)

3. PARAM_SCHEMA default (pool class definition — lowest priority)

Key classes:

• OptunaRange: Defines search bounds and scale for hyperparameter tuning.

• ParamSpec: Full specification for a single parameter (default, tuning range, transform, trainability).

• COMMON_PARAM_SCHEMA: Shared parameter definitions used across multiple pool types.

Key functions:

• get_param_value(): Resolves a parameter value through the priority chain.

• get_optuna_range(): Retrieves tuning ranges with optional run_fingerprint overrides.

• sample_in_range(): Maps [0, 1] samples to parameter ranges (for ensemble init).

Example usage in a pool class:

class MomentumPool(TFMMBasePool):
    PARAM_SCHEMA = {
        "memory_length": ParamSpec(
            initial=10.0,
            optuna=OptunaRange(low=1, high=200, log_scale=True),
        ),
        "k_per_day": ParamSpec(
            initial=20,
            optuna=OptunaRange(low=0.1, high=1000, log_scale=True),
        ),
    }

class OptunaRange(low, high, log_scale=False, scalar=False)

Bases: object

Defines the search range for Optuna hyperparameter optimization.

Parameters:

• low (float)

• high (float)

• log_scale (bool)

• scalar (bool)

low

Lower bound of the search range

Type:

float

high

Upper bound of the search range

Type:

float

log_scale

Whether to use log scale for sampling (useful for parameters that span multiple orders of magnitude)

Type:

bool

scalar

If True, use same value for all assets. If False, tune per-asset.

Type:

bool

__init__(low, high, log_scale=False, scalar=False)

Parameters:

• low (float)

• high (float)

• log_scale (bool)

• scalar (bool)

Return type:

None

class ParamSpec(initial, optuna=None, transform=None, description='', trainable=True)

Bases: object

Specification for a single pool parameter.

Parameters:

• initial (float | List[float])

• optuna (OptunaRange | None)

• transform (str | None)

• description (str)

• trainable (bool)

initial

Default initial value. Can be a scalar (applied to all assets) or a list (per-asset values).

Type:

Union[float, List[float]]

optuna

Search range for Optuna optimization. If None, parameter is not tuned.

Type:

Optional[OptunaRange]

transform

Transformation to apply: “log2” for log_k, “logit_lamb” for memory params. If None, no transformation is applied.

Type:

Optional[str]

description

Human-readable description of the parameter.

Type:

str

trainable

Whether this parameter should receive gradients during training.

Type:

bool

__init__(initial, optuna=None, transform=None, description='', trainable=True)

Parameters:

• initial (float | List[float])

• optuna (OptunaRange | None)

• transform (str | None)

• description (str)

• trainable (bool)

Return type:

None

COMMON_PARAM_SCHEMA = {'initial_weights_logits': ParamSpec(initial=1.0, optuna=OptunaRange(low=-10, high=10, log_scale=False, scalar=False), transform=None, description='Logit-space initial portfolio weights', trainable=False)}

Parameter definitions shared across multiple pool types.

Pool classes can merge this into their own PARAM_SCHEMA to inherit common defaults without duplication. Currently contains:

• initial_weights_logits: Logit-space initial portfolio weights. These are passed through softmax to produce the initial weight vector. Typically not trained (optimized via Optuna instead), since gradient descent on initial weights is poorly conditioned.

get_param_value(param_name, schema, initial_values_dict, run_fingerprint)

Get parameter value with priority: initial_values_dict > run_fingerprint > schema.

Parameters:

• param_name (str) – Name of the parameter (e.g., “memory_length”)

• schema (Dict[str, ParamSpec]) – Parameter schema from the pool class

• initial_values_dict (Dict[str, Any]) – User-provided initial values

• run_fingerprint (Dict[str, Any]) – Run configuration dict

Returns:

The parameter value to use

Return type:

Any

get_optuna_range(param_name, schema, run_fingerprint=None)

Get Optuna search range for a parameter.

Parameters:

• param_name (str) – Name of the parameter

• schema (Dict[str, ParamSpec]) – Parameter schema from the pool class

• run_fingerprint (Optional[Dict[str, Any]]) – Run configuration (may contain overrides)

Returns:

The Optuna range, or None if parameter shouldn’t be tuned

Return type:

Optional[OptunaRange]

sample_in_range(samples, optuna_range)

Map [0, 1] samples to parameter range.

Parameters:

• samples (np.ndarray) – Samples in [0, 1] range

• optuna_range (OptunaRange) – The parameter’s valid range

Returns:

Samples mapped to [low, high] (or log-space if log_scale=True)

Return type:

np.ndarray