[feature] Example script and input files

Create example.py (inspired from main.py) and clean the script to make it easier to read and understand for new users.

INPUTS/AV_CENTRAL/Example1_AV.yaml

+NumberOfPanelsX:
+   Value: 1
+   Type: integer
+   Limit: [1, 1000]
+   Unit: dimensionless [-]
+   Definition: Number of panels on the x axis in one block of panels (x axis being the second potential axis of rotation of the block of panels)
+NumberOfPanelsY:
+   Value: 4
+   Type: integer
+   Limit: [1, 1000]
+   Unit: dimensionless [-]
+   Definition: Number of panels on the y axis in one block of panels
+RepetitionDistanceOfPanelsX:
+   Value: 2.450
+   Type: float
+   Limit: [0, 100]
+   Unit: meters [m]
+   Definition: Length between the repetition of 2 panels on the x axis of one block of panels
+RepetitionDistanceOfPanelsY:
+   Value: 1.953
+   Type: float
+   Limit: [0, 100]
+   Unit: meters [m]
+   Definition: Length between the repetition of 2 panels on the y axis of one block of panels
+RotationAxisNumber:
+   Value: 0
+   Type: integer
+   Limit: [0, 1]
+   Unit: dimensionless [-]
+   Definition: Number of rotation axis that drive the block of panels
+TiltY:
+   Value: 20
+   Type: float
+   Limit: [-90, 90]
+   Unit: degree [°]
+   Definition: Tilt of the photovoltaic block around the y axis which would be the potential main axis of rotation
+Height:
+   Value: 1.22
+   Type: float
+   Limit: [0.1, 20]
+   Unit: meters [m]
+   Definition: Height from the ground to the main axis of the block of panels
+NumberOfPVBlocksX:
+   Value: 1
+   Type: integer
+   Limit: [0, 1000]
+   Unit: dimensionless [-]
+   Definition: Number of blocks on the x axis of the photovoltaic central (x axis being the potential second rotation axis of the block of panels)
+NumberOfPVBlocksY:
+   Value: 1
+   Type: integer
+   Limit: [0, 1000]
+   Unit: dimensionless [-]
+   Definition: Number of blocks on the y axis of the photovoltaic central (y axis being the potential main rotation axis of the block of panels)
+RepetitionDistanceOfPVBlocksX:
+   Value: 4.5
+   Type: float
+   Limit: [NumberOfPanelsX*RepetitionDistanceOfPanelsX,1000]
+   Unit: meters [m]
+   Definition: Length between the repetition of 2 blocks of panels on the x axis of the photovoltaic central
+RepetitionDistanceOfPVBlocksY:
+   Value: 49
+   Type: float
+   Limit: [NumberOfPanelsY*RepetitionDistanceOfPanelsY, 1000]
+   Unit: meters [m]
+   Definition: Length between the repetition of 2 blocks of panels on the y axis of the photovoltaic central
+TwoFacetsRelativePosition:
+   Value: 0.55
+   Type: float
+   Limit: [-5, 5]
+   Units: meters
+   Definition: If you have to construct a PV geometry with modules having 2 facets (often 1 oriented east and the other west), it is the horizontal relative position of the panels potential rotation axis and the centre of the module with 2 facets. If there is not 2 facets, set this parameter to 0.
+CentralAzimut:
+   Value: 90
+   Type: float
+   Limit: [0,360]
+   Unit: degrees [°]
+   Definition: Rotation angle of the central around the z axis. 0 is N ; 90 is E ; 180 is S ; 270 is W

INPUTS/HARDWARE/PV_MODULES/Example1_PV_Module.yaml

+PanelDimensionX:
+   Value: 2.384
+   Type: float
+   Limit: [0.1,5]
+   Unit: meters [m]
+   Definition: Panel dimension on the x axis which would be the second potential axis of rotation
+PanelDimensionY:
+   Value: 1.303
+   Type: float
+   Limit: [0.1,5]
+   Unit: meters [m]
+   Definition: Panel dimension on the y axis which would be the main potential axis of rotation
+Panel_Peak_Power:
+   Value: 400
+   Type: float
+   Limit: [0.1,2000]
+   Unit: watt-peak [Wp]
+   Definition: Maximal electrical power production of the panel in Standard Test Conditions
+Bifaciality:
+   Value: False
+   Type: boolean
+   Possibilities: [False, True]
+   Definition: Boolean telling if the panels are bifacial (True) or not (False)
+Bifaciality_factor:
+   Value: 0.7
+   Type: float
+   Limit: [0.1, 1]
+   Unit: dimensionless [-]
+   Definition: Bifaciality factor, ratio between th efficiency of the rear face and the efficiency of the front face of the panel
+PanelThickness:
+   Value: True
+   Type: boolean
+   Possibilities: [False, True]
+   Definition: Boolean telling if the panels have a thickness in the simulation
\ No newline at end of file

INPUTS/SCENARIOS/Example1_loc.yaml

