internals.debugtools
Tools for debugging and profiling Starsim runs: sim.profile(), detailed diagnostics, and mock objects for testing a module without a sim
They exist so that a slow or surprising run can be looked into without changing the model.
Used with: agents and compartments; declared and coded modules
Classes
| Name | Description |
|---|---|
| Diagnostics | Helper class for storing detailed diagnostic information; see sim.set_diagnostics() for usage; not to be used directly |
| Profile | Class to profile the performance of a simulation |
Diagnostics
internals.debugtools.Diagnostics(sim, rvs=True, states=True, detailed=False)Helper class for storing detailed diagnostic information; see sim.set_diagnostics() for usage; not to be used directly
It exists to find where two runs that should match first differ.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | ss.Sim |
the sim to attach diagnostics to | required |
| rvs | bool / str |
whether to track random variates; if a string, used as the export filename (default ‘debug_rvs.json’) | True |
| states | bool / str |
whether to track people states; if a string, used as the export filename (default ‘debug_states.json’) | True |
| detailed | bool |
if True, store full arrays; if False, store summary statistics only | False |
Methods
| Name | Description |
|---|---|
| compute_stats | Compute length, mean, min, max, and unique hash |
| export | Export saved data to file(s); filenames must be set when the object is created |
| store_rvs | Store random numbers (random variates) |
| store_states | Store all states from people |
compute_stats
internals.debugtools.Diagnostics.compute_stats(v)Compute length, mean, min, max, and unique hash
export
internals.debugtools.Diagnostics.export()Export saved data to file(s); filenames must be set when the object is created
store_rvs
internals.debugtools.Diagnostics.store_rvs(dist, rvs)Store random numbers (random variates)
store_states
internals.debugtools.Diagnostics.store_states(key=None)Store all states from people
Profile
internals.debugtools.Profile(
sim,
follow=None,
do_run=True,
plot=True,
verbose=True,
**kwargs,
)Class to profile the performance of a simulation
Typically invoked via sim.profile() (kind='line', the default).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | ss.Sim |
the sim to profile | required |
| 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 |
| verbose | bool |
whether to print the profile | True |
| **kwargs | dict |
passed to sc.profile() |
Examples
import starsim as ss
import starsim.library as ssl
net = ss.RandomNet()
hiv = ssl.HIV() # A disease written as code
sim = ss.Sim(networks=net, diseases=hiv)
prof = sim.profile(follow=[net.add_pairs, hiv.transmit])
prof.disp()Methods
| Name | Description |
|---|---|
| disp | Same as sc.profile.disp(), but skip the run function by default |
| plot_cpu | Shortcut to sim.loop.plot_cpu() |
| profile_init | Handle sim init – both run it and profile it |
| run | Profile the performance of the simulation |
disp
internals.debugtools.Profile.disp(bytime=1, maxentries=10, skiprun=True)Same as sc.profile.disp(), but skip the run function by default
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bytime | int |
1 to sort by the time in each function; see sc.profile.disp() |
1 |
| maxentries | int |
the number of functions to show | 10 |
| skiprun | bool |
whether to leave out the run function itself | True |
plot_cpu
internals.debugtools.Profile.plot_cpu()Shortcut to sim.loop.plot_cpu()
profile_init
internals.debugtools.Profile.profile_init()Handle sim init – both run it and profile it
run
internals.debugtools.Profile.run(disp=None)Profile the performance of the simulation
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| disp | bool |
whether to show the results | None |
Functions
| Name | Description |
|---|---|
| check_sims_match | Shortcut to using diff_sims() to check if multiple sims match |
| diff_sims | Compute the difference of the summaries of two simulations, and print any |
| metadata | Store metadata; like sc.metadata(), but optimized for speed |
| mock_module | Create a minimal mock “Module” object; kwargs are passed to ss.debugtools.mock_time() |
| mock_people | Create a minimal mock “People” object with ages |
| mock_sim | Create a minimal mock “Sim” object to initialize objects that require it |
| mock_time | Create a minimal mock “Time” object |
check_sims_match
internals.debugtools.check_sims_match(*args, full=False)Shortcut to using 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 |
Examples
s1 = ss.Sim(diseases='sir', networks='random').run()
s2 = ss.Sim(dict(diseases='sir', networks='random')).run()
s3 = ss.Sim(diseases=ss.SIR(), networks=ss.RandomNet()).run()
assert ss.debugtools.check_sims_match(s1, s2, s3)diff_sims
internals.debugtools.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 a dict of its summary (e.g. sim.summarize().value.to_dict()) | required |
| sim2 | Sim / MultiSim / 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 |
Examples
s1 = ss.Sim(rand_seed=1).run()
s2 = ss.Sim(rand_seed=2).run()
ss.debugtools.diff_sims(s1, s2)metadata
internals.debugtools.metadata(comments=None)Store metadata; like sc.metadata(), but optimized for speed
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| comments | str |
any comments to store with the metadata | None |
mock_module
internals.debugtools.mock_module(dur=10, **kwargs)Create a minimal mock “Module” object; kwargs are passed to ss.debugtools.mock_time()
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| dur | float |
the duration | 10 |
| **kwargs | dict |
passed to mock_time() |
mock_people
internals.debugtools.mock_people(
n_agents=100,
min_age=0,
max_age=70,
age_seed=1,
)Create a minimal mock “People” object with ages
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n_agents | int |
the number of agents | 100 |
| min_age | float |
the youngest age | 0 |
| max_age | float |
the oldest age | 70 |
| age_seed | int |
the random seed for the ages | 1 |
mock_sim
internals.debugtools.mock_sim(n_agents=100, **kwargs)Create a minimal mock “Sim” object to initialize objects that require it
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n_agents | int |
the number of agents to create | 100 |
| **kwargs | dict |
passed to ss.debugtools.mock_time() |
mock_time
internals.debugtools.mock_time(dt=1.0, dur=10, start=2000)Create a minimal mock “Time” object
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| dt | float |
the timestep | 1.0 |
| dur | float |
the duration | 10 |
| start | float |
the start | 2000 |