jtopmodel 0.1.0__py3-none-any.whl

jtopmodel/__init__.py

@@ -0,0 +1,198 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2024-2026 SYMFLUENCE Team <dev@symfluence.org>
+
+"""
+TOPMODEL (Beven & Kirkby 1979) -- Standalone Plugin Package.
+
+A native Python/JAX implementation of TOPMODEL, enabling:
+- Automatic differentiation for gradient-based calibration
+- JIT compilation for fast execution
+- DDS and evolutionary calibration integration
+
+Algorithms:
+    - Degree-day snow module
+    - Exponential transmissivity baseflow (Beven & Kirkby 1979)
+    - Saturation-excess overland flow with topographic index distribution
+    - Linear reservoir channel routing
+
+Components:
+    - TopmodelPreProcessor: Prepares forcing data (P, T, PET)
+    - TopmodelRunner: Executes model simulations
+    - TopmodelPostprocessor: Extracts streamflow results
+    - TopmodelWorker: Handles calibration
+
+References:
+    Beven, K.J. & Kirkby, M.J. (1979). A physically based, variable
+    contributing area model of basin hydrology. Hydrological Sciences
+    Bulletin, 24(1), 43-69.
+"""
+
+from typing import TYPE_CHECKING
+
+
+# Lazy import mapping: attribute name -> (module, attribute)
+_LAZY_IMPORTS = {
+    # Configuration
+    'TOPMODELConfig': ('.config', 'TOPMODELConfig'),
+    'TopmodelConfigAdapter': ('.config', 'TopmodelConfigAdapter'),
+
+    # Main components
+    'TopmodelPreProcessor': ('.preprocessor', 'TopmodelPreProcessor'),
+    'TopmodelRunner': ('.runner', 'TopmodelRunner'),
+    'TopmodelPostprocessor': ('.postprocessor', 'TopmodelPostprocessor'),
+    'TopmodelResultExtractor': ('.extractor', 'TopmodelResultExtractor'),
+
+    # Parameters
+    'PARAM_BOUNDS': ('.parameters', 'PARAM_BOUNDS'),
+    'DEFAULT_PARAMS': ('.parameters', 'DEFAULT_PARAMS'),
+    'TopmodelParameters': ('.parameters', 'TopmodelParameters'),
+    'TopmodelState': ('.parameters', 'TopmodelState'),
+    'create_params_from_dict': ('.parameters', 'create_params_from_dict'),
+    'create_initial_state': ('.parameters', 'create_initial_state'),
+    'generate_ti_distribution': ('.parameters', 'generate_ti_distribution'),
+
+    # Core model
+    'simulate': ('.model', 'simulate'),
+    'simulate_jax': ('.model', 'simulate_jax'),
+    'simulate_numpy': ('.model', 'simulate_numpy'),
+    'snow_step': ('.model', 'snow_step'),
+    'topmodel_step': ('.model', 'topmodel_step'),
+    'route_step': ('.model', 'route_step'),
+    'step': ('.model', 'step'),
+    'HAS_JAX': ('.model', 'HAS_JAX'),
+
+    # Loss functions (for gradient-based calibration)
+    'nse_loss': ('.losses', 'nse_loss'),
+    'kge_loss': ('.losses', 'kge_loss'),
+    'get_nse_gradient_fn': ('.losses', 'get_nse_gradient_fn'),
+    'get_kge_gradient_fn': ('.losses', 'get_kge_gradient_fn'),
+
+    # Calibration
+    'TopmodelWorker': ('.calibration.worker', 'TopmodelWorker'),
+    'TopmodelParameterManager': ('.calibration.parameter_manager', 'TopmodelParameterManager'),
+    'get_topmodel_calibration_bounds': ('.calibration.parameter_manager', 'get_topmodel_calibration_bounds'),
+}
+
+
+def __getattr__(name: str):
+    """Lazy import handler for TOPMODEL module components."""
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        from importlib import import_module
+        module = import_module(module_path, package=__name__)
+        return getattr(module, attr_name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    """Return available attributes for tab completion."""
+    return list(_LAZY_IMPORTS.keys()) + ['register']
+
+
+def register() -> None:
+    """Register TOPMODEL components with symfluence plugin registry."""
+    from symfluence.core.registry import model_manifest
+    from .calibration.optimizer import TopmodelModelOptimizer
+    from .calibration.parameter_manager import TopmodelParameterManager
+    from .calibration.worker import TopmodelWorker
+    from .config import TopmodelConfigAdapter
+    from .extractor import TopmodelResultExtractor
+    from .postprocessor import TopmodelPostprocessor
+    from .preprocessor import TopmodelPreProcessor
+    from .runner import TopmodelRunner
+
+    model_manifest(
+        "TOPMODEL",
+        preprocessor=TopmodelPreProcessor,
+        runner=TopmodelRunner,
+        runner_method='run_topmodel',
+        postprocessor=TopmodelPostprocessor,
+        config_adapter=TopmodelConfigAdapter,
+        result_extractor=TopmodelResultExtractor,
+        optimizer=TopmodelModelOptimizer,
+        worker=TopmodelWorker,
+        parameter_manager=TopmodelParameterManager,
+    )
+
+
+# Type hints for IDE support
+if TYPE_CHECKING:
+    from .calibration.parameter_manager import TopmodelParameterManager, get_topmodel_calibration_bounds
+    from .calibration.worker import TopmodelWorker
+    from .config import TOPMODELConfig, TopmodelConfigAdapter
+    from .extractor import TopmodelResultExtractor
+    from .losses import (
+        get_kge_gradient_fn,
+        get_nse_gradient_fn,
+        kge_loss,
+        nse_loss,
+    )
+    from .model import (
+        HAS_JAX,
+        route_step,
+        simulate,
+        simulate_jax,
+        simulate_numpy,
+        snow_step,
+        step,
+        topmodel_step,
+    )
+    from .parameters import (
+        DEFAULT_PARAMS,
+        PARAM_BOUNDS,
+        TopmodelParameters,
+        TopmodelState,
+        create_initial_state,
+        create_params_from_dict,
+        generate_ti_distribution,
+    )
+    from .postprocessor import TopmodelPostprocessor
+    from .preprocessor import TopmodelPreProcessor
+    from .runner import TopmodelRunner
+
+
+__all__ = [
+    # Main components
+    'TopmodelPreProcessor',
+    'TopmodelRunner',
+    'TopmodelPostprocessor',
+    'TopmodelResultExtractor',
+
+    # Configuration
+    'TOPMODELConfig',
+    'TopmodelConfigAdapter',
+
+    # Parameters
+    'PARAM_BOUNDS',
+    'DEFAULT_PARAMS',
+    'TopmodelParameters',
+    'TopmodelState',
+    'create_params_from_dict',
+    'create_initial_state',
+    'generate_ti_distribution',
+
+    # Core model
+    'simulate',
+    'simulate_jax',
+    'simulate_numpy',
+    'snow_step',
+    'topmodel_step',
+    'route_step',
+    'step',
+    'HAS_JAX',
+
+    # Loss functions
+    'nse_loss',
+    'kge_loss',
+    'get_nse_gradient_fn',
+    'get_kge_gradient_fn',
+
+    # Calibration
+    'TopmodelWorker',
+    'TopmodelParameterManager',
+    'get_topmodel_calibration_bounds',
+
+    # Plugin registration
+    'register',
+]

jtopmodel/calibration/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: GPL-3.0-or-later

jtopmodel/calibration/optimizer.py

@@ -0,0 +1,259 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2024-2026 SYMFLUENCE Team <dev@symfluence.org>
+
+"""
+TOPMODEL Optimizer.
+
+TOPMODEL-specific optimizer inheriting from BaseModelOptimizer.
+Supports DDS and other iterative optimization algorithms.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import numpy as np
+import pandas as pd
+
+from symfluence.evaluation.metrics import calculate_all_metrics
+from symfluence.optimization.optimizers.base_model_optimizer import BaseModelOptimizer
+
+
+class TopmodelModelOptimizer(BaseModelOptimizer):
+    """
+    TOPMODEL-specific optimizer using the unified BaseModelOptimizer framework.
+
+    Supports:
+    - Standard iterative optimization (DDS, PSO, SCE-UA, DE)
+    """
+
+    def __init__(
+        self,
+        config: Dict[str, Any],
+        logger: logging.Logger,
+        optimization_settings_dir: Optional[Path] = None,
+        reporting_manager: Optional[Any] = None
+    ):
+        self.experiment_id = config.get('EXPERIMENT_ID')
+        self.data_dir = Path(config.get('SYMFLUENCE_DATA_DIR'))
+        self.domain_name = config.get('DOMAIN_NAME')
+        self.project_dir = self.data_dir / f"domain_{self.domain_name}"
+
+        self.topmodel_setup_dir = self.project_dir / 'settings' / 'TOPMODEL'
+
+        super().__init__(config, logger, optimization_settings_dir, reporting_manager=reporting_manager)
+
+        self.logger.debug("TopmodelModelOptimizer initialized")
+
+    def _get_model_name(self) -> str:
+        """Return model name."""
+        return 'TOPMODEL'
+
+    def _get_final_file_manager_path(self) -> Path:
+        """Get path to TOPMODEL configuration (placeholder for in-memory model)."""
+        return self.topmodel_setup_dir / 'topmodel_config.txt'
+
+    def _create_parameter_manager(self):
+        """Create TOPMODEL parameter manager."""
+        from jtopmodel.calibration.parameter_manager import TopmodelParameterManager
+        return TopmodelParameterManager(
+            self.config,
+            self.logger,
+            self.topmodel_setup_dir
+        )
+
+    def _run_model_for_final_evaluation(self, output_dir: Path) -> bool:
+        """Run TOPMODEL for final evaluation using best parameters."""
+        best_result = self.get_best_result()
+        best_params = best_result.get('params')
+
+        if not best_params:
+            self.logger.warning("No best parameters found for final evaluation")
+            return False
+
+        self.worker.apply_parameters(best_params, self.topmodel_setup_dir)
+
+        return self.worker.run_model(
+            self.config,
+            self.topmodel_setup_dir,
+            output_dir,
+            save_output=True
+        )
+
+    def run_final_evaluation(self, best_params: Dict[str, float]) -> Optional[Dict[str, Any]]:
+        """Run final evaluation with consistent warmup handling for TOPMODEL.
+
+        Calculates separate metrics for calibration and evaluation periods,
+        matching the in-memory warmup handling used during optimization.
+        """
+        self.logger.info("=" * 60)
+        self.logger.info("RUNNING FINAL EVALUATION")
+        self.logger.info("=" * 60)
+
+        try:
+            if not self.worker._initialized:
+                if not self.worker.initialize():
+                    self.logger.error("Failed to initialize TOPMODEL worker for final evaluation")
+                    return None
+
+            if not self.worker.apply_parameters(best_params, self.topmodel_setup_dir):
+                self.logger.error("Failed to apply best parameters for final evaluation")
+                return None
+
+            final_output_dir = self.results_dir / 'final_evaluation'
+            final_output_dir.mkdir(parents=True, exist_ok=True)
+
+            runoff = self.worker._run_simulation(
+                self.worker._forcing,
+                best_params
+            )
+
+            self.worker.save_output_files(
+                runoff[self.worker.warmup_days:],
+                final_output_dir,
+                self.worker._time_index[self.worker.warmup_days:] if self.worker._time_index is not None else None
+            )
+
+            # Get time index and observations
+            time_index = self.worker._time_index
+            observations = self.worker._observations
+
+            if time_index is None or observations is None:
+                self.logger.error("Missing time index or observations for metric calculation")
+                return None
+
+            # Parse calibration and evaluation periods
+            calib_period = self._parse_period_config('calibration_period', 'CALIBRATION_PERIOD')
+            eval_period = self._parse_period_config('evaluation_period', 'EVALUATION_PERIOD')
+
+            # Calculate metrics for calibration period (with warmup skip)
+            calib_metrics = self._calculate_period_metrics_inmemory(
+                runoff, observations, time_index,
+                calib_period, 'Calib',
+                skip_warmup=True
+            )
+
+            # Calculate metrics for evaluation period (no warmup skip needed)
+            eval_metrics = {}
+            if eval_period[0] and eval_period[1]:
+                eval_metrics = self._calculate_period_metrics_inmemory(
+                    runoff, observations, time_index,
+                    eval_period, 'Eval',
+                    skip_warmup=False
+                )
+
+            # Combine all metrics
+            all_metrics = {**calib_metrics, **eval_metrics}
+
+            # Add unprefixed versions for backward compatibility
+            for k, v in calib_metrics.items():
+                unprefixed = k.replace('Calib_', '')
+                if unprefixed not in all_metrics:
+                    all_metrics[unprefixed] = v
+
+            # Log results
+            self._log_final_evaluation_results(
+                {k: v for k, v in calib_metrics.items()},
+                {k: v for k, v in eval_metrics.items()}
+            )
+
+            return {
+                'final_metrics': all_metrics,
+                'calibration_metrics': calib_metrics,
+                'evaluation_metrics': eval_metrics,
+                'success': True,
+                'best_params': best_params,
+                'output_dir': str(final_output_dir),
+            }
+
+        except Exception as e:  # noqa: BLE001 — calibration resilience
+            self.logger.error(f"Final evaluation failed: {e}")
+            import traceback
+            self.logger.debug(traceback.format_exc())
+            return None
+
+    def _parse_period_config(self, attr_name: str, dict_key: str):
+        """Parse a period configuration string into start/end timestamps."""
+        period_str = self._get_config_value(
+            lambda: getattr(self.config.domain, attr_name, ''),
+            default='',
+            dict_key=dict_key
+        )
+        if not period_str:
+            return (None, None)
+
+        try:
+            dates = [d.strip() for d in period_str.split(',')]
+            if len(dates) >= 2:
+                return (pd.Timestamp(dates[0]), pd.Timestamp(dates[1]))
+        except (ValueError, AttributeError) as e:
+            self.logger.debug(f"Could not parse period string '{period_str}': {e}")
+        return (None, None)
+
+    def _calculate_period_metrics_inmemory(
+        self,
+        runoff: np.ndarray,
+        observations: np.ndarray,
+        time_index: pd.DatetimeIndex,
+        period: tuple,
+        prefix: str,
+        skip_warmup: bool = True
+    ) -> Dict[str, float]:
+        """Calculate metrics for a specific period using in-memory data.
+
+        Warmup is skipped from the full simulation start before filtering
+        to the target period, matching the calibration behavior.
+        """
+        try:
+            if skip_warmup and len(runoff) > self.worker.warmup_days:
+                runoff = runoff[self.worker.warmup_days:]
+                observations = observations[self.worker.warmup_days:]
+                time_index = time_index[self.worker.warmup_days:]
+
+            sim_series = pd.Series(runoff, index=time_index)
+            obs_series = pd.Series(observations, index=time_index)
+
+            if period[0] and period[1]:
+                period_mask = (time_index >= period[0]) & (time_index <= period[1])
+                sim_period = sim_series[period_mask]
+                obs_period = obs_series[period_mask]
+                self.logger.info(
+                    f"{prefix} period: {period[0].date()} to {period[1].date()}, "
+                    f"{len(sim_period)} points"
+                )
+            else:
+                sim_period = sim_series
+                obs_period = obs_series
+
+            common_idx = sim_period.index.intersection(obs_period.index)
+            if len(common_idx) == 0:
+                self.logger.warning(f"No common indices for {prefix} period")
+                return {}
+
+            sim_aligned = sim_period.loc[common_idx].values
+            obs_aligned = obs_period.loc[common_idx].values
+
+            valid_mask = ~(np.isnan(sim_aligned) | np.isnan(obs_aligned))
+            sim_valid = sim_aligned[valid_mask]
+            obs_valid = obs_aligned[valid_mask]
+
+            if len(sim_valid) < 10:
+                self.logger.warning(f"Insufficient valid points for {prefix} metrics: {len(sim_valid)}")
+                return {}
+
+            metrics_result = calculate_all_metrics(
+                pd.Series(obs_valid),
+                pd.Series(sim_valid)
+            )
+
+            prefixed_metrics = {}
+            for key, value in metrics_result.items():
+                prefixed_metrics[f"{prefix}_{key}"] = value
+
+            return prefixed_metrics
+
+        except Exception as e:  # noqa: BLE001 — calibration resilience
+            self.logger.error(f"Error calculating {prefix} metrics: {e}")
+            import traceback
+            self.logger.debug(traceback.format_exc())
+            return {}

jtopmodel/calibration/parameter_manager.py

@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2024-2026 SYMFLUENCE Team <dev@symfluence.org>
+
+"""
+TOPMODEL Parameter Manager.
+
+Provides parameter bounds, transformations, and management for TOPMODEL calibration.
+"""
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+from jtopmodel.parameters import DEFAULT_PARAMS, PARAM_BOUNDS
+from symfluence.optimization.core.base_parameter_manager import BaseParameterManager
+
+
+class TopmodelParameterManager(BaseParameterManager):
+    """
+    Manages TOPMODEL parameters for calibration.
+
+    Provides:
+    - Parameter bounds retrieval
+    - Transformation between normalized [0,1] and physical space
+    - Default values
+    - Parameter validation
+    """
+
+    def __init__(self, config: Dict, logger: logging.Logger, topmodel_settings_dir: Path):
+        """
+        Initialize parameter manager.
+
+        Args:
+            config: Configuration dictionary
+            logger: Logger instance
+            topmodel_settings_dir: Path to TOPMODEL settings directory
+        """
+        super().__init__(config, logger, topmodel_settings_dir)
+
+        self.domain_name = self._get_config_value(lambda: self.config.domain.name, default=None, dict_key='DOMAIN_NAME')
+        self.experiment_id = self._get_config_value(lambda: self.config.domain.experiment_id, default=None, dict_key='EXPERIMENT_ID')
+
+        # Parse TOPMODEL parameters to calibrate from config
+        topmodel_params_str = self._get_config_value(lambda: self.config.model.topmodel.params_to_calibrate, default=None, dict_key='TOPMODEL_PARAMS_TO_CALIBRATE') or self._get_config_value(lambda: None, default=None, dict_key='PARAMS_TO_CALIBRATE')
+
+        # Handle None, empty string, or 'default' as signal to use ALL available parameters
+        if topmodel_params_str is None or topmodel_params_str == '' or topmodel_params_str == 'default':
+            self.topmodel_params = list(PARAM_BOUNDS.keys())
+            logger.debug(f"Using all available TOPMODEL parameters for calibration: {self.topmodel_params}")
+        else:
+            self.topmodel_params = [p.strip() for p in str(topmodel_params_str).split(',') if p.strip()]
+            logger.debug(f"Using user-specified TOPMODEL parameters: {self.topmodel_params}")
+
+        # Store internal references
+        self.all_bounds = PARAM_BOUNDS.copy()
+        self.defaults = DEFAULT_PARAMS.copy()
+        self.calibration_params = self.topmodel_params
+
+    # ========================================================================
+    # IMPLEMENT ABSTRACT METHODS
+    # ========================================================================
+
+    def _get_parameter_names(self) -> List[str]:
+        """Return TOPMODEL parameter names from config."""
+        return self.topmodel_params
+
+    def _load_parameter_bounds(self) -> Dict[str, Dict[str, float]]:
+        """Return TOPMODEL parameter bounds from central registry."""
+        from symfluence.optimization.core.parameter_bounds_registry import get_topmodel_bounds
+        return get_topmodel_bounds()
+
+    def update_model_files(self, params: Dict[str, float]) -> bool:
+        """TOPMODEL runs in-memory; parameters passed directly to model."""
+        return True
+
+    def get_initial_parameters(self) -> Optional[Dict[str, float]]:
+        """Get initial parameter values from config or defaults."""
+        initial_params = self._get_config_value(lambda: None, default='default', dict_key='TOPMODEL_INITIAL_PARAMS')
+
+        if initial_params == 'default':
+            self.logger.debug("Using standard TOPMODEL defaults for initial parameters")
+            return {p: self.defaults[p] for p in self.topmodel_params}
+
+        if isinstance(initial_params, str) and initial_params != 'default':
+            try:
+                param_dict = {}
+                for pair in initial_params.split(','):
+                    if '=' in pair:
+                        k, v = pair.split('=')
+                        param_dict[k.strip()] = float(v.strip())
+                return param_dict
+            except Exception as e:  # noqa: BLE001 — calibration resilience
+                self.logger.warning(f"Could not parse TOPMODEL_INITIAL_PARAMS: {e}")
+                return {p: self.defaults[p] for p in self.topmodel_params}
+
+        return {p: self.defaults[p] for p in self.topmodel_params}
+
+    def get_bounds(self, param_name: str) -> Tuple[float, float]:
+        """Get bounds for a single parameter."""
+        if param_name not in self.all_bounds:
+            raise KeyError(f"Unknown TOPMODEL parameter: {param_name}")
+        return self.all_bounds[param_name]
+
+    def get_calibration_bounds(self) -> Dict[str, Dict[str, float]]:
+        """Get bounds for all calibration parameters."""
+        return {
+            name: {'min': self.all_bounds[name][0], 'max': self.all_bounds[name][1]}
+            for name in self.calibration_params
+        }
+
+    def get_bounds_array(self) -> Tuple[np.ndarray, np.ndarray]:
+        """Get bounds as arrays for optimization algorithms."""
+        lower = np.array([self.all_bounds[p][0] for p in self.calibration_params])
+        upper = np.array([self.all_bounds[p][1] for p in self.calibration_params])
+        return lower, upper
+
+    def get_default(self, param_name: str) -> float:
+        """Get default value for a parameter."""
+        return self.defaults.get(param_name, 0.0)
+
+    def get_default_vector(self) -> np.ndarray:
+        """Get default values as array for calibration parameters."""
+        return np.array([self.defaults[p] for p in self.calibration_params])
+
+    def normalize(self, params: Dict[str, float]) -> np.ndarray:
+        """Normalize parameters to [0, 1] range."""
+        normalized = []
+        for name in self.calibration_params:
+            value = params.get(name, self.defaults[name])
+            low, high = self.all_bounds[name]
+            norm_val = (value - low) / (high - low + 1e-10)
+            normalized.append(np.clip(norm_val, 0, 1))
+        return np.array(normalized)
+
+    def denormalize(self, values: np.ndarray) -> Dict[str, float]:
+        """Convert normalized [0, 1] values to physical parameter values."""
+        params = {}
+        for i, name in enumerate(self.calibration_params):
+            low, high = self.all_bounds[name]
+            params[name] = low + values[i] * (high - low)
+        return params
+
+    def array_to_dict(self, values: np.ndarray) -> Dict[str, float]:
+        """Convert parameter array to dictionary."""
+        return dict(zip(self.calibration_params, values))
+
+    def dict_to_array(self, params: Dict[str, float]) -> np.ndarray:
+        """Convert parameter dictionary to array."""
+        return np.array([params.get(p, self.defaults[p]) for p in self.calibration_params])
+
+    def validate(self, params: Dict[str, float]) -> Tuple[bool, List[str]]:
+        """Validate parameter values are within bounds."""
+        violations = []
+        for name, value in params.items():
+            if name in self.all_bounds:
+                low, high = self.all_bounds[name]
+                if value < low:
+                    violations.append(f"{name}={value} < min={low}")
+                elif value > high:
+                    violations.append(f"{name}={value} > max={high}")
+
+        return len(violations) == 0, violations
+
+    def clip_to_bounds(self, params: Dict[str, float]) -> Dict[str, float]:
+        """Clip parameter values to their bounds."""
+        clipped = {}
+        for name, value in params.items():
+            if name in self.all_bounds:
+                low, high = self.all_bounds[name]
+                clipped[name] = np.clip(value, low, high)
+            else:
+                clipped[name] = value
+        return clipped
+
+    def get_complete_params(self, partial_params: Dict[str, float]) -> Dict[str, float]:
+        """Complete partial parameter dict with defaults."""
+        complete = self.defaults.copy()
+        complete.update(partial_params)
+        return complete
+
+
+def get_topmodel_calibration_bounds(
+    params_to_calibrate: Optional[List[str]] = None
+) -> Dict[str, Dict[str, float]]:
+    """
+    Convenience function to get TOPMODEL calibration bounds.
+
+    Args:
+        params_to_calibrate: List of parameters. If None, uses all.
+
+    Returns:
+        Dict mapping param_name -> {'min': float, 'max': float}
+    """
+    if params_to_calibrate is None:
+        params_to_calibrate = list(PARAM_BOUNDS.keys())
+
+    return {
+        name: {'min': PARAM_BOUNDS[name][0], 'max': PARAM_BOUNDS[name][1]}
+        for name in params_to_calibrate if name in PARAM_BOUNDS
+    }