Simulator

This data stores the run function for model running, storing global variables and other services.

class Melodie.simulator.BaseModellingManager(config: Config, scenario_cls: Type[Scenario], model_cls: Type[Model], data_loader_cls: Type[DataLoader] | None = None)

Bases: ABC

Base class of Simulator/Trainer/Calibrator.

get_dataframe(table_name) → pd.DataFrame

Get a static DataFrame from the data loader.

Parameters:

table_name – Name of dataframe.

Returns:

get_matrix(matrix_name) → np.ndarray

Get a matrix from data loader.

Parameters:

matrix_name – Name of matrix.

Returns:

subworker_prerun()

If run as sub-worker, run this function to avoid deleting the existing tables in database.

pre_run(clear_db=True)

pre_run means this function should be executed before run, to initialize the scenario parameters.

Parameters:

clear_db – If True, this method will clear database.

Returns:

abstract generate_scenarios()

Abstract method for generation of scenarios.

class Melodie.simulator.SimulatorMeta

Bases: object

Record the current scenario, params scenario of simulator

to_dict(public_only=False)
class Melodie.simulator.Simulator(config: Config, scenario_cls: Type[Scenario], model_cls: Type[Model], data_loader_cls: Type[DataLoader] | None = None, visualizer_cls: type[Melodie.visualizer.visualizer.BaseVisualizer] | None = None)

Bases: BaseModellingManager

Simulator simulates the logics written in the model.

Parameters:

  • config – Config instance for current project.

  • scenario_cls – Scenario class for current project.

  • model_cls – Model class in current project.

  • data_loader_cls – DataLoader class in current project.

  • visualizer_cls – Visualizer class in current project.

generate_scenarios() → List[Scenario]

Generate scenarios from the dataframe_loader

Returns:

A list of generated scenarios.

run_model(config, scenario, id_run, model_class: Type[Model], visualizer=None)

Run a model once.

setup()

Setup method of simulator, usually need not to inherit.

Returns:

None

run()

Main function for running model.

Returns:

None

run_visual()

Main function for running model with visualization.

Returns:

None

run_parallel(cores: int = 1)

Parallelized running through a series of scenarios.

Melodie does not start subprocesses directly. For the first shot, which means running one of the runs out of one scenario, it will be run by the main-thread to verify the model and initialize the database. After the first shot, subprocesses will be created as many as the value of parameter cores.

Parameters:

cores –

How many subprocesses will be created in the parallel simulation.

  • It is suggested that this parameter should be NO MORE THAN the physical cores of your computer.

  • Beside ‘cores’, You may found that your cpu has one more metric: threads, which means your CPU supports hyper-threading. If so, use ‘physical cores’, not ‘threads’ as the upper limit.

  • For example, an Intel® I5-8250U has 4 physical cores and 8 threads. If you use a computer equipped with this CPU, this parameter cannot be larger than 4.

  • In short, hyper-threading only improves performance in io intensive programs. As Melodie was computation intensive, if there are more subprocess than physical cores, subprocesses will fight for CPU, costing a lot of extra time.

Sqlite itself was thread-safe for writing. However, pandas tries to create the table if table was not exist, which might trigger conflict condition.

For example:

p1, p2 stands for process 1 and 2 request writing to a table test; db stands for database; 1. p1 –> db <found no table named ‘test’> 2. p2 –> db <found no table named ‘test’> 3. p1 –> db <request the db to create a table ‘test’> 4. p2 –> db <request the db to create a table ‘test’> 5. db –> p1 <created table named ‘test’> 6. db –> p2 <table ‘test’ already exists!> ERROR!

For multiple-cores, if running model this might happen very frequently. To avoid this, Melodie makes the first shot, which means running one of the runs out of one scenario, by main-process. Only when first shot completes will the subprocesses be launched.

Returns:

None

new_parallel(cores: int = 1)

Parallelized running through a series of scenarios.

Melodie does not start subprocesses directly. For the first shot, which means running one of the runs out of one scenario, it will be run by the main-thread to verify the model and initialize the database. After the first shot, subprocesses will be created as many as the value of parameter cores.

Parameters:

cores –

How many subprocesses will be created in the parallel simulation.

  • It is suggested that this parameter should be NO MORE THAN the physical cores of your computer.

  • Beside ‘cores’, You may found that your cpu has one more metric: threads, which means your CPU supports hyper-threading. If so, use ‘physical cores’, not ‘threads’ as the upper limit.

  • For example, an Intel® I5-8250U has 4 physical cores and 8 threads. If you use a computer equipped with this CPU, this parameter cannot be larger than 4.

  • In short, hyper-threading only improves performance in io intensive programs. As Melodie was computation intensive, if there are more subprocess than physical cores, subprocesses will fight for CPU, costing a lot of extra time.

Sqlite itself was thread-safe for writing. However, pandas tries to create the table if table was not exist, which might trigger conflict condition.

For example:

p1, p2 stands for process 1 and 2 request writing to a table test; db stands for database; 1. p1 –> db <found no table named ‘test’> 2. p2 –> db <found no table named ‘test’> 3. p1 –> db <request the db to create a table ‘test’> 4. p2 –> db <request the db to create a table ‘test’> 5. db –> p1 <created table named ‘test’> 6. db –> p2 <table ‘test’ already exists!> ERROR!

For multiple-cores, if running model this might happen very frequently. To avoid this, Melodie makes the first shot, which means running one of the runs out of one scenario, by main-process. Only when first shot completes will the subprocesses be launched.

Returns:

None