Source code for GUIBRUSHR.Retrieval.ModelCalculation.Classes.Bestpars

"""
Best parameters class for atmospheric retrieval calculations.

This module contains the Bestpars class which manages the best-fit parameters
for atmospheric retrieval using Differential Evolution algorithms.
"""

from numpy import sqrt




class Bestpars:
    """
    Manages best-fit parameters for atmospheric retrieval calculations.
    
    This class handles the storage and configuration of best-fit parameters
    used in atmospheric retrieval algorithms, particularly for Differential
    Evolution Retrieval methods.
    
    Attributes:
        list_bestpars: List of best-fit parameter values
        list_bestpars_initial_value: List of initial parameter values
        nfit: Number of fitted parameters
        nchains: Number of chains for the retrieval algorithm
        ncores: Number of cores for the retrieval algorithm
        gamma_coeff: Gamma coefficient for Differential Evolution
        multiplier_chains: Multiplier for the number of chains
        multiplier_cores: Multiplier for the number of cores
        use_pool: Flag indicating whether to use multiprocessing pool
        use_parallel_init: Flag indicating whether to use parallel initialization
    """
    


    def __init__(
        self, list_bestpars, list_bestpars_initial_value, multiplier_chains=2, multiplier_cores=1,
        use_pool=False, use_parallel_init=False, mode_jump_threshold=0.05
    ):
        """
        Initialize the Bestpars object.

        Args:
            list_bestpars: List containing the best-fit parameter values
            list_bestpars_initial_value: List containing initial parameter values
            multiplier_chains: Multiplier for the number of chains
            multiplier_cores: Multiplier for the number of cores
            use_pool: Flag indicating whether to use multiprocessing pool
            use_parallel_init: Flag indicating whether to use parallel initialization
            mode_jump_threshold: Probability of using gamma=1 mode-jumping (ter Braak 2006).
                Default 0.05 (5%). Set lower for high-dimensional problems.
        """
        # Store the parameter lists
        self.list_bestpars = list_bestpars
        self.list_bestpars_initial_value = list_bestpars_initial_value
        self.multiplier_chains = multiplier_chains
        self.multiplier_cores = multiplier_cores
        self.use_pool = use_pool
        self.use_parallel_init = use_parallel_init
        
        # Calculate number of fitted parameters
        self.nfit = len(list_bestpars)
        
        # Set number of chains (standard: 2 times the number of parameters)
        self.nchains = int(self.multiplier_chains * self.nfit)
        self.ncores = int(self.nchains / self.multiplier_cores)
        
        # Calculate gamma coefficient for Differential Evolution Retrieval
        # Standard formula: 2.38 / sqrt(2 * number_of_parameters)
        self.gamma_coeff = 2.38 / sqrt(2 * self.nfit)

        # Probability of gamma=1 mode-jumping (ter Braak 2006 §2.3)
        self.mode_jump_threshold = mode_jump_threshold

        # Optional Hessian-based chain-init artifacts populated by
        # map_optimizer.compute_hessian_at_map() when the user selects
        # init_mode == "diagonal" or "correlated". When None, the chain init
        # in exofast_demc.py:724-729 falls back to the legacy isotropic path
        # (``MAP + init_scatter_factor * scale * N(0, I)``).
        self.init_scale_per_param = None  # numpy 1-D array, len = nfit
        self.init_cholesky = None         # numpy 2-D Cholesky factor of cov