hdim-opt 1.3.0__py3-none-any.whl → 1.3.1__py3-none-any.whl

hdim_opt/__init__.py

@@ -4,10 +4,11 @@
 
 Functions:
 	- quasar: QUASAR optimization for high-dimensional, non-differentiable problems.
-	- hds: Generate an exploitative HDS sequence, to distribute samples in focused regions.
+	- hyperellipsoid: Generate a non-uniform hyperellipsoid density sequence.
 	- sobol: Generate a uniform Sobol sequence (via SciPy).
 	- sensitivity: Perform Sobol sensitivity analysis to measure each variable's importance on objective function results (via SALib).
-	- waveform: Decompose the input waveform array (handles time- and frequency-domain via FFT / IFFT) into a diagnostic summary.
+	- waveform: Decompose the input waveform array (handles time- and frequency-domain via FFT / IFFT) into a diagnostic summary (work in progress).
+	- isotropize: Isotropize the input matrix using zero-phase component analysis.
 
 Modules:
 	- test_functions: Contains test functions for local optimization testing.
@@ -29,7 +30,7 @@ Example Usage:
 	>>> solution, fitness = h.quasar(obj_func, bounds)
 	>>> sens_matrix = h.sensitivity(obj_func, bounds)
 
-	>>> hds_samples = h.hds(n_samples, bounds)
+	>>> hds_samples = h.hyperellipsoid(n_samples, bounds)
 	>>> sobol_samples = h.sobol(n_samples, bounds)
 	>>> isotropic_samples = h.isotropize(sobol_samples)
 
