sim

sim

Define core Sim classes

Classes

Name	Description
AlreadyRunError	Raised if trying to re-run an already-run sim without re-initializing
Sim	The Sim object

AlreadyRunError

sim.AlreadyRunError()

Raised if trying to re-run an already-run sim without re-initializing

Sim

sim.Sim(
    pars=None,
    label=None,
    people=None,
    modules=None,
    demographics=None,
    diseases=None,
    networks=None,
    interventions=None,
    analyzers=None,
    connectors=None,
    copy_inputs=True,
    data=None,
    **kwargs,
)

The Sim object

All Starsim simulations run via the Sim class. It is responsible for initializing and running all modules and generating results.

Parameters

Name	Type	Description	Default
pars	SimPars / dict	either an ss.SimPars object, or a nested dictionary; can include all other arguments	None
label	str	the human-readable name of the simulation	None
people	People	if provided, use this ss.People object	None
modules	Module / list	if provided, use these modules (and divide among demographics, diseases, etc. based on type)	None
demographics	str / Demographics / list	a string naming the demographics module to use, the module itself, or a list	None
connectors	str / Connector / list	as above, for connectors	None
networks	str / Network / list	as above, for networks	None
interventions	str / Intervention / list	as above, for interventions	None
diseases	str / Disease / list	as above, for diseases	None
analyzers	str / Analyzer / list	as above, for analyzers	None
copy_inputs	bool	if True, copy modules as they’re inserted into the sim (allowing reuse in other sims, but meaning they won’t be updated)	True
data	df	a dataframe (or dict) of data, with a column “time” plus data of the form “module.result”, e.g. “hiv.new_infections” (used for plotting only)	None
kwargs	dict	merged with pars; see ss.SimPars for all parameter values	{}

Examples:

sim = ss.Sim(diseases='sir', networks='random') # Simplest Starsim sim; equivalent to ss.demo()
sim = ss.Sim(diseases=ss.SIR(), networks=ss.RandomNet()) # Equivalent using objects instead of strings
sim = ss.Sim(diseases=['sir', ss.SIS()], networks=['random', 'mf']) # Example using list inputs; can mix and match types

Attributes

Name	Description
label	Get the sim label from the parameters, if available.
label_to_name	Return a mapping from module labels to module names, e.g. {‘HIV’: ‘hiv’, ‘Pregnancy’: ‘pregnancy’}
modules	Return an interator over all Module instances (stored in standard places) in the Sim

Methods

Name	Description
check_method_calls	Check if any required methods were not called.
check_results_ready	Check that results are ready
cprofile	Profile the performance of the simulation using a function profiler (sc.cprofile())
finalize	Compute final results
finalize_results	Scale the results and remove any “unused” results
finish_step	Finish the simulation timestep
get_module	Retrieve a single module
get_modules	Retrieve modules from the Sim
init	Perform all initializations for the sim
init_data	Initialize or add data to the sim
init_dists	Initialize the distributions
init_module_attrs	Move initialized modules to the sim
init_modules_post	Initialize values in other modules, including networks and time parameters, and do any other post-processing
init_modules_pre	Initialize all the modules with the sim
init_people	Initialize people within the sim
init_people_vals	Initialize the People states with actual values
init_results	Create initial results that are present in all simulations
init_time	Time indexing; derived values live in the sim rather than in the pars
plot	Plot all results in the Sim object
products	List all products across interventions; not an ndict like the other module types
profile	Profile the performance of the simulation using a line profiler (sc.profile())
reset_time_pars	Reset the time parameters in the modules; used for imposing the sim’s timestep on the modules
run	Run the model – the main method for running a simulation.
run_one_step	Run a single sim step; only used for debugging purposes.
save	Save to disk as a gzipped pickle.
set_diagnostics	Store detailed diagnostics information in the sim
shrink	“Shrinks” the simulation by removing the people and other memory-intensive
start_step	Start the step – only print progress; all actual changes happen in the modules
summarize	Provide a quick summary of the sim; returns the last entry for count and
to_df	Export results as a Pandas dataframe
to_json	Export results and parameters as JSON.
to_yaml	Export results and parameters as YAML.

check_method_calls

sim.Sim.check_method_calls(die=None, warn=None, verbose=False)

Check if any required methods were not called.

Typically called automatically by sim.run(); default behavior is to warn (see options.check_method_calls).

Parameters

Name	Type	Description	Default
die	bool	whether to raise an exception if missing methods were found (default False)	None
warn	bool	whether to raise a warning if missing methods were found (default False)	None
verbose	bool	whether to print the number of times each method was called (default False)	False

Returns

Name	Type	Description
		A list of missing method calls by module

