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

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

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

- Auto-generate simulation scripts,
- Run model executables with varying parameters,
- 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/ThreeTanks.png
     :scale: 35 %
     :alt: Sankey digarams of three tanks model

  |

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

  .. image:: examples/PID-nyquist.png
     :scale: 35 %
     :alt: example for modelicares.LinRes.nyquist()

  The links below describe the components of ModelicaRes.  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 loads data files and provides a Python_ interpreter to
  help analyze them.  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.

.. only:: latex

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

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

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

  .. figure:: examples/PID-nyquist.pdf
     :scale: 50 %

  The following chapters describe the components of ModelicaRes.  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 loads data files and provides a Python_ interpreter to
  help analyze them.  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`_.  To install
  the package, first download and extract it.  Then 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 helped in the development of 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
  <http://www.j-raedler.de/projects/dymat/>`_).

  **License terms**

  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.

  **See also**

  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::

  modelicares
  loadres
  simres
  linres
  multi
  exps
  texunit
  base

.. only:: html

  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`_.  To install the package, first download and extract it.
  Then 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**

  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.

  **See also**

  The `pysimulator`_, `BuildingsPy`_, DyMat_, and `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`_,
  MATLAB\ :sup:`®`, and `Network Common Data Form (netCDF)`_.  awesim_ provides
  tools to help run simulation experiments and organize the results.

.. _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/
