Attribute Schema

The Portfolio Coordination project is constructing a database of all WETO software to facilitate the portfolio-wide analysis. Initially, only actively-funded software is included, but it will expand to all software under WETO. The database consists of attributes of each software project expressed in a YAML file in the nrel/wetostack repository. The attributes should conform to the JSON schema (YAML is a superset of JSON) described in the documentation below. See the FLORIS entry for an example.

To add or update a project entry, submit a pull request to this repository modifying an existing project file or creating a new one. All entries should be in the ./software_attributes/database directory. A validation script is available, and it is run automatically upon creation and update of the pull request.

How to read the schema docs

The schema docs provide the following information:

• The list of required fields

• A short description, where necessary

• Value data types

• Set of valid values

• An example, where necessary

system_type

Type: array of enum (of string)

The wind energy system architectures supported by the software. Use any if the software is type-agnostic.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "hawt"
• "vawt"
• "awes"
• "any"

Each attribute in blue text is a drop-down element. Try clicking the attribute text “system_type” above to open the element.

The first line indicates the data type required for the value. In this case, Type: array of enum (of string) means the value must be an array where each element is a string matching one of a predefined set of options.

The next line is a description of the attribute.

Then, contextual information for the data type and available options for the value is provided. Finally, an example is given in some cases.

Quick tips

• Attributes with null values (None) must be removed or commented, such as:

key1: value1
# key2:
key3: value3

• Boolean values are either true or false.

• Strings do not require quotes.

Expand all Collapse all

Type: object
No Additional Properties

github_account

Type: string

The associated account on GitHub.
In the web address, this is the middle component: https://github.com/<account>/<repo>.

github_repo

Type: string

The repository name.
In the web address, this is the last component: https://github.com/<account>/<repo>.

primary_uses

Type: array of enum (of string)

The primary use for this software. Though there may be many uses, choose the options that most closely match the envisioned use.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "controls"
• "cost"
• "data_analysis"
• "design"
• "optimization"
• "simulation"

active_funding

Type: boolean

Has this project received funding to directly support software development in the current quarter?

development_status

Type: enum (of string)

• on_hold: No active development or maintenance
• maintenance: Maintenance activities only including bug fixes
• new_features: Actively planning and developing new features

Must be one of:

• "on_hold"
• "maintenance"
• "new_features"

programming_language

Type: enum (of string)

The primary programming language even though many projects contain source code in a few languages.

Must be one of:

• "python"
• "fortran"
• "matlab"
• "c++"
• "rust"
• "julia"
• "r"

license_type

Type: enum (of string)

Choose the corresponding license string from this list of license types.

Must be one of:

• "afl-3.0"
• "apache-2.0"
• "artistic-2.0"
• "bsl-1.0"
• "bsd-2-clause"
• "bsd-3-clause"
• "bsd-3-clause-clear"
• "bsd-4-clause"
• "0bsd"
• "cc"
• "cc0-1.0"
• "cc-by-4.0"
• "cc-by-sa-4.0"
• "wtfpl"
• "ecl-2.0"
• "epl-1.0"
• "epl-2.0"
• "eupl-1.1"
• "agpl-3.0"
• "gpl"
• "gpl-2.0"
• "gpl-3.0"
• "lgpl"
• "lgpl-2.1"
• "lgpl-3.0"
• "isc"
• "lppl-1.3c"
• "ms-pl"
• "mit"
• "mpl-2.0"
• "osl-3.0"
• "postgresql"
• "ofl-1.1"
• "ncsa"
• "unlicense"
• "zlib"

data_collection_methods

Type: array of enum (of string)

• modeling: Retrieved from a numerical model
• laboratory: Data from a controlled experiment such as RAAW
• field: Data from systems "in the field", typically in a commercial setting

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "modeling"
• "laboratory"
• "field"

last_release_date

Type: string

Date of the last tagged release available on GitHub; use the following format: YYYY-MM-DD.

scope

Type: array of enum (of string)

The wind energy system scope of the software. System implies engineering and cost coupling

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "turbine"
• "farm"
• "system"
• "atmosphere"

system_type

Type: array of enum (of string)

The wind energy system architectures supported by the software. Use any if the software is type-agnostic.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "hawt"
• "vawt"
• "awes"
• "any"

system_location

Type: array of enum (of string)

The location of the wind energy system supported by the software. Use any if the software is location-agnostic and offshore for fixed + floating.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "land"
• "offshore"
• "fixed_offshore"
• "floating_offshore"
• "any"

time_domain

Type: string or array of enum (of string)

Does the software support modeling or analysis in a dynamic time domain, steady-state, and/or the frequency domain? This is an array-type field, so include multiple elements, as needed.

Example:

time_domain:
- steady
- dynamic
- frequency

turbine_model

Type: array of enum (of string)

The fidelity with which the turbine is represented in the software model (if at all). Options are 'regression' (e.g. NREL CSM), 'lookuptable' (e.g. in FLORIS), 'momentumsink' (e.g. in WRF), 'multibodybem' (e.g. OpenFAST), 'vortexmethod' (e.g. OLAF), 'actuator' (e.g. in CFD), 'geometry_resolved' (e.g. in CFD), 'SCADA' (e.g. FLASC/OpenOA)

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "regression"
• "lookup_table"
• "momentum_sink"
• "multibody_bem"
• "vortex_method"
• "actuator"
• "geometry_resolved"
• "SCADA"
• "N/A"

