(array-design-methods)=
# Array Cabling System Design Methodology

For details of the code implementation, please see the [Array System Design API](#array-design-api)
documentation.

## Overview

Below is an overview of the process used to design an array cable system in ORBIT.
For more details on the helper classes used to support this design please see
[Cabling Helper Classes](#cable-helpers-methods).

As of the current version of the code there are three array cabling layouts
that can be configured in ORBIT: grid, ring and custom. [Fig. 1](#grid-no-partial) is an example
of a grid layout featuring 7 "full-strings" and configured distances between
turbines on a string and each row. [Fig. 2](#ring-partial) is an example of a ring layout
where the there is a predetermined distance between the first turbines on a
string and the substation. This figure is also an example of a
"partial string" that is needed to complete the layout. The next sections will
go into more detail of the key steps in building out the array cabling system.

(grid-no-partial)=
:::{figure} ../../images/examples/full_grid_example.png
:align: left
:width: 35%

Grid layout with no partial strings.
:::

(ring-partial)=
:::{figure} ../../images/examples/partial_ring_example.png
:align: right
:width: 35%

Ring layout with 1 partial string
:::

<!-- # TODO: Adopt this when Jupyter Book v2 enables Python API docs building
:::{figure}
:label: layout-comparison-grid
:align: center
:class: grid grid-cols-2

(grid-no-partial)=
![Grid layout with no partial strings.](../../images/examples/full_grid_example.png)

(ring-partial)=
![Ring layout with 1 partial string.](../../images/examples/partial_ring_example.png)

Comparison of a grid layout with no partial strings ([](#grid-no-partial)) and a ring layout with
a partial string ([](#ring-partial))
::: -->

## Determining the Total Number of Strings

In order to create the minimum number of strings required to complete a
"standardized" array cable layout we must first determine how many turbines
can fit on a given set of cable types without overloading them.

### Maximum Turbines per Cable

The maximum number of turbines that can fit on each cable is determined by
dividing each cable type's power rating by the rated capacity of the turbine
and rounding down to the nearest integer.

{py:attr}`Cable.max_turbines` = $\lfloor\frac{P}{turbine\_rating}\rfloor$,
where

$P$ = {py:attr}`Cable.power`, and \\
{py:attr}`turbine_rating` = rated capacity of turbine

### Calculating a Complete String

The number of turbines that can fit on a string is determined by the user
configured cable types of the system. Starting from the smallest capacity cable
available, turbines are added to the string until that cable's maximum power
capacity is reached. This process is repeated for each of the next largest
capacity cables until all cable types have reached their maximum capacity. The
number of cable sections added to the string in this process represents the
maximum number of cables that can be added to each string.

```{code-block} py
:name: string-computation

# Assume that we are using the Fig 1. example so there can only be 6
# turbines contained in a single string of cables
max_turbines_per_string = 6

# Keeping with the Fig 1. example, assume cable1 is a Cable object that
# represents the "XLPE_400mm_36kV" cable from and cable2 represents the
# "XLPE_630mm_36kV" cable. Note that this is sorted from smallest to largest.
cable_list = [cable1, cable2]

# Start with an empty string
cable_layout = []
n = len(cable_layout)

# Loop through the cables as long as we haven't reached the string maximum
# and there are cables in cable_list
while n < max_turbines_per_string and cables:
    cable = cable_list.pop(0)  # remove the first cable in the list

    # Ensure that the most turbines in a string is is lower than the
    # string maximum and the maximum the individual cable can support,
    # then add another cable.
    while max_turbines_per_string > n < cable.max_turbines:
        cable_layout.append(cable.name)
        n = len(cable_layout)
```

After the above calculation is performed, {py:func}`cable_layout` will contain
a list of cable sections starting from the offshore substation and ending at
the last turbine on a string and will look like the following:

{py:attr}`full_string` = `["XLPE_630mm_36kV", "XLPE_630mm_36kV", "XLPE_400mm_36kV",`
`"XLPE_400mm_36kV", "XLPE_400mm_36kV", "XLPE_400mm_36kV"]`

In [Fig. 1](#grid-no-partial), there are 7 of full strings. In the [Fig. 2](#ring-partial) there are 7 full
strings and 1 partial string:

{py:attr}`partial_string` = `["XLPE_400mm_36kV", "XLPE_400mm_36kV", "XLPE_400mm_36kV"]`

### Number of Full and Partial Strings

The number of full strings is calculated using the equation below,

{py:attr}`num_full_strings` = $\lfloor \frac{Plant.num\_turbines}{num\_turbines\_full\_string} \rfloor$

and the number of partial strings (containing any remaining turbines) is
calculated with the following equation.

{py:attr}`num_partial_strings` = $Plant.num\_turbines \ \% \ num\_turbines\_full\_string$

## Layouts

### Ring

For a ring layout, the {py:attr}`substation_distance` is used as the radius of
the first row of turbines, spaced evenly around the ring. Subsequent turbines
on a string are spaced using the {py:attr}`turbine_distance` attribute. An
example of this layout can be seen above in [Fig. 2](#ring-partial).

### Grid

For the grid layout, an evenly spaced grid of (x, y) coordinates for each
turbine is calculated based off the {py:attr}`turbine_distance`,
{py:attr}`row_distance`, and {py:attr}`substation_distance` with the offshore
substation being located at (0, ({py:attr}`num_strings` - 1) * {py:attr}`row_distance` / {py:attr}`num_strings`)

### Custom

Coming soon!

## Section Lengths

The distance between a turbine and it's subsequent connection determines the
cable length that is required for the array system. These lengths are summed up
and stored in the {py:attr}`design_result`, which can be utilized by the
[array cable installation module](#array-install-methods).

## Process Diagrams

![Array cable design process diagram](../../images/process_diagrams/ArraySystemDesign.png)
