Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Prepare v.0.3.0 release #180

Merged
merged 45 commits into from
Aug 9, 2018
Merged

Prepare v.0.3.0 release #180

merged 45 commits into from
Aug 9, 2018

Conversation

ljvmiranda921
Copy link
Owner

@ljvmiranda921 ljvmiranda921 commented Jul 25, 2018

Tasklist (Deadline: August 10, 2018)

Please write the changelog below for our release notes. It would be nice to follow this link.


Release v.0.3.0

We're proud to present the release of PySwarms version 0.3.0! Coinciding with this, we would like to welcome Aaron Moser (@whzup) as one of the project's maintainers! v.0.3.0 includes new topologies, a static option to configure a particle's neighbor/s, and a revamped plotters module. We would like to thank our contributors for helping us with this release.

Release notes

New Topologies and the GeneralOptimizerPSO Class

New topologies were added to improve the ability to customize how a swarm behaves during optimization. In addition, a GeneralOptimizerPSO class was added to enable switching-out various topologies. Check out the description below!

New Topology classes and the static attribute

The newly added topologies expand on the existing ones (Star and Ring topology) and increase the built-in variety of possibilities for users that want to build their custom swarm implementation from the pyswarms.backend module. The new topologies include:
- Pyramid topology: Computes the neighbours using a Delaunay triangulation of the particles.
- Random topology: Computes the neighbours randomly, but systematically.
- VonNeumann topology: Computes the neighbours using a Von Neumann topology (inherited from the Ring topology)
With these new topologies, the ability to change the behaviour of the topologies was added in form of a static argument that is passed when initializing a Topology class. The static parameter is a boolean that decides whether the neighbours in the topologies are computed every iteration (static=False) or only in the first one (static=True). It is passed as a parameter at the initialization of the topology and is False by default. Additionally, the LocalBestPSO now also takes a static parameter to pass this information to its Ring topology. For an example see below.

The GeneralOptimizerPSO class

The new topologies can also be easily used in the new GeneralOptimizerPSO class which extends the collection of optimizers. In addition to the parameters used in the GlobalBestPSO and LocalBestPSO classes, the GeneralOptimizerPSO uses a topology argument. This argument passes a Topology class to the GeneralOptimizerPSO.

from pyswarms.single import GeneralOptimizer
from pyswarms.backend.topology import Random

options = {"w": 1, "c1": 0.4, "c2": 0.5, "k": 3}
topology = Random(static=True)
optimizer = GeneralOptimizerPSO(n_particles=20, dimensions=4, options=options, bounds=bounds, topology=topology)

The plotters module

The environments module is now deprecated. Instead, we have a plotters module that takes a property of the optimizer and plots it with minimal effort. The whole module is built on top of matplotlib.

 import pyswarms as ps
 from pyswarms.utils.functions import single_obj as fx
 from pyswarms.utils.plotters import plot_cost_history

 # Set-up optimizer
 options = {'c1':0.5, 'c2':0.3, 'w':0.9}
 optimizer = ps.single.GlobalBestPSO(n_particles=50, dimensions=2, options=options)
 optimizer.optimize(fx.sphere_func, iters=100)

 # Plot the cost
 plot_cost_history(optimizer.cost_history)
 plt.show()

Imgur

We can also plot the animation...

from pyswarms.utils.plotters.formatters import Mesher
from pyswarms.utils.plotters.formatters import Designer
from pyswarms.utils.plotters import plot_contour, plot_surface

# Plot the sphere function's mesh for better plots
m = Mesher(func=fx.sphere_func)

# Adjust figure limits
d = Designer(limits=[(-1,1), (-1,1), (-0.1,1)],
             label=['x-axis', 'y-axis', 'z-axis'])

In 2D,

plot_contour(pos_history=optimizer.pos_history, mesher=m, mark=(0,0))

Contour

Or in 3D!

pos_history_3d = m.compute_history_3d(optimizer.pos_history) # preprocessing
animation3d = plot_surface(pos_history=pos_history_3d,
                           mesher=m, designer=d,
                           mark=(0,0,0))    

Surface

ljvmiranda921 and others added 30 commits June 11, 2018 18:59
This commit makes the if-else statements in generators more concise.
To be honest, I didn't know what came into my mind as to why I nested
those if statements. It turns out that using the "and" operator is
much, much better.

