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

alchemist_core/utils/__init__.py

@@ -4,4 +4,6 @@ Utility functions for ALchemist Core.
 Will be populated in future branches.
 """
 
-__all__ = []
+from .acquisition_utils import evaluate_acquisition
+
+__all__ = ['evaluate_acquisition']

alchemist_core/utils/acquisition_utils.py

@@ -0,0 +1,60 @@
+"""
+Utility functions for acquisition function evaluation.
+
+These are internal helper functions used by visualization methods.
+Users should use the high-level plotting APIs in OptimizationSession instead.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union, Tuple, Optional, Dict, Any
+
+
+def evaluate_acquisition(
+    model,
+    X: Union[pd.DataFrame, np.ndarray],
+    acq_func: str = 'ucb',
+    acq_func_kwargs: Optional[Dict[str, Any]] = None,
+    goal: str = 'maximize'
+) -> Tuple[np.ndarray, Optional[np.ndarray]]:
+    """
+    Evaluate acquisition function at given points using the model's backend.
+    
+    This is an internal utility function used by visualization methods.
+    Users should call plot_acquisition_slice() or plot_acquisition_contour() instead.
+    
+    Args:
+        model: Trained model instance (SklearnModel or BoTorchModel)
+        X: Points to evaluate (DataFrame or array with shape (n, d))
+        acq_func: Acquisition function name:
+                 - 'ei': Expected Improvement
+                 - 'pi': Probability of Improvement
+                 - 'ucb/lcb': Upper/Lower Confidence Bound
+                 - 'logei', 'logpi': Log variants (BoTorch only)
+        acq_func_kwargs: Additional parameters:
+                       - 'xi' (float): Exploration parameter for EI/PI (default: 0.01)
+                       - 'kappa' (float): Exploration parameter for UCB (default: 1.96)
+                       - 'beta' (float): Exploration parameter for UCB (BoTorch, default: 0.5)
+        goal: 'maximize' or 'minimize' - optimization direction
+        
+    Returns:
+        Tuple of (acq_values, None) - None because acquisition functions are deterministic
+        
+    Example:
+        >>> from alchemist_core.utils.acquisition_utils import evaluate_acquisition
+        >>> acq_vals, _ = evaluate_acquisition(
+        ...     session.model, points, acq_func='ei', goal='maximize'
+        ... )
+    
+    Note:
+        - Requires trained model
+        - Acquisition values are relative - only their ordering matters
+        - Higher values indicate better candidates for next experiment
+    """
+    if model is None:
+        raise ValueError("Model must be trained before evaluating acquisition functions")
+    
+    maximize = (goal.lower() == 'maximize')
+    
+    # Delegate to model's evaluate_acquisition method
+    return model.evaluate_acquisition(X, acq_func, acq_func_kwargs, maximize)

alchemist_core/visualization/__init__.py

@@ -0,0 +1,45 @@
+"""
+Visualization module for ALchemist.
+
+Pure plotting functions with no session or UI dependencies.
+All functions return matplotlib Figure/Axes objects for maximum flexibility.
+"""
+
+from alchemist_core.visualization.plots import (
+    create_parity_plot,
+    create_contour_plot,
+    create_slice_plot,
+    create_voxel_plot,
+    create_metrics_plot,
+    create_qq_plot,
+    create_calibration_plot,
+    create_regret_plot,
+    create_probability_of_improvement_plot,
+    create_uncertainty_contour_plot,
+    create_uncertainty_voxel_plot,
+    create_acquisition_voxel_plot,
+)
+
+from alchemist_core.visualization.helpers import (
+    check_matplotlib,
+    compute_z_scores,
+    compute_calibration_metrics,
+)
+
+__all__ = [
+    'create_parity_plot',
+    'create_contour_plot',
+    'create_slice_plot',
+    'create_voxel_plot',
+    'create_metrics_plot',
+    'create_qq_plot',
+    'create_calibration_plot',
+    'create_regret_plot',
+    'create_probability_of_improvement_plot',
+    'create_uncertainty_contour_plot',
+    'create_uncertainty_voxel_plot',
+    'create_acquisition_voxel_plot',
+    'check_matplotlib',
+    'compute_z_scores',
+    'compute_calibration_metrics',
+]

