hdim-opt 1.0.0__py3-none-any.whl

hdim_opt/__init__.py

@@ -0,0 +1,11 @@
+# hdim_opt/__init__.py
+
+# package version
+__version__ = "1.0.0"
+
+# import core components
+from .quasar_optimization import optimize as quasar
+from .hyperellipsoid_sampling import sample as hds
+
+# list what is available for star-imports
+__all__ = ['quasar', 'hds']

hdim_opt/hyperellipsoid_sampling.py

@@ -0,0 +1,579 @@
+import numpy as np
+import pandas as pd
+from scipy import stats
+from joblib import Parallel, delayed
+from sklearn.neighbors import BallTree
+from sklearn.cluster import MiniBatchKMeans, AgglomerativeClustering
+from sklearn.random_projection import GaussianRandomProjection
+from sklearn.decomposition import PCA
+import scipy.cluster.hierarchy as shc
+import time
+import warnings
+
+# globals
+warnings.filterwarnings('ignore', category=UserWarning)
+epsilon = 1e-12
+
+### misc helper functions 
+
+def sample_hypersphere(n_dimensions, radius, n_samples_in_sphere, radius_qmc_sequence):
+    '''
+    Objective:
+        - Samples unit hyperspheres using Marsaglia polar vectors scaled by a QMC sequence.
+    '''
+    
+    # generate normal distribution (for angular direction)
+    samples = np.random.normal(size=(n_samples_in_sphere, n_dimensions))
+    
+    # normalize vectors to get points on the surface of a unit sphere (direction)
+    squared_norms = np.sum(samples**2, axis=1)
+    inv_norms = 1.0 / (np.sqrt(squared_norms) + epsilon)
+    
+    # efficiently apply directions (broadcasting faster than division)
+    samples = samples * inv_norms[:, np.newaxis]
+    
+    # use input QMC sequence for radius scaling (r^(1/n))
+    random_radii_qmc = np.power(radius_qmc_sequence, (1.0 / n_dimensions))
+    
+    # scale and apply final radius
+    samples = samples * (random_radii_qmc * radius)[:, np.newaxis]
+    
+    return samples
+
+def sample_hyperellipsoid(n_dimensions, n_samples_in_ellipsoid, origin, pca_components, pca_variances, scaling_factor, radius_qmc_sequence=None):
+    '''
+    Objective:
+        - Generates samples inside the hyperellipsoid.
+            - Calls the function to sample unit hyperspheres.
+            - Transforms the hyperspherical samples to the ellipsoid axes defined using the PCA variances.
+    '''
+    
+    # generate samples in unit hypersphere
+    unit_sphere_samples = sample_hypersphere(n_dimensions, 1.0, n_samples_in_ellipsoid, radius_qmc_sequence)
+    
+    # axis lengths: L = sqrt(variance + epsilon) * scaling_factor
+    axis_lengths = np.sqrt(pca_variances + epsilon) * scaling_factor
+    
+    # scale samples in PCA space and rotates back to original parameter space
+    scaled_and_rotated = (unit_sphere_samples * axis_lengths) @ pca_components
+    
+    # translate samples to cluster origin
+    ellipsoid_samples = scaled_and_rotated + origin
+    
+    return ellipsoid_samples
+
+def sample_in_voids(existing_samples, n_to_fill, bounds_min, bounds_max,
+                    k_neighbors=5, spread_factor=0.5,
+                    n_query_max=1000, n_tree_max=10000): 
+    '''
+    Objective:
+        - Identify & fill voids in the sample space, using the out-of-bounds sample set.
+        - Uses BallTree K-NearestNeighbors to identify voids.
+    '''
+    
+    # extract shape
+    n_existing, n_dimensions = existing_samples.shape
+
+    # if no samples to replace
+    if n_to_fill <= 0:
+        return np.zeros((0, n_dimensions))
+        
+    # if number of neighbors exceeds number of existing samples
+    if n_existing < k_neighbors + 1:
+        return stats.uniform.rvs(loc=bounds_min, scale=bounds_max - bounds_min, size=(n_to_fill, n_dimensions))
+
+    # for number of points > 100,000, reduce size to 10,000 for speed
+    if n_existing > n_tree_max:
+        tree_indices = np.random.choice(n_existing, size=n_tree_max, replace=False)
+        tree_samples = existing_samples[tree_indices]
+    else:
+        tree_indices = np.arange(n_existing)
+        tree_samples = existing_samples
+        
+    # recalculate n_existing for reduced set
+    n_existing_for_tree = tree_samples.shape[0]
+
+    # reduce dimensionality for speed
+    n_rp_components = min(max(10, int(2*np.log2(n_dimensions))), n_dimensions)
+    if n_rp_components < n_dimensions:
+        rp = GaussianRandomProjection(n_components=n_rp_components)
+        existing_samples_reduced = rp.fit_transform(tree_samples)
+    else:
+        existing_samples_reduced = tree_samples
+    
+    # build BallTree
+    start_kdtree_build = time.time()
+    tree = BallTree(existing_samples_reduced) 
+    
+    # BallTree query on subset
+    k_to_query = k_neighbors + 1 # k-th neighbor distance
+
+    # select random subset of centers to calculate void probability for (query set)
+    # query set sampled from the reduced set (existing_samples_reduced)
+    if n_existing_for_tree > n_query_max:
+        query_subset_indices = np.random.choice(n_existing_for_tree, size=n_query_max, replace=False)
+        existing_samples_query = existing_samples_reduced[query_subset_indices]
+    else:
+        query_subset_indices = np.arange(n_existing_for_tree)
+        existing_samples_query = existing_samples_reduced
+    
+    # query the subset against the reduced-sample tree
+    # returns distances first, then indices.
+    kth_nn_distances_subset, _ = tree.query(existing_samples_query, k=k_to_query,)
+    
+    # extract distance to the k-th nearest neighbor
+    kth_nn_distances_subset = kth_nn_distances_subset[:, k_neighbors]
+    
+    # identify void centers
+    probabilities = kth_nn_distances_subset / (kth_nn_distances_subset.sum() + epsilon)
+    void_center_query_indices = np.random.choice(
+        len(query_subset_indices),
+        size=n_to_fill,
+        p=probabilities,
+        replace=True
+        )
+    
+    # map back to indices in the tree_samples set
+    void_center_tree_indices = query_subset_indices[void_center_query_indices]
+
+    # map the indices back to the original full-sized existing_samples array
+    void_center_full_indices = tree_indices[void_center_tree_indices]
+
+    # extract centers and spreads from original, full-D data
+    chosen_centers = existing_samples[void_center_full_indices]
+    # kth_nn_distances_subset is still correct as it corresponds to the query points
+    chosen_kth_distances = kth_nn_distances_subset[void_center_query_indices] 
+    
+    # calculate spreads and generate samples (in full-D)
+    spreads = chosen_kth_distances[:, np.newaxis] * spread_factor + epsilon
+    a_params = (bounds_min - chosen_centers) / spreads
+    b_params = (bounds_max - chosen_centers) / spreads
+    new_samples = stats.truncnorm.rvs(a=a_params, b=b_params, loc=chosen_centers, scale=spreads)
+    
+    return new_samples
+
+def fit_pca_for_cluster(cluster_samples, current_origin, initial_samples_std, n_dimensions):
+    '''
+    Performs PCA on a single cluster's samples or returns a default, 
+    called in parallel.
+    '''
+    
+    # extract shape
+    n_cluster_samples = len(cluster_samples)
+    
+    if n_cluster_samples > n_dimensions * 2 and n_cluster_samples > 0:
+        pca = PCA(n_components=n_dimensions)
+        pca.fit(cluster_samples)
+        
+        return {'origin': current_origin, 
+                'components': pca.components_.T, 
+                'variances': pca.explained_variance_}
+    else:
+        # handle empty/too small clusters
+        fixed_variance = np.ones(n_dimensions) * initial_samples_std
+
+        return {'origin': current_origin, 
+                'components': np.eye(n_dimensions), 
+                'variances': fixed_variance}
+
+
+# main sample function
+
+def sample(n_samples, bounds,
+           weights=None, normalize=False,
+           n_ellipsoids=None, n_initial_clusters=None, n_initial_qmc=None,
+           seed=None, verbose=False):
+    '''
+    Objective:
+        - Generates a Hyperellipsoid Density sample sequence over the specified parameter range.
+    Inputs:
+        - n_samples: Number of samples to generate.
+        - bounds: Bounds of the parameter range.
+        - weights: Gaussian weights to influence clusters and final sample locations.
+        - normalize: Boolean to scale samples to the original parameter space, or leave normalized from [0,1].
+        - n_ellipsoids: Number of hyperellipsoids to sample.
+            - Replaces and skips the Agglomerative Hierarchical Clustering (AHC) step.
+        - n_initial_clusters: Number of initial clusters to use in calculating number of hyperellipsoids.
+            - Redunant if n_ellipsoids is specified.
+        - n_initial_qmc: Number of initial QMC samples to use for cluster analysis.
+        - seed: Random seed.
+        - verbose: Boolean to display stats and plots.
+    Outputs:
+        - hds_samples: Hyperellipsoid Density sample sequence.
+    '''
+
+    # initialize misc parameters:
+    start_time = time.time()
+    if seed is None:
+        seed = time.time()
+    seed = int(round(seed))
+    np.random.seed(seed)
+
+    # initialize sampling parameters:
+    n_samples = int(n_samples)
+    bounds = np.array(bounds)
+    n_dimensions = bounds.shape[0]
+
+    # n_initial_clusters scaling for D > 100
+    if n_initial_clusters is None:
+        if n_dimensions <= 500:
+            n_initial_clusters = 100 # 100 clusters for <= 500D
+        elif n_dimensions < 1000:
+            n_initial_clusters = 50 # 50 clusters sees same stddev as 100 for > 500D
+        else:
+            n_initial_clusters = 25 # 25 clusters sees same stddev as 100 for > 1000D
+    n_initial_clusters = int(n_initial_clusters)
+    
+    # number of qmc samples scaling
+    n_initial_qmc_max = 2**15
+    if n_initial_qmc is None:
+        min_qmc_dimensions = int(2**np.ceil(np.log2(n_dimensions*200)))
+        n_initial_qmc = min(min_qmc_dimensions, n_initial_qmc_max)
+    
+    # keep data normalized (0 to 1) for clustering
+    bounds_min_orig = bounds[:, 0]
+    bounds_max_orig = bounds[:, 1]
+    working_bounds_min = np.zeros(n_dimensions)
+    working_bounds_max = np.ones(n_dimensions)
+    
+    # generate initial QMC samples:
+    qmc_start_time = time.time()
+    initial_sobol_sampler = stats.qmc.Sobol(d=n_dimensions, seed=np.random.randint(0, 1000))
+    initial_samples_unit = initial_sobol_sampler.random(n=n_initial_qmc)
+    initial_samples = initial_samples_unit
+    
+    # calculate sample weights based on input
+    sample_weights = np.ones(initial_samples.shape[0])
+    if weights:
+        initial_samples_denorm = stats.qmc.scale(initial_samples, bounds_min_orig, bounds_max_orig)
+        for dim, info in weights.items():
+            center = info['center']
+            std = info['std']
+            if not std > 0:
+                raise ValueError(f'Gaussian weight stddevs must be > 0.')
+                return None
+            dim_values = initial_samples_denorm[:, dim]
+            gaussian_weights = stats.norm.pdf(dim_values, loc=center, scale=std)
+            
+            gaussian_weights += epsilon
+            sample_weights *= gaussian_weights
+
+    if verbose and n_ellipsoids is None:
+        print('Calculating ellipsoid density.')
+        
+    # determine number of ellipsoids via agglomerative clustering
+    # KMeans to get stable sub-cluster centers
+    kmeans_initial = MiniBatchKMeans(n_clusters=n_initial_clusters, random_state=seed, n_init=6)
+    kmeans_initial.fit(initial_samples, sample_weight=sample_weights)
+    initial_centroids = kmeans_initial.cluster_centers_
+    
+    # skip agglomerative clustering if number of initial clusters is provided
+    linkage_matrix = None
+    optimal_distance = None
+    if n_ellipsoids is not None and n_ellipsoids >= 1:
+        n_hyperellipsoids = n_ellipsoids
+    else:
+        # hierarchical clustering on the centroids to find natural grouping
+        linkage_matrix = shc.linkage(initial_centroids, method='ward')
+        
+        # find optimal cut-off distance (d) based on largest jump
+        distances = linkage_matrix[:, 2]
+        optimal_distance = 0
+        if len(distances) > 2:
+            diffs = distances[1:] - distances[:-1]
+            max_diff_index = np.argmax(diffs)
+            optimal_distance = distances[max_diff_index + 1] 
+            
+            # in case initial sample clusters are uniform
+            if optimal_distance < 0.1: 
+                optimal_distance = 0.5 
+                
+            # agglomerative clustering to determine k at the optimal distance
+            agg_model = AgglomerativeClustering(n_clusters=None, distance_threshold=optimal_distance, linkage='ward')
+            agg_model.fit(initial_centroids)
+            n_hyperellipsoids = agg_model.n_clusters_
+            
+        else:
+            n_hyperellipsoids = 1
+    n_hyperellipsoids = max(1, n_hyperellipsoids)
+    
+    # K-Means again with optimal n_hyperellipsoids to find final centers
+    kmeans = MiniBatchKMeans(n_clusters=n_hyperellipsoids, random_state=seed, n_init=6)
+    kmeans.fit(initial_samples, sample_weight=sample_weights)
+    origins = kmeans.cluster_centers_
+    cluster_labels = kmeans.labels_
+    
+    # pre-calculate sample stddev
+    initial_samples_std = np.std(initial_samples)
+    
+    # prepare inputs for the parallel loop
+    cluster_data_inputs = []
+    for i in range(n_hyperellipsoids):
+        cluster_samples = initial_samples[cluster_labels == i]
+        current_origin = origins[i]
+        
+        # recenter origin if the cluster is empty
+        if len(cluster_samples) == 0:
+            current_origin = initial_samples[np.random.randint(len(initial_samples))]
+        
+        cluster_data_inputs.append((cluster_samples, current_origin, initial_samples_std, n_dimensions))
+
+    # calculate hyperellipsoid shapes via PCA (parallelized)
+    if verbose:
+        print(f'Orienting axes.')
+    ellipsoid_params = Parallel(n_jobs=-1)(
+        delayed(fit_pca_for_cluster)(*args) for args in cluster_data_inputs
+        )
+    
+    # recalculate cluster counts from labels, for proportional sampling
+    cluster_sample_counts = np.array([np.sum(cluster_labels == i) for i in range(n_hyperellipsoids)])
+
+    # distribute samples proportionally to cluster size
+    total_cluster_count = np.sum(cluster_sample_counts)
+    if total_cluster_count == 0:
+        n_samples_per_ellipsoid = np.ones(n_hyperellipsoids, dtype=int)
+    else:
+        n_samples_per_ellipsoid = np.round(n_samples * (cluster_sample_counts / total_cluster_count)).astype(int)
+    n_samples_per_ellipsoid[-1] += n_samples - np.sum(n_samples_per_ellipsoid)
+    n_samples_per_ellipsoid = np.maximum(0, n_samples_per_ellipsoid)
+    
+    # generate hyperellipsoid samples (sobol distributed radius):
+    hds_samples_normalized = np.zeros((0, n_dimensions))
+
+    # radius scaling factor; scales with dimension
+    confidence_level = 0.9999 # captures 99.99% of cluster's samples
+
+    # critical value (the statistical radius squared)
+    chi2_critical_value = stats.chi2.ppf(confidence_level, df=n_dimensions)
+    baseline_factor = 0.55 - 0.01*np.log(n_dimensions) # empirically derived to resample out-of-bounds points
+    
+    # square root as the scaling factor (Mahalanobis distance)
+    ellipsoid_scaling_factor = baseline_factor * np.sqrt(chi2_critical_value)
+
+    # QMC sequence for radius scaling
+    radius_qmc_sampler = stats.qmc.Sobol(d=1, seed=seed+1) # offset seed from initial qmc
+    radius_qmc_sequence_base = radius_qmc_sampler.random(n=int(n_samples * 2.5)) # generate extra samples
+    radius_start_idx = 0
+    
+    # sequentially generate samples from each ellipsoid
+    collected_samples = []
+    for i, params in enumerate(ellipsoid_params):
+        n_to_generate = n_samples_per_ellipsoid[i] * 2
+        
+        # select next chunk of QMC radius sequence
+        radius_end_idx = radius_start_idx + n_to_generate
+        
+        # prevent index out of bounds
+        if radius_end_idx > len(radius_qmc_sequence_base):
+            # use the remainder
+            radius_qmc_chunk = radius_qmc_sequence_base[radius_start_idx:].flatten()
+        else:
+            radius_qmc_chunk = radius_qmc_sequence_base[radius_start_idx:radius_end_idx].flatten()
+        
+        radius_start_idx = radius_end_idx
+
+        # prevent ValueError from empty array
+        if n_to_generate > 0 and radius_qmc_chunk.size == 0:
+            continue # skip ellipsoid if this chunk is empty
+
+        # generate samples inside current ellipsoid
+        ellipsoid_samples = sample_hyperellipsoid(n_dimensions, 
+                                                n_to_generate, 
+                                                params['origin'], 
+                                                params['components'],
+                                                params['variances'],
+                                                scaling_factor=ellipsoid_scaling_factor,
+                                                radius_qmc_sequence=radius_qmc_chunk
+                                                )
+        
+        # identify points outside boundaries ([0,1] hypercube)
+        in_bounds_mask = np.all(ellipsoid_samples >= 0, axis=1) & np.all(ellipsoid_samples <= 1, axis=1)
+        valid_samples = ellipsoid_samples[in_bounds_mask]
+        
+        # add required number of valid samples
+        num_to_add = min(n_samples_per_ellipsoid[i], len(valid_samples))
+        collected_samples.append(valid_samples[:num_to_add])
+        
+    # vstack
+    if collected_samples:
+        hds_samples_normalized = np.vstack(collected_samples)
+    else:
+        hds_samples_normalized = np.zeros((0, n_dimensions))
+
+    # identify number of points to resample
+    n_to_fill = n_samples - len(hds_samples_normalized) 
+    if n_to_fill > 0:
+        if verbose:
+            print(f'Geometric void filling {n_to_fill} samples.')
+
+        # use the existing collected hds samples to find the voids
+        k_void_neighbors = min(max(5, int(n_dimensions / 10)), 10)
+        void_resamples = sample_in_voids(
+            existing_samples=hds_samples_normalized, 
+            n_to_fill=n_to_fill, 
+            bounds_min=working_bounds_min,
+            bounds_max=working_bounds_max,
+            k_neighbors=k_void_neighbors, # k scales with dimension
+            spread_factor=0.25 # stay local
+            )
+        
+        # combine original hds samples with new void samples
+        hds_samples_normalized = np.vstack([hds_samples_normalized, void_resamples])
+    
+    hds_samples_normalized = hds_samples_normalized[:n_samples]
+    
+    if normalize:
+        # leave in [0,1] space
+        hds_sequence = hds_samples_normalized
+    else:
+        # scale samples to original bounds
+        hds_sequence = hds_samples_normalized * (bounds_max_orig - bounds_min_orig) + bounds_min_orig
+    
+    ### print & plot results:
+    if verbose:
+        end_time = time.time()
+        sample_generation_time = end_time - start_time
+        
+        # visualization imports
+        import matplotlib.pyplot as plt
+        import seaborn as sns
+        from matplotlib.patches import Circle, Rectangle
+        sns.set_style('dark')
+        
+        # print results
+        print('\nresults:')
+        print('    - number of samples:', len(hds_sequence))
+        print(f'    - sample generation time: {sample_generation_time:.2f}')
+        print(f'    - number of hyperellipsoids: {n_hyperellipsoids}')
+        print(f'    - number of initial QMC: {n_initial_qmc}')
+        print(f'    - number of initial clusters: {n_initial_clusters}')
+        if weights:
+            print(f'    - gaussian weights: {weights}')
+        
+        # generate a sobol sequence for comparison
+        sobol_sampler = stats.qmc.Sobol(d=n_dimensions, seed=seed+2) # offset seed to be different from initial qmc
+        sobol_samples_unit = sobol_sampler.random(n=n_samples)
+        if normalize:
+            sobol_samples = sobol_samples_unit
+        else:
+            sobol_samples = stats.qmc.scale(sobol_samples_unit, bounds_min_orig, bounds_max_orig)
+
+        # samples stats:
+        hds_mean = np.mean(hds_sequence)
+        sobol_mean = np.mean(sobol_samples)
+        hds_std = np.std(hds_sequence)
+        sobol_std = np.std(sobol_samples)
+
+        print('\nstats:')
+        print(f'    - mean HDS: {hds_mean:.2f}')
+        print(f'    - mean comparison QMC: {sobol_mean:.2f}')
+        print(f'    - stdev HDS: {hds_std:.2f}')
+        print(f'    - stdev comparison QMC: {sobol_std:.2f}\n')
+
+        # dendrogram of centroids
+        if linkage_matrix is not None:
+            plt.figure(figsize=(9, 7))
+            plt.title(f'Dendrogram of Initial Centroids: {n_dimensions}D')
+            
+            # using pre-calculated linkage matrix
+            shc.dendrogram(linkage_matrix, color_threshold=optimal_distance, above_threshold_color='gray')
+            plt.axhline(y=optimal_distance, color='r', linestyle='--', label=f'Optimal Cutoff (k={n_hyperellipsoids})')
+            plt.ylabel('Dissimilarity Distance')
+            plt.xticks([])
+            
+            plt.legend(loc='upper right')
+            plt.show()
+        
+        # plot for 1d samples
+        if n_dimensions == 1:
+            plt.figure(figsize=(6,5))
+            plt.hist(hds_sequence, bins=30, color='deepskyblue', alpha=0.9, label='HDS Samples')
+            plt.hist(sobol_samples, bins=30, color='red', alpha=0.5, label='Sobol Samples')
+            plt.title('HDS Sample Distribution')
+            plt.xlabel('Value')
+            plt.ylabel('Frequency')
+            plt.legend()
+            plt.show()
+            return hds_sequence
+
+        
+        ### PCA for n_dim > 2:
+
+        if normalize:
+            data_to_plot_raw = initial_samples
+        else:
+            data_to_plot_raw = stats.qmc.scale(initial_samples, bounds_min_orig, bounds_max_orig)
+
+        if n_dimensions > 2:
+            pca = PCA(n_components=2)
+            data_to_plot = pca.fit_transform(data_to_plot_raw)
+            hds_sequence_plot = pca.transform(hds_sequence)
+            sobol_samples_plot = pca.transform(sobol_samples)
+            origins_plot = pca.transform(origins)
+            title_str = f'Parameter Space (PCA): n={n_samples}, D={n_dimensions}'
+            xlabel_str = f'Principal Component 1 ({pca.explained_variance_ratio_[0]:.1%})'
+            ylabel_str = f'Principal Component 2 ({pca.explained_variance_ratio_[1]:.1%})'
+        else:
+            data_to_plot = data_to_plot_raw
+            hds_sequence_plot = hds_sequence
+            sobol_samples_plot = sobol_samples
+            origins_plot = origins
+            title_str = f'Parameter Space: n={n_samples}, D={n_dimensions}'
+            xlabel_str = f'Dimension 0'
+            ylabel_str = f'Dimension 1'
+
+        # plot histograms
+        fig, ax = plt.subplots(1,2,figsize=(9,5))
+        ax[0].hist(hds_sequence.flatten(), bins=30, label='HDS Samples')
+        ax[0].set_title('HDS Distribution')
+        ax[0].set_ylabel('')
+        ax[0].set_yticks([])
+        ax[0].set_xticks([])
+        ax[0].set_xlabel('')
+        ax[1].hist(sobol_samples.flatten(), bins=30, label='Sobol Samples')
+        ax[1].set_title('Sobol Distribution')
+        ax[1].set_ylabel('')
+        ax[1].set_xlabel('')
+        ax[1].set_xticks([])
+        ax[1].set_yticks([])
+        
+        plt.tight_layout()
+        plt.show()
+        
+        # dark visualization parameters for better sample visuals
+        plt.rcParams['figure.facecolor'] = 'black'
+        plt.rcParams['axes.facecolor'] = 'black'
+        plt.rcParams['text.color'] = 'white'
+        plt.rcParams['axes.labelcolor'] = 'white'
+        plt.rcParams['xtick.color'] = 'white'
+        plt.rcParams['ytick.color'] = 'white'
+        plt.rcParams['axes.edgecolor'] = 'white'
+        plt.rcParams['grid.color'] = 'white'
+        plt.rcParams['lines.color'] = 'white'
+
+        # plot samples in PCA space
+        fig, ax = plt.subplots(figsize=(7, 6))
+
+        # samples
+        ax.scatter(data_to_plot[:, 0], data_to_plot[:, 1], zorder=0, color='deepskyblue', label='Initial QMC Data', alpha=0.5, s=1.5)
+        ax.scatter(hds_sequence_plot[:, 0], hds_sequence_plot[:, 1], color='yellow', s=5, zorder=5, label='HDS Samples')
+        ax.scatter(sobol_samples_plot[:, 0], sobol_samples_plot[:, 1], color='red', s=8, label='Sobol Samples')
+        
+        # data hypercube boundary
+        min_plot = np.min(data_to_plot, axis=0)
+        max_plot = np.max(data_to_plot, axis=0)
+        width = max_plot[0] - min_plot[0]
+        height = max_plot[1] - min_plot[1]
+        hypercube_boundary = Rectangle((min_plot[0], min_plot[1]), width, height, fill=False, color='deepskyblue', linewidth=1.5, linestyle='--', label='Bounds', zorder=6)
+        
+        ax.add_patch(hypercube_boundary)
+        ax.set_title(title_str, fontweight='bold', fontsize=14)
+        ax.set_xlabel(xlabel_str)
+        ax.set_ylabel(ylabel_str)
+        ax.axis(False)
+        ax.legend(loc=(0.7,0.75), fontsize=11)
+
+        plt.tight_layout()
+        plt.show()
+
+    return hds_sequence

