Documentation updates for FY21 Q4 (WEC-Sim#707)

* miscellaneous cleanup

* update run from sim documentation and terminology formatting

* update responseClass API

* fix nonlinear capitalization

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,6 +1,6 @@
 ---
 name: Bug report
-about: Create a report to help us asses and resolve a potential bug
+about: Create a report to help us assess and resolve a potential bug
 title: "[BUG]"
 labels: bug
 assignees: ''
@@ -14,6 +14,7 @@ _A clear and concise description of what the perceived bug is._
 
 **WEC-Sim file(s)**
 _If known, please identify the the WEC-Sim files causing the bug or error:_
+_Please upload relevant case files if possible to speed debugging._
 
 **To Reproduce**
 _Steps to reproduce the behavior:_
@@ -22,6 +23,8 @@ _Steps to reproduce the behavior:_
 3. _Scroll down to '....'_
 4. _See error_
 
+_State method of running WEC-Sim (command line, from simulink with input file, from simulink with custom parameters)_
+
 **Expected behavior**
 _A clear and concise description of what you expected to happen._
 

.github/ISSUE_TEMPLATE/developer-issue.md

@@ -1,7 +1,7 @@
 ---
 name: Developer Issue
 about: For the use of the development team to note issues associated with the development
-  of WEC-Sim
+  of WEC-Sim. Users please use an alternate template.
 title: "[Developer Issue]"
 labels: ''
 assignees: ''

docs/_include/terminology.rst

@@ -70,7 +70,7 @@ JS                 		JONSWAP Spectrum
 :math:`\omega` 			Wave frequency (rad/s), :math:`\omega = \frac{2\pi}{T}`
 :math:`\phi` 			Wave phase (rad)
 :math:`\sigma`			Wave spectrum coefficient (JONSWAP)
-:math:`\gamma`			Wave spectrum non-dimensional peak shape parameter
+:math:`\gamma`			Wave spectrum nondimensional peak shape parameter
 Pitch (Ry)         		Rotation about the Y-axis
 PM                 		Pierson-Moskowitz Specturm
 :math:`P_{PTO}`			Power from the PTO

docs/_include/viz.rst

@@ -4,7 +4,7 @@ This section describes how to use ParaView for visualizing data from a WEC-Sim s
 Using ParaView visualization improves on the SimMechanics explorer by:
 
 * Visualizing the wave field
-* Visualizing the cell-by-cell non-linear hydrodynamic forces (when using nonlinear buoyancy and Froude-Krylov wave excitation)
+* Visualizing the cell-by-cell nonlinear hydrodynamic forces (when using nonlinear buoyancy and Froude-Krylov wave excitation)
 * Allowing data manipulation and additional visualization options
 
 However, the SimMechanics explorer shows the following information not included in the ParaView visualization:
@@ -50,9 +50,9 @@ The following table lists the WEC-Sim simulation parameters that can be specifie
 +---------------------------+-----------------------------------------------------------+
 | ``simu.pathParaviewVideo``| directory to create ParaView visualization files          |
 +---------------------------+-----------------------------------------------------------+
-| | ``simu.nlHydro``        | | 0 for no non-linear hydro [default]                     |
-|                           | | 1 for non-linear hydro with mean free surface           |
-|                           | | 2 for non-linear hydro with instantaneous free surface  |
+| | ``simu.nlHydro``        | | 0 for no nonlinear hydro [default]                      |
+|                           | | 1 for nonlinear hydro with mean free surface            |
+|                           | | 2 for nonlinear hydro with instantaneous free surface   |
 +---------------------------+-----------------------------------------------------------+
 | ``simu.domainSize``       | size of ground and water planes in meters [default 200]   |
 +---------------------------+-----------------------------------------------------------+
@@ -106,44 +106,44 @@ An example using Paraview for visualization of WEC-Sim data is provided in the `
 The **RM3_MoorDyn_Viz** example uses ParaView for WEC-Sim data visualization of a WEC-Sim model coupled with [MoorDyn](http://wec-sim.github.io/WEC-Sim/advanced_features.html#moordyn) to simulate a mooring system for the [RM3](http://wec-sim.github.io/WEC-Sim/tutorials.html#two-body-point-absorber-rm3) geometry. 
 
 
-Non-Linear Hydro Visualization in ParaView
+Nonlinear Hydro Visualization in ParaView
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When using non-linear buoyancy and Froude-Krylov Wave Excitation the paraview files also contain cell data for the bodies.
+When using nonlinear buoyancy and Froude-Krylov wave excitation the paraview files also contain cell data for the bodies.
 The cell data are:
 
 * Cell areas
 * Hydrostatic pressures
 * Linear Froude-Krylov pressures
-* Non-linear Froude-Krylov pressures
+* Nonlinear Froude-Krylov pressures
 
 The ``pressureGlyphs`` macro calculates cell normals, and cell centers. It then creates the following glyphs:
 
-* Hydrostatic Pressure
+* Hydrostatic pressure
 * Linear Froude-Krylov pressure
-* Non-linear Froude-Krylov pressure
-* Total pressure (hydrostatic plus non-linear Froude-Krylov)
-* Froude-Krylov delta (non-linear minus linear)
+* Nonlinear Froude-Krylov pressure
+* Total pressure (hydrostatic plus nonlinear Froude-Krylov)
+* Froude-Krylov delta (nonlinear minus linear)
 
-To view WEC-Sim non-linear hydro data in ParaView:
+To view WEC-Sim nonlinear hydro data in ParaView:
 
 * Open the ``$CASE/vtk/<filename>.pvd`` file in ParaView
 * Select the WEC-Sim model in the pipeline, and run the ``WEC-Sim`` macro
 * Move the camera to desired view
-* Select the non-linear hydro body in the pipeline, and run the ``pressureGlyphs`` macro
+* Select the nonlinear hydro body in the pipeline, and run the ``pressureGlyphs`` macro
 * Select which features to visualize in the pipeline
 * Click the green arrow (play) button
 
 The video below shows three different views of the RM3 model described in the tutorials.
-The top right shows glyphs of the non-linear Froude-Krylov pressure acting on the float. 
+The top right shows glyphs of the nonlinear Froude-Krylov pressure acting on the float. 
 The bottom right shows the float colored by hydrostatic pressure.
 
  .. raw:: html
 
 	<iframe width="420" height="315" src="https://www.youtube.com/embed/VIPXsS8h9pg" frameborder="0" allowfullscreen></iframe>
 
 
-An example using Paraview for visualization of non-linear hydro WEC-Sim data is provided in the ``Paraview_Visualization`` directory on the `WEC-Sim Applications <https://github.com/WEC-Sim/WEC-Sim_Applications>`_ repository.
-The **OSWEC_NonLinear_Viz** example uses ParaView for WEC-Sim data visualization of a WEC-Sim model with [Non-linear Hydro](http://wec-sim.github.io/WEC-Sim/advanced_features.html#nonlinear-buoyancy-and-froude-krylov-excitation) to simulate non-linear wave excitation on the flap of the [OSWEC](http://wec-sim.github.io/WEC-Sim/tutorials.html#oscillating-surge-wec-oswec) geometry. 
+An example using Paraview for visualization of nonlinear hydro WEC-Sim data is provided in the ``Paraview_Visualization`` directory on the `WEC-Sim Applications <https://github.com/WEC-Sim/WEC-Sim_Applications>`_ repository.
+The **OSWEC_NonLinear_Viz** example uses ParaView for WEC-Sim data visualization of a WEC-Sim model with [nonlinear Hydro](http://wec-sim.github.io/WEC-Sim/advanced_features.html#nonlinear-buoyancy-and-froude-krylov-excitation) to simulate nonlinear wave excitation on the flap of the [OSWEC](http://wec-sim.github.io/WEC-Sim/tutorials.html#oscillating-surge-wec-oswec) geometry. 
 
 Loading a ParaView State File
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -154,4 +154,4 @@ If a previous `*.pvsm`` ParaView state file was saved, the state can be applied
 * Select the desired ``$CASE/<filename>.pvsm`` Paraview state file to apply
 * Select the "Search files under specified directory" option, specify the desired WECS-Sim ``$CASE/vtk/`` directory, and click ``OK``
 
-Paraview state files are provided for both **Paraview_Visualization** examples on the `WEC-Sim Applications <https://github.com/WEC-Sim/WEC-Sim_Applications>`_ repository, one for the RM3 using MoorDyn, and another for the OSWEC with non-linear hydro.
+Paraview state files are provided for both **Paraview_Visualization** examples on the `WEC-Sim Applications <https://github.com/WEC-Sim/WEC-Sim_Applications>`_ repository, one for the RM3 using MoorDyn, and another for the OSWEC with nonlinear hydro.

docs/introduction/release_notes.rst

@@ -181,7 +181,7 @@ Previous Releases
 `WEC-Sim v2.2 <https://github.com/WEC-Sim/WEC-Sim/releases/tag/v2.2>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* Added option to save pressure data for non-linear hydro (`simu.pressureDis`)
+* Added option to save pressure data for nonlinear hydro (`simu.pressureDis`)
 
 * Update to moorDyn parser (doesn't require line#.out)  
 
@@ -252,7 +252,7 @@ Previous Releases
 * State space radiation
 * Wave directionality
 * User-defined wave elevation time-series
-* Imports non-dimensionalized BEMIO hydrodynamic data (instead of fully dimensional coefficients)
+* Imports nondimensionalized BEMIO hydrodynamic data (instead of fully dimensional coefficients)
 * Variant Subsystems implemented to improve code stability (instead of if statements)
 * Bug fixes
 

docs/theory/theory.rst

@@ -63,7 +63,7 @@ for the velocity potential, which assumes the flow is inviscid, incompressible,
 and irrotational. More details on the theory for the frequency-domain BEM can 
 be found in :cite:`Lee2006`. 
 
-WEC-Sim imports non-dimensionalized hydrodynamic coefficients from an ``*.h5`` 
+WEC-Sim imports nondimensionalized hydrodynamic coefficients from an ``*.h5`` 
 data structure generated by :ref:`user-advanced-features-bemio` for the BEM solvers: WAMIT, 
 AQWA, NEMOH or CAPYTAINE. Alternatively, the ``*.h5`` data structure can be 
 manually defined by the user. The WEC-Sim code scales the hydrodynamic 
@@ -477,7 +477,7 @@ spectrum :cite:`IEC-2` is defined by:
 
     S_{JS}\left( f \right) = C_{ws} \left(\gamma\right) S_{PM} \gamma^{\alpha}
 
-where :math:`\gamma` is the non-dimensional peak-shape parameter.
+where :math:`\gamma` is the nondimensional peak-shape parameter.
 
 The normalizing factor, :math:`C_{ws}\left(\gamma\right)`, is defined as: 
 

docs/user/advanced_features.rst

@@ -37,6 +37,76 @@ This section provides an overview of WEC-Sim's simulation class features; for
 more information about the simulation class code structure, refer to 
 :ref:`user-code-structure-simulation-class`. 
 
+Running WEC-Sim
+^^^^^^^^^^^^^^^
+
+The subsection describes the various ways to run WEC-Sim. The standard method is 
+to type the command ``wecSim`` in the MATLAB command window when in a ``$CASE`` 
+directory. This is the same method described in the :ref:`user-workflow` and 
+:ref:`user-tutorials` sections.
+
+
+.. _user-advanced-features-fcn:
+
+Running as Function 
+"""""""""""""""""""
+
+WEC-Sim allows users to execute WEC-Sim as a function by using ``wecSimFcn``. 
+This option may be useful for users who wish to devise their own batch runs, 
+isolate the WEC-Sim workspace, create a special set-up before running WEC-Sim, 
+or link to another software.
+
+
+.. _user-advanced-features-simulink:
+
+Running from Simulink
+"""""""""""""""""""""
+
+Beginning in version 4.3, WEC-Sim can also be run from Simulink. The Run From 
+Simulink advanced feature allows users to initialize WEC-Sim from the command 
+window and then begin the simulation from Simulink. This allows greater 
+compatibility with other models or hardware-in-the-loop simulations that must 
+start in Simulink. The WEC-Sim library contains mask options that allow users to 
+either:
+
+   1. Define an standard input file to use in WEC-Sim or 
+   2. Define custom parameters inside the block masks.
+
+The Global Reference Frame mask controls whether an input file or custom 
+parameters are used for WEC-Sim. Note that when the Custom Parameters options is 
+selected, WEC-Sim will only use those variable in the block masks. Certain options 
+become visible when the correct flag is set. For example, ``body.morisonElement.cd`` 
+will not be visible unless ``body.morisonElement.on > 0``. This method of running 
+WEC-Sim may help some users visualize the interplay between the blocks and classes.
+For more information on how the blocks and classes are related, see the 
+:ref:`user-code-structure` section.
+
+To run WEC-Sim from Simulink, open the Simulink ``.slx`` file and choose whether to 
+use an input file or custom parameters in the Global Reference Frame. Next type 
+``initializeWecSim`` in the MATLAB Command Window. Lastly, run the model from the 
+Simulink interface:
+
+* Run from Simulink with a wecSimInputFile.m
+	* Set the Global Reference Frame to use an input file
+	* Choose the correct input file
+	* Type ``initializeWecSim`` in the Command Window
+	* Run the model from Simulink
+* Run from Simulink with custom parameters
+	* Set the Global  Reference Frame to use custom parameters
+	* (Optional) prefill parameters by loading an input file.
+	* Edit custom parameters as desired
+	* Type ``initializeWecSim`` in the Command Window
+	* Run the model from Simulink
+
+.. Note::
+    After running WEC-Sim from Simulink with custom parameters, a 
+    ``wecSimInputFile_simulinkCustomParameters.m`` file is written to the ``$CASE`` 
+    directory. This file specifies all non-default WEC-Sim parameters used for the 
+    WEC-Sim simulation. This file serves as a record of how the case was run for 
+    future reference. It may be used in the same manner as other input files when 
+    renamed to ``wecSimInputFile.m``
+
+
 .. _user-advanced-features-mcr:
 
 Multiple Condition Runs (MCR)
@@ -104,44 +174,6 @@ setting for ``simu.reloadH5Data`` in the WEC-Sim input file.
     Please use ``userDefinedFunctions.m`` instead.
 
 
-.. _user-advanced-features-fcn:
-
-Running as Function 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-WEC-Sim allows users to execute WEC-Sim as a function by using ``wecSimFcn``.
-
-
-
-.. _user-advanced-features-simulink:
-
-Running from Simulink
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Beginning in version 4.3, WEC-Sim can also be run from Simulink. 
-The WEC-Sim library now allows for an input file or custom parameters to be used inside the block masks.
-This mode is useful when using WEC-Sim in conjunction with hardware-in-the-loop or other Simulink models with their own initialization.
-To run WEC-Sim from Simulink, open the Simulink ``.slx`` file and choose whether to use an input file or custom parameters in the Global Reference Frame.
-Next type ``initializeWecSim`` in the MATLAB Command Window. 
-Lastly, run the model from the Simulink interface.
-
-* Run from Simulink with a wecSimInputFile.m
-	* Set the Global Reference Frame to use an input file
-	* Choose the correct input file
-	* Type ``initializeWecSim`` in the Command Window
-	* Run the model from Simulink
-* Run from Simulink with custom parameters
-	* Set the Global  Reference Frame to use custom parameters
-	* (Optional) prefill parameters by loading an input file.
-	* Edit custom parameters as desired
-	* Type ``initializeWecSim`` in the Command Window
-	* Run the model from Simulink
-
-Upon completion of a WEC-Sim simulation run from Simulink a ``wecSimInputFile_simulinkCustomParameters.m`` file is written to the ``$CASE`` directory including the WEC-Sim parameters used for the WEC-Sim simulation.
-
-Refer to :ref:`user-tutorials-examples` for more details on how to run the examples 
-
-
 State-Space Representation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/user/applications.rst

@@ -90,7 +90,7 @@ Nonlinear Hydrodynamic Body
 
 Example using :ref:`Nonlinear Hydro <user-advanced-features-nonlinear>`
 to run WEC-Sim for a :ref:`heaving ellipsoid <user-advanced-features-nonlinear-tutorial-heaving-ellipsoid>`.
-Includes examples of running non-linear hydrodynamics with different :ref:`fixed and
+Includes examples of running nonlinear hydrodynamics with different :ref:`fixed and
 variable time-step solvers <user-advanced-features-time-step>`
 (ode4/ode45), and different regular wave formulations (with/without CIC). 
 Execute the `runNL.m` script to run this case. 

docs/user/code_structure.rst

@@ -31,7 +31,7 @@ WEC-Sim Simulink Library    ``WECSim_Lib.slx``    ``$WECSIM/source/lib``
 
 The WEC-Sim executable is the ``wecSim.m`` file.
 Executing ``wecSim`` from a case directory parses the user input data, 
-performs preprocessing calculations in each of the classes, selects and 
+performs pre-processing calculations in each of the classes, selects and 
 initializes variant subsystems in the Simulink model, runs the time-domain 
 simulations in WEC-Sim, and calls post-processing scripts. 
 When a WEC-Sim case is properly set-up, the user only needs to use the single command ``wecSim`` 

docs/user/troubleshooting.rst

@@ -156,9 +156,9 @@ If a CIC wave continues to oscillate without decaying to a steady state, the con
 Increase ``simu.CITime`` to a greater value or use the state space option (``simu.ssCalc=1``).
 In BEMIO, check that the convolution integral time is long enough for all oscillations to decay. 
 
-**Non-linear Hydrodynamics:**
-If a user wishes to use the non-linear hydro options, they should first follow this same workflow with ``simu.nlHydro=0`` and again with ``simu.nlHydro=1,2``
-The non-linear hydro options are difficult to set-up and must be used with care. 
+**Nonlinear Hydrodynamics:**
+If a user wishes to use the nonlinear hydro options, they should first follow this same workflow with ``simu.nlHydro=0`` and again with ``simu.nlHydro=1,2``
+The nonlinear hydro options are difficult to set-up and must be used with care. 
 A highly refined mesh is required to get an accurate displaced volume and wetted surface area at each time step.
 
 

docs/user/workflow.rst

@@ -249,21 +249,17 @@ geometry file(s) ``*.stl``, and the hydrodynamic data file (``*.h5``) .
 Step 5: Run WEC-Sim
 ^^^^^^^^^^^^^^^^^^^
 
-Lastly, WEC-Sim can be executed from the ``$CASE`` directory using the following methods:
+Lastly, WEC-Sim can be executed from the ``$CASE`` directory using the following method:
 
-
-* Run from MATLAB Command Window (for RM3 and OSWEC examples)
 	* Type ``wecSim`` in the Command Window
-* Run from Simulink (for RM3FromSimulink example)
-	* Open the relevant WEC-Sim Simulink file
-	* Type ``initializeWecSim`` in the Command Window
-	* Hit Play in Simulink model to run 
 
-Refer to :ref:`user-tutorials-examples` for more details on how to run the examples. To customize or develop a new WEC-Sim model that runs from Simlunk (e.g. for Hardware-in-the-Loop, HIL, applications) refer to :ref:`user-advanced-features-simulink` for more information.
+Refer to :ref:`user-tutorials-examples` for more details on how to run the examples. 
 
-Users may also use ``wecSimMCR``, ``wecSimPCT``, ``wecSimFcn`` and  as described in the advanced features 
-sections :ref:`user-advanced-features-mcr`, :ref:`user-advanced-features-pct`, and :ref:`user-advanced-features-fcn`. 
-These options are only available in through the MATLAB Command Window.
+Users may also run WEC-Sim from Simulink, or use the commands ``wecSimMCR``, 
+``wecSimPCT``, and ``wecSimFcn`` as described in the advanced features 
+sections :ref:`user-advanced-features-simulink`, 
+:ref:`user-advanced-features-mcr`, :ref:`user-advanced-features-pct`, 
+and :ref:`user-advanced-features-fcn`. 
 
 .. Note:: The WEC-Sim source code is located in the ``$WECSIM`` directory, but 
 	WEC-Sim must be executed from the ``$CASE`` directory. 

examples/OSWEC/wecSimInputFile.m

@@ -2,10 +2,10 @@
 simu = simulationClass();               % Initialize Simulation Class
 simu.simMechanicsFile = 'OSWEC.slx';    % Specify Simulink Model File
 simu.mode = 'normal';                   % Specify Simulation Mode ('normal','accelerator','rapid-accelerator')
-simu.explorer='on';                     % Turn SimMechanics Explorer (on/off)
+simu.explorer = 'on';                   % Turn SimMechanics Explorer (on/off)
 simu.startTime = 0;                     % Simulation Start Time [s]
 simu.rampTime = 100;                    % Wave Ramp Time [s]
-simu.endTime=400;                       % Simulation End Time [s]        
+simu.endTime = 400;                     % Simulation End Time [s]        
 simu.solver = 'ode4';                   % simu.solver = 'ode4' for fixed step & simu.solver = 'ode45' for variable step 
 simu.dt = 0.1;                          % Simulation Time-Step [s]
 simu.CITime = 30;                       % Specify CI Time [s]