Skip to content

Changes

Page history
test authored by Selim Grote's avatar Selim Grote
Show whitespace changes
Inline Side-by-side
documentation/tutorial.md
View page @ 347c55ea
......@@ -102,73 +102,236 @@ with positive tilt, the PV modules face South.
The structure configuration defines the physical mounting system for the PV modules.
This is controlled by parameters in the `INPUTS/HARDWARE/STRUCTURES/` YAML files.
#### Structure Types
The `StructureType` parameter determines the overall logic and available components:
- **Agrivoltaic Fence**: Vertical posts (poles) with horizontal bars.
- **PV Table**: Fixed tilted tables with poles, rafters, diagonals, and purlins.
- **HSATS** (Horizontal Single Axis Tracker): Tracking systems with rotating rafters.
#### Positioning and Spacing
![Structure types](uploads/structure/three_struc_example.png)
These parameters control where panels and structure groups are placed in space.
Figure 4 - Three examples of structures: HSATS, PV Table and Agrivoltaic Fence.
| Parameter | Unit | Description |
|---|---|---|
| `Height` | m | Base elevation of the panel array above the ground |
| `TiltY` | ° | Tilt angle of the panels around the Y axis |
| `PanelOffset` | m | Offset applied to panel positioning |
| `PoleSpacingX` | m | Total distance between the two poles along X |
| `StructureSpacingY` | m | Spacing between structure groups along Y |
| `PoleGroundPositioning` | m | Vertical offset relative to ground level (0 = flush, negative = buried) |
---
#### Structure Components
A structure is built from several elementary objects. You can customize the dimensions and shape of each:
A PV structure is composed of several elementary parts. Each part has a **shape**, **dimensions**, and a **count**.
1. **Pole**: Vertical support posts.
2. **Rafter**: Beams oriented along the X-axis (often tilted).
3. **Purlin**: Horizontal bars oriented along the Y-axis (supporting the panels).
4. **Diagonal**: Bracing struts (specific to PV Table).
#### Shape options
![HSATS](uploads/structure/HSATS.png)
All structural members support three cross-section profiles:
Figure 5 - HSATS structure with highlighting objects representing the different components. This object represent a group you can duplicate along the X axis and Y axis to form a full AV system.
| Shape | Parameters used |
|---|---|
| `Square` | `Side` |
| `Rectangle` | `Width`, `Height` |
| `Cylinder` | `Radius` |
#### Customizing Geometry
For each component (Pole, Purlin, Rafter, Diagonal), you can define its shape and size using these parameters:
#### Poles
- **Shape**: Defined by `Shape` (e.g., `PoleShape`). Choices are `Square`, `Rectangle`, or `Cylinder`.
- **Dimensions**:
- For **Square/Rectangle**: Use `Width` (X-dimension), `Height` (Y-dimension), or `Side` (for Square).
- For **Cylinder**: Use `Radius`.
- **Length**: Defined by `Length` (e.g., `PoleLength`).
Vertical posts that carry the entire structure.
![objectForms](uploads/structure/objectForms.png)
| Parameter | Unit | Description |
|---|---|---|
| `PoleShape` | — | Cross-section type: `Square`, `Rectangle`, or `Cylinder` |
| `PoleSide` | m | Side length (square profile) |
| `PoleWidth` / `PoleHeight` | m | Width and height (rectangular profile) |
| `PoleRadius` | m | Radius (cylindrical profile) |
| `PoleLength` | m | Total pole length along Z |
#### Positioning and Spacing
Key parameters control how the structure is placed:
#### Purlins
Horizontal beams running along the **Y axis**, connecting poles and supporting panels from below.
| Parameter | Unit | Description |
|---|---|---|
| `PurlinShape` | — | Cross-section type |
| `PurlinSide` / `PurlinWidth` / `PurlinHeight` / `PurlinRadius` | m | Profile dimensions |
| `NumberOfPurlins` | — | Number of purlins per group (1–10) |
#### Rafters
Beams oriented along the **X axis**, used to carry purlins or panels across the span.
| Parameter | Unit | Description |
|---|---|---|
| `RafterShape` | — | Cross-section type |
| `RafterSide` / `RafterWidth` / `RafterHeight` / `RafterRadius` | m | Profile dimensions |
| `RafterLength` | m | Length of each rafter |
| `NumberOfRafters` | — | Number of rafters per group (1–10) |
#### Diagonals
Diagonal bracing bars connecting two poles to stiffen the structure against lateral loads.
| Parameter | Unit | Description |
|---|---|---|
| `DiagonalShape` | — | Cross-section type |
| `DiagonalSide` / `DiagonalWidth` / `DiagonalHeight` / `DiagonalRadius` | m | Profile dimensions |
| `DiagonalEpsilon` | — | Small numerical offset to avoid degenerate geometry |
---
#### Structure types
Three structure types are available. The active type is set with `StructureType`:
```yaml
StructureType:
Value: PV Table # or: HSATS, Agrivoltaic Fence
```
---
- **Height**: Elevation of the structure base from the ground.
- **PoleSpacingX**: Distance between two poles along the row (X-axis).
- **StructureSpacingY**: Distance between parallel rows of structures (Y-axis).
- **PoleGroundPositioning**: Vertical offset for the poles foundation (0 is flush with ground, negative values bury the pole).
- **TiltY**: Tilt angle of the PV modules (and rafters/purlins depending on the type).
- **PanelOffset**: Distance between the structure's mounting point and the panel center (useful to model mounting clamps or gaps).
#### example
![Structure types](uploads/structure/three_struc_example.png)
Figure 4 - Three examples of structures: HSATS, PV Table and Agrivoltaic Fence.
#### PV Table
**Description:** A fixed, tilted table structure. Two poles of different heights support a tilted rafter, with diagonal bracing and horizontal purlins.
**How it works:**
- Two poles per bay — one taller (high side) and one shorter (low side) — create the tilt.
- A rafter sits on top of both poles at the tilted angle.
- Purlins run horizontally along Y to support the panels.
- A diagonal brace connects the two poles for rigidity.
**Key parameters:**
| Parameter | Default | Description |
|---|---|---|
| `TiltY` | — | Tilt angle of the table (°). Combined with `PoleSpacingX` it determines the pole height difference. |
| `PoleSpacingX` | 0.2 m | Total distance between the two poles along X |
| `RafterLength` | 3.8 m | Minimum rafter length (auto-adjusted if too short for the tilt) |
| `NumberOfPurlins` | 5 | Purlins distributed evenly across the rafter span |
> ⚠️ If `TiltY` is too large relative to `Height` and `PoleSpacingX`, the structure will extend below ground. PASE will raise a `ValueError` in that case.
**Example YAML snippet (`PV_table.yaml`):**
```yaml
StructureType:
Value: PV Table
Material:
Value: Wood
PoleShape:
Value: square
PoleLength:
Value: 3.8
PoleSpacingX:
Value: 0.2
NumberOfPurlins:
Value: 5
NumberOfRafters:
Value: 3
```
![PV Table](uploads/structure/PVTable.png)
Figure 6 - PV Table structure groups. PV tables have diagonals that start from the smallest pole of the group and end at the largest pole of the group. The length and angle of the diagonals are calculated automatically.
Figure 5 - PV Table structure groups. PV tables have diagonals that start from the smallest pole of the group and end at the largest pole of the group. The length and angle of the diagonals are calculated automatically.
![TiltY](uploads/structure/TiltY.png)
Figure 7 - TiltY parameter : the tilt angle of the PV modules (and rafters/purlins depending on the type).
Figure 6 - TiltY parameter : the tilt angle of the PV modules (and rafters/purlins depending on the type).
You can set the `PanelOffset`, this is the distance between the structure's group and the panel center, this parameter is always applied along the normal of the panel.
---
**Warning**: If the tilt angle is too high for the given base height, the structure may extend below ground level. Ensure that `Height` or `PoleSpacingX` is increased, or `TiltY` is decreased, to avoid a `ValueError`: "Invalid PVTable configuration: The tilt angle is too high for the given base height. This results in the structure extending below ground level. Please increase 'Height' or 'PoleSpacingX' or decrease 'TiltY'."
#### HSATS
**Description:** Horizontal Single-Axis Tracking Structure. A central pole supports a rotating frame that can track the sun along one axis.
**Typical use case:** Tracking installations where panels rotate around a horizontal axis.
**How it works:**
- A single central pole is placed at the base height.
- Purlins run along X, rafters run along Y — together they form a flat frame that can be tilted.
- No diagonal brace is used.
**Key parameters:**
| Parameter | Default | Description |
|---|---|---|
| `PoleRadius` | 0.1 m | Cylindrical pole (default shape: `Cylinder`) |
| `NumberOfPurlins` | 5 | Purlins distributed across the rafter span |
| `NumberOfRafters` | 3 | Rafters distributed across the purlin span |
| `RafterLength` | 1.8 m | Length of each rafter along X |
**Example YAML snippet (`HSATS.yaml`):**
```yaml
StructureType:
Value: HSATS
Material:
Value: Metal
PoleShape:
Value: Cylinder
PoleRadius:
Value: 0.1
PoleLength:
Value: 3.8
NumberOfPurlins:
Value: 5
NumberOfRafters:
Value: 3
```
![HSATS](uploads/structure/HSATS.png)
Figure 7 - HSATS structure with highlighting objects representing the different components. This object represent a group you can duplicate along the X axis and Y axis to form a full AV system.
![Agrivoltaic Fence](uploads/structure/AgriFence.png)
---
Figure 8 - Agrivoltaic Fence Structure : the poles remain vertical and tilt is applied to each module separately.
#### Agrivoltaic Fence
**Description:** A fence-like structure where panels are mounted vertically or near-vertically between posts.
**Typical use case:** Agrivoltaic fields where crops or livestock coexist with the PV installation.
**How it works:**
- A single vertical pole per bay is placed along Y.
- Two horizontal bars are attached to each pole — one at `StructureHeight`, one offset downward by `RepetitionDistanceOfPanelsX`.
- A terminal end-post closes the last bay.
**Key parameters:**
| Parameter | Default | Description |
|---|---|---|
| `StructureHeight` | 3.3 m | Height of the top horizontal bar |
| `PoleLength` | 3.8 m | Total pole length (should exceed `StructureHeight`) |
| `PoleGroundPositioning` | -0.5 m | Buries the pole base 0.5 m underground for stability |
| `StructureSpacingY` | 5.0 m | Spacing between fence bays |
**Example YAML snippet (`agrivoltaic_fence.yaml`):**
```yaml
StructureType:
Value: Agrivoltaic Fence
Material:
Value: Wood
PoleShape:
Value: Cylinder
PoleRadius:
Value: 0.1
PoleLength:
Value: 3.8
PoleGroundPositioning:
Value: -0.5
StructureHeight:
Value: 3.3
StructureSpacingY:
Value: 5.0
```
![Agrivoltaic Fence](uploads/structure/AgriFence.png)
Figure 8 - Agrivoltaic Fence Structure : the poles remain vertical and tilt is applied to each module separately.
---
## Weather data
......
......