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

hdim_opt/__init__.py

@@ -1,7 +1,43 @@
-# hdim_opt/__init__.py
+"""
+
+# hdim-opt: High-Dimensional Optimization Toolkit
+
+Functions:
+	- quasar: QUASAR optimization for high-dimensional, non-differentiable problems.
+	- hds: Generate an exploitative HDS sequence, to distribute samples in focused regions.
+	- 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.
+
+Modules:
+	- test_functions: Contains test functions for local optimization testing.
+	- waveform_analysis: Contains pulse generation functions.
+
+Example Usage:
+
+	# Import
+	>>> import hdim_opt as h
+
+	# Parameter Space
+	>>> n_dimensions = 30
+	>>> bounds = [(-100,100)] * n_dimensions
+	>>> n_samples = 1000
+	>>> obj_func = h.test_functions.rastrigin
+	>>> time, pulse = h.waveform_analysis.e1_waveform()
+
+	# Functions
+	>>> solution, fitness = h.quasar(obj_func, bounds)
+	>>> sens_matrix = h.sensitivity(obj_func, bounds)
+
+	>>> hds_samples = h.hds(n_samples, bounds)
+	>>> sobol_samples = h.sobol(n_samples, bounds)
+	>>> isotropic_samples = h.isotropize(sobol_samples)
+
+	>>> signal_data = h.waveform(x=time,y=pulse)
+"""
 
 # package version
-__version__ = "1.2.2"
+__version__ = "1.3.0"
 __all__ = ['quasar', 'hds', 'sobol', 'sensitivity', 'test_functions', 'quasar_helpers'] # available for star imports
 
 # import core components
@@ -9,5 +45,9 @@ from .quasar_optimization import optimize as quasar
 from .hyperellipsoid_sampling import sample as hds
 from .sobol_sampling import sobol_sample as sobol
 from .sobol_sensitivity import sens_analysis as sensitivity
+from .waveform_analysis import analyze_waveform as waveform
+from .quasar_helpers import isotropize
+from .quasar_helpers import deisotropize
 from . import test_functions
-from . import quasar_helpers
+from . import quasar_helpers
+from . import waveform_analysis

hdim_opt/hyperellipsoid_sampling.py

@@ -472,10 +472,8 @@ def sample(n_samples, bounds,
         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}')
