Metadata-Version: 2.0
Name: dtcontrol
Version: 1.11.5
Summary: A small tool which can convert automatically synthesised formally verified controllers into concise decision trees.
Home-page: https://dtcontrol.model.in.tum.de/
Author: Mathias Jackermeier
Author-email: mathias.jackermeier@outlook.de
License: MIT
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: dd (==0.5.5)
Requires-Dist: Jinja2 (==2.10.3)
Requires-Dist: pandas (==0.25.2)
Requires-Dist: psutil (==5.6.7)
Requires-Dist: pydot (==1.4.1)
Requires-Dist: ruamel.yaml (==0.16.10)
Requires-Dist: scikit-learn (==0.22)
Requires-Dist: tabulate (==0.8.6)
Requires-Dist: tqdm (==4.42.0)

##########################################################################
dtControl: Decision Tree Learning Algorithms for Controller Representation
##########################################################################


*******************
System requirements
*******************

To run dtControl, you need Python 3.6.8 or higher with several other libraries which are automatically installed if installing with the python-based ``pip`` package manager. We have tested the installation and basic functionality on Ubuntu Linux, MacOS Catalina and Windows 10.


************************************
Installing dtControl on your machine
************************************

For most users, running the following command should install the latest version of dtControl, as long as you have Python 3.6.8 or newer and ``pip`` installed on your system::

    $ pip install dtcontrol

Note that in case you have both Python 2 as well as Python 3 installed, you might have to run ``python3 -m pip install dtcontrol``.


*******************
Manual Installation
*******************

*Note: In case of difficulty when following any of the instructions in this section, please check the section 'Common Installation Issues' below*

1. Make sure you have ``python3.6.8`` (or newer) and ``pip3``.

   On Ubuntu 16.10 or newer::

       $ sudo apt-get install python3.6 python3-pip

   On MacOS::

       $ brew install python3

   On Windows, you could, for example install Python 3 and ``pip`` via `Chocolatey <https://docs.python-guide.org/starting/install3/win/>`_.
2. Use a virtual environment to make sure that the installation is clean and easy, and does not interfere with any other python packages installed in your system. Create a new folder ``dtcontrol`` and create a virtual environment inside it and activate the virtual environment::

       $ mkdir dtcontrol
       $ cd dtcontrol
       $ python3 -m venv venv
       $ source venv/bin/activate

   Run ``python`` and verify that the displayed version is greater than 3.6.8. Press ``Ctrl+D`` to exit the python console again.
3. With the virtual environment activated, run::

       $ pip install dtcontrol

   This should install *dtControl* and all its dependencies. Try running *dtControl* by typing dtControl in the console. It should print the help text.


**Uninstallation** You can delete the ``dtcontrol`` folder created above to delete all traces of dtcontrol as well as its dependencies.

**************************
Common Installation Issues
**************************

1. If ``sudo apt-get install python3.6`` does not work, this `askubuntu answer <https://askubuntu.com/questions/865554/how-do-i-install-python-3-6-using-apt-get)>`_ might help you.
2. In case of errors when trying to run ``virtualenv``, check that it is located in a directory that is included in your path; this `stackoverflow answer <https://stackoverflow.com/questions/31133050/virtualenv-command-not-found>`_ might be relevant.
3. If you don't see what went wrong, leave the virtual environment (run "deactivate"), delete the folder ``rm -rf ~/dtcontrol-venv`` and go through all the installation steps again. If errors still occur, please `raise an issue <https://gitlab.lrz.de/i7/dtcontrol/-/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=>`_ or `contact us <https://dtcontrol.model.in.tum.de>`_.

***********************
Running the experiments
***********************

This section assumes you have installed *dtControl* so that upon entering dtControl in your command line, the help text is displayed. Additionally it assumes that you have unzip-ed all examples in ``./dtcontrol/examples``. If you installed dtControl via ``pip`` and you do not have the examples folder, you can `download dtControl examples <https://gitlab.lrz.de/i7/dtcontrol/-/archive/master/dtcontrol-master.zip?path=examples>`_ and extract them into ``./dtcontrol/examples``.

To execute a single algorithm on a single model, run a command like::

    $ dtcontrol --input ./dtcontrol/examples/cartpole.scs --use-preset maxfreq --timeout 30m

If run successfully, this should create a ``benchmark.html`` file displaying the results of the current run. It should also create a ``decision_trees`` folder containing the output (DOT and C files) decision trees.

We have pre-defined a few preset methods, which can be listed using::

    $ dtcontrol preset --list

Run ``dtcontrol preset --sample`` or see the `manual <https://dtcontrol.readthedocs.io>`_ for details on how to pick and mix your own presets.

Other commands can be found by running::

    $ dtcontrol --help

******************
Reading the output
******************

To get an overview of the results, the file ``benchmark.html`` is created in the directory from which you call dtControl.  You can open it in any browser.


