search

oemof / tespy

Thermal Engineering Systems in Python (TESPy). This package provides a powerful simulation toolkit for thermodynamic modeling of thermal engineering plants such as power plants, heat pumps or refrigeration machines.
https://tespy.readthedocs.io
MIT License
281 stars 88 forks source link

Comments on JOSS Manuscript #180

Closed Andrew-S-Rosen closed 4 years ago

Andrew-S-Rosen commented 4 years ago

This is not really the ideal place for me to put this, but I'd rather share my comments now than wait for the JOSS review to formally be opened. I will link to this Issue when the review opens.

With regards to the manuscript hosted under the pre-review, I have the following comments:

Very minor typographical comments that do not influence the quality of the submitted manuscript:

fwitte commented 4 years ago

Hi Andrew,

thank you very much for your suggestions. I implemented the changes in #181 and recompiled the paper (see https://github.com/openjournals/joss-reviews/issues/2178). I commented under your bullets. Please let me know, if there are any issues remaining. I will kepp #181 open until the review is completed.

Additionally, I added a short paragraph on hydraulic state/pressure equations as I had the impression this was missing.

Have a nice week Francesco

This is not really the ideal place for me to put this, but I'd rather share my comments now than wait for the JOSS review to formally be opened. I will link to this Issue when the review opens.

With regards to the manuscript hosted under the pre-review, I have the following comments:

  • It is obvious to most using this package what the variables mean, but I think it'd still be nice for them to be defined. One of the great things about making an open-source package like this is it makes it accessible to people who otherwise aren't experts in the field. For instance, a chemical engineer might initially interpret P to be pressure rather than power, which of course is inappropriate. Similarly, L, H, Vj, theta{log}, etc. should be defined (all variables, actually).

Good point, thank you. Due to the restriction of the length of the paper, I have added the definitions in line instead of using a table of symbols.

  • Since there will be people using this package from all backgrounds, could you explicitly define in the text the Q convention used? Just to prevent confusion.

Updated together with the changes above.

  • The equations are not numbered but still referenced with numbers. This should be adjusted.

Done.

  • You may wish to write the general expression for the open-system energy balance before Equation 3, then in the text it can be made clear which terms are neglected overall (e.g. differences in potential energy due to height) as well as which terms are neglected for specific process equipment highlighted in the text (e.g. adiabatic turbomachinery). This would make it easier for the reader and of course more general.

Good point, thank you.

  • I think it would be helpful in the manuscript to briefly describe the layout of the code, highlighting the modular nature. For instance, on the TESPy modules page, you describe the Networks, Components, component groups, Connections, and so on. It would be worth briefly highlighting the different modules that make up TESPy in the manuscript.

I tried to very briefly outline the main purpose of the different modules. Again, regarding the length of the paper, I wanted to keep it as short as possible.

  • Are there any other attempts at open-source alternatives to Aspen Plus in Python or other languages? If so, these should be referenced and distinguishing qualities of TESPy highlighted.

I know of/found one alternative (ThermoPower) which is not quite the same but similar. It is designed for dynamic modeling of steam power plants. I added a reference and briefly highlighted the benefits of TESPy vs. ThermoPower.

  • Several software packages are cited under the acknowledgments. SciPy now has a formal citation here, which you may consider adding.

Thank you for the hint, it was already in my paper.bib, I somehow oversaw this.

  • Please update the pandas citation to include the journal, as mentioned here.

For me it displays correctly (I did not apply changes to this entry in the updated article): grafik

  • Several other contributors are listed on the GitHub contributor list, although the contributions look to be somewhat minor. Per the JOSS review criteria, I feel obligated to ask you to confirm that no additional authors should be added to the current review.

Yes, we will stick with this.

Very minor typographical comments that do not influence the quality of the submitted manuscript:

  • Acknowledgements --> Acknowledgments

Done.

  • Please capitalize Python under the Motivation section

Done.

  • Please change E. g. to not have a space between the abbreviated letters

I never thought about that, thank you for the hint. The german for example is "zum Beispiel" and abbreviated explicitly with a space (z. B.). I also adjusted all appearances I found in the online documentation.

  • Please italicize fl in the second line of the second page to match the variable in the equations

Done.

  • I was expecting the Example Implementations section to be like a mini tutorial of how the code is working. Perhaps it would be better to rename the section something more like Previous Implementations.

That sounds good, thank you.

Andrew-S-Rosen commented 4 years ago

@fwitte -- These changes look great! I think this really helps improve the readability of the equations, particularly for those who may not deal with mass/energy balances as often but want to use your code. It's a nice writeup! I'll post remaining comments on the main JOSS page.