check_results_ready

sim.Sim.check_results_ready(errormsg=None)

Check that results are ready

cprofile

sim.Sim.cprofile(sort='cumtime', mintime=0.001, **kwargs)

Profile the performance of the simulation using a function profiler (sc.cprofile())

Parameters

Name	Type	Description	Default
sort	str	default sort column; common choices are ‘cumtime’ (total time spent in a function, includin subfunctions) and ‘selftime’ (excluding subfunctions)	'cumtime'
mintime	float	exclude function calls less than this time in seconds	0.001
**kwargs	dict	passed to sc.cprofile()	{}

Example:

import starsim as ss

net = ss.RandomNet()
sis = ss.SIS()
sim = ss.Sim(networks=net, diseases=sis)
prof = sim.cprofile()

finalize

sim.Sim.finalize()

Compute final results

finalize_results

sim.Sim.finalize_results()

Scale the results and remove any “unused” results

finish_step

sim.Sim.finish_step()

Finish the simulation timestep

get_module

sim.Sim.get_module(query, die=True, match_case=False)

Retrieve a single module

This method is guaranteed to return a single module if it succeeds, so can be relied on in places where this is expected to retrieve a specific module from the Sim (and retrieving no modules or multiple modules would be unexpected). Use Sim.get_modules() to retrieve all matching modules.

Parameters

Name	Type	Description	Default
query	type / str	Query input supported by get_modules (either a Type e.g., ss.SIR) or a string that will match module names.	required
die	bool	if True (default), raises an exception unless exactly 1 module is found; else return None if no modules found	True
match_case	bool	if query is a string, whether to match case (default False)	False

Returns

Name	Type	Description
		An ss.Module instance

get_modules

sim.Sim.get_modules(query=None, match_case=False, as_dict=False)

Retrieve modules from the Sim

Retrieve a module by name or by type. The query term can be the type of module to match e.g., ss.SIR, ss.Disease, ss.Intervention, or a string which is tested against module names. The string can contain a '*' at the start or end.

If the Sim is not initialized, this will search over any ss.Module instances contained in Sim.pars. Note that sim initialization might result in the creation of modules, therefore some modules may be retrieved after initialization but not before (e.g. diseases='sir' will not be registered as the module ss.SIR() until after initialization).

Parameters

Name	Type	Description	Default
query	type / str	The module type (e.g. ss.SIR) or a case-insensitive string (e.g. 'sir'); if None, return all modules	None
match_case	bool	if query is a string, whether to match case (default False)	False
as_dict	bool	only used if query=None, in which case return a dict rather than list of modules	False

Returns

Name	Type	Description
		A list of ss.Module instances. The list will be empty if no modules were found

init

sim.Sim.init(force=False, timer=False, **kwargs)

Perform all initializations for the sim

Parameters

Name	Type	Description	Default
force	bool	whether to overwrite sim attributes even if they already exist	False
timer	bool	if True, count the time required for initialization (otherwise just count run time)	False
kwargs	dict	passed to ss.People()	{}

init_data

sim.Sim.init_data(data=None)

Initialize or add data to the sim

init_dists

sim.Sim.init_dists()

Initialize the distributions

init_module_attrs

sim.Sim.init_module_attrs(force=False)

Move initialized modules to the sim

init_modules_post

sim.Sim.init_modules_post()

Initialize values in other modules, including networks and time parameters, and do any other post-processing

init_modules_pre

sim.Sim.init_modules_pre()

Initialize all the modules with the sim

init_people

sim.Sim.init_people(verbose=None, **kwargs)

Initialize people within the sim Sometimes the people are provided, in which case this just adds a few sim properties to them. Other time people are not provided and this method makes them.

Parameters

Name	Type	Description	Default
verbose	int	detail to print	None
kwargs	dict	passed to ss.People()	{}

init_people_vals

sim.Sim.init_people_vals()

Initialize the People states with actual values

init_results

sim.Sim.init_results()

Create initial results that are present in all simulations

This method initializes results by calling People.init_results() to let People handle its own result initialization (including automatic BoolState results).

init_time

sim.Sim.init_time()

Time indexing; derived values live in the sim rather than in the pars

plot

sim.Sim.plot(
    key=None,
    fig=None,
    show_data=True,
    show_skipped=False,
    show_module=None,
    show_label=False,
    n_ticks=None,
    annualize=False,
    **kwargs,
)

Plot all results in the Sim object

Parameters

