tlo.simulation module

The main simulation controller.

class Simulation(*, start_date: Timestamp, seed: int | None = None, log_config: dict | None = None, show_progress_bar=False)

Bases: object

The main control centre for a simulation.

This class contains the core simulation logic and event queue, and holds references to all the information required to run a complete simulation: the population, disease modules, etc.

Key attributes include:

date

The current simulation date.

modules

A list of the disease modules contributing to this simulation.

population

The Population being simulated.

rng

The simulation-level random number generator. Note that individual modules also have their own random number generator with independent state.

configure_logging(filename: str | None = None, directory: Path | str = './outputs', custom_levels: Dict[str, int] | None = None, suppress_stdout: bool = False)

Configure logging, can write logging to a logfile in addition the default of stdout.

Minimum custom levels for each logger can be specified for filtering out messages

Parameters:

• filename – Prefix for logfile name, final logfile will have a datetime appended

• directory – Path to output directory, default value is the outputs folder.

• custom_levels – dictionary to set logging levels, ‘*’ can be used as a key for all registered modules. This is likely to be used to disable all disease modules, and then enable one of interest e.g. {'*': logging.CRITICAL 'tlo.methods.hiv': logging.INFO}

• suppress_stdout – If True, suppresses logging to standard output stream (default is False)

Returns:

Path of the log file if a filename has been given.

property log_filepath

The path to the log file, if one has been set.

register(*modules, sort_modules=True, check_all_dependencies=True)

Register one or more disease modules with the simulation.

Parameters:

• modules – the disease module(s) to use as part of this simulation. Multiple modules may be given as separate arguments to one call.

• sort_modules – Whether to topologically sort the modules so that any initialisation dependencies (specified by the INIT_DEPENDENCIES attribute) of a module are initialised before the module itself is. A ModuleDependencyError exception will be raised if there are missing initialisation dependencies or circular initialisation dependencies between modules that cannot be resolved. If this flag is set to True there is also a requirement that at most one instance of each module is registered and MultipleModuleInstanceError will be raised if this is not the case.

• check_all_dependencies – Whether to check if all of each module’s declared dependencies (that is, the union of the INIT_DEPENDENCIES and ADDITIONAL_DEPENDENCIES attributes) have been included in the set of modules to be registered. A ModuleDependencyError exception will be raised if there are missing dependencies.

make_initial_population(*, n)

Create the initial population to simulate.

Parameters:

n – the number of individuals to create; must be given as a keyword parameter for clarity

simulate(*, end_date)

Simulation until the given end date

Parameters:

end_date – when to stop simulating. Only events strictly before this date will be allowed to occur. Must be given as a keyword parameter for clarity.

schedule_event(event, date)

Schedule an event to happen on the given future date.

Parameters:

• event – the Event to schedule

• date – when the event should happen

fire_single_event(event, date)

Fires the event once for the given date

Parameters:

• event – Event to fire

• date – the date of the event

do_birth(mother_id)

Create a new child person.

We create a new person in the population and then call the on_birth method in all modules to initialise the child’s properties.

Parameters:

mother_id – the maternal parent

Returns:

the new child

find_events_for_person(person_id: int)

Find the events in the queue for a particular person. :param person_id: the person_id of interest :returns list of tuples (date_of_event, event) for that person_id in the queue.

NB. This is for debugging and testing only - not for use in real simulations as it is slow

class EventQueue

Bases: object

A simple priority queue for events.

This doesn’t really care what events and dates are, provided dates are comparable.

schedule(event, date)

Schedule a new event.

Parameters:

• event – the event to schedule

• date – when it should happen

next_event()

Get the earliest event in the queue.

Returns:

an (event, date) pair