---

MultiSim - A simulation tool for energy systems

MultiSim is a simulation tool for energy systems consisting of multiple different parts like pipes, storages, valves, heat exchangers, etc. F.i. technical appliances such as space or water heating appliances can be designed, simulated and optimized.

MultiSim was mainly designed to solve the convection-diffusion-reaction-equation but can also be utilized to solve other differential equations. It features an adaptive step size solver, which is capable of yielding a stable solution even when loads fluctuate vigorously. Furthermore the solver can handle steps in flow variables due to interference of controllers (f.i. PID).

• Developer/maintainer: https://www.linkedin.com/in/johannes-elfner

Short documentation

The short documentation consists of:

• Installation instructions
• Description of available Components
• Getting startet
• Basic examples
• Summary of the validation of the simulation software
• Known limitations and To-do

Install

To install the newest snapshot of MultiSim:

1. Make a local clone of this repository or download the release to the installation path
2. cd the console to the download/clone folder
3. pip install -e . to install MultiSim in editable mode or pip install . if you want a fixed installation.

The newest snapshot of the branch master is always fully operational, but may include code which will be deprecated in the next release. If you want to stick to fixed releases, you can stick to the version published on PyPi and install MultiSim with:

1. pip install MultiSim

Fixed releases may be outdated by several months, so I recommend cloning this repository.

For slightly more detailed building, distribution and installation instructions, see INSTALL.rst.

Components

MultiSim supports different types of components, most notably:

• Parts which require differential equations to be solved (called "basic parts" hereafter)
• Connectors and Actuators which can affect flow variables, either controlled by controllers, stationary or time series based
• Controllers which control actuators
• Boundary Conditions like in- and outflows to ambience, both stationary and time series based
• Compound parts consisting of multiple parts, actuators, controllers and boundary conditions
• Meters to track process variables of specific important parts/cells and perform basic calculations on-the-fly
• Utility tools for pre- and postprocessing, plotting, loading and storing data, ...

Basic parts

The following basic parts are currently available:

• Pipe
• Thermal storage (TES)
• Heat exchanger
  • Numeric (by solution of differential equations)
  • Non-numeric condensing flue gas heat exchanger based on fitting an ElasticNet regression to measurement data (very specific to the type of HEX)

Parts derived by class inheritance of the basic parts:

• Heated pipe
• Branched pipe, pipe with valve, pipe with pump (these are also compound parts)

Actuators and connectors

The following actuators and connectors can be installed:

• Three way connector
• Mixing valve/splitting valve/three way valve
• Branch
• Pump
• Connector to ambient conditions/boundary conditions

All actuators/connectors can be controlled by controllers, set to a static value or follow a predefined behaviour by defining a time series.

Controllers

parts/controllers defines the following controllers:

• PID controller
• Bang–bang controller (also 2 step or on–off controller) with a hysteresis
• Two sensor controller (switch on when sensor 1 is > or < than setpoint 1, switch off when sensor 2 is > or < than setpoint 2)
• Model predictive controller (CHP plant specific to optimally follow a predicted electric profile)

All controllers support setting:

• Fixed setpoints and setting the setpoint to a process variable of another part
• Control variable saturation limits
• Part specific control variable post processing like conversion to a specific value range
• Setting slopes to control variable changes
• Linking controllers to make controller action depend on another controller to construct control chains

PID controllers additionally support semi-automatic tuning by Ziegler-Nichols method. Thus preferred tuning method for PID controllers is Ziegler-Nichols, since the parameters Kp_crit and T_crit can be passed directly to the controller while specifying the aggressiveness of the PID controller with rules like classic or pessen-int (Pessen integral rule).

Compound parts

Compound parts consisting of multiple other parts and controllers can be found in parts/part_modules. Part dimensions, such as pipe diameters, and controller coefficients have been fit to a wide range of flow speeds and temperatures, but may be adjusted if controls show instabilities or if the solver requires too many retries to find a stable solution. The following compound parts can be used:

• Gas boiler
• Chp plant, also with flue gas heat exchanger (based on fitting a model to manufacturer specific measurement data)
• Consumer appliances
  • Space heating
  • State-of-the-art water heating
  • Low exergy water heating

New parts and controllers can be added either by defining completely new classes or by inheriting from existing parts.

Meters

There is also a list of sensors/meters which can be "installed" at any (numeric) cell of each part to track the state of this cell or perform calculations like energy flows, cumulated mass and energy flows etc. on the fly, such as:

• Temperature sensor
• Mass flow sensor
• Heat meter (power, mass flow, volume flow, temperature of hot and cold part, cumulated values)

Utility tools

The file utility_functions provides methods for pre- and post-processing of input/output data and basic plotting/statistic analysis. Also methods to open the *.hdf5 files, which are used to store the results on disk, are provided.

But: utility_functions.py requires heavy refactoring!! This is scheduled for the next release.

Some parts have already been refactored to multisim/_utility/:

• Meters, also see section Meters
• plotting provides basic plotting methods for validation and heatmap plots and also some formatting helpers. More will be added soon.
• Statistical error measures provides basic error measures useful for validation, such as the (adjusted) coefficient of determination, MSE, RMSE, CV(RMSE), NME, ...

Getting started

Import MultiSim and create your simulation environment instance with:

import multisim as ms

my_sim = ms.SimEnv()

Now simply follow the detailed step-by-step instructions printed to the console.

Examples

We will cover three basic examples in this section, all covering the temperature control of a three-way-valve flowing into a thermal energy storage (TES):

1. A stable PID controller (loop tuned with Ziegler-Nichols)
2. An instable PID controller. Stable at first for small steps in the process variable, but instable with persisting oscillations for larger steps.
3. A bang-bang controller to control the pump.

The appliance/setup to simulate is, in all three cases, the following:

With the temperature of the water flowing into port B of 'pipe_in' describing a step from 50.0 °C to 85.0 °C after 300 s.

Stable PID controller

This small example covers controlling the mixing temperature of the three-way-valve via a stable PID controller. The PID controller is tuned using the class Ziegler-Nichols rule.

The full executable example as a Python script can be found at doc/examples/basic_loop_w_stable_pid.py.

To set up the simulation environment, first start by loading the required modules and defining boundary conditions like the temperatures and temperature time series:

import matplotlib as mpl
import matplotlib.pyplot as plt
import pandas as pd

import multisim as ms

# define temperatures
sp_pid = 40.0  # setpoint for the PID in degree celsius
theta_low = 20.0  # degree celsius
theta_high = pd.Series(
    data=50.0, index=pd.date_range('2021-01-01', periods=1000, freq='1s')
)
theta_high.iloc[300:] = 85.0

Now create an instance of the simulation environment, and set some basic options:

# create simulation environment
my_sim = ms.Models()
# set disksaving, simulatiion timeframe and solver
my_sim.set_disksaving(save=True, start_date='infer', sim_name='sim_a')
my_sim.set_timeframe(timeframe=900, adaptive_steps=True)
my_sim.set_solver(solver='heun', allow_implicit=False)

Next define specifications for pipes and the ports at each pipe. Dimensio