Name	Type	Description	Default
key	str / list	the results key to plot (by default, all); if a list, plot exactly those keys	None
fig	Figure	if provided, plot results into an existing figure	None
style	str	the plotting style to use	required
show_data	bool	plot the data, if available	True
show_skipped	bool	show even results that are skipped by default	False
show_module	int	whether to show the module as well as the result name; if an int, show if the label is less than that length (default, 26); if -1, use a newline	None
show_label	str	if ‘fig’, reset the fignum; if ‘title’, set the figure suptitle	False
n_ticks	tuple of ints	if provided, specify how many x-axis ticks to use (default: (2,5), i.e. minimum of 2 and maximum of 5)	None
annualize	bool	if True, resample results to annual values before plotting (uses each Result’s summarize_by to determine sum/mean/last)	False
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 ss.style(), for controlling the detailed plotting style (default “starsim”; other options are “simple”, None, or any Matplotlib style)	required
**kwargs	dict	known arguments (e.g. figsize, font) split between the above dicts; see ss.plot_args() for all valid options	{}

Examples:

sim = ss.Sim(diseases='sis', networks='random').run()

# Basic usage
sim.plot()

# Plot a single result
sim.plot('sis.prevalence')

# Plot with a custom figure size, font, and style
sim.plot(figsize=(12,16), font='Raleway', style='fancy')

products

sim.Sim.products()

List all products across interventions; not an ndict like the other module types

profile

sim.Sim.profile(follow=None, do_run=True, plot=True, **kwargs)

Profile the performance of the simulation using a line profiler (sc.profile())

Parameters

Name	Type	Description	Default
follow	func / list	a list of functions/methods to follow in detail	None
do_run	bool	whether to immediately run the sim	True
plot	bool	whether to plot time spent per module step	True
**kwargs	dict	passed to sc.profile()	{}

Example:

import starsim as ss

net = ss.RandomNet()
sis = ss.SIS()
sim = ss.Sim(networks=net, diseases=sis)
prof = sim.profile(follow=[net.add_pairs, sis.infect])

reset_time_pars

sim.Sim.reset_time_pars(force=True)

Reset the time parameters in the modules; used for imposing the sim’s timestep on the modules

run

sim.Sim.run(until=None, verbose=None, check_method_calls=True)

Run the model – the main method for running a simulation.

Parameters

Name	Type	Description	Default
until	date / str / float	the date to run the sim until	None
verbose	float	the level of detail to print (default 0.1, i.e. output once every 10 steps)	None
check_method_calls	bool	whether to check that all required methods were called	True

run_one_step

sim.Sim.run_one_step(verbose=None)

Run a single sim step; only used for debugging purposes.

Note: sim.run_one_step() runs a single simulation timestep, which involves multiple function calls. In contrast, loop.run_one_step() runs a single function call.

Note: the verbose here is only for the Loop object, not the sim.

save

sim.Sim.save(filename=None, shrink=None, **kwargs)

Save to disk as a gzipped pickle.

Parameters

Name	Type	Description	Default
filename	str or None	the name or path of the file to save to; if None, uses stored	None
shrink	bool or None	whether to shrink the sim prior to saving (reduces size by ~99%)	None
kwargs		passed to sc.makefilepath()	{}

Returns

Name	Type	Description
filename	str	the validated absolute path to the saved file

Example:

sim.save() # Saves to a .sim file

set_diagnostics

sim.Sim.set_diagnostics(rvs=True, states=True, detailed=False)

Store detailed diagnostics information in the sim

Stores every random number produced during a sim run (by ss.Dist objects) and/or every state of every agent, at every timestep. This allows e.g. understanding exactly where two runs that should have been identical diverged. Results can be exported (in JSON format) and analyzed externally.

Although the states export could be used for analysis, users are encouraged to write an ss.Analyzer instead, as enabling diagnostics significantly degrades sim run time and memory usage.

Parameters

Name	Type	Description	Default
rvs	bool	whether to enable diagnostics for random numbers/variates (default True)	True
states	bool	as above, for people states (default True)	True
detailed	bool	if true, store literally every random number and agent state (otherwise, use summary stats) (default False)	False

Examples:

# General settings -- use a small sim and few timesteps if possible
kw = dict(n_agents=100, start=0, stop=10, networks='random', diseases='sis')

# Simplest usage: store info and print states
sim = ss.Sim(**kw)
sim.set_diagnostics()
sim.run()
print(sim.diagnostics.states)

# Configure separately, with custom file export and saving all detail
sim = ss.Sim(**kw)
sim.set_diagnostics(rvs='diagnostics_rvs.json', states='diagnostics_states.json', detailed=True)
sim.run()
sim.diagnostics.export()

shrink

sim.Sim.shrink(inplace=True, size_limit=1.0, intercept=10, die=True)

