shaunfell / grboondi Goto Github PK

Here are suggestions to improve the documentation:

• One of the selling features for GRBoondi is that only a handful of files are required to simulate new interesting Proca scenarios. However, how to set these new cases up is not explained. Maybe you could add a tutorial on how to add a new case? This is different from an example because it guides the user in the process and highlights the various components (e.g., how does one fill the params folder? What is the role of GNUmakefile?), as opposed to just having all the files in one place
• See comment in openjournals/joss-reviews#6888 (comment)
• Not related to documentation, but why is csh required? It is a little odd requirement
• I think it would be useful to document the typical computational requirements for a simulation. E.g., how much RAM, disk, CPUs for a reasonable simulation
• Documentation on parameters is a little overwhelming. If some parameters are more important than others, I'd suggest highlighting those to increase the signal-to-noise ratio
• The Home page of the documentation does not take me to the next step. It should be clear where to click next.
• There are no contributor guidelines, e.g., code style, contribution workflow, testing requirements
• There is no documentation on how to run tests
• There are not many backlinks to GRChombo and Chombo.
• If GRBoondi is not supposed to be used as a black box, how are user supposed to learn how the internals work? There is no documentation about this

Here are some issues I see with the tools in PostProcessing:

• There is no installation instruction
• Dependencies are not declared anywhere, and some of the dependencies are not trivial (e.g., numpy, pandas, matplotlib)
• There are no tests
• It's unclear what versions of python are supported/required
• It's unclear what versions of visit are supported/required
• There is not much error handling (e.g., what if some output files already exist?, or what is len(argv) < 1?)
• Scripts seem hard to understand/extend. There is not much explanation of what is happening, or what is the relationship between python and ini files.
• Comments like the ones in lines

  GRBoondi/PostProcessing/IntegralsPlot.py

  Lines 156 to 160 in efa29d2

  	#setup the plot style
  	setup_plots()
  	#make the plots
  	make_plots(data_obj, plot_variables, xlims, linestyles)

  are not useful
• Some tabs are 8 spaces, other 4
• SystemError is typically used for problems like "disk full", or "file not found"

I'll add some comments here, overall it looks great, but I can make some stylistic suggestions.