dfm-python 0.6.13__tar.gz → 0.6.14__tar.gz

{dfm_python-0.6.13 → dfm_python-0.6.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfm-python
-Version: 0.6.13
+Version: 0.6.14
 Summary: Dynamic Factor Model (DFM) estimation and forecasting in Python
 Project-URL: Homepage, https://github.com/yourusername/dfm-python
 Project-URL: Documentation, https://github.com/yourusername/dfm-python#readme

{dfm_python-0.6.13 → dfm_python-0.6.14}/config/ddfm_exchange.yaml

@@ -9,16 +9,20 @@ encoder_layers: [16, 4]  # Hidden layers: [16] -> latent: 4 (matching original s
 activation: relu  # Matching original link='relu'
 use_batch_norm: true  # Matching original batch_norm=True
 
-# Training Parameters (matching original TensorFlow DDFM)
-learning_rate: 0.005  # Matching original learning_rate=0.005
-n_mc_samples: 10  # Number of MC samples per MCMC iteration (matching original epochs=10)
-window_size: 100  # Time-step batch size for training (matching original batch_size=100)
+# Training Parameters
+# NOTE: for fair comparison with iVDFM exchange tutorial/config, we align the
+# effective window length and training budget (see ivdfm_exchange.yaml).
+learning_rate: 0.005
+n_mc_samples: 10
+window_size: 200  # Align with iVDFM sequence_length=200
 
-# MCMC/Iterative Parameters (matching original TensorFlow DDFM)
-max_epoch: 200  # Maximum MCMC iterations (matching original max_iter=200)
-tolerance: 0.0005  # Convergence tolerance (matching original tolerance=0.0005)
-disp: 10  # Display frequency for training progress (matching original disp=10)
-seed: 3  # Random seed (matching original seed=3)
+# MCMC/Iterative Parameters
+# NOTE: DDFM uses max_epoch as an iteration budget; iVDFM uses max_epochs.
+# We set this to 10 here to make the tutorials comparable in runtime budget.
+max_epoch: 10
+tolerance: 0.0005
+disp: 10
+seed: 3
 
 # Interpolation Parameters
 interpolation_method: linear  # Interpolation method for missing values
@@ -28,16 +32,3 @@ interpolation_limit_direction: both  # Direction to fill ('forward', 'backward',
 # Data Handling (used by Dataset, not Model)
 clock: d  # Daily clock frequency (all series are daily)
 scaler: null  # No scaler - data should be pre-scaled before passing to Dataset
-
-# Frequency mapping (all series are daily)
-# If not specified, all series use clock frequency (d)
-# Format: {"series_name": "frequency_code"}
-# frequency:
-#   AUD_USD: d
-#   GBP_USD: d
-#   CAD_USD: d
-#   CHF_USD: d
-#   CNY_USD: d
-#   JPY_USD: d
-#   SGD_USD: d
-#   NZD_USD: d

{dfm_python-0.6.13 → dfm_python-0.6.14}/config/ddfm_finance.yaml

@@ -3,17 +3,24 @@
 # Clock: Monthly (m) - all series are monthly frequency
 
 # Neural Network Architecture
-encoder_layers: [64, 32, 2]  # Hidden layers: [64, 32] -> latent: 2 factors
+# Match iVDFM depth/width more closely: 3 hidden layers of size ~200
+encoder_layers: [64, 32, 5]  # Hidden layers: [200, 200] -> latent: 5 factors (match iVDFM capacity)
 activation: relu  # Activation function: 'tanh', 'relu', 'sigmoid'
 use_batch_norm: true  # Use batch normalization
+decoder_type: mlp  # Use non-linear (MLP) decoder instead of linear
+
+# Target/covariate split
+# For DDFM finance: covariates are ALL columns except the target.
+target_col: market_forward_excess_returns
+covariates: all_except_target
 
 # Training Parameters
 learning_rate: 0.001  # Learning rate for optimizer
-n_mc_samples: 1  # Number of MC samples per MCMC iteration (reduced for faster execution)
-window_size: 100  # Time-step batch size for training
+n_mc_samples: 10  # Number of MC samples per MCMC iteration
+window_size: 200  # Align with iVDFM sequence_length=200
 
 # MCMC/Iterative Parameters
-max_epoch: 200  # Maximum MCMC iterations
+max_epoch: 10  # Align with iVDFM max_epochs=10
 tolerance: 0.0005  # Convergence tolerance
 disp: 10  # Display frequency for training progress
 seed: null  # Random seed (None uses default)
@@ -27,10 +34,4 @@ interpolation_limit_direction: both  # Direction to fill ('forward', 'backward',
 clock: m  # Monthly clock frequency
 scaler: standard  # Scaler for target series: 'standard', 'robust', 'minmax', 'maxabs', 'quantile', or null
 
-# Frequency mapping (optional)
-# If not specified, all series use clock frequency
-# Format: {"series_name": "frequency_code"}
-# frequency:
-#   gdp: q
-#   unemployment: m
-#   interest_rate: m
+

dfm_python-0.6.14/config/ivdfm_exchange.yaml

@@ -0,0 +1,39 @@
+# iVDFM Configuration for Exchange Rate Dataset
+# Data: 8 exchange rate series (AUD_USD, GBP_USD, CAD_USD, CHF_USD, CNY_USD, JPY_USD, SGD_USD, NZD_USD)
+# Clock: Daily (d) - all series are daily frequency
+# Date range: 1990-01-01 to 2010-10-10
+
+# ===== Model Structure =====
+# Latent dimension
+num_factors: 2
+sequence_length: 200  # Sequence length for sliding windows
+context: null  # Column names (DataFrame) or indices (array) for context variables. If None, time-based context is generated.
+context_dim: 1  # Dimension of context. Used when context is None (generates time-based context) or when context is multivariate.
+
+# ===== Neural Network Architecture =====
+encoder_hidden_dim: 200  # Encoder hidden dimension
+encoder_n_layers: 3  # Number of encoder layers
+decoder_hidden_dim: 200  # Decoder hidden dimension
+decoder_n_layers: 3  # Number of decoder layers
+prior_hidden_dim: 100  # Prior network hidden dimension
+prior_n_layers: 2  # Number of prior network layers
+activation: lrelu  # Activation function: 'relu', 'lrelu', 'tanh', 'sigmoid'
+slope: 0.1  # Leaky ReLU slope
+
+# ===== Dynamics and Distribution Parameters =====
+factor_order: 1  # AR order for factors (p in AR(p))
+innovation_distribution: laplace  # Innovation distribution: 'laplace', 'gaussian', 'student_t'
+decoder_var: 0.01  # Decoder variance (observation noise)
+
+# ===== Training Parameters =====
+learning_rate: 0.001  # Learning rate for optimizer
+optimizer: Adam  # Optimizer type: 'Adam', 'AdamW', 'SGD'
+batch_size: 256  # Batch size for training (larger to reduce #batches/epoch)
+max_epochs: 10  # Maximum training epochs
+tolerance: 1.0e-5  # Convergence tolerance
+seed: null  # Random seed (None uses default)
+
+# ===== Base Model Config (inherited) =====
+frequency: null  # iVDFM doesn't use mixed-frequency structure
+clock: d  # Daily clock frequency (all series are daily)
+scaler: null  # Scaler for targets: 'standard', 'robust', 'minmax', 'maxabs', 'quantile', or null. Applied to targets only (not context/auxiliary variables)

dfm_python-0.6.14/config/ivdfm_finance.yaml

@@ -0,0 +1,38 @@
+# iVDFM Configuration for Finance Dataset
+# Data: Finance data with market_forward_excess_returns as target variable
+# Clock: Monthly (m) - all series are monthly frequency
+
+# ===== Model Structure =====
+# Latent dimension
+num_factors: 5
+sequence_length: 200  # Sequence length for sliding windows
+context: null  # Column names (DataFrame) or indices (array) for context variables. If None, time-based context is generated.
+context_dim: 1  # Dimension of context. Used when context is None (generates time-based context) or when context is multivariate.
+
+# ===== Neural Network Architecture =====
+encoder_hidden_dim: 50  # Encoder hidden dimension
+encoder_n_layers: 2  # Number of encoder layers
+decoder_hidden_dim: 50  # Decoder hidden dimension
+decoder_n_layers: 2  # Number of decoder layers
+prior_hidden_dim: 100  # Prior network hidden dimension
+prior_n_layers: 2  # Number of prior network layers
+activation: lrelu  # Activation function: 'relu', 'lrelu', 'tanh', 'sigmoid'
+slope: 0.1  # Leaky ReLU slope
+
+# ===== Dynamics and Distribution Parameters =====
+factor_order: 2  # AR order for factors (p in AR(p))
+innovation_distribution: laplace  # Innovation distribution: 'laplace', 'gaussian', 'student_t'
+decoder_var: 0.01  # Decoder variance (observation noise)
+
+# ===== Training Parameters =====
+learning_rate: 0.001  # Learning rate for optimizer
+optimizer: Adam  # Optimizer type: 'Adam', 'AdamW', 'SGD'
+batch_size: 128  # Batch size for training (larger to reduce #batches/epoch)
+max_epochs: 10  # Maximum training epochs
+tolerance: 1.0e-5  # Convergence tolerance
+seed: null  # Random seed (None uses default)
+
+# ===== Base Model Config (inherited) =====
+frequency: null  # iVDFM doesn't use mixed-frequency structure
+clock: m  # Monthly clock frequency
+scaler: standard  # Scaler for targets: 'standard', 'robust', 'minmax', 'maxabs', 'quantile', or null. Applied to targets only (not context/auxiliary variables)

dfm_python-0.6.14/config/ivdfm_macro.yaml

@@ -0,0 +1,40 @@
+# iVDFM Configuration for Macroeconomic Datasets
+# Based on Korean economic indicators (KO* series)
+# Data: 101 series, mixed weekly/monthly frequency (1985-04-05 to 2025-11-21)
+# Clock: Weekly (w) - base frequency for latent factors
+# Target: KOEQUIPTE (Investment, Equipment, Estimation, SA)
+
+# ===== Model Structure =====
+# Latent dimension
+num_factors: 5
+sequence_length: 200  # Sequence length for sliding windows
+context: null  # Column names (DataFrame) or indices (array) for context variables. If None, time-based context is generated.
+context_dim: 1  # Dimension of context. Used when context is None (generates time-based context) or when context is multivariate.
+
+# ===== Neural Network Architecture =====
+encoder_hidden_dim: 200  # Encoder hidden dimension
+encoder_n_layers: 3  # Number of encoder layers
+decoder_hidden_dim: 200  # Decoder hidden dimension
+decoder_n_layers: 3  # Number of decoder layers
+prior_hidden_dim: 100  # Prior network hidden dimension
+prior_n_layers: 2  # Number of prior network layers
+activation: lrelu  # Activation function: 'relu', 'lrelu', 'tanh', 'sigmoid'
+slope: 0.1  # Leaky ReLU slope
+
+# ===== Dynamics and Distribution Parameters =====
+factor_order: 3  # AR order for factors (p in AR(p))
+innovation_distribution: laplace  # Innovation distribution: 'laplace', 'gaussian', 'student_t'
+decoder_var: 0.01  # Decoder variance (observation noise)
+
+# ===== Training Parameters =====
+learning_rate: 0.001  # Learning rate for optimizer
+optimizer: Adam  # Optimizer type: 'Adam', 'AdamW', 'SGD'
+batch_size: 256  # Batch size for training (larger to reduce #batches/epoch)
+max_epochs: 10  # Maximum training epochs
+tolerance: 1.0e-5  # Convergence tolerance
+seed: null  # Random seed (None uses default)
+
+# ===== Base Model Config (inherited) =====
+frequency: null  # iVDFM doesn't use mixed-frequency structure
+clock: w  # Weekly clock frequency (base frequency for latent factors)
+scaler: standard  # Scaler for targets: 'standard', 'robust', 'minmax', 'maxabs', 'quantile', or null. Applied to targets only (not context/auxiliary variables)

{dfm_python-0.6.13 → dfm_python-0.6.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dfm-python"
-version = "0.6.13"
+version = "0.6.14"
 description = "Dynamic Factor Model (DFM) estimation and forecasting in Python"
 requires-python = ">=3.10"
 license = {text = "MIT"}

{dfm_python-0.6.13 → dfm_python-0.6.14}/src/dfm_python/config/constants.py

@@ -344,6 +344,47 @@ COMPUTATION_ERROR_TYPES = (RuntimeError, ValueError, TypeError, AttributeError,
 DEFAULT_KDFM_AR_ORDER = 1  # Default AR order (VAR lag order p) for KDFM
 DEFAULT_KDFM_MA_ORDER = 0  # Default MA order (MA lag order q) for KDFM (0 = pure VAR)
 
+# ============================================================================
+# iVDFM Defaults
+# ============================================================================
+
+# iVDFM sequence and dimension defaults
+DEFAULT_IVDFM_SEQUENCE_LENGTH = 100  # Default sequence length for sliding windows
+DEFAULT_IVDFM_LATENT_DIM = 3  # Default number of factors
+DEFAULT_IVDFM_AUX_DIM = 1  # Default auxiliary variable dimension
+
+# iVDFM network architecture defaults
+DEFAULT_IVDFM_ENCODER_HIDDEN_DIM = 200  # Default encoder hidden dimension
+DEFAULT_IVDFM_ENCODER_N_LAYERS = 3  # Default encoder layers
+DEFAULT_IVDFM_DECODER_HIDDEN_DIM = 200  # Default decoder hidden dimension
+DEFAULT_IVDFM_DECODER_N_LAYERS = 3  # Default decoder layers
+DEFAULT_IVDFM_PRIOR_HIDDEN_DIM = 100  # Default prior network hidden dimension
+DEFAULT_IVDFM_PRIOR_N_LAYERS = 2  # Default prior network layers
+
+# iVDFM dynamics and distribution defaults
+DEFAULT_IVDFM_FACTOR_ORDER = 1  # Default AR order for factors
+DEFAULT_IVDFM_INNOVATION_DIST = 'laplace'  # Default innovation distribution
+DEFAULT_IVDFM_DECODER_VAR = 0.01  # Default decoder variance
+DEFAULT_IVDFM_ACTIVATION = 'lrelu'  # Default activation function
+DEFAULT_IVDFM_SLOPE = 0.1  # Default leaky ReLU slope
+
+# iVDFM training defaults
+DEFAULT_IVDFM_BATCH_SIZE = 32  # Default batch size
+DEFAULT_IVDFM_MAX_EPOCHS = 100  # Default maximum epochs
+DEFAULT_IVDFM_AUX_VARIABLE_TYPE = 'time'  # Default auxiliary variable type
+
+# iVDFM optimizer defaults
+DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY = 0.0  # Default weight decay for optimizer
+DEFAULT_IVDFM_OPTIMIZER_MOMENTUM = 0.9  # Default momentum for SGD
+
+# iVDFM scheduler defaults
+DEFAULT_IVDFM_SCHEDULER_TYPE = 'step'  # Default scheduler type: 'step', 'plateau', 'cosine', 'exponential', None
+DEFAULT_IVDFM_SCHEDULER_STEP_SIZE = None  # Default step_size for StepLR (auto: max_epochs // 3)
+DEFAULT_IVDFM_SCHEDULER_GAMMA = 0.5  # Default gamma for StepLR/ExponentialLR
+DEFAULT_IVDFM_SCHEDULER_PATIENCE = 10  # Default patience for ReduceLROnPlateau
+DEFAULT_IVDFM_SCHEDULER_FACTOR = 0.1  # Default factor for ReduceLROnPlateau
+DEFAULT_IVDFM_SCHEDULER_MIN_LR = 0.0  # Default min_lr for ReduceLROnPlateau
+
 # ============================================================================
 # Tutorial Defaults
 # ============================================================================
@@ -564,6 +605,24 @@ __all__ = [
     # KDFM defaults
     'DEFAULT_KDFM_AR_ORDER',
     'DEFAULT_KDFM_MA_ORDER',
+    # iVDFM defaults
+    'DEFAULT_IVDFM_SEQUENCE_LENGTH',
+    'DEFAULT_IVDFM_LATENT_DIM',
+    'DEFAULT_IVDFM_AUX_DIM',
+    'DEFAULT_IVDFM_ENCODER_HIDDEN_DIM',
+    'DEFAULT_IVDFM_ENCODER_N_LAYERS',
+    'DEFAULT_IVDFM_DECODER_HIDDEN_DIM',
+    'DEFAULT_IVDFM_DECODER_N_LAYERS',
+    'DEFAULT_IVDFM_PRIOR_HIDDEN_DIM',
+    'DEFAULT_IVDFM_PRIOR_N_LAYERS',
+    'DEFAULT_IVDFM_FACTOR_ORDER',
+    'DEFAULT_IVDFM_INNOVATION_DIST',
+    'DEFAULT_IVDFM_DECODER_VAR',
+    'DEFAULT_IVDFM_ACTIVATION',
+    'DEFAULT_IVDFM_SLOPE',
+    'DEFAULT_IVDFM_BATCH_SIZE',
+    'DEFAULT_IVDFM_MAX_EPOCHS',
+    'DEFAULT_IVDFM_AUX_VARIABLE_TYPE',
     # Tutorial defaults
     'TUTORIAL_MAX_PERIODS',
     'TUTORIAL_MAX_EPOCHS',

dfm_python-0.6.14/src/dfm_python/config/schema/__init__.py

@@ -0,0 +1,19 @@
+"""Configuration schema package for DFM models.
+
+This package contains:
+- model.py: BaseModelConfig, DFMConfig, DDFMConfig - model configurations
+- results.py: BaseResult, DFMResult, DDFMResult - result structures
+
+Note: Series are specified via frequency dict mapping column names to frequencies.
+"""
+
+from .model import BaseModelConfig, DFMConfig, DDFMConfig, iVDFMConfig
+from .results import BaseResult, DFMResult, DDFMResult, iVDFMResult
+from .params import DFMStateSpaceParams, DDFMStateSpaceParams, iVDFMModelState
+
+__all__ = [
+    'BaseModelConfig', 'DFMConfig', 'DDFMConfig', 'iVDFMConfig',
+    'BaseResult', 'DFMResult', 'DDFMResult', 'iVDFMResult',
+    'DFMStateSpaceParams', 'DDFMStateSpaceParams', 'iVDFMModelState',
+]
+

{dfm_python-0.6.13 → dfm_python-0.6.14}/src/dfm_python/config/schema/model.py

@@ -48,6 +48,14 @@ from ..constants import (
     DEFAULT_BATCH_SIZE,
     DEFAULT_DDFM_WINDOW_SIZE,
     DEFAULT_GRAD_CLIP_VAL,
+    DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY,
+    DEFAULT_IVDFM_OPTIMIZER_MOMENTUM,
+    DEFAULT_IVDFM_SCHEDULER_TYPE,
+    DEFAULT_IVDFM_SCHEDULER_STEP_SIZE,
+    DEFAULT_IVDFM_SCHEDULER_GAMMA,
+    DEFAULT_IVDFM_SCHEDULER_PATIENCE,
+    DEFAULT_IVDFM_SCHEDULER_FACTOR,
+    DEFAULT_IVDFM_SCHEDULER_MIN_LR,
     DEFAULT_REGULARIZATION_SCALE,
     DEFAULT_STRUCTURAL_REG_WEIGHT,
     DEFAULT_CONVERGENCE_THRESHOLD,
@@ -70,6 +78,23 @@ from ..constants import (
     DEFAULT_KDFM_MA_ORDER,
     FREQUENCY_HIERARCHY,
     DEFAULT_HIERARCHY_VALUE,
+    DEFAULT_IVDFM_SEQUENCE_LENGTH,
+    DEFAULT_IVDFM_LATENT_DIM,
+    DEFAULT_IVDFM_AUX_DIM,
+    DEFAULT_IVDFM_ENCODER_HIDDEN_DIM,
+    DEFAULT_IVDFM_ENCODER_N_LAYERS,
+    DEFAULT_IVDFM_DECODER_HIDDEN_DIM,
+    DEFAULT_IVDFM_DECODER_N_LAYERS,
+    DEFAULT_IVDFM_PRIOR_HIDDEN_DIM,
+    DEFAULT_IVDFM_PRIOR_N_LAYERS,
+    DEFAULT_IVDFM_FACTOR_ORDER,
+    DEFAULT_IVDFM_INNOVATION_DIST,
+    DEFAULT_IVDFM_DECODER_VAR,
+    DEFAULT_IVDFM_ACTIVATION,
+    DEFAULT_IVDFM_SLOPE,
+    DEFAULT_IVDFM_BATCH_SIZE,
+    DEFAULT_IVDFM_MAX_EPOCHS,
+    DEFAULT_IVDFM_AUX_VARIABLE_TYPE,
 )
 
 
@@ -136,6 +161,7 @@ class BaseModelConfig:
     # ========================================================================
     clock: str = 'm'  # Required: Base frequency for latent factors (global clock): 'd', 'w', 'm', 'q', 'sa', 'a' (defaults to 'm' for monthly)
     target_scaler: Optional[ScalerType] = None  # Fitted sklearn scaler instance (StandardScaler, RobustScaler, etc.) for target series only. Must be a fitted scaler object (call .fit() on target data first). Pass scaler object directly, not string. Feature series are assumed to be manually preprocessed. If None, target series are assumed to be already in the desired scale.
+    scaler: Optional[str] = None  # Scaler type as string: 'standard', 'robust', 'minmax', 'maxabs', 'quantile', or null. Applied to targets only (not context/auxiliary variables). For iVDFM, this is the preferred way to specify scaler (like DDFM pattern).
     
     def __post_init__(self):
         """Validate basic model structure.
@@ -626,6 +652,244 @@ class DDFMConfig(BaseModelConfig):
         )
 
 
+@dataclass
+class iVDFMConfig(BaseModelConfig):
+    """Identifiable Variational Dynamic Factor Model configuration.
+    
+    Uses 'scaler' (string) pattern like DDFM, not 'target_scaler' (instance).
+    Scaler is applied to targets only, not to context/auxiliary variables.
+    """
+    """Identifiable Variational Dynamic Factor Model configuration.
+    
+    This configuration class extends BaseModelConfig with parameters specific
+    to iVDFM models trained using variational inference with identifiable
+    innovation priors.
+    
+    Note: iVDFM does NOT use block structure. Use num_factors directly to specify
+    the number of factors.
+    
+    The configuration can be built from:
+    - Main settings (training parameters) from config files
+    - Series definitions via frequency dict (column names -> frequencies)
+    """
+    # ========================================================================
+    # Model Structure
+    # ========================================================================
+    num_factors: Optional[int] = None  # Number of factors (inferred from config if None)
+    sequence_length: int = DEFAULT_IVDFM_SEQUENCE_LENGTH  # Sequence length for training
+    context: Optional[Union[List[str], List[int]]] = None  # Column names (DataFrame) or indices (array) for context variables. If None, context_dim is used to generate time-based context.
+    context_dim: int = DEFAULT_IVDFM_AUX_DIM  # Dimension of context. Used when context is None (generates time-based context) or when context is multivariate.
+    
+    # ========================================================================
+    # Neural Network Architecture
+    # ========================================================================
+    encoder_hidden_dim: Union[int, List[int]] = DEFAULT_IVDFM_ENCODER_HIDDEN_DIM  # Encoder architecture
+    encoder_n_layers: int = DEFAULT_IVDFM_ENCODER_N_LAYERS  # Number of encoder layers
+    decoder_hidden_dim: Union[int, List[int]] = DEFAULT_IVDFM_DECODER_HIDDEN_DIM  # Decoder architecture
+    decoder_n_layers: int = DEFAULT_IVDFM_DECODER_N_LAYERS  # Number of decoder layers
+    prior_hidden_dim: Union[int, List[int]] = DEFAULT_IVDFM_PRIOR_HIDDEN_DIM  # Prior network architecture
+    prior_n_layers: int = DEFAULT_IVDFM_PRIOR_N_LAYERS  # Number of prior network layers
+    activation: str = DEFAULT_IVDFM_ACTIVATION  # Activation function
+    slope: float = DEFAULT_IVDFM_SLOPE  # Leaky ReLU slope
+    
+    # ========================================================================
+    # Dynamics and Distribution Parameters
+    # ========================================================================
+    factor_order: int = DEFAULT_IVDFM_FACTOR_ORDER  # AR order for factors
+    innovation_distribution: str = DEFAULT_IVDFM_INNOVATION_DIST  # Innovation distribution type
+    decoder_var: float = DEFAULT_IVDFM_DECODER_VAR  # Decoder variance
+    
+    # ========================================================================
+    # Training Parameters
+    # ========================================================================
+    learning_rate: float = DEFAULT_LEARNING_RATE  # Learning rate
+    optimizer: str = 'Adam'  # Optimizer type
+    optimizer_weight_decay: float = DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY  # Weight decay (L2 regularization)
+    optimizer_momentum: float = DEFAULT_IVDFM_OPTIMIZER_MOMENTUM  # Momentum for SGD
+    batch_size: int = DEFAULT_IVDFM_BATCH_SIZE  # Batch size
+    max_epochs: int = DEFAULT_IVDFM_MAX_EPOCHS  # Maximum epochs
+    tolerance: float = DEFAULT_TOLERANCE  # Convergence tolerance
+    seed: Optional[int] = None  # Random seed
+    
+    # ========================================================================
+    # Scheduler Parameters
+    # ========================================================================
+    scheduler_type: Optional[str] = DEFAULT_IVDFM_SCHEDULER_TYPE  # Scheduler type: 'step', 'plateau', 'cosine', 'exponential', None
+    scheduler_step_size: Optional[int] = DEFAULT_IVDFM_SCHEDULER_STEP_SIZE  # Step size for StepLR (None = auto: max_epochs // 3)
+    scheduler_gamma: float = DEFAULT_IVDFM_SCHEDULER_GAMMA  # Gamma for StepLR/ExponentialLR
+    scheduler_patience: int = DEFAULT_IVDFM_SCHEDULER_PATIENCE  # Patience for ReduceLROnPlateau
+    scheduler_factor: float = DEFAULT_IVDFM_SCHEDULER_FACTOR  # Factor for ReduceLROnPlateau
+    scheduler_min_lr: float = DEFAULT_IVDFM_SCHEDULER_MIN_LR  # Min learning rate for ReduceLROnPlateau
+    
+    def __post_init__(self):
+        """Validate iVDFM configuration."""
+        super().__post_init__()  # Validate base config
+        
+        from ...utils.errors import ConfigurationError
+        
+        # Validate sequence_length
+        if self.sequence_length < 1:
+            raise ConfigurationError(
+                f"sequence_length must be >= 1, got {self.sequence_length}"
+            )
+        
+        # Validate context_dim
+        if self.context_dim < 1:
+            raise ConfigurationError(
+                f"context_dim must be >= 1, got {self.context_dim}"
+            )
+        
+        # Validate num_factors if provided
+        if self.num_factors is not None and self.num_factors < 1:
+            raise ConfigurationError(
+                f"num_factors must be >= 1, got {self.num_factors}"
+            )
+        
+        # Validate factor_order
+        if self.factor_order < 1:
+            raise ConfigurationError(
+                f"factor_order must be >= 1, got {self.factor_order}"
+            )
+        
+        # Validate innovation_distribution
+        valid_dists = {'laplace', 'gaussian', 'student_t', 'gamma', 'beta', 'exponential'}
+        if self.innovation_distribution not in valid_dists:
+            raise ConfigurationError(
+                f"innovation_distribution must be one of {valid_dists}, got '{self.innovation_distribution}'"
+            )
+        
+        # Validate activation
+        valid_activations = {'relu', 'lrelu', 'tanh', 'sigmoid'}
+        if self.activation not in valid_activations:
+            raise ConfigurationError(
+                f"activation must be one of {valid_activations}, got '{self.activation}'"
+            )
+        
+        # Validate optimizer
+        from ..constants import VALID_OPTIMIZERS
+        if self.optimizer not in VALID_OPTIMIZERS:
+            raise ConfigurationError(
+                f"optimizer must be one of {VALID_OPTIMIZERS}, got '{self.optimizer}'"
+            )
+        
+        # Validate scheduler_type
+        valid_schedulers = {'step', 'plateau', 'cosine', 'exponential', None}
+        if self.scheduler_type not in valid_schedulers:
+            raise ConfigurationError(
+                f"scheduler_type must be one of {valid_schedulers}, got '{self.scheduler_type}'"
+            )
+        
+        # Validate scheduler parameters
+        if self.scheduler_gamma <= 0 or self.scheduler_gamma > 1:
+            raise ConfigurationError(
+                f"scheduler_gamma must be in (0, 1], got {self.scheduler_gamma}"
+            )
+        
+        if self.scheduler_patience < 0:
+            raise ConfigurationError(
+                f"scheduler_patience must be >= 0, got {self.scheduler_patience}"
+            )
+        
+        if self.scheduler_factor <= 0 or self.scheduler_factor > 1:
+            raise ConfigurationError(
+                f"scheduler_factor must be in (0, 1], got {self.scheduler_factor}"
+            )
+        
+        if self.scheduler_min_lr < 0:
+            raise ConfigurationError(
+                f"scheduler_min_lr must be >= 0, got {self.scheduler_min_lr}"
+            )
+    
+    @classmethod
+    def _extract_ivdfm(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract iVDFM-specific parameters from config dict."""
+        from ..constants import (
+            DEFAULT_IVDFM_SEQUENCE_LENGTH,
+            DEFAULT_IVDFM_LATENT_DIM,
+            DEFAULT_IVDFM_AUX_DIM,
+            DEFAULT_IVDFM_ENCODER_HIDDEN_DIM,
+            DEFAULT_IVDFM_ENCODER_N_LAYERS,
+            DEFAULT_IVDFM_DECODER_HIDDEN_DIM,
+            DEFAULT_IVDFM_DECODER_N_LAYERS,
+            DEFAULT_IVDFM_PRIOR_HIDDEN_DIM,
+            DEFAULT_IVDFM_PRIOR_N_LAYERS,
+            DEFAULT_IVDFM_FACTOR_ORDER,
+            DEFAULT_IVDFM_INNOVATION_DIST,
+            DEFAULT_IVDFM_DECODER_VAR,
+            DEFAULT_IVDFM_ACTIVATION,
+            DEFAULT_IVDFM_SLOPE,
+            DEFAULT_IVDFM_BATCH_SIZE,
+            DEFAULT_IVDFM_MAX_EPOCHS,
+            DEFAULT_IVDFM_AUX_VARIABLE_TYPE,
+            DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY,
+            DEFAULT_IVDFM_OPTIMIZER_MOMENTUM,
+            DEFAULT_IVDFM_SCHEDULER_TYPE,
+            DEFAULT_IVDFM_SCHEDULER_STEP_SIZE,
+            DEFAULT_IVDFM_SCHEDULER_GAMMA,
+            DEFAULT_IVDFM_SCHEDULER_PATIENCE,
+            DEFAULT_IVDFM_SCHEDULER_FACTOR,
+            DEFAULT_IVDFM_SCHEDULER_MIN_LR,
+        )
+        
+        ivdfm_params = cls._extract_params(data, {
+            'num_factors': None,
+            'sequence_length': DEFAULT_IVDFM_SEQUENCE_LENGTH,
+            'context': None,
+            'context_dim': DEFAULT_IVDFM_AUX_DIM,
+            'encoder_hidden_dim': DEFAULT_IVDFM_ENCODER_HIDDEN_DIM,
+            'encoder_n_layers': DEFAULT_IVDFM_ENCODER_N_LAYERS,
+            'decoder_hidden_dim': DEFAULT_IVDFM_DECODER_HIDDEN_DIM,
+            'decoder_n_layers': DEFAULT_IVDFM_DECODER_N_LAYERS,
+            'prior_hidden_dim': DEFAULT_IVDFM_PRIOR_HIDDEN_DIM,
+            'prior_n_layers': DEFAULT_IVDFM_PRIOR_N_LAYERS,
+            'activation': DEFAULT_IVDFM_ACTIVATION,
+            'slope': DEFAULT_IVDFM_SLOPE,
+            'factor_order': DEFAULT_IVDFM_FACTOR_ORDER,
+            'innovation_distribution': DEFAULT_IVDFM_INNOVATION_DIST,
+            'decoder_var': DEFAULT_IVDFM_DECODER_VAR,
+            'learning_rate': DEFAULT_LEARNING_RATE,
+            'optimizer': 'Adam',
+            'optimizer_weight_decay': DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY,
+            'optimizer_momentum': DEFAULT_IVDFM_OPTIMIZER_MOMENTUM,
+            'batch_size': DEFAULT_IVDFM_BATCH_SIZE,
+            'max_epochs': DEFAULT_IVDFM_MAX_EPOCHS,
+            'tolerance': DEFAULT_TOLERANCE,
+            'seed': None,
+            'scheduler_type': DEFAULT_IVDFM_SCHEDULER_TYPE,
+            'scheduler_step_size': DEFAULT_IVDFM_SCHEDULER_STEP_SIZE,
+            'scheduler_gamma': DEFAULT_IVDFM_SCHEDULER_GAMMA,
+            'scheduler_patience': DEFAULT_IVDFM_SCHEDULER_PATIENCE,
+            'scheduler_factor': DEFAULT_IVDFM_SCHEDULER_FACTOR,
+            'scheduler_min_lr': DEFAULT_IVDFM_SCHEDULER_MIN_LR,
+            'scaler': None,  # Scaler string: 'standard', 'robust', 'minmax', 'maxabs', 'quantile', or null
+        })
+        
+        return ivdfm_params
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'iVDFMConfig':
+        """Create iVDFMConfig from dictionary.
+        
+        Parameters
+        ----------
+        data : Dict[str, Any]
+            Configuration dictionary
+            
+        Returns
+        -------
+        iVDFMConfig
+            iVDFM configuration instance
+        """
+        # Extract base params
+        base_params = cls._extract_base(data)
+        
+        # Extract iVDFM-specific params
+        ivdfm_params = cls._extract_ivdfm(data)
+        
+        # Combine and create config
+        return cls(**base_params, **ivdfm_params)
+
+
 # ============================================================================
 # Validation Functions
 # ============================================================================