alchemist-nrel 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

alchemist_core/acquisition/botorch_acquisition.py

@@ -268,6 +268,7 @@ class BoTorchAcquisition(BaseAcquisition):
                     "batch_limit": batch_limit,
                     "maxiter": max_iter,
                     "ftol": 1e-3,  # More relaxed convergence criteria
+                    "factr": None, # Required when ftol is specified
                 }
             else:
                 # Standard parameters for other acquisition functions

alchemist_core/data/experiment_manager.py

@@ -45,16 +45,23 @@ class ExperimentManager:
         
         # Add iteration tracking
         if iteration is not None:
-            # Use provided iteration and ensure _current_iteration reflects it
+            # Use provided iteration explicitly
             new_point['Iteration'] = int(iteration)
-            # Keep _current_iteration in sync with the latest explicit iteration
-            try:
-                self._current_iteration = int(iteration)
-            except Exception:
-                pass
         else:
-            # Use current iteration (doesn't increment until lock_acquisition)
-            new_point['Iteration'] = int(self._current_iteration)
+            # Auto-calculate next iteration based on existing data
+            # This ensures proper iteration tracking across all clients
+            if len(self.df) > 0 and 'Iteration' in self.df.columns:
+                max_iteration = int(self.df['Iteration'].max())
+                new_point['Iteration'] = max_iteration + 1
+            else:
+                # First experiment defaults to iteration 0
+                new_point['Iteration'] = 0
+        
+        # Keep _current_iteration in sync with latest iteration for backward compatibility
+        try:
+            self._current_iteration = int(new_point['Iteration'])
+        except Exception:
+            pass
         
         # Add reason
         new_point['Reason'] = reason if reason is not None else 'Manual'

alchemist_core/models/sklearn_model.py

@@ -396,8 +396,12 @@ class SklearnModel(BaseModel):
         if return_std:
             pred_mean, pred_std = predictions
             
+            # Safety check: replace invalid/negative std with small positive value
+            # Sklearn GP can produce negative variances due to numerical issues
+            pred_std = np.maximum(pred_std, 1e-6)
+            
             # Apply calibration to standard deviation if enabled
-            if self.calibration_enabled:
+            if self.calibration_enabled and np.isfinite(self.calibration_factor):
                 pred_std = pred_std * self.calibration_factor
             
             # Inverse transform the mean predictions
@@ -636,11 +640,35 @@ class SklearnModel(BaseModel):
         y_pred = self.cv_cached_results['y_pred']
         y_std = self.cv_cached_results['y_std']
         
+        # Check for numerical issues (zero/negative variances)
+        if np.any(y_std <= 0) or np.any(~np.isfinite(y_std)):
+            logger.warning("Sklearn GP produced invalid uncertainties (zero/negative/inf). Disabling calibration.")
+            self.calibration_enabled = False
+            self.calibration_factor = 1.0
+            return
+        
         # Compute standardized residuals (z-scores)
-        z_scores = (y_true - y_pred) / y_std
+        # Add small epsilon to avoid division by zero
+        epsilon = 1e-10
+        z_scores = (y_true - y_pred) / (y_std + epsilon)
+        
+        # Check for numerical validity
+        if not np.all(np.isfinite(z_scores)):
+            logger.warning("Z-scores contain NaN/inf. Disabling calibration.")
+            self.calibration_enabled = False
+            self.calibration_factor = 1.0
+            return
         
         # Calibration factor = std(z)
         self.calibration_factor = np.std(z_scores, ddof=1)
+        
+        # Final check for valid calibration factor
+        if not np.isfinite(self.calibration_factor) or self.calibration_factor <= 0:
+            logger.warning(f"Invalid calibration factor: {self.calibration_factor}. Disabling calibration.")
+            self.calibration_enabled = False
+            self.calibration_factor = 1.0
+            return
+        
         self.calibration_enabled = True
         
         # Create calibrated copy of CV results for plotting

alchemist_core/session.py

@@ -31,23 +31,23 @@ class OptimizationSession:
     5. Iterate
     
     Example:
