Kelley's Notes on the Docs Example Page

H0R5E commented 4 years ago

Originally posted by @kmruehl in https://github.com/SNL-WaterPower/WecOptTool/issues/65#issuecomment-605360662

This is a list of improvements to the example section in the docs provided by @kmruehl.

Example

Update link about RM3 to this page: https://tethys-engineering.pnnl.gov/signature-projects/rm3-wave-point-absorber. The Sandia RMP page is being taken down.

"geometric design variables, a^2" but figure states "r1, r2, d1, d2"

label the "gray evaluation block" in the figure

label the inputs and outputs in this figure

I think there needs to be more of a theoretical explanation of what this toolbox does. The figure is helpful, but it does not provide enough description of the underlying theory behind this approach.

What are the inherent assumptions?

What are its applications and limitations? It seems to be dependent on linear potential flow theory (e.g. NEMOH), so I assume this means I shouldn't apply this tool for extreme events.

When would I want to use this? Once I already have a general shape and I want to tune its general dimensions?

I assume I cannot use this to change my geometry completely, right? I can't use it to compare a point absorber to a OSWC, etc. The underlying theory/assumptions/limitations should be explicitly stated.

What are the outputs of this tool? The figure doesn't show what I'm optimizing for, cost, power, peak/avg loads, power/weight etc.?

What are the inputs to this tool?

Am I assuming that the float is a cylinder and that the damping plat is a cylinder? Do they have to have a flat top/bottom? What about the central column, what is its dimension, can I change it?

How is the PTO system modeled? Is damping specified, if so where/how, etc?

Define Design Variables section needs more clarification. The lower bounds and upper bounds are mentioned without really being introduced. I think it's fairly intuitive, but I recommend making this as clear as possible. Consider adding a Variable definition section to your documentation.

Running the Example

Section 2.6. Run the study and view results, how dod I execute the example? Do I run the example.m file? it doesn't run if I type WecOptTool.run(study, options); into the command line. This is confusing. It appears that the code is executed by running the example.m file but this is not stated in the example documentation. It seems like this section is actually just explaining the different lines of the example.m file. That's useful, but needs to be stated.

There needs to be an explanation of what this case is, what its doing, what the inputs are, and what the outputs are.

I ran the example and got the following results, but do not know what this means or how to use this information. Elapsed time is 95.649494 seconds. Optimal solution is: r1: 5 [m] r2: 7.5 [m] d1: 1.125 [m] d2: 42 [m] Optimal function value is: 2202419.3209 [W] Generating plot...

I recommend focusing your efforts on this section, this is really the meat of the documentation right now. Explain what this example is, how to use it, what the I/Os are, and how to use the results

API Doc

This is great. Make sure to reference it in the rest of the documentation. For example, you should reference the API doc for WecOptTool.geom.Parametric when you're describing the geometry parameters. This will add clarity to the document.

kmruehl commented 4 years ago

@H0R5E @ryancoe just in case you didn't have enough to do already... I would also recommend making the example.m a MATLAB live example and incorporating it into your documentation on gh-pages. We did it for MHKiT-MATLAB here (we still have the same compile/indexing issue we have with the API doc, but it's there).