parameterrun 0.1.0__py3-none-any.whl

parameterrun/__init__.py

@@ -0,0 +1,3 @@
+from .parallel_utils import parameterrun
+
+__all__ = ["parameterrun"]

parameterrun/parallel_utils.py

@@ -0,0 +1,376 @@
+import contextlib
+import sys
+from datetime import datetime
+from itertools import product
+from time import time
+from typing import Any, Callable, List, Optional, Tuple, Union
+
+import joblib
+import numpy as np
+from joblib import Parallel, delayed
+from tqdm.auto import tqdm
+
+
+def _normalized_time(time_seg: float) -> str:
+    """
+    Normalize the time to a human-readable format
+    """
+    if time_seg < 60:
+        return f'{time_seg:.2f} s'
+    elif time_seg < 3600:
+        mins, sec = divmod(time_seg, 60)
+        return f'{int(mins)} min {sec:.2f} s'
+    else:
+        hours, time_seg = divmod(time_seg, 3600)
+        mins, sec = divmod(time_seg, 60)
+        return f'{int(hours)} h {int(mins)} min {sec:.2f} s'
+
+
+def _log(message: str, verbose: Optional[bool] = False, hostname: Optional[str] = None) -> None:
+    if verbose:
+        # Compute timestamp
+        time_stamp = datetime.now().strftime("%H:%M:%S, %d/%m/%Y")
+        msg = f'{time_stamp}: {message}'
+        if hostname is not None:
+            msg = f'[{hostname}]: {msg}'
+
+        print(msg, flush=True)
+
+
+@contextlib.contextmanager
+def tqdm_joblib(tqdm_object: tqdm):
+    """Context manager to patch joblib to report into tqdm progress bar given as argument"""
+
+    class TqdmBatchCompletionCallback(joblib.parallel.BatchCompletionCallBack):
+        def __call__(self, *args, **kwargs):
+            tqdm_object.update(n=self.batch_size)
+            return super().__call__(*args, **kwargs)
+
+    old_batch_callback = joblib.parallel.BatchCompletionCallBack
+    joblib.parallel.BatchCompletionCallBack = TqdmBatchCompletionCallback
+    try:
+        yield tqdm_object
+    finally:
+        joblib.parallel.BatchCompletionCallBack = old_batch_callback
+        tqdm_object.close()
+
+
+def _parameterrun_joblib(fun: Callable[..., Any], param_names: List[List[str]], param_values: List[List[List]],
+                         indices_iterate: list, desc, n_workers: Optional[int] = -1, pbar_bool: bool = True,
+                         leave: Optional[bool] = True, **fun_kwargs) -> Tuple[List[List], int]:
+    n_total = len(indices_iterate)
+    if n_total == 0:
+        raise ValueError('No parameter combinations generated. Please provide at least one value per group.')
+
+    if n_workers == 1:  # If only one worker, do not use joblib
+        result = []
+        pbar = tqdm(indices_iterate, desc=desc, leave=leave, disable=not pbar_bool)
+        for index in pbar:
+            result.append(fun(**{**_get_iteration(index, param_names, param_values), **fun_kwargs}))
+    else:
+        with tqdm_joblib(tqdm(indices_iterate, desc=desc, leave=leave, disable=not pbar_bool)) as _:
+            result = Parallel(n_jobs=n_workers)(
+                delayed(fun)(**{**_get_iteration(index, param_names, param_values), **fun_kwargs}) for index in
+                indices_iterate)
+
+    n_output = len(result[0]) if isinstance(result[0], tuple) else 1
+    if n_output == 1:
+        result = [(result_i,) for result_i in result]
+
+    result_temp = []
+    for i in range(n_output):
+        result_temp.append([result[j][i] for j in range(n_total)])
+
+    return result_temp, n_output
+
+
+def _parameterrun_mpi(fun: Callable[..., Any], param_names: List[List[str]], param_values: List[List[List]],
+                      groups_iterate: list, desc: str, pbar_bool: bool = True, verbose: Optional[bool] = False,
+                      leave: Optional[bool] = True, **fun_kwargs) -> Tuple[List[List], int]:  # pragma: no cover
+    from mpi4py import MPI
+
+    comm = MPI.COMM_WORLD
+    rank = comm.Get_rank()
+    size = comm.Get_size()
+
+    n_total = len(groups_iterate)
+
+    # Shuffle the indices to avoid bias in the computation
+    if rank == 0:
+        total_indices = np.arange(n_total)
+        np.random.shuffle(total_indices)
+    else:
+        total_indices = None
+
+    total_indices = comm.bcast(total_indices, root=0)
+    indices_compute = np.array_split(total_indices, size)[rank]
+
+    groups_compute = np.array(groups_iterate)[indices_compute]
+
+    pbar = tqdm(groups_compute, desc=desc, leave=leave, disable=not (pbar_bool and rank == 0), file=sys.stdout)
+
+    n_outputs = 0
+    result: List[Any] = []
+
+    if 'Open MPI v5.0.6' in MPI.Get_library_version():
+        mpi_flush = True
+    else:
+        mpi_flush = False
+
+    for index in pbar:
+        if pbar_bool and rank == 0 and mpi_flush:
+            print('\r', flush=True)  # Needed to show the progress bar in some mpi versions
+            sys.stdout.write("\033[F")  # Move the cursor up one line
+
+        result_temp = fun(**{**_get_iteration(index, param_names, param_values), **fun_kwargs})
+
+        if not isinstance(result_temp, tuple):
+            result_temp = (result_temp,)
+
+        # Check how many parameters are returned
+        if len(result) == 0:  # First iteration
+            n_outputs = len(result_temp)
+            for _ in range(n_outputs):
+                result.append([])
+
+        for i, result_temp_i in enumerate(result_temp):
+            result[i].append(result_temp_i)
+
+    _log(f'Rank {rank} finished', verbose, hostname=MPI.Get_processor_name())
+
+    # Notify root when each worker is done, and show a progress bar
+    if rank == 0:
+        progress = 0
+        pbar = tqdm(total=size - 1, desc='Waiting for workers', leave=leave, disable=not pbar_bool, file=sys.stdout)
+
+        while progress < size - 1:
+            if comm.Iprobe(source=MPI.ANY_SOURCE, tag=0):
+                if pbar_bool and mpi_flush:
+                    print('\r', flush=True)  # Needed to show the progress bar in some mpi versions
+                    sys.stdout.write("\033[F")
+
+                comm.recv(source=MPI.ANY_SOURCE, tag=0)  # Receive a signal from each worker
+                progress += 1
+                pbar.update(1)
+
+        pbar.close()
+    else:
+        comm.send(1, dest=0, tag=0)  # Notify root that the work is done
+
+    n_outputs = comm.bcast(n_outputs, root=0)
+
+    if not result:  # For workers that did not compute anything
+        result = [[] for _ in range(n_outputs)]
+
+    results_gathered = []
+    for i in range(n_outputs):
+        _log(f'Gathering results {i}', verbose and rank == 0, hostname=MPI.Get_processor_name())
+
+        result_gathered = comm.gather(result[i], root=0)
+
+        _log('Results gathered', verbose and rank == 0, hostname=MPI.Get_processor_name())
+
+        if rank == 0:
+            result_gathered = [item for sublist in result_gathered for item in sublist]  # Flatten the list
+
+            results_unshuffled = [None] * n_total
+            for j, index in enumerate(total_indices):
+                results_unshuffled[index] = result_gathered[j]
+
+            results_gathered.append(results_unshuffled)
+
+        _log('Results reshaped', verbose and rank == 0, hostname=MPI.Get_processor_name())
+
+    return results_gathered, n_outputs
+
+
+def _get_iteration(index, param_names, param_values):
+    n_groups = len(param_values)
+    n_parameters = [len(group) for group in param_values]
+
+    dic_temp = {}
+    for group_index in range(n_groups):
+        for parameter_index in range(n_parameters[group_index]):
+            dic_temp[param_names[group_index][parameter_index]] = (
+                param_values[group_index][parameter_index][index[group_index]])
+
+    return dic_temp
+
+
+def _format_input(param_names: Union[str, list], param_values: list) -> Tuple[List[List[str]], List[List[List]]]:
+    # Check the depth of the parameters
+
+    if type(param_names) is str:
+        depth = 1
+    elif type(param_names[0]) is str:
+        depth = 2
+        if type(param_values) is not list:
+            raise ValueError('The parameters values must be a list of values')
+    elif type(param_names[0][0]) is str:
+        depth = 3
+        if type(param_values[0]) is not list:
+            raise ValueError('The parameters values must be a list of values')
+    else:
+        raise ValueError('Unknown input format for the parameters names')
+
+    # Correct the input if the depth is not equal to 3
+    if depth == 1:
+        # Only one parameter is provided
+        param_names = [[param_names]]
+        param_values = [[param_values]]
+    elif depth == 2:
+        # Groups with a single parameters are provided
+        param_names = [[param_name_i] for param_name_i in param_names]
+        param_values = [[param_values_i] for param_values_i in param_values]
+
+    # Check that the number of groups of parameters is the same as the number of groups of values
+    if len(param_names) != len(param_values):
+        raise ValueError('The number of groups of parameters must be the same as the number of groups of values')
+
+    # Check that all parameters in the same group have the same length
+    for group in param_values:
+        if len(set([len(param) for param in group])) != 1:
+            raise ValueError('All parameters in the same group must have the same length')
+
+    return param_names, param_values  # type: ignore[return-value]
+
+
+def parameterrun(fun: Callable[..., Any], param_names: Union[str, List[str], List[List[str]]],
+                 param_values: Union[List, List[List], List[List[List]]], n_workers: Optional[int] = -1,
+                 pbar_bool: bool = True, verbose: Optional[bool] = False, pbar_kwargs: Optional[dict] = None,
+                 reshape: Optional[bool] = True, backend: Optional[str] = None, desc: Optional[str] = None, **kwargs) -> \
+        Union[list, np.ndarray, None]:  # noqa: E501
+    """
+    Run a function with multiple parameters in parallel. To indentify the parameters of interest, user must provide its
+    name as is written in the function definition. If more parameters should be pass to the function, they can be
+    provided as kwargs. The backend used for the parallelization is chosen automatically between joblib and mpi4py.
+    If mpi4py is used, the function must be run with mpirun -n n_workers python script.py. Finally, the result can be
+    reshaped as a (hyper)matrix if the reshape parameter is set to True, if the functions return multiple values,
+    the result is a list of arrays.
+
+    The parameters can be grouped in different ways, the possible options are:
+    - A single parameter: The function is run with a single parameter. In this case, param_names='param_name' and
+    param_values=[value1, value2, ...]
+    - Multiple parameters: The function is run with multiple parameters. In this case, param_names=['param_name1',
+    'param_name2', ...] and param_values=[[value1, value2, ...], [value1, value2, ...], ...]
+    - Multiple groups of parameters: The function is run with multiple groups of parameters, running the parameters in
+    the same group at the same time. In this case, param_names=[['param_name1', 'param_name2', ...], ['param_name1',
+    'param_name2', ...], ...] and param_values=[[[value1, value2, ...], [value1, value2, ...], ...], [[value1, value2,
+    ...], [value1, value2, ...], ...], ...]. Note that in this case, the number of values for each parameter in the same
+    group must be the same.
+
+    Parameters
+    ----------
+    fun : callable
+        Function to run in parallel.
+    param_names : str or list
+        Name of the parameters to run in parallel.
+    param_values : list
+        Values of the parameters to run in parallel.
+    n_workers : int, optional (default=-1)
+        Number of workers to use in parallel. If -1, the number of workers is the maximum number of cores available.
+    pbar_bool : bool, optional (default=True)
+        If True, show a progress bar.
+    backend : str, optional (default=None)
+        Backend to use for the parallelization. If None, the backend is chosen automatically between joblib and mpi.
+    verbose : bool, optional (default=False)
+        If True, print information about the parallelization.
+    pbar_kwargs : dict, optional (default=None)
+        Dictionary with the parameters to pass to the tqdm such as desc and leave.
+    reshape : bool, optional (default=True)
+        If True, reshape the result as a (hyper)matrix. Sometimes, due to the nature of the output, the reshape is not
+        possible, in this case, the result is not reshaped.
+    desc: str, optional (default=None)
+        Description of the progress bar. If None, the description denotes the function and parameters names.
+    kwargs :
+        Additional parameters to pass to the function.
+
+    Returns
+    -------
+    result : list or np.ndarray
+        Result of the function run in parallel. The shape of the (hyper)matrix is (n_values1, n_values2, ...,
+         n_valuesN), where n_valuesI is the number of values in the I-th group.
+    """
+
+    if pbar_kwargs is None:
+        pbar_kwargs = {}
+
+    time_start = time()
+
+    param_names, param_values = _format_input(param_names, param_values)
+
+    # Create the list of dictionaries with the parameters in a nested loop
+    n_values = [len(group[0]) for group in param_values]
+    if any(n_value == 0 for n_value in n_values):
+        raise ValueError('Parameter groups must contain at least one value.')
+
+    indices = [list(range(n_value)) for n_value in n_values]
+    indices_iterate = product(*indices)
+
+    # Choose the backed
+    if backend is not None:
+        available_backends = ['joblib', 'mpi']
+        if backend not in available_backends:
+            raise ValueError(f'Unknown backend {backend}. Available backends are {available_backends}')
+
+    size = 1
+    rank = 0
+
+    mpi_module = None
+    if backend is None or backend == 'mpi':
+        try:
+            from mpi4py import MPI
+            mpi_module = MPI
+            comm = MPI.COMM_WORLD
+            size = comm.Get_size()
+            rank = comm.Get_rank()
+        except ImportError as err:
+            if backend == 'mpi':
+                raise ImportError('backend="mpi" requires mpi4py to be installed and available.') from err
+
+        if size == 1 and backend is None:
+            backend = 'joblib'
+        else:
+            backend = 'mpi'
+
+    if desc is None:
+        param_names_pbar = [parameters_names_i for parameters_names_i in param_names]
+        desc = f'{fun.__name__}: {param_names_pbar}'
+
+        if len(desc) > 40:
+            desc = desc[:40] + '(...)'
+
+    # Execute the parallel run
+    if backend == 'joblib':
+        _log('Running under joblib', verbose)
+
+        result, n_outputs = _parameterrun_joblib(fun, param_names, param_values, list(indices_iterate), desc,
+                                                 n_workers=n_workers, pbar_bool=pbar_bool, **pbar_kwargs, **kwargs)
+
+    elif backend == 'mpi':
+        _log(f'Running under mpi with {size} workers', verbose and rank == 0,
+             hostname=mpi_module.Get_processor_name() if mpi_module is not None else None, )
+
+        result, n_outputs = _parameterrun_mpi(fun, param_names, param_values, list(indices_iterate), desc,
+                                              pbar_bool=pbar_bool, verbose=verbose, **pbar_kwargs, **kwargs)
+
+    else:
+        raise ValueError('Unknown backend')
+
+    if rank == 0:
+        # Reshape the result to get the (hyper)matrix
+        if reshape:
+            try:
+                if n_outputs == 1:
+                    result = np.array(result[0])
+                else:
+                    result = [np.array(result[i]) for i in range(n_outputs)]
+            except ValueError:
+                print('Could not reshape the result')
+
+        total_time = time() - time_start
+        _log(f'Total time: {_normalized_time(total_time)}', verbose)
+
+        return result
+    else:
+        return None

