distributions

distributions

The distributions to choose from: ss.uniform, ss.normal, ss.poisson, and so on, each a random-number-safe ss.Dist

These exist so that a model can use any distribution for a parameter or a draw, with the same random numbers for the same agent across scenarios. How they work is in ss.dists. As agents, they are drawn for each agent; in a compartmental run, most are read for what they say about the group, such as their mean.

Used with: agents and compartments; declared and coded modules

Classes

Name	Description
bernoulli	Bernoulli distribution: True or False with the given probability (which can be an array, or a function of the agents)
beta_dist	Beta distribution, with values between 0 and 1, given by its shape parameters, or by its mean and standard deviation
binom	Binomial distribution: the number of successes in n trials; as a likelihood (see sim.fit()), the model’s value is the probability and the data are counts, e.g. the positives among n tested (not their fraction)
choice	Random choice between discrete options
choose_n	Choose exactly n agents (without replacement) from a set of candidate UIDs
constant	Constant (delta) distribution: every draw is the same value, e.g. for a parameter that takes a distribution but should not vary
expon	Exponential distribution
gamma	Gamma distribution (specifically, scipy.stats.gamma)
histogram	Draws from a histogram, uniform within each bin, e.g. ages from the number of people in each age group
lognormal	Lognormal distribution, given by its own mean and standard deviation, or by those of its logarithm
multi_random	Random numbers for pairs (or larger groups) of agents, e.g. one for each edge of a network in a transmission
nbinom	Negative binomial distribution, given by n and p, or by n and the mean
normal	Normal distribution
poisson	Poisson distribution
randint	Random integer distribution, on the interval [low, high)
random	Random distribution, with values on the interval (0, 1): the raw uniform draws, for code that uses them directly
truncnorm	Normal distribution truncated to an interval
uniform	Uniform distribution, values on interval (low, high); with one argument, it is the upper bound (ss.uniform(5) is between 0 and 5)
weibull	Weibull distribution (specifically, scipy.stats.weibull_min)

bernoulli

distributions.bernoulli(p=0.5, **kwargs)

Bernoulli distribution: True or False with the given probability (which can be an array, or a function of the agents)

Unlike most distributions, it has a filter() method, which returns the agents for whom it is True (e.g. those who are infected, out of those exposed), and split(), which returns those for whom it is True and False.

Parameters

Name	Type	Description	Default
p	float	the probability of returning True (default 0.5)	0.5

Methods

Name	Description
filter	The agents for whom it is True, or with both=True, those for whom it is True and those for whom it is False
split	Alias to filter(uids, both=True)

filter

distributions.bernoulli.filter(uids=None, both=False)

The agents for whom it is True, or with both=True, those for whom it is True and those for whom it is False

Parameters

Name	Type	Description	Default
uids	array	the agents to choose among (default: all active agents)	None
both	bool	if True, return the UIDs for both True and False	False

split

distributions.bernoulli.split(uids=None)

Alias to filter(uids, both=True)

Parameters

Name	Type	Description	Default
uids	array	the agents to choose among (default: all active agents)	None

beta_dist

distributions.beta_dist(
    a=None,
    b=None,
    *,
    mean=None,
    std=None,
    force=False,
    **kwargs,
)

Beta distribution, with values between 0 and 1, given by its shape parameters, or by its mean and standard deviation

Parameters

Name	Type	Description	Default
a	float	shape parameter, must be > 0 (default 1.0)	None
b	float	shape parameter, must be > 0 (default 1.0)	None
mean	float	instead of a and b, the mean, which must be 0 < mean < 1 (with std)	None
std	float	the standard deviation, which must be 0 < std² < mean×(1 − mean)	None
force	bool	with mean and std, clip them to the valid range (with a warning) rather than raise an error	False

Examples

ss.beta_dist(a=2, b=5)
ss.beta_dist(mean=0.3, std=0.1) # E.g. a probability that varies between people

Methods

Name	Description
shape_pars	The shape parameters a and b of a beta distribution with this mean and variance

shape_pars

distributions.beta_dist.shape_pars(mean, var, force=False)