Signed-off-by: Lester James V. Miranda <[email protected]>
Modify if-else statements in generators
In this commit, we add a DeprecationWarning for the PlotEnvironment
module. Although useful, I realized that it might be a hassle when the
environment still optimizes the optimizer if we just want to plot it.

What if a swarm iteration takes a long time? Will plotting take the same
amount of time? We want to decouple the optimization part from the
visualization.

It is better to just have the user supply the position and
cost histories and we just have the module do what it knows.

Signed-off-by: Lester James V. Miranda <[email protected]>
In this commit, we decided to remove the @Property in storing
the dependency. I found this very redundant and violates Python's
rule of having only one way of doing things. Instead, we just
access the histories from the class/instance attributes

Signed-off-by: Lester James V. Miranda <[email protected]>
In this commit, we updated the tests on the optimizers to reflect
the changes on using @Property. It's much better now because our
tests are parameterized than having multiple asserts.

Signed-off-by: Lester James V. Miranda <[email protected]>
This coincides with the decision to deprecate the PlotEnvironment.
The whole environments module is now unsupported, and users will
now be required to use the plotters module instead.

Signed-off-by: Lester James V. Miranda <[email protected]>
Reference: #130

This commit adds a plotters.py module to replace the environments
module. We hope that we can actually decouple the optimization and
visualization part, without having the environment to do another
rollout of your PSO.

Signed-off-by: Lester James V. Miranda <[email protected]>
Reference: #130

The problem before is that we tend to have many parameters in our
plotting functions. The formatters module changes that. We have
three types of formatters: Designer, Animator, and Mesher. There
are defaults present, but the user can change and pass them to the
ploting functions whenever needed.

Signed-off-by: Lester James V. Miranda <[email protected]>
Sometimes your swarm can generate a pure 0 or pure 1 vector,
we should account that.

Signed-off-by: Lester James V. Miranda <[email protected]>
This commit adds the plotters module into ReadTheDocs index
and adds a deprecated information on plot_environment.py

Signed-off-by: Lester James V. Miranda <[email protected]>
This commit updates the docstrings in formatters.py
and adds a legend attribute in plotters.py

Signed-off-by: Lester James V. Miranda <[email protected]>
This commit formats the majority of pyswarms code using the
black formatter. This will be our new formatter from this point
forward.

Signed-off-by: Lester James V. Miranda <[email protected]>
This commit adds the .flake8 and pyproject.toml to specify flake8
and black configuration. In addition, we updated the code to reflect
the warnings found in flake8.

Signed-off-by: Lester James V. Miranda <[email protected]>
In this commit, we explicitly say that we are using black as our
code formatter.

Signed-off-by: Lester James V. Miranda <[email protected]>
Format code using black and add pre-commit hooks
Resolves #136 

Created an Inverse Kinematics Tutorial in a Jupyter Notebook.
Committed with @whzup
Reference: #129 

Created a class for the implementation of a pyramid topology using Delaunay
triangulation. Additionally, @whzup changed a small error in the description
of the `compute_velocity()` method in the Ring class.

Notes:
- For v.0.2.0-dev.3.
- TODO: Update README in dev

Committed with: @whzup 
Signed-off-by: Lester James V. Miranda <[email protected]>
Resolves #143 

This commit adds a `**kwargs` parameter to the `optimize()` method
to pass arguments directly on the objective function. Additional tests
and documentation were also provided.

Committed with @bradahoward 
Signed-off-by: Lester James V. Miranda <[email protected]>
Created a GeneralOptimizer class with a topology parameter so one can choose which topology to use. Some special additions implemented:

 - Added an error message in case the topology attribute has the wrong type.
 - Added a special case for the ring topology so it's the same as local optimization.

Also, created the corresponding test file and updated the documentation as well as the RST files for the GeneralOptimizer as well as the Pyramid topology.

Resolves: #148
Fixed an index error in the Pyramid class that occured because the type of the idx array did not match 'int'
Reference: #129 

Added a new topology with random neighbors. Added documentation and
a test file for it and reworked the documentation of the GeneralOptimizer 
class to incorporate all available topologies. Simplified the fixture function 
for the GeneralOptimizer class. Cited the relevant paper for the 
algorithm implemented.

