Getting Started Guide

This document presents a step-by-step procedure for setting up a WakeBlaster project. The use of WakeBlaster involves three main components, as depicted below:

The client is the code on the user-side of the API. It is responsible for creating and uploading data through the WakeBlaster application so that it can perform calculations. The WakeBlaster API provides a language-independent standard interface between your IT System and the WakeBlaster Application. In order to simplify client-side code, there are also language-specific WakeBlaster Software Development Kits (SDK’s) available in python and matlab which provide functions that wrap around the API:

The full documentation for the WakeBlaster API can be found here. In this present document we describe briefly the process of using the API to configure WakeBlaster and how to submit data and retrieve results. Please refer to the API specific documentation for details.

At a very high level, WakeBlaster compromises:

  • A database of wind turbine and met-masts designs uploaded by the user. These describe properties such as power curves, thrust curves, hub-heights, rotor diameters, and instrument types and instrument mounting heights.

  • A database of wind farms. Each wind farm comprises one or more instances of wind turbines and meteorological masts. Each of the instances are in turn described by one of the wind turbine and met-mast designs.

  • The calculation engine itself. This is the part of wake blaster that takes measurements data that the client code submits to WakeBlaster and undertakes the advanced wake calculations.

  • A database of measurements (e.g. wind speeds and directions) uploaded by the user.

  • A databse of results from simulations that were initiated by the user based on prior sets of measurements.

The WakeBlaster client code is expected to upload turbine and met mast designs, wind farm description and ambient measurements through the API in order to run simulations. The steps a first-time user will need to take are:

  1. Upload wind turbine designs and perhaps met mast designs

  2. Upload a wind farm description

  3. Submit measurements (they can be real SCADA measurements or entirely virtual) which indicate the flow cases to simulate

  4. Start the WakeBlaster simulation

  5. Retrieve the results once the simulation has finished.

Note that once the user has uploaded the designs and wind farm description, these do not need to be re-uploaded for future simulations, assuming that the information is unchanged.

Step 1: Uploading Designs

Wind turbine and mast designs are representations of specific models of wind turbines and masts. Most wind farms will just have one design of wind turbine but it is also common for there to be multiple designs in a single wind farm.

Wind turbine designs are defined by wind industry standard “.wtg” files, which are originally a WASP format. The file is in an XML format and contains information about the turbine power and thrust coefficient curves as well as the rotor diameter and hub height.

The met mast designs indicate the mounting heights at which instruments are placed on a met mast. This is used by WakeBlaster to determine the height of a measurement and therefore make necessary adjustments for shear and turbulence. The format is based on JSON key-value pairs and is documented in the API docs. A simple met mast design would look like this:

{
   "description": "Mast",
   "height": 80,
   "type": "Lattice",
   "instruments": [
      {
         "id": "1",
         "mounting_height": 80
      }
   ]
}
}

When uploading designs through the API, the client must specify the design ID via the URL. This identifer is then reference in the turbine and met-mast properties in the wind farm description. Uploading designs is fully documented in the API docs with an example. This includes documentation for the met mast design format.

Step 2: Uploading a Wind Farm Description

In WakeBlaster, the Wind Farm Description provides details such as the location of each wind turbine and met mast in the farm, assigning each of them an identifier, design and location.

The wind farm description format is WakeBlaster specific that contains two main fields:

  • A list of turbine instances and their properties.

  • [Optional] A list of met-mast instances and their properties.

It is fully documented in the API docs, which describes the required properties for each instance. A simple wind farm description in JSON will look something like:

{
    "met_mast_instances": [
        {
            "id": "M1",
            "design_id": "80m_lattice_mast",
            "easting": 600500, 
            "northing": 500000,
            "elevation": 0
        }
   ],
    "turbine_instances": [
        {
            "id": "WTG1",
            "design_id": "V110-2.0MW",
            "easting": 600000,
            "northing": 500000,
            "elevation": 0
        },
        { 
            "id": "WTG2",
            "design_id": "V110-2.0MW",
            "easting": 600000,
            "northing": 500500,
            "elevation": 0
        }
    ]
}

Optionally, a wind resource grid may be uploaded alongside the wind farm description. This is an output of the terrain flow model in the WASP .wrg or .rsf format. This specifies the speed-ups across the site from the location where measurements are provided. It is also valid to not provide a wind resource grid however, in which case then terrain is assumed homogeneous with constant wind speed over the site.

Step 3: Uploading Measurements

Measurements are the method by which the user tells WakeBlaster the ambient and turbine conditions at the site. Measurements may be measurements from a pre-construction met-mast, SCADA data from an operating wind farm, or entirely virtual data (for example to create a wind farm power curve).