The shape parameters a and b of a beta distribution with this mean and variance

binom

distributions.binom(n=1, p=0.5, **kwargs)

Binomial distribution: the number of successes in n trials; as a likelihood (see sim.fit()), the model’s value is the probability and the data are counts, e.g. the positives among n tested (not their fraction)

Parameters

Name	Type	Description	Default
n	int	the number of trials (default 1)	1
p	float	the probability of success in [0,1], (default 0.5)	0.5

Methods

Name	Description
ppf	The inverse CDF, compiled (see ss.solvers.backends.draws); SciPy’s above a mean of 30 (on the smaller side of 1/2), and for unusual parameters

ppf

distributions.binom.ppf(rands)

The inverse CDF, compiled (see ss.solvers.backends.draws); SciPy’s above a mean of 30 (on the smaller side of 1/2), and for unusual parameters

choice

distributions.choice(a=2, p=None, replace=True, **kwargs)

Random choice between discrete options

The probabilities can differ by agent: give p as a 2D array with one row per agent drawn for (or a function returning one), and one column per choice. Each row is normalized to sum to 1. Each agent’s choice is found from their own random number by the inverse CDF of their own row, so the draw is one vectorized call, and keeps common random numbers: an agent’s choice doesn’t depend on who else is drawn for, or on other agents’ probabilities.

Parameters

Name	Type	Description	Default
a	int or array	the number of choices, or the choices themselves (default 2)	2
p	array / func	if supplied, the probability of each choice (default, 1/a for a choices); or a 2D array (or a function returning one) with a row of probabilities (or weights) for each agent	None
replace	bool	whether an option can be chosen more than once (default True)	True

Examples

# Simulate 10 die rolls
ss.choice(6, strict=False)(10) + 1

# Choose between specified options each with a specified probability (must sum to 1)
ss.choice(a=[30, 70], p=[0.3, 0.7], strict=False)(10)

# A row of probabilities per agent: here by age group, from a table of age groups × choices
table = np.array([[0.7, 0.2, 0.1], [0.3, 0.4, 0.3]])
def p_by_age(self, sim, uids):
    return table[(sim.people.age[uids] >= 18).astype(int)]
method = ss.choice(a=['none', 'pill', 'iud'], p=p_by_age) # In a module's __init__()
chosen = self.method.rvs(uids) # In its step()

Note: although Bernoulli trials can be generated using a=2, it is much faster to use ss.bernoulli() instead.

Methods

Name	Description
make_rvs	Draws without UIDs (a size, or replace=False) when p is a row per draw: the same inverse CDF as ppf(); not for the user
ppf	The choice for each uniform random number, by the inverse CDF
process_size	For replace=False, draw one value per UID; not for the user

make_rvs

distributions.choice.make_rvs()

Draws without UIDs (a size, or replace=False) when p is a row per draw: the same inverse CDF as ppf(); not for the user

ppf

distributions.choice.ppf(rands)

The choice for each uniform random number, by the inverse CDF

process_size

distributions.choice.process_size(n=1)

For replace=False, draw one value per UID; not for the user

choose_n

distributions.choose_n(n=1, weights=None, die=False, **kwargs)

Choose exactly n agents (without replacement) from a set of candidate UIDs

Like ss.bernoulli, use the filter() method, which returns the chosen UIDs. One random number is drawn per candidate (based on its slot), and the n candidates with the smallest numbers are chosen. This means that if the candidates change slightly (e.g. between two scenarios), most of the same agents are still chosen (unlike e.g. ss.choice(replace=False)).

If weights are supplied, candidates are chosen with probability proportional to their weight, via the Efraimidis–Spirakis key (1-u)**(1/w). This is computed as -log(1-u)/w, so the n smallest are chosen as before, and equal weights give the same agents as no weights. Candidates with zero weight are never chosen, so fewer than n UIDs are returned if fewer than n candidates have nonzero weight.

Parameters

