Working with external simulators — energysim 2.0 documentation

# 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.