.. _Frequently-Asked-Questions:

Frequenty Asked Questions
=========================

For any questions about **EstimationPy** please contact

 * Marco Bonvini MBonvini@lbl.gov, bonvini.m@gmail.com


How to contribute?
++++++++++++++++++

If you want to contribute to the **EstimationPy** see the section
:ref:`Contribute`.

How to install?
+++++++++++++++

To install **EstimationPy** please refer to the section :ref:`Installation`.

How to run tests?
+++++++++++++++++

**EstimationPy** comes with a series of unit tests. To run the tests you can simply
access from a terminal the folder containing the source code where the
file ``setup.py`` is located and then run::

  python setup.py test

If everything goes right you should see a message like this::

  [... many log messages ...]
  ----------------------------------------------------------------------
  Ran 30 tests in 47.920s
  
  OK

How to generate the documentation?
++++++++++++++++++++++++++++++++++

EstimationPy html docs are generated with Sphinx and are hosted on the Github pages of the
project. Github pages is a convenient mechanism for showing the docs generated by Sphinx.
The project has a branch called **gh-pages** that contains only the html documentation files
and are available at http://lbl-srg.github.io/EstimationPy whereas the source code
is available at https://github.com/lbl-srg/EstimationPy .

To build the docs please follow the instructions provided
`here <http://daler.github.io/sphinxdoc-test/includeme.html>`_ .

According to the instructions, your setup should be such that you have the following
folders on your machine::

  <...>
  ├── estimationpy
  │   ├── LICENSE
  │   ├── Legal.txt
  │   ├── MANIFEST.in
  │   ├── Makefile
  │   ├── README.rst
  │   ├── doc
  │   │   ├── Makefile
  │   │   ├── build
  │   │   └── source
  │   ├── dockers
  │   │   └── README.rst
  │   ├── estimationpy
  │   │   ├── __init__.py
  │   │   ├── examples
  │   │   ├── fmu_utils
  │   │   ├── modelica
  │   │   ├── tests
  │   │   └── ukf
  │   └── setup.py
  └── estimationpy-docs
      └── html

When you run the command ``make html`` in the folder ``<...>/estimationpy/doc`` the documentation
is built in the folder ``<...>/estimationpy-docs/html``.

The Makefile also contains a command that automatically generates the html docs, enters
the folder ``<...>/estimationpy-docs/html``, commit the changes, and push them
to the branch **gh-pahes**. The command is called ``buildandcommithtml``.

.. literalinclude:: /../Makefile
   :language: Makefile
   :linenos:
   :lines:  1-17, 46-49, 157-160 


How to run examples and generate plots if a X server is not available?
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

If you're using EstimationPy in a Docker container and you don't have linked its
X server to the one of the host OS, you can use the following shorcut.
Open a terminal and type::

   python -c 'import matplotlib; \
   matplotlib.use("Agg");\
   from estimationpy.examples.stuck_valve import run_ukf_smooth_fdd; \
   run_ukf_smooth_fdd.main()'

The former set of instructions loads **matplotlib**, defines the operation
mode that allows to save images without an X server, loads one of the
examples provided by EstimationPy and runs it.

How can I assign a default logger to EstimationPy?
++++++++++++++++++++++++++++++++++++++++++++++++++

The modules, classes and functions contained in EstimationPy use the logging
module that comes with Python. EstimationPy produces log messages with different
priorities and severity, for either debugging or reporting errors.
One can specify the default logger by adding the following lines at the beginning
of the script using EstimationPy::

  import logging
  from estimationpy.fmu_utils import estimationpy_logging
  estimationpy_logging.configure_logger()

The function :func:`estimationpy.fmu_utils.estimationpy_logging.configure_logger` takes
parameters that can be used to configure the level of logging.
An example is::
  
  estimationpy_logging.configure_logger(log_level = logging.DEBUG, \
  log_level_console = logging.INFO, log_level_file = logging.DEBUG)

In this case all the log messages at DEBUG level that are generated by EstimationPy
will be saved in the log file, while the log messages at the INFO level will be displayed
at the console level.

Fore more info look :ref:`Logging`.