Name	Type	Description	Default
n	int / func	the number of agents to choose (or a function returning it); if more than the number of candidates, all are chosen	1
weights	array / func	if supplied, the relative weight of each candidate (or a function returning them), matching the UIDs passed to filter()	None
die	bool	if True, raise an exception if fewer than n agents can be chosen (default: False)	False

Examples

# Seed exactly 20 infections of a disease written as code
sir = ssl.AgentSIR(init_prev=ss.choose_n(20))

# Choose 5 agents, weighted by age
chooser = ss.choose_n(5, weights=lambda self, sim, uids: sim.people.age[uids])

Methods

Name	Description
filter	Return the chosen UIDs (sorted), i.e. min(n, len(uids)) of them; if both=True, also return the UIDs not chosen (as ss.bernoulli.filter())
rvs	Return a boolean array of whether each agent is chosen (n can be UIDs or a size), so ss.choose_n() can be used in place of ss.bernoulli()
split	Alias to filter(uids, both=True)

filter

distributions.choose_n.filter(uids=None, both=False)

Return the chosen UIDs (sorted), i.e. min(n, len(uids)) of them; if both=True, also return the UIDs not chosen (as ss.bernoulli.filter())

Parameters

Name	Type	Description	Default
uids	array	the agents to choose among (default: all active agents)	None
both	bool	if True, also return the UIDs not chosen	False

rvs

distributions.choose_n.rvs(n=1, round=None, reset=False)

Return a boolean array of whether each agent is chosen (n can be UIDs or a size), so ss.choose_n() can be used in place of ss.bernoulli()

Parameters

Name	Type	Description	Default
n	int / array	the UIDs, or a size	1
round	None	accepted so the call matches ss.Dist.rvs(); a choice is not rounded, so only None	None
reset	bool	likewise; a choice is not reset, so only False	False

split

distributions.choose_n.split(uids=None)

Alias to filter(uids, both=True)

Parameters

Name	Type	Description	Default
uids	array	the agents to choose among (default: all active agents)	None

constant

distributions.constant(value=0.0, **kwargs)

Constant (delta) distribution: every draw is the same value, e.g. for a parameter that takes a distribution but should not vary

Parameters

Name	Type	Description	Default
value	float	the value to return	0.0

expon

distributions.expon(mean=1.0, **kwargs)

Exponential distribution

Parameters

Name	Type	Description	Default
mean	float	the mean of the distribution, e.g. a duration (default 1.0); its rate is 1/mean	1.0

Examples

ss.expon(ss.days(5)) # A mean of 5 days

Methods

Name	Description
ppf	The inverse CDF, compiled (see ss.solvers.backends.draws); SciPy’s for unusual parameters
sync_pars	Translate to SciPy’s names

ppf

distributions.expon.ppf(rands)

The inverse CDF, compiled (see ss.solvers.backends.draws); SciPy’s for unusual parameters

sync_pars

distributions.expon.sync_pars()

Translate to SciPy’s names

gamma

distributions.gamma(
    shape=None,
    scale=None,
    *,
    loc=0.0,
    mean=None,
    std=None,
    **kwargs,
)

Gamma distribution (specifically, scipy.stats.gamma)

Given by its shape and scale, or by its mean and standard deviation.

Parameters

Name	Type	Description	Default
shape	float	the shape parameter, sometimes called k or α (default 1.0)	None
scale	float	the scale parameter, sometimes called θ (default 1.0)	None
loc	float	a shift of the whole distribution, e.g. a shortest duration (default 0.0), as SciPy’s loc; by keyword only, so ss.gamma(2, 5) is a shape and a scale	0.0
mean	float	the mean, instead of shape and scale (with std); with loc, the mean of the whole distribution, shift included	None
std	float	the standard deviation, with mean	None

Examples

ss.gamma(shape=2, scale=ss.days(5)) # A mean of 10 days
ss.gamma(mean=ss.days(10), std=ss.days(7)) # About the same
ss.par(1800, prior=ss.gamma(mean=1800, std=400))

Methods

Name	Description
make_rvs	Use SciPy rather than NumPy to include the scale parameter
sync_pars	Translate to SciPy’s names

make_rvs

distributions.gamma.make_rvs()

Use SciPy rather than NumPy to include the scale parameter

