This in-progress package currently includes an overall floating array project class, classes for components of a floating array, and a series of data structures and functions for bathymetry, soil conditions, and other site conditions.
This package integrates various open-source array modeling tools such as RAFT, MoorPy, and FLORIS. FAModel can automatically create a model of the array in any of these tools.
To enable organized storage of floating array information and functions specific to components, each component of an array has a dedicated class (i.e. Mooring class, Turbine class, etc).
This document provides information on the FAModel class structure, then delves into the Project class methods and properties, and finally provides an overview of the FAModel Ontology YAML setup.
The structure of the project class and component classes is described in the following sections:
- Project Class
- Base Classes
- Platform Class
- Mooring Class
- Anchor Class
- Cable Class
- Turbine Class
- Substation Class
All array information and component objects are stored in the Project object, so component objects must be accessed through the Project object.
Major component classes (Platform, Mooring, Cable, Anchor, Turbine, Substation) are stored in a dedicated dictionary within the project class that lists each component instance in the array, with the key being the component's ID and the value pointing to the object.
For example, mooringList is the Project class dictionary listing all Mooring objects in the array. To access a component object, the user can follow
this method: project.mooringList[<mooring line ID>] where project in this case is the name of the Project class instance.
Subcomponent classes (such as Section, Connector, Dynamic Cable, Static Cable, Joint) can be accessed
through the subcomponent list of the parent component object. For example, the static cable within a cable object can be accessed in the following way:
project.cableList[<cable ID>].subcomponents[2] if the static cable was the third subcomponent from end A of the cable. Subcomponents are
always listed from end A to end B of the parent object.
Each component is overviewed in a section of this ReadMe, and a full list of each component class's properties and methods is provided in the ReadMe dedicated to that specific class.
A full description of the project class methods and properties is found in the following sections:
FAModel integrates a variety of modeling tools, and provides functions for easy transfer of information from design tools to FAModel. The FAModel Integration section provides an overview of the tools integrated with FAModel and how to use them.
An overview of the Ontology YAML file setup is found in the following section.
- FAModel Ontology Overview
For a full description of the ontology yaml file with examples, see Ontology ReadMe
The Project class provides a standard data structure that combines
design information (through an ontology yaml file or RAFT) and site information.
Currently the site information focuses on the seabed and lease area
boundary. In the future, metocean data will also be included. The design information
includes anchors, platforms, turbines, substations, cables, and mooring lines. Components of the array each have a dedicated class. All component classes inherit from either an edge or a node
base class. Base classes are described in more detail in Base Classes. The class structure is visualized below:
The project class includes a grid over which seabed bathymetry and
soil information is stored. The soil information follows a property
parameterization with the following fields:
- soil_class - soil classification name:
- soft clay
- medium clay
- hard clay
- sand
- soil_gamma - soil effective unit weight [kPa] (all soils)
- soil_Su0 - undrained shear strength at mudline [kPa] (clay soils)
- soil_K - undrained shear strength gradient [kPa/m] (clay soils)
- soil_alpha - soil skin friction coefficient [-] (clay soils)
- soil_phi - angle of internal friction [deg] (sand soils)
For details on the properties and methods of the Project class, see Project class methods and Project class properties
There are two base classes from which all array component classes inherit: Nodes and Edges. These classes provide methods to create, look up, and remove attachments between component objects.
Nodes are classes that can be described by a point in space, such as a platform or anchor. Edges are classes that connect two nodes, such as a mooring line or cable.
The Node class contains the following properties:
- id : unique ID of the Node object
- attachments : dictionary of objects attached to the node (usually Edges). The key is the id of the attached object, and the value is a dictionary of information on the attached object, set up as shown below: {'obj': attached object, 'id': id of attached object, 'r_rel': relative location of attached object, 'type': 'node'}
- part_of : Edge object this node is a subcomponent of (if applicable)
- r : xy position of Node [m]
- theta : heading of Node [rad]
- R : rotation matrix
The Node class methods are:
- isAttached : check if an object is attached to the node
- attach : attach an object to this node
- detach : detach a specified object from this node
- getTopLevelEdge : returns higher-level edge this node is a part of, if applicable
- setPosition : sets position of node, and heading if applicable
The Edge class contains the following properties:
- id : unique ID of the edge object
- attached_to : object(s) either end of the edge is attached to. This is a list of the objects (not a dictionary like node.attachments), where end A attachment is in the 0th index, and end B attachment object is in the 1st index.
- rA : end A location [x,y]
- rB : end B location [x,y]
- part_of : Edge object this edge is a subcomponent of (if applicable)
- subcomponents : chain of edges and nodes that make up this edge
- whole : boolean, false if sub edges/nodes aren't all connected
The Edge class methods are:
- isAttachedTo : checks if specified node is attached to this edge
- attachTo : attaches a specified node to end A or end B of this edge
- detachFrom : detach a specified end of this edge from what it is attached to
- addSubcomponents : adds a sequence of alternating nodes and edges as subcomponents of this edge, connecting the subcomponent objects in the process.
- getTopLevelEdge : returns higher-level edge this edge is a part of, if applicable
- setEndPosition : sets the position of an edge end
- delete : detach the edge from anything it is attached to
Edge classes such as Cables and Moorings can be made up of subcomponents that are alternating series of nodes and edges. For example, a Mooring object with subcomponents Connector-Section-Connector, or a Cable with subcomponents DynamicCable-Joint-StaticCable-Joint-DynamicCable.
The platform class contains properties and methods pertaining to a floating platform. Platforms can be substation platforms, floating wind platforms, wave energy converters, buoys, or other floating structures. The Platform class inherits from the Node class.
The Platform class is described in detail in the Platform ReadMe file.
The Mooring class contains properties and methods pertaining to a mooring line of a floating offshore wind turbine. The Mooring class inherits from the Edge class.
A mooring class object contains all of the subcomponents of a line from anchor to fairlead, or from fairlead to fairlead for a shared mooring line. Mooring lines will have subcomponents which alternate between Connector objects and Section objects.
In a chain-polyester line, there would be 5 subcomponents of the Mooring object: [Connector, Section, Connector, Section, Connector]
Note
The anchor is not part of the Mooring object
Detailed information on the Mooring, Section, and Connector classes is provided in the Mooring ReadMe file
The section class contains information on a mooring line segment. A mooring line may have multiple materials or properties along the line, and each segment will have its own Section object. The Section class inherits from Edge and dict. For example: in a chain-polyester-chain line for a semi-taut mooring line, there will be 3 Section objects, one for each segment. These Sections are subcomponents of the Mooring object.
The Connector class contains information on a mooring line connector. Each end of a mooring line will have a Connector object, meaning the minimum number of subcomponents of a Mooring object is 3 (Connector, Section, Connector). There will also be a connector between segments of the mooring line with different properties. The Connector class inherits from Node and dict.
The Anchor class contains properties and methods of a mooring line anchor. The Anchor class inherits from the Node class. Anchors may be shared (multiple lines attached to the same anchor).
Capacity and load functions in the anchors folder provide the capacities of an anchor and the loads at its lug location. These functions are called from the Anchor method getAnchorCapacity(). A sizing function alters the anchor geometry until the desired factors of safety are reached. Various anchor types are supported, for detailed information on the Anchor class, as well as capacity and load functions see the Anchor ReadMe file.
The Cable class contains properties and methods of an intra-array cable. The Cable object is defined as the entirety of an electrical cable between two platforms or a platform and an offshore substation. For full details on the Cable class and its subcomponent classes (DynamicCable, StaticCable, Joint), see the Cable ReadMe file
The Cable class is comprised of
subcomponents. For a suspended cable with no static portion, there is only one subcomponent - a DynamicCable object, as shown below:
For cables with dynamic and static portions, there will be multiple subcomponents, as the static portion
of the cable willl be a StaticCable object, and there will be a Joint object at each end of a static cable. For example, a Cable object may
have subcomponents in the order DynamicCable-Joint-StaticCable-Joint-DynamicCable.
Note
Unlike the Mooring class, there does not need to be a Joint at the platform connections, only between a static and dynamic cable.
The DynamicCable class contains properties and methods for a cable section that will experience motion. These cables often contain buoyancy modules to create a buoyant section that relieves tensions when the platform it is connected to moves.
The segments of the dynamic cable with buoyancy modules is not split into its own subcomponents because the dynamic cable is all one portion. Instead, the design dictionary contains information on the location of buoyancy modules along the cable length. Joint locations are determined based on the heading and span of the DynamicCable.
The StaticCable class contains properties and methods for a cable section that will not move (generally these cables are buried or otherwise prevented from moving along the seabed). Routing can be specified for each StaticCable between its end Joints.
The Joint class contains information on a joint between cable types. The Joint locations are set based on the seabed endpoint of the connected DynamicCable.
The Turbine class contains properties and methods for a floating offshore wind turbine (including RNA, tower, and any transition pieces). Turbine objects are generally attached to a platform object.
For a complete description of the Turbine class, see the Turbine ReadMe file
The substation class contains information on the offshore substation topside. Currently, the capabilities of the substation class are very minimal, but in the future will include detailed information on the substation topside design. Substation objects are generally attached to a platform object. For a complete description of the Substation class, see the Substation ReadMe file
The anchors subpackage contains modules for anchor capacity calculations as a function of soil type. It has the following:
- level-1 capacity curves for the following general anchor types and soil classes:
- DEAs in soft clay, medium clay, hard clay, or sand
- VLAs in soft clay or medium clay
- Suction anchors in soft clay or medium clay
- SEPLAs in soft clay
- level-2 capacity functions for select anchor types and quantitative soil properties
- a general anchor capacity calculation 'switchboard' that routes to the appropriate functions for specified anchor and soil types.
- a sizing function that uses COBYLA to minimize anchor cost while meeting safety factor requirements.
The seabed subpackage provides a set of functions for inputting and processing "seabed" information, including bathymetry, soil properties, and other spatial properties of a lease area such as the lease area boundary.
Loads in information from ontology yaml and calls loadDesign and loadSite to store information and create necessary objects.
Load in the design information from a YAML file or dictionary. Loads in cables, mooring lines, anchors, platforms, turbines, and substations. Creates objects for each component in the array. Dictionaries of mooring line objects, anchor objects, platform objects, cable objects, turbine objects, and substation objects are created and stored in the project (array level) object.
Load site information from a YAML file or dictionary. Loads in bathymetry from a file using the loadBathymetry method, or from xyz data. Loads in boundaries from a file using the loadBoundary method, or loads in the boundaries from xy data. Additional site information such as general depth, water density, air density, and air dynamic viscosity are also loaded here.
Set up the rectangular grid over which site or seabed data will be saved and worked with. Directions x and y are generally assumed to be aligned with the East and North directions, respectively, at the array reference point.
Load a lease area boundary for the project from an input file.
Load bathymetry information from an input file (format TBD), convert to a rectangular grid, and save the grid to the floating array object (TBD).
Load geoetechnical information from an input file (format TBD), convert to a rectangular grid, and save the grid to the floating array object (TBD).
The input file should provide rows with the following entries:
- x coordinate
- y coordinate
- class - soil classification name ('clay', 'sand', or 'rock' with optional modifiers)
- gamma* - soil effective unit weight [kPa] (all soils)
- Su0* - undrained shear strength at mudline [kPa] (clay
- K* - undrained shear strength gradient [kPa/m] (clay
- alpha* - soil skin friction coefficient [-] (clay soils)
- phi* - angle of internal friction [deg] (sand soils)
Some (*) parameters are optional depending on the soil class and mode.
Irregular sampling points will be supported and interpolated to a rectangular grid.
Interpolate soil properties at specified location from the soil properties grid and return a dictionary of soil properties that can be used in anchor capacity calculations.
Compute holding capacity of a given anchor based on the soil info at its position. The anchor object's anchor properties and location will be used to determine the holding capacity, which will be saved to the anchor object.
Computes the depth at a specified x-y location based on the bathymetry grid stored in the project. The seabed normal vector can also be obtained.
Computes the location at which a ray crosses the seabed
Obtain the z-coordinates of a projection along the seabed surface for a set of x-y coordinates.
Computes the horizontal distance between every turbine's undisplaced location and returns a matrix of these distances for the array.
Calculates the cable's length based on its routing
Checks whether a cable crosses over any exclusions or other out of bounds areas
Trims bathymetry and soil grid information that is outside the project boundaries, for faster execution and plotting.
Creates cable objects from a list and connects them to platforms. If a cable configuration dictionary is provided, full 3d cable designs will be loaded in and cable headings/routing will be adjusted to avoid mooring line clashing. If only list of cable connections is provided, only basic information such as cable cross-sectional properties, conductor size, and connections will be loaded. Designed to work with the output list format from FADesign/CableLayout_functions.getCableLayout(), which will be publicly available in the near future.
Plots aspects of the Project object in matplotlib 3D. Depending on available information and settings, RAFT platform and turbine models, cables (dynamic and static, including routing), moorings, bathymetry, lease boundaries, and soil conditions are plotted.
Plots aspects of the Project object into matplotlib in 2D. Depending on available information and settings, moorings, cables (including routing), lease boundaries, bathymetry, and soil conditions are plotted.
Creates an array in MoorPy based on the mooring, anchor, cable, and platform objects listed in the project object. Also allows the option to plot the resulting MoorPy array.
Sets up a FLORIS interface and stores thrust/windspeed curve
Function to find array equilibrium with FLORIS wake losses and MoorPy platform offsets.
Function to calculate AEP in FLORIS with moorpy platform offsets
Create a RAFT object and store in the project class
Calls the addMarineGrowth mooring and/or cable class method for the chosen mooring and/or cable objects, and applies the specified marine growth thicknesses at the specified depth ranges for the specified marine growth densities.
Function to reduce MBL of specified lines based on corrosion thickness
Function to update the array spacing, angles, platform locations and headings, etc for a uniform array
Function to duplicate a platform object and all of its associated moorings and anchors. Does not duplicate cables.
Create a platofrm object, along with associated mooring and anchor objects from a moorpy system. Currently only works for regular (non-shared) moorings.
Method to run watch circles on all FOWTs in the array at once from a provided thrust force. Determines max force on moorings, anchors, and cables and stores maximum for each. Can optionally determine safety factors, include dynamic amplification factors, and determine seabed disturbance from the mooring line in the watch circle.
Produces mooring line shapely envelopes and platform watch circle shapely envelopes that will appear if plot2d() is called.
Function to sum all available costs for the array components. Eventually will produce a spreadsheet with itemized costs for each component
Function to unload information to an ontology yaml file
Function to extract farm-level information required to create FAST.Farm case simulations. Currently under development.
Function to create a FAST.Farm-compatible MoorDyn input file.
Streamlines getting values from the design dictionary from YAML file, including error checking.
A variety of tools are integrated with FAModel. RAFT, MoorPy, and FLORIS models can all be automatically built based on information stored in the project class:
The frequency domain floating wind modeling tool RAFT is integrated in FAModel through the project method getRAFT(). This requires the RAFT dependencies to be included in your python environment. Additionally, sections of the yaml file related to RAFT are required. If building a project class without a yaml file, a modified RAFT yaml will need to be built and sent as a dictionary input to project.getRAFT(), although no mooring sections are needed as this information is pulled from the project's moorpy array. The RAFT model is then automatically saved in the project class under the property project.array.
MoorPy is a quasi-static modeling tool for stationkeeping systems, cables, and floating platforms. It is recommended to check out the development branch of MoorPy for use with FAModel.
A MoorPy system of all the platforms, moorings, anchors, and cables in an array can be automatically built using the project method getMoorPyArray(). No further information is required to build this model, as it pulls details on object connections, design, and location from the project class.
FLORIS is a wake modeling and wind farm controls software for wind farm arrays, including floating arrays. To use the FLORIS-FAModel integration, FLORIS and its dependencies must be installed in the famodel environment.
FAModel is designed to be compatible with the information outputs from NREL floating array design tools, which are being concurrently developed.
Contains all information on the design of the floating array. For a detailed description of the Ontology YAML by section with examples, see Ontology ReadMe
Key information for building the floating array design yaml file by section:
This section contains information about the site, either through listing of data file names, or site information listed in table format. Subsections include general information, boundaries, exclusions, bathymetry, seabed, metocean, and resource.
This section contains a table of information about the turbine array layout. Each row in the table represents one turbine. The turbineID refers to the turbine type in the turbine section, the platformID refers to the platform type from the platform section, the mooringID refers to the mooring system number in the mooring_systems section. The x_location and y_location refer to the xy coordinates for the center of the platform, and the heading adjust describes any rotation of the platform's mean position.
If 0 is provided for the mooring system ID, this designates that the mooring details for that turbine are in the array_mooring section, which is generally in use for shared moorings or anchors.
This section contains array-level data on anchors and lines. Mooring lines listed here are not part of the mooring_systems section, as these are either shared lines or lines connected to shared anchors. The anchors are listed in the anchor_data table, where the xy location, anchor type, and embedment information are provided. The line_data table provides information on each line, including which platform row number (from the array table) and/or anchor number (from the anchor_data table) is attached to the line, what the headings for each end are, and whether there is any length adjustment.
headingA refers to the mooring heading of the turbine the line is connected to for end A of the line, if it is connected to a platform (for all non-shared moorings, end A is connected to the anchor, and in this instance NA can be used for headingA). Similarly, headingB refers to the mooring heading of the platform the line is connected to for end B of the line. End B must be connected to a platform.
This section lists the mooring system for each turbine, not including any shared lines or lines with shared anchors. The list of mooring systems is numbered by msX where X is the mooring system ID number provided in the array table. Each mooring system provides the ID of the configuration, the heading, the anchor type, and whether there is any length adjustment.
Platforms that have shared mooring or shared anchors for some of their lines may have a listing in the mooring system (if the MooringID is not 0 for that platform in the array section), but this mooring system will only contain mooring line configurations that are not shared moorings or anchors.
This section lists the mooring configurations that are called out i nthe mooring_systems section or the array_mooring section. For each configuration, a descriptive name, fairlead and anchor radius, fairlead depth, and list of sections is provided. Items in the sections list may be mooring lines (in which case type and length are given as keys) or connectors (in which case the key connectorType must be used). Connectors are optional, and some, all, or none of the connectors for a line may be provided. However, only one connector may be listed between each line type listed.
Please note that the order of the sections list is very important. Entries in the sections list must be provided in order from end A (anchor end for non-shared lines) to end B (fairlead end).
For shared line configurations, a key 'symmetric' may be used to describe whether the provided line configuration is half of a symmetric line (symmetric: True) or a full line configuration (symmetric: False) in the same level as the name and radii information. If a connector is given as the last item in the section list for a shared symmetric line, it is assumed that the provided connector is located in the center of the line.
This section provides design details for each line type listed in the line configurations section. Necessary information to be listed for each line type includes nominal diameter, volume-equivalent diameter, mass per unit length, quasi-static stiffness, minimum breaking load, and material. Optional information includes cost per unit length, dynamic stiffness, dynamic stiffness mean-load multiplier, and material details.
This section provides design details for each mooring connector type listed in the line configurations section. There are no requirements on what must be listed for each connector, but optional inputs include mass, volume, and CdA (product of cross sectional area and drag coefficient).
This section provides design detials for each anchor type listed in the mooring_systems section or the array_mooring anchor_data table. There are no requirements on what must be listed for each anchor, but optional inputs include diameter, length, mass, area, thickness, and embedment length.