parameterrun-0.1.0.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: parameterrun
+Version: 0.1.0
+Summary: Parallel parameter sweeps with joblib/MPI and tqdm progress bars.
+Project-URL: Homepage, https://github.com/Davtax/ParameterRun
+Project-URL: Repository, https://github.com/Davtax/ParameterRun
+Project-URL: Issues, https://github.com/Davtax/ParameterRun/issues
+Project-URL: Changelog, https://github.com/Davtax/ParameterRun/blob/main/CHANGELOG.md
+Author-email: David Fernández-Fernández <david.fernandezf@hotmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: joblib,mpi,parallel,parameter-sweep,python,scientific-computing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: joblib>=1.3
+Requires-Dist: numpy>=1.23
+Requires-Dist: tqdm>=4.66
+Provides-Extra: mpi
+Requires-Dist: mpi4py>=3.1; extra == 'mpi'
+Description-Content-Type: text/markdown
+
+# ParameterRun
+
+`parameterrun` is a lightweight utility for running parameter sweeps in Python with a simple, function-based API.
+
+It is designed for scientific and numerical workflows where you want to evaluate a function over one or more parameter
+grids, optionally in parallel, while keeping progress bars and output reshaping convenient.
+
+The package supports:
+
+- single-parameter scans
+- multi-parameter scans
+- grouped parameters that must vary together
+- parallel execution with `joblib`
+- MPI execution with `mpi4py`
+- automatic reshaping of outputs into arrays
+- functions returning either one output or multiple outputs
+
+## Installation
+
+### With `pip`
+
+```bash
+pip install parameterrun
+```
+
+### With optional MPI support
+
+```bash
+pip install parameterrun[mpi]
+```
+
+## Basic idea
+
+The main entry point is:
+
+```python
+from parameterrun import parameterrun
+```
+
+The function `parameterrun(...)` evaluates a user-defined function over a set of parameter values. The parameters to
+sweep are identified by their names exactly as they appear in the target function signature. Additional fixed arguments
+can be passed as keyword arguments.
+
+## Quick start
+
+### 1. Single parameter
+
+```python
+from parameterrun import parameterrun
+
+
+def square(x):
+    return x ** 2
+
+
+result = parameterrun(square, param_names="x", param_values=[0, 1, 2, 3], n_workers=1, )
+
+print(result)  # array([0, 1, 4, 9])
+```
+
+### 2. Multiple independent parameters
+
+This creates a Cartesian product of the parameter groups.
+
+```python
+from parameterrun import parameterrun
+
+
+def f(x, y, scale=1):
+    return scale * (x + y)
+
+
+result = parameterrun(f, param_names=["x", "y"], param_values=[[1, 2, 3], [10, 20], ], scale=2, )
+
+result = result.reshape(3, 2)
+print(result.shape)  # (3, 2)
+```
+
+### 3. Grouped parameters
+
+Parameters in the same group vary together and must have the same number of values.
+
+```python
+from parameterrun import parameterrun
+
+
+def f(x, y, z):
+    return x + y + z
+
+
+result = parameterrun(f, param_names=[["x", "y"], ["z"]], param_values=[[[1, 2], [10, 20]],  # (x, y) = (1,10), (2,20)
+                                                                         [[100, 200, 300]],  # z varies independently
+                                                                         ], n_workers=1, )
+
+result = result.reshape(2, 3)
+print(result.shape)  # (2, 3)
+```
+
+This grouped-input mode is useful when some parameters are logically linked and should not be combined independently.
+
+## Multiple outputs
+
+If the target function returns a tuple, parameterrun returns a list of arrays, one per output channel.
+
+```python
+from parameterrun import parameterrun
+
+
+def stats(x):
+    return x + 1, x ** 2
+
+
+mean_like, square_like = parameterrun(stats, param_names="x", param_values=[1, 2, 3], n_workers=1, )
+
+print(mean_like)
+# array([2, 3, 4])
+
+print(square_like)  # array([1, 4, 9])
+```
+
+If the function returns a single object, the result is returned as a single array when reshaping is possible.
+
+## Parallel backend
+
+`parameterrun` supports two execution backends:
+
+- `joblib`: a simple, local parallelization library that works well for most use cases.
+- `mpi`: a distributed parallelization approach using MPI, suitable for running on clusters or supercomputers.
+
+If `backend=None`, the package tries to detect whether MPI is available. If MPI is not available, it falls back to
+`joblib`; otherwise it uses MPI.
+
+### Joblib backend
+
+```python
+result = parameterrun(my_function, param_names=["x", "y"], param_values=[[1, 2, 3], [4, 5]], backend="joblib",
+    n_workers=-1, )
+```
+
+If `n_workers=1`, the function runs serially without spawning joblib workers.
+
+### MPI backend
+
+```python
+result = parameterrun(my_function, param_names=["x", "y"], param_values=[[1, 2, 3], [4, 5]], backend="mpi", )
+```
+
+Run the script with MPI, for example:
+
+```bash
+mpirun -n 4 python my_script.py
+```
+
+Under MPI, only rank 0 returns the final result; the other ranks return `None`.
+
+## Progress bars and verbosity
+
+By default, progress bars are enabled:
+
+```python
+result = parameterrun(my_function, param_names="x", param_values=[1, 2, 3], pbar_bool=True, )
+```
+
+You can also pass extra keyword arguments to `tqdm` through `pbar_kwargs`:
+
+```python
+result = parameterrun(my_function, param_names="x", param_values=[1, 2, 3], pbar_kwargs={"leave": False}, )
+```
+
+Verbose logging can be enabled with:
+
+```python
+result = parameterrun(my_function, param_names="x", param_values=[1, 2, 3], verbose=True, )
+```
+
+The progress-bar description is generated automatically from the function name and parameter names, unless you provide
+`desc` explicitly.
+
+## API reference
+
+`parameterrun`
+
+```python
+parameterrun(fun, param_names, param_values, n_workers=-1, pbar_bool=True, verbose=False, pbar_kwargs=None,
+    reshape=True, backend=None, desc=None, **kwargs, )
+```
+
+* `fun`: function to evaluate
+* `param_names`: parameter name or grouped parameter names
+* `param_values`: values corresponding to `param_names`
+* `n_workers`: number of workers for `joblib`
+* `pbar_bool`: enable or disable progress bars
+* `verbose`: print backend and timing information
+* `pbar_kwargs`: additional keyword arguments passed to tqdm
+* `reshape`: reshape results into arrays when possible
+* `backend`: `"joblib"`, `"mpi"`, or `None`
+* `desc`: custom progress-bar label
+* `**kwargs`: extra fixed keyword arguments forwarded to `fun`
+
+## Input formats
+
+`parameterrun` accepts three input styles.
+
+### A. Single parameter
+
+```python
+param_names = "x"
+param_values = [1, 2, 3]
+```
+
+### B. Multiple independent parameters
+
+```python
+param_names = ["x", "y"]
+param_values = [[1, 2, 3], [10, 20], ]
+```
+
+### C. Multiple groups of parameters
+
+```python
+param_names = [["x", "y"], ["z"]]
+param_values = [[[1, 2], [10, 20]], [[100, 200, 300]], ]
+```
+
+## Development checks
+
+Before opening a PR or publishing a release, run:
+
+```bash
+pytest
+ruff check .
+mypy src/parameterrun
+python -m build
+python -m twine check dist/*
+```

parameterrun-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+parameterrun/__init__.py,sha256=ihShiMZY0S5PMNQP3OKDd1_3SwIRYGVb6xO96uNZ7f8,69
+parameterrun/parallel_utils.py,sha256=AztK0J5dMF-9uWM55aWWWY_U2S8ztQ-45poCf8Y0sOs,15446
+parameterrun-0.1.0.dist-info/METADATA,sha256=AfCEQ7uCgIp4O7-6BcAqu_gkj7BciC5ULw9AuSAGNO0,7356
+parameterrun-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+parameterrun-0.1.0.dist-info/licenses/LICENSE,sha256=r8q7OrtqDHayzNYdmNa6uMpzmCQCNUQ9DoNekm9vQec,1512
+parameterrun-0.1.0.dist-info/RECORD,,

parameterrun-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

parameterrun-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, David Fernandez Fernandez
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.