run

run

Utilities for running in parallel

Classes

Name	Description
MultiSim	Class for running multiple copies of a simulation.

MultiSim

run.MultiSim(
    self,
    sims=None,
    base_sim=None,
    label=None,
    n_runs=4,
    initialize=False,
    inplace=True,
    debug=False,
    **kwargs,
)

Class for running multiple copies of a simulation.

Parameters

Name	Type	Description	Default
sims	Sim / list	a single sim or a list of sims	None
base_sim	Sim	the sim used for shared properties; if not supplied, the first of the sims provided	None
label	str	the name of the multisim	None
n_runs	int	if a single sim is provided, the number of replicates (default 4)	4
initialize	bool	whether or not to initialize the sims (otherwise, initialize them during run)	False
inplace	bool	whether to modify the sims in-place (default True); else return new sims	True
debug	bool	if True, run in serial	False
kwargs	dict	stored in run_args and passed to run()	{}

Methods

Name	Description
brief	A single-line display of the MultiSim; same as print(multisim)
disp	Display the full object
init_sims	Initialize the sims
mean	Alias for reduce(use_mean=True). See reduce() for full description.
median	Alias for reduce(use_mean=False). See reduce() for full description.
plot	Plot all results in the MultiSim object.
reduce	Combine multiple sims into a single sim statistically: by default, use
reset	Undo reduce() by resetting the base sim, which, and results
run	Run the sims; see ss.multi_run() for additional arguments
show	Print a moderate length summary of the MultiSim. See also multisim.disp()
shrink	Not to be confused with reduce(), this shrinks each sim in the msim;
summarize	Summarize the simulations statistically.

brief

run.MultiSim.brief()

A single-line display of the MultiSim; same as print(multisim)

disp

run.MultiSim.disp()

Display the full object

init_sims

run.MultiSim.init_sims(**kwargs)

Initialize the sims

mean

run.MultiSim.mean(bounds=None, **kwargs)

Alias for reduce(use_mean=True). See reduce() for full description.

Parameters

Name	Type	Description	Default
bounds	float	multiplier on the standard deviation for the upper and lower bounds (default, 2)	None
kwargs	dict	passed to reduce()	{}

median

run.MultiSim.median(quantiles=None, **kwargs)

Alias for reduce(use_mean=False). See reduce() for full description.

Parameters

Name	Type	Description	Default
quantiles	list or dict	upper and lower quantiles (default, 0.1 and 0.9)	None
kwargs	dict	passed to reduce()	{}

plot

run.MultiSim.plot(key=None, fig=None, legend=True, **kwargs)

Plot all results in the MultiSim object.

If the MultiSim object has been reduced (i.e. mean or median), then plot the best value and uncertainty bound. Otherwise, plot individual sims.

Parameters

Name	Type	Description	Default
key	str	the results key to plot (by default, all)	None
fig	Figure	if provided, plot results into an existing figure	None
fig_kw	dict	passed to sc.getrowscols(), then plt.subplots() and plt.figure()	required
plot_kw	dict	passed to plt.plot()	required
data_kw	dict	passed to plt.scatter(), for plotting the data	required
style_kw	dict	passed to sc.options.with_style(), for controlling the detailed plotting style	required
fill_kw	dict	passed to plt.fill_between()	required
legend_kw	dict	passed to plt.legend()	required
legend	bool	whether to show the legend	True
**kwargs	dict	known arguments (e.g. figsize, font) split between the above dicts; see ss.plot_args() for all valid options	{}

reduce

run.MultiSim.reduce(quantiles=None, use_mean=False, bounds=None, output=False)

Combine multiple sims into a single sim statistically: by default, use the median value and the 10th and 90th percentiles for the lower and upper bounds. If use_mean=True, then use the mean and ±2 standard deviations for lower and upper bounds.

Parameters

Name	Type	Description	Default
quantiles	dict	the quantiles to use, e.g. [0.1, 0.9] or {‘low : ’0.1, ’high’ : 0.9}	None
use_mean	bool	whether to use the mean instead of the median	False
bounds	float	if use_mean=True, the multiplier on the standard deviation for upper and lower bounds (default 2)	None
output	bool	whether to return the “reduced” sim (in any case, modify the multisim in-place)	False

Example:

msim = ss.MultiSim(ss.Sim())
msim.run()
msim.reduce()
msim.summarize()

reset

run.MultiSim.reset()

Undo reduce() by resetting the base sim, which, and results

run

run.MultiSim.run(**kwargs)

Run the sims; see ss.multi_run() for additional arguments

Parameters

Name	Type	Description	Default
n_runs	int	how many replicates of each sim to run (if a list of sims is not provided)	required
inplace	bool	whether to modify the sims in place (otherwise return copies)	required
kwargs	dict	passed to multi_run(); use run_args to pass arguments to sim.run()	{}

Returns

Name	Type	Description
		None (modifies MultiSim object in place)

show

run.MultiSim.show(output=False)

