search

jhrmnn / pyberny

Molecular structure optimizer
Mozilla Public License 2.0
110 stars 21 forks source link

Documentation #31

Closed litman90 closed 5 years ago

litman90 commented 5 years ago

Hi, I report this here rather than sending a personal email since several people could be interested to comment. Basically, the documentation provided is quite general. It would desirable to have a more specific explanation of, at least, which features this project contains. The documentation only describes how the internal coordinates are computed and sketches how to go back to cartesian ones. Something like, which actually optimization algorithms are already implemented or if any constraint can be applied would help to any potential user (like me) to know if he/she is interested in the project and if it is worth it to spend some time navigating through the code or not.

I guess that it shouldn't be too difficult or time-consuming, but it would be quite useful. Regards, Yair

jhrmnn commented 5 years ago

I agree that the documentation could be broader, and what's in the Algorithm section is a bit random. But I also thought that I already cover the most important bits in the README. What are you missing in particular? In terms of features, it's basically this:

The algorithm is an amalgam of several techniques, comprising redundant internal coordinates, iterative Hessian estimate, trust region, line search, and coordinate weighing, mostly inspired by the optimizer in the Gaussian program.

Anything that is not mentioned there is not supported. So, for instance, there are no constraints at the moment.

The top-level logic of the algorithm is essentially the Berny.send() routine:

https://github.com/azag0/pyberny/blob/master/berny/berny.py#L110-L169

If that was described in human speak in the documentation, would you find that sufficient?

litman90 commented 5 years ago

Those 3 lines are adding valuable information. I would also suggest differentiating, if possible, which algorithms/implementations are the standard textbook ones, which are less standard but still have a reference that could be cited and finally, which are original in this library. I think that together with the lines you wrote above, it would be sufficient as a project description for any potential new user. Then going through the code to understand the details will be up to the user.

jhrmnn commented 5 years ago

I've updated the readme and the algorithm section of the docs. Let me know if you find it sufficient now.

litman90 commented 5 years ago

Yes, now it is pretty clear. Thanks