sync_pars

distributions.gamma.sync_pars()

Translate to SciPy’s names

histogram

distributions.histogram(
    values=None,
    bins=None,
    density=False,
    data=None,
    **kwargs,
)

Draws from a histogram, uniform within each bin, e.g. ages from the number of people in each age group

Note: unlike other distributions, the parameters of this distribution can’t be modified after creation.

Parameters

Name	Type	Description	Default
values	array	the probability (or count) of each bin	None
bins	array	the edges of each bin	None
density	bool	treat the histogram as a density instead of counts; only matters with unequal bin widths, see numpy.histogram and scipy.stats.rv_histogram for more information	False
data	array	if supplied, compute the values and bin edges using this data and np.histogram() instead	None

Note: if the length of bins is equal to the length of values, they will be interpreted as left bin edges, and one additional right-bin edge will be added based on the difference between the last two bins (e.g. if the last two bins are 40 and 50, the final right edge will be added at 60). If no bins are supplied, then they will be created as integers matching the length of the values.

The values can be supplied in either normalized (sum to 1) or un-normalized format.

Examples

# Sample from an age distribution
age_bins = [0,    10,  20,  40,  65, 100]
age_vals = [0.1, 0.1, 0.3, 0.3, 0.2]
h1 = ss.histogram(values=age_vals, bins=age_bins, strict=False)
h1.plot_hist()

# Create a histogram from data
data = np.random.randn(10_000)*2+5
h2 = ss.histogram(data=data, strict=False)
h2.plot_hist(bins=100)

Methods

Name	Description
by_group	One histogram for each group: each person is drawn from the histogram of their group
make_rvs	Draws without UIDs: the same inverse CDF as ppf(); not for the user
ppf	The inverse of the CDF, which is piecewise linear

by_group

distributions.histogram.by_group(parts, group, **kwargs)

One histogram for each group: each person is drawn from the histogram of their group

Parameters

Name	Type	Description	Default
parts	list	the histograms (ss.histogram), one for each group	required
group		each person’s group, as an index into parts (e.g. ss.by(urban={False: 0, True: 1}), or a function of the agents)	required
kwargs	dict	passed to ss.histogram

make_rvs

distributions.histogram.make_rvs()

Draws without UIDs: the same inverse CDF as ppf(); not for the user

ppf

distributions.histogram.ppf(rands)

The inverse of the CDF, which is piecewise linear

lognormal

distributions.lognormal(
    mean=None,
    std=None,
    *,
    log_mean=None,
    log_std=None,
    **kwargs,
)

Lognormal distribution, given by its own mean and standard deviation, or by those of its logarithm

Parameters

Name	Type	Description	Default
mean	float	the mean of the values (default 1.0); must be > 0	None
std	float	the standard deviation of the values (default 1.0)	None
log_mean	float	instead of mean and std, the mean of the logarithm of the values (with log_std)	None
log_std	float	the standard deviation of the logarithm of the values	None

The mean and standard deviation can have units (e.g. mean=ss.days(10)); the log moments cannot, since they are of the logarithm, so give a unit with unit= (ss.lognormal(log_mean=2, log_std=0.5, unit='day')).

Examples

ss.lognormal(mean=2, std=1, strict=False).rvs(1000).mean() # Close to 2
ss.lognormal(log_mean=2, log_std=1, strict=False).rvs(1000).mean() # Roughly 12, i.e. exp(2 + 1/2)
ss.lognormal(mean=ss.days(10), std=ss.days(3)) # A duration

Methods

Name	Description
log_moments	The mean and standard deviation of the logarithm of a lognormal with this mean and standard deviation
log_pars	The mean and standard deviation of the logarithm, from its current parameters
make_rvs	NumPy’s lognormal, which takes the moments of the logarithm
scaled_pars	Parameters (as plain numbers, or functions of the agents) whose draws are those of pars times factor: the mean of the log moves by log(factor); used for unit= in a declared model
sync_pars	Convert to the moments of the logarithm, then translate to SciPy

log_moments

distributions.lognormal.log_moments(mean, std)

