###############
  ModelicaRes
###############

**Python utilities to set up and analyze Modelica simulation experiments**

ModelicaRes is a free, open-source tool to manage Modelica_ simulations,
interpret results, and create publishable figures.  It is currently possible to

- Auto-generate simulation scripts,
- Browse data,
- Perform custom calculations, and
- Produce various plots and diagrams.

The figures are generated via matplotlib_, which offers a rich set of plotting
routines.  ModelicaRes includes convenient functions to automatically pre-format
and label some figures, like xy plots, Bode and Nyquist plots, and Sankey
diagrams.  ModelicaRes can be scripted or run from a Python_ interpreter with
math and matrix functions from NumPy_.

.. only:: html

  .. image:: _static/browse.png
     :scale: 45 %
     :alt: Variable browser

  .. image:: ../examples/PIDs-nyquist.png
     :scale: 35 %
     :alt: Nyquist plot of PID with varying differential time constant

  |

  .. image:: ../examples/ChuaCircuit.png
     :scale: 35 %
     :alt: Plot of Chua circuit

  .. image:: ../examples/ThreeTanks.png
     :scale: 35 %
     :alt: Sankey digarams of three tanks model

  The links below and in the sidebar describe the components of ModelicaRes.
  For an introduction see :mod:`loadres`, which loads data files and provides a
  Python_ interpreter to help analyze them.

