Metadata-Version: 2.4
Name: mosaik-influxdb2
Version: 0.4.0
Summary: An adapter to connect mosaik with InfluxDB 2
License: MIT
License-File: LICENSE
Author: Eike Schulte
Author-email: eike.schulte@offis.de
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: influxdb-client (>=1.35.0,<2.0.0)
Requires-Dist: loguru (>=0.7.3,<0.8.0)
Requires-Dist: mosaik-api-v3 (>=3.0.13,<4.0.0)
Description-Content-Type: text/markdown

# mosaik-influxdb2

This package contains an adapter to write data from a mosaik simulation into an
InfluxDB 2 database.

## Installation

This package is on pypi, so you can install it using pip:

```sh
pip install mosaik-influxdb2
```

## Usage

To use the simulator, first add it to your `sim_config`:

```python
sim_config = {
    "InfluxWriter": {"python": "mosaik_components.influxdb2.writer:Simulator"},
    # ...
}
```

Next, you need to start the simulator. Here, you have two choices to make:

1. The simulator can run both in time-based mode with a fixed step size or in
   event-based mode without a step size. You can choose the time-based mode by giving
   the parameter `step_size` when starting the simulator. If you give `step_size=None`
   (or don’t specify anything), the simulator will use the event-based mode.
2. You can either supply a start date (as a string parseable by Python’s `datetime`
   module) which will be combined with the (mosaik) time and time resolution to
   calculate each step’s time, or you can supply the time for each step on the
   `local_time` attribute (again, as a string). If you give both, the value on the
   `local_time` attribute will take precedence.

So one possible invocation would be

```python
influx_sim = world.start("InfluxWriter",
    step_size=900,
    start_date="2022-01-01 00:00:00Z",
)
```

to start the simulator in time-based mode with a step size of 900 and times based on
the given start date. You can leave off either argument with the effects described
above.

Finally, the model needs to be started with your Influx credentials:

```python
influx = influx_sim.Database(
    url="http://localhost:8086",
    org='.',
    bucket='my_bucket',
    token='secret_token',
    measurement='experiment_0001'
)
```

We recommend setting a new value for the measurement on each simulation run. (For
example, you can use the start time of your simulation or a random UUID.)

Afterwards, you can define `world.connect(other_entity, influx, attrs)` as you like.

The simulator supports only one instance of the Database model. If you want to connect
to several databases, you will need to start several instances of the simulator as well.

## Other settings

By default, the adapter will save the simulator ID and entity ID of the producer of each data point in the *src_sim* and *src_entity* tags on that data point.
You can change the name of these tags by passing the `src_sim_tag` and `src_entity_tag` to the `start` call.
Setting them to `None` will disable writing the corresponding tag entirely.

Additionally, you can use the extra method `register_src_types` on the `influx_sim` object to pass a dict mapping entities' full IDs to arbitrary strings.
Entities for which the full ID is registered in this way will have their data point augmented by the tag *src_type*, with the corresponding value in the dict as the tag value.

You would usually use this to store an entities "type" (for example, bus, line, PV system, etc.) as the adapter cannot reliably deduce this from the entity IDs.
(Not every simulator uses the convention "ModelName-Index" for those.)

The name of this tag can be changed via the `src_type_tag` parameter to `start`.