Updated the documentation of the Random class. 
Especially the __compute_neighbor() method. Added the comments
inside the method to the docstring and deleted irrelevant comments.
Changed the nested for-loops to one loop with the itertools library.
Added a new test for the return value of the __compute_neighbor() 
method, which checks the shape and the symmetry.
Added a new test for the return value of the __compute_neighbors() 
method, which compares the returned matrix with a preset comparison 
matrix using a seed.

Signed-off-by: Lester James V. Miranda <[email protected]>
Committed-by: @whzup
Reference: #129

Added two new attributes to the topologies. `static` decides whether the topology
is a static or a dynamic one, it is initialized together with the class. `neighbor_idx` 
is an array that stores the indices of the neighbors of every particle. Changed 
all occurrences of topologies to fit the new initialization. Reworked the tests to 
fit the new functionality and added more parametrization of fixture functions. 
Updated the documentation to incorporate the new functionality.

Signed-off-by: Lester James V. Miranda <[email protected]>
Commited-by: @whzup
@ljvmiranda921 ljvmiranda921 modified the milestone: Version Release (v0.2.0) Jul 30, 2018
Copy link
Collaborator

@whzup whzup left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Release Status

I guess it's all fine from my side. The tests run and the GeneralOptimizerclass with all the topologies look fine. I'll go ahead and beat the topologies a bit more until 12. August, hopefully without finding a bug 😄. I've written the first draft for my changelog, where shall I deposit it?

@ljvmiranda921
Copy link
Owner Author

Yes, I think you're fine and it's my turn to finish all other admin tasks. Let me do them next week, I'll now move between cities this weekend! 👍

For the Changelog, you can just copy paste them below the TaskList above. 👍

@ljvmiranda921
Copy link
Owner Author

Awesome work, can you also link the corresponding PR/s for each feature? Thank you so much and sorry for the hassle.

This commit updates all image source from local to Imgur.
Turns out that whenever we create a setup file, the docs
directory is excluded, thus, the images are nowhere
to be found. By sourcing them from Imgur, we can
resolve this problem.

Signed-off-by: Lester James V. Miranda <[email protected]>
@ljvmiranda921
Copy link
Owner Author

ljvmiranda921 commented Jul 31, 2018

Release Status

Everything is fine on my end. We are ready to release on August 10, 2018.
If there are any bugs before that time, hopefully we can resolve them. If not,
let's just make patch releases (e.g. 0.3.1, 0.3.2, etc.) in the future.

For boundary conditions, let's just put that on v.0.4.0. It coincides with other features
we are actually planning so it might be a better fit.

I think the Release Notes are fine. We can even edit that after releasing so there's no pressure
to make it perfect from the get-go.

cc: @whzup @SioKCronin

@whzup
Copy link
Collaborator

whzup commented Jul 31, 2018

How did you make the fancy pictures in the release notes for 0.2.0? Maybe we could use something similar for this one 😋 BTW, have you updated this part of the documentation with the new features?

@whzup
Copy link
Collaborator

whzup commented Jul 31, 2018

I added this

from pyswarms.utils.plotters import plot_contour, plot_surface

to the changelog for completeness 👍

@whzup
Copy link
Collaborator

whzup commented Jul 31, 2018

These parts of the documentation are outdated:

@ljvmiranda921
Copy link
Owner Author

ljvmiranda921 commented Aug 1, 2018

Hi @whzup ,

How did you make the fancy pictures in the release notes for 0.2.0?

LaTeX with TikZ 👍 There's a steep learning curve though, haha!

Maybe we could use something similar for this one

What kind of diagram do you propose? Sure no problem!

BTW, have you updated this part of the documentation with the new features?

I think there's no need. This part only describes the general API. And our new version doesn't really break that. We can leave this one out for now. 👍

@ljvmiranda921
Copy link
Owner Author

ljvmiranda921 commented Aug 1, 2018

Hi @whzup ,

These parts of the documentation are outdated:

You are correct and thanks for catching these! Would you like to make a PR? I can, but I might be able to fix this next week 😕

Thanks a lot @whzup ! I'm excited for the new release!

@whzup
Copy link
Collaborator

