parismc 0.1.0__tar.gz

parismc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Miaoxin Liu, Alvin J. K. Chua
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parismc-0.1.0/MANIFEST.in

@@ -0,0 +1,38 @@
+# Include the README
+include README.md
+
+# Include the license
+include LICENSE
+
+# Include requirements
+include requirements.txt
+
+# Include all example files
+recursive-include examples *.py
+recursive-include examples *.md
+
+# Include any data files if you have them
+# recursive-include parismc/data *
+
+# Exclude unnecessary files
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * *.so
+recursive-exclude * .DS_Store
+exclude .gitignore
+exclude .git
+recursive-exclude .git *
+
+# Include any additional documentation
+include *.rst
+include *.txt
+include *.md
+
+# Include setup files
+include setup.py
+include setup.cfg
+
+# Exclude build artifacts
+prune build
+prune dist
+prune *.egg-info

parismc-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: parismc
+Version: 0.1.0
+Summary: PARIS: Parallel Adaptive Reweighting Importance Sampling for high-dimensional multi-modal Bayesian inference
+Home-page: https://github.com/mx-Liu123/parismc
+Author: Alvin J. K. Chua
+Author-email: Miaoxin Liu <mx.liu123@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mx-Liu123/parismc
+Project-URL: Repository, https://github.com/mx-Liu123/parismc
+Project-URL: Documentation, https://github.com/mx-Liu123/parismc/blob/main/README.md
+Project-URL: Bug Reports, https://github.com/mx-Liu123/parismc/issues
+Keywords: monte carlo,bayesian inference,importance sampling,multimodal,adaptive sampling,MCMC
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: License :: OSI Approved :: MIT License
+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: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: smt>=2.0.0
+Requires-Dist: tqdm>=4.62.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Provides-Extra: plotting
+Requires-Dist: matplotlib>=3.5.0; extra == "plotting"
+Requires-Dist: seaborn>=0.11.0; extra == "plotting"
+Provides-Extra: notebook
+Requires-Dist: jupyter>=1.0.0; extra == "notebook"
+Requires-Dist: ipython>=7.0.0; extra == "notebook"
+Provides-Extra: full
+Requires-Dist: matplotlib>=3.5.0; extra == "full"
+Requires-Dist: seaborn>=0.11.0; extra == "full"
+Requires-Dist: jupyter>=1.0.0; extra == "full"
+Requires-Dist: ipython>=7.0.0; extra == "full"
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# PARIS Monte Carlo Sampler
+
+**An efficient adaptive importance sampler for high-dimensional multi-modal Bayesian inference.**
+
+PARIS (**Parallel Adaptive Reweighting Importance Sampling**) combines global exploration with local adaptation to tackle complex posteriors. The workflow is simple:
+
+1. **Global Initialization**: Start with a space-filling design (e.g. Latin Hypercube Sampling) to seed promising regions.
+2. **Adaptive Proposals**: Each seed runs its own importance sampling process, where the proposal is a Gaussian mixture centered on past weighted samples with covariance estimated from the local sample set.
+3. **Dynamic Reweighting**: All samples are reweighted against the evolving proposal mixture, ensuring unbiased estimates and self-correcting any early overweights.
+4. **Mode Clustering**: Parallel processes that converge to the same region are merged to avoid redundancy, while distinct modes are preserved.
+5. **Posterior & Evidence**: The collected weighted samples directly reconstruct the posterior and yield accurate Bayesian evidence estimates.
+
+This adaptive–parallel design allows PARIS to efficiently discover, refine, and integrate over complex multi-modal landscapes with minimal tuning and far fewer likelihood calls than conventional approaches.
+
+## Features
+
+* **Adaptive Proposals per Seed** – Each process maintains its own proposal, evolving a local Gaussian mixture that adapts to past samples.
+* **Auto-balanced Exploration** – High-weight discoveries automatically attract more samples, while overweights self-correct over time.
+* **Accurate Evidence Estimation** – Bayesian evidence is computed directly from importance weights, no extra machinery needed.
+* **Parallel Mode Discovery** – Multiple seeds explore independently, merging only when they converge to the same mode.
+* **Intuitive Hyperparameters** – Settings like number of seeds, initial covariance, and merge thresholds map directly to prior knowledge.
+* **Efficiency at Scale** – Handles high-dimensional, multi-modal targets with substantially fewer likelihood calls.
+* **Boundary-safe** – Automatically respects \[0,1]^d priors.
+* **Multiprocessing Ready** – Runs smoothly across CPU cores for large inference tasks.
+
+## Installation
+
+### From PyPI (when available)
+```bash
+pip install parismc
+```
+
+### From Source
+```bash
+git clone https://github.com/yourusername/parismc.git
+cd parismc
+pip install -e .
+```
+
+### Development Installation
+```bash
+git clone https://github.com/yourusername/parismc.git
+cd parismc
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from parismc import Sampler, SamplerConfig
+
+# Define your log-likelihood function
+def log_likelihood(x):
+    """Example: multivariate Gaussian log-likelihood"""
+    return -0.5 * np.sum(x**2, axis=1)
+
+# Create sampler configuration
+config = SamplerConfig(
+    alpha=1000,
+    latest_prob_index=1000,
+    boundary_limiting=True,
+    use_pool=False  # Set to True for multiprocessing
+)
+
+# Initialize sampler
+ndim = 2
+n_walkers = 5
+init_cov_list = [np.eye(ndim) * 0.1] * n_walkers
+
+sampler = Sampler(
+    ndim=ndim,
+    n_seed=n_walkers,
+    log_reward_func=log_likelihood,
+    init_cov_list=init_cov_list,
+    config=config
+)
+
+# Prepare initial samples
+sampler.prepare_lhs_samples(lhs_num=1000, batch_size=100)
+
+# Run sampling
+sampler.run_sampling(num_iterations=500, savepath='./results')
+
+# Get results
+samples, weights = sampler.get_samples_with_weights(flatten=True)
+```
+
+## Advanced Usage
+
+### Custom Prior Transform
+
+```python
+def uniform_to_normal(x):
+    """Transform from [0,1]^d to unbounded space"""
+    from scipy.stats import norm
+    return norm.ppf(x)
+
+sampler = Sampler(
+    ndim=ndim,
+    n_seed=n_walkers,
+    log_reward_func=log_likelihood,
+    init_cov_list=init_cov_list,
+    prior_transform=uniform_to_normal
+)
+```
+
+### Configuration Options
+
+```python
+config = SamplerConfig(
+    proc_merge_prob=0.9,        # Probability threshold for merging clusters
+    alpha=1000,                 # Importance sampling parameter
+    latest_prob_index=1000,     # Number of recent samples for weighting
+    trail_size=1000,           # Maximum trial samples per iteration
+    boundary_limiting=True,     # Enable boundary constraint handling
+    use_beta=True,             # Use beta correction for boundaries
+    integral_num=100000,       # Monte Carlo samples for beta estimation
+    gamma=100,                 # Covariance update frequency
+    use_pool=True,             # Enable multiprocessing
+    n_pool=4                   # Number of processes
+)
+```
+
+## API Reference
+
+### Main Classes
+
+- `Sampler`: Main sampling class
+- `SamplerConfig`: Configuration dataclass
+
+### Key Methods
+
+- `prepare_lhs_samples()`: Initialize with Latin Hypercube Sampling
+- `run_sampling()`: Execute the sampling process
+- `get_samples_with_weights()`: Retrieve samples and importance weights
+- `save_state()` / `load_state()`: State persistence
+
+### Utility Functions
+
+- `find_sigma_level()`: Compute confidence level thresholds
+- `oracle_approximating_shrinkage()`: Covariance regularization
+- Various weighting and clustering utilities
+
+## Requirements
+
+- Python >= 3.8
+- NumPy >= 1.20.0
+- SciPy >= 1.7.0
+- scikit-learn >= 1.0.0
+- smt >= 2.0.0
+- tqdm >= 4.62.0
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit pull requests or open issues.
+
+## Citation
+
+If you use this software in your research, please cite:
+
+```bibtex
+@software{parismc,
+  title={Parallel Adaptive Reweighting Importance Sampling (PARIS)},
+  author={Miaoxin Liu, Alvin J. K. Chua},
+  year={2025},
+  url={https://github.com/mx-Liu123/parismc}
+}
+
+```
+
+
+

parismc-0.1.0/README.md

@@ -0,0 +1,177 @@
+# PARIS Monte Carlo Sampler
+
+**An efficient adaptive importance sampler for high-dimensional multi-modal Bayesian inference.**
+
+PARIS (**Parallel Adaptive Reweighting Importance Sampling**) combines global exploration with local adaptation to tackle complex posteriors. The workflow is simple:
+
+1. **Global Initialization**: Start with a space-filling design (e.g. Latin Hypercube Sampling) to seed promising regions.
+2. **Adaptive Proposals**: Each seed runs its own importance sampling process, where the proposal is a Gaussian mixture centered on past weighted samples with covariance estimated from the local sample set.
+3. **Dynamic Reweighting**: All samples are reweighted against the evolving proposal mixture, ensuring unbiased estimates and self-correcting any early overweights.
+4. **Mode Clustering**: Parallel processes that converge to the same region are merged to avoid redundancy, while distinct modes are preserved.
+5. **Posterior & Evidence**: The collected weighted samples directly reconstruct the posterior and yield accurate Bayesian evidence estimates.
+
+This adaptive–parallel design allows PARIS to efficiently discover, refine, and integrate over complex multi-modal landscapes with minimal tuning and far fewer likelihood calls than conventional approaches.
+
+## Features
+
+* **Adaptive Proposals per Seed** – Each process maintains its own proposal, evolving a local Gaussian mixture that adapts to past samples.
+* **Auto-balanced Exploration** – High-weight discoveries automatically attract more samples, while overweights self-correct over time.
+* **Accurate Evidence Estimation** – Bayesian evidence is computed directly from importance weights, no extra machinery needed.
+* **Parallel Mode Discovery** – Multiple seeds explore independently, merging only when they converge to the same mode.
+* **Intuitive Hyperparameters** – Settings like number of seeds, initial covariance, and merge thresholds map directly to prior knowledge.
+* **Efficiency at Scale** – Handles high-dimensional, multi-modal targets with substantially fewer likelihood calls.
+* **Boundary-safe** – Automatically respects \[0,1]^d priors.
+* **Multiprocessing Ready** – Runs smoothly across CPU cores for large inference tasks.
+
+## Installation
+
+### From PyPI (when available)
+```bash
+pip install parismc
+```
+
+### From Source
+```bash
+git clone https://github.com/yourusername/parismc.git
+cd parismc
+pip install -e .
+```
+
+### Development Installation
+```bash
+git clone https://github.com/yourusername/parismc.git
+cd parismc
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from parismc import Sampler, SamplerConfig
+
+# Define your log-likelihood function
+def log_likelihood(x):
+    """Example: multivariate Gaussian log-likelihood"""
+    return -0.5 * np.sum(x**2, axis=1)
+
+# Create sampler configuration
+config = SamplerConfig(
+    alpha=1000,
+    latest_prob_index=1000,
+    boundary_limiting=True,
+    use_pool=False  # Set to True for multiprocessing
+)
+
+# Initialize sampler
+ndim = 2
+n_walkers = 5
+init_cov_list = [np.eye(ndim) * 0.1] * n_walkers
+
+sampler = Sampler(
+    ndim=ndim,
+    n_seed=n_walkers,
+    log_reward_func=log_likelihood,
+    init_cov_list=init_cov_list,
+    config=config
+)
+
+# Prepare initial samples
+sampler.prepare_lhs_samples(lhs_num=1000, batch_size=100)
+
+# Run sampling
+sampler.run_sampling(num_iterations=500, savepath='./results')
+
+# Get results
+samples, weights = sampler.get_samples_with_weights(flatten=True)
+```
+
+## Advanced Usage
+
+### Custom Prior Transform
+
+```python
+def uniform_to_normal(x):
+    """Transform from [0,1]^d to unbounded space"""
+    from scipy.stats import norm
+    return norm.ppf(x)
+
+sampler = Sampler(
+    ndim=ndim,
+    n_seed=n_walkers,
+    log_reward_func=log_likelihood,
+    init_cov_list=init_cov_list,
+    prior_transform=uniform_to_normal
+)
+```
+
+### Configuration Options
+
+```python
+config = SamplerConfig(
+    proc_merge_prob=0.9,        # Probability threshold for merging clusters
+    alpha=1000,                 # Importance sampling parameter
+    latest_prob_index=1000,     # Number of recent samples for weighting
+    trail_size=1000,           # Maximum trial samples per iteration
+    boundary_limiting=True,     # Enable boundary constraint handling
+    use_beta=True,             # Use beta correction for boundaries
+    integral_num=100000,       # Monte Carlo samples for beta estimation
+    gamma=100,                 # Covariance update frequency
+    use_pool=True,             # Enable multiprocessing
+    n_pool=4                   # Number of processes
+)
+```
+
+## API Reference
+
+### Main Classes
+
+- `Sampler`: Main sampling class
+- `SamplerConfig`: Configuration dataclass
+
+### Key Methods
+
+- `prepare_lhs_samples()`: Initialize with Latin Hypercube Sampling
+- `run_sampling()`: Execute the sampling process
+- `get_samples_with_weights()`: Retrieve samples and importance weights
+- `save_state()` / `load_state()`: State persistence
+
+### Utility Functions
+
+- `find_sigma_level()`: Compute confidence level thresholds
+- `oracle_approximating_shrinkage()`: Covariance regularization
+- Various weighting and clustering utilities
+
+## Requirements
+
+- Python >= 3.8
+- NumPy >= 1.20.0
+- SciPy >= 1.7.0
+- scikit-learn >= 1.0.0
+- smt >= 2.0.0
+- tqdm >= 4.62.0
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit pull requests or open issues.
+
+## Citation
+
+If you use this software in your research, please cite:
+
+```bibtex
+@software{parismc,
+  title={Parallel Adaptive Reweighting Importance Sampling (PARIS)},
+  author={Miaoxin Liu, Alvin J. K. Chua},
+  year={2025},
+  url={https://github.com/mx-Liu123/parismc}
+}
+
+```
+
+
+

parismc-0.1.0/examples/basic_example.py

@@ -0,0 +1,141 @@
+"""
+Basic example of using the Paris Monte Carlo Sampler.
+
+This example demonstrates:
+1. Setting up a simple multivariate Gaussian target distribution
+2. Configuring the sampler with minimal parameters
+3. Running a short sampling process
+4. Analyzing basic results
+"""
+
+import numpy as np
+from parismc import Sampler, SamplerConfig
+
+# Define target distribution parameters at module level
+TRUE_MEAN = np.array([0.3, 0.7])
+TRUE_COV = np.array([[0.01, 0.005], [0.005, 0.02]])
+INV_COV = np.linalg.inv(TRUE_COV)
+
+def log_likelihood(x):
+    """
+    Log-likelihood for multivariate Gaussian in [0,1]^2 space.
+    
+    Parameters:
+    ----------
+    x : array-like, shape (n_samples, 2)
+        Sample points in [0,1]^2
+        
+    Returns:
+    -------
+    array-like, shape (n_samples,)
+        Log-likelihood values
+    """
+    if x.ndim == 1:
+        x = x.reshape(1, -1)
+    
+    # Compute Mahalanobis distance
+    diff = x - TRUE_MEAN
+    mahal_dist = np.einsum('ij,jk,ik->i', diff, INV_COV, diff)
+    
+    # Return log-likelihood (without normalization constant)
+    return -0.5 * mahal_dist
+
+def main():
+    
+    # Configure sampler with minimal settings
+    config = SamplerConfig()  # Use all default values
+    
+    # Initialize sampler
+    ndim = 2
+    n_walkers = 3
+    init_cov_list = [np.eye(ndim) * 0.05] * n_walkers
+    
+    print("Initializing sampler...")
+    sampler = Sampler(
+        ndim=ndim,
+        n_seed=n_walkers,
+        log_reward_func=log_likelihood,
+        init_cov_list=init_cov_list
+        # No prior_transform needed for this simple example
+    )
+    
+    # Prepare initial LHS samples
+    print("Preparing LHS samples...")
+    sampler.prepare_lhs_samples(lhs_num=1000, batch_size=100)
+    
+    # Run sampling
+    print("Running sampling...")
+    sampler.run_sampling(num_iterations=100, savepath='./basic_results', print_iter=20)
+    
+    # Get results
+    print("Extracting results...")
+    samples, weights = sampler.get_samples_with_weights(flatten=True)
+    
+    # Basic analysis
+    print(f"\nResults Summary:")
+    print(f"Total samples: {len(samples)}")
+    print(f"Effective sample size: {1/np.sum(weights**2):.1f}")
+    
+    # Weighted statistics
+    weighted_mean = np.average(samples, weights=weights, axis=0)
+    weighted_cov = np.cov(samples.T, aweights=weights)
+    
+    print(f"\nTrue mean: {TRUE_MEAN}")
+    print(f"Estimated mean: {weighted_mean}")
+    print(f"Mean error: {np.linalg.norm(weighted_mean - TRUE_MEAN):.6f}")
+    
+    print(f"\nTrue covariance diagonal: {np.diag(TRUE_COV)}")
+    print(f"Estimated covariance diagonal: {np.diag(weighted_cov)}")
+    
+    # Optional plotting
+    try:
+        import matplotlib.pyplot as plt
+        
+        plt.figure(figsize=(10, 4))
+        
+        # Plot 1: Sample scatter plot
+        plt.subplot(1, 2, 1)
+        # Color samples by their weights
+        scatter = plt.scatter(samples[:, 0], samples[:, 1], 
+                            c=weights, s=30, alpha=0.7, cmap='viridis')
+        plt.colorbar(scatter, label='Sample Weight')
+        plt.scatter(TRUE_MEAN[0], TRUE_MEAN[1], color='red', s=100, 
+                   marker='x', label='True mean', linewidth=3)
+        plt.scatter(weighted_mean[0], weighted_mean[1], color='orange', s=100, 
+                   marker='+', label='Estimated mean', linewidth=3)
+        plt.xlim(0, 1)
+        plt.ylim(0, 1)
+        plt.xlabel('X1')
+        plt.ylabel('X2')
+        plt.title('Weighted Samples')
+        plt.legend()
+        plt.grid(True, alpha=0.3)
+        
+        # Plot 2: Weight distribution
+        plt.subplot(1, 2, 2)
+        plt.hist(weights, bins=30, alpha=0.7, density=True, edgecolor='black')
+        plt.xlabel('Weight')
+        plt.ylabel('Density')
+        plt.title('Weight Distribution')
+        plt.grid(True, alpha=0.3)
+        
+        plt.tight_layout()
+        plt.savefig('basic_results/sampling_results.png', dpi=150, bbox_inches='tight')
+        print(f"\nPlot saved to: basic_results/sampling_results.png")
+        
+        # Show plot if in interactive environment
+        try:
+            plt.show()
+        except:
+            pass
+        
+    except ImportError:
+        print("\nMatplotlib not available. Skipping plots.")
+    except Exception as e:
+        print(f"\nPlotting failed: {e}")
+    
+    print("\nBasic example completed successfully!")
+    print("For more complex examples, see multimodal_example.py")
+
+if __name__ == "__main__":
+    main()