hdim_opt/quasar_optimization.py

@@ -0,0 +1,740 @@
+# global imports
+import numpy as np
+from scipy import stats
+epsilon = 1e-12 # small epsilon to prevent zero-point errors
+
+
+### test functions, for local testing ###
+
+def rastrigin(x, vectorized=False):
+    '''Rastrigin test function, for local testing.'''
+    
+    A = 10 # rastrigin coefficient
+    
+    # check if x is a matrix (2D) or a single vector (1D)
+    matrix_flag = x.ndim > 1
+    if matrix_flag:
+        # for x of (popsize, dimensions)
+        n = x.shape[1]
+        rastrigin_value = A * n + np.sum(x**2 - A * np.cos(2 * np.pi * x), axis=1)
+    else:
+        # for single solution vector x
+        n = x.shape[0]
+        rastrigin_value = A * n + np.sum(x**2 - A * np.cos(2 * np.pi * x))
+    
+    return rastrigin_value
+
+def ackley(x, vectorized=False):
+    '''Ackley test function, for local testing.'''
+    
+    # check if x is a matrix (2D) or a single vector (1D)
+    matrix_flag = x.ndim > 1
+    if matrix_flag:
+        # for x of (popsize, dimensions)
+        n = x.shape[1]
+        arg1 = -0.2 * np.sqrt(1/n * np.sum(x**2, axis=1))
+        arg2 = 1/n * np.sum(np.cos(2 * np.pi * x), axis=1)
+    else:
+        # for single solution vector x
+        n = x.shape[0]
+        arg1 = -0.2 * np.sqrt(1/n * np.sum(x**2))
+        arg2 = 1/n * np.sum(np.cos(2 * np.pi * x))
+    
+    ackley_val = -20 * np.exp(arg1) - np.exp(arg2) + 20 + np.exp(1)
+    
+    return ackley_val
+
+def sphere(x, vectorized=False):
+    '''Sphere test function, for local testing.'''
+    
+    # check if x is a matrix (2D) or a single vector (1D)
+    matrix_flag = x.ndim > 1
+    if matrix_flag:
+        sphere_val = np.sum(x**2, axis=1)
+    else:
+        sphere_val = np.sum(x**2)
+    
+    return sphere_val
+
+def shifted_function(func, shift_vector, vectorized=False):
+    '''
+    Objective:
+        - Shifts the global optimum of the given test function.
+    
+    Inputs:
+        - func: Original test function.
+        - shift_vector: 1D array of the new optimum.
+    
+    Outputs:
+        - shifted_func: New function with the shifted optimum.
+    '''
+    
+    def shifted_func(x, vectorized=False):
+        return func(x - shift_vector, vectorized=vectorized)
+    return shifted_func
+
+
+### verbose plotting functions ###
+
+def plot_mutations(n_points=100000):
+    '''
+    Plots the distribution of mutation factors for all mutation strategies.
+    '''
+
+    # ensure integer n_points
+    n_points = int(n_points)
+
+    # import matplotlib
+    import matplotlib.pyplot as plt
+
+    # mutation plot params
+    dimensions = 1 # for plotting
+    peak_loc = 0.5
+    initial_std_loc = 0.25
+    local_std = 0.33
+    
+    loc_signs = np.random.choice([-1.0, 1.0], size=(n_points, 1), p=[0.5, 0.5])
+    locs = loc_signs * peak_loc
+    base_mutations = np.random.normal(loc=0.0, scale=initial_std_loc, size=(n_points, dimensions))
+    global_muts = base_mutations + locs
+    global_muts_flat = global_muts.flatten()
+    
+    local_muts = np.random.normal(loc=0.0, scale=local_std, size=(n_points, dimensions))
+    local_muts_flat = local_muts.flatten()
+    
+    try: # in case seaborn is not imported
+        import seaborn as sns
+        sns.set_style('dark')
+        sns.histplot(x=global_muts_flat, bins=50, edgecolor='black',stat='density',kde=True,color='deepskyblue',alpha=0.85,label='Global')
+        sns.histplot(x=local_muts_flat, bins=50, edgecolor='black',stat='density',kde=True,color='darkorange',alpha=0.85,label='Local')
+    except:
+        plt.rcParams['figure.facecolor'] = 'black'
+        plt.rcParams['axes.facecolor'] = 'black'
+        plt.rcParams['text.color'] = 'white'
+        plt.rcParams['axes.labelcolor'] = 'white'
+        plt.rcParams['xtick.color'] = 'white'
+        plt.rcParams['ytick.color'] = 'white'
+        plt.rcParams['axes.edgecolor'] = 'white'
+        plt.rcParams['grid.color'] = 'white'
+        plt.rcParams['lines.color'] = 'white'
+        plt.hist(global_muts_flat, bins=50, edgecolor='black',density=True,color='deepskyblue',alpha=0.85,label='Global')
+        plt.hist(local_muts_flat, bins=50, edgecolor='black',density=True,color='darkorange',alpha=0.85,label='Local')
+    finally:
+        plt.title('Mutation Factor Distribution',fontsize=16)
+        plt.xlabel('Mutation Factor',fontsize=15)
+        plt.ylabel('Frequency',fontsize=15)
+        plt.legend(fontsize=15)
+        
+        plt.tight_layout()
+        plt.show()
+
+
+def plot_trajectories(obj_function, pop_history, best_history, bounds, num_to_plot):
+    '''
+    Plots the solution position history.
+    '''
+    
+    from sklearn.decomposition import PCA
+    import matplotlib.pyplot as plt
+
+    # visualization params
+    plt.rcParams['figure.facecolor'] = 'black'
+    plt.rcParams['axes.facecolor'] = 'black'
+    plt.rcParams['text.color'] = 'white'
+    plt.rcParams['axes.labelcolor'] = 'white'
+    plt.rcParams['xtick.color'] = 'white'
+    plt.rcParams['ytick.color'] = 'white'
+    plt.rcParams['axes.edgecolor'] = 'white'
+    plt.rcParams['grid.color'] = 'white'
+    plt.rcParams['lines.color'] = 'white'
+    
+    original_dims = bounds.shape[0]
+    
+    # convert to arrays
+    plot_pop_history = np.array(pop_history)
+    plot_best_history = np.array(best_history)
+    
+    # ensure bounds array has more than 2 dimensions
+    if original_dims > 2:
+        pca = PCA(n_components=2)
+        
+        # reshape data to fit PCA
+        all_data = plot_pop_history.reshape(-1, original_dims)
+        
+        # fit PCA on population history
+        pca.fit(all_data)
+
+        # reshape data
+        num_generations = plot_pop_history.shape[0]
+        popsize = plot_pop_history.shape[1]
+        
+        # transform and reshape dadta
+        plot_pop_history = pca.transform(all_data).reshape(num_generations, popsize, 2)
+        plot_best_history = pca.transform(plot_best_history)
+        
+        # adjust bounds
+        combined_transformed_data = np.concatenate([plot_pop_history.reshape(-1, 2), plot_best_history], axis=0)
+        
+        # ensure combined data is not empty
+        if combined_transformed_data.size > 0:
+            min_vals = np.min(combined_transformed_data, axis=0)
+            max_vals = np.max(combined_transformed_data, axis=0)
+            x_min, x_max = min_vals[0], max_vals[0]
+            y_min, y_max = min_vals[1], max_vals[1]
+        else:
+            x_min, x_max = -1, 1
+            y_min, y_max = -1, 1
+    
+    else:
+        x_min, x_max = bounds[0, 0], bounds[0, 1]
+        y_min, y_max = bounds[1, 0], bounds[1, 1]
+    
+    plt.figure(figsize=(9, 7))
+    plt.xlabel('Principal Component 0')
+    plt.ylabel('Principal Component 1')
+    plt.title('Solution Trajectories')
+    
+    # objective function contour plot
+    x = np.linspace(x_min, x_max, 100)
+    y = np.linspace(y_min, y_max, 100)
+    X, Y = np.meshgrid(x, y)
+    xy_coords = np.vstack([X.ravel(), Y.ravel()]).T
+    
+    if plot_pop_history is not None:
+        indices_to_plot = np.random.choice(plot_pop_history.shape[1], min(num_to_plot, plot_pop_history.shape[1]), replace=False)
+        
+        for i in indices_to_plot:
+            x_coords = plot_pop_history[:, i, 0]
+            y_coords = plot_pop_history[:, i, 1]
+            plt.plot(x_coords, y_coords, linestyle='-', marker='o', markersize=3, alpha=0.67, zorder=1)
+
+    # plot path of best solution
+    if plot_best_history is not None:
+        x_coords = plot_best_history[:, 0]
+        y_coords = plot_best_history[:, 1]
+        plt.plot(x_coords, y_coords, linestyle='-', marker='x', markersize=8, color='red', label='Best Solution Trajectory', 
+                 alpha=0.85, zorder=2)
+        plt.scatter(x_coords[0], y_coords[0], color='cyan', marker='d', s=300, label='Initial Best Solution', alpha=0.8, zorder=5)
+        plt.scatter(x_coords[-1], y_coords[-1], color='cyan', marker='X', s=350, label='Final Best Solution', alpha=0.8, zorder=5)
+    
+    plt.legend(fontsize=10,markerscale=0.67)
+    plt.grid(False)
+    plt.show()
+
+
+### evolution algorithm ###
+
+def initialize_population(popsize, bounds, init, hds_weights, seed, verbose):
+    '''
+    Objective:
+        - Initializes a population using Sobol, Adaptive Hyperellipsoid, or a custom population.
+    '''
+
+    # misc extracts
+    n_dimensions = bounds.shape[0]
+    
+    # if input is not a string assume it is the initial population
+    if isinstance(init, str):
+        init = init.lower() # ensure lowercase string
+        
+        # generate adaptive hypersphere sequence
+        if init == 'hds':
+            # import hds
+            try:
+                from . import hyperellipsoid_sampling as hds
+            except ImportError:
+                import hyperellipsoid_sampling as hds
+    
+            # generate samples
+            if verbose:
+                print('Initializing Hyperellipsoid vectors.')
+            initial_population = hds.sample(popsize, bounds, weights=hds_weights, 
+                                            seed=seed, verbose=False)
+    
+        # generate sobol sequence
+        elif init == 'sobol':
+            if verbose:
+                print('Initializing Sobol vectors.')
+            import warnings
+            warnings.filterwarnings('ignore', category=UserWarning) # ignore power-of-2 warning
+            sobol_sampler = stats.qmc.Sobol(d=n_dimensions, seed=seed)
+            sobol_samples_unit = sobol_sampler.random(n=popsize)
+            initial_population = stats.qmc.scale(sobol_samples_unit, bounds[:, 0], bounds[:, 1])
+    
+        elif init == 'lhs':
+            if verbose:
+                print('Initializing Latin Hypercube vectors.')
+            lhs_sampler = stats.qmc.LatinHypercube(d=n_dimensions, seed=seed)
+            lhs_samples_unit = lhs_sampler.random(n=popsize)
+            initial_population = stats.qmc.scale(lhs_samples_unit, bounds[:, 0], bounds[:, 1])
+    
+        elif init == 'random':
+            if verbose:
+                print('Initializing random vectors.')
+            initial_population = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(popsize, n_dimensions))
+    else:
+        initial_population = init
+        if verbose:
+            print('Initializing custom population.')
+
+    return initial_population
+
+def evolve_generation(obj_function, population, fitnesses, best_solution, 
+                      bounds, entangle_rate, generation, maxiter, 
+                      vectorized, *args):
+    '''
+    Objective:
+        - Evolves the population for the current generation.
+            - Dynamic crossover rate:
+                - Worst solution CR = 1.0, best solution CR = 0.33.
+            - Local & global mutation factor distributions.
+                - Can be displayed using the 'plot_mutations' function.
+            - Greedy selection:
+                - New solution vector is chosen as the better between of trial and current vectors.
+            - Covariance reinitialization is handled externally.
+    '''
+
+    # crossover parameters
+    base_crossover_proba = 1.0
+    min_crossover_proba = 0.33
+    
+    if vectorized:
+        dimensions, popsize = population.shape
+        
+        # select random entangled partners for all solutions
+        random_indices = np.random.randint(0, popsize, size=popsize)
+        entangled_partners = population[:, random_indices]
+
+        # global mutation factor:
+        global_std = 0.25
+        global_peaks = 0.5
+        is_positive_peak = np.random.choice([True, False], p=[0.5, 0.5])
+        global_mutation = np.random.normal(loc=global_peaks, scale=global_std, 
+                                            size=(dimensions,1)) if is_positive_peak else np.random.normal(loc=-global_peaks, 
+                                            scale=global_std, size=(dimensions,1))
+
+        # local mutation factor:
+        local_mutation_std = 0.33
+        local_mutation = np.random.normal(0.0, local_mutation_std, size=(dimensions,1))
+        
+        # best solution as a column vector (dimensions, 1)
+        best_solution_broadcast = best_solution[:, np.newaxis]
+
+        # identify solution indices to use Spooky-Best strategy
+        local_indices = np.random.rand(1, popsize) < entangle_rate
+
+        # global mutations
+        mutant_vectors_current = population + global_mutation * (best_solution_broadcast - entangled_partners)
+        mutant_vectors_random = entangled_partners + global_mutation * (population - entangled_partners)
+        
+        # 50% chance of using Spooky-Random, otherwise Spooky-Current
+        entangled_random_indices = np.random.rand(1, popsize) < 0.5
+        
+        # select between the two global mutations
+        global_mutants = np.where(entangled_random_indices, mutant_vectors_random, mutant_vectors_current)
+        
+        # select between local and global mutations
+        mutant_vectors = np.where(local_indices, best_solution_broadcast + local_mutation * (population - entangled_partners), 
+                                  global_mutants)
+        
+        # rank solutions by fitness
+        sorted_indices = np.argsort(fitnesses)
+        ranks = np.zeros_like(fitnesses)
+        ranks[sorted_indices] = np.arange(popsize)
+        max_rank = popsize - 1
+
+        # calculate adaptive crossover rates
+        relative_fitness = (max_rank - ranks) / max_rank
+        adaptive_crossover_proba_raw = (1 - base_crossover_proba) + base_crossover_proba * relative_fitness
+        adaptive_crossover_proba = np.maximum(adaptive_crossover_proba_raw, min_crossover_proba)
+
+        # apply crossover to create trial vectors
+        crossover_indices = np.random.rand(dimensions, popsize) < adaptive_crossover_proba
+        trial_vectors = np.where(crossover_indices, mutant_vectors, population)
+
+        # clip trial vectors to bounds
+        trial_vectors = np.clip(trial_vectors, bounds[:, np.newaxis, 0], bounds[:, np.newaxis, 1])
+        
+        # steady-state elitism selection
+        trial_fitnesses = obj_function(trial_vectors.T, *args)
+        selection_indices = trial_fitnesses < fitnesses
+        
+        new_population = np.where(selection_indices[np.newaxis, :], trial_vectors, population)
+        new_fitnesses = np.where(selection_indices, trial_fitnesses, fitnesses)
+        
+        return new_population, new_fitnesses
+        
+    else:
+        # extract shape
+        popsize, dimensions = population.shape
+
+        # initialize arrays
+        new_population = np.zeros_like(population)
+        new_fitnesses = np.zeros_like(fitnesses)
+
+        # global mutation factor
+        global_std = 0.25
+        global_peaks = 0.5
+        is_positive_peak = np.random.choice([True, False], p=[0.5, 0.5])
+        global_mutation = np.random.normal(loc=global_peaks, scale=global_std, 
+                                           size=dimensions) if is_positive_peak else np.random.normal(loc=-global_peaks, 
+                                                                                      scale=global_std, size=dimensions)
+        
+        # local mutation factor
+        local_mutation_std = 0.33
+        local_mutation = np.random.normal(0.0, local_mutation_std, size=dimensions)
+
+        # adaptive crossover calculations
+        sorted_indices = np.argsort(fitnesses)
+        ranks = np.zeros_like(fitnesses)
+        ranks[sorted_indices] = np.arange(popsize)
+        max_rank = popsize - 1
+        relative_fitness = (max_rank - ranks) / max_rank
+        adaptive_crossover_proba_raw = (1 - base_crossover_proba) + base_crossover_proba * relative_fitness
+        adaptive_crossover_proba = np.maximum(adaptive_crossover_proba_raw, min_crossover_proba)
+        
+        # loop through each solution in population
+        for i in range(popsize):
+            solution = population[i]
+            current_fitness = fitnesses[i]
+
+            # select random 'entangled' partner indices
+            random_index = np.random.randint(0, popsize)
+            entangled_partner = population[random_index]
+
+            # apply mutations
+            if np.random.rand() < entangle_rate:
+                mutant_vector = best_solution + local_mutation * (solution - entangled_partner) # original
+            else:
+                # 50% chance of moving around current location
+                mutant_vector = solution + global_mutation * (best_solution - entangled_partner) # original
+                # 50% chance of moving to entangled partner
+                if np.random.rand() < 0.5:
+                    mutant_vector = entangled_partner + global_mutation * (solution - entangled_partner) # original
+            
+            crossover_indices = np.random.rand(dimensions) < adaptive_crossover_proba[i]
+            trial_vector = np.where(crossover_indices, mutant_vector, solution)
+
+            # clip trial vectors to bounds
+            trial_vector = np.clip(trial_vector, bounds[:, 0], bounds[:, 1])
+
+            # steady-state elitism selection
+            trial_fitness = obj_function(trial_vector, *args)
+            
+            if trial_fitness < current_fitness:
+                new_population[i] = trial_vector
+                new_fitnesses[i] = trial_fitness
+            else:
+                new_population[i] = solution
+                new_fitnesses[i] = current_fitness
+        
+        return new_population, new_fitnesses
+
+def covariance_reinit(population, current_fitnesses, bounds, vectorized):
+    '''
+    Objective:
+        - Reinitializes the worst 33% solutions in the population.
+        - Locations are determined based on a Gaussian distribution from the covariance matrix of 25% best solutions.
+            - Noise is added to enhance diversity.
+        - Probability decays to 33% at the 33% generation.
+        - Conceptualizes particles tunneling to a more stable location.
+    '''
+
+    # reshape depending on vectorized input
+    if vectorized:
+        dimensions, popsize = population.shape
+    else:
+        popsize, dimensions = population.shape
+
+    # handle case where not enough points for covariance matrix
+    if popsize < dimensions + 1:
+        return population
+
+    # keep 25% of best solutions
+    num_to_keep_factor = 0.25
+    num_to_keep = int(popsize * num_to_keep_factor)
+    if num_to_keep <= dimensions:
+        num_to_keep = dimensions + 1 # minimum sample size scaled by dimensions
+    
+    # identify best solutions to calculate covariance gaussian model
+    sorted_indices = np.argsort(current_fitnesses)
+    best_indices = sorted_indices[:num_to_keep]
+    if vectorized:
+        best_solutions = population[:, best_indices]
+    else:
+        best_solutions = population[best_indices]
+    
+    # learn full-covariance matrix
+    if vectorized:
+        mean_vector = np.mean(best_solutions, axis=1)
+        cov_matrix = np.cov(best_solutions)
+    else:
+        mean_vector = np.mean(best_solutions, axis=0)
+        cov_matrix = np.cov(best_solutions, rowvar=False)
+
+    # add epsilon to the diagonal to prevent singular matrix issues
+    cov_matrix += np.eye(dimensions) * epsilon
+
+    # identify solutions to be reset
+    reset_population = 0.33
+    num_to_replace = int(popsize * reset_population)
+    worst_indices = sorted_indices[-num_to_replace:]
+
+    # new solutions sampled from multivariate normal distribution
+    if vectorized:
+        new_solutions_sampled = np.random.multivariate_normal(mean=mean_vector, cov=cov_matrix, size=num_to_replace).T
+    else:
+        new_solutions_sampled = np.random.multivariate_normal(mean=mean_vector, cov=cov_matrix, size=num_to_replace)
+    
+    # add noise for exploration
+    noise_scale = (bounds[:, 1] - bounds[:, 0]) / 20.0
+    if vectorized:
+        noise = np.random.normal(0, noise_scale[:, np.newaxis], size=new_solutions_sampled.shape)
+        new_solutions = new_solutions_sampled + noise
+    else:
+        noise = np.random.normal(0, noise_scale, size=new_solutions_sampled.shape)
+        new_solutions = new_solutions_sampled + noise
+
+    # clip new solutions to bounds
+    if vectorized:
+        population[:, worst_indices] = np.clip(new_solutions, bounds[:, np.newaxis, 0], bounds[:, np.newaxis, 1])
+    else:
+        population[worst_indices] = np.clip(new_solutions, bounds[:, 0], bounds[:, 1])
+
+    return population
+
+def optimize(func, bounds, args=(), 
+              init='sobol', popsize=None, maxiter=100,
+              entangle_rate=0.33, polish=True,
+              patience=np.inf, vectorized=False, 
+              verbose=True, num_to_plot=10,
+              hds_weights=None,
+              seed=None):
+    '''
+    Objective:
+        - Searches for the optimal solution to minimize the objective function.
+        - Conceptualizes quantum stellar particles searching for the most stable energy state.
+        - Mutation factors can be visualized with plot_mutations().
+    Inputs:
+        - func: Objective function to minimize.
+        - bounds: Parameter bounds.
+        - *args: Input arguments for objective function.
+        - init: Initial population sampling method. 
+            - Options are 'sobol', 'random', 'hds', 'lhs', or a custom sample sequence.
+                - Defaults to 'sobol'.
+                - 'hds' to accelerate convergence with slower initialization.
+        - popsize: Number of solution vectors to evolve. 
+            - Defaults to 10 * n_dimensions.
+        - maxiter: Number of generations to evolve.
+        - entangle_rate: Probability of solutions using the local Spooky-Best mutation strategy.
+            - Defaults to 0.33. This causes to the three mutation strategies to be applied equally.
+            - Decreasing leads to higher exploration.
+        - patience: Number of generations without improvement before early convergence.
+        - polish: Final polishing step using 'L-BFGS-B' minimization.
+        - vectorized: Boolean to accept vectorized objective functions.
+        - verbose: Displays prints and plots.
+        - num_to_plot: Number of solution trajectories to display in the verbose plot.
+    Outputs:
+        - (best_solution, best_fitness) tuple:
+            - best_solution: Best solution found.
+            - best_fitness: Fitness of the optimal solution.
+    '''
+
+    # set random seed
+    if seed == None:
+        np.random.seed()
+    else:
+        np.random.seed(seed)
+
+    # handle case where time is not imported
+    if verbose:
+        try:
+            import time
+            start_time = time.time()
+        except:
+            pass
+
+    # lowercase initialization
+    if type(init) == str:
+        init = init.lower()
+        
+    # raise errors for invalid inputs:
+    # entangle rate error
+    if not 0.0 <= entangle_rate <= 1.0:
+        raise ValueError('Entanglement rate must be between [0,1].')
+
+    # initialization error
+    if (type(init) == str) and init not in ['sobol','hds','random','lhs']:
+        raise ValueError("Initial sampler must be one of ['sobol','random','ahs','lhs'], or a custom population.")
+    
+    # patience error
+    if patience <= 1:
+        raise ValueError('Patience must be > 1 generation.')
+    
+    # initialize histories
+    pop_history = []
+    best_history = []
+
+    # ensure bounds is array; shape (n_dimensions,2)
+    bounds = np.array(bounds)
+    n_dimensions = bounds.shape[0]
+    
+    # if init is not a string, assume it is a custom population
+    if not isinstance(init, str):
+        popsize = init.shape[0]
+        
+    # default popsize to 10*n_dimensions
+    if popsize == None:
+        popsize = 10*n_dimensions
+
+    # ensure integers
+    popsize, maxiter = int(popsize), int(maxiter)
+
+    # generate initial population
+    initial_population = initialize_population(popsize, bounds, init, hds_weights, seed, verbose)
+    if verbose:
+        print('\nEvolving population:')
+
+    # match differential evolution conventions
+    if vectorized:
+        initial_population = initial_population.T
+        initial_fitnesses = func(initial_population.T, *args)
+    else:
+        initial_fitnesses = np.array([func(sol, *args) for sol in initial_population])
+
+    # calculate initial best fitness
+    min_fitness_idx = np.argmin(initial_fitnesses)
+    initial_best_fitness = initial_fitnesses[min_fitness_idx]
+
+    # identify initial best solution
+    if vectorized:
+        initial_best_solution = initial_population[:, min_fitness_idx].copy()
+    else:
+        initial_best_solution = initial_population[min_fitness_idx].copy()
+
+    # initialze population and fitnesses
+    population = initial_population
+    current_fitnesses = initial_fitnesses
+
+    # add initial population to population history
+    if verbose:
+        if vectorized:
+            pop_history.append(population.T.copy())
+        else:
+            pop_history.append(population.copy())
+
+    # add initial best solution to best solution history
+    best_history.append(initial_best_solution.copy())
+    
+    # initialize best solution and fitness
+    best_solution = initial_best_solution
+    best_fitness = initial_best_fitness
+    
+    # iterate through generations
+    last_improvement_gen = 0
+    for generation in range(maxiter):
+        
+        # evolve population
+        if vectorized:
+            population, current_fitnesses = evolve_generation(func, population, current_fitnesses, best_solution, bounds, 
+                                                             entangle_rate, generation, maxiter, vectorized, *args)
+        else:
+            population, current_fitnesses = evolve_generation(func, population, current_fitnesses, best_solution, bounds, 
+                                                             entangle_rate, generation, maxiter, vectorized, *args)
+        
+        # update best solution found
+        min_fitness_idx = np.argmin(current_fitnesses)
+        current_best_fitness = current_fitnesses[min_fitness_idx]
+
+        # identify current best solution
+        if vectorized:
+            current_best_solution = population[:, min_fitness_idx].copy()
+        else:
+            current_best_solution = population[min_fitness_idx].copy()
+
+        # update best known solution
+        if current_best_fitness < best_fitness:
+            best_fitness = current_best_fitness
+            best_solution = current_best_solution
+            last_improvement_gen = 0
+        else:
+            last_improvement_gen += 1
+
+        # apply asymptotic covariance reinitialization to population
+        final_proba = 0.33
+        decay_generation = 0.33
+        reinit_proba = np.e**((np.log(final_proba)/(decay_generation*maxiter))*generation)
+        if np.random.rand() < reinit_proba:
+            population = covariance_reinit(population, current_fitnesses, bounds, vectorized=vectorized)
+
+        # clip population to bounds
+        if vectorized:
+            population = np.clip(population, bounds[:, np.newaxis, 0], bounds[:, np.newaxis, 1])
+        else:
+            population = np.clip(population, bounds[:, 0], bounds[:, 1])
+
+        # add to population history
+        if verbose:
+            if vectorized:
+                pop_history.append(population.T.copy())
+            else:
+                pop_history.append(population.copy())
+            best_history.append(best_solution.copy())
+
+        # print generation status
+        if verbose:
+            stdev = np.std(current_fitnesses)
+            print(f' Gen. {generation+1}/{maxiter} | f(x)={best_fitness:.2e} | stdev={stdev:.2e} | reinit={reinit_proba:.2f}')
+
+        # patience for early convergence
+        if (generation - last_improvement_gen) > patience:
+            if verbose:
+                print(f'\nEarly convergence: generations without improvement exceeds patience ({patience}).')
+            break
+
+    # polish final solution step via L-BFGS-B
+    if polish:
+        if verbose:
+            print('Polishing solution.')
+        try:
+            from scipy.optimize import minimize
+            if vectorized:
+                res = minimize(func, best_solution, args=args, bounds=bounds, method='L-BFGS-B', tol=0)
+            else:
+                res = minimize(func, best_solution, args=args, bounds=bounds, method='L-BFGS-B', tol=0)
+            if res.success:
+                best_solution = res.x
+                best_fitness = res.fun
+        except Exception as e:
+            print(f'Polishing failed: {e}')
+
+    # final solution prints
+    if verbose:
+        print('\nResults:')
+
+        # print best fitness
+        print(f'- f(x): {best_fitness:.2e}')
+        
+        #print best solution
+        if len(best_solution)>3:
+            formatted_display = ', '.join([f'{val:.2e}' for val in best_solution[:3]])
+            print(f'- Solution: [{formatted_display}, ...]')
+        else:
+            formatted_display = ', '.join([f'{val:.2e}' for val in best_solution])
+            print(f'- Solution: [{formatted_display}]')
+
+        # print optimization time
+        try:
+            print(f'- Elapsed: {(time.time() - start_time):.3f}s')
+        except Exception as e:
+            print(f'- Elapsed: null') # case where time isn't imported
+        
+        # plotting
+        print()
+        try:
+            plot_trajectories(func, pop_history, best_history, bounds, num_to_plot)
+
+        except Exception as e:
+            print(f'Failed to generate plots: {e}')
+    
+    return (best_solution, best_fitness)