-        >>> from alchemist_core import OptimizationSession
-        >>> 
-        >>> # Create session with search space
-        >>> session = OptimizationSession()
-        >>> session.add_variable('temperature', 'real', bounds=(300, 500))
-        >>> session.add_variable('pressure', 'real', bounds=(1, 10))
-        >>> session.add_variable('catalyst', 'categorical', categories=['A', 'B', 'C'])
-        >>> 
-        >>> # Load experimental data
-        >>> session.load_data('experiments.csv', target_column='yield')
-        >>> 
-        >>> # Train model
-        >>> session.train_model(backend='botorch', kernel='Matern')
-        >>> 
-        >>> # Suggest next experiment
-        >>> next_point = session.suggest_next(strategy='EI', goal='maximize')
-        >>> print(next_point)
+        > from alchemist_core import OptimizationSession
+        > 
+        > # Create session with search space
+        > session = OptimizationSession()
+        > session.add_variable('temperature', 'real', bounds=(300, 500))
+        > session.add_variable('pressure', 'real', bounds=(1, 10))
+        > session.add_variable('catalyst', 'categorical', categories=['A', 'B', 'C'])
+        > 
+        > # Load experimental data
+        > session.load_data('experiments.csv', target_column='yield')
+        > 
+        > # Train model
+        > session.train_model(backend='botorch', kernel='Matern')
+        > 
+        > # Suggest next experiment
+        > next_point = session.suggest_next(strategy='EI', goal='maximize')
+        > print(next_point)
     """
     
     def __init__(self, search_space: Optional[SearchSpace] = None, 
@@ -79,10 +79,16 @@ class OptimizationSession:
         self.model_backend = None
         self.acquisition = None
         
+        # Staged experiments (for workflow management)
+        self.staged_experiments = []  # List of experiment dicts awaiting evaluation
+        self.last_suggestions = []  # Most recent acquisition suggestions (for UI)
+        
         # Configuration
         self.config = {
             'random_state': 42,
-            'verbose': True
+            'verbose': True,
+            'auto_train': False,  # Auto-train model after adding experiments
+            'auto_train_threshold': 5  # Minimum experiments before auto-train
         }
         
         logger.info(f"OptimizationSession initialized: {self.metadata.session_id}")
@@ -103,8 +109,8 @@ class OptimizationSession:
                 - For 'categorical': categories=[list of values] or values=[list]
         
         Example:
-            >>> session.add_variable('temp', 'real', bounds=(300, 500))
-            >>> session.add_variable('catalyst', 'categorical', categories=['A', 'B'])
+            > session.add_variable('temp', 'real', bounds=(300, 500))
+            > session.add_variable('catalyst', 'categorical', categories=['A', 'B'])
         """
         # Convert user-friendly API to internal format
         params = kwargs.copy()
@@ -196,7 +202,7 @@ class OptimizationSession:
             noise_column: Optional column with measurement noise/uncertainty
         
         Example:
