Metadata-Version: 2.4
Name: hdim_opt
Version: 1.6.0
Summary: High-dimensional numerical optimization, sampling, and analysis toolkit.
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
Project-URL: Issues, https://github.com/jgsoltes/hdim-opt/issues
Project-URL: Changelog, https://github.com/jgsoltes/hdim-opt/releases
Project-URL: Documentation, https://github.com/jgsoltes/hdim-opt/blob/main/README.md
Keywords: optimization,high-dimensional,quasi-monte-carlo,global-optimization,derivative-free,evolutionary-algorithm,sensitivity-analysis,QUASAR,hyperellipsoid,symbolic-regression,stepAIC
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
Requires-Dist: scipy
Provides-Extra: hds
Requires-Dist: scikit-learn; extra == "hds"
Provides-Extra: sensitivity
Requires-Dist: pandas; extra == "sensitivity"
Requires-Dist: SALib; extra == "sensitivity"
Requires-Dist: gplearn; extra == "sensitivity"
Requires-Dist: numba; extra == "sensitivity"
Requires-Dist: statsmodels; extra == "sensitivity"

# hdim-opt: High-Dimensional Optimization Toolkit

Numerical optimization package for complex, high-dimensional problems. hdim_opt is a lightweight and comprehensive suite to streamline sampling, optimization, and analysis. Home of the QUASAR evolutionary algorithm and Hyperellipsoid quasi-Monte Carlo sampling.

All core functions, listed below, are single-line executable and depend on three essential parameters: [obj_function, bounds, n_samples]:

### Sampling
* **uniform**: Generate uniform QMC sample sequences (via Scipy.stats.qmc).
* **hyperellipsoid**: Generate hyperellipsoidal sample sequence; may accelerate optimization.
* **isotropize**: Isotropize the input data via zero-phase component analysis (ZCA).
* **encode_bipolar**: Bipolar-logarithmic transform, when negative values and exponents are present.
* **lorentzian**: Fit a Lorentzian/Cauchy kernel density estimation (KDE) to the data.

### Optimization
* **quasar**: Optimization using the QUASAR evolutionary algorithm.
* **minimize**: Optimization using gradient-based minimization (via SciPy.minimize).
* **symbolic**: Symbolic regression to approximate the input data or function (via gplearn).
* **stepAIC**: Stepwise feature selection for linear or logistic regression (R's MASS:stepAIC).

### Analysis
* **sensitivity**: Sensitivity analysis to quantify each dimension's influence (via SALib).
* **hyperslice**: Create a hyperslice of the function's underlying solution space.
* **waveform**: Decompose any 2D waveform.
* **analyze**: Analyze any input dataset.


## Installation
Install `hdim_opt` directly from PyPI:

```bash
pip install hdim_opt
```

## Example Usage
```python
import hdim_opt as h

### Parameter Space
n_samples = 2**10
n_dimensions = 10
bounds = [(-100,100)] * n_dimensions # Parameter bounds
obj_func = h.test_functions.rastrigin # Test function

### Sampling
uniform_samples = h.uniform(n_samples, bounds, method='sobol') # Uniform sampling
ellipsoid_samples = h.hyperellipsoid(n_samples, bounds, verbose=True) # Hyperellipsoid sampling
iso_samples, iso_params = h.isotropize(ellipsoid_samples) # Isotropize data (ZCA)
bipolar_log_samples = h.encode_bipolar(iso_samples, [b[0] for b in bounds]) # Bipolar-logarithm transform
kde = h.lorentzian(iso_samples, 1.0, iso_samples, verbose=True) # Lorentzian multivariate KDE

### Optimization
solution, fitness = h.quasar(obj_func, bounds, init=ellipsoid_samples) # Evolutionary optimization
local_sol, local_fit = h.minimize(obj_func, bounds, init=solution) # Gradient-based optimization
all_expr, best_expr = h.symbolic(obj_func, bounds) # Symbolic regression
opt_features, opt_model = h.stepAIC(iso_samples, solution) # R's stepAIC for linear/logistic regression

### Analysis
Si, S2 = h.sensitivity(obj_func, bounds) # Sensitivity analysis
slice_data, stats = h.hyperslice(obj_func, bounds, slice_dims=(0,1)) # Estimate/hyperslice the solution space
signal_results = h.waveform(uniform_samples[:,0], slice_data.iloc[:,1]) # Analyze 2D waveform
h.analyze(slice_data) # Analyze any numerical dataset
```

## QUASAR Optimizer
**QUASAR** (Quasi-Adaptive Search with Asymptotic Reinitialization) is a quantum-inspired evolutionary algorithm, highly efficient for minimizing high-dimensional, non-differentiable, and non-parametric objective functions.

* Benefit: Significant improvements in convergence speed and solution quality for high-dimensional spaces compared to standard optimization algorithms like Differential Evolution and L-SHADE. (Reference: [https://arxiv.org/abs/2511.13843]).

## HDS Sampler
**HDS** (Hyperellipsoid Density Sampling) is a non-uniform Quasi-Monte Carlo sampling method, specifically designed to exploit promising regions of the parameter space.

* Benefit: Provides control over high-dimensional sample distributions. Results in higher average solution quality when initializing optimization. (Reference: [https://arxiv.org/abs/2511.07836]).