“Shrinks” the simulation by removing the people and other memory-intensive attributes (e.g., some interventions and analyzers), and returns a copy of the “shrunken” simulation. Used to reduce the memory required for RAM or for saved files.

Parameters

Name	Type	Description	Default
inplace	bool	whether to perform the shrinking in place (default), or return a shrunken copy instead	True
size_limit	float	print a warning if any module is larger than this size limit, in units of KB per timestep (set to None to disable)	1.0
intercept	float	the size (in units of size_limit) to allow for a zero-timestep sim	10
die	bool	whether to raise an exception if the shrink failed	True

Returns

Name	Type	Description
shrunken	Sim	a Sim object with the listed attributes removed

start_step

sim.Sim.start_step()

Start the step – only print progress; all actual changes happen in the modules

summarize

sim.Sim.summarize(how='default')

Provide a quick summary of the sim; returns the last entry for count and cumulative results, and the mean otherwise.

Parameters

Name	Type	Description	Default
how	str	how to summarize: can be ‘mean’, ‘median’, ‘last’, or a mapping of result keys to those	'default'

to_df

sim.Sim.to_df(sep='_', **kwargs)

Export results as a Pandas dataframe Args: sep (str): separator for the keys kwargs: passed to results.to_df()

to_json

sim.Sim.to_json(
    filename=None,
    keys=None,
    tostring=False,
    indent=2,
    verbose=False,
    **kwargs,
)

Export results and parameters as JSON.

Parameters

Name	Type	Description	Default
filename	str	if None, return string; else, write to file	None
keys	str / list	attributes to write to json (choices: ‘pars’, ‘summary’, and/or ‘results’)	None
verbose	bool	detail to print	False
**kwargs	dict	passed to sc.jsonify()	{}

Returns

Name	Type	Description
		A dictionary representation of the parameters and/or summary results
		(or write that dictionary to a file)

Examples:

json = sim.to_json() # Convert to a dict
sim.to_json('sim.json') # Write everything
sim.to_json('summary.json', keys='summary') # Just write the summary

to_yaml

sim.Sim.to_yaml(filename=None, sort_keys=False, **kwargs)

Export results and parameters as YAML.

Parameters

Name	Type	Description	Default
filename	str	the name of the file to write to (default {sim.label}.yaml)	None
kwargs	dict	passed to sim.to_json()	{}

Example:

sim = ss.Sim(diseases='sis', networks='random').run()
sim.to_yaml('results.yaml', keys='results')

Functions

Name	Description
check_sims_match	Shortcut to using ss.diff_sims() to check if multiple sims match
demo	Create a simple demo simulation for Starsim
diff_sims	Compute the difference of the summaries of two simulations, and print any

check_sims_match

sim.check_sims_match(*args, full=False)

Shortcut to using ss.diff_sims() to check if multiple sims match

Parameters

Name	Type	Description	Default
args	list	a list of 2 or more sims to compare	()
full	bool	if True, return whether each sim matches the first	False

Example:

s1 = ss.Sim(diseases='sir', networks='random')
s2 = ss.Sim(pars=dict(diseases='sir', networks='random'))
s3 = ss.Sim(diseases=ss.SIR(), networks=ss.RandomNet())
assert ss.check_sims_match(s1, s2, s3)

demo

sim.demo(run=True, plot=True, summary=True, show=True, **kwargs)

Create a simple demo simulation for Starsim

Defaults to using the SIR model with a random network, but these can be configured.

Parameters

Name	Type	Description	Default
run	bool	whether to run the sim	True
plot	bool	whether to plot the results	True
summary	bool	whether to print a summary of the results	True
kwargs	dict	passed to ss.Sim()	{}

Examples:

ss.demo() # Run, plot, and show results
ss.demo(diseases='hiv', networks='mf') # Run with different defaults

diff_sims

sim.diff_sims(
    sim1,
    sim2,
    skip_key_diffs=False,
    skip=None,
    full=False,
    output=False,
    die=False,
)

Compute the difference of the summaries of two simulations, and print any values which differ.

Parameters

Name	Type	Description	Default
sim1	Sim / MultiSim / dict	either a simulation/MultiSim object or the sim.summary dictionary	required
sim2	im / dict	ditto	required
skip_key_diffs	bool	whether to skip keys that don’t match between sims	False
skip	list	a list of values to skip	None
full	bool	whether to print out all values (not just those that differ)	False
output	bool	whether to return the output as a string (otherwise print)	False
die	bool	whether to raise an exception if the sims don’t match	False

Example:

s1 = ss.Sim(rand_seed=1).run()
s2 = ss.Sim(rand_seed=2).run()
ss.diff_sims(s1, s2)