Each measurement indicates:

  • The instance where the measurement is taken (in the case of virtual measurements it may be a good idea to add a virtual met mast in the wind farm description at the reference location of wind conditions)

  • The quantity (e.g. wind speed) that it’s measuring (which is denoted by the signal ID).

  • The value

  • Optionally, the instrument ID, which would be used to infer the height of the measurement (important for shear effects).

  • Either:

    • A time-stamp for time series data

    • A flow-case ID for non-time-domain data.

Each measurement thus measures only one quantity. Measurements are later aggregated together by the simulator by matching their time-stamp or flow-case ID so that contemporaneous measurements correspond to the same flow case. Each flow case must have at the very minimum one wind speed and one wind direction measurement.

The API for adding a measurement set and the format of the data for each measurement is here. The “signal_id” specifies the type of quantity that is being measured. The table below describes the how the signal ID is matched:

Signal ID contains Interpretation Unit WindSpeed_avg wind speed - 10 minute mean m/s WindDirection Mean wind direction – clockwise from North deg WindSpeed_std 10 minute standard deviation of wind speed m/s AirTemperature Air temperature (for calculation of air density with pressure) Celsius AirPressure Air pressure (for calculation of air density with temperature) millibar AirDensity Air density kg/m^3 MoninObukhovLength Monin-Obukhov Length (needs to be enabled in the settings) m NacDirection Nacelle downwind direction – clockwise from North deg OperatingState 0 = not operating, 1=operating -

The client will generally link each measurement set to a farm that has already been uploaded (step 2). If the measurement set is not linked to a farm at this point it can be later linked to a farm when creating a simulation (step 4).

A small example upload of a single wind speed and single wind direction measurement might look in JSON format something like: 

{
  "farm_id": "demo_wind_farm",
  "processing_state": "clean",
  "measurements": [
    {
      "signal_id": "WMET_WindSpeed1_avg",
      "instance_id": "M1",
      "value": 8.3,
      "timestamp": "2017-01-23T06:30+01:00"
    },
    {
      "signal_id": "WMET_WindDirection1_avg",
      "instance_id": "M1",
      "value": 212.1,
      "timestamp": "2017-01-23T06:30+01:00"
    }
  ]
}

When uploading a measurement set, a corresponding ID is returned by the API which needs to be retained by the client for step 4.

Step 4: Starting a WakeBlaster Simulation

Once one or measurement sets have been submitted, a simulation is enacted upon a group of measurement sets. The basic building blocks of a simulation is outlined in the figure below. Each (previously uploaded) measurement set contains many measurements which the simulator internally groups into flow-cases by matching up corresponding time-stamps or flow-case ID’s within the same measurement set. A flow-case is defined here as one flow and wake analysis of the wind farm based on contemporaneous steady-state conditions.

The API for starting a simulation is documented in the API docs. When adding the simulation, the API returns a simulation ID which needs to be retained by the client for step 5. Note that adding a simulation starts a separate asynchronous process on the cloud. The client must not assume that results are already available once its process returns from the API.

Step 5: Retrieving Simulation Results

As the simulation proceeds on a remotely hosted separate process, the client will most likely want to check periodically whether some or all of the results are available. This is sketched out below.

The client can get the status of the simulation by accessing the getSimulation endpoint, documented in the API docs. The information returned includes a flow case count, which was calculated by the simulator based on the measurements submitted, and a result count, of which there will be one per flow case once the simulation has completed. It is possible that some flow cases will result in errors, and these will be included in the error count and not in the result count.

Once simulated, the results can be retrieved via the getResults endpoint, documented in the API docs. This returns a container of result objects. Each result references a flow-case or timestamp and measurement set ID and contains results for farm level properties (e.g. farm power output) and results at each turbine and met mast in the farm. These can be processed in any way the client likes. A reduced example output of a single result in JSON format will look like:

{
  "measurement_set_id": "a0xbcd",
  "simulation_id": "b6r37d",
  "timestamp": "2017-01-23T06:30+01:00",
  "farm_power_output": 2100000,
  "turbine_results": [
    {
      "instance_id": "WTG1",
      "power": 1100000,
      "rotor_wind_speed": 8.31
    },
    {
      "instance_id": "WTG2",
      "power": 1000000,
      "rotor_wind_speed": 8.03
    }
  ],
  "met_mast_results": [
    {
      "instance_id": "M1",
      "wind_speed": 8.31
    }
  ]
}

Note how the instance ID matches up with the ID fields uploaded in the wind farm description and how the timestamp matches with the timestamp submitted when uploading the measurements.

Conclusion

This document explains the basic steps that the user needs to run their first WakeBlaster simulation and understand the process in general. The WakeBlaster HTTPS API can be interfaced to any language that supports the RESTful protocol. To help with the syntax-heavy steps of communicating with the API, we have created open-source Software Development Kits (SDK) in Python and Matlab, which provide functions to execute the steps described above. Please contact wakeblaster@proplanen.com for more information.