+            print(f'    - 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
@@ -492,10 +490,8 @@ def sample(n_samples, bounds,
         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')
+        print(f'    - HDS mean: {hds_mean:.2f}')
+        print(f'    - HDS stdev: {hds_std:.2f}\n')
 
         # dendrogram of centroids
         if plot_dendrogram:

hdim_opt/quasar_helpers.py

@@ -1,7 +1,56 @@
 # global imports
+import pandas as pd
+from sklearn.preprocessing import StandardScaler
 import numpy as np
+from scipy.linalg import cholesky, solve_triangular
 epsilon = 1e-12
 
+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 
+    '''
+    
+    # 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)
+    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)
+    
+    # transform Y = (X_centered) @ (L^-1).T
+    data_iso = solve_triangular(L, X_centered.T, lower=True).T
+    
+    # store parameters for deisotropization
+    params = {
+        'mean': mean,
+        'stdev': stdev,
+        'L': L
+    }
+    return data_iso, params
+
+def deisotropize(data_iso, params):
+    '''De-isotropize data to its original parameter space.'''
+    
+    # reverse whitening: X_centered = Y @ L.T
+    data_centered = np.dot(data_iso, params['L'].T)
+    
+    # reverse scaling: X = (X_centered * std) + mean
+    data_original = (data_centered * params['stdev']) + params['mean']
+    return data_original
+
 ############## CONSTRAINTS ##############
 def apply_penalty(fitnesses, solutions, constraints, constraint_penalty, vectorized):
     '''

hdim_opt/quasar_optimization.py

@@ -32,14 +32,14 @@ def initialize_population(popsize, bounds, init, hds_weights, seed, verbose):
     
             # generate samples
             if verbose:
-                print(f'Initializing: Hyperellipsoid population (N={popsize}, D={n_dimensions}).')
+                print(f'Initializing: Hyperellipsoid (N={popsize}, D={n_dimensions}).')
             initial_population = hds.sample(popsize, bounds, weights=hds_weights, 
                                             seed=seed, verbose=False)
     
         # generate sobol sequence
         elif init == 'sobol':
             if verbose:
-                print(f'Initializing: Sobol population (N={popsize}, D={n_dimensions}).')
+                print(f'Initializing: Sobol (N={popsize}, D={n_dimensions}).')
             import warnings
             warnings.filterwarnings('ignore', category=UserWarning) # ignore power-of-2 warning
             sobol_sampler = stats.qmc.Sobol(d=n_dimensions, seed=seed)
@@ -48,14 +48,14 @@ def initialize_population(popsize, bounds, init, hds_weights, seed, verbose):
     
         elif (init == 'lhs') or (init == 'latinhypercube'):
             if verbose:
-                print(f'Initializing: Latin Hypercube population (N={popsize}, D={n_dimensions}).')
+                print(f'Initializing: Latin Hypercube (N={popsize}, D={n_dimensions}).')
             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(f'Initializing: Random population (N={popsize}, D={n_dimensions}).')
+                print(f'Initializing: Random (N={popsize}, D={n_dimensions}).')
             initial_population = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(popsize, n_dimensions))
     else:
         if init.ndim == 1:
@@ -64,7 +64,7 @@ def initialize_population(popsize, bounds, init, hds_weights, seed, verbose):
             initial_population = init   
         if verbose:
             custom_popsize, custom_n_dimensions = initial_population.shape
-            print(f'Initializing: Custom population (N={custom_popsize}, D={custom_n_dimensions}).')
+            print(f'Initializing: Custom (N={custom_popsize}, D={custom_n_dimensions}).')
 
     return initial_population
 
@@ -374,7 +374,7 @@ def optimize(func, bounds, args=(),
               patience=np.inf, vectorized=False,
               hds_weights=None, kwargs={},
               constraints=None, constraint_penalty=1e9,
-              reinitialization=True, reinitialization_method='covariance',
+              reinitialization_method='covariance',
               verbose=True, plot_solutions=True, num_to_plot=10, plot_contour=True,
               workers=1, seed=None
               ):
@@ -382,6 +382,7 @@ 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].
             
@@ -432,13 +433,11 @@ def optimize(func, bounds, args=(),
                                         }
         - constraint_penalty: Penalty applied to each constraint violated, defaults to 1e12.
 
-        - reinitialization: Boolean to disable covariance reinitialization if needed.
-            - For cases where the population size is computationally prohibitive.
-            - Disabled by default for 1D problems.
         - reinitialization_method: Type of re-sampling to use in the asymptotic reinitialization.
             - Options are ['covariance', 'sobol'].
             - 'covariance' (exploitative) is default for most problems.
             - 'sobol' (explorative) is optional, for high exploration and faster computation.
+            - None to disable reinitialization calculations.
         
         - verbose: Displays prints and plots.
             - Mutation factor distribution shown with hdim_opt.test_functions.plot_mutations()
