Contribution Instructionsο
To contribute to the python package, please follow these simple steps
Fork deephys (not the deephys-aio repository)
Edit the python code
Run the python tests
Check to make sure your edits are still compatible with these docs. If they are not, please edit the docs and include it in your pull request.
Add your changes to the changelist
Run these google colabs (additional python tests)
Before committing, please use black with the default settings to format any files you edit. This simplifies diffs as much as possible. The command should be something like
python -m black source_file.py.Submit a pull request
Our current method for exporting data from MATLAB deep learning pipelines is simply to access the python exporter tool through an embedded interpreter in MATLAB. Here is the example code.
If you would like to help us on the MATLAB front, here are a few ideas:
You could flesh out our MATLAB example code, and perhaps create a full MATLAB demo with real deep learning data
You could create a formal MATLAB toolbox that wraps around the python package
You could write a independent MATLAB exporter tool that has the same set of features as the python tool, but without requiring the python tool. This will presumably be the most ideal solution in the long run, but will take the most work.
Note
If you are considering contributing to the kotlin app, please reach out to us so we can help you get started.
Before contributing to the kotlin app, please consider the following:
The app must be rigorously tested with each change to prevent memory leaks, cpu bottlenecks, and other issues
The app is built for multiple operating systems (Mac OS Silicon, Mac OS Intel, Windows, Linux AArch64, Linux x86). The app should be tested on all of these platforms after any significant changes
The app uses a set of git submodules as libraries. Any changes to these submodules will need their own pull requests
Being performance-intensive software, using a profiler tool such as YourKit is highly recommended
Compiling the app will take a significant amount of time on older machines
Note
The main developer of this software uses a Silicon Mac. If you have a different operating system, you may face issues. If you do, please let us know.
If you are still here, you must be very brave. Read on for step by step instructionsβ¦
Setting up JDK
This is kotlin/gradle project. To compile and run from source requires JDK. The project is developed in OpenJDK 17 on a silicon Mac. Other JDKs and operating systems may or may not work.
If you have never worked on java or kotlin code before, you likely do not have JDK. There are multiple ways to install it.
Setting up JDK: Silicon Mac
openjdk17 is recommended for Silicon Macs. You can install it with Homebrew like so:
brew install openjdk@17
Setting up JDK: Intel Mac
JDK 17 Corretto is recommended on intel macs. While the project is developed using openjdk17 on a silicon mac, for some unknown reason intel macs have an error with openjdk17 and we have found that JDK 17 Corretto works on them. JDK 17 Corretto can be installed through IntelliJ.
Setting up JDK: Linux
sudo apt install openjdk-17-jdk
Setting up JDK: Windows
Nobody has yet attempted to run the visualizer from source on Windows. Will you be the first? If so, please let us know how it goes.
Setting up the Project
Run the following commands to properly clone the repository
git clone --recurse-submodules -j10 https://github.com/mjgroth/deephys-aio
cd deephys-aio
If you have never worked on a java project on your machine, you will need to tell gradle which JDK to use. There are a few ways you can do this.
The recommended approach is to append org.gradle.java.home=/path/to/your/jdk/home to your ~/.gradle/gradle.properties. For more detailed information on setting up your gradle environment, see the Gradle documentation
Common paths to java include:
Mac:
~/Library/Java/JavaVirtualMachines/openjdk-17.0.1/Contents/HomeMac:
/Library/Java/JavaVirtualMachines/corretto-17.0.5/Contents/Home
Running From Source
Now we should make sure that the app runs from source. This is not strictly neccesary to edit the code, but it will be neccesary for tests later on. Use the following command:
./gradlew :k:nn:deephys:run --stacktrace --no-configuration-cache
Note that when running from source through Gradle, command line arguments are passed to the app through a special argument. So if, for example, you need to reset the app, you will need to use a different syntax.
Normally if running the compiled app from source, you would use:
./deephys reset
But through gradle, you will need to use:
./gradlew :k:nn:deephys:run "--args="reset"" --no-configuration-cache --stacktrace
If you successfully ran the app, then you are almost ready to start editing the code!
Concepts to understand before editing the source code
Before editing the code, it may be helpful to understand some concepts:
Strong and weak references in java (critical for memory management and used throughout the code)
Kotlin lambdas (important to understand when a reference is strongly held in a lambda)
Testing
If you would like to submit your edits, we request that you rigorously test the app.
You can run the tests with the following command:
./gradlew :k:nn:deephys:test --stacktrace --no-configuration-cache
You may also add new tests to the test source code to test your new features.
Profiling
Ideally, you can also profile your code. We understand this may not always be possible since most profilers are not free. But if you can, using a java profiler will really help you understand the memory and cpu consumption. This is not required for small edits but if you are adding new features to the app is likely a must.
Testing on other Operating Systems
Your edits may behave unexpectedly on other operating systems. We request you try to test your changes on as many different operating systems as possible.