Working with external simulators

One of the USPs of energysim is that it can be coupled to external simulators fairly easily. However, it is expected that the users are familiar with intermediate level of python programming. In this section, we show how users can interface their own simulators with energysim very easily.

In the main code, users can add their simulators to my_world by using:

my_world.add_simulator(sim_type='external', sim_name = 'my_external_simulator', sim_loc = sim_loc, outputs=['var1', 'var2'], step_size=1)

Here the sim_name is the file name of the interfaced simulator my_external_simulator.py. This file has the following template:

#make necessary imports


class external_simulator():
    
    def __init__(self, sim_name, sim_loc, inputs = [], outputs = [], step_size=1):
        self.sim_name = sim_name
        self.sim_loc = sim_loc
        self.inputs = inputs
        self.outputs = outputs
        self.step_size = step_size
            
    def init(self):
        #specify simulator initialization command
        
        #remove pass after initialization has been set
        pass
    
    def set_value(self, variable, value):
        #this should set the simulator paramaters as values. Return cmd not reqd
        
        #remove the pass after specifying set_value
        pass
    
    def get_value(self, variable, time):
        #this should return a list of values from simulator as a list corresponding to parameters
        
        **Return reqd**
        
        #remove the pass after specifying get_value. 
        pass    
    
    def step(self, time):
        #use the time variable (if needed) to step the simulator to t=time
        
        #return is not required. remove the pass command afterwards.
        pass
    

The four functions inside class external_simulator() are all that energysim requires to interface with the simulator. Users are free to make imports, and create other functions which can be called within this file. Let us go through each function and their definitions.

init() method

Note that this is different from the __init__() class. This method is needed to initialize the simulator. You can use it to, for example, establish connection to another software, or package. Basically, start-up the simulator.

step(time) method

The step method is used by energysim coordinator to perform time stepping for each simulator. The coordinator steps the simulator by deltaT = step_size defined while adding the simulator to world. The step method is useful when the model consists consists of time-dependent equations and exibits dynamics behavior.

get_value(variable, time) method

The get_value method is used by the simulator to query variable value from the simulator. The coordinator queries the simulator by asking the value of variable at time=``time``. The variable is enclosed in a python list. The user must define in this method, how to obtain the value of that variable from its simulator.

set_value(variable, value) method

The set_value method is used by the simulator to set the variable to a particular value at the time instance when message are exchanged between simulators. In this method, users must specify how to set the variable to the specified value. Both the variable and value are enclosed within a list.