ictonyx.config

ModelConfig and configuration helpers.

class ictonyx.config.ModelConfig(params=None)

Bases: object

Training configuration container with validation and factory methods.

Stores hyperparameters as a flat dictionary with typed property accessors for common parameters (epochs, batch_size, learning_rate). Supports dictionary-style access, method chaining, deep copying, and parameter validation.

Use the factory classmethods to create pre-configured defaults for common model types.

Parameters:

params (Dict[str, Any] | None) – Dictionary of hyperparameters. If None, an empty config is created.

Example:

config = ModelConfig({'epochs': 20, 'batch_size': 64})
config.learning_rate = 0.001
config.set('dropout', 0.3).set('optimizer', 'adam')

See also

from_defaults(), for_cnn(), for_xgboost(), for_variability_study()

__init__(params=None)

Initialize the config with a dictionary of parameters.

Parameters:

params (Dict[str, Any] | None)

to_dict()

Return a shallow copy of the parameters dictionary.

Return type:

Dict[str, Any]

get(key, default=None)

Get parameter with optional default value.

Parameters:

• key (str)

• default (Any)

Return type:

Any

set(key, value)

Set parameter and return self for chaining.

Parameters:

• key (str)

• value (Any)

Return type:

ModelConfig

update(other_params)

Update multiple parameters at once and return self for chaining.

Parameters:

other_params (Dict[str, Any])

Return type:

ModelConfig

merge(other_params)

Alias for update().

Deprecated since version 0.3.9: merge() is identical to update() and will be removed in v0.5.0. Use update() instead.

Parameters:

other_params (Dict[str, Any])

Return type:

ModelConfig

has(key)

Check if parameter exists.

Deprecated since version 0.3.9: Use the in operator instead: 'key' in config. Will be removed in v0.5.0.

Parameters:

key (str)

Return type:

bool

keys()

Get all parameter keys.

Return type:

KeysView[str]

values()

Get all parameter values.

Return type:

ValuesView[Any]

items()

Get all parameter key-value pairs.

Return type:

ItemsView[str, Any]

copy()

Create a deep copy of the configuration.

The frozen state is preserved: a frozen config produces a frozen copy.

Return type:

ModelConfig

freeze()

Make this config read-only to prevent mutation after construction.

Once frozen, any attempt to set or update parameters raises RuntimeError. Returns self for method chaining.

Example:

config = ModelConfig({"epochs": 10}).freeze()
config.set("epochs", 20)  # raises RuntimeError

Return type:

ModelConfig

validate_required(required_params)

Check if required parameters are present.

Parameters:

required_params (List[str]) – List of parameter names that must be present

Returns:

List of missing parameter names (empty if all present)

Return type:

List[str]

validate_types(type_specs)

Validate parameter types.

Parameters:

type_specs (Dict[str, type]) – Dictionary mapping parameter names to expected types

Returns:

List of validation error messages (empty if all valid)

Return type:

List[str]

property epochs: int | None

Get epochs parameter.

property batch_size: int | None

Get batch_size parameter.

property learning_rate: float | None

Get learning_rate parameter.

property verbose: int | None

Get verbose parameter.

property num_runs: int | None

Get num_runs parameter for variability studies.

property epochs_per_run: int | None

Get epochs_per_run parameter for variability studies.

classmethod from_defaults()

Create a config with sensible defaults for a generic training run.

Returns:

A ModelConfig with epochs=10, batch_size=32, learning_rate=0.001, verbose=0, and cleanup_threshold=0.8.

Return type:

ModelConfig

classmethod for_cnn(input_shape=(128, 128, 3), num_classes=10)

Create a config with defaults suitable for a CNN model.

Extends from_defaults() with CNN-specific parameters and a more aggressive cleanup threshold (0.75) for memory-intensive models.

Parameters:

• input_shape (tuple) – Spatial dimensions and channels, e.g. (64, 64, 3).

• num_classes (int) – Number of output classes.

Returns:

A ModelConfig with CNN-appropriate defaults.

Return type:

ModelConfig

classmethod for_xgboost(num_classes=10)

Create a config with defaults suitable for an XGBoost model.

Extends from_defaults() with n_estimators=180, max_depth=7, and the appropriate objective function (binary:logistic for 2 classes, multi:softprob otherwise).

Parameters:

num_classes (int) – Number of output classes.

Returns:

A ModelConfig with XGBoost-appropriate defaults.

Return type:

ModelConfig

classmethod for_variability_study(base_config, num_runs=20)

Create a config for a variability study from an existing base config.

Copies the base config and adds study-specific parameters (num_runs, epochs_per_run).

Parameters:

• base_config (ModelConfig) – An existing ModelConfig to use as a template.

• num_runs (int) – Number of independent training runs. Default 20.

Returns:

A new ModelConfig with study parameters added.

Return type:

ModelConfig

property cleanup_threshold: float | None

Get cleanup_threshold parameter.