solvers.engine
Not for the user: the base of the engines that run a declared model (Engine), and what they share
It exists so that the solvers read one model the same way. What it gives modules that act on a disease (Effects) applies to diseases written as code too, through ss.solvers.Undeclared.
Used with: agents and compartments; declared and coded modules
Classes
| Name | Description |
|---|---|
| CountState | A state as it is at run time when it holds a count rather than agents |
| Effects | What the engine of every disease gives the modules that act on it, whether the disease is declared or written as code: the modifiers |
| Engine | Base class for the engines that run a graph |
| StockCtx | Evaluates result expressions (sums and ratios of states, and of flows) from the counts after the step |
CountState
solvers.engine.CountState(engine, state)A state as it is at run time when it holds a count rather than agents
It exists so that code reading a state, such as dis.I, also works in a compartmental run.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| engine | Engine | the engine that holds the values | required |
| state | ss.State |
the declared state | required |
Attributes
| Name | Description |
|---|---|
| frac | The number in this state as a fraction of the module’s people |
| n | The number in this state |
| raw | Each agent’s value, which a compartmental run does not have |
| uids | Agents, which a compartmental run does not have |
| values | The number in this state in each group |
Methods
| Name | Description |
|---|---|
| count | The number in this state, as .n (the same spelling as agents have, where count() is the number of agents) |
| no_agents | A read of agents, which a compartmental run does not have (e.g. a module that reads each person’s state, run beside the compartments) |
count
solvers.engine.CountState.count()The number in this state, as .n (the same spelling as agents have, where count() is the number of agents)
no_agents
solvers.engine.CountState.no_agents(what)A read of agents, which a compartmental run does not have (e.g. a module that reads each person’s state, run beside the compartments)
Effects
solvers.engine.Effects(module, sim)What the engine of every disease gives the modules that act on it, whether the disease is declared or written as code: the modifiers and products active on its quantities (mult_raw(), contact_mult()), for the people their conditions select (selector), in the sim’s unit
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| module | ss.Module |
the module | required |
| sim | ss.Sim |
the sim | required |
Attributes
| Name | Description |
|---|---|
| dt | The module’s timestep, in the sim’s unit (worked out again only if the timestep is replaced) |
| selector | Evaluates conditions for this module: see ss.conditions.Selector |
Methods
| Name | Description |
|---|---|
| clip | A modified rate, duration, or multiplier that has gone below 0 (e.g. by add=) is 0; the first time, a note says so, and sim.what_modifies() reports it |
| contact_mult | The multiplier on the contacts of a network from the modifiers of its n_contacts (e.g. ss.modify('school.pars.n_contacts', multiply=0.2)): 1 if it has none |
| convert | Convert a typed quantity to a plain number in the sim’s unit: a duration to units, a rate to per unit; each is converted once, unless its number is changed |
| current_par | A parameter with the modifiers active on it, in its own type: one value, or, if they differ between people, one for each of uids (see ss.Disease.current_value()) |
| init_pars | For a module written as code: the parameters its code reads from self.pars, with their base values, which have modifiers (see write_pars()) |
| mult_raw | The multiplier on a quantity that is not a parameter (rel_sus, rel_trans, or a transition’s rate) from the modifiers active on it, at least 0 (1 if there are none) |
| reduce | A modified value as the engine uses it; see the subclasses |
| reset_pars | Parameters are back to their base values after the run |
| unapplied_par | Why a module written as code would not apply the modifiers (mods) on a parameter, or None if it would |
| write_pars | Put the modified value of each of these parameters in self.pars, which is what the module’s code reads |
clip
solvers.engine.Effects.clip(value, path)A modified rate, duration, or multiplier that has gone below 0 (e.g. by add=) is 0; the first time, a note says so, and sim.what_modifies() reports it
contact_mult
solvers.engine.Effects.contact_mult(name)The multiplier on the contacts of a network from the modifiers of its n_contacts (e.g. ss.modify('school.pars.n_contacts', multiply=0.2)): 1 if it has none
convert
solvers.engine.Effects.convert(val)Convert a typed quantity to a plain number in the sim’s unit: a duration to units, a rate to per unit; each is converted once, unless its number is changed
current_par
solvers.engine.Effects.current_par(name, uids=None)A parameter with the modifiers active on it, in its own type: one value, or, if they differ between people, one for each of uids (see ss.Disease.current_value())
init_pars
solvers.engine.Effects.init_pars()For a module written as code: the parameters its code reads from self.pars, with their base values, which have modifiers (see write_pars())
mult_raw
solvers.engine.Effects.mult_raw(kind, name=None, state=None)The multiplier on a quantity that is not a parameter (rel_sus, rel_trans, or a transition’s rate) from the modifiers active on it, at least 0 (1 if there are none)
reduce
solvers.engine.Effects.reduce(value, state=None, what=None)A modified value as the engine uses it; see the subclasses
reset_pars
solvers.engine.Effects.reset_pars()Parameters are back to their base values after the run
unapplied_par
solvers.engine.Effects.unapplied_par(name, mods)Why a module written as code would not apply the modifiers (mods) on a parameter, or None if it would
write_pars
solvers.engine.Effects.write_pars()Put the modified value of each of these parameters in self.pars, which is what the module’s code reads
Engine
solvers.engine.Engine(module, sim, solver=None)Base class for the engines that run a graph
It exists to keep what does not depend on the solver in one place.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| module | ss.Module |
the module whose graph is run | required |
| sim | ss.Sim |
the sim | required |
| solver | str |
the solver it is laid out for, if not the sim’s (the ODE, when it is laid out to choose the solver: see ss.solvers.choose.lay_out()) |
None |
Attributes
| Name | Description |
|---|---|
| carriage | The strain dimension, if its levels include people who carry several strains at once (see ss.dimensions.Strat.init_carriage()) |
| inferred_unit | Whether the sim’s unit was worked out from the typed values in the model, rather than given with unit= (see ss.solvers.choose.init_unit()) |
| net_mods | The modifiers of the contacts of networks |
| ti | The time point the engine takes people’s state at: the start of the step being taken, the loop’s ti. |
Methods
| Name | Description |
|---|---|
| act_hazards | The hazard per act, −ln(1 − p), of a probability per act on a network, in each of its directions (one if it has no sides): an array of directions, or of directions by groups |
| adjusted_rel | The multiplier on rel_trans or rel_sus for each group in a state, from the multipliers by level of the stratifications (a strain’s): see the subclasses |
| arrive | Add the people who arrive in a step |
| at_points | The values of something that varies in time at each time point, as results read them: an array over the steps (and over the groups, for an ss.by) |
| attr | The value of an attribute, as an expression reads it |
| backfill_burnin | Place the people part way through at the start (see ss.Pregnancy’s burnin=) |
| bare_return | A function for a rate or a duration that returns a bare number, when the unit is inferred from the typed values, raises rather than guess its unit (0 is 0 in any unit) |
| branch_fracs | The probability of each branch out of a state, with their modifiers |
| branch_mult | The multiplier on a branch’s probability from its modifiers (for some agents, if uids are given), or None if it has none |
| branch_mult_of | As branch_mult(), by name: a transition, or one destination of a transition with several ('progression.C'); with the multipliers by level of the stratifications (a strain’s) on a branch |
| branch_probs | The probability of each destination of a transition (1 if there is only one), from its p= or the expressions given for them |
| by_dims | The dimensions of the sim that the values by level (ss.by) in an expression are given for, as indices; with space=False, not the places |
| by_group | Expand a value for each level of one or more dimensions to a value for each group, once a step |
| by_levels | The values of ss.by(dim=fn) (ss.parameters.by_func) this step, as a number or an ss.by, once a step |
| call | Call a user function of the sim: once a step, if it takes only the sim |
| call_uids | Call a function that takes uids |
| can_infect | Whether a transmission can infect the people of each group (with a coefficient above 0 for them) |
| can_take | Whether people at some levels of a strain dimension whose levels carry several strains are changed by infection with a strain: if they do not carry it, and there is a level for carrying it as well |
| check_counted_strains | With strains, an acquisition whose rate counts the disease’s own states (beta*I.frac, beta*I.n) would give each new |
| check_frac | Check a fraction given with init=: more than 1 raises, and a whole number 1 is everyone, with a warning to write 1.0 (or init_n= for one person) |
| check_modifier_levels | A modifier whose amount is a value by level (ss.modify(sir.recovery, multiply=ss.by(severity=[1, 2]))) of a dimension that the people it is for have no level of: there is no level to take, so it is an error, as for a value by level in a rate |
| check_short | Warn, once, if events of a movement register asked for more people than there were |
| clear_flows | Start counting flows afresh: at the end of each step, once its flows are recorded, and after the initialization (whose moves are part of the state at the start, not a flow); so anything moved between steps (e.g. by disease.infect() after sim.run(until=...)) is counted in the next step |
| clock | The value of a clock (X.time_in), as an expression reads it |
| count | The number of people in some states, in all or by group |
| count_expr | The value of a count in a rate (I.n, I.total, I.frac), with another disease’s states counted by that disease |
| count_matrices | The contact matrices that act on a count in a rate, as this engine has them (see ss.solvers.Mixing.count_terms()); by the engines |
| count_stocks | Count the number in each state now: after the initialization, and at the end of each step, which the next step’s record_states() records as the state at its start |
| count_weighted | A weighted count ((ss.by(biting=w)*I).n, A.n_infectious: see ss.expressions.Count), in the same place as whoever it is evaluated for; by the engines |
| define | Put the run-time form of the declared states on the module, and make its distributions |
| density_rate | For an acquisition at a rate on counts of people: how many people a day one infectious person would infect if everyone were |
| derived_groups | The index of each (group, level) pair among the results by a derived stratification |
| dest_fracs | The probability of each destination of a transition with several, with the modifiers of each ('progression.C', 'outcome.dead'), as branch_fracs() does for branches |
| die_frac | The probability of ss.dead in a split (0 if it is not one of the destinations), given the fractions of its states: what they leave over, less what ss.stay takes |
| dim_map | Where the people who leave one state land in another, when the two do not have the same dimensions |
| dwell_mean | The current mean dwell time of a transition, in the sim’s unit |
| dwell_mods | The modifiers of a dwell time’s parameter when it is a distribution (e.g. ss.modify('sir.pars.dur_inf', set=ss.constant(ss.years(5)))), as agents: |
| enters | Whether a transition with one destination takes people into a dimension that the state they leave does not have, so is recorded at the destination’s level |
| evaluating | Evaluate a block with some of the engine’s flags set (e.g. with self.evaluating(by_group=True):), restored after it: see Evaluating |
| exposure | Exposure to the people in a state |
| finalize_results | Once the results are final (and scaled: see ss.Result._apply_scale()), say where chance would matter |
| find_results | What the results are written to, found once (results are not added during the run) |
| force | Move people to a state now, by a delivery; returns how many moved |
| held_frac | The fraction holding a product, as an expression reads it |
| held_value | A value that varies in time (or an ss.by of them, for each group), at the start of the current step, or at a year within it (see Compartmental.at_middle()): worked out for every step at once, the first time it is needed (as in Compartmental.tables()), rather than at each call |
| inflow_dims | The dimensions an inflow with a rate is given at, so arrives at the same level (see inflow_split()): those of its values by level, and the places, if it uses the number in one |
| inflow_split | Where an inflow arrives: people are born into the youngest group, and a count into the groups of its own dimensions |
| init_adjust | The multiplier on each transition in each group, from the multipliers by level of every stratification (a strain’s) |
| init_derived_results | Results by a stratification of a derived attribute (e.g. hiv.stratify(cd4=[0, 200, 500])), which adds no |
| init_dims | Work out which dimensions each state has |
| init_dwell_mods | The modifiers of each dwell time (see dwell_mods()), once every module has registered its modifiers (see Sim._init_modules_pre()): after the layout, which may be made before them, to choose the solver |
| init_dwells | Work out the dwell-time distribution of every transition that has one |
| init_fractions | The fraction of people who start in each state, and the count in each state that is not people |
| init_immunity | The protection between the strains of a disease with shared states (ss.Strains(immunity=...), see ss.immunity) |
| init_outcomes | Work out the sources and delay of each outcome, and the order to compute them in |
| init_post | Set the starting values, once the people are initialized |
| init_pre | Lay out what the run needs, before the people are initialized |
| init_results | One count per state, one flow per transition (res.infection.cum is its cumulative total), and a result for each expression, outcome, and transfer |
| init_strain_weights | The fraction of the infectiousness of the people at each level of the strain dimension that goes to each strain (levels by strains) |
| local_count | The number in some states as it is used in a rate: in a model with places, the number in the same place |
| make_rng | The random numbers of the engine: stream 0 for draws made in Python, 1 for the kernels, 2 for the events of a register at the start; from the sim’s seed (or the one given) and the module’s name, so no two modules share them |
| met_count | The number of people in some states met through the sim’s contact matrices (Σ_j C_ij·I_j, or Σ_j C_ij·w_j·I_j for a weighted count: see ss.solvers.Mixing.count_terms()), for whoever it is evaluated for; by the engines |
| met_counts | The ids of the counts in rates that the sim’s contact matrices act on (see ss.graph.Graph.met_counts): none if it has none |
| modified | Apply the modifiers that are active on a parameter: set, then multiply, then add |
| mother | The value of an expression for each person’s mother (ss.mother()) |
| move_some | A one-off move from code (ss.move()) |
| move_states | Move people out of some states into another |
| moves | The change of level of a transition with move= or increment=, as ((dimension, level), …), where the level of a counter is (‘+’, amount); or None |
| mult_raw | The multiplier on a quantity that is not a parameter (rel_sus, rel_trans, or a transition’s rate) from its modifiers (once a step), and from the multipliers by level of the stratifications (a strain’s) |
| n_people | The number of people, in all or by group |
| never_taken | Whether a transition to one destination has a branch probability of 0 everywhere (e.g. death in ss.SIR with p_death=0) |
| note_chance | For a run with real numbers (ode): say where chance would matter, as a stochastic run would show |
| note_counter | Note a counter whose levels are not one apart, if it matters to this engine |
| note_fast_steps | See note_steps() |
| note_function_reads | Say when a parameter that a modifier changes is read inside a function, which sees its own value rather than the changed one |
| note_stages | Say how a dwell time that is not exponential or Erlang is approximated; agents draw it as it is (see Compartmental.note_stages()) |
| note_steps | In a run that takes whole steps, say which transitions are fast compared with the timestep: by the parameters’ own values, without their modifiers, which may read what does not exist until the run (e.g. a property of people another module adds) |
| outcome_frac | The events of an outcome from those of one of its sources, times its weight: a fraction of whole events is a draw if draw, and the part of an event left over (from agents who stand for a fraction of a person) is kept as its mean |
| own_moves | The moves of move= and increment=: see moves() |
| per_level | A birth rate per person given for each level of some dimensions (ss.birth(S, rate=ss.by(species=mu))), as the inflow it is: the |
| plain_value | A value written inside another (a direction of ss.peract, or a route of a beta dict) as a number, or a value for each group |
| plausible_density | Whether an acquisition at a rate on counts of people is density-dependent transmission as meant (S >> I @ beta*I.n), rather than a count |
| product_of | The sim’s copy of the product of a fraction holding it (itn.held_frac, see ss.expressions.HeldFrac) |
| prop | The value of a property of people, as an expression reads it |
| protection | The fraction of the force of infection of a strain that reaches people in a state at some levels of the strain dimension, by the strains they carry there (see init_immunity()) |
| record_events | Record the flows of the step, at its index, and the results worked out from them and the states at its start |
| record_states | Record the number in each state at the start of the step, at its index (so R[ti] has the people recovered by time |
| register_sets | For a movement register: the sets of states its events name, with the default (None) first, |
| report_outcome | One step of an outcome: its events in the step (amount, for each group, or each run and group) are reported after |
| route_value | The value of a transmission’s beta on the route it is being worked out for (self._route, as agents): a beta |
| row_stocks | The states by group at the start of the row of several steps that time point ti is in (see ss.solvers.group_rows()), for the results worked out over the row |
| sample | Draw samples from a distribution of durations, in the sim’s unit (used to build delay kernels, not during the run) |
| seed_dist | An init_prev that chooses who starts infected one by one, which only agents have (see Agents.seed_dist()) |
| seed_reach | For seeding through several transmissions (see seed_transmissions()): the fraction of the seeds of each group (or of each agent, with uids) |
| seed_transmissions | The transmissions that init_prev seeds through: those out of the first state (e.g. one for each sex), or the first transmission if none is, or if they all lead to the same states; with none, the first acquisition |
| series_over | The values of something that varies in time at some years, kept under key, as (func, the values of any parameters inside it, which can change between runs, values) |
| set_count | Set the number of people in a state |
| shrink | Drop the sim and the arrays the run worked in, for saving; the results are kept on the module |
| split_events | n events over the slots with chances p: whole events are drawn, and the part of an event left over is kept as its mean, so that small amounts from fractional agents aren’t rounded away |
| split_states | Some states split into this disease’s own and other diseases’ (e.g. syph.I in a rate of HIV), by the name of each other disease |
| start_count | The starting amount of a state that is not people, read from the numbers in other states (e.g. init=m*N): those in the states of people are their fractions of the population |
| start_step | Start the step: values held for the last step are worked out again |
| step | The part of a step after the interventions, including transmission |
| step_funcs | Call the module’s custom per-step functions, after its transitions |
| step_outcomes | Work out this step’s value of each outcome, in each group, from the flows it is counted from |
| step_state | The part of a step before the interventions: what changes with no contact with others |
| stock | The number in a state, as an expression reads it |
| strain_effect | The multiplier on the force of infection of one strain from the products that protect against acquiring it (ss.by(strain=...)): for each agent, or for each group of a state |
| strain_levels | The strains of the module’s strain dimension, if it has one: each has a force of infection of its own |
| strain_rate | The part of a transmission’s rate that comes from one strain |
| superinfects | Whether a transmission leaves people in the state they are in (so only changes the strains they carry) |
| takes_uids | Whether a user function takes the agents (uids), worked out once for each function (see ss.utils.fn_args()) |
| total_count | The number in some states in the whole population, wherever they are (I.total) |
| transfer_dist | The distribution of a transfer’s dur= as numbers in the sim’s unit, if it is not exponential (None if it is a rate, a scalar, or exponential): agents draw it for each person (see Agents.step_transfers()) |
| undefined | The error for a method this engine does not define |
| value | The value of a parameter, as a number in the sim’s unit |
| varying_dwell | A dwell time whose distribution has parameters with a value for each group (ss.by): see each engine’s own |
| weighted_events | An outcome’s amount by group from the people who went through a transition, each with their own weight; None if they are not known (see Agents.weighted_events()) |
| where_frac | For a branch with who=: 1 for the people it is open to and 0 for the others (agents: for uids; compartments: for each group of state, if the condition is on states and strata), or None |
| where_mults | The branches’ multipliers with their who=: a branch is closed to the people (or groups) it does not hold for, so the |
| whole_steps | A time as a number of whole steps |
| with_unrepresented | The number in each state (and by group), as the results count them: with dynamic rescaling (rescale=True), including the people no agent stands for yet |
| write_scale | The scale counts of people are written in, as agents (see ss.results.people_scale()), set on the results that keep values by group |
act_hazards
solvers.engine.Engine.act_hazards(val, route)The hazard per act, −ln(1 − p), of a probability per act on a network, in each of its directions (one if it has no sides): an array of directions, or of directions by groups
adjusted_rel
solvers.engine.Engine.adjusted_rel(kind, state=None)The multiplier on rel_trans or rel_sus for each group in a state, from the multipliers by level of the stratifications (a strain’s): see the subclasses
arrive
solvers.engine.Engine.arrive(*args, **kwargs)Add the people who arrive in a step
at_points
solvers.engine.Engine.at_points(func)The values of something that varies in time at each time point, as results read them: an array over the steps (and over the groups, for an ss.by)
attr
solvers.engine.Engine.attr(a)The value of an attribute, as an expression reads it
backfill_burnin
solvers.engine.Engine.backfill_burnin(sp)Place the people part way through at the start (see ss.Pregnancy’s burnin=)
bare_return
solvers.engine.Engine.bare_return(p, func, out)A function for a rate or a duration that returns a bare number, when the unit is inferred from the typed values, raises rather than guess its unit (0 is 0 in any unit)
branch_fracs
solvers.engine.Engine.branch_fracs(trs, ps, mults)The probability of each branch out of a state, with their modifiers
A modifier on a branch multiplies its probability, and the branches with none share what is left in proportion to their own; if every branch is modified (or the modified ones come to more than 1), they are scaled to sum to 1.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| trs | list |
the transitions (or their names) | required |
| ps | list |
the probability of each, or None for the one that takes the rest | required |
| mults | list |
the multiplier of each, or None for those with no modifiers | required |
branch_mult
solvers.engine.Engine.branch_mult(tr, uids=None)The multiplier on a branch’s probability from its modifiers (for some agents, if uids are given), or None if it has none
branch_mult_of
solvers.engine.Engine.branch_mult_of(name, uids=None)As branch_mult(), by name: a transition, or one destination of a transition with several ('progression.C'); with the multipliers by level of the stratifications (a strain’s) on a branch
branch_probs
solvers.engine.Engine.branch_probs(tr, ps=None)The probability of each destination of a transition (1 if there is only one), from its p= or the expressions given for them
by_dims
solvers.engine.Engine.by_dims(expr, space=True)The dimensions of the sim that the values by level (ss.by) in an expression are given for, as indices; with space=False, not the places
by_group
solvers.engine.Engine.by_group(by)Expand a value for each level of one or more dimensions to a value for each group, once a step
by_levels
solvers.engine.Engine.by_levels(bf)The values of ss.by(dim=fn) (ss.parameters.by_func) this step, as a number or an ss.by, once a step
call
solvers.engine.Engine.call(func, p=None)Call a user function of the sim: once a step, if it takes only the sim
call_uids
solvers.engine.Engine.call_uids(func, p=None)Call a function that takes uids
can_infect
solvers.engine.Engine.can_infect(tr, uids=None)Whether a transmission can infect the people of each group (with a coefficient above 0 for them)
can_take
solvers.engine.Engine.can_take(levels, strain)Whether people at some levels of a strain dimension whose levels carry several strains are changed by infection with a strain: if they do not carry it, and there is a level for carrying it as well
check_counted_strains
solvers.engine.Engine.check_counted_strains()With strains, an acquisition whose rate counts the disease’s own states (beta*I.frac, beta*I.n) would give each new case a strain from the strain set’s split, not from who infected them, since a count carries no strain: refused, with the transmission that says the same (beta*I is the same force under homogeneous mixing, weighted by infectiousness)
check_frac
solvers.engine.Engine.check_frac(state, vals, whole)Check a fraction given with init=: more than 1 raises, and a whole number 1 is everyone, with a warning to write 1.0 (or init_n= for one person)
check_modifier_levels
solvers.engine.Engine.check_modifier_levels()A modifier whose amount is a value by level (ss.modify(sir.recovery, multiply=ss.by(severity=[1, 2]))) of a dimension that the people it is for have no level of: there is no level to take, so it is an error, as for a value by level in a rate
check_short
solvers.engine.Engine.check_short(short)Warn, once, if events of a movement register asked for more people than there were
clear_flows
solvers.engine.Engine.clear_flows()Start counting flows afresh: at the end of each step, once its flows are recorded, and after the initialization (whose moves are part of the state at the start, not a flow); so anything moved between steps (e.g. by disease.infect() after sim.run(until=...)) is counted in the next step
clock
solvers.engine.Engine.clock(clock)The value of a clock (X.time_in), as an expression reads it
count
solvers.engine.Engine.count(states, total=True)The number of people in some states, in all or by group
count_expr
solvers.engine.Engine.count_expr(expr)The value of a count in a rate (I.n, I.total, I.frac), with another disease’s states counted by that disease
count_matrices
solvers.engine.Engine.count_matrices()The contact matrices that act on a count in a rate, as this engine has them (see ss.solvers.Mixing.count_terms()); by the engines
count_stocks
solvers.engine.Engine.count_stocks()Count the number in each state now: after the initialization, and at the end of each step, which the next step’s record_states() records as the state at its start
count_weighted
solvers.engine.Engine.count_weighted(states, expr)A weighted count ((ss.by(biting=w)*I).n, A.n_infectious: see ss.expressions.Count), in the same place as whoever it is evaluated for; by the engines
define
solvers.engine.Engine.define()Put the run-time form of the declared states on the module, and make its distributions
density_rate
solvers.engine.Engine.density_rate(tr)For an acquisition at a rate on counts of people: how many people a day one infectious person would infect if everyone were susceptible (the rate with every count 1, times the population); None if it is not known until the run
derived_groups
solvers.engine.Engine.derived_groups(strat, groups, levels)The index of each (group, level) pair among the results by a derived stratification
dest_fracs
solvers.engine.Engine.dest_fracs(tr, ps, uids=None, ev=None, ends=False)The probability of each destination of a transition with several, with the modifiers of each ('progression.C', 'outcome.dead'), as branch_fracs() does for branches
ss.dead and ss.stay are branches like the states: given a probability, they keep it (scaled with the others if a modifier makes them come to more than 1), and a modifier on one of them scales it. With no destination left to take the rest, it goes to ss.stay if it is one, and otherwise to ss.dead.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| tr | Transition | the transition | required |
| ps | list |
the probability of each of its states, evaluated, or None for the one that takes the rest | required |
| uids | array |
the agents, for an agent engine | None |
| ev | func |
how to evaluate the probabilities of ss.dead and ss.stay (default: self.eval) |
None |
| ends | bool |
whether to return the fractions of ss.dead and ss.stay too, after those of the states (in that order, those that are destinations) | False |
die_frac
solvers.engine.Engine.die_frac(tr, fracs, ev=None, uids=None)The probability of ss.dead in a split (0 if it is not one of the destinations), given the fractions of its states: what they leave over, less what ss.stay takes
dim_map
solvers.engine.Engine.dim_map(src, dst, strain=None, record=False, move=None)Where the people who leave one state land in another, when the two do not have the same dimensions
Returns None if they stay in their own group, or else a matrix of groups by groups: a dimension the destination lacks is dropped, one that only the destination has is entered in proportion to its split, and a new infection takes the strain of its source.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| src | str |
the state they leave (None for an inflow) | required |
| dst | str |
the state they enter | required |
| strain | int |
for a new infection, the strain of the people it came from | None |
| record | bool |
if True, give the groups the flow is recorded in (the source’s, with the strain acquired) | False |
| move | tuple |
for a transition with move=, the level of each dimension people move to: see moves() |
None |
dwell_mean
solvers.engine.Engine.dwell_mean(name)The current mean dwell time of a transition, in the sim’s unit
dwell_mods
solvers.engine.Engine.dwell_mods(name, dw)The modifiers of a dwell time’s parameter when it is a distribution (e.g. ss.modify('sir.pars.dur_inf', set=ss.constant(ss.years(5)))), as agents: dw.mods are the modifiers, and dw.sets the distribution each set= draws from, by the modifier’s index (not its id, which would be in the path its seed is made from) (a duration is the mean of an exponential, as for dur=), with its mean. People who enter the state while one is active draw from it; those already there have what is left of their dwell rescaled by the change in its mean (see Agents.rescale_exits()).
enters
solvers.engine.Engine.enters(tr, src)Whether a transition with one destination takes people into a dimension that the state they leave does not have, so is recorded at the destination’s level
evaluating
solvers.engine.Engine.evaluating(**flags)Evaluate a block with some of the engine’s flags set (e.g. with self.evaluating(by_group=True):), restored after it: see Evaluating
exposure
solvers.engine.Engine.exposure(state)Exposure to the people in a state
finalize_results
solvers.engine.Engine.finalize_results()Once the results are final (and scaled: see ss.Result._apply_scale()), say where chance would matter
find_results
solvers.engine.Engine.find_results()What the results are written to, found once (results are not added during the run)
force
solvers.engine.Engine.force(*args, **kwargs)Move people to a state now, by a delivery; returns how many moved
held_frac
solvers.engine.Engine.held_frac(expr)The fraction holding a product, as an expression reads it
held_value
solvers.engine.Engine.held_value(func, year=None)A value that varies in time (or an ss.by of them, for each group), at the start of the current step, or at a year within it (see Compartmental.at_middle()): worked out for every step at once, the first time it is needed (as in Compartmental.tables()), rather than at each call
inflow_dims
solvers.engine.Engine.inflow_dims(tr)The dimensions an inflow with a rate is given at, so arrives at the same level (see inflow_split()): those of its values by level, and the places, if it uses the number in one
inflow_split
solvers.engine.Engine.inflow_split(tr)Where an inflow arrives: people are born into the youngest group, and a count into the groups of its own dimensions
init_adjust
solvers.engine.Engine.init_adjust()The multiplier on each transition in each group, from the multipliers by level of every stratification (a strain’s)
init_derived_results
solvers.engine.Engine.init_derived_results()Results by a stratification of a derived attribute (e.g. hiv.stratify(cd4=[0, 200, 500])), which adds no groups: the number in each of its states, and each flow out of them, by the level of the attribute (at the source, for a flow), as well as by the sim’s own groups
init_dims
solvers.engine.Engine.init_dims()Work out which dimensions each state has
A state that a dimension does not apply to (a count, or a state left out of states=) is kept at the first level of that dimension.
init_dwell_mods
solvers.engine.Engine.init_dwell_mods()The modifiers of each dwell time (see dwell_mods()), once every module has registered its modifiers (see Sim._init_modules_pre()): after the layout, which may be made before them, to choose the solver
init_dwells
solvers.engine.Engine.init_dwells()Work out the dwell-time distribution of every transition that has one
init_fractions
solvers.engine.Engine.init_fractions()The fraction of people who start in each state, and the count in each state that is not people
init_immunity
solvers.engine.Engine.init_immunity()The protection between the strains of a disease with shared states (ss.Strains(immunity=...), see ss.immunity)
The people in a state given by due_to=R are protected by the strains they carry in it, against each strain: a multiplier for each level of the strain dimension and strain, in protect. A state people are not infected in (R) can be infected again, moving on as from the first state (immune_states); one they are infected in (L) can carry another strain as well (see ss.strains.add_superinfection()).
init_outcomes
solvers.engine.Engine.init_outcomes(results)Work out the sources and delay of each outcome, and the order to compute them in
init_post
solvers.engine.Engine.init_post()Set the starting values, once the people are initialized
init_pre
solvers.engine.Engine.init_pre()Lay out what the run needs, before the people are initialized
init_results
solvers.engine.Engine.init_results()One count per state, one flow per transition (res.infection.cum is its cumulative total), and a result for each expression, outcome, and transfer
init_strain_weights
solvers.engine.Engine.init_strain_weights()The fraction of the infectiousness of the people at each level of the strain dimension that goes to each strain (levels by strains)
Someone who carries one strain passes it on; someone who carries several passes on each in proportion to its infectiousness (its rel_trans); their own infectiousness is that of their level.
local_count
solvers.engine.Engine.local_count(states)The number in some states as it is used in a rate: in a model with places, the number in the same place
make_rng
solvers.engine.Engine.make_rng(stream=0, seed=None)The random numbers of the engine: stream 0 for draws made in Python, 1 for the kernels, 2 for the events of a register at the start; from the sim’s seed (or the one given) and the module’s name, so no two modules share them
met_count
solvers.engine.Engine.met_count(states, expr)The number of people in some states met through the sim’s contact matrices (Σ_j C_ij·I_j, or Σ_j C_ij·w_j·I_j for a weighted count: see ss.solvers.Mixing.count_terms()), for whoever it is evaluated for; by the engines
met_counts
solvers.engine.Engine.met_counts()The ids of the counts in rates that the sim’s contact matrices act on (see ss.graph.Graph.met_counts): none if it has none
modified
solvers.engine.Engine.modified(p, value)Apply the modifiers that are active on a parameter: set, then multiply, then add
mother
solvers.engine.Engine.mother(expr)The value of an expression for each person’s mother (ss.mother())
move_some
solvers.engine.Engine.move_some(*args, **kwargs)A one-off move from code (ss.move())
move_states
solvers.engine.Engine.move_states(*args, **kwargs)Move people out of some states into another
moves
solvers.engine.Engine.moves(tr)The change of level of a transition with move= or increment=, as ((dimension, level), …), where the level of a counter is (‘+’, amount); or None
mult_raw
solvers.engine.Engine.mult_raw(kind, name=None, state=None)The multiplier on a quantity that is not a parameter (rel_sus, rel_trans, or a transition’s rate) from its modifiers (once a step), and from the multipliers by level of the stratifications (a strain’s)
n_people
solvers.engine.Engine.n_people(total=True)The number of people, in all or by group
never_taken
solvers.engine.Engine.never_taken(tr)Whether a transition to one destination has a branch probability of 0 everywhere (e.g. death in ss.SIR with p_death=0)
note_chance
solvers.engine.Engine.note_chance()For a run with real numbers (ode): say where chance would matter, as a stochastic run would show
note_counter
solvers.engine.Engine.note_counter(strat, what)Note a counter whose levels are not one apart, if it matters to this engine
note_fast_steps
solvers.engine.Engine.note_fast_steps()See note_steps()
note_function_reads
solvers.engine.Engine.note_function_reads()Say when a parameter that a modifier changes is read inside a function, which sees its own value rather than the changed one
note_stages
solvers.engine.Engine.note_stages(name, dw)Say how a dwell time that is not exponential or Erlang is approximated; agents draw it as it is (see Compartmental.note_stages())
note_steps
solvers.engine.Engine.note_steps()In a run that takes whole steps, say which transitions are fast compared with the timestep: by the parameters’ own values, without their modifiers, which may read what does not exist until the run (e.g. a property of people another module adds)
outcome_frac
solvers.engine.Engine.outcome_frac(flow, weight, draw)The events of an outcome from those of one of its sources, times its weight: a fraction of whole events is a draw if draw, and the part of an event left over (from agents who stand for a fraction of a person) is kept as its mean
own_moves
solvers.engine.Engine.own_moves(tr)The moves of move= and increment=: see moves()
per_level
solvers.engine.Engine.per_level(rate)A birth rate per person given for each level of some dimensions (ss.birth(S, rate=ss.by(species=mu))), as the inflow it is: the number of people counted by the rate at their level (a weighted count, see ss.expressions.Count), born at that level; a newborn is in the youngest age group and of either sex, so those are the sum over their levels (counts are already in the same place). Returns the rate, and the dimensions whose levels the births are at (for describe()).
plain_value
solvers.engine.Engine.plain_value(val)A value written inside another (a direction of ss.peract, or a route of a beta dict) as a number, or a value for each group
plausible_density
solvers.engine.Engine.plausible_density(tr)Whether an acquisition at a rate on counts of people is density-dependent transmission as meant (S >> I @ beta*I.n), rather than a count written for a fraction: whether one infectious person would infect fewer than 10 people a day in a population with no immunity (measles infects about 2). A beta meant for a fraction (0.3 a day) gives 0.3 × N, which is far more in any population but a handful of people
product_of
solvers.engine.Engine.product_of(expr)The sim’s copy of the product of a fraction holding it (itn.held_frac, see ss.expressions.HeldFrac)
prop
solvers.engine.Engine.prop(cond)The value of a property of people, as an expression reads it
protection
solvers.engine.Engine.protection(state, levels, strain)The fraction of the force of infection of a strain that reaches people in a state at some levels of the strain dimension, by the strains they carry there (see init_immunity())
record_events
solvers.engine.Engine.record_events()Record the flows of the step, at its index, and the results worked out from them and the states at its start
record_states
solvers.engine.Engine.record_states()Record the number in each state at the start of the step, at its index (so R[ti] has the people recovered by time point ti, before the step from it, whose recoveries are recovery[ti]); they are kept for the results worked out with the flows of the step (see record_events())
register_sets
solvers.engine.Engine.register_sets()For a movement register: the sets of states its events name, with the default (None) first, and for each, the states of this module that people are chosen from and that people are added to
A state that the register names must belong to some module of the sim; one that is not in this module is left out, and a module with none of the states of a set uses its default.
report_outcome
solvers.engine.Engine.report_outcome(info, buf, amount, ti, draw)One step of an outcome: its events in the step (amount, for each group, or each run and group) are reported after its delay, and stay in it for its duration, each drawn for each event if draw. buf keeps the events still to be reported (pending) and to leave (leaving), each a ring over the next steps, and the number in the outcome (n). A step at a time for step_outcomes(), and over the steps of a whole run for Compartmental.derived_outcomes(), so the two draw the same. Returns the events reported in the step.
route_value
solvers.engine.Engine.route_value(p, raw)The value of a transmission’s beta on the route it is being worked out for (self._route, as agents): a beta for each route gives its value for this one; on a network with acts, a probability per act (ss.peract, or a bare number) gives the hazard per act, −ln(1 − p), in each of the network’s directions (see act_hazards())
row_stocks
solvers.engine.Engine.row_stocks(stock_groups, ti)The states by group at the start of the row of several steps that time point ti is in (see ss.solvers.group_rows()), for the results worked out over the row
sample
solvers.engine.Engine.sample(dist, n)Draw samples from a distribution of durations, in the sim’s unit (used to build delay kernels, not during the run)
seed_dist
solvers.engine.Engine.seed_dist()An init_prev that chooses who starts infected one by one, which only agents have (see Agents.seed_dist())
seed_reach
solvers.engine.Engine.seed_reach(trs, uids=None)For seeding through several transmissions (see seed_transmissions()): the fraction of the seeds of each group (or of each agent, with uids) that each takes, equal among those that can infect them (a coefficient above 0 for them), e.g. a transmission to women only seeds women
seed_transmissions
solvers.engine.Engine.seed_transmissions()The transmissions that init_prev seeds through: those out of the first state (e.g. one for each sex), or the first transmission if none is, or if they all lead to the same states; with none, the first acquisition
series_over
solvers.engine.Engine.series_over(func, years, key)The values of something that varies in time at some years, kept under key, as (func, the values of any parameters inside it, which can change between runs, values)
set_count
solvers.engine.Engine.set_count(state, value)Set the number of people in a state
shrink
solvers.engine.Engine.shrink()Drop the sim and the arrays the run worked in, for saving; the results are kept on the module
split_events
solvers.engine.Engine.split_events(n, p)n events over the slots with chances p: whole events are drawn, and the part of an event left over is kept as its mean, so that small amounts from fractional agents aren’t rounded away
split_states
solvers.engine.Engine.split_states(states)Some states split into this disease’s own and other diseases’ (e.g. syph.I in a rate of HIV), by the name of each other disease
start_count
solvers.engine.Engine.start_count(name, init, fracs, counts, later)The starting amount of a state that is not people, read from the numbers in other states (e.g. init=m*N): those in the states of people are their fractions of the population
start_step
solvers.engine.Engine.start_step()Start the step: values held for the last step are worked out again
step
solvers.engine.Engine.step()The part of a step after the interventions, including transmission
step_funcs
solvers.engine.Engine.step_funcs()Call the module’s custom per-step functions, after its transitions
step_outcomes
solvers.engine.Engine.step_outcomes()Work out this step’s value of each outcome, in each group, from the flows it is counted from
step_state
solvers.engine.Engine.step_state()The part of a step before the interventions: what changes with no contact with others
stock
solvers.engine.Engine.stock(state)The number in a state, as an expression reads it
strain_effect
solvers.engine.Engine.strain_effect(strain, state=None)The multiplier on the force of infection of one strain from the products that protect against acquiring it (ss.by(strain=...)): for each agent, or for each group of a state
strain_levels
solvers.engine.Engine.strain_levels()The strains of the module’s strain dimension, if it has one: each has a force of infection of its own
strain_rate
solvers.engine.Engine.strain_rate(tr, rate, strain)The part of a transmission’s rate that comes from one strain
superinfects
solvers.engine.Engine.superinfects(tr, state)Whether a transmission leaves people in the state they are in (so only changes the strains they carry)
takes_uids
solvers.engine.Engine.takes_uids(func)Whether a user function takes the agents (uids), worked out once for each function (see ss.utils.fn_args())
total_count
solvers.engine.Engine.total_count(states)The number in some states in the whole population, wherever they are (I.total)
transfer_dist
solvers.engine.Engine.transfer_dist(tf, per_agent=None)The distribution of a transfer’s dur= as numbers in the sim’s unit, if it is not exponential (None if it is a rate, a scalar, or exponential): agents draw it for each person (see Agents.step_transfers())
undefined
solvers.engine.Engine.undefined(name)The error for a method this engine does not define
value
solvers.engine.Engine.value(p)The value of a parameter, as a number in the sim’s unit
varying_dwell
solvers.engine.Engine.varying_dwell(name, tr, raw, dw, to_unit)A dwell time whose distribution has parameters with a value for each group (ss.by): see each engine’s own
weighted_events
solvers.engine.Engine.weighted_events(key, weight, integer)An outcome’s amount by group from the people who went through a transition, each with their own weight; None if they are not known (see Agents.weighted_events())
where_frac
solvers.engine.Engine.where_frac(tr, state, uids=None)For a branch with who=: 1 for the people it is open to and 0 for the others (agents: for uids; compartments: for each group of state, if the condition is on states and strata), or None
where_mults
solvers.engine.Engine.where_mults(branches, state, mults, uids=None)The branches’ multipliers with their who=: a branch is closed to the people (or groups) it does not hold for, so the others share the rest; but if every branch is closed to someone, they are split as before and wait until one opens
whole_steps
solvers.engine.Engine.whole_steps(*args, **kwargs)A time as a number of whole steps
with_unrepresented
solvers.engine.Engine.with_unrepresented()The number in each state (and by group), as the results count them: with dynamic rescaling (rescale=True), including the people no agent stands for yet
Each agent stands for scale people; the people no agent stands for (sim.results.unrepresented, see ss.Sim.rescale()) are like the agents, and are shared out as the agents alive are, in agents (as the other counts are, before they are scaled). For a disease, which rescaling makes naive again, they have never been infected, so their fraction is in its first state; for another module (e.g. ss.Pregnancy), each state has its fraction. The engine’s own stocks (used in the dynamics) are untouched.
write_scale
solvers.engine.Engine.write_scale()The scale counts of people are written in, as agents (see ss.results.people_scale()), set on the results that keep values by group
StockCtx
solvers.engine.StockCtx(engine, stocks=None, flows=None, ti=None)Evaluates result expressions (sums and ratios of states, and of flows) from the counts after the step
It exists so that results are worked out the same way for every solver.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| engine | ss.solvers.Engine |
the engine | required |
| stocks | dict |
the number in each state: one number for the current step (the default), or an array over the steps | None |
| flows | dict |
the same for the flow along each transition | None |
| ti | int / array |
the time point, for one step, or for stocks by group, the time point of each row; if None, an array over the steps | None |
Methods
| Name | Description |
|---|---|
| flow | The number of people who made a transition in the step |
| stock | The number of people (or the count) in a state |
| value | A parameter’s value; one that varies in time is taken at the time point of the result, for a whole run or a step, whichever moment a rate reads it at |
flow
solvers.engine.StockCtx.flow(flow)The number of people who made a transition in the step
stock
solvers.engine.StockCtx.stock(state)The number of people (or the count) in a state
value
solvers.engine.StockCtx.value(p)A parameter’s value; one that varies in time is taken at the time point of the result, for a whole run or a step, whichever moment a rate reads it at
Functions
| Name | Description |
|---|---|
| add_rows | Add values at consecutive time points tis (along the first axis of vals) into the rows of out they belong to: see ss.solvers.group_rows() |
| at_starts | Put the values at the time points among tis that start a row into that row of out |
| by_level | The positions of the entries at each of n levels, as where each level’s start and end, and the positions in order (np.flatnonzero(levels == i) for each level, by one sort) |
| convert | Convert a typed quantity to a plain number in a unit: a duration to units, a rate to per unit; with a cache (a dict), each is converted once, unless its number is changed |
| group_rows | The time points at which results are kept by group: each one, or the start of every few steps if each one would take more than budget bytes |
| init_people | In a compartmental run, the results that agents give the sim (alive, died, emigrated), made with the other results, so they can be read during the run, as with agents; filled in as the declared modules record theirs (see record_people()) |
| kept_by_group | Whether a result of a module is kept by group: every one, unless the sim parameter group_results names the ones to keep (by name, or as “module.name”) |
| people_counts | The number alive, the deaths, and the emigrants of a compartmental sim, from the results of its declared modules, as get(mod, key) gives them (of one run, or of many with a run axis first); or None if it has no people |
| record_people | In a compartmental run, the results that agents give the sim (alive, died, emigrated), from the declared states and flows: at every time point, or at ti (only keys, if given) |
add_rows
solvers.engine.add_rows(out, rows, tis, vals)Add values at consecutive time points tis (along the first axis of vals) into the rows of out they belong to: see ss.solvers.group_rows()
at_starts
solvers.engine.at_starts(out, rows, starts, tis, vals)Put the values at the time points among tis that start a row into that row of out
by_level
solvers.engine.by_level(levels, n)The positions of the entries at each of n levels, as where each level’s start and end, and the positions in order (np.flatnonzero(levels == i) for each level, by one sort)
convert
solvers.engine.convert(val, unit, cache=None)Convert a typed quantity to a plain number in a unit: a duration to units, a rate to per unit; with a cache (a dict), each is converted once, unless its number is changed
group_rows
solvers.engine.group_rows(sim, npts, row_bytes, budget, name=None)The time points at which results are kept by group: each one, or the start of every few steps if each one would take more than budget bytes
The number of steps between them is the shortest of a week, two weeks, four weeks, a quarter, half a year, or a year (or of 2, 5, 10, 20, … steps for a sim with no unit, or one longer than a day) that keeps them within the budget. A row of values by group then holds a flow added up over its steps, and anything else as it is at the start of them (so a ratio of states is the ratio then). See ss.Result.select().
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| npts | int |
the number of time points | required |
| row_bytes | float |
the memory the results take at each time point | required |
| budget | float |
the most memory they may take | required |
| name | str |
the module whose results they are, to say so in a note | None |
Returns the row of each time point and the time point each row starts at, or (None, None) for every time point.
init_people
solvers.engine.init_people(sim)In a compartmental run, the results that agents give the sim (alive, died, emigrated), made with the other results, so they can be read during the run, as with agents; filled in as the declared modules record theirs (see record_people())
kept_by_group
solvers.engine.kept_by_group(sim, mod, key)Whether a result of a module is kept by group: every one, unless the sim parameter group_results names the ones to keep (by name, or as “module.name”)
people_counts
solvers.engine.people_counts(sim, get)The number alive, the deaths, and the emigrants of a compartmental sim, from the results of its declared modules, as get(mod, key) gives them (of one run, or of many with a run axis first); or None if it has no people
record_people
solvers.engine.record_people(sim, ti=None, keys=None)In a compartmental run, the results that agents give the sim (alive, died, emigrated), from the declared states and flows: at every time point, or at ti (only keys, if given)