The mean and standard deviation of the logarithm of a lognormal with this mean and standard deviation

log_pars

distributions.lognormal.log_pars()

The mean and standard deviation of the logarithm, from its current parameters

make_rvs

distributions.lognormal.make_rvs()

NumPy’s lognormal, which takes the moments of the logarithm

scaled_pars

distributions.lognormal.scaled_pars(pars, factor)

Parameters (as plain numbers, or functions of the agents) whose draws are those of pars times factor: the mean of the log moves by log(factor); used for unit= in a declared model

sync_pars

distributions.lognormal.sync_pars()

Convert to the moments of the logarithm, then translate to SciPy

multi_random

distributions.multi_random(names, *args, crn=None, **kwargs)

Random numbers for pairs (or larger groups) of agents, e.g. one for each edge of a network in a transmission

It holds an ss.random() for each member of the pair, and combines their numbers, so the number for a pair depends on both agents and, with common random numbers, not on which other pairs are drawn for. For the manual version, see ss.distributions.combine_rands(); this class should be used in almost all cases.

Parameters

Name	Type	Description	Default
names	str / list	name(s) for each internal random distribution	required
*args		additional names (shorthand)
crn	bool	whether to use common random numbers; if None (default), follow ss.options.crn (note: only crn=False can override it, since crn=True has no effect if ss.options.crn=False)	None
**kwargs		passed to each ss.random() instance

Examples

multi = ss.multi_random('source', 'target')
rvs = multi.rvs(source_uids, target_uids)

Methods

Name	Description
combine2_rvs	Fast path for the common two-distribution case (avoids nb.typed.List, ~550us/call)
combine_rvs	Combine the random numbers of each distribution into one, by bitwise XOR of their bits
init	Initialize each distribution; not usually needed, since the sim does it
jump	Move each distribution on to its next random numbers; not usually needed, since the sim does it
reset	Reset each distribution; not usually needed, since the sim does it
rvs	One random number between 0 and 1 for each pair (or group) of agents

combine2_rvs

distributions.multi_random.combine2_rvs(a, b, int_type, int_max)

Fast path for the common two-distribution case (avoids nb.typed.List, ~550us/call)

combine_rvs

distributions.multi_random.combine_rvs(rvs_list, int_type, int_max)

Combine the random numbers of each distribution into one, by bitwise XOR of their bits

init

distributions.multi_random.init(*args, **kwargs)

Initialize each distribution; not usually needed, since the sim does it

Parameters

Name	Type	Description	Default
args	list	passed to the init() of each distribution
kwargs	dict	passed to the init() of each distribution

jump

distributions.multi_random.jump(*args, **kwargs)

Move each distribution on to its next random numbers; not usually needed, since the sim does it

Parameters

Name	Type	Description	Default
args	list	passed to the jump() of each distribution
kwargs	dict	passed to the jump() of each distribution

reset

distributions.multi_random.reset(*args, **kwargs)

Reset each distribution; not usually needed, since the sim does it

Parameters

Name	Type	Description	Default
args	list	passed to the reset() of each distribution
kwargs	dict	passed to the reset() of each distribution

rvs

distributions.multi_random.rvs(*args)

One random number between 0 and 1 for each pair (or group) of agents

Parameters

Name	Type	Description	Default
args	list	the UIDs for each distribution, in order, e.g. the sources and the targets

nbinom

distributions.nbinom(n=1, p=None, mean=None, **kwargs)

Negative binomial distribution, given by n and p, or by n and the mean

With the mean, n is the dispersion: the variance is mean + mean²/n, so a smaller n is more overdispersed, and a large n is close to a Poisson distribution.

Parameters

Name	Type	Description	Default
n	float	the number of successes, > 0 (default 1); with mean, the dispersion	1
p	float	the probability of success in [0,1], (default 0.5)	None
mean	float	the mean, instead of p (which is then n/(n + mean))	None

Examples

ss.nbinom(n=3, p=0.5) # A mean of 3
ss.nbinom(mean=20, n=0.5) # A mean of 20 and a variance of 820

Methods

