This project implements a co-simulation orchestration algorithms capable of hybrid co-simulation including two different coupling algorithms: Gauss-Seidel and Jacobi coupling algorithm. It uses an agent based system which handles the simulator and model executions. Wrapper classes are responsible to perform the model exchange between Continuous Time (CT) and Discrete Event (DE) models. It is designed in an abstract way but it's adaptable structure allows it to be used for specific use-cases as well.
The file orchestrator.py is the main file of the project. It includes the Orchestrator class responsible for running the simulation. The Orchestrator class needs the following parameter values:
-
(String) The name of the used coupling algorithm: either "gauss-seidel" or "jacobi"
-
(List) A list containing the needed information about the used simulators: name, which factory class is used to create the simulator, on which other simulator's output it depends on and the order of execution. The list is structured in the form:
[{"name": "simulatorA", "factory": simulatorA_factory, "dependency": ["simulatorB"], "order": 0},
{"name": "simulatorB", "factory": simulatorB_factory, "dependency": ["simulatorA"], "order": 1}]
-
(Dictionary) The initial data for every simulator in the form:
{"simulatorA": [9, 2], "simulatorB": 2.0234203}
The orchestrator.py file contains a main function which runs one use case of the simulation. The function defines an Orchestration objects and calls its run function. The code structure is as follows:
orchestrator = Orchestrator(coupling_algorithm_name, simulator_list, initial_data_dict)
orchestrator.run_simulation()
By changing the values of coupling_algorithm_name, simulator_list and initial_data_dict, the simulation can be changed. Before the first run, all required libraries have to be downloaded by executing the following command:
pip install -r requirements.txt.
The simulation can then be run by executing the following command:
python orchestrator.py
Per default, the Orchestrator simulates three models:
- A DE model simulating the waiting time of customers visiting a bank (open-source model called CIW [1])
- A CT Hiden Markov Model (using the open-source library hmmlearn [2])
- A CT logistic growth model [3]
The simulation results are written in a JSON file called simulation_output.json which is located in the root folder and contains every result for every computed time step and model. The results are also printed on the terminal.
You'll find a template for adding new models, etc. in the folder simulators_template. The folder consists of two model folders (Model_CT and Model_DE) that only contain the skeleton code for the model, simulator, factory and wrapper files, but no content. Thus, you can add your model code to the model file and adjust the simulator, factory and wrapper classes to work together with your model. When writing your code, you can orient yourself on the other example folders in the project. Lastly, in the main file orchestrator.py at the bottom, there is a commented template of combining the template models and run the simulation. Just uncomment this part and adapt the code to your liking. This is all the steps you need to perform to add new models and run them. If you need to add more than two models, you can multiply the template folders and proceed the same way.
If you would like to add a new coupling algorithm class, you can add its file to the strategy folder. Just make sure, that your class inherits from the abstract class in the strategy_algorithm.py file. Your class needs to implement an algorithm() function, but apart form that, you are free in your implementation.
[1] Palmer, Geraint I., et al. "Ciw: An open-source discrete event simulation library." Journal of Simulation 13.1 (2019): 68-82. Website
[2] hmmlearn developers (2010). hmmlearn. Website
[3] Hiroki Sayama (2020). Simulating Continuous-Time Models. OpenSUNY. Website