@@ -37,12 +38,12 @@ Example Usage:
 """
 
 # package version
-__version__ = "1.3.0"
-__all__ = ['quasar', 'hds', 'sobol', 'sensitivity', 'test_functions', 'quasar_helpers'] # available for star imports
+__version__ = "1.3.1"
+__all__ = ['quasar', 'hyperellipsoid', 'sobol', 'sensitivity', 'test_functions', 'quasar_helpers','waveform'] # available for star imports
 
 # import core components
 from .quasar_optimization import optimize as quasar
-from .hyperellipsoid_sampling import sample as hds
+from .hyperellipsoid_sampling import sample as hyperellipsoid
 from .sobol_sampling import sobol_sample as sobol
 from .sobol_sensitivity import sens_analysis as sensitivity
 from .waveform_analysis import analyze_waveform as waveform

hdim_opt/hyperellipsoid_sampling.py

@@ -1,5 +1,5 @@
 # global epslion
-epsilon = 1e-12
+epsilon = 1e-16
 
 ### misc helper functions 
 
@@ -179,6 +179,7 @@ def fit_pca_for_cluster(cluster_samples, current_origin, initial_samples_std, n_
 def sample(n_samples, bounds,
            weights=None, normalize=False,
            n_ellipsoids=None, n_initial_clusters=None, n_initial_qmc=None,
+           ellipsoid_scaling_factor=None,
            seed=None, plot_dendrogram=False, verbose=False):
     '''
     Objective:
@@ -367,11 +368,12 @@ def sample(n_samples, bounds,
     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)
+    if ellipsoid_scaling_factor == None:
+        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

hdim_opt/quasar_helpers.py

@@ -2,52 +2,52 @@
 import pandas as pd
 from sklearn.preprocessing import StandardScaler
 import numpy as np
-from scipy.linalg import cholesky, solve_triangular
-epsilon = 1e-12
+epsilon = 1e-16
 
 def isotropize(data):
     '''
     Objective: 
-        - Converts data to isotropic space. Removes correlations and scales to mean and variance.
-        - Promotes optimization stability.
-    Inputs: 
-        - data: Input data.
-    Outputs: 
-        - data_isotropic: Isotropized data.
-        - metadata: Scaler and whitening matrix 
+        - Converts data to isotropic space using Zero-Phase Component Analysis (ZCA).
+        - Maintains original feature orientation while removing correlations.
     '''
+    from scipy.linalg import eigh
     
     # convert to array
     X = np.array(data)
     
     # standard scaling (mean = 0, var = 1)
     mean = np.mean(X, axis=0)
-    stdev = np.std(X, axis=0)
+    stdev = np.std(X, axis=0) + epsilon # Add epsilon to avoid div0
     X_centered = (X - mean) / stdev
     
-    # whitening parameters
-    n_dims = X_centered.shape[1]
-    cov = np.cov(X_centered, rowvar=False) + np.eye(n_dims) * epsilon
-    L = cholesky(cov, lower=True)
+    # eigen-decomposition of the correlation matrix
+    cov = np.cov(X_centered, rowvar=False) + np.eye(X_centered.shape[1]) * epsilon
+    eigenvalues, eigenvectors = eigh(cov) # eigh is more stable for symmetric matrices like covariance
     
-    # transform Y = (X_centered) @ (L^-1).T
-    data_iso = solve_triangular(L, X_centered.T, lower=True).T
+    # ZCA whitening matrix: W_zca = U @ diag(1/sqrt(lambda)) @ U.T
+    # transforms data to identity covariance while minimizing rotation
+    diag_inv_sqrt = np.diag(1.0 / np.sqrt(eigenvalues + epsilon))
+    W_zca = eigenvectors @ diag_inv_sqrt @ eigenvectors.T
+    
+    # transform: y = X_centered @ W_zca.T
+    data_iso = np.dot(X_centered, W_zca.T)
     
     # store parameters for deisotropization
     params = {
         'mean': mean,
         'stdev': stdev,
-        'L': L
+        'W_zca': W_zca,
+        'W_zca_inv': eigenvectors @ np.diag(np.sqrt(eigenvalues + epsilon)) @ eigenvectors.T
     }
     return data_iso, params
 
 def deisotropize(data_iso, params):
-    '''De-isotropize data to its original parameter space.'''
+    '''De-isotropize data to its original parameter space via inverse ZCA.'''
     
-    # reverse whitening: X_centered = Y @ L.T
-    data_centered = np.dot(data_iso, params['L'].T)
+    # inverse ZCA: X_centered = y @ W_zca_inv.T
+    data_centered = np.dot(data_iso, params['W_zca_inv'].T)
     
-    # reverse scaling: X = (X_centered * std) + mean
+    # inverse scaling: X = (X_centered * std) + mean
     data_original = (data_centered * params['stdev']) + params['mean']
     return data_original
 

hdim_opt/quasar_optimization.py

@@ -371,10 +371,10 @@ def asym_reinit(population, current_fitnesses, bounds, reinit_method, seed, vect
 def optimize(func, bounds, args=(),
               init='sobol', popsize=None, maxiter=100,
               entangle_rate=0.33, polish=True, polish_minimizer=None,
-              patience=np.inf, vectorized=False,
-              hds_weights=None, kwargs={},
+              patience=np.inf, tolerance=-np.inf, vectorized=False,
+              kwargs={},
               constraints=None, constraint_penalty=1e9,
-              reinitialization_method='covariance',
+              reinitialization='covariance', hds_weights=None,
               verbose=True, plot_solutions=True, num_to_plot=10, plot_contour=True,
               workers=1, seed=None
               ):
@@ -382,7 +382,6 @@ def optimize(func, bounds, args=(),
     Objective:
         - Finds the optimal solution for a given objective function.
         - Designed for non-differentiable, high-dimensional problems.
-        - For explorative problems chance reinitialization_method to '
         - Test functions available for local testing, called as hdim_opt.test_functions.function_name.
             - Existing test functions: [rastrigin, ackley, sinusoid, sphere, shubert].
             
@@ -413,11 +412,10 @@ def optimize(func, bounds, args=(),
             - Recommended to place constraints in objective function to use Powell.
         
         - patience: Number of generations without improvement before early convergence.
+        - tolerance: Target objective function value for early convergence.
         - vectorized: Boolean to accept vectorized (N,D) objective functions 
-            - Extremely efficient, highly recommended whenever possible.
+            - Highly efficient, recommended when possible.
         
-        - hds_weights: Optional weights for hyperellipsoid density sampling initialization.
-            - {0 : {'center' : center, 'std': stdev}, 1: {...} }
         - kwargs: Dictionary of keyword arguments for the objective function.
 
         - constraints: Dictionary of constraints to penalize.
@@ -433,11 +431,13 @@ def optimize(func, bounds, args=(),
                                         }
         - constraint_penalty: Penalty applied to each constraint violated, defaults to 1e12.
 
-        - reinitialization_method: Type of re-sampling to use in the asymptotic reinitialization.
+        - reinitialization: Type of re-sampling to use in the asymptotic reinitialization.
             - Options are ['covariance', 'sobol'].
-            - 'covariance' (exploitative) is default for most problems.
+            - 'covariance' (exploitative) is default for N > D problems.
             - 'sobol' (explorative) is optional, for high exploration and faster computation.
             - None to disable reinitialization calculations.
+        - hds_weights: Optional weights for hyperellipsoid density sampling initialization.
+            - {0 : {'center' : center, 'std': stdev}, 1: {...} }
         
         - verbose: Displays prints and plots.
             - Mutation factor distribution shown with hdim_opt.test_functions.plot_mutations()
@@ -499,10 +499,7 @@ def optimize(func, bounds, args=(),
     # ensure bounds is array; shape (n_dimensions,2)
     bounds = np.array(bounds)
     n_dimensions = bounds.shape[0]
-
-    if n_dimensions == 1:
-        reinitialization = False
-        
+    
     # if init is not a string, assume it is a custom population
     if not isinstance(init, str):
         popsize = init.shape[0]
@@ -516,7 +513,11 @@ def optimize(func, bounds, args=(),
     # ensure integers
     popsize, maxiter = int(popsize), int(maxiter)
 
+    # map to sobol if N < D
+    if n_dimensions == 1:
+        reinitialization = None
     
+        
     ################################# INPUT ERRORS #################################
     
     # entangle rate error
@@ -537,11 +538,11 @@ def optimize(func, bounds, args=(),
     # generate initial population
     initial_population = initialize_population(popsize, bounds, init, hds_weights, seed, verbose)
     if verbose:
-        if reinitialization_method not in ['sobol', 'covariance', None]:
-            print("reinitialization_method must be one of ['covariance', 'sobol', None].")
+        if reinitialization not in ['sobol', 'covariance', None]:
+            print("reinitialization must be one of ['covariance', 'sobol', None].")
             print(f'\nEvolving (None):')
         else:
-            print(f'\nEvolving ({reinitialization_method}):')
+            print(f'\nEvolving ({reinitialization}):')
 
     # match differential evolution conventions    
     if vectorized:
@@ -648,12 +649,12 @@ def optimize(func, bounds, args=(),
         # apply asymptotic covariance reinitialization to population
         final_proba = 0.33
         decay_generation = 0.33
-        if reinitialization_method in ['sobol','covariance']:
+        if (reinitialization in ['sobol','covariance']):
             reinit_proba = np.e**((np.log(final_proba)/(decay_generation*maxiter))*generation)
         else:
             reinit_proba = 0.0
         if np.random.rand() < reinit_proba:
-            population = asym_reinit(population, current_fitnesses, bounds, reinitialization_method, seed, vectorized=vectorized)
+            population = asym_reinit(population, current_fitnesses, bounds, reinitialization, seed, vectorized=vectorized)
 
         # clip population to bounds
         if vectorized:
@@ -685,9 +686,12 @@ def optimize(func, bounds, args=(),
         # patience for early convergence
         if (generation - last_improvement_gen) > patience:
             if verbose:
-                print(f'\nEarly convergence: number of generations without improvement exceeds patience ({patience}).')
+                print(f'Early convergence: number of generations without improvement exceeds patience ({patience}).')
+            break
+        if best_fitness <= tolerance:
+            if verbose:
+                print(f'Early convergence: f(x) below tolerance ({tolerance:.2e}).')
             break
-
     
     ################################# POLISH #################################
     
@@ -703,7 +707,7 @@ def optimize(func, bounds, args=(),
                                         maxiter=maxiter, vectorized=vectorized, constraints=constraints, 
                                         args=args, kwargs=kwargs, 
                                         polish_minimizer=polish_minimizer, verbose=verbose
-    )
+        )
 
     
     ################################# VERBOSE #################################

hdim_opt/sobol_sampling.py

@@ -4,7 +4,7 @@ import numpy as np
 def sobol_sample(n_samples, bounds, normalize=False, seed=None):
     '''
     Objective:
-        - Generate a uniform scrambled Sobol sample sequence.
+        - Generates a uniform scrambled Sobol sample sequence.
     Inputs:
         - n_samples: Number of samples to generate.
         - bounds: Range to sample over.

hdim_opt/sobol_sensitivity.py

@@ -1,4 +1,4 @@
-def sens_analysis(func, bounds, n_samples=None, 
+def sens_analysis(func, bounds, n_samples=2**7, 
                   kwargs=None, param_names=None,
                   verbose=True, log_scale=True):
     '''
@@ -24,9 +24,10 @@ def sens_analysis(func, bounds, n_samples=None,
         from SALib.analyze import sobol as sobol_analyze
         import pandas as pd
         from functools import partial
+        import time
     except ImportError as e:
         raise ImportError(f'Sensitivity analysis requires dependencies: (SALib, pandas, functools).') from e
-    
+    start_time = time.time()
     
     # define input parameters and their ranges
     bounds = np.array(bounds)
@@ -34,10 +35,6 @@ def sens_analysis(func, bounds, n_samples=None,
     if param_names == None:
         param_names = range(0,n_params)
 
-    # scale default n_samples by dimension (power of 2)
-    if n_samples == None:
-        n_samples = int(2**np.ceil(np.log2(10*n_params)))
-
     # define problem
     problem = {
         'num_vars': n_params,
@@ -68,7 +65,10 @@ def sens_analysis(func, bounds, n_samples=None,
     S2_df = S2_df.fillna(S2_df.T)
     mask = np.tril(np.ones_like(S2_df, dtype=bool))
 
+    end_time = time.time()
+    run_time = end_time - start_time
     if verbose:
+        print(f'\nRun time: {run_time:.2f}s')
         # import
         try:
             import matplotlib.pyplot as plt
@@ -114,6 +114,7 @@ def sens_analysis(func, bounds, n_samples=None,
         
         axs[0].set_yticks(index)
         axs[0].set_yticklabels(names_sorted)
+        axs[0].legend()
         
         # plot 2: heatmap of second order indices
         sns.heatmap(data=S2_df, mask=mask, cbar_kws={'label': 'Second-order Index ($S_2$)'},ax=axs[1]) # magma

hdim_opt/waveform_analysis.py

@@ -440,7 +440,10 @@ def plot_diagnostic_dashboard(temporal, spectral, metrics):
     im = ax_spec.pcolormesh(t_spec*1e6, f, 10*np.log10(Sxx + epsilon), 
                             shading='gouraud', cmap='plasma')
     
+    ax_spec.set_title('Spectrogram')
     ax_spec.set_yscale('log')
     ax_spec.set_ylim(np.abs(spectral['freq']).min()+epsilon, np.abs(spectral['freq'].max()/sample_rate))
+    cbar = fig.colorbar(im, ax=ax_spec)
+    cbar.set_label('Power/Frequency (dB/Hz)')
 
     plt.show()

{hdim_opt-1.3.0.dist-info → hdim_opt-1.3.1.dist-info}/METADATA

@@ -1,19 +1,33 @@
 Metadata-Version: 2.4
 Name: hdim_opt
-Version: 1.3.0
-Summary: Optimization toolkit for high-dimensional, non-differentiable problems.
+Version: 1.3.1
+Summary: High-dimensional global optimization and sampling toolkit for complex and non-differentiable problems.
 Author-email: Julian Soltes <jsoltes@regis.edu>
 License: MIT
+Project-URL: Homepage, https://github.com/jgsoltes/hdim_opt
 Project-URL: Repository, https://github.com/jgsoltes/hdim_opt
-Keywords: optimization,high-dimensional,sampling,QUASAR,hyperellipsoid
+Project-URL: Issues, https://github.com/jgsoltes/hdim_opt/issues
+Project-URL: Changelog, https://github.com/jgsoltes/hdim_opt/releases
+Keywords: optimization,high-dimensional,sampling,QUASAR,hyperellipsoid,evolutionary-algorithm,non-differentiable,global-optimization,stochastic-optimization,black-box-optimization
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Natural Language :: English
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Scientific/Engineering :: Physics
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: numpy
@@ -32,7 +46,7 @@ A modern optimization package to accelerate convergence in complex, high-dimensi
 
 All core functions, listed below, are single-line executable and require three essential parameters: [obj_function, bounds, n_samples].
 * **quasar**: QUASAR optimization for high-dimensional, non-differentiable problems.
-* **hds**: Generate an exploitative HDS sequence, to distribute samples in focused regions.
+* **hyperellipsoid**: Generate a non-uniform Hyperellipsoid Density sequence, to focus sample distributions.
 * **sobol**: Generate a uniform Sobol sequence (via SciPy).
 * **sensitivity**: Perform Sobol sensitivity analysis to measure each variable's importance on objective function results (via SALib).
 * **waveform**: Decompose the input waveform array (handles time- and frequency-domain via FFT / IFFT) into a diagnostic summary.
@@ -63,7 +77,7 @@ time, pulse = h.waveform_analysis.e1_waveform()
 solution, fitness = h.quasar(obj_func, bounds)
 sens_matrix = h.sensitivity(obj_func, bounds)
 
-hds_samples = h.hds(n_samples, bounds)
+hds_samples = h.hyperellipsoid(n_samples, bounds)
 sobol_samples = h.sobol(n_samples, bounds)
 isotropic_samples = h.isotropize(sobol_samples)
 
@@ -75,7 +89,7 @@ signal_data = h.waveform(x=time,y=pulse)
 
 * Benefit: Significant improvements in convergence speed and solution quality compared to contemporary optimizers. (Reference: [https://arxiv.org/abs/2511.13843]).
 
-## HDS Sampler (Hyperellipsoid Density Sampling)
-**HDS** is a non-uniform Quasi-Monte Carlo sampling method, specifically designed to exploit promising regions of the search space.
+## HDS Sampler
+**HDS** (Hyperellipsoid Density Sampling) is a non-uniform Quasi-Monte Carlo sampling method, specifically designed to exploit promising regions of the search space.
 
 * Benefit: Provides control over the sample distribution. Results in higher average optimization solution quality when used for population initialization compared to uniform QMC methods. (Reference: [https://arxiv.org/abs/2511.07836]).

hdim_opt-1.3.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+hdim_opt/__init__.py,sha256=qP_2iUU5q7121cfy7TyvKyCDQnyg9tF8jhjszF95KAE,2023
+hdim_opt/hyperellipsoid_sampling.py,sha256=hfmQD6bPVD7VIrZfE9faAHO9BUAHrk1fYQla5RH4vFs,24459
+hdim_opt/quasar_helpers.py,sha256=Gv5QFvx7-RfTnS89Eg7b7oVn6S5urgP7t8CwVPLMTcw,16597
+hdim_opt/quasar_optimization.py,sha256=GKvO4XFZUAZ7Gz24-OFw4odqlOwVVnPJEuBZprEVqx4,32490
+hdim_opt/sobol_sampling.py,sha256=yZl6QyPtl8WpDrclPoFbr61dVww0xnhSQqvmE2XvP8E,913
+hdim_opt/sobol_sensitivity.py,sha256=QciwOnUMxDVEf6mjH2G-HB6CLLDHxO0fqTDdb3Cykcc,4427
+hdim_opt/test_functions.py,sha256=RqjKYIiwAqWplGUsH4oPHLBrVdnLRyw7f0dJX5iyJ4g,2821
+hdim_opt/waveform_analysis.py,sha256=KFoTDvP3NXrZiw9FRTNRGFE9a6Q5f5QH38YnX1_2Aj0,15206
+hdim_opt-1.3.1.dist-info/METADATA,sha256=e8FzDUbxo-tpfZ5VJ_sf8slr2TgUKInE8_QpmTYP-ZI,4440
+hdim_opt-1.3.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+hdim_opt-1.3.1.dist-info/top_level.txt,sha256=1KtWo9tEfEK3GC8D43cwVsC8yVG2Kc-9pl0hhcDjw4o,9
+hdim_opt-1.3.1.dist-info/RECORD,,

{hdim_opt-1.3.0.dist-info → hdim_opt-1.3.1.dist-info}/WHEEL

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

hdim_opt-1.3.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-hdim_opt/__init__.py,sha256=CeLrf9egFUScaSirq3gkT8WXcvw0F58L3b_i6oT8Egs,1894
-hdim_opt/hyperellipsoid_sampling.py,sha256=WYlFJxeLKUf8frrl1vM4b28WRJ8zpneKn1NitSPtQMI,24356
-hdim_opt/quasar_helpers.py,sha256=zcoBggHfc6XhZFlJFJy6p0MGVsQwHa6nMudWauT5Vzo,16255
-hdim_opt/quasar_optimization.py,sha256=U7a4ZbgsNJ24V7sff710D7LGYsUWE0CVNoZCmjahZmE,32329
-hdim_opt/sobol_sampling.py,sha256=Xe_Zzs13xMxCben17gT85lFsoV-GKVOAAgi7lMxnlBI,912
-hdim_opt/sobol_sensitivity.py,sha256=HmwqNSDvofX5u1hOayLgjMZOdjQdOHYHzrOLxMTfhhc,4390
-hdim_opt/test_functions.py,sha256=RqjKYIiwAqWplGUsH4oPHLBrVdnLRyw7f0dJX5iyJ4g,2821
-hdim_opt/waveform_analysis.py,sha256=EV87W4D1rJ31x2X5M2_uFaCFDLhhnMwIft-0djCNXoI,15083
-hdim_opt-1.3.0.dist-info/METADATA,sha256=2HJSVNmCZ_zYYrkMHNYo2s53UR3eLQXmi2t-J77IaeQ,3481
-hdim_opt-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hdim_opt-1.3.0.dist-info/top_level.txt,sha256=1KtWo9tEfEK3GC8D43cwVsC8yVG2Kc-9pl0hhcDjw4o,9
-hdim_opt-1.3.0.dist-info/RECORD,,