tlo.simulation module¶
The main simulation controller.
- class Simulation(*, start_date: Timestamp, seed: Optional[int] = None, log_config: Optional[dict] = None, show_progress_bar=False)[source]¶
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: Optional[str] = None, directory: Union[Path, str] = './outputs', custom_levels: Optional[Dict[str, int]] = None, suppress_stdout: bool = False)[source]¶
Configure logging, can write logging to a logfile in addition the default of stdout.
Minimum custom levels for each loggers 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¶
- register(*modules, sort_modules=True, check_all_dependencies=True)[source]¶
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. AModuleDependencyError
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 toTrue
there is also a requirement that at most one instance of each module is registered andMultipleModuleInstanceError
will be raised if this is not the case.check_all_dependencies – Whether to check if all of each modules declared dependencies (that is, the union of the
INIT_DEPENDENCIES
andADDITIONAL_DEPENDENCIES
attributes) have been included in the set of modules to be registered. AModuleDependencyError
exception will be raised if there are missing dependencies.
- make_initial_population(*, n)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
Fires the event once for the given date
- Parameters
event –
Event
to firedate – the date of the event
- do_birth(mother_id)[source]¶
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)[source]¶
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[source]¶
Bases:
object
A simple priority queue for events.
This doesn’t really care what events and dates are, provided dates are comparable so we can tell which is least, i.e. earliest.