whzup commented Aug 3, 2018

Hey @ljvmiranda921, I was a bit inactive the last few days due to some issues with my computer and time management 😄 I started working on the deprecated parts of the docs and I thought while on it, I could integrate the roadmap? We could put it in the General section, what do you think?

Updated the documentation of the base class to include the
GeneralOptimizer. Additionally, changed the chapter "Writing unit test"
in the dev.optimizer.rst because we don't use the unittest module
anymore. I replaced the "unittest" module with the "pytest" module and
rewrote some parts of the paragraph so it reads a bit more easily. Also,
added a link to the pytest docs for the running of tests.
@ljvmiranda921
Copy link
Owner Author

I started working on the deprecated parts of the docs and I thought while on it, I could integrate the roadmap? We could put it in the General section, what do you think?

Oh, you mean put the roadmap in the documentation? Sure I think that's a nice idea but our roadmap seems to be a "live" document that we'll keep on updating. Normally I'll start with something general and then we make it more specific etc.

But yeah sure, we can put a "Roadmap" section under general (last part) and then we update them after every release!

@whzup
Copy link
Collaborator

whzup commented Aug 6, 2018

Hi @ljvmiranda921, I just saw the release notes for GitHub Desktop and I really like their formatting. We could use some of their elements, for example:

I guess the labels (new, fixed, etc.) are made with images.

@ljvmiranda921
Copy link
Owner Author

ljvmiranda921 commented Aug 6, 2018

This looks interesting @whzup . Wanna do it for v.0.3.0? I think we can get by with bold labels. 👍

@whzup
Copy link
Collaborator

whzup commented Aug 6, 2018

I changed the release notes above. They look pretty slick now, don't they?😋

@ljvmiranda921
Copy link
Owner Author

ljvmiranda921 commented Aug 7, 2018

This is awesome, @whzup ! Do you have edit access on the release notes here? It would be nice if the formatting is uniform.

I guess this kind of formatting will work in our History I can do this on Friday night or on the weekend. 👍

@whzup
Copy link
Collaborator

whzup commented Aug 7, 2018

I do have access! Shall I do this today? I'd have some spare time 😄 For the History we could use coloured labels like the GitHub Desktop example, what do you think? If so, we should style them differently though 😋

@ljvmiranda921
Copy link
Owner Author

Shall I do this today? I'd have some spare time smile

Sure! If you want, then much better!

For the History we could use coloured labels like the GitHub Desktop example, what do you think? If so, we should style them differently though

How can we achieve this? Small image labels or just colored text? If the icons look ugly then using bold letters may suffice. 👍

@whzup
Copy link
Collaborator

whzup commented Aug 7, 2018

@ljvmiranda921, I reformatted the release notes on GitHub. In my opinion, they look pretty slick now 😄 I unified the formatting to fit our "standard" for 0.3.0 and corrected some spelling and grammar errors. I noticed that in the History tab at RTD you mixed up two PRs (113 and 114 in 0.2.0) and a link is visible in the 0.2.1 notes.

@ljvmiranda921
Copy link
Owner Author

ljvmiranda921 commented Aug 8, 2018

I reformatted the release notes on GitHub. In my opinion, they look pretty slick now smile I unified the formatting to fit our "standard" for 0.3.0 and corrected some spelling and grammar errors.

Understood. Yes, they look much cleaner now!

I noticed that in the History tab at RTD you mixed up two PRs (113 and 114 in 0.2.0) and a link is visible in the 0.2.1 notes.

Will you make a PR on this (+ similar standard on our Release Notes)? If not, we can just do this on v.0.4.0. Really sorry for I've been quite busy due to internship. 😭

@whzup whzup mentioned this pull request Aug 8, 2018
10 tasks
Added the GeneralOptimizer and the plotters module to the features.rst
file and provided a deprecation warning in the environment package.
Updated the HISTORY.rst file with the new release note format based on
the notes in #180.
@ljvmiranda921
Copy link
Owner Author

Hi @whzup , this looks good already. I will merge to master today so that tomorrow I can just upload the tarballs and wheel files and then we'll be all set!

@ljvmiranda921 ljvmiranda921 merged commit f58d308 into master Aug 9, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
admin System-related and potential overrides
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants