Quickstart

Technology

This simulator uses Python 3.7.7. You are free to use any version you desire, but we do not guarantee the simulator will work under such conditions. Any version launched before 3.7.x will not run this project due to retro compatibility errors. We recommend using an IDE such as PyCharm or equivalent for easier code inspection, usage and overall faster and, more stable workflows.

Installation - Part I

  1. Download and install Python 3.7.x or higher:

- https://www.python.org/downloads/release/python-377/

  1. Clone our repository at:

- https://github.com/FranciscoKloganB/hive-msc-thesis

  1. We recommended using JetBrains’ IDEs, but you can skip this step:

- https://www.jetbrains.com/pycharm/download

4. Create a virtual environment of your choosing, two example guides are linked below:

- https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/
- https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html

  1. Make sure pip and setuptools are installed and working, official guide below:

- https://packaging.python.org/tutorials/installing-packages/

6. This step is applicable only if you desire the possibility to call MatLab (requires valid license and installation) code from within the Hives simulator. More details are given in the link below. In short you want to install the MatLab package, which is not available in open-source repositories. This requires you to navigate to the folder where MatLab is currently installed and running their engine setup.

- $ cd matlabroot/extern/engines/python
- $ python setup.py install
- https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html

7. Navigate to hive folder located at the root of your recently cloned project:

- $ cd hive

8. Install project dependencies by opening your terminal and inserting the commands:

- $ pip install numpy
- $ pip install -r requirements.txt

The previous steps complete the setup of your Hives project. If you have or can obtain licenses for Mosek or MatLab, read Installation - Part II, otherwise read Disabling Licensed Components.

Installation - Part II

Throughout the development of the project, a handful of convex optimization problems had to be solved. We used the CVXPY package to tackle that issue; unfortunately, the solvers available to Python are few and not very powerful, specially when it comes to open-source ones. For semi-definite programming problems with utilized Mosek. We let CVXPY select the solver for global optimization problems, from among the pool of installed solvers. We also use BMIBNB solver from MatLab (through the MatLabEngine) using YALMIP because the latter supports non-convex constraints.

To use MOSEK along with CVXPY follow the installation instructions linked below:

  1. Mosek licensing quick start.

- https://docs.mosek.com/9.2/licensing/quickstart.html

  1. Installing Mosek on your python environment.

- https://docs.mosek.com/9.2/pythonapi/install-interface.html

For the MatLab Engine to work you need to have MatLab R2020a or higher installed on your machine with a valid license. After you installing and validating the software, you should install YALMIP. BMIBNB is bundled with YALMIP by default and no further action is required.

Disabling Licensed Components

As explained in the previous session, some licensed components were needed during the development of our research, which we bundled with the simulator source code for demonstrative purposes. Concerning Mosek, you do not need to take any action. Any modules’ functions that use the Mosek Optimizer API through CVXPY check if the package is installed and properly licensed before using it in favor of other open-source solvers. Concerning MatLab you should not need any further action either - our modules deal both with invalid licenses and Pythons’ AttributeError transparently when invoking MatLabEngine methods as a result of our singleton, thread-safe, implementation of MatlabEngineContainer.

Usage

A typical usage of the Hives simulator would include the following sequence of commands (see Scripts and Flags section for option details), responding accordingly to any prompts that appear on your command line terminal:

$ cd hive/app

$ python simfile_generator.py --file=test01.json

$ python hive_simulation.py --file=test01.json --iters=30 --epochs=720