To pin or not to pin the requirements

[Spectre5]

I want to have a discussion on pinning dependencies. Since section-properties may be used for real engineering applications, you would ideally be able to exactly re-produce an analysis at any later time, simply by knowing which version of section properties was used. Currently, that isn't possible as a given version of section-properties may have different versions of numpy, scipy, meshpy, etc installed as well as different sub-dependencies.

When it comes to pinning dependencies, there is an important distinction between a "library" and an "application" (end product).

A library typically isn't used by itself; it is intended to be used in another project with other dependencies and thus it should avoid pinning dependencies so that it can remain as compatible as possible with anything else the user installs. If all libraries pinned their dependencies, then there would be countless dependency conflicts! Currently section-properties does not pin dependencies.

For an end-user application though, it is generally best practice to pin the dependencies so that all users get the same versions (maybe not the same sub-dependencies though).

I see section-properties as somewhat in between. It doesn't really have a direct user interface and thus needs to be used in a script, but most use cases are probably just using the library itself in a script to analyze and output some data which is effectively treating it as an application. Then again, someone could include it in some other larger application with a GUI and all the bells and whistles.

There are lots of discussions on dependencies and pinning, applications vs libraries, etc. Here are a few links:

• one
• two
• three

I'm not trying to advocate either way here, I just want to make sure everyone understand this potential issue. I think I see section-properties as closer to a library and thus probably should not pin the dependencies. As already mentioned, even if they were pinned, and sub-dependencies wouldn't necessarily be the same anyway. Thus, if an end user wants to be 100% sure they can exactly reproduce an analysis, then they should probably install section-properties into a new virtual environment and pip freeze that entire python environment to a requirements file. Then they'll have a list of every library version, including all sub dependencies, that was used to generate their analysis.

[Czarified]

Interesting, I've never heard of "pinning" before... I just write out the library versions to a log file any time I'm doing something important, so I can at least reproduce my own results. I think there's no need to pin all the dependencies.

In reality, I think there's really only 3 libraries that could mess with our results: meshpy, scipy, and shapely.

meshpy probably won't be an issue. Triangle seems frozen, and there's not a lot of activity on GitHub. We could probably pin it with no issues, but it's also very unlikely to change in a way that will modify results.

scipy already causes a minor dependency issue for me. I'm writing a full library at work that applies structural methods for hand calculations and automatically writes reports. I use sectionproperties for my beams checks. I use a scipy optimize function in there somewhere, and I can't just install the latest scipy 1.6.2, because we say it needs to be <1.6. (See #43 for Robbie's explanation here, it will probably get changed at some point). If scipy were to change/break their optimizatoin functions, it could mess up our results, but only the plastic/warping results (and only if Connor doesn't replace them with shapely entirely). Again, I think the risk here is very low.

shapely is more of a wild card to me. I know very little about it, and what could change in a future release and mess up our usage.

So overall I'm in the camp of leaning into low risk that things will break with updated dependencies, and leaving that risk for users to manage as they deem necessary.

[Spectre5]

So it sounds like you follow that last paragraph I mentioned?

Overall, I agree with you. I think we shouldn't pin. But I wonder if adding part of that last paragraph would be a good idea. In the end, we can't control whatever a user is going to do, but we could suggest in a section of the README that they use a separate virtual environment for any engineering work and pip freeze the requirements as it is the only way they can be sure to get exactly re-producible results.

On a tangent, if using certain stochastic optimizer in scipy (not that section-properties does), then to get exactly repeatable results you may need to make sure you set the numpy random seed! Particularly if the optimization function is complicated/highly non-linear. I was recently bit by that at work for an optimization script and it took me a little bit to figure out why I was getting different results when I used the same inputs!