Print a moderate length summary of the MultiSim. See also multisim.disp() (detailed output) and multisim.brief() (short output).

Parameters

Name	Type	Description	Default
output	bool	if true, return a string instead of printing output	False

Example:

msim = ss.MultiSim(ss.demo(run=False), label='Example multisim')
msim.run()
msim.show() # Prints moderate length output

shrink

run.MultiSim.shrink(**kwargs)

Not to be confused with reduce(), this shrinks each sim in the msim; see sim.shrink() for more information.

Parameters

Name	Type	Description	Default
kwargs	dict	passed to sim.shrink() for each sim	{}

summarize

run.MultiSim.summarize(method='mean', quantiles=None, how='default')

Summarize the simulations statistically.

Parameters

Name	Type	Description	Default
method	str	one of ‘mean’ (default: [mean, 2*std]), ‘median’ ([median, min, max]), or ‘all’ (all results)	'mean'
quantiles	dict	if method=‘median’, use these quantiles	None
how	str	passed to sim.summarize()	'default'

Functions

Name	Description
multi_run	For running multiple sims in parallel. If the first argument is a list of sims
parallel	A shortcut to ss.MultiSim(), allowing the quick running of multiple simulations
single_run	Convenience function to perform a single simulation run. Mostly used for

multi_run

run.multi_run(
    sim,
    n_runs=4,
    reseed=None,
    iterpars=None,
    shrink=None,
    run_args=None,
    sim_args=None,
    par_args=None,
    do_run=True,
    parallel=True,
    n_cpus=None,
    verbose=None,
    **kwargs,
)

For running multiple sims in parallel. If the first argument is a list of sims rather than a single sim, exactly these will be run and most other arguments will be ignored.

Note: n_cpus=1 is not the same thing as setting parallel=False. The former still uses the parallelization methods (just on a single core), while the latter simply runs in a loop.

Parameters

Name	Type	Description	Default
sim	(Sim/list	the sim instance to be run, or a list of sims.	required
n_runs	(int)	the number of parallel runs	4
reseed	(bool)	whether or not to generate a fresh seed for each run (default: true for single, false for list of sims)	None
iterpars	(dict)	any other parameters to iterate over the runs; see sc.parallelize() for syntax	None
shrink	(bool)	whether to shrink the sim after the sim run	None
run_args	(dict)	arguments passed to sim.run()	None
sim_args	(dict)	extra parameters to pass to the sim	None
par_args	(dict)	arguments passed to sc.parallelize()	None
do_run	(bool)	whether to actually run the sim (if not, just initialize it)	True
parallel	(bool)	whether to run in parallel using multiprocessing (else, just run in a loop)	True
n_cpus	(int)	the number of CPUs to run on (if blank, set automatically; otherwise, passed to par_args, and use all cores)	None
verbose	(int)	detail to print	None
kwargs	(dict)	also passed to the sim	{}

Returns

Name	Type	Description
		If combine is True, a single sim object with the combined results from each sim.
		Otherwise, a list of sim objects (default).

Example:

import starsim as ss
sim = ss.Sim()
sims = ss.multi_run(sim, n_runs=6)

parallel

run.parallel(*args, **kwargs)

A shortcut to ss.MultiSim(), allowing the quick running of multiple simulations at once.

Parameters

Name	Type	Description	Default
args	list	The simulations to run	()
kwargs	dict	passed to multi_run()	{}

Returns

Name	Type	Description
		A run MultiSim object.

Examples:

s1 = ss.Sim(n_agents=1000, label='Small', diseases='sis', networks='random')
s2 = ss.Sim(n_agents=2000, label='Large', diseases='sis', networks='random')
ss.parallel(s1, s2).plot()
msim = ss.parallel([s1, s2], shrink=False)

single_run

run.single_run(
    sim,
    ind=0,
    reseed=True,
    shrink=True,
    run_args=None,
    sim_args=None,
    verbose=None,
    do_run=True,
    **kwargs,
)

Convenience function to perform a single simulation run. Mostly used for parallelization, but can also be used directly.

Parameters

Name	Type	Description	Default
sim	(Sim)	the sim instance to be run	required
ind	(int)	the index of this sim	0
reseed	(bool)	whether to generate a fresh seed for each run	True
noise	(float)	the amount of noise to add to each run	required
noisepar	(str)	the name of the parameter to add noise to	required
shrink	(bool)	whether to shrink the sim after the sim run	True
run_args	(dict)	arguments passed to sim.run()	None
sim_args	(dict)	extra parameters to pass to the sim, e.g. ‘n_infected’	None
verbose	(int)	detail to print	None
do_run	(bool)	whether to actually run the sim (if not, just initialize it)	True
kwargs	(dict)	also passed to the sim	{}

Returns

Name	Type	Description
sim	Sim	a single sim object with results

Example:

import starsim as ss
sim = ss.Sim() # Create a default simulation
sim = ss.single_run(sim) # Run it, equivalent(ish) to sim.run()