alchemist_core/visualization/helpers.py

@@ -0,0 +1,130 @@
+"""
+Helper functions for visualization module.
+
+Utilities for data preparation, validation, and computation.
+"""
+
+import numpy as np
+from typing import Optional, Tuple
+
+
+def check_matplotlib() -> None:
+    """
+    Check if matplotlib is available for plotting.
+    
+    Raises:
+        ImportError: If matplotlib is not installed
+    """
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError:
+        raise ImportError(
+            "matplotlib is required for visualization. "
+            "Install with: pip install matplotlib"
+        )
+
+
+def compute_z_scores(
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+    y_std: np.ndarray
+) -> np.ndarray:
+    """
+    Compute standardized residuals (z-scores).
+    
+    z = (y_true - y_pred) / y_std
+    
+    Args:
+        y_true: Actual experimental values
+        y_pred: Model predicted values
+        y_std: Prediction standard deviations
+    
+    Returns:
+        Array of z-scores (standardized residuals)
+    
+    Note:
+        Small epsilon (1e-10) added to denominator to avoid division by zero.
+    """
+    return (y_true - y_pred) / (y_std + 1e-10)
+
+
+def compute_calibration_metrics(
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+    y_std: np.ndarray,
+    prob_levels: Optional[np.ndarray] = None
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Compute nominal vs empirical coverage for calibration curves.
+    
+    For each nominal probability level, computes the empirical fraction of
+    observations that fall within the predicted confidence interval.
+    
+    Args:
+        y_true: Actual experimental values
+        y_pred: Model predicted values
+        y_std: Prediction standard deviations
+        prob_levels: Nominal coverage probabilities to evaluate.
+                    Default: np.arange(0.10, 1.00, 0.05)
+    
+    Returns:
+        Tuple of (nominal_probs, empirical_coverage)
+        - nominal_probs: The requested probability levels
+        - empirical_coverage: Observed coverage fractions
+    
+    Example:
+        >>> nominal, empirical = compute_calibration_metrics(y_true, y_pred, y_std)
+        >>> # nominal[i] is the expected coverage (e.g., 0.68 for ±1σ)
+        >>> # empirical[i] is the observed coverage fraction
+    """
+    from scipy import stats
+    
+    if prob_levels is None:
+        prob_levels = np.arange(0.10, 1.00, 0.05)
+    
+    empirical_coverage = []
+    
+    for prob in prob_levels:
+        # Convert probability to sigma multiplier
+        # For symmetric interval: P(|Z| < z) = prob → z = Φ^(-1)((1+prob)/2)
+        sigma = stats.norm.ppf((1 + prob) / 2)
+        
+        # Compute empirical coverage at this sigma level
+        lower_bound = y_pred - sigma * y_std
+        upper_bound = y_pred + sigma * y_std
+        within_interval = (y_true >= lower_bound) & (y_true <= upper_bound)
+        empirical_coverage.append(np.mean(within_interval))
+    
+    return prob_levels, np.array(empirical_coverage)
+
+
+def sort_legend_items(labels: list) -> list:
+    """
+    Sort legend labels for consistent ordering.
+    
+    Preferred order: Prediction, uncertainty bands (small to large), Experiments
+    
+    Args:
+        labels: List of legend label strings
+    
+    Returns:
+        List of indices for sorted order
+    """
+    def sort_key(lbl):
+        if 'Prediction' in lbl:
+            return (0, 0)
+        elif 'σ' in lbl:
+            # Extract sigma value for sorting bands
+            import re
+            match = re.search(r'±([\d.]+)σ', lbl)
+            if match:
+                return (1, float(match.group(1)))
+            return (1, 999)
+        elif 'Experiment' in lbl:
+            return (2, 0)
+        else:
+            return (3, 0)
+    
+    indices = list(range(len(labels)))
+    indices.sort(key=lambda i: sort_key(labels[i]))
+    return indices