First of all, thank you for considering to contribute! 🙏🎉
The following is a set of guidelines for contributing to the swarmlib. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
To report a 🐛 please file an issue using the bug template. Please fill out the template tediously and provide information as detailed as possible. Include screenshots or GIFs to visualize the problem.
To suggest an enhancement please file an issue using the feature request template. Please fill out the template tediously and provide information as detailed as possible. The template will ask you for all relevant information.
Before starting to code please ensure you explicitly address an issue and comment on that issue indicating that you are working on it.
It would be a shame to reject a PR with your awesome work just because somebody else was faster or due to the lack of an issue.
First you need to fork the repo, clone it and install all dependencies. I recommend you using a virtual environment for development.
# Clone the repository
git clone [email protected]:yourUserName/swarmlib.git
cd swarmlib
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies
make install
# Open the project with VS Code
code .When you open the project the first time with VS Code the editor will ask you to install all recommended workspace extensions. Confirm that dialog and you are all set up.
If you are new to VS Code and python check out the official documentation to get started.
If you want to contribute a new optimization algorithm ensure you opened an issue beforehand.
Please reuse common components that can be found in the swarmlib/util directory.
There is no need to write a new visualization all over again 😉.
When contributing a new algorithm you probably set up / change the following files:
swarmlib
|- swarmlib
| |- your_awesome_new_algorithm
| | |- __init__.py
| | |- main.py // Provide the argument parser for the algorithm
| | |- problem.py // Implement the algorithm here similar to PSO etc. Main work will be done here.
| | |- animal.py // Optional: Subclass of coordinate.py to add additional functions if needed
| | |- visualizer.py // Optional: Subclass of base_visualizer.py if any additional functions are needed
| |- __init__.py // import problem for easier API access
| |- __main__.py // Register the argument parser for the algorithm
| |- _version.py // Update the version according to semantic versioning
|- tests
| |- your_awesome_new_algorithm_test // Unit-Test the major components of your algorithm here (like the WOA does).
| |- ...
|- setup.py // Add new keywords for the new algorithm
|- CHANGELOG.md // Briefly state all relevant changes that will be shipped with the next release
To get started, I recommend you to take a look at the implementation of the CS, PSO, ABC algorithms.
❗ avoid sorting the coordinates list. This will cause the visualizer to wrongly replay position transitions.
Consider the following example with two particles:
The first particle p1 has coordinates (0, 0) and a value of -1.
The second particle p2 has coordinates (1, 1) and a value of 0.
At the start of the algorithm we pass those positions to the visualizer:
Now lets apply an algorithm which causes the first particle p1 to update its position to (-1, -1) with value -0.5.
p2 now has a position (2, 2) with value -2.
Now if we sort the particles with respect to their value p2 is before p1.
When we now pass those to the visualizer and calculated the velocities afterwards the visualizer will calculate wrong velocities:
- p2's first position and p2's second position
- p1's first position and p2's second position
### Step 0
# p1 with position (0, 0) and value 0
# p2 with position (1, 1) and value -1
particles = [p1, p2]
positions = [particles.position for particle in particles]
visualizer = BaseVisualizer(**kwargs)
visualizer.add_data(positions=positions)
# Algorithm is applied...
### Step 2
# p1 with position (-1, -1) and value -0.5
# p2 with position (2, 2) and value -2
particles.sort() # this leads to [p2, p1]
positions = [particles.position for particle in particles]
visualizer.add_data(positions=positions)
# Now the visualizer has internal positions of
# [
# [(0, 0), (1, 1)], # Step 0
# [(2, 2), (-1, -1)] # Step 1
# ]
# If now the velocities are calculated afterwards the visualizer calculates the velocities
# of (0, 0) -> (2, 2) and (1, 1) -> (-1, -1) which is obviously false
visualizer.replay()As of release v0.10.0 swarmlib uses the functions supplied by landscapes. If you are missing a benchmark function please open an issue in the landscapes repository. Once the function is implemented there we are happy to update swarmlib's landscapes dependency.
Please follow these steps to have your contribution considered:
- Reference the issue you are working on e.g.:
Fixes #1 - Add information on how you solved the issue.
- After you submit your pull request, verify that all status checks are passing.
After your pull request was submitted and the status checks pass I will review your changes. I may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
Swarmlib organizes its documentation in a wiki. Please ensure you opened an issue beforehand which provides an explanation of the changes you want to propose to the wiki. After that you can fork the wiki and submit a pull request to address that issue.