Skip to content

D. Developer Instructions

Jump to bottom
Hans-Christian Ruiz Euler edited this page Sep 15, 2022 · 11 revisions

This code contains useful libraries that are expected to be used and maintained by different researchers and students at University of Twente. If you would like to collaborate on the development of this or any projects of the Brains Research Group, you will be required to create a GitHub account. GitHub is based on the Git distributed version control system, if you are not familiar with Git, you can have a look at their documentation. If Git commands feel daunting, you are also welcome to use the graphical user interface provided by GitHub Desktop.

The development will follow the Github fork-and-pull workflow. You can have a look at how it works here. Feel free to create your own fork of the repository. Make sure you set this repository as upstream, in order to be able to pull the latest changes of this repository to your own fork by syncing. Pull requests on the original project will be accepted after maintainers have revised them. The code in this repository follows the PEP8 python coding style guide. Please make sure that your own fork is synced with this repository, and that it respects the PEP8 coding style.

0. Prerequisite installs:

0.1 Download and install Anaconda (the current version at the time this wiki was written is 4.12.0) for your Operating System, and install it following the official instructions (Linux, Windows.

0.2 Download and install git, if writing commands in git is daunting for you, you can also use a graphical user interface extension to help you manage the commands.

0.3 If your system has a GPU that supports CUDA, install CUDA on your system first. Make sure that your Cuda version is the highest supported by the latest PyTorch libraries before installing Cuda here. You can download the version you need from the official NVIDIA website.

1. Clone repository:

**Before you start with the installation, decide if you are going to implement your own features that could benefit brains-py or any of its packages. If you are unsure about this, please contact either your University of Twente supervisor or one of the maintainers of this repository. If you are going to develop some code around brains-py please read the developer instructions before doing your installation. Feel free to create your own Github account and fork this repository. Once it is forked, you can clone it from your own fork, instead of this one. **

Clone the repositories you need. Depending on your needs, you can clone, and follow the installation, of one or more of the following packages (brains-py, brainspy-tasks, and brainspy-smg). More information about the packages can be found in the user instructions.

You might require to clone and install the packages from the official repository https://github.com/BraiNEdarwin, or from your own fork https://github.com/ . The main packages can be found in:

If you are planning to add a new feature to this repository, please make sure that you have spoken on which branch it should be done.

2. Create and activate Anaconda environment

2.1 Create an environment (choose name, e.g. "bspy"):

conda create -n bspy python==3.9.1

2.2. Activate the environment:

activate bspy

3. Install brains-py package in development mode

Go to the directory " brains-py", in the directory tree where you cloned the repository. Run the setup file. The setup file can be run with two flags: 'install' or 'develop'. If you intend to modify the code in any way in the future, perhaps adding a new feature, run the following command:

python setup.py develop

3.2 (Optional) If you require to install brainspy-tasks, go to the directory " brainspy-tasks" . Run the setup file with your custom flag:

python setup.py develop

3.3 (Optional) If you require to install brainspy-smg, go to the directory " brainspy-smg". Run the setup file with your custom flag:

python setup.py develop

Prepare development environment

We recommend you to use the open-source development environment of Visual Studio Code for python, which can be installed following the official guide. For Ubuntu users, it is recommended to be installed using snap: sudo snap install --classic code.

This project follows PEP8 formatting and the NumPy style of documentation. In order to follow these, we recommend you to use some packages and extensions. The formatter YAPF makes sure the code follows almost all PEP8 formatting rules. Any problems not fixed by YAPF will be detected by the linter flake8 and can be fixed manually. Flake8 also serves as a good general linter. Additionally, mypy can be used to detect typing issues. Finally, a docstring generator helps with putting the documentation in the right format.

Here are the steps for making these packages work:

  • Open your conda terminal and activate the environment (if you do not have it activated already): conda activate bspy-instr
  • Install the packages from pip:
    • pip install yapf==0.31.0
    • pip install flake8==3.9.1
    • pip install mypy==0.812
    • pip install coverage==6.4
  • From the same terminal, Open Visual Studio Code with the command: code
  • Go to the extensions marketplace (Ctrl+Shift+X)
  • Install the following extensions:
    • Python (Microsoft)
    • Python Docstring Generator (Nils Werner)
  • On Visual Studio Code, press Ctrl+Shift+P and write "Open Settings (JSON)". The configuration file should have the following settings:
{
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": false,
    "python.linting.mypyEnabled": true,
    "python.linting.flake8Enabled": true,
    "python.linting.flake8Args": [
        "--max-line-length=120",
        "--ignore=W503,W504,E126",
    ],
    "editor.formatOnSave": true,
    "python.formatting.provider": "yapf",
    "autoDocstring.docstringFormat": "numpy"
}

In order to add these args, click on the configurations (gear icon on the bottom left of visual studio), and then click on settings. You can find "flake8" on the search bar and click on "add item", under the "Flake8 Args" section. Add each line individually.

These rules have been disabled because they go against the PEP8 recommended style. More info here.

Running tests

Developers of the library are expected to create their own tests. The library used for performing the tests is called unittest.

You can run tests by executing the following command in your environment, in the root folder of your project (e.g., brains-py): python -m coverage run -m unittest

Note that tests can be executed in different modes, depending on if there are National Instrument devices connected or not. To modify the different modes, you can access the variable TEST_MODE at the root package (e.g., brainspy.TEST_MODE). There are three test modes: SIMULATION_PC, HARDWARE_NIDAQ, and HARDWARE_CDAQ. Choose any of those strings depending on which equipment you have connected.

You can have more information about how to create tests and run coverage tests here.

Continuous integration

Continuous integration is supported using circleci.org. You can create an account, give permission to access github, and monitor the status of the tests with your latest commits. This can be done on both a fork or the main repository, depending on where do you have access.

Updating package in pip

You can update the brainspy package in pip by updating the version in setup.py. After the version is updated, make sure it passes all the tests. If the current version passes all tests, you can create the dist files using: python setup.py sdist

Finally, you can upload the dist files using twine: python -m twine upload dist/*

You will be prompted for the credentials. If twine is not installed, you can install it via: pip install twine

Clone this wiki locally