-            >>> session.load_data('experiments.csv', target_column='yield')
+            > session.load_data('experiments.csv', target_column='yield')
         """
         # Load the CSV
         import pandas as pd
@@ -245,7 +251,7 @@ class OptimizationSession:
             reason: Reason for this experiment (e.g., 'Manual', 'Expected Improvement')
         
         Example:
-            >>> session.add_experiment(
+            > session.add_experiment(
             ...     inputs={'temperature': 350, 'catalyst': 'A'},
             ...     output=0.85,
             ...     reason='Manual'
@@ -288,6 +294,124 @@ class OptimizationSession:
             'feature_names': list(X.columns)
         }
     
+    # ============================================================
+    # Staged Experiments (Workflow Management)
+    # ============================================================
+    
+    def add_staged_experiment(self, inputs: Dict[str, Any]) -> None:
+        """
+        Add an experiment to the staging area (awaiting evaluation).
+        
+        Staged experiments are typically suggested by acquisition functions
+        but not yet evaluated. They can be retrieved, evaluated externally,
+        and then added to the dataset with add_experiment().
+        
+        Args:
+            inputs: Dictionary mapping variable names to values
+            
+        Example:
+            > # Generate suggestions and stage them
+            > suggestions = session.suggest_next(n_suggestions=3)
+            > for point in suggestions.to_dict('records'):
+            >     session.add_staged_experiment(point)
+            > 
+            > # Later, evaluate and add
+            > staged = session.get_staged_experiments()
+            > for point in staged:
+            >     output = run_experiment(**point)
+            >     session.add_experiment(point, output=output)
+            > session.clear_staged_experiments()
+        """
+        self.staged_experiments.append(inputs)
+        logger.debug(f"Staged experiment: {inputs}")
+        self.events.emit('experiment_staged', {'inputs': inputs})
+    
+    def get_staged_experiments(self) -> List[Dict[str, Any]]:
+        """
+        Get all staged experiments awaiting evaluation.
+        
+        Returns:
+            List of experiment input dictionaries
+        """
+        return self.staged_experiments.copy()
+    
+    def clear_staged_experiments(self) -> int:
+        """
+        Clear all staged experiments.
+        
+        Returns:
+            Number of experiments cleared
+        """
+        count = len(self.staged_experiments)
+        self.staged_experiments.clear()
+        if count > 0:
+            logger.info(f"Cleared {count} staged experiments")
+            self.events.emit('staged_experiments_cleared', {'count': count})
+        return count
+    
+    def move_staged_to_experiments(self, outputs: List[float], 
+                                   noises: Optional[List[float]] = None,
+                                   iteration: Optional[int] = None,
+                                   reason: Optional[str] = None) -> int:
+        """
+        Evaluate staged experiments and add them to the dataset in batch.
+        
+        Convenience method that pairs staged inputs with outputs and adds
+        them all to the experiment manager, then clears the staging area.
+        
+        Args:
+            outputs: List of output values (must match length of staged experiments)
+            noises: Optional list of measurement uncertainties
+            iteration: Iteration number for all experiments (auto-assigned if None)
+            reason: Reason for these experiments (e.g., 'Expected Improvement')
+            
+        Returns:
+            Number of experiments added
+            
+        Example:
+            > # Stage some experiments
+            > session.add_staged_experiment({'x': 1.0, 'y': 2.0})
+            > session.add_staged_experiment({'x': 3.0, 'y': 4.0})
+            > 
+            > # Evaluate them
+            > outputs = [run_experiment(**point) for point in session.get_staged_experiments()]
+            > 
+            > # Add to dataset and clear staging
+            > session.move_staged_to_experiments(outputs, reason='LogEI')
+        """
+        if len(outputs) != len(self.staged_experiments):
+            raise ValueError(
+                f"Number of outputs ({len(outputs)}) must match "
+                f"number of staged experiments ({len(self.staged_experiments)})"
+            )
+        
+        if noises is not None and len(noises) != len(self.staged_experiments):
+            raise ValueError(
+                f"Number of noise values ({len(noises)}) must match "
+                f"number of staged experiments ({len(self.staged_experiments)})"
+            )
+        
+        # Add each experiment
+        for i, inputs in enumerate(self.staged_experiments):
+            noise = noises[i] if noises is not None else None
+            self.add_experiment(
+                inputs=inputs,
+                output=outputs[i],
+                noise=noise,
+                iteration=iteration,
+                reason=reason
+            )
+        
+        count = len(self.staged_experiments)
+        self.clear_staged_experiments()
+        
+        logger.info(f"Moved {count} staged experiments to dataset")
+        return count
+    
+    # ============================================================
+    # Initial Design Generation
+    # ============================================================
+    
     def generate_initial_design(
         self,
         method: str = "lhs",
@@ -320,16 +444,16 @@ class OptimizationSession:
             List of dictionaries with variable names and values (no outputs)
         
         Example:
-            >>> # Generate initial design
-            >>> points = session.generate_initial_design('lhs', n_points=10)
-            >>> 
-            >>> # Run experiments and add results
-            >>> for point in points:
-            >>>     output = run_experiment(**point)  # Your experiment function
-            >>>     session.add_experiment(point, output=output)
-            >>> 
-            >>> # Now ready to train model
-            >>> session.train_model()
+            > # Generate initial design
+            > points = session.generate_initial_design('lhs', n_points=10)
+            > 
+            > # Run experiments and add results
+            > for point in points:
+            >     output = run_experiment(**point)  # Your experiment function
+            >     session.add_experiment(point, output=output)
+            > 
+            > # Now ready to train model
+            > session.train_model()
         """
         if len(self.search_space.variables) == 0:
             raise ValueError(
@@ -389,8 +513,8 @@ class OptimizationSession:
             Dictionary with training results and hyperparameters
         
         Example:
-            >>> results = session.train_model(backend='botorch', kernel='Matern')
-            >>> print(results['metrics'])
+            > results = session.train_model(backend='botorch', kernel='Matern')
+            > print(results['metrics'])
         """
         df = self.experiment_manager.get_data()
         if df is None or df.empty:
@@ -410,6 +534,27 @@ class OptimizationSession:
         # Extract calibration_enabled before passing kwargs to model constructor
         calibration_enabled = kwargs.pop('calibration_enabled', False)
         
+        # Validate and map transform types based on backend
+        # BoTorch uses: 'normalize', 'standardize'
+        # Sklearn uses: 'minmax', 'standard', 'robust', 'none'
+        if self.model_backend == 'sklearn':
+            # Map BoTorch transform types to sklearn equivalents
+            transform_map = {
+                'normalize': 'minmax',      # BoTorch normalize → sklearn minmax
+                'standardize': 'standard',  # BoTorch standardize → sklearn standard
+                'none': 'none'
+            }
+            if 'input_transform_type' in kwargs:
+                original = kwargs['input_transform_type']
+                kwargs['input_transform_type'] = transform_map.get(original, original)
+                if original != kwargs['input_transform_type']:
+                    logger.debug(f"Mapped input transform '{original}' → '{kwargs['input_transform_type']}' for sklearn")
+            if 'output_transform_type' in kwargs:
+                original = kwargs['output_transform_type']
+                kwargs['output_transform_type'] = transform_map.get(original, original)
+                if original != kwargs['output_transform_type']:
+                    logger.debug(f"Mapped output transform '{original}' → '{kwargs['output_transform_type']}' for sklearn")
+        
         # Import appropriate model class
         if self.model_backend == 'sklearn':
             from alchemist_core.models.sklearn_model import SklearnModel
@@ -428,6 +573,15 @@ class OptimizationSession:
         elif self.model_backend == 'botorch':
             from alchemist_core.models.botorch_model import BoTorchModel
             
+            # Apply sensible defaults for BoTorch if not explicitly overridden
+            # Input normalization and output standardization are critical for performance
+            if 'input_transform_type' not in kwargs:
+                kwargs['input_transform_type'] = 'normalize'
+                logger.debug("Auto-applying input normalization for BoTorch model")
+            if 'output_transform_type' not in kwargs:
+                kwargs['output_transform_type'] = 'standardize'
+                logger.debug("Auto-applying output standardization for BoTorch model")
+            
             # Build kernel options - BoTorch uses 'cont_kernel_type' not 'kernel_type'
             kernel_options = {'cont_kernel_type': kernel}
             if kernel_params:
@@ -598,8 +752,8 @@ class OptimizationSession:
             DataFrame with suggested experiment(s)
         
         Example:
-            >>> next_point = session.suggest_next(strategy='EI', goal='maximize')
-            >>> print(next_point)
+            > next_point = session.suggest_next(strategy='EI', goal='maximize')
+            > print(next_point)
         """
         if self.model is None:
             raise ValueError("No trained model available. Use train_model() first.")
@@ -663,6 +817,9 @@ class OptimizationSession:
         logger.info(f"Suggested point: {suggestion_dict}")
         self.events.emit('acquisition_completed', {'suggestion': suggestion_dict})
         
+        # Store suggestions for UI/API access
+        self.last_suggestions = result_df.to_dict('records')
+        
         # Cache suggestion info for audit log
         self._last_acquisition_info = {
             'strategy': strategy,
@@ -685,11 +842,11 @@ class OptimizationSession:
             Tuple of (predictions, uncertainties)
         
         Example:
-            >>> test_points = pd.DataFrame({
+            > test_points = pd.DataFrame({
             ...     'temperature': [350, 400],
             ...     'catalyst': ['A', 'B']
             ... })
-            >>> predictions, uncertainties = session.predict(test_points)
+            > predictions, uncertainties = session.predict(test_points)
         """
         if self.model is None:
             raise ValueError("No trained model available. Use train_model() first.")
@@ -722,9 +879,9 @@ class OptimizationSession:
             callback: Callback function
         
         Example:
-            >>> def on_training_done(data):
+            > def on_training_done(data):
             ...     print(f"Training completed with R² = {data['metrics']['r2']}")
-            >>> session.on('training_completed', on_training_done)
+            > session.on('training_completed', on_training_done)
         """
         self.events.on(event, callback)
     
@@ -740,7 +897,7 @@ class OptimizationSession:
             **kwargs: Configuration parameters to update
         
         Example:
-            >>> session.set_config(random_state=123, verbose=False)
+            > session.set_config(random_state=123, verbose=False)
         """
         self.config.update(kwargs)
         logger.info(f"Updated config: {kwargs}")
@@ -764,8 +921,8 @@ class OptimizationSession:
             Created AuditEntry
             
         Example:
-            >>> session.add_experiment({'temp': 100, 'pressure': 5}, output=85.2)
-            >>> session.lock_data(notes="Initial screening dataset")
+            > session.add_experiment({'temp': 100, 'pressure': 5}, output=85.2)
+            > session.lock_data(notes="Initial screening dataset")
         """
         # Set search space in audit log (once)
         if self.audit_log.search_space_definition is None:
@@ -805,8 +962,8 @@ class OptimizationSession:
             ValueError: If no model has been trained
             
         Example:
-            >>> session.train_model(backend='sklearn', kernel='matern')
-            >>> session.lock_model(notes="Best cross-validation performance")
+            > session.train_model(backend='sklearn', kernel='matern')
+            > session.lock_model(notes="Best cross-validation performance")
         """
         if self.model is None:
             raise ValueError("No trained model available. Use train_model() first.")
@@ -898,8 +1055,8 @@ class OptimizationSession:
             Created AuditEntry
             
         Example:
-            >>> suggestions = session.suggest_next(strategy='EI', n_suggestions=3)
-            >>> session.lock_acquisition(
+            > suggestions = session.suggest_next(strategy='EI', n_suggestions=3)
+            > session.lock_acquisition(
             ...     strategy='EI',
             ...     parameters={'xi': 0.01, 'goal': 'maximize'},
             ...     suggestions=suggestions,
@@ -967,7 +1124,7 @@ class OptimizationSession:
             filepath: Path to save session file (.json extension recommended)
             
         Example:
-            >>> session.save_session("~/ALchemist_Sessions/catalyst_study_nov2025.json")
+            > session.save_session("~/ALchemist_Sessions/catalyst_study_nov2025.json")
         """
         filepath = Path(filepath)
         
@@ -1066,7 +1223,7 @@ class OptimizationSession:
             OptimizationSession with restored state
             
         Example:
-            >>> session = OptimizationSession.load_session("my_session.json")
+            > session = OptimizationSession.load_session("my_session.json")
         """
         filepath = Path(filepath)
         
@@ -1156,7 +1313,7 @@ class OptimizationSession:
             tags: New tags (optional)
             
         Example:
-            >>> session.update_metadata(
+            > session.update_metadata(
             ...     name="Catalyst Screening - Final",
             ...     description="Optimized Pt/Pd ratios",
             ...     tags=["catalyst", "platinum", "palladium", "final"]
@@ -1188,7 +1345,7 @@ class OptimizationSession:
             **kwargs: Configuration parameters to update
         
         Example:
-            >>> session.set_config(random_state=123, verbose=False)
+            > session.set_config(random_state=123, verbose=False)
         """
         self.config.update(kwargs)
         logger.info(f"Updated config: {kwargs}")