tlo.performance module

A module to collect metrics, checkpoints, hashes and a variety of other information about the simulation as it runs, for debugging and performance monitoring purposes.

class MagpieOptions(log_perf: bool = False, log_perf_freq: int = 1, log_pop_hash: bool = False, save_sim: bool = False, save_sim_freq: int = 6, save_sim_on_end: bool = False, wall_time_limit_minutes: float | None = None)

Bases: object

log_perf: bool = False

log_perf_freq: int = 1

log_pop_hash: bool = False

save_sim: bool = False

save_sim_freq: int = 6

save_sim_on_end: bool = False

wall_time_limit_minutes: float | None = None

class Magpie(**kwargs)

Bases: Module

Register in simulation: ```

Magpie(
log_perf=True, # turn on logging of performance statistics… log_perf_freq=2, # …every n months log_pop_hash=True, # include hash of population dataframe (can be slow) save_sim=True, # save the simulation to a pickle file… save_sim_freq=3, # …every n months save_sim_on_end=True # save the simulation to a pickle file at the end of the simulation wall_time_limit_minutes=60 # stop the simulation if it runs for more than n minutes (checked every month)

)

```

e.g. to add to an existing scenario: ```

def modules(self):

return fullmodel() + [Magpie(log_perf=True,
log_perf_freq=2, log_pop_hash=True, save_sim=False, save_sim_on_end=True)]

```

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters:: name – the name to use for this module. Defaults to the concrete subclass’ name.

read_parameters(data_folder)

Read parameter values from file, if required.

Must be implemented by subclasses.

Parameters:: data_folder – path of a folder supplied to the Simulation containing data files. Typically, modules would read a particular file within here.

initialise_simulation(sim: Simulation)

Get ready for simulation start.

Must be implemented by subclasses.

This method is called just before the main simulation loop begins, and after all modules have read their parameters and the initial population has been created. It is a good place to add initial events to the event queue.

on_birth(mother_id, child_id)

Initialise our properties for a newborn individual.

Must be implemented by subclasses.

This is called by the simulation whenever a new person is born.

Parameters:

mother_id – the person id for the mother of this child (can be -1 if the mother is not identified).
child_id – the person id of new child

on_simulation_end(): This is called after the simulation has ended. Modules do not need to declare this.

parameters

class SaveSimulation(module, frequency_months)

Bases: RegularEvent, PopulationScopeEventMixin

Create a new regular event.

Parameters:

module – the module that created this event
frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

This is a no-op; subclasses should override this method.

Parameters:: target – the target of the event

class LogPerfProfile(module, frequency_months, do_hash)

Bases: RegularEvent, PopulationScopeEventMixin

Create a new regular event.

Parameters:

module – the module that created this event
frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

This is a no-op; subclasses should override this method.

Parameters:: target – the target of the event

class WallTimeLimit(module, wall_time_limit_minutes)

Bases: RegularEvent, PopulationScopeEventMixin

Create a new regular event.

Parameters:

module – the module that created this event
frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

This is a no-op; subclasses should override this method.

Parameters:: target – the target of the event

make_pickle_filename(sim_date)

profile_statistics(sim, do_hash)

memory_statistics() → dict[str, float]

Extract memory usage statistics in current process using psutil if available. Statistics are returned as a dictionary. If psutil not installed an empty dict is returned.

Key / value pairs are: memory_rss_MiB: float

Resident set size in mebibytes. The non-swapped physical memory the process has used.

memory_vms_MiB: float: Virtual memory size in mebibytes. The total amount of virtual memory used by the process.
memory_uss_MiB: float: Unique set size in mebibytes. The memory which is unique to a process and which would be freed if the process was terminated right now