Kelley's Notes on the Docs Example Page

[H0R5E]

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]

@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).

[ryancoe]

@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).

@ssolson and I discussed this... we didn't like that Live Scripts are binary files... however, it is nice that they can be compiled to HTML

[ryancoe]

@ssolson - I've made some progress on this, but I could use your help. Here's what I would consider priority level items for the v0 release:

• 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.
• label the "gray evaluation block" in the figure
• "geometric design variables, a^2" but figure states "r1, r2, d1, d2"
• explain that the tool is for parametrically altering designs (not changing them into something completely new)
• expand description of design variables
• expand explanation of results and plot (and maybe add more labels to plot?)
• related to previous, show the power produced by a design using x0

[ryancoe]

addressed first three items above w/ acf3a7f, a7e2f02, 69b7896

[ryancoe]

explain that the tool is for parametrically altering designs (not changing them into something completely new) - this is just the definition of optimization... not sure I can really expand

[ryancoe]

design variable explanation: f14b711
results explanation: edbd4b6

[ryancoe]

related to previous, show the power produced by a design using x0 - don't really know how to do this at the moment and I don't think its critical