The wombats Library

This repo houses the example usage notebooks (experiments) as well as the core wombats and flexfringe libraries powering the framework.

Docker Installation

Please use VSCode to build an image from Dockerfile and reopen VSCode in the remote container. Please follow the official guide.

After opening VSCode in the container, run

conda activate wombats
jupyter notebook

Local Installation

Please take a look at inside the Dockerfile for specific steps.

• install anaconda (if you want to work with conda)

• install flexfringe dependencies for your OS, listed here. Please take a look at the Dockerfile.

• clone this repo with:

git clone --recurse-submodules https://github.com/aria-systems-group/wombats_experiments

• change into this repo's directory:

cd wombats_experiments

• build the flexfringe tool:

cd dfasat && make gitversion.cpp && make && cd ..

Install python packages with Conda

• create the conda environment for this library:

conda env create -f environment.yml

• activate the conda environment:

conda activate wombats

Install python packages with venv+pip

• create virtual environment with ven and pip install packages:

python3 -m venv env
source env/bin/activate
pip install .

Examples

• Launch a jupyter server:

jupyter notebook

• In the jupyter UI, navigate to the experiments directory. Each directory has a self-contained experiment which is housed in the ipynb (jupyter notebook) file. For example, to see a large example that exercises most of the library, open experiments/seshia_paper_reproduction/seshia_paper_reproduction.ipynb. After opening any notebook, click "Cell > Run all" and enjoy!

IROS 2021

Open three different experiments

• 1. simple_running_example_rss
• 2. seshia_paper_reproduction_with_safety
• 3. safe_pdfa_learning_performance_analysis

FlexFringe

If you need to dive into FlexFringe implementation, you should be aware that there is no documentation. However, you can always read the source code to understand the actual implementation as well as "some" documentation generated by Doxygen. All of those are included in the dfasat/doc/ directory.

Navigate to the directory and open index.html. This will open up the documentation on your web-browser.

cd dfasat/doc
open html/index.html

Hyperparameters

The wombat tool includes an interface to FlexFringe library in Python. It simply calls c++ executables from a Python script. If you want to see all the arguments details, either call ./flexfringe --help on your terminal OR create an instance of FlexFringeInterface and call flexfringe.infer_model(get_help=True) in your python script.

flexfringe = FlexfringeInterface(output_directory=LEARNER_DATA_DIR)
flexfringe.infer_model(training_file=train_data_file,
                       h='kldistance',  # change this to alergia
                       d='kl_data',     # change this to alergia_data
                       n='5',
                       x='0',
                       w='0',
                       b='1',
                       f='1',
                       I='0',
                       t='1',
                       l='0',
                       q='0',
                       y='0',
                       p='0.5')

• Change Method Replace -h and -d with appropriate names like kldistance & kl_data or alergia & alergia_data. More algorithms are in dfasat/evaluation directory. Method name and data are registered in each script as follows:

  REGISTER_DEC_DATATYPE(alergia_data);
  REGISTER_DEC_TYPE(alergia);

• Change alpha value in ALERGIA / MDI Algorithm Replace -p with appropriate value. For ALERGIA, it's a statistical test value [0, 1]. For MDI, it's just a threshold for the MDI score (Cross Entropy / No. of Nodes).

MUCH more documentation to come...