Name	Description
ppf	The inverse CDF, compiled (see ss.solvers.backends.draws); SciPy’s above a mean of 30, and for unusual parameters
sync_pars	Convert the mean (if given) to p, then translate to SciPy

ppf

distributions.nbinom.ppf(rands)

The inverse CDF, compiled (see ss.solvers.backends.draws); SciPy’s above a mean of 30, and for unusual parameters

sync_pars

distributions.nbinom.sync_pars()

Convert the mean (if given) to p, then translate to SciPy

normal

distributions.normal(mean=0.0, std=1.0, **kwargs)

Normal distribution

Parameters

Name	Type	Description	Default
mean	float	the mean of the distribution (default 0.0)	0.0
std	float	the standard deviation of the distribution (default 1.0)	1.0

Examples

ss.normal(5, 1) # A mean of 5 and a standard deviation of 1
ss.normal(mean=ss.days(8), std=ss.days(2))

Methods

Name	Description
ppf	The inverse CDF: the same arithmetic as SciPy’s, without its checking of the arguments, which is most of the cost of a small draw
sync_pars	Translate to SciPy’s names

ppf

distributions.normal.ppf(rands)

The inverse CDF: the same arithmetic as SciPy’s, without its checking of the arguments, which is most of the cost of a small draw

sync_pars

distributions.normal.sync_pars()

Translate to SciPy’s names

poisson

distributions.poisson(mean=1.0, **kwargs)

Poisson distribution

Note: unlike rate-based distributions, a plain-number mean is not automatically scaled by dt. If using this distribution in a context where dt != 1, give the mean as a rate (e.g. ss.poisson(ss.peryear(3))) or scale it manually.

Parameters

Name	Type	Description	Default
mean	float	the mean of the distribution, often written λ (default 1.0)	1.0

Methods

Name	Description
ppf	Fast inverse-CDF sampling for the common-random-number (ppf) path.
sync_pars	Translate to SciPy’s names

ppf

distributions.poisson.ppf(rands)

Fast inverse-CDF sampling for the common-random-number (ppf) path.

SciPy’s generic discrete ppf is very slow (it root-finds per element), and for CRN draws it is called every time an ss.poisson is sampled by UID. For a scalar mean we instead precompute the CDF once and map each uniform via np.searchsorted, which is 30-60x faster and produces bitwise-identical results. An array-valued mean is inverted by ss.solvers.backends.draws (SciPy’s above a mean of 30, and for unusual values).

sync_pars

distributions.poisson.sync_pars()

Translate to SciPy’s names

randint

distributions.randint(*args, low=None, high=None, dtype=None, **kwargs)

Random integer distribution, on the interval [low, high)

Parameters

Name	Type	Description	Default
low	int	the lower bound of the distribution (default 0)	None
high	int	the upper bound of the distribution (default: the largest integer of ss.dtypes.rand_int, 2,147,483,647 by default)	None
dtype	type	the data type of the values	None

Attributes

Name	Description
hash_dtype	Use float64 uniforms for wide ranges, since float32 only gives 2^24 distinct values

Methods

Name	Description
convert_timepars	The bounds of a random integer can’t have units

convert_timepars

distributions.randint.convert_timepars()

The bounds of a random integer can’t have units

random

distributions.random(dtype=None, **kwargs)

Random distribution, with values on the interval (0, 1): the raw uniform draws, for code that uses them directly

Its values are those of ss.uniform() with its defaults, but it cannot be scaled or given a unit, and it can be given a dtype (e.g. float32); for a value between bounds, or with a unit, use ss.uniform().

Parameters

Name	Type	Description	Default
dtype	type	the data type of the values (default: ss.dtypes.float)	None
kwargs	dict	passed to ss.Dist

truncnorm

distributions.truncnorm(mean=0.0, std=1.0, low=-np.inf, high=np.inf, **kwargs)

Normal distribution truncated to an interval

Parameters

Name	Type	Description	Default
mean	float	the mean of the normal distribution before truncation (default 0.0)	0.0
std	float	its standard deviation (default 1.0)	1.0
low	float	the lowest value (default -inf)	-np.inf
high	float	the highest value (default inf)	np.inf

