Using AI assistants with Mergen#

Modern AI assistants are good at turning a plain description of an experiment into a starting point: a parameter space, a sensible criterion and algorithm, and a runnable script. But no assistant knows Mergen from its training, so left to itself it will guess at method names and get them wrong. The template below solves this by being self-contained: it carries Mergen’s real API and its own decision rules into the conversation. Fill in the bracketed parts and paste the whole thing into the assistant of your choice.

Treat the answer as a draft, not a verdict. An assistant cannot see your system respond; when its suggestion matters, verify it the same way this documentation recommends everywhere else: run Sampler.compare() on the shortlisted options and let the ranked table decide (see comparing designs).

The template#

You are helping me plan a space-filling Design of Experiments with
the Python package Mergen (import name `mergen`, distribution
`mergen-doe`). You do not know this package from training. Use ONLY
the API contract and the decision rules given below; do not invent
any method, argument or plot kind that is not listed here.

MY STUDY
- Goal of the experiment: [describe what you want to learn]
- Parameters and ranges: [name each setting; say whether it is a
  set of values, a continuous range (linear or log), an integer
  range, or a category]
- Total run budget: [how many experiments you can afford]
- Constraints: [combinations that are impossible or forbidden;
  regions that matter more; runs that already exist - or "none"]
- What matters most to me: [for example even coverage, good 1D/2D
  projections for a surrogate model, uniformity, or handling
  categorical settings well]

API CONTRACT (use exactly this, nothing else)
- Space:
    space = mergen.ParameterSpace({
        'name': [v1, v2, ...],                  # discrete values
        'name': ('continuous', low, high),       # linear range
        'name': ('continuous', low, high, 'log'),# log-spaced range
        'name': ('integer', low, high),
        'name': ('nominal', 'a', 'b', ...),      # unordered category
        'name': ('ordinal', 'low', 'mid', ...),  # ordered category
    })
- Sampler setup (all optional except set_design):
    sampler = mergen.Sampler(space)
    sampler.set_design(n_samples=..., n_validation=...)
    sampler.add_prescribed(points)      # keep existing runs
    sampler.load_design(points)         # resume a full design
    sampler.add_focus(region, n=...)    # extra points in a region
    sampler.add_exclusion(region)       # forbid a region
    sampler.set_optimizer('sa', ...)    # tune budget if asked
- Run and result:
    result = sampler.run(criteria='umaxpro', algorithm='sa', seed=44)
    result.summary(); result.quality_report()
    result.plot(kind, save=True)  # kinds: 'pairplot','1d','2d',
        # 'distances','correlation','quality'
    result.to_csv()
- Comparison sweep:
    comparison = sampler.compare(criteria=[...], algorithms=[...])
    comparison.summary(); comparison.plot(save=True)

MERGEN'S DECISION RULES (follow these)
- Criteria: 'umaxpro' is the default for continuous or mixed
  numeric spaces and optimises all lower-dimensional projections;
  'maxpro' is its classical predecessor; 'phi_p' approximates
  maximin distance and gives the most even point separation; 'cd2'
  and 'stratified' target uniformity in the discrepancy sense;
  'maxproqq' extends projection quality to spaces with nominal or
  ordinal parameters; 'qqd' is designed for category-heavy spaces.
  If the space has nominal or ordinal parameters, only recommend
  criteria that support them ('maxproqq', 'qqd').
- Algorithms: 'sa' (simulated annealing with restarts) is the
  robust default; 'sce' and 'ese' are alternatives worth trying in
  a compare() sweep; 'ese' does not support one-dimensional spaces.
- Sample size: about 10 runs per parameter is the accepted initial
  rule of thumb; fewer reduces quality, more helps until the budget
  runs out. Mergen also reserves a validation set by default.
- When two or more options seem plausible, do not guess: tell me to
  run Sampler.compare() on the shortlist.

WHAT TO PRODUCE
1. A ParameterSpace definition for my study, as Python code.
2. A recommended criterion and algorithm with a one-paragraph
   rationale tied to my goals, plus a suggested n_samples.
3. A complete runnable script using only the API contract above:
   ParameterSpace, Sampler, set_design, run, then
   result.summary(), result.quality_report(),
   result.plot('pairplot', save=True), result.to_csv().
4. If my constraints mention forbidden regions, prior runs or
   focus areas, use add_exclusion, add_prescribed / load_design or
   add_focus accordingly.
5. A short note on what to check in the quality report before
   trusting the design.
Ask me for any missing information before answering.

Why the template is structured this way#

The API contract exists because assistants do not know Mergen: it replaces guessing with copying. The decision-rules block hands the assistant the same guidance a careful reader would take from the criterion and algorithm pages, so its advice cannot drift away from how Mergen actually behaves. The sample-size rule it carries is the widely used ten-runs-per-parameter guideline for initial computer experiments (Loeppky, Sacks & Welch, 2009).

Reference#

Loeppky, J. L., Sacks, J., & Welch, W. J. (2009). Choosing the sample size of a computer experiment: A practical guide. Technometrics, 51(4), 366-376.