mosaik-api 3.0.6
Python implementation of the mosaik API.

Mosaik API for Python
=====================

**Note that the mosaik-api package has been superceded by the mosaik-api-v3
package and is not updated anymore.**

This is an implementation of the mosaik API for simulators written in Python.
It hides all the messaging and networking related stuff and provides a simple
base class that you can implement.


Installation
------------

Just use `pip <https://pip.pypa.io>`_ to install it:

.. sourcecode:: bash

    $ pip install mosaik-api


Documentation
-------------

Please refer to `mosaik’s documentation`__ of the API.

__ http://mosaik.readthedocs.org/en/latest/mosaik-api/high-level.html


Example Simulator
-----------------

This distribution contains an example simulator in the ``example_sim`` package.

It can be started via the ``pyexamplesim`` command; ``pyexamplesim --help``
shows you how to use it.

It can also be run in-process by importing and calling
``example_sim.mosaik.main()``.


Example MAS
-----------

This distribution contains an example "multi-agent system" that uses the
asyncronous remote calls to mosaik (``get_progress()``,
``get_related_entities()``, ``get_data()``, ``set_data()``).

It can be started via the ``pyexamplemas`` command; ``pyexamplemas --help``
shows you how to use it.

It can also be run in-process by importing and calling
``example_mas.mosaik.main()``.


Development setup
-----------------

To setup a devleopment environment, create a virtualenv and install the
packages from ``requirements.txt``:

.. code-block:: bash

   $ mkvirtualenv --python=/usr/bin/python3 mosaik-api-python
   (mosaik-api-python)$ pip install -r requirements.txt

To run the tests for the Python version you are currently using, execute
``py.test``. You should also add the test coverage check:

.. code-block:: bash

   (mosaik-api-python)$ py.test --cov=example_mas --cov=example_sim --cov=mosaik_api

To run the tests for all supported Python versions, run ``tox``:

.. code-block:: bash

   (mosaik-api-python)$ tox

Mosaik's `documentation
<https://mosaik.readthedocs.org/en/latest/dev/setup.html>`_ contains more
details.


Changelog
=========

3.0.6 - 2024-07-08
------------------

- [CHANGE] Move deprecation warning up (so it is shown even when packages are missing)

3.0.5 - 2024-06-26
------------------

- [CHANGE] Adjust stacklevel of deprecation warning

3.0.4 - 2024-06-26
------------------

- [CHANGE] Add deprecation warning referring users to mosaik-api-v3.

3.0.3 - 2022-12-14
------------------

- [NEW] Add datetime utility

3.0.2 - 2022-06-01
------------------

- [CHANGE] Use internal mosaik-simpy-io>=0.2.4 instead of simpy.io

3.0.1 - 2022-04-22
------------------

- [CHANGE] Set external events via highlevel function call

3.0.0 - 2021-05-02
------------------

- [CHANGE] Added time_resolution to init function
- [CHANGE] Added max_advance to step function
- [NEW] Implemented set_events capability (external events)

2.4.2 - 2020-11-24
------------------

- [FIX] Constrain simpy to version <4 due to simpy.io incompatibility

2.4 - 2019-02-05
----------------

- [NEW] Simulator can now be started on a different node than mosaik, using the
  remote flag "-r" and the timeout flag "-t". Mosaik can the integrate the simulator
  using the "connect" method of the simmanager.

2.3 – 2019-01-24
----------------

- [BugFix] Bugfix Tests


2.2 – 2016-02-15
----------------

- [NEW] API version 2.2: Added an optional "setup_done()" method.

- [CHANGE] API version validation: The API version is no longer an integer but
  a "major.minor" string.  The *major* part has to math with mosaiks major
  version.  The *minor* part may be lower or equal to mosaik's minor version.

- [FIX] Various minor fixes and stability improvements.


2.1 – 2014-10-24
----------------

- [NEW] Allow extra API methods to be called. See
  http://mosaik.readthedocs.org/en/2.0/mosaik-api/high-level.html#mosaik_api.Simulator

- [CHANGE] The *rel* entry in the entity description returned by *create()* is
  now optional.


2.0 – 2014-09-22
----------------

- Initial release of the mosaik 2 Sim API for Python.


Authors
=======

The original concepts for the mosaik API were developed by Steffen Schütten and
Stefan Scherfke.

The author of the mosaik API version 2 is Stefan Scherfke.

The author of the mosaik API version 3 is Thomas Raub.

Additional contributors: André El-Ama, Okko Nannen, Annika Ofenloch, Thomas Raub, Eike Schulte, Jan Sören Schwarz, Cornelius Steinbrink