OCDocker.OCScore.Optimization.OptunaSearchSpace module

Centralized Optuna search-space definitions for staged OCScore optimization.

Edit the dataclasses in this module to expand or restrict hyperparameter search spaces without modifying sampler logic in StagedOptuna.py.

class OCDocker.OCScore.Optimization.OptunaSearchSpace.OptimizerSearchSpace(learning_rate_min=1e-05, learning_rate_max=0.001, weight_decay_min=1e-06, weight_decay_max=0.001, batch_size_options=(32, 64, 128, 256))[source]

Bases: object

Optimizer and training batch search space.

Parameters:

  • learning_rate_min (float, optional) – Minimum learning rate, by default 1e-5.

  • learning_rate_max (float, optional) – Maximum learning rate, by default 1e-3.

  • weight_decay_min (float, optional) – Minimum weight decay, by default 1e-6.

  • weight_decay_max (float, optional) – Maximum weight decay, by default 1e-3.

  • batch_size_options (tuple[int, ...], optional) – Batch-size candidates, by default (32, 64, 128, 256).

learning_rate_min: float = 1e-05
learning_rate_max: float = 0.001
weight_decay_min: float = 1e-06
weight_decay_max: float = 0.001
batch_size_options: tuple[int, ...] = (32, 64, 128, 256)
class OCDocker.OCScore.Optimization.OptunaSearchSpace.EncoderSearchSpace(hidden_size_options=(32, 64, 128, 256, 512), depth_options=(2, 3, 4), latent_dim_options=(8, 16, 32, 64, 128), dropout_min=0.0, dropout_max=0.3, max_hidden_layers=4)[source]

Bases: object

Encoder / feature-extractor search space.

The encoder is constrained to be monotonic (non-increasing widths). Same-size plateaus are allowed; expansion between encoder layers is not sampled.

Parameters:

  • hidden_size_options (tuple[int, ...], optional) – Candidate hidden widths, by default (32, 64, 128, 256, 512).

  • depth_options (tuple[int, ...], optional) – Candidate encoder depths, by default (2, 3, 4).

  • latent_dim_options (tuple[int, ...], optional) – Candidate latent dimensions, by default (8, 16, 32, 64, 128).

  • dropout_min (float, optional) – Minimum encoder dropout, by default 0.0.

  • dropout_max (float, optional) – Maximum encoder dropout, by default 0.3.

  • max_hidden_layers (int, optional) – Maximum number of encoder_hidden_* Optuna parameters, by default 4.

hidden_size_options: tuple[int, ...] = (32, 64, 128, 256, 512)
depth_options: tuple[int, ...] = (2, 3, 4)
latent_dim_options: tuple[int, ...] = (8, 16, 32, 64, 128)
dropout_min: float = 0.0
dropout_max: float = 0.3
max_hidden_layers: int = 4
class OCDocker.OCScore.Optimization.OptunaSearchSpace.ProjectionSearchSpace(projection_dim_options=(0, 16, 32, 64, 128))[source]

Bases: object

Projection block search space after the encoder.

Parameters:

projection_dim_options (tuple[int, ...], optional) – Candidate projection dimensions. 0 disables the projection block.

projection_dim_options: tuple[int, ...] = (0, 16, 32, 64, 128)
class OCDocker.OCScore.Optimization.OptunaSearchSpace.DecoderSearchSpace(depth_options=(1, 2, 3), hidden_size_options=(8, 16, 32, 64, 128, 256, 512), lambda_rec_options=(0.0, 0.01, 0.05, 0.1, 0.2))[source]

Bases: object

Optional PDBbind reconstruction decoder search space.

The decoder is a PDBbind-only auxiliary branch. It is not transferred to DUDEz. Decoder hidden layers may expand toward the input dimension.

Parameters:

  • depth_options (tuple[int, ...], optional) – Candidate decoder depths, by default (1, 2, 3).

  • hidden_size_options (tuple[int, ...], optional) – Candidate explicit decoder hidden widths.

  • lambda_rec_options (tuple[float, ...], optional) – Reconstruction-loss weights. 0.0 disables the decoder.

depth_options: tuple[int, ...] = (1, 2, 3)
hidden_size_options: tuple[int, ...] = (8, 16, 32, 64, 128, 256, 512)
lambda_rec_options: tuple[float, ...] = (0.0, 0.01, 0.05, 0.1, 0.2)
class OCDocker.OCScore.Optimization.OptunaSearchSpace.PDBbindHeadSearchSpace(regression_loss_options=('huber', 'mse'), huber_delta_min=0.1, huber_delta_max=2.0)[source]

Bases: object

PDBbind regression-head search space.

Parameters:

  • regression_loss_options (tuple[str, ...], optional) – Regression loss candidates, by default ("huber", "mse").

  • huber_delta_min (float, optional) – Minimum Huber delta when Huber loss is selected.

  • huber_delta_max (float, optional) – Maximum Huber delta when Huber loss is selected.

regression_loss_options: tuple[str, ...] = ('huber', 'mse')
huber_delta_min: float = 0.1
huber_delta_max: float = 2.0
class OCDocker.OCScore.Optimization.OptunaSearchSpace.DUDEzHeadSearchSpace(classifier_hidden_size_options=(32, 64, 128, 256), classifier_dropout_min=0.0, classifier_dropout_max=0.3, fine_tuning_mode_options=('frozen', 'partial', 'full'), num_unfrozen_layers_options=(1, 2, 3), use_transfer_options=(True, False), use_class_weighting_options=(True, False))[source]

Bases: object

DUDEz classifier-head and transfer search space.

