1. Installing the ROSCO tools#

As a reminder, the ROSCO toolbox is a python-based tool used to write the DISCON.IN file, which is read by the ROSCO controller (a compiled binary file). If you only wish to run the controller, you do not need to install the ROSCO toolbox.

Depending on what is needed, a user can choose to use just the ROSCO controller or to use both the ROSCO controller and the toolbox. Both the controller and the toolbox should be installed if one wishes to leverage the full ROSCO tool-chain. Table 1.1 provides an overview of the primary methods available for Installing the ROSCO controller. Additionally, Table 1.2 provides an overview of the primary methods available to acquire the ROSCO toolbox. Finally, if you wish to install and use both the controller and toolbox, the section about Full ROSCO Installation provides the best methods of doing so.

Table 1.1 Methods for Installing the ROSCO Controller#
Method	Use Case
Direct Download	Best for users who simply want to use a released version of the controller without working through the compilation procedures.
Anaconda Download - ROSCO	Best for users who just want to use the controller but prefer to download using the Anaconda package man age Full ROSCO Installation.
Full ROSCO Installation	Best for users who wish to both use the controller and leverage the tools in the ROSCO toolbox
Compile using CMake	Best for users who need to re-compile the source code often, plan to use non-released versions of ROSCO (including modified source code), or who simply want to compile the controller themselves so they have the full code available locally. This is necessary for users who wish to use the ZeroMQ Interface.

Table 1.2 Methods for Installing the ROSCO Toolbox#
Method	Use Case
Anaconda Download - ROSCO Toolbox	Best for users who simply want to use the primary ROSCO toolbox functions
Full ROSCO Installation	(Recommended) Best for users who wish to both use the primary ROSCO toolbox functions, as well run and use the many example and testing scripts available. This process can be done with or without compiling ROSCO.

For many of the methods used to install both ROSCO and the ROSCO toolbox, both Anaconda and CMake are necessary. Anaconda is a popular package manager used to distribute software packages of various types. Anaconda is used to download requisite packages and distribute pre-compiled versions of the ROSCO tools. CMake is a build configuration system that creates files as input to a build tool like GNU Make, Visual Studio, or Ninja. CMake does not compile code or run compilers directly, but rather creates the environment needed for another tool to run compilers and create binaries. CMake is used to ease the processes of compiling the ROSCO controller locally. For more information on CMake, please see understanding CMake in the OpenFAST documentation.

1.1. Installing the ROSCO controller#

The standard ROSCO controller is based in Fortran and must be compiled; the source code can be found at: https://github.com/NREL/ROSCO/ROSCO.

1.1.1. Direct Download#

The most recent tagged version releases of the controller are available for download. One can simply download these compiled binary files for their system and point to them in their simulation tools (e.g. through DLL_FileName in the ServoDyn input file of OpenFAST).

1.1.2. Anaconda Download - ROSCO#

Using the popular package manager, Anaconda, the tagged 64-bit versions of ROSCO are available through the conda-forge channel. In order to download the most recently compiled version release, from an anaconda powershell (Windows) or terminal (Mac/Linux) window, create a new anaconda virtual environment:

conda config --add channels conda-forge
conda create -y --name rosco-env python=3.9
conda activate rosco-env

navigate to your desired folder to save the compiled binary using:

cd <desired_folder>

and download the controller:

conda install -y ROSCO

This will download a compiled ROSCO binary file into the default filepath for any dynamic libraries downloaded via anaconda while in the ROSCO-env. The ROSCO binary file can be copied to your desired folder using:

cp $CONDA_PREFIX/lib/libdiscon.* <desired_folder>

on linux or:

copy %CONDA_PREFIX%/lib/libdiscon.* <desired_folder>

on Windows.

1.1.3. Compile using CMake#

CMake eases the compiling process significantly. We recommend that users use CMake if at all possible, as we cannot guarantee support for the use of other tools to aid with compiling ROSCO.