wake_model

Type: array of enum (of string)

The fidelity with which turbine wakes are represented in the software model (if at all).

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "analytical"
• "dynamic_meandering"
• "vortex_method"
• "navier_stokes"
• "N/A"

loads

Type: boolean

Does the software calculate system loads?

design_optimization

Type: boolean

Can the software conduct design optimization?

costs

Type: boolean

Does the software include or focus on costs?

tags

Type: array of string

List tags describing the methods and underlying equations modeled in the software. These are free-form entries, and are not validated. This field is not currently used, but aggregating the tags throughout the software portfolio will allow for categorizing the tools later.

No Additional Items

Each item of this array must be:

Type: string

Example:

tags:
- Euler bernoulli beam theory
- Blade element momentum theory
- Reynolds averaged Navier-Stokes
- Large eddy simulation
- Monte carlo methods

supported_platforms

Type: array of enum (of string)

List the type of computing platforms that are supported. Use any if the software is platform-agnostic.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "linux"
• "windows"
• "macos"
• "HPC"
• "any"

package_manager

Type: array of enum (of string)

List the package managers leveraged to distribute the software.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "homebrew"
• "pypi"
• "conda"
• "conda-forge"
• "spack_manager"

package_manager_url

Type: array of string

For any package managers listed in package_manager, include the URL to the package listing.

No Additional Items

Each item of this array must be:

Type: string

installation_complexity

Type: integer

Estimate the difficulty for a user with minimal context to install.
- 1 is a downloadable executable that can be double clicked
- 10 requires compiling from source code with numerous other compiled dependencies.

Value must be greater or equal to 1 and lesser or equal to 10

documentation_url

Type: string

Provide the URL to the project's online documentation.

has_user_docs

Type: boolean

Does the documentation contain a section tailored to using (i.e. executing, developing inputs, understanding outputs) the software?

has_developer_docs

Type: boolean

Does the documentation contain a section tailored to developing (i.e. extending, maintaining, testing) the software?

has_api_docs

Type: boolean

Does the documentation contain a description of the public API's?

has_cli_docs

Type: boolean

Does the documentation contain a description of the command line interface?

has_installation_docs

Type: boolean

Does the documentation contain a section describing the installation procedures?

has_getting_started_docs

Type: boolean

Does the documentation contain a section to guide new users through the onboarding and getting started process?

has_examples_tutorials

Type: boolean

Are examples or tutorials included with the software either through the documentation or in the repository directly?

has_design_intent_statement

Type: boolean

Is a statement describing the holistic design intent and design considerations of the software available?

readability

Type: integer

Estimate the readability of the documentation considering a user with minimal context.

Value must be greater or equal to 1 and lesser or equal to 10

project_coverage

Type: integer

Estimate the portion of the project covered by the documentation.

Value must be greater or equal to 1 and lesser or equal to 10

testing_framework

Type: boolean

Does the software leverage a testing framework?

continuous_testing

Type: boolean

Does the software have continuous testing in place?

test_coverage

Type: integer

The portion of the project covered by formal tests.

Value must be greater or equal to 0 and lesser or equal to 100

test_documentation

Type: boolean

Is documentation for the tests available?

performance_tests

Type: boolean

Are performance tests available?

first_class_ui

Type: array of enum (of string)

List the user interfaces that receive primary funding or developer attention.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "gui"
• "input_files"
• "library_interface"
• "web"

has_cli

Type: boolean

Is a command line interface available?

language_interfaces

Type: array of enum (of string)

List the connections available to interface the software to other languages.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "python"
• "fortran"
• "matlab"
• "c++"
• "rust"
• "julia"
• "r"

feature_accessibility

Type: integer

How much of the project is reachable through a public API?

Value must be greater or equal to 1 and lesser or equal to 100

filetypes

Type: array of enum (of string)

List the filetypes used in the project including inputs and outputs.

No Additional Items

Each item of this array must be:

Type: enum (of string)

Must be one of:

• "csv"
• "custom"
• "hdf5"
• "json"
• "numpy binary"
• "pvd"
• "xdmf"
• "yaml"
• "xlsx"

file_structure_stability

Type: enum (of string)

• stable: Never or rarely changes
• in_development: Actively changing
• semantic_versioning: Changes according to rules of semantic versioning

Must be one of:

• "stable"
• "in_development"
• "semantic_versioning"

dependencies

Type: array of array

List other WETO software projects that this one depends on either through a direct or indirect connection.
- direct: code-code integration
- indirect: one uses the output of the other via output file or another workflow process

This field is a 2D list. See the example below for syntax.

An example of a real dependency is FLORIS requires a power coefficient and thrust coefficient look up table from a higher fidelity simulation or field data. This often comes from OpenFAST, so that tool is an indirect dependency of FLORIS.

No Additional Items

Each item of this array must be:

Type: array
No Additional Items

Tuple Validation

Item at 1 must be:

Type: string

Item at 2 must be:

Type: enum (of string)

Must be one of:

• "direct"
• "indirect"

Example:

dependencies:
- - openfast
  - direct
- - floris
  - direct
- - exawind
  - indirect