Metadata-Version: 2.4
Name: mosaik-api-v3
Version: 3.0.14
Summary: Python implementation of the mosaik API, version 3
Project-URL: Homepage, https://mosaik.offis.de
Project-URL: Repository, https://gitlab.com/mosaik/api/mosaik-api-python
Author-email: mosaik development team <mosaik@offis.de>
License: MIT License
        
        Copyright (c) 2023 mosaik development team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: AUTHORS.txt
License-File: LICENSE.txt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: docopt>=0.6.1
Requires-Dist: loguru>=0.6.0
Requires-Dist: typing-extensions>=4.4.0
Description-Content-Type: text/x-rst

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

This is an implementation of version 3 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-v3


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_v3

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.14 - 2025-10-07
-------------------

- [NEW] Introduce the `run_as_client` and `run_as_server` functions
  to run simulators as part of larger programs. Unlike
  `start_simulation`, these functions don't provide their own
  command-line interface and take the necessary settings as
  parameters.

3.0.13 - 2024-12-11
-------------------

- [CHANGE] The finalize method is now called before the connection
  to mosaik is closed.

3.0.12 - 2024-08-19
-------------------

- [FIX] Remote exceptions occurring during calls to mosaik are now
  correctly reported to the calling simulator.

3.0.11 - 2024-07-17
-------------------

- [CHANGE] Set default logging level back to info
- [NEW] `configure_logging` flag on `start_simulation` to control
  automatic logger setup

3.0.10 - 2024-05-17
-------------------

- [CHANGE] Simulators return a stacktrace to mosaik when running
  into an exception
- [FIX] Type for ModelDescription was missing fields

3.0.9 - 2024-03-28
------------------

- [CHANGE] We don't overwrite the logging system in `start_simulation`
  anymore, except when the user explicitly sets `--log-level` on the
  command line. This also changed the default level to `debug`.

3.0.8 - 2024-03-25
------------------

- [FIX] Enable yielding coroutines in finalize

3.0.7 - 2023-12-19
------------------

- [FIX] Make example_sim's meta legal

3.0.6 - 2023-12-13
------------------

- [FIX] Close asyncio.StreamWriters properly

3.0.5 - 2023-11-08
------------------

- [CHANGE] Improve typing support: package is marked with py.typed file,
  types are exported from mosaik_api_v3, Meta and CreateResult are split
  into optional and required fields

3.0.4 - 2023-08-31
------------------

- [NEW] Use loguru for logging
- [CHANGE] Remove simpy.io

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ütte 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
