Metadata-Version: 2.4
Name: mergen-doe
Version: 0.1.0
Summary: Space-filling Design of Experiments for Python
Project-URL: Homepage, https://github.com/acanbay/mergen
Project-URL: Issues, https://github.com/acanbay/mergen/issues
Author-email: Ali Can Canbay <acanbay@ankara.edu.tr>
License: MIT
License-File: LICENSE
Keywords: Latin hypercube,computer experiments,design of experiments,experimental design,optimization,sampling,space-filling,surrogate modeling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Requires-Dist: jinja2>=3.0
Requires-Dist: joblib>=1.2
Requires-Dist: matplotlib>=3.6
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.10
Requires-Dist: tabulate>=0.9
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-nb>=1.1; extra == 'docs'
Requires-Dist: openpyxl>=3.1; extra == 'docs'
Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-design>=0.5; extra == 'docs'
Requires-Dist: sphinx-gallery<0.22,>=0.15; extra == 'docs'
Requires-Dist: sphinx>=7.3; extra == 'docs'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/_static/logo-dark.png">
    <img src="docs/_static/logo-light.png" alt="Mergen" width="420">
  </picture>
</p>

<p align="center"><b>M</b>ulti-dimensional <b>E</b>xperimental <b>R</b>un <b>GEN</b>erator:
space-filling Design of Experiments for Python.</p>

<p align="center">
  <a href="https://github.com/acanbay/mergen/actions/workflows/tests.yaml"><img src="https://github.com/acanbay/mergen/actions/workflows/tests.yaml/badge.svg" alt="Tests"></a>
  <a href="https://www.python.org"><img src="https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue" alt="Python"></a>
  <a href="https://mergen.readthedocs.io"><img src="https://readthedocs.org/projects/mergen/badge/?version=latest" alt="Documentation"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
</p>

---

## What is Mergen?

Every experimental study works under a fixed budget: only a limited
number of runs can be afforded, and each one should be as informative
as possible. Mergen selects those runs. Given a parameter space (its
bounds, resolution, constraints and critical regions), it computes
the coordinates of *n* points that spread evenly through the space,
so that no region is left unexplored and no run is wasted.

The result is not a random sample but a mathematically optimised
design, delivered together with a statistical quality report suitable
for the methods section of a paper. Mergen handles the spaces real
studies actually have: mixed factor types, forbidden regions, runs
that already exist, and zones that deserve extra attention.

## Features

- **Factor types:** discrete, continuous (linear or log), integer,
  nominal and ordinal, freely mixed in one space, with feasibility
  constraints.
- **Design control:** prescribed points, focus regions, exclusion
  zones, named extra sets, and resuming from an existing design.
- **Optimisation:** seven space-filling criteria (including recent
  developments such as uMaxPro and the stratified L2-discrepancy)
  and three optimisers over a discrete-grid Latin-hypercube
  structure, with a `compare()` sweep for when you are unsure.
- **Evidence and export:** a Monte Carlo quality report, eight plot
  types, and CSV, JSON, Markdown, LaTeX, HTML and Excel export.
- **Sequential workflows:** extend, subsample, reorder and nest
  designs as a campaign grows.

## Installation

```bash
git clone https://github.com/acanbay/mergen.git
cd mergen
pip install .
```

The distribution name is `mergen-doe`; the import name is `mergen`.
Requires Python 3.9 or newer; the core dependencies (NumPy, SciPy,
pandas, matplotlib) are installed automatically.

## Quick start

```python
from mergen import ParameterSpace, Sampler

space = ParameterSpace({
    'temperature': range(100, 500, 10),        # discrete
    'pressure':    ('continuous', 0.5, 5.0),   # continuous grid
    'n_layers':    ('integer', 2, 10),         # integer grid
})

sampler = Sampler(space)
sampler.set_design(n_samples=30)
result = sampler.run()

result.summary()
result.quality_report()
result.plot('pairplot', save=True)
result.to_csv()
```

## Documentation

The full documentation lives at
**[mergen.readthedocs.io](https://mergen.readthedocs.io)**. It covers
tutorials, task guides, the reasoning behind every choice Mergen asks
you to make, an executed gallery of fifteen example studies with
their complete output and figures, and the full API reference.

To build the documentation locally (for instance when contributing):

```bash
pip install -e ".[docs]"
sphinx-build -b html docs docs/_build/html
```

then open `docs/_build/html/index.html`.

## Examples

Fifteen complete, runnable studies from different domains live in
[`examples/`](examples/), from a five-line quickstart to CFD,
wet-lab and particle-physics campaigns.

## Citing

If you use Mergen in academic work, please cite it using the
information in [`CITATION.cff`](CITATION.cff); GitHub renders it
under the "Cite this repository" button.

## License

MIT © Ali Can Canbay