+LocationName: 
+   Value: Siguesol
+   Type: string
+   Definition: Name of the location
+TimeZone:
+   Value: Etc/GMT+0
+   Type: string
+   Definition: Precision on the time zone because otherwise, pvlib import sun positions in UTC0   
+Latitude:
+   Value: 50.376
+   Type: float
+   Limit: [-90, 90]
+   Unit: degrés décimaux [-]
+   Definition: Latitude of the location
+Longitude:
+   Value: 5.677
+   Type: float
+   Limit: [-180, 180]
+   Unit: degrés décimaux [-]
+   Definition: Longitude of the location
+Altitude:
+   Value: 433
+   Type: float
+   Limit: [0, 3000]
+   Unit: meters [m]
+   Definition: Altitude of the location
+WeatherDataOption:
+   Value: 1
+   Type: integer
+   Limit: [1, 2]
+   Unit: dimensionless [-]
+   Definition: Option 1 means get the meteo data from PvGis and option 2 means get the meteo data from a file in DATABASE
+WeatherFileName:
+   Value: Chanco_Chile_WD
+   Type: string
+   Definition: Name of the hourly or more precise (10 min or 15 min) weather data csv file (pay attention to the format it should have) if WeatherDataOption is 2
+DailyWeatherFileName:
+   Value: PRECIP_VP_Loc1
+   Type: string
+   Definition: Name of the daily weather data csv file with precipitation and vapour pressure (pay attention to the format it should have) if WeatherDataOption is 1 (PVGis used)
+SimulationStartingYear:
+   Value: 2005
+   Type: integer
+   Limit: [1900, SimulationEndingYear]
+   Unit: dimensionless [-]
+   Definition: Starting year of the simulation, PvGis has data from 2005 to 2016 comprise
+SimulationEndingYear:
+   Value: 2007
+   Type: integer
+   Limit: [SimulationStartingYear, 2022]
+   Unit: dimensionless [-]
+   Definition: Ending year of the simulation (included in the simulation)
+PrecisionLevelOnSunPosition:
+   Value: 1
+   Type: integer
+   Limit: [1, 3]
+   Unit: dimensionless [-]
+   Definition: Level 1 means the same average solar position during each days of a month, level 2 means the same average solar position during each days of a week and level 3 means solar position is computed for each day
+Xmin_InterestZone:
+   Value: -2
+   Type: float
+   Limit: [-2000, 2000]
+   Unit: meters [m]
+   Definition: Minimal x coordinates of the zone of interest for the light and crop modelling
+Xmax_InterestZone:
+   Value: 2
+   Type: float
+   Limit: [-2000, 2000]
+   Unit: meters [m]
+   Definition: Maximal x coordinates of the zone of interest for the light and crop modelling
+dX_InterestZone:
+   Value: 1
+   Type: float
+   Limit: [-2000, 2000]
+   Unit: meters [m]
+   Definition: Increment in the x coordinates of the zone of interest for the light and crop modelling
+Ymin_InterestZone:
+   Value: -2
+   Type: float
+   Limit: [-2000, 2000]
+   Unit: meters [m]
+   Definition: Minimal y coordinates of the zone of interest for the light and crop modelling
+Ymax_InterestZone:
+   Value: 2
+   Type: float
+   Limit: [-2000, 2000]
+   Unit: meters [m]
+   Definition: Maximal y coordinates of the zone of interest for the light and crop modelling
+dY_InterestZone:
+   Value: 1
+   Type: float
+   Limit: [-2000, 2000]
+   Unit: meters [m]
+   Definition: Increment in the y coordinates of the zone of interest for the light and crop modelling

example.py

