From e8beb58d35328e46f787ed038d38a7941a4c4b9b Mon Sep 17 00:00:00 2001 From: nikhar-abbas <40865984+nikhar-abbas@users.noreply.github.com> Date: Wed, 10 Feb 2021 15:26:58 -0700 Subject: [PATCH] Docs (#36) * Update for readthedocs, new version * Iterate version * Update README.md Co-authored-by: dzalkind <65573423+dzalkind@users.noreply.github.com> --- CMakeLists.txt | 2 +- README.md | 55 ++++++++++++-------------------------------------- 2 files changed, 14 insertions(+), 43 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 882972732..ea5694d04 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,5 @@ cmake_minimum_required(VERSION 3.6) -project(ROSCO VERSION 2.1.1 LANGUAGES Fortran) +project(ROSCO VERSION 2.2.0 LANGUAGES Fortran) set(CMAKE_Fortran_MODULE_DIRECTORY "${CMAKE_BINARY_DIR}/ftnmods") diff --git a/README.md b/README.md index d81c08cf1..7b1af13ab 100644 --- a/README.md +++ b/README.md @@ -2,47 +2,18 @@ NREL's Reference OpenSource Controller (ROSCO) for wind turbine applications uses the Bladed-style DISCON interface used by OpenFAST, Bladed (versions 4.5 or earlier), HAWC2, and more. ## Introduction -The NREL Reference OpenSource Controller (ROSCO) provides an open, modular and fully adaptable baseline wind turbine controller to the scientific community. Because of the open character and modular set-up, scientists are able to collaborate and contribute in making continuous improvements to the code. New control implementations can be added to the existing baseline controller, and in this way, convenient assessments of the proposed algorithms is possible. ROSCO is being developed in Fortran and uses the Bladed-style DISCON controller interface. The compiled controller is configured by a single control settings parameter file, and can work with any wind turbine model and simulation software using the DISCON interface. Baseline parameter files are supplied for the NREL 5-MW and DTU 10-MW reference wind turbines. +The NREL Reference OpenSource Controller (ROSCO) provides an open, modular and fully adaptable baseline wind turbine controller to the scientific community. Because of the open character and modular set-up, scientists are able to collaborate and contribute in making continuous improvements to the code. New control implementations can be added to the existing baseline controller, and in this way, convenient assessments of the proposed algorithms is possible. ROSCO is being developed in Fortran and uses the Bladed-style DISCON controller interface. The compiled controller is configured by a single control settings parameter file, and can work with any wind turbine model and simulation software using the DISCON interface. Baseline parameter files are supplied for the NREL 5-MW, DTU 10-MW, and IEA15MW reference wind turbines. -## Compiling ROSCO -For simple download of the most recent release, compiled binaries for Mac (.dylib), Linux (.so), and Windows (.dll) are provided with the [tagged releases](https://github.com/NREL/ROSCO/tags). +## Documentation +Relevant documentation about the ROSCO controller and corresponding ROSCO toolbox can all be found at https://rosco-toolbox.readthedocs.io/. -For the interested user, the same releases can be installed using [anaconda](https://www.anaconda.com/) using: -``` -conda install -c conda-forge rosco -``` -Please note that if you do install using anaconda, the binary will be installed with all other package libraries in the anaconda "active environment path", which can be found by typing `conda info`. - -If you wish to compile ROSCO directly, this is made simple using [cmake](https://cmake.org/) on Unix based machines. Windows users can leverage [mingw](http://www.mingw.org/) to compile similarly. - -### Required Software to build ROSCO -* Fortran compiler (GNU compiler version above 4.6.0 or Intel compiler version above 11) -* C/C++ compiler -* GNU Make (version 3.81 or later) -* CMake (version 2.8.12 or later) - for unix -* MinGW - for windows - -### Steps to compile -First, clone the git repository: -``` -git clone https://github.com/NREL/ROSCO.git -``` -Second, you will need to compile the controller. From the ROSCO home directory: -``` -mkdir build -cd build -cmake .. # Mac/Linux -cmake .. -G "MinGW Makefiles" # Windows -make install -``` -A dynamic link library will be compiled into the the `/ROSCO/install/lib` directory with the title `libdiscon.*`, where the file extension is `.so`, `.dll`, or `.dylib`, depending on the user's operating system. - -Note: when compiling with MinGW on Windows, modifying the cmake line in the above code to: `cmake .. -G "MinGW Makefiles" -DCMAKE_Fortran_COMPILER=gfortran` can solve compiler errors that may arrise, depending on your local configuration. +## Downloading/Compiling ROSCO +The easiest way to get the most recent version release of ROSCO is to download it from the [tagged releases](https://github.com/NREL/ROSCO/tags) page. If you wish to download ROSCO using [Anaconda](https://www.anaconda.com/) or compile ROSCO yourself, please follow the instruction [here](https://rosco-toolbox.readthedocs.io/en/latest/source/install.html#compiling-rosco). Compiling ROSCO will be necessary if you wish to use any version of ROSCO that is not a tagged release. ## Running ROSCO -A few files are needed to run ROSCO. Of course, the compiled binary, named `libdiscon.*` by default, is needed. This should be appropriately pointed to by your ServoDyn input file (for OpenFAST). In addition to the binary, a controller input file title DISCON.IN is necessary. Two example input files are provided for the NREL 5MW and DTU 10MW wind turbine controllers in the [parameter_files](parameter_files) folder. Note that DISCON.IN (or similar) is pointed to by the `DLL_InFile` parameter in ServoDyn. For generic controller tuning methods, and an automated writing of this DISCON.IN file, we point you to the complete [ROSCO_toolbox](https://github.com/nrel/rosco_toolbox). +A few files are needed to run ROSCO. Of course, the compiled binary, named `libdiscon.*` by default, is needed. This should be appropriately pointed to by your ServoDyn input file (for OpenFAST). In addition to the binary, a controller input file title DISCON.IN is necessary. Three example input files are provided for the NREL 5MW, DTU 10MW, and IEA 15MW wind turbine controllers in the [parameter_files](parameter_files) folder. Note that DISCON.IN (or similar) is pointed to by the `DLL_InFile` parameter in ServoDyn. For generic controller tuning methods, and an automated writing of this DISCON.IN file, we point you to the complete [ROSCO_toolbox](https://github.com/nrel/rosco_toolbox). -In addition to DISCON.IN, if you wish to use either of the wind speed estimators offered by ROSCO (`WE_mode > 0`), you will need a rotor performance input file. This is, again, provided for the NREL 5MW and DTU 10MW wind turbines, and can be easily made for other turbines using the [ROSCO_toolbox](https://github.com/nrel/rosco_toolbox). The input `PerfFileName` in DISCON.IN points to this file. +In addition to DISCON.IN, if you wish to use either of the wind speed estimators (`WE_Mode > 0`) or pitch saturation routines (`PS_Mode > 0`) offered by ROSCO , you will need a rotor performance input file. This is, again, provided for the sample wind turbines, and can be easily made for other turbines using the [ROSCO_toolbox](https://github.com/nrel/rosco_toolbox). The input `PerfFileName` in DISCON.IN points to this file. ## Using ROSCO for Bladed If you want to use the controller with DNV GL Bladed v4.5 or earlier (which still has support for the DISCON external controller interface), do the following: @@ -56,15 +27,15 @@ If you want to use the controller with DNV GL Bladed v4.5 or earlier (which stil If ROSCO played a role in your research, please cite it. This software can be cited as: - ROSCO. Version 1.0.0 (2020). Available at https://github.com/nrel/rosco. + ROSCO. Version 2.2.0 (2021). Available at https://github.com/nrel/rosco. For LaTeX users: ``` - @misc{ROSCO_2020, + @misc{ROSCO_2021, author = {NREL}, - title = {{ROSCO. Version 1.0.0}}, - year = {2020}, + title = {{ROSCO. Version 2.2.0}}, + year = {2021}, publisher = {GitHub}, journal = {GitHub repository}, url = {https://github.com/NREL/rosco} @@ -78,7 +49,7 @@ The initial release of this controller was the Delft Research Controller. This w * Mulders, S.P. and van Wingerden, J.W. "Delft Research Controller: an open-source and community-driven wind turbine baseline controller." Journal of Physics: Conference Series. Vol. 1037. No. 3. IOP Publishing, 2018. [Link to the paper](https://iopscience.iop.org/article/10.1088/1742-6596/1037/3/032009/meta) The Delft Research Controller was the initial version of this work. It has since been grown significantly and become NREL's ROSCO. -Primary contributions to ROSCO have been provided by researchers the National Renewable Energy Laboratory (Nikhar J. Abbas, Alan Wright, and Paul Fleming), Delft University of Technology (Sebastiaan Mulders and Jan-Willem van Wingerden), and the University of Colorado Boulder (Lucy Pao). Much of the intellect behind these contributions has been inspired or derived from an extensive amount of work in the literature. The bulk of this has been cited through the primary publications about this work. +Primary contributions to ROSCO have been provided by researchers the National Renewable Energy Laboratory (Nikhar J. Abbas, Daniel Zalkind, Alan Wright, and Paul Fleming), Delft University of Technology (Sebastiaan Mulders and Jan-Willem van Wingerden), and the University of Colorado Boulder (Lucy Pao). Much of the intellect behind these contributions has been inspired or derived from an extensive amount of work in the literature. The bulk of this has been cited through the primary publications about this work. There are also some specific acknowledgements we would like to communicate: -* The setpoint smoothing regime implemented through the ROSCO controller was contributed by sowento GmbH. \ No newline at end of file +* The setpoint smoothing regime implemented through the ROSCO controller was contributed by sowento GmbH.