Metadata-Version: 2.1
Name: energysim
Version: 2.0.4
Summary: Python package for cosimulation of multi-energy systems
Home-page: https://github.com/dgusain1/energysim
Author: Digvijay Gusain
Author-email: digvijay.gusain29@gmail.com
License: MIT
Description: 
        .. image:: logo.png	
        
        Compatible with Python 3.6 and above.
        Documentation available `here <https://energysim.readthedocs.io/en/latest/>`_.
        
        What is energysim?
        ##################
        
        ``energysim`` is a python based cosimulation tool designed to simplify multi-energy cosimulations. The tool was initially called ``FMUWorld``, since it focussed exclusively on combining models developed and packaged as Functional Mockup Units (FMUs). However, it has since been majorly updated to become a more generalisable cosimulation tool to include a more variety of energy system simulators.
        
        The idea behind development of ``energysim`` is to simplify cosimulation to focus on the high-level applications, such as energy system planning, evaluation of control strategies, etc., rather than low-level cosimulation tasks such as message exchange, time progression coordination, etc. 
        
        Currently, ``energysim`` allows users to combine:
        	
        	1. Dynamic models packaged as *Functional Mockup Units*.
        	2. Pandapower networks packaged as *pickle files*.
        	3. PyPSA models (still under testing) as *Excel files*.
        	4. User-defined external simulators interfaced with *.py functions*.
        	5. CSV data files
        
        
        Installation
        ############
        ``energysim`` can be installed with ``pip`` using::
        
        	pip install energysim
        
        Dependencies
        ^^^^^^^^^^^^
        ``energysim`` requires the following packages to work:
        
        	1. FMPy
        	2. Pandapower
        	3. PyPSA
        	4. NumPy
        	5. Pandas
        	6. Matplotlib
        	7. NetworkX
        	8. tqdm
        
        Usage
        #####
        
        ``energysim`` cosimulation is designed for an easy-plug-and-play approach. The main component is the ``world()`` object. This is the "playground" where all simulators, and connections are added and the options for simulation are specified. ``world()`` can be imported by implementing::
        
        	from energysim import world
        
        
        Initialization
        ^^^^^^^^^^^^^^
        Once ``world`` is imported, it can be initialized with basic simulation parameters using:: 
        
        
        	my_world = world(start_time=0, stop_time=1000, logging=True, t_macro=60)
        
        ``world`` accepts the following parameters :
        
        	- ``start_time`` : simulation start time (0 by default).
        	- ``stop_time`` : simulation end time (1000 by default).
        	- ``logging`` : Flag to toggle update on simulation progress (True by default). 
        	- ``t_macro`` : Time steps at which information between simulators needs to be exchanged. (60 by default).
        
        Adding Simulators
        ^^^^^^^^^^^^^^^^^
        After initializing the world cosimulation object, simulators can be added to the world using the ``add_simulator()`` method::
        
        	my_world.add_simulator(sim_type='fmu', sim_name='FMU1', 
        	sim_loc=/path/to/sim, inputs=['v1', 'v2'], outputs=['var1','var2'], step_size=1)
        	
        where:
        
        	- ``sim_type`` : 'fmu', 'powerflow', 'csv', 'external'
        	- ``sim_name`` : Unique simulator name.
        	- ``sim_loc`` : A raw string address of simulator location.
        	- ``outputs`` : Variables that need to be recorded from the simulator during simulation.
        	- ``inputs`` : Input variables to the simulator.
        	- ``step_size`` : Internal step size for simulator (1e-3 by default).
        
        Please see documentation on ``add_simulator`` to properly add simulators to ``energysim``.
        The values to simulator input are kept constant for the duration between two macro time steps.
        
        Connections between simulators
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        Once all the required simulators are added, the connections between them can be specified with a dictionary as follows ::
        
        	connections = {'sim1.output_variable1' : 'sim2.input_variable1',
        	   'sim3.output_variable2' : 'sim4.input_variable2',
        	   'sim1.output_variable3' : 'sim2.input_variable3',}
        
        This dictionary can be passed onto the world object::
        
        	my_world.add_connections(connections)
        
        
        Initializing simulator variables
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        Initialization is important to start-up simulator in a cosimulation. If the simulators are not internally initialized, or of users want to use different initial conditions for the simulators, it can easily be done in ``energysim``. To provide initial values to the simulators, an ``init`` dictionary can be specified and given to the ``world`` object ::
        
        	initializations = {'sim_name1' : (['sim_variables'], [values]),
        	                   'sim_name2' : (['sim_variables'], [values])}
        	options = {'init' : initializations}
        	my_world.options(options)
        
        
        Executing simulation
        ^^^^^^^^^^^^^^^^^^^^
        Finally, the ``simulate()`` function can be called to simulate the world. 
        This returns a dictionary with simulator name as keys and the results of 
        the simulator as pandas dataframe. ``pbar`` can be used to toggle the progress bar for the simulation::
        
        	results = my_world.simulate(pbar=True)
        
        
        
        More information is provided on the documentation page.
        
        ## Citing
        Please cite the following paper if you use **energysim**:
        Gusain, D, Cvetković, M & Palensky, P 2019, Energy flexibility analysis using FMUWorld. in 2019 IEEE Milan PowerTech., 8810433, IEEE, 2019 IEEE Milan PowerTech, PowerTech 2019, Milan, Italy, 23/06/19. https://doi.org/10.1109/PTC.2019.8810433
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Description-Content-Type: text/x-rst