hdim_opt-1.0.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: hdim_opt
+Version: 1.0.0
+Summary: High-Dimensional Optimization Suite: contains QUASAR optimizer and HDS sampling algorithms.
+Author-email: Julian Soltes <jsoltes@regis.edu>
+License: MIT
+Keywords: optimization,high-dimensional,sampling,QUASAR,HDS
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: hds
+Requires-Dist: pandas; extra == "hds"
+Requires-Dist: scikit-learn; extra == "hds"
+Requires-Dist: joblib; extra == "hds"

hdim_opt-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+hdim_opt/__init__.py,sha256=pMI8O7BXPx6ldK98DCsrjGUEZIjlvTDayhO0ceoa--I,263
+hdim_opt/hyperellipsoid_sampling.py,sha256=B8A238hL9bQxVS7R4OjMGRnM6_UyuT70QmE1IR957Lw,24387
+hdim_opt/quasar_optimization.py,sha256=6UwLwyG5H-Q_lgeSHVPsHJe2mW4adhniOinEPx6_sb0,29075
+hdim_opt-1.0.0.dist-info/METADATA,sha256=Wa7wnKwCHwhgsZXe1IS_bjkHhrmseYQfdOCRveN9Fa4,944
+hdim_opt-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hdim_opt-1.0.0.dist-info/top_level.txt,sha256=1KtWo9tEfEK3GC8D43cwVsC8yVG2Kc-9pl0hhcDjw4o,9
+hdim_opt-1.0.0.dist-info/RECORD,,

hdim_opt-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hdim_opt-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hdim_opt