Parameters:

  • classifier_hidden_size_options (tuple[int, ...], optional) – Classifier hidden-size candidates.

  • classifier_dropout_min (float, optional) – Minimum classifier dropout.

  • classifier_dropout_max (float, optional) – Maximum classifier dropout.

  • fine_tuning_mode_options (tuple[str, ...], optional) – Feature-extractor fine-tuning modes.

  • num_unfrozen_layers_options (tuple[int, ...], optional) – Candidate numbers of unfrozen encoder layers in partial mode.

  • use_transfer_options (tuple[bool, ...], optional) – Whether from-scratch extractors are allowed when allow_scratch is True.

  • use_class_weighting_options (tuple[bool, ...], optional) – Class-weighting candidates when class weighting is tunable.

classifier_hidden_size_options: tuple[int, ...] = (32, 64, 128, 256)
classifier_dropout_min: float = 0.0
classifier_dropout_max: float = 0.3
fine_tuning_mode_options: tuple[str, ...] = ('frozen', 'partial', 'full')
num_unfrozen_layers_options: tuple[int, ...] = (1, 2, 3)
use_transfer_options: tuple[bool, ...] = (True, False)
use_class_weighting_options: tuple[bool, ...] = (True, False)
class OCDocker.OCScore.Optimization.OptunaSearchSpace.SharedNeuralSearchSpace(activation_options=('ReLU', 'LeakyReLU', 'ELU', 'GELU', 'SiLU', 'Mish'), encoder=<factory>, projection=<factory>, optimizer=<factory>)[source]

Bases: object

Search-space blocks shared by PDBbind and DUDEz stages.

Parameters:

  • activation_options (tuple[str, ...], optional) – Activation candidates for encoder/projection/decoder/classifier blocks.

  • encoder (EncoderSearchSpace, optional) – Encoder search space.

  • projection (ProjectionSearchSpace, optional) – Projection-block search space.

  • optimizer (OptimizerSearchSpace, optional) – Optimizer search space.

activation_options: tuple[str, ...] = ('ReLU', 'LeakyReLU', 'ELU', 'GELU', 'SiLU', 'Mish')
encoder: EncoderSearchSpace
projection: ProjectionSearchSpace
optimizer: OptimizerSearchSpace
class OCDocker.OCScore.Optimization.OptunaSearchSpace.PDBbindSearchSpaceConfig(activation_options=('ReLU', 'LeakyReLU', 'ELU', 'GELU', 'SiLU', 'Mish'), encoder=<factory>, projection=<factory>, optimizer=<factory>, decoder=<factory>, pdbbind_head=<factory>)[source]

Bases: SharedNeuralSearchSpace

Full PDBbind staged Optuna search space.

Parameters:
decoder: DecoderSearchSpace
pdbbind_head: PDBbindHeadSearchSpace
class OCDocker.OCScore.Optimization.OptunaSearchSpace.DUDEzSearchSpaceConfig(activation_options=('ReLU', 'LeakyReLU', 'ELU', 'GELU', 'SiLU', 'Mish'), encoder=<factory>, projection=<factory>, optimizer=<factory>, dudez_head=<factory>)[source]

Bases: SharedNeuralSearchSpace

Full DUDEz staged Optuna search space.

Parameters:
dudez_head: DUDEzHeadSearchSpace
OCDocker.OCScore.Optimization.OptunaSearchSpace.validate_pdbbind_search_phase(phase)[source]

Return a normalized PDBbind search-phase name.

Parameters:

phase (str) – Requested phase (full or encoder_regression).

Returns:

Validated phase string.

Return type:

str

Raises:

ValueError – If the phase is unknown.

OCDocker.OCScore.Optimization.OptunaSearchSpace.pdbbind_search_space_for_phase(phase, *, base=None)[source]

Build a PDBbind search space for a staged search phase.

Parameters:

  • phase (str) – full uses the default wide space. encoder_regression restricts PDBbind to encoder + regression only (no decoder, DAE, or projection).

  • base (PDBbindSearchSpaceConfig | None, optional) – Optional base configuration copied before phase overrides.

Returns:

Phase-specific search-space configuration.

Return type:

PDBbindSearchSpaceConfig

OCDocker.OCScore.Optimization.OptunaSearchSpace.available_activation_options(requested=None)[source]

Return activation names supported by the installed PyTorch build.

Parameters:

requested (Sequence[str] | None, optional) – Candidate activation names. Defaults to DEFAULT_ACTIVATION_OPTIONS.

Returns:

Activation names that can be constructed at runtime.

Return type:

tuple[str, …]

Raises:

ValueError – If no requested activation is available.

OCDocker.OCScore.Optimization.OptunaSearchSpace.activation_is_available(name)[source]

Return whether one activation name is supported.

Parameters:

name (str) – Activation name.

Returns:

True when the activation can be constructed.

Return type:

bool

OCDocker.OCScore.Optimization.OptunaSearchSpace.build_activation_module(name)[source]

Build one activation module from a centralized search-space name.

Parameters:

name (str) – Activation name from DEFAULT_ACTIVATION_OPTIONS.

Returns:

Instantiated activation module.

Return type:

torch.nn.Module

Raises:

ValueError – If the activation is unknown or unavailable in the installed PyTorch build.

OCDocker.OCScore.Optimization.OptunaSearchSpace.search_space_to_summary(space)[source]

Convert one search-space dataclass into a JSON-compatible summary.

Parameters:

space (SharedNeuralSearchSpace) – Search-space configuration object.

Returns:

JSON-compatible search-space summary.

Return type:

dict[str, Any]