+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+#Copyright (c) 2020-2024 - University of Liège - Digital Energy and Agriculture Lab (DEAL)
+#Author : Roxane Bruhwyler (roxane.bruhwyler@uliege.be or roxane.bruhwyler@hotmail.com)
+#This file is part of the PASE software, and is distributed under the MIT license.
+
+import numpy as np
+import os
+import pickle
+from MODULES.user_support_tools import PASE_Logger
+from MODULES.DATA_MANAGEMENT.yaml_inputs_provider import YAML_Inputs_provider, Inputs_aggregator
+from MODULES.DATA_MANAGEMENT.weather_data_provider import Weather_data
+from MODULES.PHOTOVOLTAICS.configuration import PV_Configuration_3D
+from MODULES.ENVIRONMENT.light import Sun_positions_sampled, Sun_positions, Light
+from MODULES.ENVIRONMENT.light import show_light_map2, Ray_casting_scene
+from MODULES.ENVIRONMENT.mesh import Mesh
+from MODULES.PHOTOVOLTAICS.production import PV_Production
+from MODULES.CROPS.run_crop_simulations import run_crop_simu
+
+PASE_Logger()
+
+###############
+# Load inputs #
+###############
+Loc_1 = YAML_Inputs_provider(file='Example1_loc.yaml', subpath='SCENARIOS').inputs
+# Import PV system and PV modules parameters
+AV_1 = YAML_Inputs_provider(file='Example1_AV.yaml', subpath='AV_CENTRAL').inputs
+PV_module_1 = YAML_Inputs_provider(file='Example1_PV_Module.yaml', subpath=os.path.join('HARDWARE','PV_MODULES')).inputs
+PV_params_dict = Inputs_aggregator([AV_1, PV_module_1]).aggregated_inputs
+
+##################
+# Pre-processing #
+##################
+# Import of weather data and computation of daily weather data
+WD = Weather_data(Loc_1['Latitude'],
+                  Loc_1['Longitude'],
+                  Loc_1['SimulationStartingYear'],
+                  Loc_1['SimulationEndingYear'],
+                  Loc_1['WeatherDataOption'],
+                  Loc_1['WeatherFileName'],
+                  Loc_1['DailyWeatherFileName'])
+
+# Import sun positions
+
+# sampled for the direct light model
+Sun_positions_samp = Sun_positions_sampled(Loc_1['Latitude'],
+                                      Loc_1['Longitude'],
+                                      Loc_1['PrecisionLevelOnSunPosition'],
+                                      Loc_1['LocationName'],
+                                      len(WD.nyears_data[str(Loc_1['SimulationStartingYear'])]),
+                                      Loc_1['TimeZone'])
+# complete for the HDKR model
+Sun_positions_complete = Sun_positions(Loc_1['Latitude'],
+                                       Loc_1['Longitude'],
+                                       len(WD.nyears_data[str(Loc_1['SimulationStartingYear'])]),
+                                       Loc_1['TimeZone'])
+
+# Instantiation of the 3D PV central
+PV_1_3Dconfig = PV_Configuration_3D(PV_params_dict, Sun_positions_samp.solar_vector,
+                                    visualization=False)                        # !!!! Problem with rotation angle that are negative
+
+# Initiation of the object containing points of interest to compute light
+M = Mesh()
+
+# Add of the points of interests on the ground for crop models
+M.add_plane_ground_regular_meshes(Loc_1['Xmin_InterestZone'],
+                                  Loc_1['Xmax_InterestZone'],
+                                  Loc_1['Ymin_InterestZone'],
+                                  Loc_1['Ymax_InterestZone'],
+                                  Loc_1['dX_InterestZone'],
+                                  Loc_1['dY_InterestZone'],
+                                  flag="crop")
+
+# Computation of sun and light data
+Light_instance = Light(WD.nyears_data, Sun_positions_complete)
+
+# Iniation and run of light ray casting model (direct and diffuse) with points of interest and scene
+L = Ray_casting_scene(mesh=M, geometry=PV_1_3Dconfig.PV_central_PD)
+L.get_light_maps(180,Sun_positions_samp.solar_vector)
+
+# Integration of irradiation along days
+L.get_daily_irradiation_map(Sun_positions_samp.SP,
+                            Light_instance.data)
+
+
+# Examples of visualisation for the direct light map, diffuse light map (sky view factor)
+# and daily irradiation map. Those lines are for PV system with no rotation axis. 
+j = 5 #  julian day of the year
+
+show_light_map2(L.sourcepoints[:,:-1], 
+                L.dir_map[:,3], 
+                PV_1_3Dconfig.PV_central_PD,
+                "Direct map [-]")
+
+show_light_map2(L.sourcepoints[:,:-1], 
+                np.array(L.diff_map,dtype=np.float32), 
+                PV_1_3Dconfig.PV_central_PD,
+                "Sky visibility map [-]")
+
+show_light_map2(L.sourcepoints[:,:-1], 
+                L.daily_irr_spat['2005'][:,j],
+                PV_1_3Dconfig.PV_central_PD,
+                "Total irradiation reaching the ground on the julian day "+str(j)+" [MJ/m²]")
+
+
+##############
+# Processing #
+##############
+
+# PV production model
+PV_central = PV_Production(PV_params_dict)
+PV_central.get_several_years_of_electricity_production(Sun_positions_complete, Light_instance.data, WD.nyears_data)
+
+for _ in ['2005', '2006', '2007']:
+    PV_prod = PV_central.production[_]
+    print(f'PV production for year 2005: {PV_prod["P_central"].sum():.2f} MW·h')
+
+# Crop model
+# Temporary lines, those 2 parameters (crop_model and option_2D) will be in
+# SCENARIOS input files (general parameters)
+crop_model = 1 # 1 for SIMPLE, 2 for STICS JAVA and 3 for GRASSIM
+option_2D = 1 # 0: no 2D-spatialization ; 1 : 2D spatialization
+Soil_plot, Crop_plot = run_crop_simu(crop_model, option_2D, WD.nyears_daily_data, 
+                                     L.daily_irr_spat,
+                                     Loc_1)
+
+# Display spatialized dry yield
+show_light_map2(L.sourcepoints[:,:-1],
+                Crop_plot.nyears_data['2005']['Dry_yield']['2005-10-10 00:00:00']/100,
+                PV_1_3Dconfig.PV_central_PD,
+                "Dry yield SIMPLE 2005 [t/ha]")