= A _Simulation as a Service_-Implementation: Demo

image:https://img.shields.io/badge/code%20style-black-000000.svg[alt=Code style: black, link=https://github.com/psf/black]
image:https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336[alt=Imports: isort, link=https://timothycrosley.github.io/isort]

This repository contains the code used for demonstrating the capabilities of the https://github.com/UdSAES/simaas-api[cloud-native _simulation as a service_-implementation] developed at the https://www.uni-saarland.de/lehrstuhl/frey.html[chair of automation and energy systems] at Saarland university by means of two use cases.

The repository also contains a very small Modelica-library link:DemoCloudNativeSIMaaS/[DemoCloudNativeSIMaaS]. The library implements the thermistor and thermistor circuit used in the second use case. An example ready to be simulated in a Modelica-IDE as well as the model used for export as FMU are included, too.

== Installation
Clone the repository, then install the dependencies (specified in `Pipfile`/`Pipfile.lock`) into a new https://pipenv.pypa.io/en/latest/[Pipenv]-environment using `pipenv install`.

=== Configuration
All environment variables without a default value MUST be set before starting the program. Otherwise, a fatal error will be raised and the program will terminate with a non-zero exit code.

For example, the ENVVARs can be set by putting `export UC1D_*=...`-statements in a file named `.env` and then loading the contents of this file via `source .env`.

[#tbl-envvars,options="header",cols="2,5,1"]
|===
| Environment Variable
| Description
| Default Value

| `UC1D_SIMAAS_ORIGIN`
| The origin of the URL identifying/locating simulation as a service-instance. Make sure that this can be resolved from the `simaas-worker`-instances (i.e. don't use `localhost` if running containers)!
| --

| `UC1D_POLLING_RETRIES`
| The maximum number of retries for polling the status of a simulation (parsed as integer)
| `30`

| `UC1D_POLLING_FREQUENCY`
| The time between to retries for polling the status of a simulation in seconds (parsed as float)
| `0.1`

| `UC1D_LOG_LEVEL`
| The minimal included https://loguru.readthedocs.io/en/stable/api/logger.html#levels[log level] that shall be printed
| `INFO`

| `UC1D_EFC_FMU`
| The path to the FMU used for the ensemble PV forecast
| --

| `UC1D_GA_FMU`
| The path to the FMU used for the parameter fitting-example using a genetic algorithm
| --

| `UC1D_WEATHER_FROM_DISK`
| Load the weather data from `./weather_forecast.csv` if `true`; request from API otherwise
| `true`

| `UC1D_WEATHER_API_ORIGIN`
| The origin of the URL identifying/locating an instance of the https://github.com/UdSAES/dwd_data_access[dwd_data_access-API]; e.g.: `https://weather.nibbler.msaas.me`
| -- footnote:[This is _not_ necessary iff `UC1D_WEATHER_FROM_DISK` is `true`!]

| `UC1D_WEATHER_API_JWT`
| The JSON web token for authentication with the https://github.com/UdSAES/dwd_data_access[dwd_data_access-API]
| `None`

|===

== Usage
There are two demos:

* `demo-efc` implements an ensemble forecast for the power generated by a PV system. By default, it uses weather forecasts created at different points in time for the same day as input which doesn't really make sense except for demonstrating that the process works.
* `demo-ga` uses a genetic algorithm (GA) to search for a set of values for the components of a thermistor circuit that results in a desired voltage over temperature-curve. Each individual represents a combination of component values and the fitness of each individual in a generation is evaluated by a SIMaaS-instance -- in parallel if and only if there are more than one worker instances.
+
The parameters of the GA are currently not exposed, but could be tuned manually by editing https://github.com/UdSAES/simaas-demo/blob/main/demo.py#L816[lines 816 ff.].

The code uses https://www.pyinvoke.org/[Invoke] to create a CLI -- see the code snippets below for usage instructions.

[source,sh]
----
# Activate virtual environment
pipenv shell

# List available demos
invoke -c demo --list

# Load ENVVARs and run demo
source .env; invoke -c demo demo-efc
----


== Development
The code in this repository represents a proof of concept, published for educational purposes only.

_There are no plans for further development._

== Acknowledgements
From January 2017 to March 2021, this work was supported by the SINTEG-project https://designetz.de["`Designetz`"] funded by the German Federal Ministry of Economic Affairs and Energy (BMWi) under grant 03SIN224.

image::logos_uds_aes_designetz_bmwi.png[]
