Skip to content

AutoMATES Getting Started

Jump to bottom
Clayton T. Morrison edited this page Sep 11, 2022 · 3 revisions

Setting up AutoMATES for development

Requirements

  1. Python 3.8
  2. Python virtual env installed (Installation — virtualenv 20.8.2.dev10+g6633e85 documentation)

Download repository

  1. Get access to the automates repository (GitHub - ml4ai/automates: AutoMATES: Automated Model Assembly from Text, Equations, and Software)
  2. Clone the automates repository onto your machine using git clone

Virtual Env

The first step to running code from the AutoMATES project is setting up your virtual environment. This is a fairly simple process.

  1. Have python virtual environment installed.
  2. Change directory into the root of your clone of the automates repository.
  3. Run something along the lines of python3 -m venv ~/.venvs/automates and replace ~/.venv/automates with your preferred venv location.
  4. Run source ~/.venv/automates/activate (replace the path with the path you used)
  5. Install Graphviz as described below
  6. Install required dependencies by running pip install -e . in the root directory of the repo

Your virtual environment should now be set up!

Install Graphviz

Debian flavored linux

  • Use the command: sudo apt-get install graphviz libgraphviz-dev pkg-config

macOS with Homebrew

  • Use the command: brew install graphviz
  • Install PyGraphviz to your virtualenv with: pip install --install-option="--include-path=/usr/local/include/" --install-option="--library-path=/usr/local/lib" pygraphviz

Installing GCC for GCC plugin development

See the README located in automates/program_analysis/gcc_plugin/

Repository Structure

At the root level of the repository there are several relevant directories:

  • automates - Contains the core AutoMATES library code. There are distinctions within the subdirectories here that are outlined below.
  • scripts - This directory has subdirectories that mirror the subdirectories of automates. They all contain scripts which make development, testing, and demoing easier. These are separate from automates as they are not tested by the CI/CD pipeline and testing framework.
  • notebooks - Similar to scripts, except containing jupyter notebooks.
  • tests - This has subdirectories that mirror automates. Each one of these subdirectories contains python test files that use the purest framework. There is one extra directory under tests called data that contains any relevant data files (typically json files) needed to test our code.

The relevant directories under automates are:

  • apps - Contains the server side code for apps that use the AutoMATES libraries (such as the AutoMATES app) .
  • equation_reading - Code related to the ER portion of the project. I (Daniel) have personally not worked on this and I am not sure if any of the code under here is in use.
  • model_assembly - This directory has code for assembly of models into into function networks and grounded function networks (GrFN — a normal function network generated by PA enriched with metadata). The actual data model for GrFN lives here in the networks.py file as the GroundedFunctionNetwork class. It also has the code for executing GrFNs.
  • model_analysis - This directory contains code to analyze GrFNs. Note that the networks.py file under here is a deprecated version of the one found under model_assembly and she be removed eventually. The code analysis that exists and works currently is sensitivity analysis in sensitivity.py.
  • program_analysis - Contains all code related to our program analysis framework such as PyAST2CAST, GCC2GrFN (A more appropriate name for this would be GCC2CAST), CAST2GrFN, and gcc_plugin. Some directories under here are deprecated and should eventually be removed such as for2py (now handled by GCC2GrFN), translators, and Py2GrFN (an initial attempt at translating python into GrFN that does not use CAST).
  • text_reading - Contains code for the text reading portion of the project as well as the text reading web application. Note that this part of the project is written in Scala.
  • utils - Contains some small files of shared code between the different libraries.

Testing

PyTest

Tests are implemented via PyTest. All tests exist under tests/<appropriate library>. When dealing with complex results that we want to verify and are hard to hardcode all of the expected values (i.e. a GrFN or CAST object), we save the expected results under tests/data/<appropriate library>/ as a json file. We then load this json file and compare the output results to it.

To run all tests, have your venv activated and run pytest tests/ from the root directory.

To run all tests in a particular file, simply name the file like so: pytest tests/program_analysis/GCC2GrFN/test_gcc_plugin_c.py

To run a single test from a file, select the file and test name using the -k option: pytest -k "test_execute_sir_simple_mock" tests/apps/automates/execution

Testing in Docker

There is a Docker file in the root directory of the repository the creates a container that allows a consistent testing environment. A built image of this container exists on docker hub. These are the steps to test automates using this image.

Prereqs

  1. We assume you have docker installed and the daemon running on your machine.

Steps

  1. Run docker pull ml4ailab/automates:latest
  2. Run docker run -itd --name test-con -v <Path to your automates repository>:/automates/ ml4ailab/automate:latest. This runs a container using the automates image, names the running container test-con and mounts the directory /automates/ inside of the container to the path <Path to your automates repository> on your machine.
  3. Run the tests via docker exec test-con make test

This will run all the tests in the docker container.

Contributing

When contributing, you should create a branch off of the master branch of the repo. A good naming convention to follow is <your GitHub name>/<purpose of branch>. For example, if I was fixing a GrFN execution bug, I could name a branch dpdicken/grfn-execution-fixes.

Add commits to your branch and push as you develop your code. When it is finished and you have verified the tests work in docker, you can push your code to GitHub and open a PR and add reviewers. This will run our CI which check several things:

  1. If all of the tests pass (this is done in the same Docker testing environment you can use locally)
  2. CodeFactor code style checks. This will check the code you added and report any simple code structure improvements you can add.
  3. Code percentage coverage. This will check that the new code you added has appropriate testing coverage.

At least one approving review is needed to merge into master. Once the PR is merged, make sure the automates app is redeployed if any of its mechanisms were impacted (see here) .

IDE

You are free to use the IDE of your choice, but a lot of the lab members use either Visual studio code or pycharm.

If you use visual studio code, it is fairly easy to set up auto formatting (we use the Black python formatting tool), use the automates venv, and setup the debugger .

Clone this wiki locally