.. only:: latex

  .. image:: _static/browse.png
     :scale: 60 %

  .. image:: ../examples/PIDs-nyquist.pdf
     :scale: 50 %

  .. image:: ../examples/ThreeTanks.pdf
     :scale: 50 %

  .. image:: ../examples/ChuaCircuit.pdf
     :scale: 50 %

  The following chapters describe the components of ModelicaRes.  For an
  introduction see :mod:`loadres`, which loads data files and provides a Python_
  interpreter to help analyze them.

  The top-level module, :mod:`modelicares`, provides direct access to the most
  important classes and functions.  Others must be accessed through their
  submodules.  The :mod:`loadres` script   The :mod:`modelicares.simres`
  submodule has classes to load, analyze, and plot simulation results.
  The :mod:`modelicares.linres` submodule has a class to load, analyze, and plot
  results from linearizing a model.  The :mod:`modelicares.multi` submodule has
  functions to load and plot results from multiple data files at once. The
  :mod:`modelicares.exps` submodule has tools to set up and manage simulation
  experiments.  The :mod:`modelicares.texunit` submodule has functions to
  translate Modelica_ *unit* and *displayUnit* strings into LaTeX_-formatted
  strings.  The last submodule, :mod:`modelicares.base`, has general supporting
  functions.

  **Installation**

  An installable copy of this package can be downloaded from the `main site
  <http://kdavies4.github.io/ModelicaRes/>`_ or the `PyPI page`_.  After
  extracting the package, run the set-up script (setup.py) from the base folder.
  On Windows, use the following command::

     python setup.py install

  On Linux, use::

     sudo python setup.py install

  The matplotlibrc file in the base folder has some recommended revisions to
  matplotlib_'s defaults.  To use it, copy or move the file to the working
  directory or matplotlib_'s configuration directory.  See
  http://matplotlib.org/users/customizing.html for details.

  **Credits**

  Kevin Bandy to development this package.  Third-party code has been included
  from:

  - Jason Grout (`ArrowLine
    <http://old.nabble.com/Arrows-using-Line2D-and-shortening-lines-td19104579.html>`_
    class),
  - Jason Heeris (`efficient base-10 logarithm
    <http://www.mail-archive.com/matplotlib-users@lists.sourceforge.net/msg14433.html>`_),
  - Richard Murray (`python-control
    <http://sourceforge.net/apps/mediawiki/python-control>`_), and
  - Joerg Raedler (method to expand a `Modelica`_ variable tree - from
    `DyMat`_).

  **License terms and development**

  ModelicaRes_ is published under the terms of the BSD license (see
  LICENSE.txt).  Please share any modifications you make (preferably on a Github
  fork from https://github.com/kdavies4/ModelicaRes) so that others may benefit
  from your work.  If you find a bug, please `report it
  <https://github.com/kdavies4/ModelicaRes/issues/new>`_.  If you have
  suggestions for improvements, please `share them here
  <https://github.com/kdavies4/ModelicaRes/wiki/Possible-Enhancements>`_.

  **See also**

  The following `Python`_ projects are related:

  - `awesim`_: helps run simulation experiments and organize results
  - `BuildingsPy`_: supports unit testing
  - `DyMat`_: exports `Modelica`_ simulation data to comma separated values (CSV),
    `Gnuplot <http://www.gnuplot.info/>`_, MATLAB®, and `Network Common Data Form
    (netCDF) <http://www.unidata.ucar.edu/software/netcdf/>`_
  - `pysimulator`_: elaborate GUI; supports the Functional Mock-up Interface (FMI)

  The `pysimulator <https://code.google.com/p/pysimulator/>`_, `BuildingsPy
  <http://simulationresearch.lbl.gov/modelica/buildingspy/>`_, DyMat_, and
  `awesim <https://github.com/saroele/awesim>`_ projects provide related Python_
  modules.  pysimulator_ includes an elaborate GUI and supports the Functional
  Model Interface (FMI).  BuildingsPy_ has a :class:`Tester` class that can be
  used for unit testing.  DyMat_ has functions to export Modelica_ simulation
  data to comma separated values (CSV), `Gnuplot <http://www.gnuplot.info/>`_,
  MATLAB\ :sup:`®`, and `Network Common Data Form (netCDF)
  <http://www.unidata.ucar.edu/software/netcdf/>`_.  awesim_ provides tools to
  help run simulation experiments and organize the results.

.. toctree::

  loadres
  modelicares
  simres
  linres
  multi
  exps
  exps.doe
  texunit
  base

.. only:: html

  The top-level module, :mod:`modelicares`, provides direct access to the most
  important classes and functions.  Others must be accessed through their
  submodules.  The :mod:`loadres` script   The :mod:`modelicares.simres`
  submodule has classes to load, analyze, and plot simulation results.
  The :mod:`modelicares.linres` submodule has a class to load, analyze, and plot
  results from linearizing a model.  The :mod:`modelicares.multi` submodule has
  functions to load and plot results from multiple data files at once. The
  :mod:`modelicares.exps` submodule has tools to set up and manage simulation
  experiments.  The :mod:`modelicares.texunit` submodule has functions to
  translate Modelica_ *unit* and *displayUnit* strings into LaTeX_-formatted
  strings.  The last submodule, :mod:`modelicares.base`, has general supporting
  functions.

  A PDF version of this documentation is available `here <ModelicaRes.pdf>`_.

  **Installation**

  An installable copy of this package can be downloaded from the `main site`_ or
  the `PyPI page`_.  After extracting the package, run the set-up script
  (setup.py) from the base folder.  On Windows, use the following command::

     python setup.py install

  On Linux, use::

     sudo python setup.py install

  The matplotlibrc file in the base folder has some recommended revisions to
  matplotlib_'s defaults.  To use it, copy or move the file to the working
  directory or matplotlib_'s configuration directory.  See
  http://matplotlib.org/users/customizing.html for details.

  **Credits**

  The main author is Kevin Davies.  Kevin Bandy also helped in the development.
  Third-party code has been included from Jason Grout (`ArrowLine
  <http://old.nabble.com/Arrows-using-Line2D-and-shortening-lines-td19104579.html>`_
  class), Jason Heeris (`efficient base-10 logarithm
  <http://www.mail-archive.com/matplotlib-users@lists.sourceforge.net/msg14433.html>`_),
  Richard Murray (`python-control
  <http://sourceforge.net/apps/mediawiki/python-control>`_), and Joerg Raedler
  (method to expand a Modelica_ variable tree - from `DyMat
  <http://www.j-raedler.de/projects/dymat/>`_).

  **License terms and development**

  ModelicaRes_ is published under the terms of the BSD license (see
  LICENSE.txt).  Please share any modifications you make (preferably on a Github
  fork from https://github.com/kdavies4/ModelicaRes) so that others may benefit
  from your work.  If you find a bug, please `report it
  <https://github.com/kdavies4/ModelicaRes/issues/new>`_.  If you have
  suggestions for improvements, please `share them here
  <https://github.com/kdavies4/ModelicaRes/wiki/Possible-Enhancements>`_.

  **See also**

  The following `Python`_ projects are related:

  - `awesim`_: helps run simulation experiments and organize results
  - `BuildingsPy`_: supports unit testing
  - `DyMat`_: exports `Modelica`_ simulation data to comma separated values
    (CSV), `Gnuplot <http://www.gnuplot.info/>`_, MATLAB®, and `Network Common
    Data Form (netCDF) <http://www.unidata.ucar.edu/software/netcdf/>`_
  - `pysimulator`_: elaborate GUI; supports the Functional Mock-up Interface
    (FMI)


.. _Modelica: http://www.modelica.org/
.. _Python: http://www.python.org/
.. _matplotlib: http://www.matplotlib.org/
.. _NumPy: http://numpy.scipy.org/
.. _PyPI page: http://pypi.python.org/pypi/ModelicaRes
.. _LaTeX: http://www.latex-project.org/
.. _awesim: https://github.com/saroele/awesim
.. _BuildingsPy: http://simulationresearch.lbl.gov/modelica/buildingspy/
.. _DyMat: http://www.j-raedler.de/projects/dymat/
.. _pysimulator: https://code.google.com/p/pysimulator/
