settings
Options for Starsim, and the plotting style
These exist so that behavior that isn’t part of a model (how much to print, how to treat warnings, which kernels to use) is set in one place, e.g.:
ss.options(verbose=0)Used with: agents and compartments; declared and coded modules
Classes
| Name | Description |
|---|---|
| Options | The options for Starsim, as ss.options: settings for everything in a session that aren’t part of a model, such as how much to print and how to treat warnings |
| OptionsContext | What ss.options(...) returns: at the end of a “with” block, it sets the options it changed back to what they were |
Options
settings.Options()The options for Starsim, as ss.options: settings for everything in a session that aren’t part of a model, such as how much to print and how to treat warnings
Set one with ss.options(verbose=0) (or ss.options.verbose = 0), or for a with block only, with with ss.options(verbose=0):; each can also be set before Python starts, by its environment variable (e.g. STARSIM_VERBOSE=0). ss.options.set('defaults') resets them all, and ss.options.set(verbose='default') one. Use ss.style() to set the plotting style for a block.
The options most often set are:
- verbose: how much a sim prints (0 for nothing)
- warnings: what to do with warnings ("warn", "print", "error", or "ignore")See ss.options.help(detailed=True) for all of them, with what each is for.
Examples
ss.options(verbose=2) # Print everything
ss.options(warnings='error') # Be more strict about warnings
with ss.options(jax='cpu'): # Just for this block
sim.gradient()Attributes
| Name | Description |
|---|---|
| is_jupyter | Whether this is a Jupyter notebook (or jupyter=1); jupyter=0 doesn’t change this, since a notebook still shows what is returned |
Methods
| Name | Description |
|---|---|
| context | Set options, as set() does, until the end of a “with” block (the same as ss.options(...)) |
| disp | Print each option and its value |
| get_default | The default of an option |
| get_orig_options | The description and the default of each option, the default read from its environment variable if set; to reset the options, use ss.options.set('defaults') |
| help | Print what each option is for, its value, its default, and its environment variable |
| refresh_references | Pass the data types on to the modules that keep their own copies, for speed (e.g. ss.arrays.ss_int) |
| set | Set one or more options (see ss.options.help() for what each is for) |
| set_blas_threads | Set the number of BLAS threads, for the libraries already loaded and any loaded later, as in new workers; unlike sc.limit_threads(), this can also raise it |
| set_jupyter | Set Sciris’ Jupyter settings as well |
| set_precision | Set the data types of the arrays of agents and kernels (ss.dtypes) to the precision of ss.options.precision |
| set_style | Set the plotting style from ss.options.style (used by ss.style()) |
| to_dict | The options as a plain dict |
| update | Set several options, as set() does (so e.g. the kernels are swapped) |
context
settings.Options.context(key=None, value=None, **kwargs)Set options, as set() does, until the end of a “with” block (the same as ss.options(...))
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| key | str |
the option to set, or ‘defaults’ to set every option to its default | None |
| value | varies |
its value | None |
| kwargs | dict |
the options to set, by name |
Returns
| Name | Type | Description |
|---|---|---|
| An object that sets them back to what they were at the end of the “with” block (and outside one, does nothing) |
Examples
# Silence all output
with ss.options(verbose=0):
ss.Sim().run()
# Convert warnings to errors
with ss.options.context(warnings='error'):
ss.Sim().init()
# Use ss.style(), not context(), for plotting options
with ss.style(dpi=50):
ss.Sim().run().plot()disp
settings.Options.disp()Print each option and its value
get_default
settings.Options.get_default(key)The default of an option
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| key | str |
the name of the option | required |
get_orig_options
settings.Options.get_orig_options()The description and the default of each option, the default read from its environment variable if set; to reset the options, use ss.options.set('defaults')
help
settings.Options.help(*args, detailed=False, output=False)Print what each option is for, its value, its default, and its environment variable
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| *args | list |
the options to print help on (default: all, if detailed) |
|
| detailed | bool |
whether to print the help on every option, rather than only the overview | False |
| output | bool |
whether to return the help on each option, as a dict | False |
Examples
ss.options.help(detailed=True)refresh_references
settings.Options.refresh_references()Pass the data types on to the modules that keep their own copies, for speed (e.g. ss.arrays.ss_int)
set
settings.Options.set(key=None, value=None, **kwargs)Set one or more options (see ss.options.help() for what each is for)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| key | str |
the option to set, or ‘defaults’ to reset every option to its default | None |
| value | varies |
its value; None or ‘default’ for its default | None |
| kwargs | dict |
the options to set, by name |
Examples
ss.options.set(verbose=0) # Equivalent to ss.options(verbose=0)set_blas_threads
settings.Options.set_blas_threads()Set the number of BLAS threads, for the libraries already loaded and any loaded later, as in new workers; unlike sc.limit_threads(), this can also raise it
set_jupyter
settings.Options.set_jupyter()Set Sciris’ Jupyter settings as well
set_precision
settings.Options.set_precision(refresh=True)Set the data types of the arrays of agents and kernels (ss.dtypes) to the precision of ss.options.precision
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| refresh | bool |
whether to pass the new data types on to the modules that keep their own copies | True |
set_style
settings.Options.set_style()Set the plotting style from ss.options.style (used by ss.style())
to_dict
settings.Options.to_dict()The options as a plain dict
update
settings.Options.update(*args, **kwargs)Set several options, as set() does (so e.g. the kernels are swapped)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| args | dict |
the options to set, as a dict | |
| kwargs | dict |
the options to set, by name |
OptionsContext
settings.OptionsContext(options, before)What ss.options(...) returns: at the end of a “with” block, it sets the options it changed back to what they were
Functions
| Name | Description |
|---|---|
| cache_numba | Keep Numba’s cache in a temporary folder if it has nowhere else to go (a read-only package and home folder, as in some containers), since cache=True would otherwise fail on import; Numba finds it by NUMBA_CACHE_DIR, as do the workers of ss.parallel() |
| load_fonts | Load the fonts bundled with Starsim (Mulish, Raleway, and Rosario) for plotting; done on import, so usually not for the user |
| style | Set the plotting style for a with block |
| with_fallback | A named font, followed by Matplotlib’s sans-serif fonts (DejaVu Sans by default) for the glyphs it lacks, e.g. the Greek letters that Mulish, Raleway, and Rosario don’t have; a generic family or a list is kept as it is |
cache_numba
settings.cache_numba()Keep Numba’s cache in a temporary folder if it has nowhere else to go (a read-only package and home folder, as in some containers), since cache=True would otherwise fail on import; Numba finds it by NUMBA_CACHE_DIR, as do the workers of ss.parallel()
load_fonts
settings.load_fonts(
folder=None,
name='Mulish',
rebuild=False,
verbose=False,
**kwargs,
)Load the fonts bundled with Starsim (Mulish, Raleway, and Rosario) for plotting; done on import, so usually not for the user
Note: if fonts don’t load, try running ss.settings.load_fonts(rebuild=True), and/or rebooting the system.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| folder | str |
the folder to add fonts from | None |
| name | str |
the name of the font to load | 'Mulish' |
| rebuild | bool |
whether to rebuild the font cache | False |
| verbose | bool |
whether to print out progress/errors | False |
| kwargs | dict |
passed to sc.fonts() |
style
settings.style(style=None, **kwargs)Set the plotting style for a with block
Note: Starsim comes bundled with three fonts: Mulish (default), Raleway, and Rosario. Use font='sans-serif' to use the Matplotlib default font.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| style | str |
the style to use; if None, use current; otherwise, ‘starsim’, ‘simple’, ‘fancy’, plus all of the Matplotlib styles are options | None |
| **kwargs | dict |
passed to sc.options.with_style() |
Examples
# Create a plot using default Starsim styling
with ss.style():
plt.plot()
# Create a plot using a built-in Matplotlib style
with ss.style('seaborn-v0_8-whitegrid'):
plt.plot()
# Customize the current style
with ss.style(font='Rosario'):
plt.plot()with_fallback
settings.with_fallback(font)A named font, followed by Matplotlib’s sans-serif fonts (DejaVu Sans by default) for the glyphs it lacks, e.g. the Greek letters that Mulish, Raleway, and Rosario don’t have; a generic family or a list is kept as it is