The WEC Design Optimization MATLAB Toolbox (WecOptTool) allows users to perform wave energy converter (WEC) device design optimization studies with constrained optimal control.
Dependency | Website | Required* |
---|---|---|
MATLAB | https://www.mathworks.com/products/matlab.html | yes1 |
MATLAB Optimization Toolbox | https://www.mathworks.com/products/optimization.html | yes |
NEMOH | https://github.com/LHEEA/Nemoh | yes |
WAFO | https://github.com/wafo-project/wafo | optional |
MATLAB Parallel Computing Toolbox | https://www.mathworks.com/products/parallel-computing.html | optional |
MATLAB Global Optimization Toolbox | https://www.mathworks.com/products/global-optimization.html | optional |
* The values in the Required column have the following meanings:
1 The WecOptTool developers are endeavoring to ensure that this software is compatible with the latest version of MATLAB (and the toolbox dependencies). Unfortunately, this may mean that backwards compatibility with older versions of MATLAB is not possible. See the MATLAB Version Support Policy page for further details.
The latest stable version of WecOptTool can be downloaded from the Releases section of this repository.
For the latest development version of WecOptTool, clone or download this repository, using the Clone or download button.
Note that, although the developers endeavor to ensure that the development version is not broken, bugs or unexpected behavior may occur, so please beware.
:warning: Unexpected behavior may occur if multiple versions of the toolbox are installed. Please following the Uninstall instructions to uninstall any previous versions of WecOptTool first.
Download the WecOptTool software: See the Download
section. If required, unzip the archive to a path of your choosing (i.e.
/path/to/WecOptTool
).
Add WecOptTool to your MATLAB path: Add the WecOptTool toolbox to your MATLAB path using the MATLAB command prompt:
>> addpath(genpath('/path/to/WecOptTool/toolbox'));
>> savepath;
Alternatively the “Set Path” graphical tool can be used to add the toolbox.
Set up Nemoh:
a. Windows: Executables are provided in the Release
directory of
the NEMOH source code. These are installed into WecOptTool using the
installNemoh.m
MATLAB script, run from the WecOptTool root directory,
using the MATLAB command window as follows:
>> cd /path/to/WecOptTool
>> installNemoh('/path/to/NEMOH/Release');
b. Linux: To set up NEMOH for linux, first, use a command window to compile the executables (you will need gfortran or the intel fortran compiler):
$ cd /path/to/NEMOH
$ make
Executables will be created a new directory called 'bin', which must
then be installed into WecOptTool using the installNemoh.m
MATLAB
script, run in the MATLAB command window from the WecOptTool
root directory:
>> cd /path/to/WecOptTool
>> installNemoh('/path/to/NEMOH/bin');
Verify dependencies installation: You can verify that the dependencies
have been installed correctly by running the dependencyCheck.m
script
provided in the root directory of the WecOptTool source code. The script is
called in MATLAB as follows:
>> cd /path/to/WecOptTool
>> dependencyCheck
and successful output may look like this:
WecOptTool Dependency Checker
-------------------------------
Required
--------
Optimization Toolbox: Found
NEMOH: Found
Optional
--------
Parallel Toolbox: Found
Global Optimization Toolbox: Not Installed
WAFO: Found
(optional) Run functionality tests: A test suite is available to verify that the code is operational. A script is provided in the root directory of the WecOptTool source code and is run from the MATLAB command window, as follows:
>> cd /path/to/WecOptTool
>> runTests;
There should be no Failed or Incomplete tests at the end of the run. For example:
Totals:
91 Passed, 0 Failed, 0 Incomplete.
195.0643 seconds testing time.
Begin use: See the
basic
or
optimization
examples for the RM3 device.
Uninstall a previous version of WecOptTool using the MATLAB command prompt:
>> rmpath(genpath('/path/to/WecOptTool/toolbox'));
Alternatively the "Set Path" graphical tool can be used to remove the toolbox.
The top level folders of the WecOptTool repository are used as follows:
The toolbox uses namespaces to subdivide it's functionality, as follows:
The code architecture for both the WecOptTool is subject to change as the code approaches maturity.
The documentation is published at snl-waterpower.github.io/WecOptTool. The documentation source code
is found in the docs
folder and HTML is compiled using the Sphinx documentation generator.
These instructions work for both Linux and Windows. For Windows, remember to
replace slashes (/
) in paths with backslashes (\
).
Install Anaconda Python.
Create the Sphinx environment:
> conda create -c conda-forge -n _sphinx click colorama colorclass future pip "sphinx=1.8.5" sphinxcontrib-bibtex sphinx_rtd_theme
> activate _sphinx
(_sphinx) > pip install sphinxcontrib-matlabdomain
(_sphinx) > pip install git+git://github.com/SuperKogito/sphinxcontrib-pdfembed
(_sphinx) > pip install https://github.com/H0R5E/sphinxcontrib-versioning/archive/v1.8.5_support.zip
(_sphinx) > conda deactivate
>
The documentation for the current branch can be built locally for inspection
prior to publishing. They are built in the docs/_build
directory. Note,
unlike the final documentation, version tags and other branches will not be
available.
To test the current branch, use the following:
> activate _sphinx
(_sphinx) > cd path/to/WecOptTool
(_sphinx) > sphinx-build -b html docs docs/_build/html
(_sphinx) > conda deactivate
>
The final documentation can be built locally for inspection prior to
publishing. They are built in the docs/_build
directory. Note, docs are built
from the remote, so only pushed changes will be shown.
To build the docs as they would be published, use the following:
> activate _sphinx
(_sphinx) > cd path/to/WecOptTool
(_sphinx) > sphinx-versioning build -abt docs docs/_build/html
(_sphinx) > conda deactivate
>
To build the docs with a current feature branch as the default docs use:
> activate _sphinx
(_sphinx) > cd path/to/WecOptTool
(_sphinx) > sphinx-versioning build -ab r <feature-branch> docs docs/_build/html
(_sphinx) > conda deactivate
>
The front page of the docs can be accessed at
WecOptTool/docs/_build/html/index.html
.
The WecOptTool docs are rebuilt automatically following every merge commit made to the master branch of the SNL-WaterPower/WecOptTool repository. They can also be published manually, as follows:
> activate _sphinx
(_sphinx) > cd path/to/WecOptTool
(_sphinx) > sphinx-versioning push -abt -e .nojekyll -e README.md -P <REMOTE> docs <BRANCH> .
(_sphinx) > conda deactivate
>
\<REMOTE> refers to the git remote which will be pushed to and \<BRANCH> refers to the target branch on the remote. Note, this command will add a new commit to the remote, so use with care.
Docstring formatting should be Google style for auto documentation with sphinx.ext.napoleon. See the docstrings in the WecOptTool package for examples.
Please see the Public Road Map to see the current development priorities.
Contributions to the toolbox are welcome. The project follows a trunk based
development paradigm and updates to the
code should be made through pull requests.
Contributions should be submitted against the master
branch.
When submitting to the MATLAB source code please run the test suite first:
>> cd /path/to/WecOptTool
>> runTests;
When the test suite has finished please add the generated test_results.pdf
file, showing that all tests have passed, to the pull request description.
For contributions to the documentation, please please run a spell-check prior to submitting a pull request.
A code maintainer will review your pull request at the earliest possible opportunity. For large pull requests, it would be advisable to open a related issue to discuss the purpose of your updates. The developers also would be grateful if "Allow edits from maintainers" is checked when making a pull request, as this will allow us to finalize your contributions more rapidly.
Copyright 2020 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software.
WecOptTool is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
WecOptTool is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with WecOptTool. If not, see https://www.gnu.org/licenses/.