Examples

ss.truncnorm(2.5, 0.5, low=1.0, high=4.0, strict=False).rvs(1000)

Methods

Name	Description
ppf	The inverse CDF: a uniform draw between the normal’s CDF at the two ends

ppf

distributions.truncnorm.ppf(rands)

The inverse CDF: a uniform draw between the normal’s CDF at the two ends

uniform

distributions.uniform(low=None, high=None, **kwargs)

Uniform distribution, values on interval (low, high); with one argument, it is the upper bound (ss.uniform(5) is between 0 and 5)

Parameters

Name	Type	Description	Default
low	float	the lower bound of the distribution (default 0.0)	None
high	float	the upper bound of the distribution (default 1.0)	None

Methods

Name	Description
make_rvs	Scaled from the raw uniform draws, which are in Starsim’s precision (NumPy’s uniform takes no dtype)

make_rvs

distributions.uniform.make_rvs()

Scaled from the raw uniform draws, which are in Starsim’s precision (NumPy’s uniform takes no dtype)

weibull

distributions.weibull(shape=1.0, scale=1.0, *, loc=0.0, **kwargs)

Weibull distribution (specifically, scipy.stats.weibull_min)

Parameters

Name	Type	Description	Default
shape	float	the shape parameter, sometimes called k (default 1.0)	1.0
scale	float	the scale parameter, sometimes called λ (default 1.0)	1.0
loc	float	a shift of the whole distribution, e.g. a shortest duration (default 0.0), as SciPy’s loc; by keyword only, so ss.weibull(2, 5) is a shape and a scale	0.0

Examples

ss.weibull(shape=1.4, scale=ss.days(8))

Methods

Name	Description
make_rvs	Use SciPy rather than NumPy to include the scale parameter
ppf	The inverse CDF, compiled (see ss.solvers.backends.draws); SciPy’s for unusual parameters
sync_pars	Translate to SciPy’s names

make_rvs

distributions.weibull.make_rvs()

Use SciPy rather than NumPy to include the scale parameter

ppf

distributions.weibull.ppf(rands)

The inverse CDF, compiled (see ss.solvers.backends.draws); SciPy’s for unusual parameters

sync_pars

distributions.weibull.sync_pars()

Translate to SciPy’s names

Functions

Name	Description
combine_rands	Combine two arrays of random integers into one array of random numbers between 0 and 1, e.g. one for each pair of agents
erlang	Erlang distribution: the sum of k exponential stages, given by its number of stages and its mean

combine_rands

distributions.combine_rands(a, b)

Combine two arrays of random integers into one array of random numbers between 0 and 1, e.g. one for each pair of agents

See ss.multi_random(), which is the version to use in almost all cases.

Inputs must be uint64: signed integers would produce output in [-0.5, 0.5] rather than [0, 1], so they raise an error rather than being cast, since casting would silently copy the array. To reinterpret existing bits for free, use arr.view(np.uint64).

Parameters

Name	Type	Description	Default
a	array	array of random uint64 integers between 0 and np.iinfo(np.uint64).max, as from ss.randint(low=0, high=np.iinfo(‘uint64’).max, dtype=np.uint64)	required
b	array	ditto, same size as a	required

Returns

Name	Type	Description
		A new array of uniformly distributed random numbers in [0, 1], the same size as a and b

erlang

distributions.erlang(k=1, mean=1.0, **kwargs)

Erlang distribution: the sum of k exponential stages, given by its number of stages and its mean

This is ss.gamma with an integer shape: ss.erlang(k=3, mean=10) is ss.gamma(shape=3, scale=10/3). As a dwell time, it has an exact compartmental form (k sub-stages), so runs the same under every solver.

Parameters

Name	Type	Description	Default
k	int	the number of stages (the shape parameter)	1
mean	float	the mean of the distribution (not of each stage; with loc=, a shift, the mean of the whole distribution)	1.0
kwargs	dict	passed to ss.gamma()

Examples

ss.erlang(k=3, mean=ss.days(10))