@@ -508,9 +507,11 @@ def optimize(func, bounds, args=(),
     if not isinstance(init, str):
         popsize = init.shape[0]
 
-    # default popsize to 10*n_dimensions
+    # default popsize to highest power of 2 from 10*n_dimensions
     if popsize == None:
-        popsize = min(2**7,10*n_dimensions)
+        min_popsize = 2**7
+        default_popsize = int(2**np.ceil(np.log2(10*n_dimensions)))
+        popsize = max(min_popsize, default_popsize)
         
     # ensure integers
     popsize, maxiter = int(popsize), int(maxiter)
@@ -536,7 +537,11 @@ def optimize(func, bounds, args=(),
     # generate initial population
     initial_population = initialize_population(popsize, bounds, init, hds_weights, seed, verbose)
     if verbose:
-        print('\nEvolving population:')
+        if reinitialization_method not in ['sobol', 'covariance', None]:
+            print("reinitialization_method must be one of ['covariance', 'sobol', None].")
+            print(f'\nEvolving (None):')
+        else:
+            print(f'\nEvolving ({reinitialization_method}):')
 
     # match differential evolution conventions    
     if vectorized:
@@ -643,7 +648,7 @@ def optimize(func, bounds, args=(),
         # apply asymptotic covariance reinitialization to population
         final_proba = 0.33
         decay_generation = 0.33
-        if reinitialization:
+        if reinitialization_method in ['sobol','covariance']:
             reinit_proba = np.e**((np.log(final_proba)/(decay_generation*maxiter))*generation)
         else:
             reinit_proba = 0.0

hdim_opt/sobol_sensitivity.py

@@ -75,7 +75,19 @@ def sens_analysis(func, bounds, n_samples=None,
             import seaborn as sns
         except ImportError as e:
             raise ImportError(f'Plotting requires dependencies: (matplotlib, seaborn).') from e
-            
+
+        # sort by S1 values
+        sort_idx = np.argsort(Si['S1'])
+        s1_sorted = Si['S1'][sort_idx]
+        st_sorted = Si['ST'][sort_idx]
+        s1_conf_sorted = Si['S1_conf'][sort_idx]
+        st_conf_sorted = Si['ST_conf'][sort_idx]
+        names_sorted = [np.array(param_names)[i] for i in sort_idx]
+    
+        
+        bar_width = 0.35
+        index = np.arange(n_params)
+        
         # plot 1: first-order (S1) and total-order (ST) indices
         sens_plot, axs = plt.subplots(2,1,figsize=(9, 13)) 
         
@@ -84,35 +96,26 @@ def sens_analysis(func, bounds, n_samples=None,
         index = np.arange(n_params)
         
         # plot S1 (first order) sensitivities
-        axs[0].barh(index - bar_width/2, Si['S1'], bar_width,
-               xerr=Si['S1_conf'], 
-               label='First-order ($S_1$)',
-               # color='cornflowerblue',
-               alpha=1,
-               # ecolor='lightgray',
-               capsize=2.5)
-               # edgecolor='black')
+        axs[0].barh(index - bar_width/2, s1_sorted, bar_width,
+                   xerr=s1_conf_sorted, 
+                   label='First-order ($S_1$)',
+                   alpha=1,
+                   capsize=2.5)
         
-        # plot ST (total order) sensitivities
-        axs[0].barh(index + bar_width/2, Si['ST'], bar_width,
-               xerr=Si['ST_conf'], 
-               label='Total-order ($S_T$)',
-               # color='violet', 
-               # ecolor='lightgray',
-               alpha=0.75, 
-               capsize=2.5)
-               # edgecolor='black')
+        axs[0].barh(index + bar_width/2, st_sorted, bar_width,
+                   xerr=st_conf_sorted, 
+                   label='Total-order ($S_T$)',
+                   alpha=0.75, 
+                   capsize=2.5)
+
         axs[0].set_title('Sensitivity Indices ($S_1$, $S_T$)')
         if log_scale:
             axs[0].set_xscale('log')
-        axs[0].set_xlabel('Sensitivity Index')
-        axs[0].set_ylabel('Parameter')
-        axs[0].legend(loc='upper right')
-        axs[0].grid(False)
+        
         axs[0].set_yticks(index)
-        axs[0].set_yticklabels(param_names, ha='right')
+        axs[0].set_yticklabels(names_sorted)
         
-        # heatmap of second order indices
+        # 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
         axs[1].set_title('Second-order Interactions ($S_2$)')
         axs[1].invert_yaxis()

hdim_opt/waveform_analysis.py

@@ -0,0 +1,446 @@
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from scipy import signal
+
+# constants
+epsilon = 1e-12 # to avoid mathematical singularities
+
+# visualization parameters
+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'
+
+def apply_noise(signal, noise):
+    # adding random gaussian noise within 1% of discrete amplitudes
+    stdev = np.std(np.abs(signal))
+    signal_noisy = signal + noise * np.random.normal(loc=0, scale=stdev, size=signal.shape)
+
+    return signal_noisy
+
+def e1_waveform(peak_Vm=50e3, rise_s=5e-9, decay_s=200e-9, 
+                              sample_Hz=10e9, duration_s=1e-6, noise=0.0):
+    '''
+    Objective:
+        - Generates time-domain double exponential H-EMP E1 waveform, per MIL-STD / IEC specifications.
+        - Pulse waveform: E(t) = E0 * k * (exp(-alpha*t) - exp(-beta*t))
+
+    Inputs:
+        - E_peak_V_m: Target EMP amplitude (V/m).
+        - E_rise_time_ns: Target EMP risetime (ns).
+        - E_decay_time_ns: Target decay time of the pulse (FWHM).
+        - sampling_rate: Sampling rate of pulse (Hz).
+        - duration_ns: Duration of pulse (ns).
+        
+    Outputs:
+        - time_s: Time array of pulse (s).
+        - E_t: Electric field amplitude array at each time (V/m).
+        
+    '''
+    
+    dt_s = 1 / sample_Hz
+    time_s = np.arange(0, duration_s, dt_s)
+
+    # alpha controls the decay and broadband shape
+    # input E_decay_time_ns = desired pulse FWHM
+    alpha = np.log(2) / decay_s # derived from from FWHM = ln(2) / FWHM
+
+    # beta controls the rise time and high-frequency content
+    beta = 2.0035 / rise_s # # approximate relationship: beta ~= 2.2 / (rise_time) (in seconds^-1)
+
+    # calculate time of pulse peak for k_norm calculation
+    t_peak_s = np.log(beta / alpha) / (beta - alpha)
+
+    # 'k_norm' factor normalizes pulse peak to input E_peak_V_m (50,000 V/m)
+    denominator = (np.exp(-alpha * t_peak_s) - np.exp(-beta * t_peak_s))
+    if np.isclose(denominator, 0):
+        k_norm = peak_Vm 
+    else:
+        k_norm = peak_Vm / denominator
+
+    # generate the E1 waveform
+    E_t = k_norm * (np.exp(-alpha * time_s) - np.exp(-beta * time_s))
+    
+    # adding random gaussian noise
+    E_t = apply_noise(E_t, noise)
+    
+    return time_s, E_t
+    
+def e2_waveform(E_peak=100, tr_us=1.5, tf_ms=1.0, sample_rate=1e6, duration_s=0.01, noise=0.0):
+    '''Generates E2 H-EMP pulse waveform (lightning-like).'''
+    t = np.arange(0, duration_s, 1/sample_rate)
+    alpha = 1 / (tf_ms * 1e-3)
+    beta = 1 / (tr_us * 1e-6)
+    E_t = E_peak * 1.1 * (np.exp(-alpha * t) - np.exp(-beta * t))
+    
+    # adding random gaussian noise
+    E_t = apply_noise(E_t, noise)
+    
+    return t, E_t
+
+def e3_waveform(E_peak=40, t_peak_s=10, sample_rate=10, duration_s=500, noise=0.0):
+    '''Generates E3 H-EMP pulse waveform (geostorm-like; magnetohydrodynamic).'''
+    t = np.arange(0, duration_s, 1/sample_rate)
+    
+    # simplified IEC 61000-2-9 E3 waveform
+    E_t = E_peak * (np.exp(-t/120) - np.exp(-t/20)) 
+    
+    # adding random gaussian noise
+    E_t = apply_noise(E_t, noise)
+    
+    return t, E_t
+
+def calculate_rise_time(time_array, pulse_array):
+    '''
+    Objective:
+        - Calculates the 10%-90% rise time of a double exponential pulse waveform.
+
+    Inputs:
+        - time_array: Pulse time array (s).
+        - pulse_array: Pulse waveform array (V/m).
+
+    Outputs: 
+        - rise_time: Rise time (10%-90%) of pulse waveform (ns).
+        - t_90_percent: Time at rising 90% peak amplitude (ns).
+        - t_10_percent: Time at rising 10% amplitude (ns).
+        
+    '''
+    
+    peak_amplitude = np.max(pulse_array)
+    
+    # calculate 10% and 90% thresholds
+    threshold_10_percent = 0.1 * peak_amplitude
+    threshold_90_percent = 0.9 * peak_amplitude
+
+    # find indices where the pulse first crosses the 10% threshold (rising side)
+    idx_10 = np.where(pulse_array >= threshold_10_percent)[0]
+    if len(idx_10) == 0:
+        return None
+    idx_10_first = idx_10[0]
+
+    # find indices where the pulse first crosses the 90% threshold (rising side)
+    idx_90 = np.where(pulse_array >= threshold_90_percent)[0]
+    if len(idx_90) == 0:
+        return None
+    idx_90_first = idx_90[0]
+
+    # interpolate to find the exact time points at 10% and 90% thresholds
+    # time at 10% threshold
+    t_10_percent = time_array[idx_10_first-1] + (threshold_10_percent - pulse_array[idx_10_first-1]) * \
+                   (time_array[idx_10_first] - time_array[idx_10_first-1]) / \
+                   (pulse_array[idx_10_first] - pulse_array[idx_10_first-1])
+    
+    # time at 90% threshold
+    t_90_percent = time_array[idx_90_first-1] + (threshold_90_percent - pulse_array[idx_90_first-1]) * \
+                   (time_array[idx_90_first] - time_array[idx_90_first-1]) / \
+                   (pulse_array[idx_90_first] - pulse_array[idx_90_first-1])
+
+    # calculate risetime
+    rise_time = t_90_percent - t_10_percent
+    
+    return rise_time, t_90_percent, t_10_percent
+    
+def calculate_fwhm(time_array, pulse_array):
+    '''
+    Objective:
+        - Calculates the full width at half maximum (FWHM) of a double exponential pulse waveform.
+
+    Inputs: 
+        - time_array: Pulse time array (s).
+        - pulse_array: Pulse waveform array (V/m).
+
+    Outputs:
+        - fwhm: Full-width half-max of pulse waveform (ns).
+        - t_fwhm2: Time at rising half-max (ns).
+        - t_fwhm1: Time at decaying half-max (ns).
+        
+    '''
+    
+    # find the peak value of the pulse
+    peak_amplitude = np.max(pulse_array)
+    half_max = peak_amplitude / 2.0
+
+    # find indices where the pulse is above half_max
+    indices_above_half_max = np.where(pulse_array >= half_max)[0]
+
+    # find the first and last points where the pulse crosses half_max
+    idx1 = indices_above_half_max[0]
+    idx2 = indices_above_half_max[-1]
+
+    # first FWHM crossing point (rising side)
+    if idx1 == 0: # pulse starts above half_max
+        t_fwhm1 = time_array[idx1]
+    else:
+        # interpolate to find first time point at half_max
+        t_fwhm1 = time_array[idx1-1] + (half_max - pulse_array[idx1-1]) * \
+                  (time_array[idx1] - time_array[idx1-1]) / \
+                  (pulse_array[idx1] - pulse_array[idx1-1])
+
+    # second FWHM crossing point (decaying side)
+    if idx2 == len(pulse_array) - 1: # pulse ends above half_max
+        t_fwhm2 = time_array[idx2]
+    else:
+        # interpolate to find second time point at half_max
+        t_fwhm2 = time_array[idx2] + (half_max - pulse_array[idx2]) * \
+                  (time_array[idx2+1] - time_array[idx2]) / \
+                  (pulse_array[idx2+1] - pulse_array[idx2])
+
+    # calculate FWHM
+    fwhm = t_fwhm2 - t_fwhm1
+    
+    return fwhm, t_fwhm2, t_fwhm1
+
+def apply_shielding(f, shielding_dB, rolloff_hf=500e6, rolloff_lf=1e3):
+    '''
+    Combines complex transfer function math with real-world 
+    LF (Magnetic) and HF (Leakage) rolloff physics.
+    '''
+    # base linear gain
+    base_gain = 10**(-shielding_dB/20) 
+
+    # HF rolloff
+    h_hf = 1 / (1 + 1j * (f / rolloff_hf))
+
+    # LF rolloff
+    h_lf = 1 / (1 + (rolloff_lf / (f + 1e-12)))
+
+    # total complex shielding function
+    h_total = base_gain * h_hf * h_lf
+    
+    return h_total
+    
+def analyze_waveform(x=None, y=None, sample_rate=None, domain='time', method='complex', 
+                     tf_function=None, tf_kwargs=None, noise=0.0, verbose=True):
+    '''
+    Decomposes & analyzes the given signal waveform.
+    Outputs:
+        - df_time: DataFrame of time-domain data (N rows)
+        - df_freq: DataFrame of positive frequency-domain data (N/2+1 rows)
+        - metrics: Dictionary of scalar results
+    '''
+
+    # clean
+    x = np.array(x)
+    y = np.array(y).flatten()
+    domain = 'time' if domain.lower() in ['t', 'time'] else 'freq'
+    
+    # apply transfer function
+    if tf_function:
+        y = apply_transfer_function(x, y, tf_function, domain=domain, **(tf_kwargs or {}))
+    
+    # apply gaussian noise
+    y = apply_noise(y, noise)
+
+    # extract parameters
+    if domain == 'time':
+        n = len(y)
+        fs = 1 / (x[1] - x[0])
+        if method == 'complex':
+            y_f = np.fft.fft(y) / n
+            freqs = np.fft.fftfreq(n, 1/fs)
+        elif method == 'real':
+            y_f = np.fft.rfft(y) / n
+            freqs = np.fft.rfftfreq(n, 1/fs)
+
+        y_t, t = y, x
+    else:
+        n = len(y)
+        fs = sample_rate if sample_rate else x[len(x)//2] * 2
+        if method == 'complex':
+            y_t = np.fft.ifft(y).real * n
+        elif method == 'real':
+            y_t = np.fft.irfft(y).real * n
+        t = np.arange(0, n) / fs
+        y_f, freqs = y, x
+
+    # positive half of frequencies
+    mask = freqs >= 0
+    f_pos = freqs[mask]
+    yf_pos = y_f[mask]
+
+    # energy calculation
+    esd = (np.abs(yf_pos)**2) * (2 / fs)
+    
+    # handle DC
+    esd = (np.abs(yf_pos)**2) * (2 / fs)
+    esd[0] = esd[0] / 2  # DC only exists once
+    
+    # if real, last bin (nyquist) only exists once
+    if method == 'real' and len(esd) > 0:
+        esd[-1] = esd[-1] / 2
+        
+    df_freq = f_pos[1] - f_pos[0]
+    cumul_energy = np.cumsum(esd) * df_freq
+    total_energy = cumul_energy[-1]
+
+    # convert to dataframes:
+    # time domain
+    temporal = {
+        'time_s': t,
+        'amplitude': y_t
+    }
+
+    # frequency domain
+    spectral = {
+        'freq': f_pos,
+        'signal': yf_pos,
+        'esd': esd,
+        'energy': cumul_energy
+    }
+
+    # max gradient
+    dv_dt = np.diff(y_t) * fs
+    
+    # action integral
+    action_integral = np.trapezoid(y_t**2, t)
+    
+    # calculate rise time/decay time
+    rise_s, _, _ = calculate_rise_time(t, np.abs(y_t))
+    rise_ns = 1e9 * rise_s
+    fwhm_s, _, _ = calculate_fwhm(t, np.abs(y_t))
+    fwhm_ns = 1e9 * fwhm_s
+    
+    # scalar metrics
+    metrics = {
+        'peak_t': np.max(np.abs(y_t)),
+        'peak_f': np.max(np.abs(yf_pos)),
+        'total_energy': total_energy,
+        'action_integral': action_integral,
+        'max_dv_dt': np.max(np.abs(dv_dt)),
+        'bw_90_hz': f_pos[np.where(cumul_energy >= 0.9 * total_energy)[0][0]],
+        'center_freq_hz': np.sum(f_pos * esd) / (total_energy + 1e-12),
+        'papr_db': 10 * np.log10(np.max(y_t**2) / np.mean(y_t**2)),
+        'sample_rate': fs,
+        'rise90_ns': rise_ns,
+        'fwhm_ns': fwhm_ns,
+    }
+    
+    # plot
+    if verbose:
+        plot_diagnostic_dashboard(temporal, spectral, metrics)
+
+    return temporal, spectral, metrics
+
+def apply_transfer_function(x, y, tf_function, domain='freq', **kwargs):
+    '''
+    x: Time or frequency array.
+    y: Input signal.
+    tf_function: The transfer function.
+    domain: 'freq' or 'time'.
+    **kwargs: Arguments passed to the transfer function.
+    '''
+
+    if domain == 'freq':
+        H_f = tf_function(np.abs(x), **kwargs)
+        output = y * H_f
+    elif domain == 'time':
+        h_t = tf_function(x, **kwargs) 
+        output = np.convolve(y, h_t, mode='same')
+        output *= (x[1] - x[0]) # normalize by dt
+    else:
+        raise ValueError('Unrecognized signal domain.')
+        
+    return output
+
+def plot_diagnostic_dashboard(temporal, spectral, metrics):
+    '''
+    6-plot diagnostic dashboard:
+    Time Domain | Frequency Magnitude
+    Phase Spectrum | Energy Spectral Density (ESD)
+    Cumulative Energy | Spectrogram
+    '''
+
+    # 3 rows, 2 columns
+    fig = plt.figure(figsize=(16, 20))
+    gs = fig.add_gridspec(3, 2, hspace=0.3, wspace=0.3)
+    
+    ax_time = fig.add_subplot(gs[0, 0])
+    ax_freq = fig.add_subplot(gs[0, 1])
+    ax_phase = fig.add_subplot(gs[1, 0])
+    ax_esd  = fig.add_subplot(gs[1, 1])
+    ax_cum  = fig.add_subplot(gs[2, 0])
+    ax_spec = fig.add_subplot(gs[2, 1])
+
+    # mask for positive frequencies to ensure dimensions match
+    pos_mask = spectral['freq'] >= 0
+    f_mhz = spectral['freq'][pos_mask] / 1e6
+    mag_pos = np.abs(spectral['signal'])[pos_mask]
+
+    # time domain
+    ax_time.plot(temporal['time_s']*1e6, temporal['amplitude'], color='cyan', label=f'Peak: {metrics['peak_t']:.2f}')
+    ax_time.set_title(f'Time-Domain Signal')
+    ax_time.set_xlabel(r'Time ($\mu s$)')
+    ax_time.set_ylabel('Amplitude')
+    ax_time.legend()
+
+    # frequency domain
+    ax_freq.semilogy(f_mhz, np.abs(spectral['signal']), color='violet')
+    ax_freq.set_title('Frequency-Domain Signal')
+    ax_freq.set_xlabel('Frequency (MHz)')
+    max_f = metrics['sample_rate'] / 2e6 # limit no higher than nyquist
+    ax_freq.set_xlim(0, min(1000, max_f))
+    ax_freq.grid(alpha=0.2, which='both')
+
+    # phase spectrum
+    ax_phase.plot(f_mhz, np.angle(spectral['signal']), color='limegreen', linewidth=0.5)
+    ax_phase.set_title('Phase Spectrum')
+    ax_phase.set_xlabel('Frequency (MHz)')
+    ax_phase.set_ylabel('Phase (rad)')
+    ax_phase.set_xlim(ax_freq.get_xlim())
+
+    # energy spectral density (ESD)
+    ax_esd.semilogy(f_mhz, spectral['esd'], color='gold')
+    ax_esd.set_title('Energy Spectral Density (ESD)')
+    ax_esd.set_ylabel(r'$V^2 \cdot s / Hz$')
+    ax_esd.set_xlabel('Frequency (MHz)')
+    ax_esd.set_xlim(ax_freq.get_xlim())
+    ax_esd.set_xlim(0, min(1000, max_f))
+
+    # cumulative energy distribution
+    ax_cum.plot(f_mhz, spectral['energy'], color='gold', linewidth=2)
+    ax_cum.fill_between(f_mhz, spectral['energy'], color='gold', alpha=0.2)
+    ax_cum.axvline(metrics['bw_90_hz'], color='red', linestyle='--', 
+                   label=f'90% Band: {metrics['bw_90_hz']:.1f} MHz')
+    ax_cum.set_title('Cumulative Energy')
+    ax_cum.set_ylabel('Normalized Energy')
+    ax_cum.set_xlabel('Frequency (MHz)')
+    ax_cum.set_xlim(ax_freq.get_xlim())
+    ax_cum.legend(fontsize='small')
+
+    # spectrogram
+    # ensure amplitude is real for spectrogram
+    sample_rate = metrics['sample_rate']
+    y_signal = np.real(temporal['amplitude'])
+    window_duration_s = 0.01*(temporal['time_s'].max() - temporal['time_s'].min())
+    nperseg = int(window_duration_s * sample_rate)
+    
+    raw_n = (1/1.15) * (window_duration_s * sample_rate)
+    
+    # powers of 2
+    if raw_n <= 1:
+        nperseg = 16 # minimum window
+    else:
+        # round to nearest power of 2
+        nperseg = int(2**np.round(np.log2(raw_n)))
+        
+        # reinforce minimum
+        nperseg = max(nperseg, 16)
+    
+    # nonoverlap always less than num per segment
+    noverlap = nperseg // 2
+    f, t_spec, Sxx = signal.spectrogram(y_signal, fs=sample_rate, window='hann', 
+                                        nperseg=nperseg, noverlap=nperseg//2)
+    
+    im = ax_spec.pcolormesh(t_spec*1e6, f, 10*np.log10(Sxx + epsilon), 
+                            shading='gouraud', cmap='plasma')
+    
+    ax_spec.set_yscale('log')
+    ax_spec.set_ylim(np.abs(spectral['freq']).min()+epsilon, np.abs(spectral['freq'].max()/sample_rate))
+
+    plt.show()

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: hdim_opt
-Version: 1.2.2
+Version: 1.3.0
 Summary: Optimization toolkit for high-dimensional, non-differentiable problems.
 Author-email: Julian Soltes <jsoltes@regis.edu>
 License: MIT
 Project-URL: Repository, https://github.com/jgsoltes/hdim_opt
-Keywords: optimization,high-dimensional,sampling,QUASAR,HDS
+Keywords: optimization,high-dimensional,sampling,QUASAR,hyperellipsoid
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -28,13 +28,14 @@ Requires-Dist: SALib; extra == "sensitivity"
 
 # hdim-opt: High-Dimensional Optimization Toolkit
 
-A modern optimization package to accelerate convergence in complex, high-dimensional problems. Includes the QUASAR evolutionary algorithm and HDS exploitative QMC sampler.
+A modern optimization package to accelerate convergence in complex, high-dimensional problems. Includes the QUASAR evolutionary algorithm, HDS exploitative QMC sampler, Sobol sensitivity analysis, and signal waveform decomposition.
 
 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.
 * **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.
 
 ---
 
@@ -52,15 +53,21 @@ pip install hdim_opt
 import hdim_opt as h
 
 # Parameter Space
-n_dimensions = 100
+n_dimensions = 30
 bounds = [(-100,100)] * n_dimensions
 n_samples = 1000
 obj_func = h.test_functions.rastrigin
+time, pulse = h.waveform_analysis.e1_waveform()
 
+# Functions
 solution, fitness = h.quasar(obj_func, bounds)
 sens_matrix = h.sensitivity(obj_func, bounds)
+
 hds_samples = h.hds(n_samples, bounds)
 sobol_samples = h.sobol(n_samples, bounds)
+isotropic_samples = h.isotropize(sobol_samples)
+
+signal_data = h.waveform(x=time,y=pulse)
 ```
 
 ## QUASAR Optimizer

hdim_opt-1.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+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,,

hdim_opt-1.2.2.dist-info/RECORD

@@ -1,11 +0,0 @@
-hdim_opt/__init__.py,sha256=eGhYIxj6AUhhlfqgAHtPQdul64gYYLaWl8esUs-vkgI,477
-hdim_opt/hyperellipsoid_sampling.py,sha256=c34JkVciZbdAXjdfNjfC4h5NsrT2CD7Epsxpef5a1xY,24625
-hdim_opt/quasar_helpers.py,sha256=zTgar2EuWs4MLSLEO7HRcP7At1xbXLP3q4Gg7-GrggQ,14799
-hdim_opt/quasar_optimization.py,sha256=cSF_aOijVhdtvr7VEBUNVyBQ1--1s8cOuWZMuPogf5A,32093
-hdim_opt/sobol_sampling.py,sha256=Xe_Zzs13xMxCben17gT85lFsoV-GKVOAAgi7lMxnlBI,912
-hdim_opt/sobol_sensitivity.py,sha256=1ebeDSTmcLn03_MKDGiyJJ7r_ZSNCq2AKNcTX-hI23A,4384
-hdim_opt/test_functions.py,sha256=RqjKYIiwAqWplGUsH4oPHLBrVdnLRyw7f0dJX5iyJ4g,2821
-hdim_opt-1.2.2.dist-info/METADATA,sha256=jId-zu3VAQTuQFgwlSQqKTgnCtwbORXuLbqsCVbSvA4,3130
-hdim_opt-1.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hdim_opt-1.2.2.dist-info/top_level.txt,sha256=1KtWo9tEfEK3GC8D43cwVsC8yVG2Kc-9pl0hhcDjw4o,9
-hdim_opt-1.2.2.dist-info/RECORD,,