pyroll-project / pyroll-docs Goto Github PK

Hello!

Thank you for sharing the repository

Related to the review at openjournals/joss-reviews#6200, I have the following commands and suggestions:

• A statement of need: On the main page, it would be useful to more explicitly state what problems the software is designed to solve and who the target audience is. For example, I am still not entirely sure what predictions the tool is actually making and how it should be used.
• Example usage: For the "Basic Example" at https://pyroll.readthedocs.io/en/latest/examples/basic.html, it would be useful if you could briefly explain what this example is doing, i.e. what it is simulating, what are the inputs, what are the outputs. It seems to be a relatively complex process (many passes) for a basic example; I wonder if a demonstration of a more simple example with a more detailed description would be more helpful in teaching new users about using the tool? Alternatively, it would be good if you could give more details about the input file.
• Example usage: At the end of https://pyroll.readthedocs.io/en/latest/examples/basic.html, it would be useful if you could provide instructions on where to learn more about how to use the packages (i.e., which page should I go to next). For example, I see that the definition of a RollPass is explained in https://pyroll.readthedocs.io/en/latest/examples/step_by_step/index.html#using-just-the-core.
• Automated tests: Does the repository contain any test script to check if it was installed correctly? For example, a test script runs a simple problem and compares the answers to reference values.
• Functionality: It would be useful if the documentation summarised the main functionality of the toolbox, that is, what features it has and what it can do.

Maybe use https://semver.org/ to explaining versioning and further explain what it means regarding compatibility between plugins.

As of today, the updated pyroll basic features also pyroll-linear-thermal as well as pyroll-lippmann-mahrenholz-force-torque.
This has been done to incorporate tensions better into pyroll basic as well as a difference between cold and hot profiles

Since many people use anaconda before starting to think, they need a little guidance to install PyRolL with Anaconda.

We should add a section or extend an existing one to better explain how the units PyRolL uses work and how they represent a real rolling mill. The question "How do i get from a rolling mill to our units?" should be answered.

This might be best done graphically - for example by showing a sideview of a rolling mill and mark all units and PyRolL specific subparts in it.

A similar graphic can already be found here.

This graphic could also be added to the explanations on the startup page, as understanding this concept is very useful when one wants to work with PyRolL.

The documentation should be rewritten.
As of right now the documentation is very much focused on programmers or better people with a programming background.
My opinion, the documentation should feature several open access papers witch are recalculated.
For example several examples published by C. Overhagen in his PhD or some from "Der Kalibreur".
Also a dedicated section for the IMF's own continuous rolling mill, this would help partners from IMF as well as students especially.

Furhermore I would suggest sections like:

Introduction to PyRolL (For Programmers)
Introduction to PyRolL (For Technologists)

The current guide works, though may not be accurate or in-depth enough.
Having pictures or even a video for all subsequent steps, even after the installation of Python (as currently), may be more understandable.

Additionally @mxstrl is currently testing this out himself and with some students so he will be able to give a better overview what steps are needed or which can cause troubles during installation.

Also it might be good to, from our side, define a optimal working environment, define how PyRolL is best used and also go through its setup during this guide.
May include:

• installation of an IDE (Pycharm)
• setup of virtual environments (hatch)
• introduction to an optimal workflow (define .venv via tomls, initialize venv, use PyRolL in venv)

If we define such a fixed workflow we could also provide templates for it (hatch.toml, pyproject.toml, jupyter-notebook with basic setup).

Everyone more experienced with Python and its usage will know where he can do something differently to our example.

The results from a pyroll-Run contain a large number of entries.

The meaning of most is obvious and selfexplanatory.

But for some like
draught, velociy, roll_max/min_radius/working_radius, roll_neutral geometry etc.
it would help if same additional descrption or sketch would be provided in the docmentation

References the

.. autoclass:: Profile
    :members:

objects used in almost all files of the documentation. While their content is useful and should still be findable somewhere, the long lists this produces add unnecessary visual clutter.
In some cases like here, there is also additional content after these blocks. This content may not be found by users of the documentation as they may not expect more things to come after the autoclass blocks.

Ideas to fix this:

• hide these Blocks in fold-outs
• also limit the height of these fold outs in height and add an additional scroll bar to them to not unnecessaryly lengthen the documentations pages.

The information currently presented on the startup page is all correct and useful but might overwhelm people that are trying to get into PyRolL. Also the description of how to install PyRolL should be further up.

The startup page should rather have the following order:

1. what can you do with PyRolL
   • maybe in the form of a short GiF or Video
   • additionally a button to try it out (link to the examples on binder)
2. How to install PyRolL
   • button with a link or a fold-out of that page
3. Getting started with PyRolL
   • button with a link or a fold-out of that page
4. ... (here the further explanations like currently can be given)

Further ideas and suggestions regarding the startuppage may be collected here.

PS: @mxstrl Is this equivalent to the order you wrote down or imagined?

At the bottom of the page https://pyroll.readthedocs.io/en/latest/examples/pyroll-examples/Basic_Usage_Of_PyRolL.html, the command sequence.out_profile.temperature > sequence2.out_profile.temperature gives the following error for me:

╭─────────────────────────────── Traceback (most recent call last) ────────────────────────────────╮
│ in <module>:1                                                                                    │
│                                                                                                  │
│ ❱ 1 sequence.out_profile.temperature > sequence2.out_profile.temperature                         │
│   2                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
AttributeError: 'NoneType' object has no attribute 'temperature'

Everything in this tutorial up to this point works as expected, but something is not correct when accessing in_profile and out_profile from a sequence object.

By the way, this is a very nice, intuitive tutorial!
Thanks.

Note: This is related to the review at openjournals/joss-reviews#6200