On Mac/Linux, standard compilers are generally available without any additional downloads. On 32-bit windows, we recommend that you install MinGW (Section 2). On 64-bit Windows, you can simply install the MSYS2 toolchain through Anaconda:

conda install m2w64-toolchain libpython
conda install cmake make  # if Windows users would like to install these in anaconda environment

Once the CMake and the required compilers are downloaded, the following code can be used to compile ROSCO.

# Clone ROSCO
git clone https://github.com/NREL/ROSCO.git

# Compile ROSCO
cd ROSCO/ROSCO
mkdir build
cd build
cmake ..                        # Mac/linux only
cmake .. -G "MinGW Makefiles"   # Windows only
make install

This will generate a file called libdiscon.so (Linux), libdiscon.dylib (Mac), or libdisscon.dll (Windows) in the /ROSCO/install/lib directory.

1.1.4. ZeroMQ Interface#

There is an option to interface ROSCO with external inputs using ZeroMQ. Currently, only externally commanded yaw offset inputs are supported, though this could easily be expanded if the need arises.

To use the ZeroMQ interface, the software must be downloaded following the ZeroMQ download instructions. Using CMake, ROSCO can then be compiled to enable this interface by using the ZMQ_CLIENT:ON flag with the cmake command in Compile using CMake:

cmake -DZMQ_CLIENT:ON ..

1.2. Installing the ROSCO toolbox#

The ROSCO toolbox is based in python and contains all relevant ROSCO tools; the source code can be found at: https://github.com/NREL/ROSCO/. In addition to tuning procedures, the ROSCO toolbox also contains example scripts, a Simulink Model of ROSCO, OpenFAST pre-and post-processing functions, linearized systems analysis tools, and a testing suite.

1.2.1. Anaconda Download - ROSCO Toolbox#

If one wishes to simply use the modules provided in the ROSCO toolbox through scripts of their own, the ROSCO toolbox can be installed via the conda-forge channel of Anaconda. They can then be accessed using the standard methods of loading modules in python, e.g:

from ROSCO_toolbox import controller as ROSCO_controller
from ROSCO_toolbox import turbine as ROSCO_turbine

Note that the install procedures for the ROSCO toolbox are the same as in Anaconda Download - ROSCO, but do not involve moving the controller binary file. In order to download the most recently compiled version release, from an anaconda powershell (Windows) or terminal (Mac/Linux) window, create a new anaconda virtual environment:

conda config --add channels conda-forge
conda create -y --name rosco-env python=3.8
conda activate rosco-env

navigate to your desired folder to save the compiled binary using:

cd <desired_folder>

and download the controller:

conda install -y ROSCO

1.3. Full ROSCO Installation#

We recommend using the full ROSCO tool-chain. This allows for full use of the provided functions along with the developed python packages and controller code,

Please follow the following steps to install the ROSCO tool-chain. You should do step 2 or 3. If you simply want to install the ROSCO toolbox without the controller, do step 3. If you would like to install the ROSCO toolbox and compile the controller simultaneously, do step 2.

Create a conda environment for ROSCO

conda config --add channels conda-forge # (Enable Conda-forge Channel For Conda Package Manager)
conda create -y --name rosco-env python=3.8 # (Create a new environment named "rosco-env" that contains Python 3.8)
conda activate rosco-env # (Activate your "rosco-env" environment)

Clone and Install the ROSCO toolbox with ROSCO controller

git clone https://github.com/NREL/ROSCO.git
cd ROSCO
conda install compilers # (Mac/Linux only)
conda install m2w64-toolchain libpython # (Windows only)
conda env config vars set FC=gfortran # Sometimes needed for Windows
conda install -y wisdem>3.7
python setup.py install --compile-rosco

Clone and Install the ROSCO toolbox without ROSCO controller

git clone https://github.com/NREL/ROSCO.git
cd ROSCO
python setup.py install

1.4. Getting Started#

Please see Standard ROSCO Workflow for several example scripts using ROSCO and the ROSCO_toolbox.