expsweep - Numerical Experiment Sweeper

Runs Monte Carlo experiments on a function with swept-parameters and collects results into a table.

Features

• automatically parallelizes experiment and displays a progress bar
• results are returned as a Pandas table which can be easily plotted in seaborn

Quickstart

pip install expsweep

Basic Example - two simultaneous experiments with a single variable sweep

import expsweep

# Function to run Monte Carlo experiment on.
# Should return a dictionary containing experiment results.
def exp(x):
    return {
        'experiment1': np.random.normal(loc=x, scale=x),
        'experiment2': np.random.normal(loc=3 * x, scale=x)
    }
    

# Run Monte Carlo experiment on exp() function.
# Sweep parameter x (with 20 repetitions for each x) and collect results.
mc = expsweep.experiment(
    exp,
    repeat=20,
    x=range(10),
)

"""
>>> mc
     x  experiment1  experiment2
0    0     0.000000     0.000000
1    0     0.000000     0.000000
2    0     0.000000     0.000000
..  ..          ...          ...
197  9    14.120838    27.557313
198  9    11.443396    21.961869
199  9    14.120838    27.557313
"""

Plotting with Seaborn

# Seaborn expects data from both experiments to be in one column.
# Use `merge=True` to merge experiment columns together for Seaborn.
mc = expsweep.experiment(
    exp,
    repeat=20,
    x=range(10),
    merge=True
)

"""
>>> mc
     x   experiment     result
0    0  experiment1   0.000000
1    0  experiment1   0.000000
2    0  experiment1   0.000000
..  ..          ...        ...
397  9  experiment2  17.528782
398  9  experiment2  17.528782
399  9  experiment2  27.557313
"""

import seaborn as sns
sns.lineplot(
    data=mc,
    x='x',
    y='result',
    hue='experiment',
    style='experiment',
)

Multiple Parameters and Fixed Parameters

More parameters can be swept combinatorially by simply providing more arguments:

def exp(x, y, z):
    ...
    return {'experiment1': ...}
    
# sweep 2 variables (and 1 fixed) with a single repetition at each point
mc = expsweep.experiment(
    exp,
    x=range(10),
    y=range(10),
    z=[1]
)

>>> mc
     x  y  z  experiment1
0    0  0  1     0.000000
1    1  0  1     0.000000
2    2  0  1     0.000000
..  ..  .             ...
97   7  9  1    17.528782
98   8  9  1    17.528782
99   9  9  1    27.557313
"""

Other Arguments

def experiment(...)

• func (function) - function to run Monte Carlo simulation on
• disable_print (boolean) - whether to show progress bars. (default False)
• repeat (int) - number of repetitions for each parameter combination. (default 1)
• merge (bool) - merge all experiment results into single data column ("results") and create new categorical column ("experiment"). (default False)
• cpu_count (int) - number of jobs to create. If None, use all available cpus. (default None)
• backend (str) - use pqdms "processes" backend or "threads" backend (more info). (default "processes")
• pqdm_kwargs (dict) - arguments to pass to pqdm (default None)

Troubleshooting

AttributeError: Can't pickle local object ...

Define the variable in question as a global or switch the backend to 'threads'.